@semilayer/data-mapping 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { FieldConfig, TransformSpec, BuiltinTransform } from '@semilayer/core';
+
+interface ApplyFieldMappingOptions {
+    nullValues?: unknown[];
+}
+/**
+ * Applies field definitions to a raw source row, producing the output row.
+ * Each field resolves its source value (from `from` or identity), applies
+ * merge/transform/null handling, and writes to the output under the field key.
+ */
+declare function applyFieldMapping(row: Record<string, unknown>, fields: Record<string, FieldConfig>, opts?: ApplyFieldMappingOptions): Record<string, unknown>;
+
+/**
+ * Execute a single transform on a value.
+ * Never throws — data massaging, not validation.
+ */
+declare function executeTransform(value: unknown, transform: BuiltinTransform, field?: string, row?: Record<string, unknown>): unknown;
+/**
+ * Execute a transform spec (single or chain) on a value.
+ */
+declare function applyTransforms(value: unknown, spec: TransformSpec, field?: string, row?: Record<string, unknown>): unknown;
+
+export { type ApplyFieldMappingOptions, applyFieldMapping, applyTransforms, executeTransform };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/transforms.ts
+function executeTransform(value, transform, field, row) {
+  try {
+    switch (transform.type) {
+      case "toString":
+        return value == null ? "" : String(value);
+      case "toNumber": {
+        if (value == null) return NaN;
+        const n = Number(value);
+        return n;
+      }
+      case "toBoolean": {
+        if (value == null) return false;
+        if (typeof value === "boolean") return value;
+        if (typeof value === "number") return value !== 0;
+        const s = String(value).toLowerCase().trim();
+        return s === "true" || s === "1" || s === "yes";
+      }
+      case "toDate": {
+        if (value == null) return null;
+        const d = new Date(value);
+        return isNaN(d.getTime()) ? null : d.toISOString();
+      }
+      case "round": {
+        const num = typeof value === "number" ? value : Number(value);
+        if (isNaN(num)) return value;
+        const decimals = transform.decimals ?? 0;
+        const factor = Math.pow(10, decimals);
+        const mode = transform.mode ?? "round";
+        return Math[mode](num * factor) / factor;
+      }
+      case "trim":
+        return value == null ? "" : String(value).trim();
+      case "lowercase":
+        return value == null ? "" : String(value).toLowerCase();
+      case "uppercase":
+        return value == null ? "" : String(value).toUpperCase();
+      case "default":
+        return value == null ? transform.value : value;
+      case "split": {
+        if (value == null) return [];
+        return String(value).split(transform.separator);
+      }
+      case "join": {
+        if (Array.isArray(value)) return value.join(transform.separator);
+        return value == null ? "" : String(value);
+      }
+      case "truncate": {
+        if (value == null) return "";
+        return String(value).slice(0, transform.length);
+      }
+      case "replace": {
+        if (value == null) return "";
+        return String(value).replace(new RegExp(transform.pattern, "g"), transform.replacement);
+      }
+      case "custom": {
+        const fn = new Function("value", "field", "row", transform.body);
+        return fn(value, field, row);
+      }
+      default:
+        return value;
+    }
+  } catch {
+    return value;
+  }
+}
+function applyTransforms(value, spec, field, row) {
+  const transforms = Array.isArray(spec) ? spec : [spec];
+  let result = value;
+  for (const t of transforms) {
+    result = executeTransform(result, t, field, row);
+  }
+  return result;
+}
+
+// src/apply.ts
+function applyFieldMapping(row, fields, opts) {
+  if (opts?.nullValues && opts.nullValues.length > 0) {
+    replaceNullSentinels(row, opts.nullValues);
+  }
+  const output = {};
+  for (const [outputName, field] of Object.entries(fields)) {
+    let value;
+    if (field.from === void 0) {
+      value = row[outputName];
+    } else if (Array.isArray(field.from)) {
+      if (field.merge === "coalesce") {
+        value = field.from.reduce((acc, src) => acc ?? row[src], void 0);
+      } else {
+        const parts = field.from.map((src) => row[src]).filter((v) => v != null);
+        value = parts.map(String).join(field.separator ?? " ");
+      }
+    } else {
+      value = row[field.from];
+    }
+    if (field.transform) {
+      value = applyTransforms(value, field.transform, outputName, row);
+    }
+    output[outputName] = value;
+    applyNullHandling(output, outputName, field);
+  }
+  return output;
+}
+function replaceNullSentinels(row, sentinels) {
+  for (const key of Object.keys(row)) {
+    if (sentinels.includes(row[key])) {
+      row[key] = null;
+    }
+  }
+}
+function applyNullHandling(output, key, field) {
+  const value = output[key];
+  if (value === void 0 && field.undefinedAs !== void 0) {
+    output[key] = field.undefinedAs;
+    return;
+  }
+  if (value === null && field.nullAs !== void 0) {
+    if (field.nullAs === "omit") {
+      delete output[key];
+    } else if (field.nullAs === "undefined") {
+      output[key] = void 0;
+    } else {
+      output[key] = field.nullAs;
+    }
+  }
+}
+export {
+  applyFieldMapping,
+  applyTransforms,
+  executeTransform
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transforms.ts","../src/apply.ts"],"sourcesContent":["import type { BuiltinTransform, TransformSpec } from '@semilayer/core'\n\n/**\n * Execute a single transform on a value.\n * Never throws — data massaging, not validation.\n */\nexport function executeTransform(\n  value: unknown,\n  transform: BuiltinTransform,\n  field?: string,\n  row?: Record<string, unknown>,\n): unknown {\n  try {\n    switch (transform.type) {\n      case 'toString':\n        return value == null ? '' : String(value)\n\n      case 'toNumber': {\n        if (value == null) return NaN\n        const n = Number(value)\n        return n\n      }\n\n      case 'toBoolean': {\n        if (value == null) return false\n        if (typeof value === 'boolean') return value\n        if (typeof value === 'number') return value !== 0\n        const s = String(value).toLowerCase().trim()\n        return s === 'true' || s === '1' || s === 'yes'\n      }\n\n      case 'toDate': {\n        if (value == null) return null\n        const d = new Date(value as string | number)\n        return isNaN(d.getTime()) ? null : d.toISOString()\n      }\n\n      case 'round': {\n        const num = typeof value === 'number' ? value : Number(value)\n        if (isNaN(num)) return value\n        const decimals = transform.decimals ?? 0\n        const factor = Math.pow(10, decimals)\n        const mode = transform.mode ?? 'round'\n        return Math[mode](num * factor) / factor\n      }\n\n      case 'trim':\n        return value == null ? '' : String(value).trim()\n\n      case 'lowercase':\n        return value == null ? '' : String(value).toLowerCase()\n\n      case 'uppercase':\n        return value == null ? '' : String(value).toUpperCase()\n\n      case 'default':\n        return value == null ? transform.value : value\n\n      case 'split': {\n        if (value == null) return []\n        return String(value).split(transform.separator)\n      }\n\n      case 'join': {\n        if (Array.isArray(value)) return value.join(transform.separator)\n        return value == null ? '' : String(value)\n      }\n\n      case 'truncate': {\n        if (value == null) return ''\n        return String(value).slice(0, transform.length)\n      }\n\n      case 'replace': {\n        if (value == null) return ''\n        return String(value).replace(new RegExp(transform.pattern, 'g'), transform.replacement)\n      }\n\n      case 'custom': {\n        // eslint-disable-next-line no-new-func\n        const fn = new Function('value', 'field', 'row', transform.body)\n        return fn(value, field, row)\n      }\n\n      default:\n        return value\n    }\n  } catch {\n    // Data massaging — never throw\n    return value\n  }\n}\n\n/**\n * Execute a transform spec (single or chain) on a value.\n */\nexport function applyTransforms(\n  value: unknown,\n  spec: TransformSpec,\n  field?: string,\n  row?: Record<string, unknown>,\n): unknown {\n  const transforms = Array.isArray(spec) ? spec : [spec]\n  let result = value\n  for (const t of transforms) {\n    result = executeTransform(result, t, field, row)\n  }\n  return result\n}\n","import type { FieldConfig } from '@semilayer/core'\nimport { applyTransforms } from './transforms.js'\n\nexport interface ApplyFieldMappingOptions {\n  nullValues?: unknown[]\n}\n\n/**\n * Applies field definitions to a raw source row, producing the output row.\n * Each field resolves its source value (from `from` or identity), applies\n * merge/transform/null handling, and writes to the output under the field key.\n */\nexport function applyFieldMapping(\n  row: Record<string, unknown>,\n  fields: Record<string, FieldConfig>,\n  opts?: ApplyFieldMappingOptions,\n): Record<string, unknown> {\n  // Phase 1: null sentinel replacement on raw row\n  if (opts?.nullValues && opts.nullValues.length > 0) {\n    replaceNullSentinels(row, opts.nullValues)\n  }\n\n  const output: Record<string, unknown> = {}\n\n  // Phase 2: process each field definition\n  for (const [outputName, field] of Object.entries(fields)) {\n    let value: unknown\n\n    if (field.from === undefined) {\n      // Identity: source column = output name\n      value = row[outputName]\n    } else if (Array.isArray(field.from)) {\n      // Multi-source merge\n      if (field.merge === 'coalesce') {\n        value = field.from.reduce<unknown>((acc, src) => acc ?? row[src], undefined)\n      } else {\n        // concat (default for multi-source)\n        const parts = field.from.map((src) => row[src]).filter((v) => v != null)\n        value = parts.map(String).join(field.separator ?? ' ')\n      }\n    } else {\n      // Single rename: from is a string\n      value = row[field.from]\n    }\n\n    // Apply transform chain\n    if (field.transform) {\n      value = applyTransforms(value, field.transform, outputName, row)\n    }\n\n    output[outputName] = value\n\n    // Null/undefined handling\n    applyNullHandling(output, outputName, field)\n  }\n\n  return output\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction replaceNullSentinels(row: Record<string, unknown>, sentinels: unknown[]): void {\n  for (const key of Object.keys(row)) {\n    if (sentinels.includes(row[key])) {\n      row[key] = null\n    }\n  }\n}\n\nfunction applyNullHandling(\n  output: Record<string, unknown>,\n  key: string,\n  field: FieldConfig,\n): void {\n  const value = output[key]\n\n  // undefinedAs: handle missing/undefined values\n  if (value === undefined && field.undefinedAs !== undefined) {\n    output[key] = field.undefinedAs\n    return\n  }\n\n  // nullAs: handle null values\n  if (value === null && field.nullAs !== undefined) {\n    if (field.nullAs === 'omit') {\n      delete output[key]\n    } else if (field.nullAs === 'undefined') {\n      output[key] = undefined\n    } else {\n      output[key] = field.nullAs\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@semilayer/data-mapping",
+  "version": "1.1.0",
+  "description": "SemiLayer data mapping — field renaming, transforms, null handling",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@semilayer/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}