@workbench-kit/field-remap 0.0.1-prototype.0 → 0.0.2-prototype.0.2.11

package/src/domain/mapping/dateFormat.ts

@@ -1,102 +1,102 @@
-export type DateParts = { readonly year: string; readonly month: string; readonly day: string };
-
-const FORMAT_TOKEN_RE = /YYYY|MM|DD/g;
-
-/** Parse a date string with a simple token format (YYYY/MM/DD only). */
-export function parseDateParts(value: string, inputFormat: string): DateParts | undefined {
-  const format = inputFormat.trim();
-  const raw = value.trim();
-  if (!format || !raw) {
-    return undefined;
-  }
-
-  let year = '';
-  let month = '';
-  let day = '';
-  let cursor = 0;
-
-  for (let i = 0; i < format.length;) {
-    if (format.startsWith('YYYY', i)) {
-      year = raw.slice(cursor, cursor + 4);
-      if (!/^\d{4}$/.test(year)) {
-        return undefined;
-      }
-      cursor += 4;
-      i += 4;
-      continue;
-    }
-    if (format.startsWith('MM', i)) {
-      month = raw.slice(cursor, cursor + 2);
-      if (!/^\d{2}$/.test(month)) {
-        return undefined;
-      }
-      cursor += 2;
-      i += 2;
-      continue;
-    }
-    if (format.startsWith('DD', i)) {
-      day = raw.slice(cursor, cursor + 2);
-      if (!/^\d{2}$/.test(day)) {
-        return undefined;
-      }
-      cursor += 2;
-      i += 2;
-      continue;
-    }
-    if (raw[cursor] !== format[i]) {
-      return undefined;
-    }
-    cursor += 1;
-    i += 1;
-  }
-
-  if (cursor !== raw.length || !year || !month || !day) {
-    return undefined;
-  }
-  return { year, month, day };
-}
-
-export function formatDateParts(parts: DateParts, outputFormat: string): string {
-  return outputFormat.replace(FORMAT_TOKEN_RE, (token) => {
-    if (token === 'YYYY') {
-      return parts.year;
-    }
-    if (token === 'MM') {
-      return parts.month;
-    }
-    return parts.day;
-  });
-}
-
-export function reformatDateString(
-  value: string,
-  inputFormat: string,
-  outputFormat: string,
-): string | undefined {
-  const parts = parseDateParts(value, inputFormat);
-  if (!parts) {
-    return undefined;
-  }
-  return formatDateParts(parts, outputFormat);
-}
-
-/** Split `YYYY-MM-DDTHH:mm:ss` / `YYYY-MM-DD HH:mm:ss` / date-only. */
-export function splitDateTimeString(value: string): { date: string; time: string } | undefined {
-  const raw = value.trim();
-  if (!raw) {
-    return undefined;
-  }
-  const tIndex = raw.indexOf('T');
-  const spaceIndex = raw.indexOf(' ');
-  const splitAt = tIndex >= 0 ? tIndex : spaceIndex;
-  if (splitAt < 0) {
-    if (/^\d{4}-\d{2}-\d{2}$/.test(raw) || /^\d{8}$/.test(raw)) {
-      return { date: raw, time: '' };
-    }
-    return undefined;
-  }
-  return {
-    date: raw.slice(0, splitAt),
-    time: raw.slice(splitAt + 1),
-  };
-}
+export type DateParts = { readonly year: string; readonly month: string; readonly day: string };
+
+const FORMAT_TOKEN_RE = /YYYY|MM|DD/g;
+
+/** Parse a date string with a simple token format (YYYY/MM/DD only). */
+export function parseDateParts(value: string, inputFormat: string): DateParts | undefined {
+  const format = inputFormat.trim();
+  const raw = value.trim();
+  if (!format || !raw) {
+    return undefined;
+  }
+
+  let year = '';
+  let month = '';
+  let day = '';
+  let cursor = 0;
+
+  for (let i = 0; i < format.length;) {
+    if (format.startsWith('YYYY', i)) {
+      year = raw.slice(cursor, cursor + 4);
+      if (!/^\d{4}$/.test(year)) {
+        return undefined;
+      }
+      cursor += 4;
+      i += 4;
+      continue;
+    }
+    if (format.startsWith('MM', i)) {
+      month = raw.slice(cursor, cursor + 2);
+      if (!/^\d{2}$/.test(month)) {
+        return undefined;
+      }
+      cursor += 2;
+      i += 2;
+      continue;
+    }
+    if (format.startsWith('DD', i)) {
+      day = raw.slice(cursor, cursor + 2);
+      if (!/^\d{2}$/.test(day)) {
+        return undefined;
+      }
+      cursor += 2;
+      i += 2;
+      continue;
+    }
+    if (raw[cursor] !== format[i]) {
+      return undefined;
+    }
+    cursor += 1;
+    i += 1;
+  }
+
+  if (cursor !== raw.length || !year || !month || !day) {
+    return undefined;
+  }
+  return { year, month, day };
+}
+
+export function formatDateParts(parts: DateParts, outputFormat: string): string {
+  return outputFormat.replace(FORMAT_TOKEN_RE, (token) => {
+    if (token === 'YYYY') {
+      return parts.year;
+    }
+    if (token === 'MM') {
+      return parts.month;
+    }
+    return parts.day;
+  });
+}
+
+export function reformatDateString(
+  value: string,
+  inputFormat: string,
+  outputFormat: string,
+): string | undefined {
+  const parts = parseDateParts(value, inputFormat);
+  if (!parts) {
+    return undefined;
+  }
+  return formatDateParts(parts, outputFormat);
+}
+
+/** Split `YYYY-MM-DDTHH:mm:ss` / `YYYY-MM-DD HH:mm:ss` / date-only. */
+export function splitDateTimeString(value: string): { date: string; time: string } | undefined {
+  const raw = value.trim();
+  if (!raw) {
+    return undefined;
+  }
+  const tIndex = raw.indexOf('T');
+  const spaceIndex = raw.indexOf(' ');
+  const splitAt = tIndex >= 0 ? tIndex : spaceIndex;
+  if (splitAt < 0) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(raw) || /^\d{8}$/.test(raw)) {
+      return { date: raw, time: '' };
+    }
+    return undefined;
+  }
+  return {
+    date: raw.slice(0, splitAt),
+    time: raw.slice(splitAt + 1),
+  };
+}

package/src/domain/mapping/mappingConflicts.ts

@@ -1,90 +1,90 @@
-import type { MappingEdge, SourceField, TargetSlot } from '../types.js';
-import { flattenSourceFields, flattenTargetSlots } from './treeUtils.js';
-
-export interface MappingConflict {
-  readonly kind: 'parent-child-source' | 'parent-child-target';
-  readonly parentId: string;
-  readonly childId: string;
-  readonly parentEdgeId: string;
-  readonly childEdgeId: string;
-}
-
-function isAncestorId(ancestorId: string, descendantId: string): boolean {
-  return (
-    descendantId.startsWith(`${ancestorId}.`) || descendantId.startsWith(`${ancestorId}.item.`)
-  );
-}
-
-/**
- * Detect edges that map both a parent object/array and one of its descendants.
- * Hosts should warn — writing both usually overwrites or double-defines output.
- */
-export function findParentChildMappingConflicts(
-  edges: readonly MappingEdge[],
-  sources: readonly SourceField[],
-  targets: readonly TargetSlot[],
-): MappingConflict[] {
-  const sourceIds = new Set(flattenSourceFields(sources).map((field) => field.id));
-  const targetIds = new Set(flattenTargetSlots(targets).map((slot) => slot.id));
-  const conflicts: MappingConflict[] = [];
-
-  for (let i = 0; i < edges.length; i += 1) {
-    const a = edges[i]!;
-    for (let j = i + 1; j < edges.length; j += 1) {
-      const b = edges[j]!;
-      if (
-        sourceIds.has(a.sourceFieldId) &&
-        sourceIds.has(b.sourceFieldId) &&
-        isAncestorId(a.sourceFieldId, b.sourceFieldId)
-      ) {
-        conflicts.push({
-          kind: 'parent-child-source',
-          parentId: a.sourceFieldId,
-          childId: b.sourceFieldId,
-          parentEdgeId: a.id,
-          childEdgeId: b.id,
-        });
-      } else if (
-        sourceIds.has(a.sourceFieldId) &&
-        sourceIds.has(b.sourceFieldId) &&
-        isAncestorId(b.sourceFieldId, a.sourceFieldId)
-      ) {
-        conflicts.push({
-          kind: 'parent-child-source',
-          parentId: b.sourceFieldId,
-          childId: a.sourceFieldId,
-          parentEdgeId: b.id,
-          childEdgeId: a.id,
-        });
-      }
-
-      if (
-        targetIds.has(a.targetSlotId) &&
-        targetIds.has(b.targetSlotId) &&
-        isAncestorId(a.targetSlotId, b.targetSlotId)
-      ) {
-        conflicts.push({
-          kind: 'parent-child-target',
-          parentId: a.targetSlotId,
-          childId: b.targetSlotId,
-          parentEdgeId: a.id,
-          childEdgeId: b.id,
-        });
-      } else if (
-        targetIds.has(a.targetSlotId) &&
-        targetIds.has(b.targetSlotId) &&
-        isAncestorId(b.targetSlotId, a.targetSlotId)
-      ) {
-        conflicts.push({
-          kind: 'parent-child-target',
-          parentId: b.targetSlotId,
-          childId: a.targetSlotId,
-          parentEdgeId: b.id,
-          childEdgeId: a.id,
-        });
-      }
-    }
-  }
-
-  return conflicts;
-}
+import type { MappingEdge, SourceField, TargetSlot } from '../types.js';
+import { flattenSourceFields, flattenTargetSlots } from './treeUtils.js';
+
+export interface MappingConflict {
+  readonly kind: 'parent-child-source' | 'parent-child-target';
+  readonly parentId: string;
+  readonly childId: string;
+  readonly parentEdgeId: string;
+  readonly childEdgeId: string;
+}
+
+function isAncestorId(ancestorId: string, descendantId: string): boolean {
+  return (
+    descendantId.startsWith(`${ancestorId}.`) || descendantId.startsWith(`${ancestorId}.item.`)
+  );
+}
+
+/**
+ * Detect edges that map both a parent object/array and one of its descendants.
+ * Hosts should warn — writing both usually overwrites or double-defines output.
+ */
+export function findParentChildMappingConflicts(
+  edges: readonly MappingEdge[],
+  sources: readonly SourceField[],
+  targets: readonly TargetSlot[],
+): MappingConflict[] {
+  const sourceIds = new Set(flattenSourceFields(sources).map((field) => field.id));
+  const targetIds = new Set(flattenTargetSlots(targets).map((slot) => slot.id));
+  const conflicts: MappingConflict[] = [];
+
+  for (let i = 0; i < edges.length; i += 1) {
+    const a = edges[i]!;
+    for (let j = i + 1; j < edges.length; j += 1) {
+      const b = edges[j]!;
+      if (
+        sourceIds.has(a.sourceFieldId) &&
+        sourceIds.has(b.sourceFieldId) &&
+        isAncestorId(a.sourceFieldId, b.sourceFieldId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-source',
+          parentId: a.sourceFieldId,
+          childId: b.sourceFieldId,
+          parentEdgeId: a.id,
+          childEdgeId: b.id,
+        });
+      } else if (
+        sourceIds.has(a.sourceFieldId) &&
+        sourceIds.has(b.sourceFieldId) &&
+        isAncestorId(b.sourceFieldId, a.sourceFieldId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-source',
+          parentId: b.sourceFieldId,
+          childId: a.sourceFieldId,
+          parentEdgeId: b.id,
+          childEdgeId: a.id,
+        });
+      }
+
+      if (
+        targetIds.has(a.targetSlotId) &&
+        targetIds.has(b.targetSlotId) &&
+        isAncestorId(a.targetSlotId, b.targetSlotId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-target',
+          parentId: a.targetSlotId,
+          childId: b.targetSlotId,
+          parentEdgeId: a.id,
+          childEdgeId: b.id,
+        });
+      } else if (
+        targetIds.has(a.targetSlotId) &&
+        targetIds.has(b.targetSlotId) &&
+        isAncestorId(b.targetSlotId, a.targetSlotId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-target',
+          parentId: b.targetSlotId,
+          childId: a.targetSlotId,
+          parentEdgeId: b.id,
+          childEdgeId: a.id,
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}

package/src/domain/mapping/mappingOperators.ts

@@ -0,0 +1,297 @@
+/**
+ * Minimal n→m operators (combine / split) evaluated beside MappingEdge[].
+ * Document v2 may persist these via `operators[]`; hosts may also call
+ * {@link applyMappingOperators} explicitly without persisting.
+ */
+
+import {
+  canonicalizeTransformId,
+  IDENTITY_TRANSFORM_ID,
+  MAX_TRANSFORM_CHAIN,
+} from '../constants.js';
+import { throwIfAborted } from '../abort.js';
+import type {
+  CombineMappingOperator,
+  MappingOperator,
+  SourceField,
+  SplitMappingOperator,
+  TargetSlot,
+  TransformContext,
+  ValueTransformRegistry,
+} from '../types.js';
+import { applyTransformChain } from '../../registry/createValueTransformRegistry.js';
+import { findSourceField, findTargetSlot } from './resolveMappedValue.js';
+import { isPlainObject, readObjectPath, writeObjectPath } from './pathUtils.js';
+
+/** Max inputs on a combine operator. */
+export const MAX_MAPPING_FAN_IN = 8;
+/** Max outputs on a split operator. */
+export const MAX_MAPPING_FAN_OUT = 8;
+
+export type { CombineMappingOperator, MappingOperator, SplitMappingOperator };
+
+export type ApplyMappingOperatorsInput = {
+  readonly operators: readonly MappingOperator[];
+  readonly sources: readonly SourceField[];
+  readonly targets: readonly TargetSlot[];
+  /** Named input bags keyed by source shape id (same contract as convertToShape). */
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly transforms: ValueTransformRegistry;
+  /** Existing nested output to merge into (usually `{}` or convertToShape output). */
+  readonly output?: Readonly<Record<string, unknown>>;
+  readonly context?: TransformContext;
+  readonly signal?: AbortSignal;
+};
+
+export type ApplyMappingOperatorsResult = {
+  readonly output: Record<string, unknown>;
+};
+
+export class MappingOperatorError extends Error {
+  readonly code = 'mapping_operator_error' as const;
+  readonly operatorId: string;
+
+  constructor(operatorId: string, message: string) {
+    super(message);
+    this.name = 'MappingOperatorError';
+    this.operatorId = operatorId;
+  }
+}
+
+function leafKey(field: {
+  readonly path?: string;
+  readonly label: string;
+  readonly id: string;
+}): string {
+  const path = field.path?.trim();
+  if (path) {
+    const parts = path.split('.').filter(Boolean);
+    return parts[parts.length - 1] ?? path;
+  }
+  const idParts = field.id.split('.').filter(Boolean);
+  return idParts[idParts.length - 1] ?? field.label;
+}
+
+function outputPathForTarget(slot: TargetSlot): string {
+  const path = slot.path?.trim();
+  if (path) {
+    return path;
+  }
+  const id = slot.id.trim();
+  if (id.includes('.')) {
+    const parts = id.split('.').filter(Boolean);
+    if (parts.length >= 2) {
+      return parts.slice(1).join('.');
+    }
+  }
+  return slot.label.trim() || id;
+}
+
+function readFieldValue(field: SourceField, inputs: Readonly<Record<string, unknown>>): unknown {
+  const shapeId = field.shapeId?.trim();
+  const bag =
+    shapeId && Object.prototype.hasOwnProperty.call(inputs, shapeId)
+      ? inputs[shapeId]
+      : Object.keys(inputs).length === 1
+        ? inputs[Object.keys(inputs)[0]!]
+        : inputs;
+
+  const path = field.path?.trim();
+  if (path) {
+    if (shapeId && Object.prototype.hasOwnProperty.call(inputs, shapeId)) {
+      return readObjectPath(bag, path);
+    }
+    const fromBag = readObjectPath(bag, path);
+    if (fromBag !== undefined) {
+      return fromBag;
+    }
+    return readObjectPath(inputs, path);
+  }
+
+  return field.sampleValue;
+}
+
+function sanitizeOperatorTransformIds(ids: readonly string[] | undefined): string[] | undefined {
+  const cleaned = ids
+    ?.map((id) => canonicalizeTransformId(id))
+    .filter((id) => id.length > 0 && id !== IDENTITY_TRANSFORM_ID);
+  if (!cleaned || cleaned.length === 0) {
+    return undefined;
+  }
+  return cleaned.slice(0, MAX_TRANSFORM_CHAIN);
+}
+
+function validateCombine(operator: CombineMappingOperator): void {
+  if (operator.inputFieldIds.length < 2) {
+    throw new MappingOperatorError(operator.id, 'combine requires at least 2 inputFieldIds.');
+  }
+  if (operator.inputFieldIds.length > MAX_MAPPING_FAN_IN) {
+    throw new MappingOperatorError(
+      operator.id,
+      `combine fan-in exceeds MAX_MAPPING_FAN_IN (${MAX_MAPPING_FAN_IN}).`,
+    );
+  }
+}
+
+function validateSplit(operator: SplitMappingOperator): void {
+  if (operator.outputSlotIds.length < 2) {
+    throw new MappingOperatorError(operator.id, 'split requires at least 2 outputSlotIds.');
+  }
+  if (operator.outputSlotIds.length > MAX_MAPPING_FAN_OUT) {
+    throw new MappingOperatorError(
+      operator.id,
+      `split fan-out exceeds MAX_MAPPING_FAN_OUT (${MAX_MAPPING_FAN_OUT}).`,
+    );
+  }
+}
+
+/**
+ * Normalize persisted / host-supplied operators for document v2.
+ * Drops malformed entries; clamps fan-in/out and transform chains.
+ */
+export function normalizeMappingOperators(
+  operators: readonly MappingOperator[] | undefined,
+): MappingOperator[] | undefined {
+  if (!operators || operators.length === 0) {
+    return undefined;
+  }
+
+  const next: MappingOperator[] = [];
+  for (const operator of operators) {
+    if (!operator || typeof operator !== 'object') {
+      continue;
+    }
+    const id = typeof operator.id === 'string' ? operator.id.trim() : '';
+    if (!id) {
+      continue;
+    }
+
+    if (operator.kind === 'combine') {
+      const inputFieldIds = (operator.inputFieldIds ?? [])
+        .map((fieldId) => (typeof fieldId === 'string' ? fieldId.trim() : ''))
+        .filter(Boolean)
+        .slice(0, MAX_MAPPING_FAN_IN);
+      const outputSlotId =
+        typeof operator.outputSlotId === 'string' ? operator.outputSlotId.trim() : '';
+      if (inputFieldIds.length < 2 || !outputSlotId) {
+        continue;
+      }
+      const combineTransforms = sanitizeOperatorTransformIds(operator.transformIds);
+      next.push({
+        kind: 'combine',
+        id,
+        inputFieldIds,
+        outputSlotId,
+        ...(combineTransforms ? { transformIds: combineTransforms } : {}),
+      });
+      continue;
+    }
+
+    if (operator.kind === 'split') {
+      const inputFieldId =
+        typeof operator.inputFieldId === 'string' ? operator.inputFieldId.trim() : '';
+      const outputSlotIds = (operator.outputSlotIds ?? [])
+        .map((slotId) => (typeof slotId === 'string' ? slotId.trim() : ''))
+        .filter(Boolean)
+        .slice(0, MAX_MAPPING_FAN_OUT);
+      if (!inputFieldId || outputSlotIds.length < 2) {
+        continue;
+      }
+      const splitTransforms = sanitizeOperatorTransformIds(operator.transformIds);
+      next.push({
+        kind: 'split',
+        id,
+        inputFieldId,
+        outputSlotIds,
+        ...(splitTransforms ? { transformIds: splitTransforms } : {}),
+      });
+    }
+  }
+
+  return next.length > 0 ? next : undefined;
+}
+
+/**
+ * Evaluate combine/split operators and merge writes into a target-shaped object.
+ * Deterministic: operators run in array order; later writes overwrite earlier paths.
+ */
+export async function applyMappingOperators(
+  input: ApplyMappingOperatorsInput,
+): Promise<ApplyMappingOperatorsResult> {
+  const signal = input.signal ?? input.context?.signal;
+  const context: TransformContext = {
+    ...input.context,
+    ...(signal ? { signal } : {}),
+  };
+  throwIfAborted(signal);
+
+  let output: Record<string, unknown> = input.output ? { ...input.output } : {};
+
+  for (const operator of input.operators) {
+    throwIfAborted(signal);
+
+    if (operator.kind === 'combine') {
+      validateCombine(operator);
+      const bag: Record<string, unknown> = {};
+      for (const fieldId of operator.inputFieldIds) {
+        const field = findSourceField(input.sources, fieldId);
+        if (!field) {
+          throw new MappingOperatorError(operator.id, `Unknown source field "${fieldId}".`);
+        }
+        bag[leafKey(field)] = readFieldValue(field, input.inputs);
+      }
+
+      const target = findTargetSlot(input.targets, operator.outputSlotId);
+      if (!target) {
+        throw new MappingOperatorError(
+          operator.id,
+          `Unknown target slot "${operator.outputSlotId}".`,
+        );
+      }
+
+      const value = await applyTransformChain(
+        input.transforms,
+        operator.transformIds ?? [],
+        bag,
+        context,
+      );
+      output = writeObjectPath(output, outputPathForTarget(target), value);
+      continue;
+    }
+
+    validateSplit(operator);
+    const source = findSourceField(input.sources, operator.inputFieldId);
+    if (!source) {
+      throw new MappingOperatorError(
+        operator.id,
+        `Unknown source field "${operator.inputFieldId}".`,
+      );
+    }
+
+    let current = readFieldValue(source, input.inputs);
+    current = await applyTransformChain(
+      input.transforms,
+      operator.transformIds ?? [],
+      current,
+      context,
+    );
+
+    if (!isPlainObject(current)) {
+      throw new MappingOperatorError(
+        operator.id,
+        'split requires a plain object source value (after transforms).',
+      );
+    }
+
+    for (const slotId of operator.outputSlotIds) {
+      const target = findTargetSlot(input.targets, slotId);
+      if (!target) {
+        throw new MappingOperatorError(operator.id, `Unknown target slot "${slotId}".`);
+      }
+      const key = leafKey(target);
+      output = writeObjectPath(output, outputPathForTarget(target), current[key]);
+    }
+  }
+
+  return { output };
+}