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

package/src/domain/document/fieldRemapDocument.ts

@@ -1,129 +1,163 @@
-import { normalizeMappingEdges } from './mappingEdge.js';
-import type { MappingEdge, FieldRemapDocument } from '../types.js';
-
-export const FIELD_REMAP_DOCUMENT_VERSION = 1 as const;
-
-/** Thrown when parse/deserialize sees a document `version` other than the supported constant. */
-export class UnsupportedFieldRemapDocumentVersionError extends Error {
-  readonly version: unknown;
-  readonly expectedVersion: typeof FIELD_REMAP_DOCUMENT_VERSION;
-
-  constructor(version: unknown) {
-    super(
-      `Unsupported field remap document version ${String(version)}; expected ${FIELD_REMAP_DOCUMENT_VERSION}.`,
-    );
-    this.name = 'UnsupportedFieldRemapDocumentVersionError';
-    this.version = version;
-    this.expectedVersion = FIELD_REMAP_DOCUMENT_VERSION;
-  }
-}
-
-/** Thrown when parse/deserialize receives a value that is not a mapping document. */
-export class InvalidFieldRemapDocumentError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'InvalidFieldRemapDocumentError';
-  }
-}
-
-/** Build a versioned, normalized mapping document for host persistence. */
-export function createFieldRemapDocument(edges: readonly MappingEdge[]): FieldRemapDocument {
-  return {
-    version: FIELD_REMAP_DOCUMENT_VERSION,
-    edges: normalizeMappingEdges(edges),
-  };
-}
-
-/** Normalize edges (including legacy transform id aliases) on a persisted document. */
-export function normalizeFieldRemapDocument(document: FieldRemapDocument): FieldRemapDocument {
-  if (document.version !== FIELD_REMAP_DOCUMENT_VERSION) {
-    throw new UnsupportedFieldRemapDocumentVersionError(document.version);
-  }
-  return {
-    version: FIELD_REMAP_DOCUMENT_VERSION,
-    edges: normalizeMappingEdges(document.edges),
-  };
-}
-
-/**
- * Stable JSON serialization for persistence / clipboard.
- * Always emits the current document version with normalized edges.
- */
-export function serializeFieldRemapDocument(
-  document: FieldRemapDocument | readonly MappingEdge[],
-): string {
-  const doc = Array.isArray(document)
-    ? createFieldRemapDocument(document)
-    : createFieldRemapDocument((document as FieldRemapDocument).edges);
-  return JSON.stringify(doc);
-}
-
-/**
- * Parse an unknown JSON value into a normalized `FieldRemapDocument`.
- * Rejects unsupported versions and malformed shapes with typed errors.
- */
-export function parseFieldRemapDocument(input: unknown): FieldRemapDocument {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new InvalidFieldRemapDocumentError(
-      'Expected a field remap document object with version and edges.',
-    );
-  }
-
-  const record = input as Record<string, unknown>;
-  if (!('version' in record)) {
-    throw new InvalidFieldRemapDocumentError('Field remap document is missing version.');
-  }
-  if (record.version !== FIELD_REMAP_DOCUMENT_VERSION) {
-    throw new UnsupportedFieldRemapDocumentVersionError(record.version);
-  }
-  if (!Array.isArray(record.edges)) {
-    throw new InvalidFieldRemapDocumentError('Field remap document edges must be an array.');
-  }
-
-  return normalizeFieldRemapDocument({
-    version: FIELD_REMAP_DOCUMENT_VERSION,
-    edges: record.edges as MappingEdge[],
-  });
-}
-
-/** JSON.parse + {@link parseFieldRemapDocument}. */
-export function deserializeFieldRemapDocument(json: string): FieldRemapDocument {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(json) as unknown;
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new InvalidFieldRemapDocumentError(`Field remap document JSON is invalid: ${detail}`);
-  }
-  return parseFieldRemapDocument(parsed);
-}
-
-/**
- * Migrate an unknown persisted value to the current {@link FieldRemapDocument}.
- *
- * Hosts should call this (or `parseFieldRemapDocument`) at load time so future
- * document versions can be rewritten here without changing call sites.
- *
- * **v1:** passthrough normalize (legacy transform id aliases rewritten).
- * Future versions: add `case` branches that rewrite into v1 shape, then normalize.
- */
-export function migrateFieldRemapDocument(input: unknown): FieldRemapDocument {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new InvalidFieldRemapDocumentError(
-      'Expected a field remap document object with version and edges.',
-    );
-  }
-
-  const record = input as Record<string, unknown>;
-  if (!('version' in record)) {
-    throw new InvalidFieldRemapDocumentError('Field remap document is missing version.');
-  }
-
-  switch (record.version) {
-    case FIELD_REMAP_DOCUMENT_VERSION:
-      return parseFieldRemapDocument(input);
-    // Future: case 2: return parseFieldRemapDocument(migrateV2ToV1(record));
-    default:
-      throw new UnsupportedFieldRemapDocumentVersionError(record.version);
-  }
-}
+import { normalizeMappingEdges } from './mappingEdge.js';
+import { normalizeMappingOperators } from '../mapping/mappingOperators.js';
+import type { MappingEdge, MappingOperator, FieldRemapDocument } from '../types.js';
+
+/** Current persistence version (edges + optional `operators[]`). */
+export const FIELD_REMAP_DOCUMENT_VERSION = 2 as const;
+/** Legacy edges-only documents. */
+export const FIELD_REMAP_DOCUMENT_V1_VERSION = 1 as const;
+
+type SupportedDocumentVersion =
+  typeof FIELD_REMAP_DOCUMENT_VERSION | typeof FIELD_REMAP_DOCUMENT_V1_VERSION;
+
+/** Thrown when parse/deserialize sees a document `version` other than a supported constant. */
+export class UnsupportedFieldRemapDocumentVersionError extends Error {
+  readonly version: unknown;
+  readonly expectedVersion: typeof FIELD_REMAP_DOCUMENT_VERSION;
+
+  constructor(version: unknown) {
+    super(
+      `Unsupported field remap document version ${String(version)}; expected ${FIELD_REMAP_DOCUMENT_V1_VERSION} or ${FIELD_REMAP_DOCUMENT_VERSION}.`,
+    );
+    this.name = 'UnsupportedFieldRemapDocumentVersionError';
+    this.version = version;
+    this.expectedVersion = FIELD_REMAP_DOCUMENT_VERSION;
+  }
+}
+
+/** Thrown when parse/deserialize receives a value that is not a mapping document. */
+export class InvalidFieldRemapDocumentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidFieldRemapDocumentError';
+  }
+}
+
+export type CreateFieldRemapDocumentOptions = {
+  readonly operators?: readonly MappingOperator[];
+};
+
+/** Build a versioned, normalized mapping document for host persistence. */
+export function createFieldRemapDocument(
+  edges: readonly MappingEdge[],
+  options?: CreateFieldRemapDocumentOptions,
+): FieldRemapDocument {
+  const operators = normalizeMappingOperators(options?.operators);
+  return {
+    version: FIELD_REMAP_DOCUMENT_VERSION,
+    edges: normalizeMappingEdges(edges),
+    ...(operators ? { operators } : {}),
+  };
+}
+
+function isSupportedVersion(version: unknown): version is SupportedDocumentVersion {
+  return version === FIELD_REMAP_DOCUMENT_V1_VERSION || version === FIELD_REMAP_DOCUMENT_VERSION;
+}
+
+/** Normalize edges / operators on a persisted document; always emits the current version. */
+export function normalizeFieldRemapDocument(document: FieldRemapDocument): FieldRemapDocument {
+  if (!isSupportedVersion(document.version)) {
+    throw new UnsupportedFieldRemapDocumentVersionError(document.version);
+  }
+  const operators = normalizeMappingOperators(document.operators);
+  return {
+    version: FIELD_REMAP_DOCUMENT_VERSION,
+    edges: normalizeMappingEdges(document.edges),
+    ...(operators ? { operators } : {}),
+  };
+}
+
+/**
+ * Stable JSON serialization for persistence / clipboard.
+ * Always emits the current document version with normalized edges / operators.
+ */
+export function serializeFieldRemapDocument(
+  document: FieldRemapDocument | readonly MappingEdge[],
+): string {
+  const doc = Array.isArray(document)
+    ? createFieldRemapDocument(document)
+    : createFieldRemapDocument((document as FieldRemapDocument).edges, {
+        operators: (document as FieldRemapDocument).operators,
+      });
+  return JSON.stringify(doc);
+}
+
+/**
+ * Parse an unknown JSON value into a normalized `FieldRemapDocument`.
+ * Accepts v1 (edges-only) and v2 (optional operators); always returns current version.
+ */
+export function parseFieldRemapDocument(input: unknown): FieldRemapDocument {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new InvalidFieldRemapDocumentError(
+      'Expected a field remap document object with version and edges.',
+    );
+  }
+
+  const record = input as Record<string, unknown>;
+  if (!('version' in record)) {
+    throw new InvalidFieldRemapDocumentError('Field remap document is missing version.');
+  }
+  if (!isSupportedVersion(record.version)) {
+    throw new UnsupportedFieldRemapDocumentVersionError(record.version);
+  }
+  if (!Array.isArray(record.edges)) {
+    throw new InvalidFieldRemapDocumentError('Field remap document edges must be an array.');
+  }
+  if (
+    record.operators !== undefined &&
+    record.operators !== null &&
+    !Array.isArray(record.operators)
+  ) {
+    throw new InvalidFieldRemapDocumentError(
+      'Field remap document operators must be an array when present.',
+    );
+  }
+
+  return normalizeFieldRemapDocument({
+    version: record.version,
+    edges: record.edges as MappingEdge[],
+    operators: record.operators as MappingOperator[] | undefined,
+  });
+}
+
+/** JSON.parse + {@link parseFieldRemapDocument}. */
+export function deserializeFieldRemapDocument(json: string): FieldRemapDocument {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json) as unknown;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new InvalidFieldRemapDocumentError(`Field remap document JSON is invalid: ${detail}`);
+  }
+  return parseFieldRemapDocument(parsed);
+}
+
+/**
+ * Migrate an unknown persisted value to the current {@link FieldRemapDocument}.
+ *
+ * Hosts should call this (or `parseFieldRemapDocument`) at load time so future
+ * document versions can be rewritten here without changing call sites.
+ *
+ * **v1:** edges-only → current version (operators omitted).
+ * **v2:** normalize edges + operators.
+ */
+export function migrateFieldRemapDocument(input: unknown): FieldRemapDocument {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new InvalidFieldRemapDocumentError(
+      'Expected a field remap document object with version and edges.',
+    );
+  }
+
+  const record = input as Record<string, unknown>;
+  if (!('version' in record)) {
+    throw new InvalidFieldRemapDocumentError('Field remap document is missing version.');
+  }
+
+  switch (record.version) {
+    case FIELD_REMAP_DOCUMENT_V1_VERSION:
+    case FIELD_REMAP_DOCUMENT_VERSION:
+      return parseFieldRemapDocument(input);
+    default:
+      throw new UnsupportedFieldRemapDocumentVersionError(record.version);
+  }
+}

package/src/domain/document/mappingEdge.ts

@@ -1,136 +1,136 @@
-import {
-  canonicalizeTransformId,
-  IDENTITY_TRANSFORM_ID,
-  MAX_TRANSFORM_CHAIN,
-} from '../constants.js';
-import {
-  sanitizeOptionRecord,
-  sanitizeOptionSteps,
-  sharedOptionsFromSteps,
-} from '../mapping/transformOptions.js';
-import type { MappingEdge } from '../types.js';
-
-export { MAX_TRANSFORM_CHAIN } from '../constants.js';
-
-function sanitizeTransformIds(ids: readonly string[] | undefined): string[] {
-  const cleaned = ids
-    ?.map((id) => canonicalizeTransformId(id))
-    .filter((id) => id.length > 0 && id !== IDENTITY_TRANSFORM_ID);
-  if (!cleaned || cleaned.length === 0) {
-    return [];
-  }
-  return cleaned.slice(0, MAX_TRANSFORM_CHAIN);
-}
-
-/**
- * Resolve the effective transform chain for an edge.
- * Prefers `transformIds`; falls back to legacy `transformId`.
- * Identity / empty / null → `[]` (pass-through).
- */
-export function edgeTransformIds(edge: MappingEdge): string[] {
-  const fromList = sanitizeTransformIds(edge.transformIds);
-  if (fromList.length > 0) {
-    return fromList;
-  }
-
-  const legacy = edge.transformId ? canonicalizeTransformId(edge.transformId) : '';
-  if (legacy && legacy !== IDENTITY_TRANSFORM_ID) {
-    return [legacy];
-  }
-
-  return [];
-}
-
-/** Per-item transform chain applied after optional `itemSourcePath` projection. */
-export function edgeItemTransformIds(edge: MappingEdge): string[] {
-  return sanitizeTransformIds(edge.itemTransformIds);
-}
-
-/**
- * Normalize an edge to the `transformIds` model while keeping `transformId`
- * as the first chain step (or `null`) for older hosts.
- *
- * Option bags:
- * - Prefer `transformOptionSteps` when present (aligned to chain length).
- * - Keep `transformOptions` as the first non-empty step (or the legacy shared bag).
- * - Same rules for `itemTransformOptionSteps` / `itemTransformOptions`.
- */
-export function normalizeMappingEdge(edge: MappingEdge): MappingEdge {
-  const ids = edgeTransformIds(edge);
-  const itemIds = edgeItemTransformIds(edge);
-  const itemSourcePath = edge.itemSourcePath?.trim() || undefined;
-  const itemEdges =
-    edge.itemEdges && edge.itemEdges.length > 0
-      ? edge.itemEdges.map((child) => {
-          // One collection level — drop nested list contexts on children.
-          const { itemEdges: _nested, ...rest } = child;
-          return normalizeMappingEdge(rest);
-        })
-      : undefined;
-
-  const transformOptionSteps = sanitizeOptionSteps(edge.transformOptionSteps, ids.length);
-  const transformOptions =
-    sharedOptionsFromSteps(transformOptionSteps) ?? sanitizeOptionRecord(edge.transformOptions);
-
-  const itemTransformOptionSteps = sanitizeOptionSteps(
-    edge.itemTransformOptionSteps,
-    itemIds.length,
-  );
-  const itemTransformOptions =
-    sharedOptionsFromSteps(itemTransformOptionSteps) ??
-    sanitizeOptionRecord(edge.itemTransformOptions);
-
-  return {
-    id: edge.id,
-    sourceFieldId: edge.sourceFieldId,
-    targetSlotId: edge.targetSlotId,
-    transformIds: ids.length > 0 ? ids : undefined,
-    transformId: ids[0] ?? null,
-    ...(transformOptionSteps ? { transformOptionSteps } : {}),
-    ...(transformOptions ? { transformOptions } : {}),
-    ...(itemSourcePath && !itemEdges ? { itemSourcePath } : {}),
-    ...(itemIds.length > 0 && !itemEdges ? { itemTransformIds: itemIds } : {}),
-    ...(itemTransformOptionSteps && !itemEdges ? { itemTransformOptionSteps } : {}),
-    ...(itemTransformOptions && !itemEdges ? { itemTransformOptions } : {}),
-    ...(itemEdges ? { itemEdges } : {}),
-  };
-}
-
-export function normalizeMappingEdges(edges: readonly MappingEdge[]): MappingEdge[] {
-  return edges.map(normalizeMappingEdge);
-}
-
-/** Build a normalized edge from wire / assign actions. */
-export function createMappingEdge(input: {
-  readonly id: string;
-  readonly sourceFieldId: string;
-  readonly targetSlotId: string;
-  readonly transformIds?: readonly string[];
-  /** Legacy single id; ignored when `transformIds` is provided. */
-  readonly transformId?: string | null;
-  readonly transformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  readonly transformOptions?: Readonly<Record<string, unknown>>;
-  /** Optional per-item projection path for array mappings. */
-  readonly itemSourcePath?: string;
-  /** Optional per-item transform chain after projection. */
-  readonly itemTransformIds?: readonly string[];
-  readonly itemTransformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  readonly itemTransformOptions?: Readonly<Record<string, unknown>>;
-  /** List-context child edges for array-of-object → array-of-object. */
-  readonly itemEdges?: readonly MappingEdge[];
-}): MappingEdge {
-  return normalizeMappingEdge({
-    id: input.id,
-    sourceFieldId: input.sourceFieldId,
-    targetSlotId: input.targetSlotId,
-    transformIds: input.transformIds,
-    transformId: input.transformId,
-    transformOptionSteps: input.transformOptionSteps,
-    transformOptions: input.transformOptions,
-    itemSourcePath: input.itemSourcePath,
-    itemTransformIds: input.itemTransformIds,
-    itemTransformOptionSteps: input.itemTransformOptionSteps,
-    itemTransformOptions: input.itemTransformOptions,
-    itemEdges: input.itemEdges,
-  });
-}
+import {
+  canonicalizeTransformId,
+  IDENTITY_TRANSFORM_ID,
+  MAX_TRANSFORM_CHAIN,
+} from '../constants.js';
+import {
+  sanitizeOptionRecord,
+  sanitizeOptionSteps,
+  sharedOptionsFromSteps,
+} from '../mapping/transformOptions.js';
+import type { MappingEdge } from '../types.js';
+
+export { MAX_TRANSFORM_CHAIN } from '../constants.js';
+
+function sanitizeTransformIds(ids: readonly string[] | undefined): string[] {
+  const cleaned = ids
+    ?.map((id) => canonicalizeTransformId(id))
+    .filter((id) => id.length > 0 && id !== IDENTITY_TRANSFORM_ID);
+  if (!cleaned || cleaned.length === 0) {
+    return [];
+  }
+  return cleaned.slice(0, MAX_TRANSFORM_CHAIN);
+}
+
+/**
+ * Resolve the effective transform chain for an edge.
+ * Prefers `transformIds`; falls back to legacy `transformId`.
+ * Identity / empty / null → `[]` (pass-through).
+ */
+export function edgeTransformIds(edge: MappingEdge): string[] {
+  const fromList = sanitizeTransformIds(edge.transformIds);
+  if (fromList.length > 0) {
+    return fromList;
+  }
+
+  const legacy = edge.transformId ? canonicalizeTransformId(edge.transformId) : '';
+  if (legacy && legacy !== IDENTITY_TRANSFORM_ID) {
+    return [legacy];
+  }
+
+  return [];
+}
+
+/** Per-item transform chain applied after optional `itemSourcePath` projection. */
+export function edgeItemTransformIds(edge: MappingEdge): string[] {
+  return sanitizeTransformIds(edge.itemTransformIds);
+}
+
+/**
+ * Normalize an edge to the `transformIds` model while keeping `transformId`
+ * as the first chain step (or `null`) for older hosts.
+ *
+ * Option bags:
+ * - Prefer `transformOptionSteps` when present (aligned to chain length).
+ * - Keep `transformOptions` as the first non-empty step (or the legacy shared bag).
+ * - Same rules for `itemTransformOptionSteps` / `itemTransformOptions`.
+ */
+export function normalizeMappingEdge(edge: MappingEdge): MappingEdge {
+  const ids = edgeTransformIds(edge);
+  const itemIds = edgeItemTransformIds(edge);
+  const itemSourcePath = edge.itemSourcePath?.trim() || undefined;
+  const itemEdges =
+    edge.itemEdges && edge.itemEdges.length > 0
+      ? edge.itemEdges.map((child) => {
+          // One collection level — drop nested list contexts on children.
+          const { itemEdges: _nested, ...rest } = child;
+          return normalizeMappingEdge(rest);
+        })
+      : undefined;
+
+  const transformOptionSteps = sanitizeOptionSteps(edge.transformOptionSteps, ids.length);
+  const transformOptions =
+    sharedOptionsFromSteps(transformOptionSteps) ?? sanitizeOptionRecord(edge.transformOptions);
+
+  const itemTransformOptionSteps = sanitizeOptionSteps(
+    edge.itemTransformOptionSteps,
+    itemIds.length,
+  );
+  const itemTransformOptions =
+    sharedOptionsFromSteps(itemTransformOptionSteps) ??
+    sanitizeOptionRecord(edge.itemTransformOptions);
+
+  return {
+    id: edge.id,
+    sourceFieldId: edge.sourceFieldId,
+    targetSlotId: edge.targetSlotId,
+    transformIds: ids.length > 0 ? ids : undefined,
+    transformId: ids[0] ?? null,
+    ...(transformOptionSteps ? { transformOptionSteps } : {}),
+    ...(transformOptions ? { transformOptions } : {}),
+    ...(itemSourcePath && !itemEdges ? { itemSourcePath } : {}),
+    ...(itemIds.length > 0 && !itemEdges ? { itemTransformIds: itemIds } : {}),
+    ...(itemTransformOptionSteps && !itemEdges ? { itemTransformOptionSteps } : {}),
+    ...(itemTransformOptions && !itemEdges ? { itemTransformOptions } : {}),
+    ...(itemEdges ? { itemEdges } : {}),
+  };
+}
+
+export function normalizeMappingEdges(edges: readonly MappingEdge[]): MappingEdge[] {
+  return edges.map(normalizeMappingEdge);
+}
+
+/** Build a normalized edge from wire / assign actions. */
+export function createMappingEdge(input: {
+  readonly id: string;
+  readonly sourceFieldId: string;
+  readonly targetSlotId: string;
+  readonly transformIds?: readonly string[];
+  /** Legacy single id; ignored when `transformIds` is provided. */
+  readonly transformId?: string | null;
+  readonly transformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
+  readonly transformOptions?: Readonly<Record<string, unknown>>;
+  /** Optional per-item projection path for array mappings. */
+  readonly itemSourcePath?: string;
+  /** Optional per-item transform chain after projection. */
+  readonly itemTransformIds?: readonly string[];
+  readonly itemTransformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
+  readonly itemTransformOptions?: Readonly<Record<string, unknown>>;
+  /** List-context child edges for array-of-object → array-of-object. */
+  readonly itemEdges?: readonly MappingEdge[];
+}): MappingEdge {
+  return normalizeMappingEdge({
+    id: input.id,
+    sourceFieldId: input.sourceFieldId,
+    targetSlotId: input.targetSlotId,
+    transformIds: input.transformIds,
+    transformId: input.transformId,
+    transformOptionSteps: input.transformOptionSteps,
+    transformOptions: input.transformOptions,
+    itemSourcePath: input.itemSourcePath,
+    itemTransformIds: input.itemTransformIds,
+    itemTransformOptionSteps: input.itemTransformOptionSteps,
+    itemTransformOptions: input.itemTransformOptions,
+    itemEdges: input.itemEdges,
+  });
+}