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

package/src/domain/shapes/convertToShape.ts

@@ -1,187 +1,187 @@
-import type { ConversionDefinition } from './conversionDefinition.js';
-import {
-  mergeSourceShapes,
-  targetSlotsFromShape,
-  type DataShape,
-  type DataShapeRegistry,
-} from './dataShape.js';
-import { convertArrayWithItemEdges } from '../mapping/convertItemEdges.js';
-import { isPlainObject, readObjectPath, writeObjectPath } from '../mapping/pathUtils.js';
-import { findSourceField, resolveMappedValue } from '../mapping/resolveMappedValue.js';
-import { findTargetSlot, flattenTargetSlots } from '../mapping/treeUtils.js';
-import type {
-  SourceField,
-  TargetSlot,
-  TransformContext,
-  ValueTransformRegistry,
-} from '../types.js';
-
-export interface ConvertToShapeInput {
-  readonly conversion: ConversionDefinition;
-  /** Shape registry, or an explicit list containing at least the referenced shapes. */
-  readonly shapes: DataShapeRegistry | readonly DataShape[];
-  /**
-   * Named input bags keyed by source shape id.
-   * Example: `{ order: liveOrder, customer: liveCustomer }`.
-   */
-  readonly inputs: Readonly<Record<string, unknown>>;
-  readonly transforms: ValueTransformRegistry;
-  readonly context?: TransformContext;
-}
-
-export interface ConvertToShapeSlotResult {
-  readonly edgeId: string;
-  readonly targetSlotId: string;
-  readonly path: string;
-  readonly value: unknown;
-}
-
-export interface ConvertToShapeResult {
-  /** Nested JSON matching target shape paths. */
-  readonly output: Record<string, unknown>;
-  /** Flat per-slot results (debug / UI panels). */
-  readonly slots: readonly ConvertToShapeSlotResult[];
-}
-
-function isDataShapeRegistry(
-  shapes: DataShapeRegistry | readonly DataShape[],
-): shapes is DataShapeRegistry {
-  return typeof (shapes as DataShapeRegistry).get === 'function';
-}
-
-function resolveShape(
-  shapes: DataShapeRegistry | readonly DataShape[],
-  id: string,
-): DataShape | undefined {
-  if (isDataShapeRegistry(shapes)) {
-    return shapes.get(id);
-  }
-  return shapes.find((shape) => shape.id === id);
-}
-
-function outputPathForTarget(slot: TargetSlot): string {
-  const path = slot.path?.trim();
-  if (path) {
-    return path;
-  }
-  // Prefer last id segment when hosts use dotted ids (`slot.display.timeText`).
-  const id = slot.id.trim();
-  if (id.includes('.')) {
-    const parts = id.split('.').filter(Boolean);
-    // Drop a leading registry prefix like `slot` when present with 3+ segments.
-    if (parts.length >= 3 && (parts[0] === 'slot' || parts[0] === 'tgt')) {
-      return parts.slice(1).join('.');
-    }
-    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]
-      : // Single-bag fallback: use the only input, or the whole inputs record.
-        Object.keys(inputs).length === 1
-        ? inputs[Object.keys(inputs)[0]!]
-        : inputs;
-
-  const path = field.path?.trim();
-  if (path) {
-    // When bags are per-shape, paths are relative to that bag.
-    // When falling back to the whole inputs record, absolute paths still work.
-    if (shapeId && Object.prototype.hasOwnProperty.call(inputs, shapeId)) {
-      return readObjectPath(bag, path);
-    }
-    const fromBag = readObjectPath(bag, path);
-    if (fromBag !== undefined) {
-      return fromBag;
-    }
-    // Absolute path into combined inputs (e.g. `order.totalCents`).
-    return readObjectPath(inputs, path);
-  }
-
-  return field.sampleValue;
-}
-
-/**
- * Apply a conversion to named input bags and build target-shaped JSON.
- *
- * This is the host runtime entry point — not `sourceShape.convert(target, data)`.
- * Multiple source shapes are supported via `inputs[shapeId]`.
- */
-export function convertToShape(input: ConvertToShapeInput): ConvertToShapeResult {
-  const sourceShapes: DataShape[] = [];
-  for (const shapeId of input.conversion.sourceShapeIds) {
-    const shape = resolveShape(input.shapes, shapeId);
-    if (!shape) {
-      throw new Error(`Unknown source shape "${shapeId}" for conversion "${input.conversion.id}".`);
-    }
-    if (shape.role === 'target') {
-      throw new Error(`Shape "${shapeId}" has role "target" and cannot be used as a source.`);
-    }
-    sourceShapes.push(shape);
-  }
-
-  const targetShape = resolveShape(input.shapes, input.conversion.targetShapeId);
-  if (!targetShape) {
-    throw new Error(
-      `Unknown target shape "${input.conversion.targetShapeId}" for conversion "${input.conversion.id}".`,
-    );
-  }
-
-  const sources = mergeSourceShapes(sourceShapes);
-  const targets = targetSlotsFromShape(targetShape);
-  const targetLeaves = flattenTargetSlots(targets);
-
-  let output: Record<string, unknown> = {};
-  const slots: ConvertToShapeSlotResult[] = [];
-
-  for (const edge of input.conversion.document.edges) {
-    const sourceField = findSourceField(sources, edge.sourceFieldId);
-    if (!sourceField) {
-      continue;
-    }
-    const targetSlot =
-      findTargetSlot(targets, edge.targetSlotId) ??
-      targetLeaves.find((slot) => slot.id === edge.targetSlotId);
-    if (!targetSlot) {
-      continue;
-    }
-
-    const sourceValue = readFieldValue(sourceField, input.inputs);
-    const value =
-      edge.itemEdges && edge.itemEdges.length > 0
-        ? convertArrayWithItemEdges({
-            items: sourceValue,
-            itemEdges: edge.itemEdges,
-            sources,
-            targets,
-            transforms: input.transforms,
-            context: input.context,
-          })
-        : resolveMappedValue(edge, sourceValue, input.transforms, {
-            ...input.context,
-            sampleValue: sourceValue,
-            record: isPlainObject(sourceValue)
-              ? sourceValue
-              : isPlainObject(input.context?.record)
-                ? input.context.record
-                : undefined,
-          });
-
-    const path = outputPathForTarget(targetSlot);
-    output = writeObjectPath(output, path, value);
-    slots.push({
-      edgeId: edge.id,
-      targetSlotId: edge.targetSlotId,
-      path,
-      value,
-    });
-  }
-
-  return { output, slots };
-}
+import type { ConversionDefinition } from './conversionDefinition.js';
+import {
+  mergeSourceShapes,
+  targetSlotsFromShape,
+  type DataShape,
+  type DataShapeRegistry,
+} from './dataShape.js';
+import { convertArrayWithItemEdges } from '../mapping/convertItemEdges.js';
+import { isPlainObject, readObjectPath, writeObjectPath } from '../mapping/pathUtils.js';
+import { findSourceField, resolveMappedValue } from '../mapping/resolveMappedValue.js';
+import { findTargetSlot, flattenTargetSlots } from '../mapping/treeUtils.js';
+import type {
+  SourceField,
+  TargetSlot,
+  TransformContext,
+  ValueTransformRegistry,
+} from '../types.js';
+
+export interface ConvertToShapeInput {
+  readonly conversion: ConversionDefinition;
+  /** Shape registry, or an explicit list containing at least the referenced shapes. */
+  readonly shapes: DataShapeRegistry | readonly DataShape[];
+  /**
+   * Named input bags keyed by source shape id.
+   * Example: `{ order: liveOrder, customer: liveCustomer }`.
+   */
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly transforms: ValueTransformRegistry;
+  readonly context?: TransformContext;
+}
+
+export interface ConvertToShapeSlotResult {
+  readonly edgeId: string;
+  readonly targetSlotId: string;
+  readonly path: string;
+  readonly value: unknown;
+}
+
+export interface ConvertToShapeResult {
+  /** Nested JSON matching target shape paths. */
+  readonly output: Record<string, unknown>;
+  /** Flat per-slot results (debug / UI panels). */
+  readonly slots: readonly ConvertToShapeSlotResult[];
+}
+
+function isDataShapeRegistry(
+  shapes: DataShapeRegistry | readonly DataShape[],
+): shapes is DataShapeRegistry {
+  return typeof (shapes as DataShapeRegistry).get === 'function';
+}
+
+function resolveShape(
+  shapes: DataShapeRegistry | readonly DataShape[],
+  id: string,
+): DataShape | undefined {
+  if (isDataShapeRegistry(shapes)) {
+    return shapes.get(id);
+  }
+  return shapes.find((shape) => shape.id === id);
+}
+
+function outputPathForTarget(slot: TargetSlot): string {
+  const path = slot.path?.trim();
+  if (path) {
+    return path;
+  }
+  // Prefer last id segment when hosts use dotted ids (`slot.display.timeText`).
+  const id = slot.id.trim();
+  if (id.includes('.')) {
+    const parts = id.split('.').filter(Boolean);
+    // Drop a leading registry prefix like `slot` when present with 3+ segments.
+    if (parts.length >= 3 && (parts[0] === 'slot' || parts[0] === 'tgt')) {
+      return parts.slice(1).join('.');
+    }
+    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]
+      : // Single-bag fallback: use the only input, or the whole inputs record.
+        Object.keys(inputs).length === 1
+        ? inputs[Object.keys(inputs)[0]!]
+        : inputs;
+
+  const path = field.path?.trim();
+  if (path) {
+    // When bags are per-shape, paths are relative to that bag.
+    // When falling back to the whole inputs record, absolute paths still work.
+    if (shapeId && Object.prototype.hasOwnProperty.call(inputs, shapeId)) {
+      return readObjectPath(bag, path);
+    }
+    const fromBag = readObjectPath(bag, path);
+    if (fromBag !== undefined) {
+      return fromBag;
+    }
+    // Absolute path into combined inputs (e.g. `order.totalCents`).
+    return readObjectPath(inputs, path);
+  }
+
+  return field.sampleValue;
+}
+
+/**
+ * Apply a conversion to named input bags and build target-shaped JSON.
+ *
+ * This is the host runtime entry point — not `sourceShape.convert(target, data)`.
+ * Multiple source shapes are supported via `inputs[shapeId]`.
+ */
+export function convertToShape(input: ConvertToShapeInput): ConvertToShapeResult {
+  const sourceShapes: DataShape[] = [];
+  for (const shapeId of input.conversion.sourceShapeIds) {
+    const shape = resolveShape(input.shapes, shapeId);
+    if (!shape) {
+      throw new Error(`Unknown source shape "${shapeId}" for conversion "${input.conversion.id}".`);
+    }
+    if (shape.role === 'target') {
+      throw new Error(`Shape "${shapeId}" has role "target" and cannot be used as a source.`);
+    }
+    sourceShapes.push(shape);
+  }
+
+  const targetShape = resolveShape(input.shapes, input.conversion.targetShapeId);
+  if (!targetShape) {
+    throw new Error(
+      `Unknown target shape "${input.conversion.targetShapeId}" for conversion "${input.conversion.id}".`,
+    );
+  }
+
+  const sources = mergeSourceShapes(sourceShapes);
+  const targets = targetSlotsFromShape(targetShape);
+  const targetLeaves = flattenTargetSlots(targets);
+
+  let output: Record<string, unknown> = {};
+  const slots: ConvertToShapeSlotResult[] = [];
+
+  for (const edge of input.conversion.document.edges) {
+    const sourceField = findSourceField(sources, edge.sourceFieldId);
+    if (!sourceField) {
+      continue;
+    }
+    const targetSlot =
+      findTargetSlot(targets, edge.targetSlotId) ??
+      targetLeaves.find((slot) => slot.id === edge.targetSlotId);
+    if (!targetSlot) {
+      continue;
+    }
+
+    const sourceValue = readFieldValue(sourceField, input.inputs);
+    const value =
+      edge.itemEdges && edge.itemEdges.length > 0
+        ? convertArrayWithItemEdges({
+            items: sourceValue,
+            itemEdges: edge.itemEdges,
+            sources,
+            targets,
+            transforms: input.transforms,
+            context: input.context,
+          })
+        : resolveMappedValue(edge, sourceValue, input.transforms, {
+            ...input.context,
+            sampleValue: sourceValue,
+            record: isPlainObject(sourceValue)
+              ? sourceValue
+              : isPlainObject(input.context?.record)
+                ? input.context.record
+                : undefined,
+          });
+
+    const path = outputPathForTarget(targetSlot);
+    output = writeObjectPath(output, path, value);
+    slots.push({
+      edgeId: edge.id,
+      targetSlotId: edge.targetSlotId,
+      path,
+      value,
+    });
+  }
+
+  return { output, slots };
+}

package/src/domain/shapes/dataShape.ts

@@ -1,109 +1,109 @@
-import type { SourceField, TargetSlot } from '../types.js';
-
-/** How a managed shape is used in conversions. */
-export type DataShapeRole = 'source' | 'target' | 'both';
-
-/**
- * Managed structure descriptor ("class-like" fixed shape).
- * Source/target field trees are host-owned; this wraps them for registry lookup.
- */
-export interface DataShape {
-  readonly id: string;
-  readonly label: string;
-  readonly role: DataShapeRole;
-  /**
-   * Field tree for source and/or target use.
-   * When `role` is `target`, treat as `TargetSlot[]` (compatible structural shape).
-   * When `role` is `source` or `both`, treat as `SourceField[]`.
-   */
-  readonly fields: readonly SourceField[] | readonly TargetSlot[];
-}
-
-export interface DataShapeRegistry {
-  register(shape: DataShape): void;
-  get(id: string): DataShape | undefined;
-  list(role?: DataShapeRole): readonly DataShape[];
-}
-
-export function defineDataShape(input: DataShape): DataShape {
-  const id = input.id.trim();
-  if (!id) {
-    throw new Error('DataShape.id must be a non-empty string.');
-  }
-  return {
-    id,
-    label: input.label.trim() || id,
-    role: input.role,
-    fields: input.fields,
-  };
-}
-
-export function createDataShapeRegistry(initial: readonly DataShape[] = []): DataShapeRegistry {
-  const byId = new Map<string, DataShape>();
-
-  const api: DataShapeRegistry = {
-    register(shape) {
-      const defined = defineDataShape(shape);
-      byId.set(defined.id, defined);
-    },
-    get(id) {
-      return byId.get(id.trim());
-    },
-    list(role) {
-      const all = [...byId.values()];
-      if (!role) {
-        return all;
-      }
-      return all.filter((shape) => shape.role === role || shape.role === 'both');
-    },
-  };
-
-  for (const shape of initial) {
-    api.register(shape);
-  }
-  return api;
-}
-
-/** Recursively stamp `shapeId` on source fields (for multi-input convert). */
-export function attachShapeIdToSourceFields(
-  fields: readonly SourceField[],
-  shapeId: string,
-): SourceField[] {
-  return fields.map((field) => {
-    const next: SourceField = {
-      ...field,
-      shapeId,
-      ...(field.children ? { children: attachShapeIdToSourceFields(field.children, shapeId) } : {}),
-    };
-    return next;
-  });
-}
-
-/**
- * Merge source shapes into one tree for `FieldRemap` / convert:
- * each shape becomes a non-mappable group whose children carry `shapeId`.
- */
-export function mergeSourceShapes(shapes: readonly DataShape[]): SourceField[] {
-  const sources: SourceField[] = [];
-  for (const shape of shapes) {
-    if (shape.role === 'target') {
-      continue;
-    }
-    const children = attachShapeIdToSourceFields(shape.fields as readonly SourceField[], shape.id);
-    sources.push({
-      id: `shape.${shape.id}`,
-      label: shape.label,
-      group: 'Shapes',
-      children,
-    });
-  }
-  return sources;
-}
-
-/** Target slots from a target (or both) shape. */
-export function targetSlotsFromShape(shape: DataShape): TargetSlot[] {
-  if (shape.role === 'source') {
-    throw new Error(`DataShape "${shape.id}" has role "source" and cannot provide target slots.`);
-  }
-  return shape.fields as TargetSlot[];
-}
+import type { SourceField, TargetSlot } from '../types.js';
+
+/** How a managed shape is used in conversions. */
+export type DataShapeRole = 'source' | 'target' | 'both';
+
+/**
+ * Managed structure descriptor ("class-like" fixed shape).
+ * Source/target field trees are host-owned; this wraps them for registry lookup.
+ */
+export interface DataShape {
+  readonly id: string;
+  readonly label: string;
+  readonly role: DataShapeRole;
+  /**
+   * Field tree for source and/or target use.
+   * When `role` is `target`, treat as `TargetSlot[]` (compatible structural shape).
+   * When `role` is `source` or `both`, treat as `SourceField[]`.
+   */
+  readonly fields: readonly SourceField[] | readonly TargetSlot[];
+}
+
+export interface DataShapeRegistry {
+  register(shape: DataShape): void;
+  get(id: string): DataShape | undefined;
+  list(role?: DataShapeRole): readonly DataShape[];
+}
+
+export function defineDataShape(input: DataShape): DataShape {
+  const id = input.id.trim();
+  if (!id) {
+    throw new Error('DataShape.id must be a non-empty string.');
+  }
+  return {
+    id,
+    label: input.label.trim() || id,
+    role: input.role,
+    fields: input.fields,
+  };
+}
+
+export function createDataShapeRegistry(initial: readonly DataShape[] = []): DataShapeRegistry {
+  const byId = new Map<string, DataShape>();
+
+  const api: DataShapeRegistry = {
+    register(shape) {
+      const defined = defineDataShape(shape);
+      byId.set(defined.id, defined);
+    },
+    get(id) {
+      return byId.get(id.trim());
+    },
+    list(role) {
+      const all = [...byId.values()];
+      if (!role) {
+        return all;
+      }
+      return all.filter((shape) => shape.role === role || shape.role === 'both');
+    },
+  };
+
+  for (const shape of initial) {
+    api.register(shape);
+  }
+  return api;
+}
+
+/** Recursively stamp `shapeId` on source fields (for multi-input convert). */
+export function attachShapeIdToSourceFields(
+  fields: readonly SourceField[],
+  shapeId: string,
+): SourceField[] {
+  return fields.map((field) => {
+    const next: SourceField = {
+      ...field,
+      shapeId,
+      ...(field.children ? { children: attachShapeIdToSourceFields(field.children, shapeId) } : {}),
+    };
+    return next;
+  });
+}
+
+/**
+ * Merge source shapes into one tree for `FieldRemap` / convert:
+ * each shape becomes a non-mappable group whose children carry `shapeId`.
+ */
+export function mergeSourceShapes(shapes: readonly DataShape[]): SourceField[] {
+  const sources: SourceField[] = [];
+  for (const shape of shapes) {
+    if (shape.role === 'target') {
+      continue;
+    }
+    const children = attachShapeIdToSourceFields(shape.fields as readonly SourceField[], shape.id);
+    sources.push({
+      id: `shape.${shape.id}`,
+      label: shape.label,
+      group: 'Shapes',
+      children,
+    });
+  }
+  return sources;
+}
+
+/** Target slots from a target (or both) shape. */
+export function targetSlotsFromShape(shape: DataShape): TargetSlot[] {
+  if (shape.role === 'source') {
+    throw new Error(`DataShape "${shape.id}" has role "source" and cannot provide target slots.`);
+  }
+  return shape.fields as TargetSlot[];
+}