@bernierllc/construction-data-service

Construction data domain service providing merge strategies, normalization, and validation for collected permit/project data.

Overview

This service centralizes construction data domain logic for projects like the construction-data Next.js app:

• Normalize connector output into CollectedRecord objects using @bernierllc/data-transformer
• Apply merge strategies (UPSERT, INSERT_IGNORE, APPEND)
• Validate records with @bernierllc/schema-validator
• Optionally persist records via an injected callback (typically using @bernierllc/supabase-client)

Installation

npm install @bernierllc/construction-data-service

Usage

import { ConstructionDataService } from '@bernierllc/construction-data-service';
import type { CollectedRecord } from '@bernierllc/construction-data-service';
import type { SchemaMapping } from '@bernierllc/data-transformer';

const service = new ConstructionDataService({
  persistRecord: async (record: CollectedRecord) => {
    // Use @bernierllc/supabase-client or another data-access package here.
  }
});

const rawData = {
  PROJECT_ID: '608923',
  TOWN: 'BOSTON',
  DESCRIPTION: 'RECONSTRUCTION ON COMM AVE'
};

const mapping: SchemaMapping[] = [
  { sourceField: 'PROJECT_ID', targetField: 'externalId', dataType: 'text' },
  { sourceField: 'TOWN', targetField: 'address', dataType: 'text' },
  { sourceField: 'DESCRIPTION', targetField: 'description', dataType: 'text' }
];

const record = service.normalizeConstructionRecord(rawData, mapping, 'source-id-123');
const validation = service.validateConstructionData(record);

if (!validation.isValid) {
  throw new Error(validation.errors.join(', '));
}

const result = await service.processBatch([record], 'UPSERT', async incoming => {
  // Optional: look up existing record for UPSERT
  return null;
});

API Surface

• normalizeConstructionRecord(rawData, mapping, sourceId): CollectedRecord
• validateConstructionData(record): ValidationResult
• mergeRecords(existing, incoming, strategy): { record, action }
• processBatch(records, strategy, existingLookup?): Promise<MergeResult>

Integration with construction-data

This package is designed to back the pages/api/collected/index.ts route in the construction-data app:

• After connectors fetch raw data, use @bernierllc/data-transformer + this service to normalize records
• Use processBatch to apply merge strategies before persisting data

See the construction-data project plans:

• plans/package-requests.md
• plans/bernierllc-packages-migration.md
• plans/packages-integration-plan.md

for the original requirements this package implements.