@stacksjs/objects 0.75.451 → 0.75.457

package/README.md

@@ -83,3 +83,18 @@ lengths throw without changing the original. A plain source record replaces a ne
 Date, Map, Set or class target during `deepMerge`; those targets are not containers
 for JSON fields. The package ships both its root and the narrow `objects/transform`
 entry as JavaScript and declarations.
+
+`omit` normalizes numeric exclusions. `objectMap` returns a partial record because
+callbacks may remove entries. `setPath` preserves sparse slots and own enumerable
+array siblings; its `SetPathResult` type follows known paths, with `unknown` for
+dynamic paths and the replacement type for an empty path.
+
+`deepMerge` tracks plain-record graphs per source overlay, preserving cycles and
+sharing each source node's first destination. It updates the same target; arrays
+and non-plain values remain atomic. Later sources use fresh graph tracking.
+
+Path inference normalizes numeric/string aliases and distributes finite union
+steps. Broad string/number/template steps and open index-signature object sources
+return `unknown`; narrow before using them. Length changes drop fixed tuple index
+guarantees, and generic array results include possible holes. Numeric-looking
+named siblings such as `-1` and `1.5` retain their own value types.

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 extends PropertyKey = K, NV = V>(obj: Record<K, V>, fn: (key: K, value: V) => [NK, NV] | undefined): Record<NK, NV>;
+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): Partial<Record<NK, NV>>;
 /**
  * Type guard for any key, `k`.
  * Marks `k` as a key of `T` if `k` is in `obj`.

package/dist/index.js

@@ -1 +1 @@
-import{notNullish}from"@stacksjs/utils";import{isObject}from"@stacksjs/validation";export*from"./transform";export function objectMap(obj,fn){return Object.fromEntries(Object.entries(obj).map(([k,v])=>fn(k,v)).filter(notNullish))}export function isKeyOf(obj,k){return k in obj}export function objectKeys(obj){return Object.keys(obj)}export function objectEntries(obj){return Object.entries(obj)}export function deepMerge(target,...sources){if(!sources.length)return target;const[source,...remaining]=sources;if(source===void 0)return target;if(isMergeableObject(target)&&isMergeableObject(source)){const into=target,from=source;for(const key of Object.keys(from)){if(key==="__proto__")continue;if(isPlainObject(from[key])){if(!Object.hasOwn(into,key)||!isPlainObject(into[key]))into[key]={};deepMerge(into[key],from[key])}else into[key]=from[key]}}return deepMerge(target,...remaining)}function isMergeableObject(item){return isObject(item)&&!Array.isArray(item)}function isPlainObject(item){if(typeof item!=="object"||item===null)return!1;const proto=Object.getPrototypeOf(item);return proto===null||proto===Object.prototype||Object.getPrototypeOf(proto)===null}export function objectPick(obj,keys,omitUndefined=!1){return Object.fromEntries(keys.filter((key)=>(key in obj)&&(!omitUndefined||obj[key]!==void 0)).map((key)=>[key,obj[key]]))}export function clearUndefined(obj){Object.keys(obj).forEach((key)=>obj[key]===void 0&&delete obj[key]);return obj}export function hasOwnProperty(obj,v){return obj==null?!1:Object.prototype.hasOwnProperty.call(obj,v)}
+import{notNullish}from"@stacksjs/utils";import{isObject}from"@stacksjs/validation";export*from"./transform";export function objectMap(obj,fn){return Object.fromEntries(Object.entries(obj).map(([k,v])=>fn(k,v)).filter(notNullish))}export function isKeyOf(obj,k){return k in obj}export function objectKeys(obj){return Object.keys(obj)}export function objectEntries(obj){return Object.entries(obj)}export function deepMerge(target,...sources){for(const source of sources)if(isMergeableObject(target)&&isMergeableObject(source))mergeGraph(target,source,new WeakMap);return target}function mergeGraph(into,from,seen){seen.set(from,into);for(const key of Object.keys(from)){if(key==="__proto__")continue;const value=from[key];let merged=value;if(isPlainObject(value)){const mapped=seen.get(value);if(mapped)merged=mapped;else{const existing=Object.hasOwn(into,key)?into[key]:void 0,child=isPlainObject(existing)?existing:{};mergeGraph(child,value,seen);merged=child}}if(Object.hasOwn(into,key))into[key]=merged;else Object.defineProperty(into,key,{value:merged,writable:!0,enumerable:!0,configurable:!0})}}function isMergeableObject(item){return isObject(item)&&!Array.isArray(item)}function isPlainObject(item){if(typeof item!=="object"||item===null)return!1;const proto=Object.getPrototypeOf(item);if(proto===null||proto===Object.prototype)return!0;if(Object.getPrototypeOf(proto)!==null)return!1;const constructor=Object.getOwnPropertyDescriptor(proto,"constructor")?.value;return typeof constructor==="function"&&Function.prototype.toString.call(constructor)===Function.prototype.toString.call(Object)}export function objectPick(obj,keys,omitUndefined=!1){return Object.fromEntries(keys.filter((key)=>(key in obj)&&(!omitUndefined||obj[key]!==void 0)).map((key)=>[key,obj[key]]))}export function clearUndefined(obj){Object.keys(obj).forEach((key)=>obj[key]===void 0&&delete obj[key]);return obj}export function hasOwnProperty(obj,v){return obj==null?!1:Object.prototype.hasOwnProperty.call(obj,v)}

package/dist/transform.d.ts

@@ -118,23 +118,7 @@ export declare function isEmptyObject(obj: object): boolean;
  * ```
  */
 export declare function getPath(source: unknown, path: readonly PathStep[], fallback?: unknown): 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;
+export declare function setPath<O extends object, const Path extends readonly PathStep[], V>(source: O, path: Path, value: V): SetPathResult<O, Path, V>;
 /**
  * A copy with every value replaced by what `transform` returns.
  *
@@ -151,3 +135,48 @@ export declare function setPath<O extends object>(source: O, path: readonly Path
 export type MappedStringValues<O extends object, R> = { [K in keyof O as K extends string | number ? K : never]: R }
 /** One step of a path: an object key or an array index. */
 export type PathStep = string | number;
+/**
+ * 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 } }
+ * ```
+ */
+declare type KeyName<K> = K extends number ? `${K}` : K;
+declare type MatchingKeys<S, K> = { [P in keyof S]-?: KeyName<P> extends KeyName<K> ? P : never }[keyof S];
+declare type PathChild<S, K extends PropertyKey> = [MatchingKeys<S, K>] extends [never] ? undefined : S[MatchingKeys<S, K>];
+declare type ArraySiblings<S extends readonly unknown[]> = Omit<S, keyof [...S]>;
+declare type UpdatedArray<S extends readonly unknown[], K extends PathStep, Rest extends readonly PathStep[], V> = Array<S[number] | SetPathResult<PathChild<S, K>, Rest, V> | undefined>
+  & Omit<ArraySiblings<S>, MatchingKeys<ArraySiblings<S>, K>>
+  & { [P in K]: SetPathResult<PathChild<S, P>, Rest, V> }
+declare type ArrayPathResult<S extends readonly unknown[], K extends PathStep, Rest extends readonly PathStep[], V> = K extends 'length' ? Array<S[number] | undefined> & Partial<ArraySiblings<S>>
+    : K extends number | `${number}`
+      ? number extends S['length'] ? UpdatedArray<S, K, Rest, V>
+        : `${K}` extends keyof S
+          ? { [I in keyof S]: I extends `${K}` ? SetPathResult<S[I], Rest, V> : S[I] }
+          : UpdatedArray<S, K, Rest, V>
+      : Omit<S, MatchingKeys<S, K>> & { [P in K]: SetPathResult<PathChild<S, P>, Rest, V> }
+/** Known paths describe their updated shape; arbitrary or patterned steps return unknown. */
+export type SetPathResult<S, Path extends readonly PathStep[], V> = number extends Path['length'] ? unknown
+    : Path extends readonly [] ? V
+      : Path extends readonly [infer K extends PathStep, ...infer Rest extends readonly PathStep[]]
+        ? K extends unknown
+          // An empty object satisfies open index signatures, but not a required literal key.
+          ? {} extends Record<K, never> ? unknown
+            : S extends readonly unknown[] ? ArrayPathResult<S, K, Rest, V>
+              : S extends object ? string extends keyof S ? unknown
+                : number extends keyof S ? unknown
+                  : Omit<S, MatchingKeys<S, K>> & { [P in K]: SetPathResult<PathChild<S, P>, Rest, V> }
+                : K extends number ? ArrayPathResult<never[], K, Rest, V>
+                  : { [P in K]: SetPathResult<undefined, Rest, V> }
+          : never
+        : unknown;

package/dist/transform.js

@@ -1 +1 @@
-export function omit(obj,keys){const excluded=new Set(keys);return Object.fromEntries(Object.entries(obj).filter(([key])=>!excluded.has(key)))}export function pickBy(obj,predicate){return Object.fromEntries(Object.entries(obj).filter(([key,value])=>predicate(value,key)))}export function omitBy(obj,predicate){return pickBy(obj,(value,key)=>!predicate(value,key))}export function mapValues(obj,transform){return Object.fromEntries(Object.entries(obj).map(([key,value])=>[key,transform(value,key)]))}export function mapKeys(obj,transform){return Object.fromEntries(Object.entries(obj).map(([key,value])=>[transform(key,value),value]))}export function invert(obj){return Object.fromEntries(Object.entries(obj).map(([key,value])=>[String(value),key]))}export function isEmptyObject(obj){for(const _key in obj)if(Object.hasOwn(obj,_key))return!1;return!0}export function getPath(source,path,fallback){let current=source;for(const step of path){if(current===null||current===void 0)return fallback;current=current[step]}return current===void 0?fallback:current}export function setPath(source,path,value){if(path.length===0)return value;const[step,...rest]=path,container=Array.isArray(source)?[...source]:{...source};if(rest.length===0){defineKey(container,step,value);return container}const existing=Object.hasOwn(container,step)?container[step]:void 0,child=existing===null||typeof existing!=="object"?typeof rest[0]==="number"?[]:{}:existing;defineKey(container,step,setPath(child,rest,value));return container}function defineKey(target,key,value){if(Array.isArray(target)&&key==="length"){Object.defineProperty(target,key,{value});return}Object.defineProperty(target,key,{value,writable:!0,enumerable:!0,configurable:!0})}
+export function omit(obj,keys){const excluded=new Set(keys.map((key)=>typeof key==="number"?String(key):key));return Object.fromEntries(Object.entries(obj).filter(([key])=>!excluded.has(key)))}export function pickBy(obj,predicate){return Object.fromEntries(Object.entries(obj).filter(([key,value])=>predicate(value,key)))}export function omitBy(obj,predicate){return pickBy(obj,(value,key)=>!predicate(value,key))}export function mapValues(obj,transform){return Object.fromEntries(Object.entries(obj).map(([key,value])=>[key,transform(value,key)]))}export function mapKeys(obj,transform){return Object.fromEntries(Object.entries(obj).map(([key,value])=>[transform(key,value),value]))}export function invert(obj){return Object.fromEntries(Object.entries(obj).map(([key,value])=>[String(value),key]))}export function isEmptyObject(obj){for(const _key in obj)if(Object.hasOwn(obj,_key))return!1;return!0}export function getPath(source,path,fallback){let current=source;for(const step of path){if(current===null||current===void 0)return fallback;current=current[step]}return current===void 0?fallback:current}export function setPath(source,path,value){if(path.length===0)return value;const[step,...rest]=path,container=Array.isArray(source)?copyArray(source):{...source};if(rest.length===0){defineKey(container,step,value);return container}const existing=Object.hasOwn(container,step)?container[step]:void 0,child=existing===null||typeof existing!=="object"?typeof rest[0]==="number"?[]:{}:existing;defineKey(container,step,setPath(child,rest,value));return container}function copyArray(source){const copy=Array(source.length);for(const key of Reflect.ownKeys(source)){if(!Object.prototype.propertyIsEnumerable.call(source,key))continue;defineKey(copy,key,source[key])}return copy}function defineKey(target,key,value){if(Array.isArray(target)&&key==="length"){Object.defineProperty(target,key,{value});return}Object.defineProperty(target,key,{value,writable:!0,enumerable:!0,configurable:!0})}

package/package.json

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