@workbench-kit/field-remap 0.0.1-prototype.0

package/src/domain/mapping/dateFormat.ts

@@ -0,0 +1,102 @@
+export type DateParts = { readonly year: string; readonly month: string; readonly day: string };
+
+const FORMAT_TOKEN_RE = /YYYY|MM|DD/g;
+
+/** Parse a date string with a simple token format (YYYY/MM/DD only). */
+export function parseDateParts(value: string, inputFormat: string): DateParts | undefined {
+  const format = inputFormat.trim();
+  const raw = value.trim();
+  if (!format || !raw) {
+    return undefined;
+  }
+
+  let year = '';
+  let month = '';
+  let day = '';
+  let cursor = 0;
+
+  for (let i = 0; i < format.length;) {
+    if (format.startsWith('YYYY', i)) {
+      year = raw.slice(cursor, cursor + 4);
+      if (!/^\d{4}$/.test(year)) {
+        return undefined;
+      }
+      cursor += 4;
+      i += 4;
+      continue;
+    }
+    if (format.startsWith('MM', i)) {
+      month = raw.slice(cursor, cursor + 2);
+      if (!/^\d{2}$/.test(month)) {
+        return undefined;
+      }
+      cursor += 2;
+      i += 2;
+      continue;
+    }
+    if (format.startsWith('DD', i)) {
+      day = raw.slice(cursor, cursor + 2);
+      if (!/^\d{2}$/.test(day)) {
+        return undefined;
+      }
+      cursor += 2;
+      i += 2;
+      continue;
+    }
+    if (raw[cursor] !== format[i]) {
+      return undefined;
+    }
+    cursor += 1;
+    i += 1;
+  }
+
+  if (cursor !== raw.length || !year || !month || !day) {
+    return undefined;
+  }
+  return { year, month, day };
+}
+
+export function formatDateParts(parts: DateParts, outputFormat: string): string {
+  return outputFormat.replace(FORMAT_TOKEN_RE, (token) => {
+    if (token === 'YYYY') {
+      return parts.year;
+    }
+    if (token === 'MM') {
+      return parts.month;
+    }
+    return parts.day;
+  });
+}
+
+export function reformatDateString(
+  value: string,
+  inputFormat: string,
+  outputFormat: string,
+): string | undefined {
+  const parts = parseDateParts(value, inputFormat);
+  if (!parts) {
+    return undefined;
+  }
+  return formatDateParts(parts, outputFormat);
+}
+
+/** Split `YYYY-MM-DDTHH:mm:ss` / `YYYY-MM-DD HH:mm:ss` / date-only. */
+export function splitDateTimeString(value: string): { date: string; time: string } | undefined {
+  const raw = value.trim();
+  if (!raw) {
+    return undefined;
+  }
+  const tIndex = raw.indexOf('T');
+  const spaceIndex = raw.indexOf(' ');
+  const splitAt = tIndex >= 0 ? tIndex : spaceIndex;
+  if (splitAt < 0) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(raw) || /^\d{8}$/.test(raw)) {
+      return { date: raw, time: '' };
+    }
+    return undefined;
+  }
+  return {
+    date: raw.slice(0, splitAt),
+    time: raw.slice(splitAt + 1),
+  };
+}

package/src/domain/mapping/mappingConflicts.ts

@@ -0,0 +1,90 @@
+import type { MappingEdge, SourceField, TargetSlot } from '../types.js';
+import { flattenSourceFields, flattenTargetSlots } from './treeUtils.js';
+
+export interface MappingConflict {
+  readonly kind: 'parent-child-source' | 'parent-child-target';
+  readonly parentId: string;
+  readonly childId: string;
+  readonly parentEdgeId: string;
+  readonly childEdgeId: string;
+}
+
+function isAncestorId(ancestorId: string, descendantId: string): boolean {
+  return (
+    descendantId.startsWith(`${ancestorId}.`) || descendantId.startsWith(`${ancestorId}.item.`)
+  );
+}
+
+/**
+ * Detect edges that map both a parent object/array and one of its descendants.
+ * Hosts should warn — writing both usually overwrites or double-defines output.
+ */
+export function findParentChildMappingConflicts(
+  edges: readonly MappingEdge[],
+  sources: readonly SourceField[],
+  targets: readonly TargetSlot[],
+): MappingConflict[] {
+  const sourceIds = new Set(flattenSourceFields(sources).map((field) => field.id));
+  const targetIds = new Set(flattenTargetSlots(targets).map((slot) => slot.id));
+  const conflicts: MappingConflict[] = [];
+
+  for (let i = 0; i < edges.length; i += 1) {
+    const a = edges[i]!;
+    for (let j = i + 1; j < edges.length; j += 1) {
+      const b = edges[j]!;
+      if (
+        sourceIds.has(a.sourceFieldId) &&
+        sourceIds.has(b.sourceFieldId) &&
+        isAncestorId(a.sourceFieldId, b.sourceFieldId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-source',
+          parentId: a.sourceFieldId,
+          childId: b.sourceFieldId,
+          parentEdgeId: a.id,
+          childEdgeId: b.id,
+        });
+      } else if (
+        sourceIds.has(a.sourceFieldId) &&
+        sourceIds.has(b.sourceFieldId) &&
+        isAncestorId(b.sourceFieldId, a.sourceFieldId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-source',
+          parentId: b.sourceFieldId,
+          childId: a.sourceFieldId,
+          parentEdgeId: b.id,
+          childEdgeId: a.id,
+        });
+      }
+
+      if (
+        targetIds.has(a.targetSlotId) &&
+        targetIds.has(b.targetSlotId) &&
+        isAncestorId(a.targetSlotId, b.targetSlotId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-target',
+          parentId: a.targetSlotId,
+          childId: b.targetSlotId,
+          parentEdgeId: a.id,
+          childEdgeId: b.id,
+        });
+      } else if (
+        targetIds.has(a.targetSlotId) &&
+        targetIds.has(b.targetSlotId) &&
+        isAncestorId(b.targetSlotId, a.targetSlotId)
+      ) {
+        conflicts.push({
+          kind: 'parent-child-target',
+          parentId: b.targetSlotId,
+          childId: a.targetSlotId,
+          parentEdgeId: b.id,
+          childEdgeId: a.id,
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}

package/src/domain/mapping/pathUtils.ts

@@ -0,0 +1,156 @@
+/**
+ * Lightweight path helpers for collection item projection and safe templates.
+ * 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_]*)*$/;
+
+/** 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;
+
+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.
+ */
+export function applyStringTemplate(
+  template: string,
+  record: Readonly<Record<string, unknown>> | null | undefined,
+): string {
+  return template.replace(TEMPLATE_PLACEHOLDER_RE, (_match, path: string) => {
+    if (!record || !isSafeObjectPath(path)) {
+      return '';
+    }
+    const resolved = readObjectPath(record, path);
+    if (resolved === null || resolved === undefined) {
+      return '';
+    }
+    if (
+      typeof resolved === 'string' ||
+      typeof resolved === 'number' ||
+      typeof resolved === 'boolean'
+    ) {
+      return String(resolved);
+    }
+    return '';
+  });
+}
+
+export function readObjectPath(value: unknown, path: string): unknown {
+  const parts = path
+    .split('.')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return value;
+  }
+
+  let current: unknown = value;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+/**
+ * Write `value` at a dotted path, creating plain-object parents as needed.
+ * Returns a new root object (does not mutate `root`).
+ */
+export function writeObjectPath(
+  root: Readonly<Record<string, unknown>> | null | undefined,
+  path: string,
+  value: unknown,
+): Record<string, unknown> {
+  const parts = path
+    .split('.')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return isPlainObject(root) ? { ...root } : {};
+  }
+
+  const result: Record<string, unknown> = isPlainObject(root) ? { ...root } : {};
+  let cursor: Record<string, unknown> = result;
+
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    const part = parts[index]!;
+    const existing = cursor[part];
+    const nextChild: Record<string, unknown> = isPlainObject(existing) ? { ...existing } : {};
+    cursor[part] = nextChild;
+    cursor = nextChild;
+  }
+
+  cursor[parts[parts.length - 1]!] = value;
+  return result;
+}
+
+/**
+ * Project each array element through `itemSourcePath`.
+ * Non-arrays are returned unchanged (callers decide whether that is valid).
+ */
+export function projectCollectionItems(value: unknown, itemSourcePath: string): unknown {
+  const path = itemSourcePath.trim();
+  if (!path || !Array.isArray(value)) {
+    return value;
+  }
+  return value.map((item) => readObjectPath(item, path));
+}
+
+export interface ArrayItemProjectionOption {
+  readonly path: string;
+  readonly label: string;
+  readonly dataType?: string;
+}
+
+/**
+ * Projection candidates for an array source:
+ * 1) explicit item-schema `children` (path / label)
+ * 2) else keys of the first object in `sampleValue`
+ */
+export function listArrayItemProjectionOptions(source: {
+  readonly children?: readonly {
+    readonly label: string;
+    readonly path?: string;
+    readonly dataType?: string;
+  }[];
+  readonly sampleValue?: unknown;
+}): ArrayItemProjectionOption[] {
+  if (source.children?.length) {
+    const options: ArrayItemProjectionOption[] = [];
+    for (const child of source.children) {
+      const path = (child.path ?? child.label).trim();
+      if (!path) {
+        continue;
+      }
+      options.push({
+        path,
+        label: child.label,
+        dataType: child.dataType,
+      });
+    }
+    return options;
+  }
+
+  if (!Array.isArray(source.sampleValue) || source.sampleValue.length === 0) {
+    return [];
+  }
+  const first = source.sampleValue[0];
+  if (first === null || first === undefined || typeof first !== 'object' || Array.isArray(first)) {
+    return [];
+  }
+  return Object.keys(first as Record<string, unknown>).map((key) => ({
+    path: key,
+    label: key,
+  }));
+}

package/src/domain/mapping/resolveMappedValue.ts

@@ -0,0 +1,96 @@
+import type {
+  MappingEdge,
+  SourceField,
+  TransformContext,
+  ValueTransformRegistry,
+} from '../types.js';
+import { edgeItemTransformIds, edgeTransformIds } from '../document/mappingEdge.js';
+import { projectCollectionItems } from './pathUtils.js';
+import { applyTransformChain } from '../../registry/createValueTransformRegistry.js';
+import { BUILTIN_TRANSFORM_IDS } from '../../registry/builtinTransforms.js';
+import { resolveOptionSteps } from './transformOptions.js';
+import { flattenSourceFields } from './treeUtils.js';
+
+export { findTargetSlot, flattenSourceFields, flattenTargetSlots } from './treeUtils.js';
+
+export { projectCollectionItems, readObjectPath } from './pathUtils.js';
+
+export function findSourceField(
+  fields: readonly SourceField[],
+  fieldId: string,
+): SourceField | undefined {
+  return flattenSourceFields(fields).find((field) => field.id === fieldId);
+}
+
+/**
+ * Resolve an edge against a live / sample source value.
+ *
+ * Apply order:
+ * 1. Optional `itemSourcePath` projection (array of objects → projected array)
+ * 2. Optional `itemTransformIds` per element (when the value is still an array)
+ * 3. `transformIds` / legacy `transformId` on the whole value (including array reduces)
+ *
+ * Per-step options (`transformOptionSteps` / `itemTransformOptionSteps`) win when
+ * present; otherwise shared `transformOptions` / `itemTransformOptions` apply to all steps.
+ */
+export function resolveMappedValue(
+  edge: MappingEdge,
+  sourceValue: unknown,
+  registry: ValueTransformRegistry,
+  context: TransformContext = {},
+): unknown {
+  let current = edge.itemSourcePath
+    ? projectCollectionItems(sourceValue, edge.itemSourcePath)
+    : sourceValue;
+
+  const itemChain = edgeItemTransformIds(edge);
+  const itemSteps = resolveOptionSteps(
+    itemChain,
+    edge.itemTransformOptionSteps,
+    edge.itemTransformOptions,
+  );
+
+  if (itemChain.length > 0 && Array.isArray(current)) {
+    current = 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;
+  }
+
+  const valueSteps = resolveOptionSteps(chain, edge.transformOptionSteps, edge.transformOptions);
+  return applyTransformChain(registry, chain, current, context, valueSteps);
+}
+
+export function resolveEdgePreview(
+  edge: MappingEdge,
+  sources: readonly SourceField[],
+  registry: ValueTransformRegistry,
+  context: TransformContext = {},
+): unknown {
+  const field = findSourceField(sources, edge.sourceFieldId);
+  const sample =
+    context.sampleValue !== undefined ? context.sampleValue : (field?.sampleValue ?? context.now);
+  return resolveMappedValue(edge, sample, registry, {
+    ...context,
+    sampleValue: sample,
+  });
+}
+
+/** Resolve every edge into `{ targetSlotId, value }` for live preview panels. */
+export 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),
+  }));
+}

package/src/domain/mapping/transformOptions.ts

@@ -0,0 +1,184 @@
+import type { TransformContext, TransformOptionField, ValueTransformRegistry } from '../types.js';
+
+/** Merge edge-local options over host `context.options` (edge wins). */
+export function contextWithEdgeOptions(
+  context: TransformContext,
+  edgeOptions: Readonly<Record<string, unknown>> | undefined,
+): TransformContext {
+  if (!edgeOptions || Object.keys(edgeOptions).length === 0) {
+    return context;
+  }
+  return {
+    ...context,
+    options: {
+      ...context.options,
+      ...edgeOptions,
+    },
+  };
+}
+
+/** Collect unique `optionFields` declared by transforms in a chain (later ids win per key). */
+export function collectOptionFields(
+  registry: ValueTransformRegistry,
+  transformIds: readonly string[],
+): TransformOptionField[] {
+  const byKey = new Map<string, TransformOptionField>();
+  for (const id of transformIds) {
+    const fields = registry.get(id)?.optionFields;
+    if (!fields) {
+      continue;
+    }
+    for (const field of fields) {
+      byKey.set(field.key, field);
+    }
+  }
+  return [...byKey.values()];
+}
+
+/** Option fields for a single chain step. */
+export function optionFieldsForStep(
+  registry: ValueTransformRegistry,
+  transformId: string | undefined,
+): TransformOptionField[] {
+  if (!transformId) {
+    return [];
+  }
+  return [...(registry.get(transformId)?.optionFields ?? [])];
+}
+
+/** Drop empty / undefined option bags when persisting edges. */
+export function sanitizeOptionRecord(
+  options: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> | undefined {
+  if (!options) {
+    return undefined;
+  }
+  const next: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined) {
+      continue;
+    }
+    next[key] = value;
+  }
+  return Object.keys(next).length > 0 ? next : undefined;
+}
+
+export function patchOptionRecord(
+  previous: Readonly<Record<string, unknown>> | undefined,
+  key: string,
+  value: unknown,
+): Readonly<Record<string, unknown>> | undefined {
+  return sanitizeOptionRecord({
+    ...previous,
+    [key]: value,
+  });
+}
+
+/**
+ * Align / sanitize per-step option bags to `length`.
+ * Returns `undefined` when every step is empty.
+ */
+export function sanitizeOptionSteps(
+  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
+  length: number,
+): readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined {
+  if (length <= 0) {
+    return undefined;
+  }
+  const next: (Readonly<Record<string, unknown>> | undefined)[] = [];
+  let any = false;
+  for (let index = 0; index < length; index += 1) {
+    const sanitized = sanitizeOptionRecord(steps?.[index]);
+    next.push(sanitized);
+    if (sanitized) {
+      any = true;
+    }
+  }
+  return any ? next : undefined;
+}
+
+/**
+ * Resolve per-step options for a transform chain.
+ * Prefers `steps`; otherwise expands shared `transformOptions` to every step (apply-to-all).
+ */
+export function resolveOptionSteps(
+  transformIds: readonly string[],
+  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
+  shared: Readonly<Record<string, unknown>> | undefined,
+): (Readonly<Record<string, unknown>> | undefined)[] {
+  const length = transformIds.length;
+  if (length === 0) {
+    return [];
+  }
+  if (steps && steps.length > 0) {
+    return Array.from({ length }, (_, index) => sanitizeOptionRecord(steps[index]));
+  }
+  const bag = sanitizeOptionRecord(shared);
+  if (!bag) {
+    return Array.from({ length }, () => undefined);
+  }
+  return Array.from({ length }, () => bag);
+}
+
+/** Back-compat summary: first non-empty step bag (else undefined). */
+export function sharedOptionsFromSteps(
+  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
+): Readonly<Record<string, unknown>> | undefined {
+  if (!steps) {
+    return undefined;
+  }
+  for (const step of steps) {
+    const sanitized = sanitizeOptionRecord(step);
+    if (sanitized) {
+      return sanitized;
+    }
+  }
+  return undefined;
+}
+
+/** Merge all step bags (later steps win) — useful for live format-sample chips. */
+export function mergeOptionSteps(
+  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
+): Readonly<Record<string, unknown>> | undefined {
+  if (!steps || steps.length === 0) {
+    return undefined;
+  }
+  const merged: Record<string, unknown> = {};
+  for (const step of steps) {
+    if (!step) {
+      continue;
+    }
+    Object.assign(merged, step);
+  }
+  return sanitizeOptionRecord(merged);
+}
+
+export function patchOptionStep(
+  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
+  length: number,
+  index: number,
+  key: string,
+  value: unknown,
+  sharedFallback?: Readonly<Record<string, unknown>>,
+): readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined {
+  const base = resolveOptionSteps(
+    Array.from({ length }, () => ''),
+    steps,
+    sharedFallback,
+  );
+  const next = base.map((step, stepIndex) =>
+    stepIndex === index ? patchOptionRecord(step, key, value) : step,
+  );
+  return sanitizeOptionSteps(next, length);
+}
+
+export function resizeOptionSteps(
+  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
+  length: number,
+): readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined {
+  if (length <= 0) {
+    return undefined;
+  }
+  const next = Array.from({ length }, (_, index) => sanitizeOptionRecord(steps?.[index]));
+  return sanitizeOptionSteps(next, length);
+}

package/src/domain/mapping/treeUtils.ts

@@ -0,0 +1,32 @@
+import type { SourceField, TargetSlot } from '../types.js';
+
+/** Flatten nested source fields depth-first. */
+export function flattenSourceFields(fields: readonly SourceField[]): SourceField[] {
+  const out: SourceField[] = [];
+  for (const field of fields) {
+    out.push(field);
+    if (field.children?.length) {
+      out.push(...flattenSourceFields(field.children));
+    }
+  }
+  return out;
+}
+
+/** Flatten nested target slots depth-first. */
+export function flattenTargetSlots(slots: readonly TargetSlot[]): TargetSlot[] {
+  const out: TargetSlot[] = [];
+  for (const slot of slots) {
+    out.push(slot);
+    if (slot.children?.length) {
+      out.push(...flattenTargetSlots(slot.children));
+    }
+  }
+  return out;
+}
+
+export function findTargetSlot(
+  slots: readonly TargetSlot[],
+  slotId: string,
+): TargetSlot | undefined {
+  return flattenTargetSlots(slots).find((slot) => slot.id === slotId);
+}