@x12i/helpers 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,43 @@
+# @x12i/helpers
+
+Small helper utilities for x12i projects.
+
+## Install
+
+```bash
+npm i @x12i/helpers
+```
+
+## Usage
+
+### Objects mapper
+
+```js
+const { mapObject, createMapper, mapArray, deepGet, deepSet } = require("@x12i/helpers");
+
+const source = { user: { first: "Jane", last: "Doe" } };
+
+const mapping = [
+  "user.first -> profile.firstName",
+  "user.last -> profile.lastName",
+  { template: "{user.first} {user.last}", to: "profile.displayName" }
+];
+
+console.log(mapObject(source, mapping));
+// { profile: { firstName: 'Jane', lastName: 'Doe', displayName: 'Jane Doe' } }
+```
+
+You can also import the mapper directly:
+
+```js
+const { mapObject } = require("@x12i/helpers/objects-mapper");
+```
+
+## API
+
+- `mapObject(source, mapping, opts)`
+- `createMapper(mapping, opts)`
+- `mapArray(sourceArray, mapping, opts)`
+- `deepGet(obj, path)`
+- `deepSet(obj, path, value)`
+

package/index.js

@@ -0,0 +1,4 @@
+module.exports = {
+  ...require("./src/helpers/objectsMapper.js"),
+};
+

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@x12i/helpers",
+  "version": "1.0.0",
+  "description": "Small helper utilities for x12i projects.",
+  "license": "MIT",
+  "author": "x12i",
+  "homepage": "https://www.npmjs.com/package/@x12i/helpers",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "keywords": [
+    "helpers",
+    "utilities",
+    "mapper",
+    "json",
+    "object-mapping"
+  ],
+  "type": "commonjs",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./objects-mapper": "./src/helpers/objectsMapper.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}
+

package/src/helpers/objectsMapper.js

@@ -0,0 +1,456 @@
+/**
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║                    JSON OBJECT MAPPER                       ║
+ * ╠══════════════════════════════════════════════════════════════╣
+ * ║  Maps properties from a source JSON object to a target      ║
+ * ║  JSON object using a flexible mapping configuration.        ║
+ * ╚══════════════════════════════════════════════════════════════╝
+ *
+ * MAPPING CONFIG — each entry can be:
+ *
+ *  ┌─────────────────────────────────────────────────────────────┐
+ *  │ STRING shorthand                                            │
+ *  │   "user.name"  →  copies source.user.name to same path     │
+ *  │   "user.name -> profile.fullName"  →  renames path         │
+ *  ├─────────────────────────────────────────────────────────────┤
+ *  │ OBJECT (full power)                                        │
+ *  │  {                                                          │
+ *  │    from:        "a.b.c"  | ["a.b", "x.y"]  | null,        │
+ *  │    to:          "d.e.f",                                   │
+ *  │    transform:   (val, source) => ...,                      │
+ *  │    default:     any,           // if source value missing   │
+ *  │    condition:   (val, source) => bool,                     │
+ *  │    flatten:     true,          // spread object into target │
+ *  │    arrayMap:    subMappingConfig,  // map each array elem   │
+ *  │    coerce:      "string"|"number"|"boolean"|"array"|"date",│
+ *  │    fallback:    ["a.b", "c.d"],   // first non-null wins   │
+ *  │    compute:     (source) => any,  // ignore `from`, build  │
+ *  │    template:    "Hello {user.first} {user.last}",          │
+ *  │    pick:        ["a","b"],     // pick keys from sub-obj   │
+ *  │    omit:        ["c","d"],     // omit keys from sub-obj   │
+ *  │    rename:      {old: "new"},  // rename keys in sub-obj   │
+ *  │  }                                                          │
+ *  ├─────────────────────────────────────────────────────────────┤
+ *  │ WILDCARD paths                                              │
+ *  │   "items[*].name -> products[*].title"                     │
+ *  │   Maps every element in an array at that depth.            │
+ *  └─────────────────────────────────────────────────────────────┘
+ */
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Parse a dot/bracket path into segments.
+ * "a.b[0].c[*]" → ["a","b","0","c","*"]
+ */
+function parsePath(path) {
+    if (!path || typeof path !== "string") return [];
+    return path
+      .replace(/\[(\w+|\*)]/g, ".$1")
+      .split(".")
+      .filter(Boolean);
+  }
+  
+  /**
+   * Safely get a deep value. Supports [*] wildcard to fan-out over arrays.
+   */
+  function deepGet(obj, path, MISSING = undefined) {
+    const segs = typeof path === "string" ? parsePath(path) : path;
+    if (!segs.length) return obj;
+  
+    let current = obj;
+    for (let i = 0; i < segs.length; i++) {
+      if (current == null) return MISSING;
+      const seg = segs[i];
+  
+      if (seg === "*") {
+        // Fan-out: apply remaining path to every element
+        if (!Array.isArray(current)) return MISSING;
+        const rest = segs.slice(i + 1);
+        return rest.length
+          ? current.map((el) => deepGet(el, rest, MISSING))
+          : current;
+      }
+      current = current[seg];
+    }
+    return current === undefined ? MISSING : current;
+  }
+  
+  /**
+   * Safely set a deep value. Creates intermediate objects/arrays as needed.
+   * [*] in target path means "append / map into array".
+   */
+  function deepSet(obj, path, value) {
+    const segs = typeof path === "string" ? parsePath(path) : path;
+    if (!segs.length) return;
+  
+    let current = obj;
+    for (let i = 0; i < segs.length - 1; i++) {
+      const seg = segs[i];
+      const next = segs[i + 1];
+  
+      if (seg === "*") {
+        // Fan-out set: value should be an array
+        if (!Array.isArray(current)) return;
+        const rest = segs.slice(i + 1);
+        const vals = Array.isArray(value) ? value : current.map(() => value);
+        current.forEach((el, idx) => {
+          if (el && typeof el === "object") {
+            deepSet(el, rest, vals[idx]);
+          }
+        });
+        return;
+      }
+  
+      if (current[seg] == null) {
+        current[seg] = next === "*" || /^\d+$/.test(next) ? [] : {};
+      }
+      current = current[seg];
+    }
+  
+    const last = segs[segs.length - 1];
+    if (last === "*") {
+      // Push or spread into array
+      if (Array.isArray(current) && Array.isArray(value)) {
+        value.forEach((v, i) => (current[i] = v));
+      }
+    } else {
+      current[last] = value;
+    }
+  }
+  
+  /**
+   * Deep merge: source properties into target without overwriting existing.
+   */
+  function deepMerge(target, source) {
+    if (!source || typeof source !== "object") return target;
+    for (const key of Object.keys(source)) {
+      if (
+        target[key] &&
+        typeof target[key] === "object" &&
+        typeof source[key] === "object" &&
+        !Array.isArray(target[key])
+      ) {
+        deepMerge(target[key], source[key]);
+      } else if (target[key] === undefined) {
+        target[key] = source[key];
+      }
+    }
+    return target;
+  }
+  
+  // ─── Coercion ─────────────────────────────────────────────────────
+  
+  const COERCIONS = {
+    string: (v) => (v == null ? "" : String(v)),
+    number: (v) => {
+      const n = Number(v);
+      return Number.isNaN(n) ? 0 : n;
+    },
+    boolean: (v) =>
+      v === "false" || v === "0" || v === "no" ? false : Boolean(v),
+    array: (v) => (v == null ? [] : Array.isArray(v) ? v : [v]),
+    date: (v) => (v instanceof Date ? v : new Date(v)),
+  };
+  
+  // ─── Template interpolation ───────────────────────────────────────
+  
+  function interpolate(template, source) {
+    return template.replace(/\{([^}]+)}/g, (_, path) => {
+      const val = deepGet(source, path.trim());
+      return val == null ? "" : String(val);
+    });
+  }
+  
+  // ─── Core mapper ──────────────────────────────────────────────────
+  
+  const MISSING = Symbol("MISSING");
+  
+  function processRule(rule, source) {
+    // ── Normalize shorthand strings ──
+    if (typeof rule === "string") {
+      if (rule.includes("->")) {
+        const [from, to] = rule.split("->").map((s) => s.trim());
+        rule = { from, to };
+      } else {
+        rule = { from: rule, to: rule };
+      }
+    }
+  
+    const {
+      from,
+      to,
+      transform,
+      default: defaultVal,
+      condition,
+      flatten,
+      arrayMap,
+      coerce,
+      fallback,
+      compute,
+      template,
+      pick,
+      omit,
+      rename,
+    } = rule;
+  
+    // ── Compute (ignore `from`, generate from whole source) ──
+    if (compute) {
+      const val = compute(source);
+      if (condition && !condition(val, source)) return { skip: true };
+      return { to, value: val };
+    }
+  
+    // ── Template interpolation ──
+    if (template) {
+      const val = interpolate(template, source);
+      if (condition && !condition(val, source)) return { skip: true };
+      return { to, value: val };
+    }
+  
+    // ── Resolve source value ──
+    let value = MISSING;
+  
+    if (fallback) {
+      // Try each path until one yields a non-null
+      for (const path of fallback) {
+        const v = deepGet(source, path, MISSING);
+        if (v !== MISSING && v != null) {
+          value = v;
+          break;
+        }
+      }
+    } else if (Array.isArray(from)) {
+      // Multi-source → array of values (fed into transform)
+      value = from.map((p) => deepGet(source, p, MISSING));
+      if (value.every((v) => v === MISSING)) value = MISSING;
+    } else if (from) {
+      value = deepGet(source, from, MISSING);
+    }
+  
+    // ── Default ──
+    if ((value === MISSING || value == null) && defaultVal !== undefined) {
+      value = typeof defaultVal === "function" ? defaultVal(source) : defaultVal;
+    }
+  
+    if (value === MISSING) value = undefined;
+  
+    // ── Condition gate ──
+    if (condition && !condition(value, source)) return { skip: true };
+  
+    // ── Transform ──
+    if (transform) value = transform(value, source);
+  
+    // ── Coerce ──
+    if (coerce && COERCIONS[coerce]) value = COERCIONS[coerce](value);
+  
+    // ── Array sub-mapping ──
+    if (arrayMap && Array.isArray(value)) {
+      value = value.map((item) => mapObject(item, arrayMap));
+    }
+  
+    // ── Pick / Omit / Rename keys on sub-objects ──
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (pick) {
+        value = Object.fromEntries(
+          Object.entries(value).filter(([k]) => pick.includes(k))
+        );
+      }
+      if (omit) {
+        value = Object.fromEntries(
+          Object.entries(value).filter(([k]) => !omit.includes(k))
+        );
+      }
+      if (rename) {
+        const renamed = {};
+        for (const [k, v] of Object.entries(value)) {
+          renamed[rename[k] || k] = v;
+        }
+        value = renamed;
+      }
+    }
+  
+    return { to, value, flatten };
+  }
+  
+  // ─── Public API ───────────────────────────────────────────────────
+  
+  /**
+   * Map a source object to a new target object.
+   *
+   * @param {object}          source   – the input JSON object
+   * @param {Array}           mapping  – array of mapping rules (strings or objects)
+   * @param {object}          [opts]
+   * @param {object}          [opts.base]       – starting target object (default {})
+   * @param {boolean}         [opts.stripNull]  – remove null/undefined from output
+   * @param {boolean}         [opts.passThrough]– copy unmapped source props as-is
+   * @param {function}        [opts.onError]    – (error, rule) => void
+   * @returns {object}
+   */
+  function mapObject(source, mapping, opts = {}) {
+    const { base = {}, stripNull = false, passThrough = false, onError } = opts;
+  
+    // Deep-clone base to avoid mutations
+    const target = JSON.parse(JSON.stringify(base));
+  
+    // Pass-through: start with a copy of source
+    if (passThrough) deepMerge(target, JSON.parse(JSON.stringify(source)));
+  
+    for (const rule of mapping) {
+      try {
+        const result = processRule(rule, source);
+        if (result.skip) continue;
+  
+        const { to: targetPath, value, flatten: shouldFlatten } = result;
+  
+        if (shouldFlatten && value && typeof value === "object") {
+          // Spread value's keys into target at the parent path
+          if (targetPath) {
+            const existing = deepGet(target, targetPath) || {};
+            deepSet(target, targetPath, { ...existing, ...value });
+          } else {
+            Object.assign(target, value);
+          }
+        } else if (targetPath) {
+          if (stripNull && (value === null || value === undefined)) continue;
+          deepSet(target, targetPath, value);
+        }
+      } catch (err) {
+        if (onError) onError(err, rule);
+        else console.warn(`[mapper] Rule failed:`, rule, err.message);
+      }
+    }
+  
+    return target;
+  }
+  
+  /**
+   * Create a reusable mapper function from a mapping config.
+   */
+  function createMapper(mapping, opts = {}) {
+    return (source) => mapObject(source, mapping, opts);
+  }
+  
+  /**
+   * Map each element of an array.
+   */
+  function mapArray(sourceArray, mapping, opts = {}) {
+    return sourceArray.map((item) => mapObject(item, mapping, opts));
+  }
+  
+  // ─── Exports ──────────────────────────────────────────────────────
+  
+  module.exports = { mapObject, createMapper, mapArray, deepGet, deepSet };
+  
+  // ══════════════════════════════════════════════════════════════════
+  //  DEMO — run with:  node json-mapper.js
+  // ══════════════════════════════════════════════════════════════════
+  
+  if (require.main === module) {
+    const source = {
+      user: {
+        firstName: "Jane",
+        lastName: "Doe",
+        email: "jane@example.com",
+        age: "29",
+        address: {
+          street: "123 Main St",
+          city: "Springfield",
+          zip: "62704",
+          country: "US",
+        },
+        tags: ["admin", "editor"],
+      },
+      orders: [
+        { id: 1, product: "Widget", qty: 3, price: 9.99 },
+        { id: 2, product: "Gadget", qty: 1, price: 24.5 },
+      ],
+      metadata: { createdAt: "2024-01-15T08:00:00Z", version: 2 },
+      legacyName: null,
+      nickname: "JD",
+    };
+  
+    const mapping = [
+      // ── String shorthand: same path ──
+      "user.email",
+  
+      // ── String shorthand: rename ──
+      "user.firstName -> profile.first",
+      "user.lastName  -> profile.last",
+  
+      // ── Coerce string → number ──
+      { from: "user.age", to: "profile.age", coerce: "number" },
+  
+      // ── Template interpolation ──
+      {
+        template: "{user.firstName} {user.lastName}",
+        to: "profile.displayName",
+      },
+  
+      // ── Nested pick + rename ──
+      {
+        from: "user.address",
+        to: "profile.location",
+        pick: ["city", "country"],
+        rename: { country: "countryCode" },
+      },
+  
+      // ── Fallback: first non-null wins ──
+      { fallback: ["legacyName", "nickname", "user.firstName"], to: "profile.name" },
+  
+      // ── Conditional ──
+      {
+        from: "user.age",
+        to: "profile.seniorDiscount",
+        transform: (v) => Number(v) >= 65,
+        condition: (v) => v != null,
+      },
+  
+      // ── Array sub-mapping ──
+      {
+        from: "orders",
+        to: "purchases",
+        arrayMap: [
+          "id",
+          "product -> name",
+          { from: "qty", to: "quantity" },
+          { from: "price", to: "unitPrice" },
+          {
+            compute: (item) => +(item.qty * item.price).toFixed(2),
+            to: "total",
+          },
+        ],
+      },
+  
+      // ── Compute from whole source ──
+      {
+        compute: (src) => src.orders.reduce((s, o) => s + o.qty * o.price, 0),
+        to: "summary.orderTotal",
+        transform: (v) => +v.toFixed(2),
+      },
+  
+      // ── Multi-source transform ──
+      {
+        from: ["user.tags", "metadata.version"],
+        to: "meta.info",
+        transform: ([tags, ver]) => ({
+          tagCount: tags.length,
+          apiVersion: `v${ver}`,
+        }),
+      },
+  
+      // ── Flatten into root ──
+      {
+        from: "metadata",
+        flatten: true,
+        pick: ["createdAt"],
+      },
+    ];
+  
+    const result = mapObject(source, mapping);
+  
+    console.log("═══ SOURCE ═══");
+    console.log(JSON.stringify(source, null, 2));
+    console.log("\n═══ RESULT ═══");
+    console.log(JSON.stringify(result, null, 2));
+  }