@stacksjs/objects 0.75.445 → 0.75.450

package/README.md

@@ -69,3 +69,17 @@ Many thanks to the following core technologies & people who have contributed to
 The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
 
 Made with 💙
+
+## Object boundary contracts
+
+`objectKeys` and `objectEntries` report string keys, including numeric property names,
+and omit symbols. `mapValues` visits own enumerable string entries; its return type
+excludes symbols and preserves optional properties. `getPath` returns `unknown`,
+including when a fallback is supplied: narrow the result before using it as a number
+or string. A fallback does not determine the type of a present property.
+
+`setPath(array, ['length'], n)` applies native array-length rules to a copy. Invalid
+lengths throw without changing the original. A plain source record replaces a nested
+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.

package/dist/index.d.ts

@@ -36,18 +36,13 @@ export declare function objectMap<K extends string, V, NK extends PropertyKey =
  * @param k key to check existence in `obj`
  */
 export declare function isKeyOf<T extends object>(obj: T, k: keyof any): k is keyof T;
-/**
- * Strict typed `Object.keys`
- *
- * @category Object
- */
-export declare function objectKeys<T extends object>(obj: T): boolean;
+export declare function objectKeys<T extends object>(obj: T): Array<ObjectStringKey<T>>;
 /**
  * Strict typed `Object.entries`
  *
  * @category Object
  */
-export declare function objectEntries<T extends object>(obj: T): boolean;
+export declare function objectEntries<T extends object>(obj: T): Array<ObjectStringEntry<T>>;
 /**
  * Deep merge :P
  *
@@ -83,4 +78,11 @@ export declare function clearUndefined<T extends object>(obj: T): T;
  * @category Object
  */
 export declare function hasOwnProperty<T>(obj: T, v: PropertyKey): boolean;
+/**
+ * Strict typed `Object.keys`
+ *
+ * @category Object
+ */
+export type ObjectStringKey<T extends object> = `${Extract<keyof T, string | number>}`;
+export type ObjectStringEntry<T extends object> = [ObjectStringKey<T>, T[Extract<keyof T, string | number>]];
 export * from './transform';

package/dist/index.js

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

package/dist/transform.d.ts

@@ -54,20 +54,7 @@ export declare function pickBy<O extends object>(obj: O, predicate: (value: O[ke
  * ```
  */
 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 };
+export declare function mapValues<O extends object, R>(obj: O, transform: (value: O[Extract<keyof O, string | number>], key: `${Extract<keyof O, string | number>}`) => R): MappedStringValues<O, R>;
 /**
  * A copy with every key replaced by what `transform` returns.
  *
@@ -130,8 +117,7 @@ export declare function isEmptyObject(obj: object): boolean;
  * 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;
+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.
  *
@@ -149,5 +135,19 @@ export declare function getPath(source: unknown, path: readonly PathStep[]): unk
  * ```
  */
 export declare function setPath<O extends object>(source: O, path: readonly PathStep[], value: unknown): 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 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;

package/dist/transform.js

@@ -0,0 +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})}

package/package.json

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