@workbench-kit/shell-react 0.0.2-prototype.0.2.6 → 0.0.2-prototype.0.2.8

package/src/field-remap/jsonata-transform.ts

@@ -0,0 +1,166 @@
+import jsonata from 'jsonata';
+import type { ValueTransformDefinition } from '@workbench-kit/field-remap';
+
+/** Host-registered JSONata expression transform (Stedi-style advanced mapping). */
+export const JSONATA_TRANSFORM_ID = 'expr:jsonata' as const;
+
+/** Default wall-clock budget for a single expression evaluation. */
+export const DEFAULT_JSONATA_TIMEOUT_MS = 2_000;
+
+/** Default maximum expression source length (characters). */
+export const DEFAULT_JSONATA_MAX_EXPRESSION_LENGTH = 4_096;
+
+export type JsonataTransformErrorPolicy = 'passthrough' | 'throw';
+
+export interface CreateJsonataValueTransformOptions {
+  /** Wall-clock timeout for `evaluate` (default {@link DEFAULT_JSONATA_TIMEOUT_MS}). */
+  readonly timeoutMs?: number;
+  /**
+   * Reject expressions longer than this many characters
+   * (default {@link DEFAULT_JSONATA_MAX_EXPRESSION_LENGTH}).
+   */
+  readonly maxExpressionLength?: number;
+  /**
+   * - `throw` (default): surface timeout / compile / evaluate failures to the host
+   * - `passthrough`: return the original value (legacy silent identity)
+   */
+  readonly onError?: JsonataTransformErrorPolicy;
+}
+
+export function createJsonataValueTransform(
+  options: CreateJsonataValueTransformOptions = {},
+): ValueTransformDefinition {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_JSONATA_TIMEOUT_MS;
+  const maxExpressionLength = options.maxExpressionLength ?? DEFAULT_JSONATA_MAX_EXPRESSION_LENGTH;
+  const onError = options.onError ?? 'throw';
+
+  return {
+    id: JSONATA_TRANSFORM_ID,
+    label: 'JSONata expression',
+    description:
+      'Evaluate a JSONata expression against the source value (host-registered; bounded).',
+    category: 'expression',
+    inputTypes: ['string', 'number', 'boolean', 'object', 'array', 'unknown'],
+    outputType: 'unknown',
+    optionFields: [
+      {
+        key: 'expression',
+        label: 'Expression',
+        kind: 'string',
+      },
+    ],
+    apply: async (value, context) => {
+      const expression =
+        typeof context.options?.expression === 'string' ? context.options.expression.trim() : '';
+      if (!expression) {
+        return value;
+      }
+
+      if (expression.length > maxExpressionLength) {
+        return handleJsonataError(
+          new Error(
+            `JSONata expression exceeds max length (${expression.length} > ${maxExpressionLength}).`,
+          ),
+          value,
+          onError,
+        );
+      }
+
+      try {
+        const compiled = jsonata(expression);
+        // jsonata@2.x evaluate returns a Promise (1.x was synchronous).
+        return await raceJsonataEvaluation(compiled.evaluate(value), {
+          timeoutMs,
+          signal: context.signal,
+        });
+      } catch (error) {
+        return handleJsonataError(error, value, onError);
+      }
+    },
+  };
+}
+
+/** Default bounded transform (`onError: 'throw'`, 2s timeout, 4k expression cap). */
+export const jsonataValueTransform: ValueTransformDefinition = createJsonataValueTransform();
+
+export class JsonataTransformTimeoutError extends Error {
+  override readonly name = 'JsonataTransformTimeoutError';
+
+  constructor(timeoutMs: number) {
+    super(`JSONata evaluation timed out after ${timeoutMs}ms.`);
+  }
+}
+
+/** Race a JSONata evaluation against timeout / AbortSignal (exported for unit tests). */
+export async function raceJsonataEvaluation<T>(
+  evaluation: PromiseLike<T>,
+  bounds: { readonly timeoutMs: number; readonly signal?: AbortSignal },
+): Promise<T> {
+  const { timeoutMs, signal } = bounds;
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' });
+  }
+
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return evaluation;
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new JsonataTransformTimeoutError(timeoutMs));
+    }, timeoutMs);
+
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(
+        signal?.reason instanceof Error
+          ? signal.reason
+          : Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' }),
+      );
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    Promise.resolve(evaluation).then(
+      (result) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(result);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}
+
+function handleJsonataError(
+  error: unknown,
+  value: unknown,
+  onError: JsonataTransformErrorPolicy,
+): unknown {
+  if (onError === 'passthrough') {
+    return value;
+  }
+  if (error instanceof Error) {
+    throw error;
+  }
+  throw new Error(String(error));
+}

package/src/{field-remap-panel.tsx → field-remap/panel.tsx}

@@ -1,175 +1,193 @@
-import { useMemo, useState, type JSX } from 'react';
-import {
-  convertToShape,
-  createBuiltinValueTransformRegistry,
-  defineConversion,
-  defineDataShape,
-  findParentChildMappingConflicts,
-  sourceFieldsFromPlainObject,
-  targetSlotsFromPlainObject,
-  withConversionEdges,
-  type MappingEdge,
-  type ValueTransformRegistry,
-} from '@workbench-kit/field-remap';
-
-import { FieldRemapFlowMapper } from './field-remap-flow.js';
-import {
-  getFieldRemapSample,
-  type FieldRemapSampleDefinition,
-  type FieldRemapSampleId,
-} from './field-remap-samples.js';
-import { jsonataValueTransform } from './jsonata-transform.js';
-import './field-remap-view.css';
-
-export interface FieldRemapPanelProps {
-  /** Catalog sample id, or a full sample definition. */
-  readonly sample?: FieldRemapSampleId | FieldRemapSampleDefinition | undefined;
-  /** Optional host-owned transform registry (defaults to builtins + JSONata). */
-  readonly transforms?: ValueTransformRegistry | undefined;
-  readonly className?: string | undefined;
-}
-
-function resolveSample(sample: FieldRemapPanelProps['sample']): FieldRemapSampleDefinition {
-  if (!sample) {
-    return getFieldRemapSample('nested-ab');
-  }
-  if (typeof sample === 'string') {
-    return getFieldRemapSample(sample);
-  }
-  return sample;
-}
-
-/**
- * Self-contained field-remap workbench panel:
- * XYFlow mapper + convertToShape preview for one A→B (or T_A→T_B) sample.
- *
- * Remount with `key={sampleId}` when switching catalog entries so edge state resets.
- */
-export function FieldRemapPanel({
-  sample: sampleProp,
-  transforms: transformsProp,
-  className,
-}: FieldRemapPanelProps): JSX.Element {
-  const sample = resolveSample(sampleProp);
-  const registry = useMemo(() => {
-    if (transformsProp) {
-      return transformsProp;
-    }
-    const next = createBuiltinValueTransformRegistry();
-    next.register(jsonataValueTransform);
-    return next;
-  }, [transformsProp]);
-
-  const [edges, setEdges] = useState<readonly MappingEdge[]>(() => [...sample.edges]);
-
-  const sourceFields = useMemo(
-    () => sourceFieldsFromPlainObject(sample.source, { idPrefix: sample.sourceIdPrefix }),
-    [sample],
-  );
-  const targetSlots = useMemo(
-    () => targetSlotsFromPlainObject(sample.targetShape, { idPrefix: sample.targetIdPrefix }),
-    [sample],
-  );
-
-  const shapes = useMemo(
-    () => [
-      defineDataShape({
-        id: sample.sourceIdPrefix,
-        label: sample.sourceLabel,
-        role: 'source',
-        fields: sourceFields,
-      }),
-      defineDataShape({
-        id: sample.targetIdPrefix,
-        label: sample.targetLabel,
-        role: 'target',
-        fields: targetSlots,
-      }),
-    ],
-    [sample, sourceFields, targetSlots],
-  );
-
-  const conflicts = useMemo(
-    () => findParentChildMappingConflicts(edges, sourceFields, targetSlots),
-    [edges, sourceFields, targetSlots],
-  );
-
-  const result = useMemo(() => {
-    const conversion = withConversionEdges(
-      defineConversion({
-        id: `${sample.sourceIdPrefix}→${sample.targetIdPrefix}`,
-        sourceShapeIds: [sample.sourceIdPrefix],
-        targetShapeId: sample.targetIdPrefix,
-        edges: [...sample.edges],
-      }),
-      edges,
-    );
-    try {
-      return convertToShape({
-        conversion,
-        shapes,
-        inputs: { [sample.sourceIdPrefix]: sample.source },
-        transforms: registry,
-      });
-    } catch (error) {
-      return {
-        output: {} as Record<string, unknown>,
-        error: error instanceof Error ? error.message : String(error),
-      };
-    }
-  }, [edges, registry, sample, shapes]);
-
-  return (
-    <div
-      className={['workbench-field-remap-demo', className].filter(Boolean).join(' ')}
-      data-testid="field-remap-demo"
-      data-sample-id={sample.id}
-    >
-      <header className="workbench-field-remap-demo__header">
-        <h2 className="workbench-field-remap-demo__title">{sample.title}</h2>
-        <p className="workbench-field-remap-demo__intro">{sample.description}</p>
-      </header>
-
-      <FieldRemapFlowMapper
-        sources={sourceFields}
-        targets={targetSlots}
-        edges={edges}
-        transforms={registry}
-        onEdgesChange={setEdges}
-        sourceTitle={sample.sourceLabel}
-        targetTitle={sample.targetLabel}
-      />
-
-      {conflicts.length > 0 ? (
-        <p
-          className="workbench-field-remap-demo__warn"
-          role="status"
-          data-testid="field-remap-conflicts"
-        >
-          Warning: parent and child fields are both mapped (
-          {conflicts.map((item) => `${item.parentId} / ${item.childId}`).join('; ')}). Prefer one
-          level.
-        </p>
-      ) : null}
-
-      {'error' in result && result.error ? (
-        <p className="workbench-field-remap-demo__error" role="alert">
-          {result.error}
-        </p>
-      ) : null}
-
-      <div className="workbench-field-remap-demo__panes">
-        <section className="workbench-field-remap-demo__pane" aria-labelledby="field-remap-source">
-          <h3 id="field-remap-source">{sample.sourceLabel}</h3>
-          <pre data-testid="field-remap-input">{JSON.stringify(sample.source, null, 2)}</pre>
-        </section>
-        <section className="workbench-field-remap-demo__pane" aria-labelledby="field-remap-target">
-          <h3 id="field-remap-target">{sample.targetLabel}</h3>
-          <pre data-testid="field-remap-result">
-            {JSON.stringify('output' in result ? result.output : {}, null, 2)}
-          </pre>
-        </section>
-      </div>
-    </div>
-  );
-}
+import { useEffect, useMemo, useState, type JSX } from 'react';
+import {
+  convertToShape,
+  createBuiltinValueTransformRegistry,
+  defineConversion,
+  defineDataShape,
+  findParentChildMappingConflicts,
+  sourceFieldsFromPlainObject,
+  targetSlotsFromPlainObject,
+  withConversionEdges,
+  type MappingEdge,
+  type ValueTransformRegistry,
+} from '@workbench-kit/field-remap';
+
+import { FieldRemapFlowMapper } from './flow.js';
+import {
+  getFieldRemapSample,
+  type FieldRemapSampleDefinition,
+  type FieldRemapSampleId,
+} from './samples.js';
+import { jsonataValueTransform } from './jsonata-transform.js';
+import './view.css';
+
+export interface FieldRemapPanelProps {
+  /** Catalog sample id, or a full sample definition. */
+  readonly sample?: FieldRemapSampleId | FieldRemapSampleDefinition | undefined;
+  /** Optional host-owned transform registry (defaults to builtins + JSONata). */
+  readonly transforms?: ValueTransformRegistry | undefined;
+  readonly className?: string | undefined;
+}
+
+type FieldRemapPreviewResult = {
+  readonly output: Record<string, unknown>;
+  readonly error?: string;
+};
+
+function resolveSample(sample: FieldRemapPanelProps['sample']): FieldRemapSampleDefinition {
+  if (!sample) {
+    return getFieldRemapSample('nested-ab');
+  }
+  if (typeof sample === 'string') {
+    return getFieldRemapSample(sample);
+  }
+  return sample;
+}
+
+/**
+ * Self-contained field-remap workbench panel:
+ * XYFlow mapper + convertToShape preview for one A→B (or T_A→T_B) sample.
+ *
+ * Remount with `key={sampleId}` when switching catalog entries so edge state resets.
+ */
+export function FieldRemapPanel({
+  sample: sampleProp,
+  transforms: transformsProp,
+  className,
+}: FieldRemapPanelProps): JSX.Element {
+  const sample = resolveSample(sampleProp);
+  const registry = useMemo(() => {
+    if (transformsProp) {
+      return transformsProp;
+    }
+    const next = createBuiltinValueTransformRegistry();
+    next.register(jsonataValueTransform);
+    return next;
+  }, [transformsProp]);
+
+  const [edges, setEdges] = useState<readonly MappingEdge[]>(() => [...sample.edges]);
+  const [result, setResult] = useState<FieldRemapPreviewResult>({ output: {} });
+
+  const sourceFields = useMemo(
+    () => sourceFieldsFromPlainObject(sample.source, { idPrefix: sample.sourceIdPrefix }),
+    [sample],
+  );
+  const targetSlots = useMemo(
+    () => targetSlotsFromPlainObject(sample.targetShape, { idPrefix: sample.targetIdPrefix }),
+    [sample],
+  );
+
+  const shapes = useMemo(
+    () => [
+      defineDataShape({
+        id: sample.sourceIdPrefix,
+        label: sample.sourceLabel,
+        role: 'source',
+        fields: sourceFields,
+      }),
+      defineDataShape({
+        id: sample.targetIdPrefix,
+        label: sample.targetLabel,
+        role: 'target',
+        fields: targetSlots,
+      }),
+    ],
+    [sample, sourceFields, targetSlots],
+  );
+
+  const conflicts = useMemo(
+    () => findParentChildMappingConflicts(edges, sourceFields, targetSlots),
+    [edges, sourceFields, targetSlots],
+  );
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const conversion = withConversionEdges(
+      defineConversion({
+        id: `${sample.sourceIdPrefix}→${sample.targetIdPrefix}`,
+        sourceShapeIds: [sample.sourceIdPrefix],
+        targetShapeId: sample.targetIdPrefix,
+        edges: [...sample.edges],
+      }),
+      edges,
+    );
+
+    void convertToShape({
+      conversion,
+      shapes,
+      inputs: { [sample.sourceIdPrefix]: sample.source },
+      transforms: registry,
+      signal: controller.signal,
+    })
+      .then((next) => {
+        if (!controller.signal.aborted) {
+          setResult({ output: next.output });
+        }
+      })
+      .catch((error: unknown) => {
+        if (controller.signal.aborted) {
+          return;
+        }
+        setResult({
+          output: {},
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+
+    return () => {
+      controller.abort();
+    };
+  }, [edges, registry, sample, shapes]);
+
+  return (
+    <div
+      className={['workbench-field-remap-demo', className].filter(Boolean).join(' ')}
+      data-testid="field-remap-demo"
+      data-sample-id={sample.id}
+    >
+      <header className="workbench-field-remap-demo__header">
+        <h2 className="workbench-field-remap-demo__title">{sample.title}</h2>
+        <p className="workbench-field-remap-demo__intro">{sample.description}</p>
+      </header>
+
+      <FieldRemapFlowMapper
+        sources={sourceFields}
+        targets={targetSlots}
+        edges={edges}
+        transforms={registry}
+        onEdgesChange={setEdges}
+        sourceTitle={sample.sourceLabel}
+        targetTitle={sample.targetLabel}
+      />
+
+      {conflicts.length > 0 ? (
+        <p
+          className="workbench-field-remap-demo__warn"
+          role="status"
+          data-testid="field-remap-conflicts"
+        >
+          Warning: parent and child fields are both mapped (
+          {conflicts.map((item) => `${item.parentId} / ${item.childId}`).join('; ')}). Prefer one
+          level.
+        </p>
+      ) : null}
+
+      {result.error ? (
+        <p className="workbench-field-remap-demo__error" role="alert">
+          {result.error}
+        </p>
+      ) : null}
+
+      <div className="workbench-field-remap-demo__panes">
+        <section className="workbench-field-remap-demo__pane" aria-labelledby="field-remap-source">
+          <h3 id="field-remap-source">{sample.sourceLabel}</h3>
+          <pre data-testid="field-remap-input">{JSON.stringify(sample.source, null, 2)}</pre>
+        </section>
+        <section className="workbench-field-remap-demo__pane" aria-labelledby="field-remap-target">
+          <h3 id="field-remap-target">{sample.targetLabel}</h3>
+          <pre data-testid="field-remap-result">{JSON.stringify(result.output, null, 2)}</pre>
+        </section>
+      </div>
+    </div>
+  );
+}