@stacksjs/objects 0.74.32 → 0.74.34

package/dist/index.d.ts

@@ -26,7 +26,7 @@ import type { DeepMerge } from '@stacksjs/types';
  * // { b: 2 }
  * ```
  */
-export declare function objectMap<K extends string, V, NK = K, NV = V>(obj: Record<K, V>, fn: (key: K, value: V) => [NK, NV] | undefined): Record<K, V>;
+export declare function objectMap<K extends string, V, NK extends PropertyKey = K, NV = V>(obj: Record<K, V>, fn: (key: K, value: V) => [NK, NV] | undefined): Record<NK, NV>;
 /**
  * Type guard for any key, `k`.
  * Marks `k` as a key of `T` if `k` is in `obj`.
@@ -72,3 +72,4 @@ export declare function clearUndefined<T extends object>(obj: T): T;
  * @category Object
  */
 export declare function hasOwnProperty<T>(obj: T, v: PropertyKey): boolean;
+export * from './transform';

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-import{notNullish as s}from"@stacksjs/utils";import{isObject as f}from"@stacksjs/validation";function p(e,n){return Object.fromEntries(Object.entries(e).map(([t,o])=>n(t,o)).filter(s))}function a(e,n){return n in e}function u(e){return Object.keys(e)}function b(e){return Object.entries(e)}function c(e,...n){if(!n.length)return e;let[t,...o]=n;if(t===void 0)return e;if(i(e)&&i(t))u(t).forEach((r)=>{if(i(t[r])){if(!e[r])e[r]={};c(e[r],t[r])}else e[r]=t[r]});return c(e,...o)}function i(e){return f(e)&&!Array.isArray(e)}function l(e,n,t=!1){return n.reduce((o,r)=>{if(r in e){if(!t||e[r]!==void 0)o[r]=e[r]}return o},{})}function y(e){return Object.keys(e).forEach((n)=>e[n]===void 0&&delete e[n]),e}function x(e,n){return e==null?!1:Object.prototype.hasOwnProperty.call(e,n)}export{y as clearUndefined,c as deepMerge,x as hasOwnProperty,a as isKeyOf,b as objectEntries,u as objectKeys,p as objectMap,l as objectPick};
+import{notNullish as O}from"@stacksjs/utils";import{isObject as p}from"@stacksjs/validation";function k(e,n){let t=new Set(n),r={};for(let[o,s]of Object.entries(e))if(!t.has(o))r[o]=s;return r}function a(e,n){let t={};for(let[r,o]of Object.entries(e))if(n(o,r))t[r]=o;return t}function l(e,n){return a(e,(t,r)=>!n(t,r))}function x(e,n){let t={};for(let[r,o]of Object.entries(e))t[r]=n(o,r);return t}function b(e,n){let t={};for(let[r,o]of Object.entries(e))t[n(r,o)]=o;return t}function j(e){let n={};for(let[t,r]of Object.entries(e))n[String(r)]=t;return n}function K(e){for(let n in e)if(Object.hasOwn(e,n))return!1;return!0}function T(e,n,t){let r=e;for(let o of n){if(r===null||r===void 0)return t;r=r[o]}return r===void 0?t:r}function y(e,n,t){if(n.length===0)return t;let[r,...o]=n,s=Array.isArray(e)?[...e]:{...e};if(o.length===0)return s[r]=t,s;let i=s[r],u=i===null||typeof i!=="object"?typeof o[0]==="number"?[]:{}:i;return s[r]=y(u,o,t),s}function m(e,n){return Object.fromEntries(Object.entries(e).map(([t,r])=>n(t,r)).filter(O))}function w(e,n){return n in e}function d(e){return Object.keys(e)}function R(e){return Object.entries(e)}function f(e,...n){if(!n.length)return e;let[t,...r]=n;if(t===void 0)return e;if(c(e)&&c(t))d(t).forEach((o)=>{if(c(t[o])){if(!e[o])e[o]={};f(e[o],t[o])}else e[o]=t[o]});return f(e,...r)}function c(e){return p(e)&&!Array.isArray(e)}function S(e,n,t=!1){return n.reduce((r,o)=>{if(o in e){if(!t||e[o]!==void 0)r[o]=e[o]}return r},{})}function V(e){return Object.keys(e).forEach((n)=>e[n]===void 0&&delete e[n]),e}function v(e,n){return e==null?!1:Object.prototype.hasOwnProperty.call(e,n)}export{V as clearUndefined,f as deepMerge,T as getPath,v as hasOwnProperty,j as invert,K as isEmptyObject,w as isKeyOf,b as mapKeys,x as mapValues,R as objectEntries,d as objectKeys,m as objectMap,S as objectPick,k as omit,l as omitBy,a as pickBy,y as setPath};

package/dist/transform.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Reshaping an object: selecting parts of it, rewriting its keys or values,
+ * reading and writing through a path.
+ *
+ * The counterpart to `arrays/src/transform.ts`, and the same answer to the same
+ * request (stacksjs/stacks#412): the operations an application kept writing
+ * inline, implemented in the package that already owns this surface rather than
+ * imported from a second utility library.
+ *
+ * Everything here is immutable and shallow unless its own documentation says
+ * otherwise. Only an object's own enumerable string keys are visited -
+ * inherited and symbol keys are left alone, which matches `Object.entries` and
+ * is what stops a plain-object helper from wandering into a prototype.
+ */
+/**
+ * A copy without the given keys.
+ *
+ * The inverse of `objectPick`. Keys that are not present are ignored rather
+ * than an error, so a caller can omit a superset without checking first.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * omit({ a: 1, b: 2, c: 3 }, ['b']) // { a: 1, c: 3 }
+ * ```
+ */
+export declare function omit<O extends object, K extends keyof O>(obj: O, keys: readonly K[]): Omit<O, K>;
+/**
+ * A copy keeping only the entries the predicate accepts.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * pickBy({ a: 1, b: 2 }, value => value > 1) // { b: 2 }
+ * ```
+ */
+export declare function pickBy<O extends object>(obj: O, predicate: (value: O[keyof O], key: keyof O & string) => boolean): Partial<O>;
+/**
+ * A copy dropping the entries the predicate accepts.
+ *
+ * The complement of {@link pickBy} - the same predicate partitions an object
+ * between the two.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * omitBy({ a: 1, b: undefined }, value => value === undefined) // { a: 1 }
+ * ```
+ */
+export declare function omitBy<O extends object>(obj: O, predicate: (value: O[keyof O], key: keyof O & string) => boolean): Partial<O>;
+/**
+ * A copy with every value replaced by what `transform` returns.
+ *
+ * Keys are untouched, which is what distinguishes this from `objectMap` and
+ * makes the result's type exact: `Record<keyof O, R>` rather than something
+ * that depends on what the callback did with the key.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * mapValues({ a: 1, b: 2 }, value => value * 10) // { a: 10, b: 20 }
+ * ```
+ */
+export declare function mapValues<O extends object, R>(obj: O, transform: (value: O[keyof O], key: keyof O & string) => R): { [K in keyof O]: R };
+/**
+ * A copy with every key replaced by what `transform` returns.
+ *
+ * Two keys can collide once rewritten; the last one visited wins, matching what
+ * an assignment loop would do.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * mapKeys({ a: 1, b: 2 }, key => key.toUpperCase()) // { A: 1, B: 2 }
+ * ```
+ */
+export declare function mapKeys<O extends object, K extends PropertyKey>(obj: O, transform: (key: keyof O & string, value: O[keyof O]) => K): Record<K, O[keyof O]>;
+/**
+ * Swap keys and values.
+ *
+ * Every value becomes a key, so values are coerced to strings by the assignment
+ * - `{ a: 1 }` inverts to `{ '1': 'a' }`. Duplicate values collapse, last one
+ * winning, which is why this is only meaningful for an object whose values are
+ * unique.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * invert({ a: 'x', b: 'y' }) // { x: 'a', y: 'b' }
+ * ```
+ */
+export declare function invert<O extends Record<string, PropertyKey>>(obj: O): Record<string, keyof O & string>;
+/**
+ * Whether an object has no own enumerable string keys.
+ *
+ * Named for what it checks rather than the broader "is this empty" this could
+ * have been: a single helper that also answers for strings, arrays, Maps and
+ * Sets reads well at the call site and badly everywhere else, because the
+ * reader cannot tell which question is being asked.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * isEmptyObject({})       // true
+ * isEmptyObject({ a: 1 }) // false
+ * ```
+ */
+export declare function isEmptyObject(obj: object): boolean;
+/**
+ * Read through a path, answering `fallback` when any step is missing.
+ *
+ * The path is an array of steps rather than a dotted string, deliberately: a
+ * dotted string cannot express a key that contains a dot, and every
+ * implementation that parses one eventually has to grow an escape syntax.
+ *
+ * A `null` or `undefined` anywhere along the way ends the walk and yields the
+ * fallback, so this never throws on a partially-populated object - which is the
+ * entire reason to use it instead of `a?.b?.c`.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * getPath({ a: { b: [10, 20] } }, ['a', 'b', 1], 0) // 20
+ * getPath({ a: {} }, ['a', 'b', 'c'], 'default')    // 'default'
+ * ```
+ */
+export declare function getPath<T>(source: unknown, path: readonly PathStep[], fallback: T): T;
+export declare function getPath(source: unknown, path: readonly PathStep[]): unknown;
+/**
+ * A copy with the value at `path` replaced, creating missing steps on the way.
+ *
+ * Only the objects along the path are copied - siblings are shared with the
+ * original, which is what makes this cheap enough to use on every update. A
+ * numeric step creates an array where a step is missing, so
+ * `setPath({}, ['items', 0], x)` produces `{ items: [x] }` rather than
+ * `{ items: { 0: x } }`.
+ *
+ * @category Object
+ * @example
+ * ```ts
+ * setPath({ a: { b: 1 } }, ['a', 'b'], 2)  // { a: { b: 2 } }
+ * setPath({}, ['a', 'b'], 1)               // { a: { b: 1 } }
+ * ```
+ */
+export declare function setPath<O extends object>(source: O, path: readonly PathStep[], value: unknown): O;
+/** One step of a path: an object key or an array index. */
+export type PathStep = string | number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/objects",
   "type": "module",
-  "version": "0.74.32",
+  "version": "0.74.34",
   "description": "The Stacks objects.",
   "author": "Chris Breuer",
   "contributors": [
@@ -56,12 +56,12 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/utils": "0.74.32",
-    "@stacksjs/validation": "0.74.32"
+    "@stacksjs/utils": "0.74.34",
+    "@stacksjs/validation": "0.74.34"
   },
   "devDependencies": {
-    "@stacksjs/collections": "0.74.32",
-    "@stacksjs/types": "0.74.32",
+    "@stacksjs/collections": "0.74.34",
+    "@stacksjs/types": "0.74.34",
     "better-dx": "^0.2.24"
   },
   "sideEffects": false