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

package/src/index.ts

@@ -0,0 +1,137 @@
+export type {
+  FieldDataType,
+  MappingEdge,
+  FieldRemapDocument,
+  SourceField,
+  TargetSlot,
+  TransformContext,
+  TransformOptionField,
+  ValueTransformDefinition,
+  ValueTransformListFilter,
+  ValueTransformRegistry,
+} from './domain/types.js';
+
+export {
+  canonicalizeTransformId,
+  IDENTITY_TRANSFORM_ID,
+  MAX_TRANSFORM_CHAIN,
+  TRANSFORM_ID_ALIASES,
+} from './domain/constants.js';
+
+export {
+  createMappingEdge,
+  edgeItemTransformIds,
+  edgeTransformIds,
+  normalizeMappingEdge,
+  normalizeMappingEdges,
+} from './domain/document/mappingEdge.js';
+
+export {
+  createFieldRemapDocument,
+  deserializeFieldRemapDocument,
+  InvalidFieldRemapDocumentError,
+  migrateFieldRemapDocument,
+  normalizeFieldRemapDocument,
+  parseFieldRemapDocument,
+  FIELD_REMAP_DOCUMENT_VERSION,
+  serializeFieldRemapDocument,
+  UnsupportedFieldRemapDocumentVersionError,
+} from './domain/document/fieldRemapDocument.js';
+
+export {
+  applyStringTemplate,
+  isPlainObject,
+  isSafeObjectPath,
+  listArrayItemProjectionOptions,
+  projectCollectionItems,
+  readObjectPath,
+  writeObjectPath,
+} from './domain/mapping/pathUtils.js';
+export type { ArrayItemProjectionOption } from './domain/mapping/pathUtils.js';
+
+export {
+  formatDateParts,
+  parseDateParts,
+  reformatDateString,
+  splitDateTimeString,
+} from './domain/mapping/dateFormat.js';
+export type { DateParts } from './domain/mapping/dateFormat.js';
+
+export { convertArrayWithItemEdges } from './domain/mapping/convertItemEdges.js';
+export { findParentChildMappingConflicts } from './domain/mapping/mappingConflicts.js';
+export type { MappingConflict } from './domain/mapping/mappingConflicts.js';
+
+export {
+  collectOptionFields,
+  contextWithEdgeOptions,
+  mergeOptionSteps,
+  optionFieldsForStep,
+  patchOptionRecord,
+  patchOptionStep,
+  resolveOptionSteps,
+  resizeOptionSteps,
+  sanitizeOptionRecord,
+  sanitizeOptionSteps,
+  sharedOptionsFromSteps,
+} from './domain/mapping/transformOptions.js';
+
+export {
+  findSourceField,
+  findTargetSlot,
+  flattenSourceFields,
+  flattenTargetSlots,
+  resolveAllEdgePreviews,
+  resolveEdgePreview,
+  resolveMappedValue,
+} from './domain/mapping/resolveMappedValue.js';
+
+export {
+  attachShapeIdToSourceFields,
+  createDataShapeRegistry,
+  defineDataShape,
+  mergeSourceShapes,
+  targetSlotsFromShape,
+} from './domain/shapes/dataShape.js';
+export type { DataShape, DataShapeRegistry, DataShapeRole } from './domain/shapes/dataShape.js';
+
+export {
+  createConversionRegistry,
+  defineConversion,
+  withConversionEdges,
+} from './domain/shapes/conversionDefinition.js';
+export type {
+  ConversionDefinition,
+  ConversionRegistry,
+  DefineConversionInput,
+} from './domain/shapes/conversionDefinition.js';
+
+export { convertToShape } from './domain/shapes/convertToShape.js';
+export type {
+  ConvertToShapeInput,
+  ConvertToShapeResult,
+  ConvertToShapeSlotResult,
+} from './domain/shapes/convertToShape.js';
+
+export { sourceFieldsFromPlainObject } from './domain/ingest/sourceFieldsFromPlainObject.js';
+export type { SourceFieldsFromPlainObjectOptions } from './domain/ingest/sourceFieldsFromPlainObject.js';
+
+export { targetSlotsFromPlainObject } from './domain/ingest/targetSlotsFromPlainObject.js';
+export type { TargetSlotsFromPlainObjectOptions } from './domain/ingest/targetSlotsFromPlainObject.js';
+
+export {
+  applyTransformChain,
+  createValueTransformRegistry,
+  isTransformChainCompatible,
+  isTransformCompatible,
+} from './registry/createValueTransformRegistry.js';
+
+export {
+  ARRAY_REDUCE_TRANSFORM_IDS,
+  BUILTIN_TRANSFORM_IDS,
+  DATE_STYLE_TRANSFORM_IDS,
+  STRING_FORMAT_TRANSFORM_IDS,
+  TIME_FORMAT_TRANSFORM_IDS,
+  builtinValueTransforms,
+  createBuiltinValueTransformRegistry,
+} from './registry/builtinTransforms.js';
+export type { CreateBuiltinValueTransformRegistryOptions } from './registry/builtinTransforms.js';

package/src/registry/builtinTransforms.ts

@@ -0,0 +1,243 @@
+import { reformatDateString, splitDateTimeString } from '../domain/mapping/dateFormat.js';
+import { applyStringTemplate, isPlainObject } from '../domain/mapping/pathUtils.js';
+import type { ValueTransformDefinition } from '../domain/types.js';
+import { createValueTransformRegistry } from './createValueTransformRegistry.js';
+
+export const BUILTIN_TRANSFORM_IDS = {
+  identity: 'identity',
+  arrayFirst: 'array:first',
+  arrayJoin: 'array:join',
+  stringTrim: 'string:trim',
+  stringUpper: 'string:upper',
+  stringLower: 'string:lower',
+  stringPrefix: 'string:prefix',
+  stringSuffix: 'string:suffix',
+  stringTemplate: 'string:template',
+  dateReformat: 'date:reformat',
+  datetimeCombine: 'datetime:combine',
+  datetimeDate: 'datetime:date',
+  datetimeTime: 'datetime:time',
+} as const;
+
+export const ARRAY_REDUCE_TRANSFORM_IDS = [
+  BUILTIN_TRANSFORM_IDS.arrayFirst,
+  BUILTIN_TRANSFORM_IDS.arrayJoin,
+] as const;
+
+export const STRING_FORMAT_TRANSFORM_IDS = [
+  BUILTIN_TRANSFORM_IDS.stringTrim,
+  BUILTIN_TRANSFORM_IDS.stringUpper,
+  BUILTIN_TRANSFORM_IDS.stringLower,
+  BUILTIN_TRANSFORM_IDS.stringPrefix,
+  BUILTIN_TRANSFORM_IDS.stringSuffix,
+] as const;
+
+function asString(value: unknown): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  return typeof value === 'string' ? value : String(value);
+}
+
+export const builtinValueTransforms: readonly ValueTransformDefinition[] = [
+  {
+    id: BUILTIN_TRANSFORM_IDS.identity,
+    label: 'Pass-through',
+    description: 'Return the source value unchanged.',
+    category: 'utility',
+    inputTypes: [
+      'string',
+      'number',
+      'boolean',
+      'date',
+      'time',
+      'datetime',
+      'object',
+      'array',
+      'unknown',
+    ],
+    outputType: 'unknown',
+    apply: (value) => value,
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.arrayFirst,
+    label: 'Array first',
+    description: 'Return the first element of an array (or the value when not an array).',
+    category: 'array',
+    inputTypes: ['array', 'unknown'],
+    outputType: 'unknown',
+    apply: (value) => (Array.isArray(value) ? value[0] : value),
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.arrayJoin,
+    label: 'Array join',
+    description: 'Join array elements with a separator (default ", ").',
+    category: 'array',
+    inputTypes: ['array', 'unknown'],
+    outputType: 'string',
+    optionFields: [
+      {
+        key: 'separator',
+        label: 'Separator',
+        kind: 'string',
+      },
+    ],
+    apply: (value, context) => {
+      if (!Array.isArray(value)) {
+        return asString(value);
+      }
+      const separator =
+        typeof context.options?.separator === 'string' ? context.options.separator : ', ';
+      return value.map((item) => asString(item)).join(separator);
+    },
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.stringTrim,
+    label: 'Trim',
+    description: 'Trim leading and trailing whitespace.',
+    category: 'string',
+    inputTypes: ['string', 'number', 'unknown'],
+    outputType: 'string',
+    apply: (value) => asString(value).trim(),
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.stringUpper,
+    label: 'Uppercase',
+    description: 'Convert text to uppercase.',
+    category: 'string',
+    inputTypes: ['string', 'number', 'unknown'],
+    outputType: 'string',
+    apply: (value) => asString(value).toUpperCase(),
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.stringLower,
+    label: 'Lowercase',
+    description: 'Convert text to lowercase.',
+    category: 'string',
+    inputTypes: ['string', 'number', 'unknown'],
+    outputType: 'string',
+    apply: (value) => asString(value).toLowerCase(),
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.stringPrefix,
+    label: 'Prefix',
+    description: 'Prepend a fixed string.',
+    category: 'string',
+    inputTypes: ['string', 'number', 'unknown'],
+    outputType: 'string',
+    optionFields: [{ key: 'value', label: 'Prefix', kind: 'string' }],
+    apply: (value, context) => {
+      const prefix = typeof context.options?.value === 'string' ? context.options.value : '';
+      return `${prefix}${asString(value)}`;
+    },
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.stringSuffix,
+    label: 'Suffix',
+    description: 'Append a fixed string.',
+    category: 'string',
+    inputTypes: ['string', 'number', 'unknown'],
+    outputType: 'string',
+    optionFields: [{ key: 'value', label: 'Suffix', kind: 'string' }],
+    apply: (value, context) => {
+      const suffix = typeof context.options?.value === 'string' ? context.options.value : '';
+      return `${asString(value)}${suffix}`;
+    },
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.stringTemplate,
+    label: 'Template',
+    description: 'Fill {path} placeholders from an object (e.g. "{first} {last}").',
+    category: 'string',
+    inputTypes: ['object', 'unknown'],
+    outputType: 'string',
+    optionFields: [{ key: 'template', label: 'Template', kind: 'string' }],
+    apply: (value, context) => {
+      const template =
+        typeof context.options?.template === 'string' ? context.options.template : '';
+      if (!template) {
+        return isPlainObject(value) ? JSON.stringify(value) : asString(value);
+      }
+      return applyStringTemplate(template, isPlainObject(value) ? value : undefined);
+    },
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.dateReformat,
+    label: 'Date reformat',
+    description: 'Reformat a date string (token formats: YYYY, MM, DD).',
+    category: 'date',
+    inputTypes: ['string', 'unknown'],
+    outputType: 'string',
+    optionFields: [
+      { key: 'inputFormat', label: 'Input format', kind: 'string' },
+      { key: 'outputFormat', label: 'Output format', kind: 'string' },
+    ],
+    apply: (value, context) => {
+      const inputFormat =
+        typeof context.options?.inputFormat === 'string' ? context.options.inputFormat : 'YYYYMMDD';
+      const outputFormat =
+        typeof context.options?.outputFormat === 'string'
+          ? context.options.outputFormat
+          : 'YYYY-MM-DD';
+      const text = asString(value);
+      return reformatDateString(text, inputFormat, outputFormat) ?? text;
+    },
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.datetimeCombine,
+    label: 'Combine date+time',
+    description: 'Join object fields into a datetime string (default keys: date, time).',
+    category: 'date',
+    inputTypes: ['object', 'unknown'],
+    outputType: 'datetime',
+    optionFields: [
+      { key: 'dateKey', label: 'Date key', kind: 'string' },
+      { key: 'timeKey', label: 'Time key', kind: 'string' },
+      { key: 'separator', label: 'Separator', kind: 'string' },
+    ],
+    apply: (value, context) => {
+      if (!isPlainObject(value)) {
+        return asString(value);
+      }
+      const dateKey =
+        typeof context.options?.dateKey === 'string' ? context.options.dateKey : 'date';
+      const timeKey =
+        typeof context.options?.timeKey === 'string' ? context.options.timeKey : 'time';
+      const separator =
+        typeof context.options?.separator === 'string' ? context.options.separator : 'T';
+      return `${asString(value[dateKey])}${separator}${asString(value[timeKey])}`;
+    },
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.datetimeDate,
+    label: 'Date part',
+    description: 'Take the date part from a datetime string.',
+    category: 'date',
+    inputTypes: ['string', 'datetime', 'unknown'],
+    outputType: 'date',
+    apply: (value) => splitDateTimeString(asString(value))?.date ?? asString(value),
+  },
+  {
+    id: BUILTIN_TRANSFORM_IDS.datetimeTime,
+    label: 'Time part',
+    description: 'Take the time part from a datetime string.',
+    category: 'date',
+    inputTypes: ['string', 'datetime', 'unknown'],
+    outputType: 'time',
+    apply: (value) => splitDateTimeString(asString(value))?.time ?? '',
+  },
+];
+
+export type CreateBuiltinValueTransformRegistryOptions = Record<string, never>;
+
+/** Builtin registry. Hosts may `register()` additional transforms. */
+export function createBuiltinValueTransformRegistry(
+  _options?: CreateBuiltinValueTransformRegistryOptions,
+) {
+  return createValueTransformRegistry(builtinValueTransforms);
+}
+
+/** @deprecated Empty — kept for import stability while hosts migrate. */
+export const TIME_FORMAT_TRANSFORM_IDS = [] as const;
+/** @deprecated Empty — kept for import stability while hosts migrate. */
+export const DATE_STYLE_TRANSFORM_IDS = [] as const;

package/src/registry/createValueTransformRegistry.ts

@@ -0,0 +1,194 @@
+import { canonicalizeTransformId, MAX_TRANSFORM_CHAIN } from '../domain/constants.js';
+import type {
+  FieldDataType,
+  TransformContext,
+  ValueTransformDefinition,
+  ValueTransformListFilter,
+  ValueTransformRegistry,
+} from '../domain/types.js';
+
+export function createValueTransformRegistry(
+  initial: readonly ValueTransformDefinition[] = [],
+): ValueTransformRegistry {
+  const byId = new Map<string, ValueTransformDefinition>();
+
+  for (const definition of initial) {
+    byId.set(definition.id, definition);
+  }
+
+  function resolve(id: string): ValueTransformDefinition | undefined {
+    const canonical = canonicalizeTransformId(id);
+    return byId.get(canonical) ?? byId.get(id);
+  }
+
+  return {
+    list(filter) {
+      return [...byId.values()].filter((definition) => matchesFilter(definition, filter));
+    },
+    get(id) {
+      return resolve(id);
+    },
+    apply(id, value, context = {}) {
+      const definition = resolve(id);
+      if (!definition) {
+        throw new Error(`Unknown value transform: ${id}`);
+      }
+      return definition.apply(value, context);
+    },
+    register(definition) {
+      byId.set(definition.id, definition);
+    },
+  };
+}
+
+/**
+ * Apply an ordered transform chain (empty = identity / unchanged).
+ * Optional `optionSteps[i]` merges over `context.options` for step `i` only.
+ */
+export function applyTransformChain(
+  registry: ValueTransformRegistry,
+  transformIds: readonly string[],
+  value: unknown,
+  context: TransformContext = {},
+  optionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[],
+): unknown {
+  let current = value;
+  const ids = transformIds.slice(0, MAX_TRANSFORM_CHAIN);
+  for (let index = 0; index < ids.length; index += 1) {
+    const stepOptions = optionSteps?.[index];
+    const stepContext =
+      stepOptions && Object.keys(stepOptions).length > 0
+        ? {
+            ...context,
+            options: {
+              ...context.options,
+              ...stepOptions,
+            },
+          }
+        : context;
+    current = registry.apply(ids[index]!, current, stepContext);
+  }
+  return current;
+}
+
+function matchesFilter(
+  definition: ValueTransformDefinition,
+  filter: ValueTransformListFilter | undefined,
+): boolean {
+  if (!filter) {
+    return true;
+  }
+
+  if (filter.category && definition.category !== filter.category) {
+    return false;
+  }
+
+  if (filter.inputType) {
+    const inputTypes = definition.inputTypes;
+    if (inputTypes && inputTypes.length > 0 && !inputTypes.includes(filter.inputType)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** Whether a transform may sit between a typed source field and a typed target slot. */
+export function isTransformCompatible(
+  definition: ValueTransformDefinition,
+  sourceType: FieldDataType | undefined,
+  targetType: FieldDataType | undefined,
+): boolean {
+  if (
+    sourceType &&
+    sourceType !== 'unknown' &&
+    definition.inputTypes &&
+    definition.inputTypes.length > 0 &&
+    !definition.inputTypes.includes(sourceType)
+  ) {
+    return false;
+  }
+
+  // Collection sources only accept transforms that declare array input (or untyped).
+  if (sourceType === 'array') {
+    const acceptsArray =
+      !definition.inputTypes ||
+      definition.inputTypes.length === 0 ||
+      definition.inputTypes.includes('array');
+    if (!acceptsArray) {
+      return false;
+    }
+  }
+
+  // Array → array is pass-through only; reduce / typed outputs are not collection-preserving.
+  if (
+    sourceType === 'array' &&
+    targetType === 'array' &&
+    definition.outputType &&
+    definition.outputType !== 'array'
+  ) {
+    return false;
+  }
+
+  if (
+    targetType &&
+    targetType !== 'unknown' &&
+    definition.outputType &&
+    definition.outputType !== 'unknown' &&
+    definition.outputType !== targetType
+  ) {
+    // Formatted outputs are strings; string sinks accept them.
+    return targetType === 'string';
+  }
+
+  // Pass-through / undeclared output: known source and target types must match.
+  if (
+    !definition.outputType &&
+    sourceType &&
+    sourceType !== 'unknown' &&
+    targetType &&
+    targetType !== 'unknown' &&
+    sourceType !== targetType
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Whether an ordered transform chain can sit between source and target types.
+ * Each step must accept the previous output type (or the original source for step 0).
+ */
+export function isTransformChainCompatible(
+  registry: ValueTransformRegistry,
+  transformIds: readonly string[],
+  sourceType: FieldDataType | undefined,
+  targetType: FieldDataType | undefined,
+): boolean {
+  if (transformIds.length === 0) {
+    return true;
+  }
+  if (transformIds.length > MAX_TRANSFORM_CHAIN) {
+    return false;
+  }
+
+  let currentType = sourceType;
+  for (let index = 0; index < transformIds.length; index += 1) {
+    const definition = registry.get(transformIds[index]!);
+    if (!definition) {
+      return false;
+    }
+    const isLast = index === transformIds.length - 1;
+    if (!isTransformCompatible(definition, currentType, isLast ? targetType : undefined)) {
+      return false;
+    }
+    if (definition.outputType) {
+      currentType = definition.outputType;
+    }
+  }
+
+  return true;
+}
+
+export type { TransformContext };