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

package/README.md

@@ -1,115 +1,115 @@
-# `@workbench-kit/field-remap`
-
-Field remap **runtime**: reshape structure A into structure B with mapping edges and `convertToShape`.
-
-This package does **not** ship a mapping UI. Hosts adapt a tree or table UI into `MappingEdge[]`
-and call `convertToShape`. The workbench sample (**Field Remap → A → B**) demonstrates a nested
-tree mapper with list context; flat OSS adapters (for example `react-table-mapping`) remain useful
-for leaf-only hosts.
-
-## Install
-
-```powershell
-pnpm add @workbench-kit/field-remap@prototype
-```
-
-## Capabilities
-
-| Pattern                                   | Support                                                              |
-| ----------------------------------------- | -------------------------------------------------------------------- |
-| Leaf → leaf rename                        | Yes                                                                  |
-| Nested object paths                       | Yes (`path` + `writeObjectPath`)                                     |
-| Array whole copy                          | Yes (`identity`)                                                     |
-| Array item projection                     | Yes (`itemSourcePath`)                                               |
-| Array → scalar reduce                     | Yes (`array:first`, `array:join`)                                    |
-| String format chain                       | Yes (`string:trim` / `upper` / `lower` / `prefix` / `suffix`, max 3) |
-| Array<object> → Array<object> | Yes (`itemEdges` list context)                                       |
-| Index / wildcard paths                    | No (P2)                                                              |
-
-Middle “graph nodes” in the sample UI are just `MappingEdge.transformIds` steps
-(plus optional `transformOptionSteps`), not a separate document type. The workbench
-sample renders them with `@xyflow/react` (source out → transform → target in).
-
-## Quick start
-
-```ts
-import {
-  convertToShape,
-  createBuiltinValueTransformRegistry,
-  defineConversion,
-  defineDataShape,
-  sourceFieldsFromPlainObject,
-  targetSlotsFromPlainObject,
-} from '@workbench-kit/field-remap';
-
-const structureA = {
-  user_name: 'Ada',
-  tags: [{ name: 'math' }, { name: 'computing' }],
-};
-
-const shapes = [
-  defineDataShape({
-    id: 'a',
-    label: 'A',
-    role: 'source',
-    fields: sourceFieldsFromPlainObject(structureA, { idPrefix: 'a' }),
-  }),
-  defineDataShape({
-    id: 'b',
-    label: 'B',
-    role: 'target',
-    fields: targetSlotsFromPlainObject({ name: '', labels: [{ title: '' }] }, { idPrefix: 'b' }),
-  }),
-];
-
-const conversion = defineConversion({
-  id: 'a→b',
-  sourceShapeIds: ['a'],
-  targetShapeId: 'b',
-  edges: [
-    {
-      id: 'e-name',
-      sourceFieldId: 'a.user_name',
-      targetSlotId: 'b.name',
-    },
-    {
-      id: 'e-tags',
-      sourceFieldId: 'a.tags',
-      targetSlotId: 'b.labels',
-      itemEdges: [
-        {
-          id: 'e-title',
-          sourceFieldId: 'a.tags.item.name',
-          targetSlotId: 'b.labels.item.title',
-        },
-      ],
-    },
-  ],
-});
-
-const { output } = convertToShape({
-  conversion,
-  shapes,
-  inputs: { a: structureA },
-  transforms: createBuiltinValueTransformRegistry(),
-});
-// { name: 'Ada', labels: [{ title: 'math' }, { title: 'computing' }] }
-```
-
-Hosts may `registry.register()` additional transforms (the sample registers `expr:jsonata` via
-[jsonata](https://jsonata.org/)).
-
-## Layout
-
-```text
-src/
-  domain/document/  edges + FieldRemapDocument
-  domain/shapes/    DataShape, ConversionDefinition, convertToShape
-  domain/ingest/    plain object → fields / slots
-  domain/mapping/   path helpers, list context, conflicts
-  registry/         ValueTransform registry (identity, array:first, array:join)
-```
-
-## Stability
-
-Published on the npm `@prototype` tag. Prefer the root export; deep paths are unsupported.
+# `@workbench-kit/field-remap`
+
+Field remap **runtime**: reshape structure A into structure B with mapping edges and `convertToShape`.
+
+This package does **not** ship a mapping UI. Hosts adapt a tree or table UI into `MappingEdge[]`
+and call `convertToShape`. The workbench sample (**Field Remap → A → B**) demonstrates a nested
+tree mapper with list context; flat OSS adapters (for example `react-table-mapping`) remain useful
+for leaf-only hosts.
+
+## Install
+
+```powershell
+pnpm add @workbench-kit/field-remap@prototype
+```
+
+## Capabilities
+
+| Pattern                                   | Support                                                              |
+| ----------------------------------------- | -------------------------------------------------------------------- |
+| Leaf → leaf rename                        | Yes                                                                  |
+| Nested object paths                       | Yes (`path` + `writeObjectPath`)                                     |
+| Array whole copy                          | Yes (`identity`)                                                     |
+| Array item projection                     | Yes (`itemSourcePath`)                                               |
+| Array → scalar reduce                     | Yes (`array:first`, `array:join`)                                    |
+| String format chain                       | Yes (`string:trim` / `upper` / `lower` / `prefix` / `suffix`, max 3) |
+| Array<object> → Array<object> | Yes (`itemEdges` list context)                                       |
+| Index / wildcard paths                    | No (P2)                                                              |
+
+Middle “graph nodes” in the sample UI are just `MappingEdge.transformIds` steps
+(plus optional `transformOptionSteps`), not a separate document type. The workbench
+sample renders them with `@xyflow/react` (source out → transform → target in).
+
+## Quick start
+
+```ts
+import {
+  convertToShape,
+  createBuiltinValueTransformRegistry,
+  defineConversion,
+  defineDataShape,
+  sourceFieldsFromPlainObject,
+  targetSlotsFromPlainObject,
+} from '@workbench-kit/field-remap';
+
+const structureA = {
+  user_name: 'Ada',
+  tags: [{ name: 'math' }, { name: 'computing' }],
+};
+
+const shapes = [
+  defineDataShape({
+    id: 'a',
+    label: 'A',
+    role: 'source',
+    fields: sourceFieldsFromPlainObject(structureA, { idPrefix: 'a' }),
+  }),
+  defineDataShape({
+    id: 'b',
+    label: 'B',
+    role: 'target',
+    fields: targetSlotsFromPlainObject({ name: '', labels: [{ title: '' }] }, { idPrefix: 'b' }),
+  }),
+];
+
+const conversion = defineConversion({
+  id: 'a→b',
+  sourceShapeIds: ['a'],
+  targetShapeId: 'b',
+  edges: [
+    {
+      id: 'e-name',
+      sourceFieldId: 'a.user_name',
+      targetSlotId: 'b.name',
+    },
+    {
+      id: 'e-tags',
+      sourceFieldId: 'a.tags',
+      targetSlotId: 'b.labels',
+      itemEdges: [
+        {
+          id: 'e-title',
+          sourceFieldId: 'a.tags.item.name',
+          targetSlotId: 'b.labels.item.title',
+        },
+      ],
+    },
+  ],
+});
+
+const { output } = convertToShape({
+  conversion,
+  shapes,
+  inputs: { a: structureA },
+  transforms: createBuiltinValueTransformRegistry(),
+});
+// { name: 'Ada', labels: [{ title: 'math' }, { title: 'computing' }] }
+```
+
+Hosts may `registry.register()` additional transforms (the sample registers `expr:jsonata` via
+[jsonata](https://jsonata.org/)).
+
+## Layout
+
+```text
+src/
+  domain/document/  edges + FieldRemapDocument
+  domain/shapes/    DataShape, ConversionDefinition, convertToShape
+  domain/ingest/    plain object → fields / slots
+  domain/mapping/   path helpers, list context, conflicts
+  registry/         ValueTransform registry (identity, array:first, array:join)
+```
+
+## Stability
+
+Published on the npm `@prototype` tag. Prefer the root export; deep paths are unsupported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workbench-kit/field-remap",
-  "version": "0.0.1-prototype.0",
+  "version": "0.0.2-prototype.0.2.5",
   "private": false,
   "type": "module",
   "exports": {

package/src/domain/constants.ts

@@ -1,14 +1,14 @@
-/** Maximum ordered transforms applied on a single edge. */
-export const MAX_TRANSFORM_CHAIN = 3;
-
-/** Built-in pass-through transform id (kept here to avoid import cycles). */
-export const IDENTITY_TRANSFORM_ID = 'identity';
-
-/** Legacy id aliases → canonical ids (empty until hosts need migration). */
-export const TRANSFORM_ID_ALIASES: Readonly<Record<string, string>> = {};
-
-/** Map a legacy or canonical transform id to its canonical form. */
-export function canonicalizeTransformId(id: string): string {
-  const trimmed = id.trim();
-  return TRANSFORM_ID_ALIASES[trimmed] ?? trimmed;
-}
+/** Maximum ordered transforms applied on a single edge. */
+export const MAX_TRANSFORM_CHAIN = 3;
+
+/** Built-in pass-through transform id (kept here to avoid import cycles). */
+export const IDENTITY_TRANSFORM_ID = 'identity';
+
+/** Legacy id aliases → canonical ids (empty until hosts need migration). */
+export const TRANSFORM_ID_ALIASES: Readonly<Record<string, string>> = {};
+
+/** Map a legacy or canonical transform id to its canonical form. */
+export function canonicalizeTransformId(id: string): string {
+  const trimmed = id.trim();
+  return TRANSFORM_ID_ALIASES[trimmed] ?? trimmed;
+}

package/src/domain/document/fieldRemapDocument.ts

@@ -1,129 +1,129 @@
-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 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);
+  }
+}