objwalk 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# objwalk
+
+Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.
+
+`objwalk` is built around a compact path syntax, so the same mental model works for picking values, setting values, extracting a new object shape, and walking through nested data.
+
+## Install
+
+```bash
+npm install objwalk
+```
+
+## Usage
+
+```ts
+import { each, extract, map, pick, set } from 'objwalk'
+```
+
+## pick
+
+Read a value from an object by path.
+
+```ts
+const data = {
+  user: {
+    name: 'Natalia Romanoff',
+    email: 'black.widow@example.com',
+  },
+}
+
+pick(data, 'user.name')
+// 'Natalia Romanoff'
+```
+
+Pick several keys from the same nested object.
+
+```ts
+pick(data, 'user.{name,email}')
+// { name: 'Natalia Romanoff', email: 'black.widow@example.com' }
+```
+
+List keys from a nested object.
+
+```ts
+pick(data, 'user.{*}')
+// ['name', 'email']
+```
+
+Read from arrays with an explicit index.
+
+```ts
+const data = {
+  items: [{ title: 'First' }, { title: 'Second' }],
+}
+
+pick(data, 'items[1].title')
+// 'Second'
+```
+
+If the path cannot be resolved, `pick` returns `undefined`.
+
+## set
+
+Set a value inside an object by path.
+
+```ts
+const data = {}
+
+set(data, 'user.name', 'Natalia')
+// { user: { name: 'Natalia' } }
+```
+
+Set values inside arrays with an explicit index.
+
+```ts
+const data = {}
+
+set(data, 'items[0].title', 'First')
+// { items: [{ title: 'Romanoff' }] }
+```
+
+`set` mutates the object passed to it and returns the same object.
+
+## extract
+
+Create a new object by mapping destination paths to source paths.
+
+```ts
+const source = {
+  profile: {
+    fullName: 'Natalia Romanoff',
+    email: 'black.widow@example.com',
+  },
+}
+
+extract(source, {
+  'user.name': 'profile.fullName',
+  'user.email': 'profile.email',
+})
+// {
+//   user: {
+//     name: 'Natalia Romanoff',
+//     email: 'black.widow@example.com',
+//   },
+// }
+```
+
+Use an array of source paths to provide fallbacks. The first resolved value is used.
+
+```ts
+extract(source, {
+  'user.name': ['profile.displayName', 'profile.fullName'],
+})
+```
+
+Use `[n]` to map over arrays.
+
+```ts
+const source = {
+  products: [
+    { name: 'Keyboard' },
+    { name: 'Mouse' },
+  ],
+}
+
+extract(source, {
+  'items[n].title': 'products[n].name',
+})
+// {
+//   items: [
+//     { title: 'Keyboard' },
+//     { title: 'Mouse' },
+//   ],
+// }
+```
+
+## each
+
+Walk through an object and call a function for each value.
+
+```ts
+each(data, (key, value, path) => {
+  console.log(key, value, path)
+})
+```
+
+The callback receives:
+
+- `key`: the current object key or array index
+- `value`: the current value
+- `path`: the full path to the current value
+
+## map
+
+Walk through an object and build a new result.
+
+```ts
+const result = map(data, (key, value, store, path) => {
+  if (typeof value === 'string') {
+    set(store, path, value.trim())
+  }
+})
+```
+
+The callback receives:
+
+- `key`: the current object key or array index
+- `value`: the current value
+- `store`: the result object being built
+- `path`: the full path to the current value
+
+`map` returns `store`.
+
+## Path syntax
+
+| Syntax | Description |
+| --- | --- |
+| `user.name` | Read or write a nested property. |
+| `items[0].title` | Read or write an array item by index. |
+| `user.{name,email}` | Pick several keys from one object. |
+| `user.{*}` | List keys from one object. |
+| `items[n].title` | Map every item in an array during `extract`. |
+
+## API
+
+```ts
+pick(data, path)
+set(data, path, value)
+extract(data, mapping)
+each(data, callback)
+map(data, callback)
+```

package/dist/index.cjs

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  each: () => each,
+  extract: () => extract,
+  map: () => map,
+  pick: () => pick,
+  set: () => set
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/each.ts
+var isWalkable = (value) => {
+  return value !== null && typeof value === "object";
+};
+var createPath = (parentPath, key, parentIsArray) => {
+  if (parentIsArray) {
+    return parentPath + "[" + key + "]";
+  }
+  return parentPath ? parentPath + "." + key : String(key);
+};
+var each = (data, callback) => {
+  const walk = (value, path, key, parentIsArray) => {
+    const currentPath = path || createPath("", key, parentIsArray);
+    callback(key, value, currentPath);
+    if (!isWalkable(value)) {
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        walk(item, createPath(currentPath, index, true), index, true);
+      });
+      return;
+    }
+    Object.entries(value).forEach(([childKey, item]) => {
+      walk(item, createPath(currentPath, childKey, false), childKey, false);
+    });
+  };
+  if (!isWalkable(data)) {
+    return;
+  }
+  if (Array.isArray(data)) {
+    data.forEach((item, index) => {
+      walk(item, createPath("", index, true), index, true);
+    });
+    return;
+  }
+  Object.entries(data).forEach(([key, value]) => {
+    walk(value, createPath("", key, false), key, false);
+  });
+};
+
+// src/helpers/getValueByPath.ts
+var getValueByPath = (obj, path) => {
+  if (!path) return obj;
+  return path.split(".").reduce((result, current) => {
+    if (result !== null && result !== void 0) {
+      const match = current.match(/(w+)[(d+)]/);
+      if (match) {
+        const [, key, index] = match;
+        const array = result[key];
+        return array && Array.isArray(array) ? array[parseInt(index, 10)] : void 0;
+      }
+      return result[current];
+    }
+    return void 0;
+  }, obj);
+};
+
+// src/helpers/parsePathSelection.ts
+var selectionRegex = /(.*){([^}]+)}$/;
+var normalizeSelectionPath = (path) => {
+  return path.endsWith(".") ? path.slice(0, -1) : path;
+};
+var parseSelectedKeys = (selection) => {
+  if (selection.trim() === "*") {
+    return "all";
+  }
+  return selection.split(",").map((key) => key.trim()).filter(Boolean);
+};
+var parsePathSelection = (path = "") => {
+  const matches = path.match(selectionRegex);
+  if (!matches) {
+    return {
+      cleanPath: path,
+      keys: []
+    };
+  }
+  return {
+    cleanPath: normalizeSelectionPath(matches[1]),
+    keys: parseSelectedKeys(matches[2])
+  };
+};
+
+// src/pick.ts
+var pick = (data = {}, path = "") => {
+  const { cleanPath, keys } = parsePathSelection(path);
+  const value = getValueByPath(data, cleanPath);
+  if (keys.length === 0 && keys !== "all") {
+    return value;
+  }
+  if (keys === "all") {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value);
+    }
+    return [];
+  }
+  if (value && typeof value === "object") {
+    if (keys.length === 1) {
+      return value[keys[0]];
+    }
+    return keys.reduce(
+      (result, key) => ({
+        ...result,
+        [key]: value[key]
+      }),
+      {}
+    );
+  }
+  return void 0;
+};
+
+// src/set.ts
+var parseArrayPathSegment = (key) => {
+  const matches = key.match(/^(\w+)\[(\d+)\]$/);
+  if (matches) {
+    return {
+      key: matches[1],
+      isArray: true,
+      index: parseInt(matches[2], 10)
+    };
+  }
+  return { key, isArray: false, index: -1 };
+};
+var set = (data = {}, path, value) => {
+  const keys = path.split(".");
+  let current = data;
+  for (let i = 0; i < keys.length; i++) {
+    const { key, isArray, index } = parseArrayPathSegment(keys[i]);
+    const isLastKey = i === keys.length - 1;
+    if (isArray) {
+      if (!current[key] || !Array.isArray(current[key])) {
+        current[key] = [];
+      }
+      if (index >= current[key].length) {
+        current[key].length = index + 1;
+      }
+      if (!isLastKey && current[key][index] === void 0) {
+        current[key][index] = {};
+      }
+      if (isLastKey) {
+        current[key][index] = value;
+        break;
+      }
+      current = current[key][index];
+    } else if (!isLastKey) {
+      if (!current[key] || typeof current[key] !== "object") {
+        current[key] = {};
+      }
+      current = current[key];
+    } else {
+      current[key] = value;
+    }
+  }
+  return data;
+};
+
+// src/extract.ts
+var mapArrayItems = (destinationPath, sourcePath, source = {}, result = {}) => {
+  const destinationParts = destinationPath.split("[n].");
+  const sourceParts = sourcePath.split("[n].");
+  const array = pick(source, sourceParts[0]);
+  if (Array.isArray(array)) {
+    array.forEach((row, index) => {
+      const itemPath = destinationParts[0] + "[" + index + "]." + destinationParts[1];
+      set(result, itemPath, pick(row, sourceParts[1]));
+    });
+  }
+};
+var extract = (source, mapping) => {
+  const result = {};
+  Object.entries(mapping).forEach(([destinationPath, sourcePath]) => {
+    if (destinationPath.includes("[n]") && typeof sourcePath === "string") {
+      mapArrayItems(destinationPath, sourcePath, source, result);
+      return;
+    }
+    if (Array.isArray(sourcePath)) {
+      for (const item of sourcePath) {
+        const value = pick(source, item);
+        if (value !== void 0) {
+          set(result, destinationPath, value);
+          break;
+        }
+      }
+      return;
+    }
+    set(result, destinationPath, pick(source, sourcePath));
+  });
+  return result;
+};
+
+// src/map.ts
+var map = (data, callback, store = {}) => {
+  each(data, (key, value, path) => {
+    callback(key, value, store, path);
+  });
+  return store;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  each,
+  extract,
+  map,
+  pick,
+  set
+});

package/dist/index.d.cts

@@ -0,0 +1,17 @@
+type WalkKey = string | number;
+type EachCallback = (key: WalkKey, value: any, path: string) => void;
+declare const each: (data: any, callback: EachCallback) => void;
+
+type ObjwalkObject$1 = Record<string, any>;
+declare const pick: (data?: ObjwalkObject$1, path?: string) => any;
+
+type ExtractMapping = Record<string, string | string[]>;
+declare const extract: (source: ObjwalkObject$1, mapping: ExtractMapping) => ObjwalkObject$1;
+
+type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (key: WalkKey, value: any, store: TStore, path: string) => void;
+declare const map: <TStore extends Record<string, any> = Record<string, any>>(data: any, callback: MapCallback<TStore>, store?: TStore) => TStore;
+
+type ObjwalkObject = Record<string, any>;
+declare const set: (data: ObjwalkObject | undefined, path: string, value: any) => ObjwalkObject;
+
+export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type WalkKey, each, extract, map, pick, set };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+type WalkKey = string | number;
+type EachCallback = (key: WalkKey, value: any, path: string) => void;
+declare const each: (data: any, callback: EachCallback) => void;
+
+type ObjwalkObject$1 = Record<string, any>;
+declare const pick: (data?: ObjwalkObject$1, path?: string) => any;
+
+type ExtractMapping = Record<string, string | string[]>;
+declare const extract: (source: ObjwalkObject$1, mapping: ExtractMapping) => ObjwalkObject$1;
+
+type MapCallback<TStore extends Record<string, any> = Record<string, any>> = (key: WalkKey, value: any, store: TStore, path: string) => void;
+declare const map: <TStore extends Record<string, any> = Record<string, any>>(data: any, callback: MapCallback<TStore>, store?: TStore) => TStore;
+
+type ObjwalkObject = Record<string, any>;
+declare const set: (data: ObjwalkObject | undefined, path: string, value: any) => ObjwalkObject;
+
+export { type EachCallback, type ExtractMapping, type MapCallback, type ObjwalkObject$1 as ObjwalkObject, type WalkKey, each, extract, map, pick, set };

package/dist/index.js

@@ -0,0 +1,204 @@
+// src/each.ts
+var isWalkable = (value) => {
+  return value !== null && typeof value === "object";
+};
+var createPath = (parentPath, key, parentIsArray) => {
+  if (parentIsArray) {
+    return parentPath + "[" + key + "]";
+  }
+  return parentPath ? parentPath + "." + key : String(key);
+};
+var each = (data, callback) => {
+  const walk = (value, path, key, parentIsArray) => {
+    const currentPath = path || createPath("", key, parentIsArray);
+    callback(key, value, currentPath);
+    if (!isWalkable(value)) {
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        walk(item, createPath(currentPath, index, true), index, true);
+      });
+      return;
+    }
+    Object.entries(value).forEach(([childKey, item]) => {
+      walk(item, createPath(currentPath, childKey, false), childKey, false);
+    });
+  };
+  if (!isWalkable(data)) {
+    return;
+  }
+  if (Array.isArray(data)) {
+    data.forEach((item, index) => {
+      walk(item, createPath("", index, true), index, true);
+    });
+    return;
+  }
+  Object.entries(data).forEach(([key, value]) => {
+    walk(value, createPath("", key, false), key, false);
+  });
+};
+
+// src/helpers/getValueByPath.ts
+var getValueByPath = (obj, path) => {
+  if (!path) return obj;
+  return path.split(".").reduce((result, current) => {
+    if (result !== null && result !== void 0) {
+      const match = current.match(/(w+)[(d+)]/);
+      if (match) {
+        const [, key, index] = match;
+        const array = result[key];
+        return array && Array.isArray(array) ? array[parseInt(index, 10)] : void 0;
+      }
+      return result[current];
+    }
+    return void 0;
+  }, obj);
+};
+
+// src/helpers/parsePathSelection.ts
+var selectionRegex = /(.*){([^}]+)}$/;
+var normalizeSelectionPath = (path) => {
+  return path.endsWith(".") ? path.slice(0, -1) : path;
+};
+var parseSelectedKeys = (selection) => {
+  if (selection.trim() === "*") {
+    return "all";
+  }
+  return selection.split(",").map((key) => key.trim()).filter(Boolean);
+};
+var parsePathSelection = (path = "") => {
+  const matches = path.match(selectionRegex);
+  if (!matches) {
+    return {
+      cleanPath: path,
+      keys: []
+    };
+  }
+  return {
+    cleanPath: normalizeSelectionPath(matches[1]),
+    keys: parseSelectedKeys(matches[2])
+  };
+};
+
+// src/pick.ts
+var pick = (data = {}, path = "") => {
+  const { cleanPath, keys } = parsePathSelection(path);
+  const value = getValueByPath(data, cleanPath);
+  if (keys.length === 0 && keys !== "all") {
+    return value;
+  }
+  if (keys === "all") {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value);
+    }
+    return [];
+  }
+  if (value && typeof value === "object") {
+    if (keys.length === 1) {
+      return value[keys[0]];
+    }
+    return keys.reduce(
+      (result, key) => ({
+        ...result,
+        [key]: value[key]
+      }),
+      {}
+    );
+  }
+  return void 0;
+};
+
+// src/set.ts
+var parseArrayPathSegment = (key) => {
+  const matches = key.match(/^(\w+)\[(\d+)\]$/);
+  if (matches) {
+    return {
+      key: matches[1],
+      isArray: true,
+      index: parseInt(matches[2], 10)
+    };
+  }
+  return { key, isArray: false, index: -1 };
+};
+var set = (data = {}, path, value) => {
+  const keys = path.split(".");
+  let current = data;
+  for (let i = 0; i < keys.length; i++) {
+    const { key, isArray, index } = parseArrayPathSegment(keys[i]);
+    const isLastKey = i === keys.length - 1;
+    if (isArray) {
+      if (!current[key] || !Array.isArray(current[key])) {
+        current[key] = [];
+      }
+      if (index >= current[key].length) {
+        current[key].length = index + 1;
+      }
+      if (!isLastKey && current[key][index] === void 0) {
+        current[key][index] = {};
+      }
+      if (isLastKey) {
+        current[key][index] = value;
+        break;
+      }
+      current = current[key][index];
+    } else if (!isLastKey) {
+      if (!current[key] || typeof current[key] !== "object") {
+        current[key] = {};
+      }
+      current = current[key];
+    } else {
+      current[key] = value;
+    }
+  }
+  return data;
+};
+
+// src/extract.ts
+var mapArrayItems = (destinationPath, sourcePath, source = {}, result = {}) => {
+  const destinationParts = destinationPath.split("[n].");
+  const sourceParts = sourcePath.split("[n].");
+  const array = pick(source, sourceParts[0]);
+  if (Array.isArray(array)) {
+    array.forEach((row, index) => {
+      const itemPath = destinationParts[0] + "[" + index + "]." + destinationParts[1];
+      set(result, itemPath, pick(row, sourceParts[1]));
+    });
+  }
+};
+var extract = (source, mapping) => {
+  const result = {};
+  Object.entries(mapping).forEach(([destinationPath, sourcePath]) => {
+    if (destinationPath.includes("[n]") && typeof sourcePath === "string") {
+      mapArrayItems(destinationPath, sourcePath, source, result);
+      return;
+    }
+    if (Array.isArray(sourcePath)) {
+      for (const item of sourcePath) {
+        const value = pick(source, item);
+        if (value !== void 0) {
+          set(result, destinationPath, value);
+          break;
+        }
+      }
+      return;
+    }
+    set(result, destinationPath, pick(source, sourcePath));
+  });
+  return result;
+};
+
+// src/map.ts
+var map = (data, callback, store = {}) => {
+  each(data, (key, value, path) => {
+    callback(key, value, store, path);
+  });
+  return store;
+};
+export {
+  each,
+  extract,
+  map,
+  pick,
+  set
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "objwalk",
+  "version": "0.1.0",
+  "description": "Small utilities for reading, writing, walking, and reshaping nested JavaScript objects.",
+  "keywords": [
+    "object",
+    "path",
+    "object-path",
+    "pick",
+    "set",
+    "extract",
+    "map",
+    "walk",
+    "traverse",
+    "transform",
+    "nested",
+    "mapper"
+  ],
+  "license": "ISC",
+  "author": "Sergey Khalilov <sergey.khalilov@gmail.com>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}