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

package/README.md

@@ -87,7 +87,7 @@ const conversion = defineConversion({
   ],
 });
 
-const { output } = convertToShape({
+const { output } = await convertToShape({
   conversion,
   shapes,
   inputs: { a: structureA },
@@ -97,7 +97,17 @@ const { output } = convertToShape({
 ```
 
 Hosts may `registry.register()` additional transforms (the sample registers `expr:jsonata` via
-[jsonata](https://jsonata.org/)).
+[jsonata](https://jsonata.org/)). `convertToShape` / `applyTransformChain` are async so Promise-returning
+host transforms (JSONata 2.x) resolve correctly.
+
+### Cancellation
+
+Pass `signal` on `convertToShape` (or `TransformContext.signal`) to cancel stale previews.
+Aborted runs reject with `AbortError` and stop further edges / chain steps. The shell Field Remap
+panel wires an `AbortController` to effect cleanup.
+
+Host JSONata transforms in `@workbench-kit/shell-react` are bounded by default (`timeoutMs`,
+`maxExpressionLength`, `onError: 'throw'`). Use `createJsonataValueTransform()` to override.
 
 ## Layout
 

package/package.json

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

package/src/domain/abort.ts

@@ -0,0 +1,29 @@
+/** Create an Error with `name === 'AbortError'` (DOMException when available). */
+export function createAbortError(message = 'The operation was aborted.'): Error {
+  if (typeof DOMException !== 'undefined') {
+    return new DOMException(message, 'AbortError');
+  }
+  const error = new Error(message);
+  error.name = 'AbortError';
+  return error;
+}
+
+export function isAbortError(error: unknown): boolean {
+  return (
+    (typeof DOMException !== 'undefined' &&
+      error instanceof DOMException &&
+      error.name === 'AbortError') ||
+    (error instanceof Error && error.name === 'AbortError')
+  );
+}
+
+/** Throw when `signal` is already aborted. */
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) {
+    return;
+  }
+  if (signal.reason instanceof Error) {
+    throw signal.reason;
+  }
+  throw createAbortError();
+}

package/src/domain/mapping/convertItemEdges.ts

@@ -1,3 +1,4 @@
+import { throwIfAborted } from '../abort.js';
 import { edgeTransformIds } from '../document/mappingEdge.js';
 import { applyTransformChain } from '../../registry/createValueTransformRegistry.js';
 import { BUILTIN_TRANSFORM_IDS } from '../../registry/builtinTransforms.js';
@@ -33,61 +34,65 @@ function itemRelativePath(
  * Convert each object in a source array through list-context `itemEdges`.
  * Child field paths are treated as item-relative (ingest array children).
  */
-export function convertArrayWithItemEdges(input: {
+export async function convertArrayWithItemEdges(input: {
   readonly items: unknown;
   readonly itemEdges: readonly MappingEdge[];
   readonly sources: readonly SourceField[];
   readonly targets: readonly TargetSlot[];
   readonly transforms: ValueTransformRegistry;
   readonly context?: TransformContext;
-}): unknown[] {
+}): Promise<unknown[]> {
   if (!Array.isArray(input.items)) {
     return [];
   }
 
   const targetLeaves = flattenTargetSlots(input.targets);
 
-  return input.items.map((rawItem) => {
-    const item = isPlainObject(rawItem) ? rawItem : {};
-    let outItem: Record<string, unknown> = {};
+  return Promise.all(
+    input.items.map(async (rawItem) => {
+      const item = isPlainObject(rawItem) ? rawItem : {};
+      let outItem: Record<string, unknown> = {};
 
-    for (const edge of input.itemEdges) {
-      const sourceField = findSourceField(input.sources, edge.sourceFieldId);
-      const targetSlot =
-        findTargetSlot(input.targets, edge.targetSlotId) ??
-        targetLeaves.find((slot) => slot.id === edge.targetSlotId);
-      if (!sourceField || !targetSlot) {
-        continue;
-      }
+      for (const edge of input.itemEdges) {
+        throwIfAborted(input.context?.signal);
 
-      const sourcePath = itemRelativePath(sourceField);
-      const sourceValue = sourcePath ? readObjectPath(item, sourcePath) : undefined;
+        const sourceField = findSourceField(input.sources, edge.sourceFieldId);
+        const targetSlot =
+          findTargetSlot(input.targets, edge.targetSlotId) ??
+          targetLeaves.find((slot) => slot.id === edge.targetSlotId);
+        if (!sourceField || !targetSlot) {
+          continue;
+        }
 
-      const chain = edgeTransformIds(edge);
-      let value: unknown;
-      if (chain.length === 0) {
-        const identity = input.transforms.get(BUILTIN_TRANSFORM_IDS.identity);
-        value = identity
-          ? identity.apply(sourceValue, { ...input.context, sampleValue: sourceValue })
-          : sourceValue;
-      } else {
-        const steps = resolveOptionSteps(chain, edge.transformOptionSteps, edge.transformOptions);
-        value = applyTransformChain(
-          input.transforms,
-          chain,
-          sourceValue,
-          { ...input.context, sampleValue: sourceValue },
-          steps,
-        );
-      }
+        const sourcePath = itemRelativePath(sourceField);
+        const sourceValue = sourcePath ? readObjectPath(item, sourcePath) : undefined;
+
+        const chain = edgeTransformIds(edge);
+        let value: unknown;
+        if (chain.length === 0) {
+          const identity = input.transforms.get(BUILTIN_TRANSFORM_IDS.identity);
+          value = identity
+            ? await identity.apply(sourceValue, { ...input.context, sampleValue: sourceValue })
+            : sourceValue;
+        } else {
+          const steps = resolveOptionSteps(chain, edge.transformOptionSteps, edge.transformOptions);
+          value = await applyTransformChain(
+            input.transforms,
+            chain,
+            sourceValue,
+            { ...input.context, sampleValue: sourceValue },
+            steps,
+          );
+        }
 
-      const targetPath = itemRelativePath(targetSlot);
-      if (!targetPath) {
-        continue;
+        const targetPath = itemRelativePath(targetSlot);
+        if (!targetPath) {
+          continue;
+        }
+        outItem = writeObjectPath(outItem, targetPath, value);
       }
-      outItem = writeObjectPath(outItem, targetPath, value);
-    }
 
-    return outItem;
-  });
+      return outItem;
+    }),
+  );
 }

package/src/domain/mapping/objectPathSafety.ts

@@ -0,0 +1,51 @@
+/**
+ * Object-path safety gate for field-remap read/write and template placeholders.
+ * Keeps prototype-mutating segments out of dotted path traversal.
+ */
+
+/** Identifier or dotted path: `city`, `a.b` (no expressions / eval). */
+const SAFE_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+const UNSAFE_OBJECT_PATH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+export class UnsafeObjectPathError extends Error {
+  readonly code = 'unsafe_object_path' as const;
+  readonly path: string;
+  readonly segment: string;
+
+  constructor(path: string, segment: string) {
+    super(`Object path "${path}" contains unsafe segment "${segment}".`);
+    this.name = 'UnsafeObjectPathError';
+    this.path = path;
+    this.segment = segment;
+  }
+}
+
+function objectPathParts(path: string): string[] {
+  return path
+    .split('.')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+function findUnsafeObjectPathSegment(parts: readonly string[]): string | undefined {
+  return parts.find((part) => UNSAFE_OBJECT_PATH_SEGMENTS.has(part));
+}
+
+/** Parse dotted path segments and reject unsafe segments when any parts exist. */
+export function requireObjectPathParts(path: string): string[] {
+  const parts = objectPathParts(path);
+  const unsafeSegment = findUnsafeObjectPathSegment(parts);
+  if (unsafeSegment) {
+    throw new UnsafeObjectPathError(path, unsafeSegment);
+  }
+  return parts;
+}
+
+export function isSafeObjectPath(path: string): boolean {
+  const trimmed = path.trim();
+  return (
+    SAFE_PATH_RE.test(trimmed) &&
+    findUnsafeObjectPathSegment(objectPathParts(trimmed)) === undefined
+  );
+}

package/src/domain/mapping/pathUtils.ts

@@ -3,8 +3,7 @@
  * Supports simple dotted paths (`name`, `meta.label`) on plain objects.
  */
 
-/** Identifier or dotted path: `city`, `a.b` (no expressions / eval). */
-const SAFE_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+import { isSafeObjectPath, requireObjectPathParts } from './objectPathSafety.js';
 
 /** Placeholder matcher: `{city}`, `{a.b}` — rejects expressions / spaces. */
 const TEMPLATE_PLACEHOLDER_RE = /\{([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\}/g;
@@ -13,10 +12,6 @@ export function isPlainObject(value: unknown): value is Record<string, unknown>
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-export function isSafeObjectPath(path: string): boolean {
-  return SAFE_PATH_RE.test(path.trim());
-}
-
 /**
  * Fill `{path}` placeholders from a plain object using safe dotted paths only.
  * Unknown / unsafe placeholders become empty strings. No JS eval.
@@ -45,10 +40,7 @@ export function applyStringTemplate(
 }
 
 export function readObjectPath(value: unknown, path: string): unknown {
-  const parts = path
-    .split('.')
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0);
+  const parts = requireObjectPathParts(path);
   if (parts.length === 0) {
     return value;
   }
@@ -72,10 +64,7 @@ export function writeObjectPath(
   path: string,
   value: unknown,
 ): Record<string, unknown> {
-  const parts = path
-    .split('.')
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0);
+  const parts = requireObjectPathParts(path);
   if (parts.length === 0) {
     return isPlainObject(root) ? { ...root } : {};
   }

package/src/domain/mapping/resolveMappedValue.ts

@@ -33,12 +33,12 @@ export function findSourceField(
  * Per-step options (`transformOptionSteps` / `itemTransformOptionSteps`) win when
  * present; otherwise shared `transformOptions` / `itemTransformOptions` apply to all steps.
  */
-export function resolveMappedValue(
+export async function resolveMappedValue(
   edge: MappingEdge,
   sourceValue: unknown,
   registry: ValueTransformRegistry,
   context: TransformContext = {},
-): unknown {
+): Promise<unknown> {
   let current = edge.itemSourcePath
     ? projectCollectionItems(sourceValue, edge.itemSourcePath)
     : sourceValue;
@@ -51,27 +51,27 @@ export function resolveMappedValue(
   );
 
   if (itemChain.length > 0 && Array.isArray(current)) {
-    current = current.map((item) =>
-      applyTransformChain(registry, itemChain, item, context, itemSteps),
+    current = await Promise.all(
+      current.map((item) => applyTransformChain(registry, itemChain, item, context, itemSteps)),
     );
   }
 
   const chain = edgeTransformIds(edge);
   if (chain.length === 0) {
     const identity = registry.get(BUILTIN_TRANSFORM_IDS.identity);
-    return identity ? identity.apply(current, context) : current;
+    return identity ? await identity.apply(current, context) : current;
   }
 
   const valueSteps = resolveOptionSteps(chain, edge.transformOptionSteps, edge.transformOptions);
   return applyTransformChain(registry, chain, current, context, valueSteps);
 }
 
-export function resolveEdgePreview(
+export async function resolveEdgePreview(
   edge: MappingEdge,
   sources: readonly SourceField[],
   registry: ValueTransformRegistry,
   context: TransformContext = {},
-): unknown {
+): Promise<unknown> {
   const field = findSourceField(sources, edge.sourceFieldId);
   const sample =
     context.sampleValue !== undefined ? context.sampleValue : (field?.sampleValue ?? context.now);
@@ -82,15 +82,17 @@ export function resolveEdgePreview(
 }
 
 /** Resolve every edge into `{ targetSlotId, value }` for live preview panels. */
-export function resolveAllEdgePreviews(
+export async function resolveAllEdgePreviews(
   edges: readonly MappingEdge[],
   sources: readonly SourceField[],
   registry: ValueTransformRegistry,
   context: TransformContext = {},
-): ReadonlyArray<{ edgeId: string; targetSlotId: string; value: unknown }> {
-  return edges.map((edge) => ({
-    edgeId: edge.id,
-    targetSlotId: edge.targetSlotId,
-    value: resolveEdgePreview(edge, sources, registry, context),
-  }));
+): Promise<ReadonlyArray<{ edgeId: string; targetSlotId: string; value: unknown }>> {
+  return Promise.all(
+    edges.map(async (edge) => ({
+      edgeId: edge.id,
+      targetSlotId: edge.targetSlotId,
+      value: await resolveEdgePreview(edge, sources, registry, context),
+    })),
+  );
 }

package/src/domain/shapes/convertToShape.ts

@@ -1,3 +1,4 @@
+import { throwIfAborted } from '../abort.js';
 import type { ConversionDefinition } from './conversionDefinition.js';
 import {
   mergeSourceShapes,
@@ -27,6 +28,12 @@ export interface ConvertToShapeInput {
   readonly inputs: Readonly<Record<string, unknown>>;
   readonly transforms: ValueTransformRegistry;
   readonly context?: TransformContext;
+  /**
+   * Optional cancellation. Merged into transform context as `signal` (wins over
+   * `context.signal` when both are set). Aborted conversions reject with `AbortError`
+   * and do not apply further edges.
+   */
+  readonly signal?: AbortSignal;
 }
 
 export interface ConvertToShapeSlotResult {
@@ -112,8 +119,17 @@ function readFieldValue(field: SourceField, inputs: Readonly<Record<string, unkn
  *
  * This is the host runtime entry point — not `sourceShape.convert(target, data)`.
  * Multiple source shapes are supported via `inputs[shapeId]`.
+ * Awaits Promise-returning host transforms (e.g. JSONata 2.x).
  */
-export function convertToShape(input: ConvertToShapeInput): ConvertToShapeResult {
+export async function convertToShape(input: ConvertToShapeInput): Promise<ConvertToShapeResult> {
+  const signal = input.signal ?? input.context?.signal;
+  const context: TransformContext = {
+    ...input.context,
+    ...(signal ? { signal } : {}),
+  };
+
+  throwIfAborted(signal);
+
   const sourceShapes: DataShape[] = [];
   for (const shapeId of input.conversion.sourceShapeIds) {
     const shape = resolveShape(input.shapes, shapeId);
@@ -141,6 +157,8 @@ export function convertToShape(input: ConvertToShapeInput): ConvertToShapeResult
   const slots: ConvertToShapeSlotResult[] = [];
 
   for (const edge of input.conversion.document.edges) {
+    throwIfAborted(signal);
+
     const sourceField = findSourceField(sources, edge.sourceFieldId);
     if (!sourceField) {
       continue;
@@ -155,21 +173,21 @@ export function convertToShape(input: ConvertToShapeInput): ConvertToShapeResult
     const sourceValue = readFieldValue(sourceField, input.inputs);
     const value =
       edge.itemEdges && edge.itemEdges.length > 0
-        ? convertArrayWithItemEdges({
+        ? await convertArrayWithItemEdges({
             items: sourceValue,
             itemEdges: edge.itemEdges,
             sources,
             targets,
             transforms: input.transforms,
-            context: input.context,
+            context,
           })
-        : resolveMappedValue(edge, sourceValue, input.transforms, {
-            ...input.context,
+        : await resolveMappedValue(edge, sourceValue, input.transforms, {
+            ...context,
             sampleValue: sourceValue,
             record: isPlainObject(sourceValue)
               ? sourceValue
-              : isPlainObject(input.context?.record)
-                ? input.context.record
+              : isPlainObject(context.record)
+                ? context.record
                 : undefined,
           });
 

package/src/domain/types.ts

@@ -134,6 +134,11 @@ export interface TransformContext {
    */
   readonly record?: Readonly<Record<string, unknown>>;
   readonly options?: Readonly<Record<string, unknown>>;
+  /**
+   * Optional cancellation signal. `applyTransformChain` / `convertToShape` check
+   * between steps and reject with `AbortError` when aborted.
+   */
+  readonly signal?: AbortSignal;
 }
 
 /** Declares a host-editable option consumed via `context.options[key]`. */
@@ -157,7 +162,11 @@ export interface ValueTransformDefinition {
   readonly category?: string;
   readonly inputTypes?: readonly FieldDataType[];
   readonly outputType?: FieldDataType;
-  readonly apply: (value: unknown, context: TransformContext) => unknown;
+  /**
+   * May return a Promise (e.g. host JSONata 2.x). Prefer `applyTransformChain` /
+   * `convertToShape`, which always await transform results.
+   */
+  readonly apply: (value: unknown, context: TransformContext) => unknown | PromiseLike<unknown>;
   /** Optional picker label that includes a live format sample. */
   readonly formatSampleLabel?: (context: TransformContext) => string;
   /**
@@ -177,6 +186,6 @@ export interface ValueTransformListFilter {
 export interface ValueTransformRegistry {
   list(filter?: ValueTransformListFilter): ValueTransformDefinition[];
   get(id: string): ValueTransformDefinition | undefined;
-  apply(id: string, value: unknown, context?: TransformContext): unknown;
+  apply(id: string, value: unknown, context?: TransformContext): unknown | PromiseLike<unknown>;
   register(definition: ValueTransformDefinition): void;
 }

package/src/index.ts

@@ -38,10 +38,10 @@ export {
   UnsupportedFieldRemapDocumentVersionError,
 } from './domain/document/fieldRemapDocument.js';
 
+export { isSafeObjectPath, UnsafeObjectPathError } from './domain/mapping/objectPathSafety.js';
 export {
   applyStringTemplate,
   isPlainObject,
-  isSafeObjectPath,
   listArrayItemProjectionOptions,
   projectCollectionItems,
   readObjectPath,
@@ -112,6 +112,8 @@ export type {
   ConvertToShapeSlotResult,
 } from './domain/shapes/convertToShape.js';
 
+export { createAbortError, isAbortError, throwIfAborted } from './domain/abort.js';
+
 export { sourceFieldsFromPlainObject } from './domain/ingest/sourceFieldsFromPlainObject.js';
 export type { SourceFieldsFromPlainObjectOptions } from './domain/ingest/sourceFieldsFromPlainObject.js';
 

package/src/registry/createValueTransformRegistry.ts

@@ -1,3 +1,4 @@
+import { throwIfAborted } from '../domain/abort.js';
 import { canonicalizeTransformId, MAX_TRANSFORM_CHAIN } from '../domain/constants.js';
 import type {
   FieldDataType,
@@ -44,17 +45,19 @@ export function createValueTransformRegistry(
 /**
  * Apply an ordered transform chain (empty = identity / unchanged).
  * Optional `optionSteps[i]` merges over `context.options` for step `i` only.
+ * Awaits Promise-returning host transforms (e.g. JSONata 2.x).
  */
-export function applyTransformChain(
+export async function applyTransformChain(
   registry: ValueTransformRegistry,
   transformIds: readonly string[],
   value: unknown,
   context: TransformContext = {},
   optionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[],
-): unknown {
+): Promise<unknown> {
   let current = value;
   const ids = transformIds.slice(0, MAX_TRANSFORM_CHAIN);
   for (let index = 0; index < ids.length; index += 1) {
+    throwIfAborted(context.signal);
     const stepOptions = optionSteps?.[index];
     const stepContext =
       stepOptions && Object.keys(stepOptions).length > 0
@@ -66,7 +69,7 @@ export function applyTransformChain(
             },
           }
         : context;
-    current = registry.apply(ids[index]!, current, stepContext);
+    current = await registry.apply(ids[index]!, current, stepContext);
   }
   return current;
 }