@helpers4/object 3.0.0-alpha.1 → 3.0.0

package/lib/index.js

@@ -4,6 +4,44 @@ var UNSAFE_KEYS = /* @__PURE__ */ new Set([
 	"prototype"
 ]);
 //#endregion
+//#region helpers/object/clone.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Creates a shallow copy of a value — one level deep, unlike {@link cloneDeep}.
+*
+* Unlike a plain `{ ...value }` spread, this correctly reconstructs `Date`,
+* `Map`, `Set`, and arrays instead of producing an empty (or wrong-shaped)
+* plain object for them. Primitives are returned as-is. Any other object
+* (including class instances not listed above) has its own enumerable string
+* keys shallow-copied into a plain object — the same fallback `cloneDeep`
+* uses, so the two stay consistent for types neither one special-cases.
+*
+* @param value - The value to shallow-clone
+* @returns A shallow copy of `value`
+* @example
+* clone({ a: { b: 1 } })
+* // => { a: { b: 1 } } — new object, but `a` is the *same* nested reference
+* @example
+* clone(new Date('2024-01-01')) // => new Date with the same timestamp
+* clone(new Map([['a', 1]]))    // => new Map with the same entries
+* clone([1, 2, 3])              // => new array, same elements
+* @since 3.0.0
+*/
+function clone(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (value instanceof Date) return new Date(value.getTime());
+	if (value instanceof Map) return new Map(value);
+	if (value instanceof Set) return new Set(value);
+	if (Array.isArray(value)) return [...value];
+	const result = {};
+	for (const key of Object.keys(value)) if (!UNSAFE_KEYS.has(key)) result[key] = value[key];
+	return result;
+}
+//#endregion
 //#region helpers/object/cloneDeep.ts
 /**
 * This file is part of helpers4.
@@ -166,10 +204,14 @@ function normalizeTimestamp(timestamp) {
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 /**
-* Type guard that checks whether a value satisfies the {@link EpochMilliseconds}
-* structural interface (e.g. `Temporal.Instant`, `Temporal.ZonedDateTime`).
+* Type guard that checks whether a value is a `Temporal.Instant` or
+* `Temporal.ZonedDateTime`.
+*
+* Duck-types the `epochMilliseconds` property rather than using `instanceof`,
+* so values crossing a realm boundary (vm context, worker, iframe) are still
+* recognized correctly.
 */
-function hasEpochMilliseconds(value) {
+function isEpochMillisecondsLike(value) {
 	return typeof value === "object" && value !== null && "epochMilliseconds" in value && typeof value.epochMilliseconds === "number";
 }
 /**
@@ -200,7 +242,7 @@ function hasEpochMilliseconds(value) {
 function ensureDate(input) {
 	if (input === null || input === void 0 || input === "" || input === 0) return null;
 	if (input instanceof Date) return isNaN(input.getTime()) ? null : input;
-	if (hasEpochMilliseconds(input)) {
+	if (isEpochMillisecondsLike(input)) {
 		const date = new Date(input.epochMilliseconds);
 		return isNaN(date.getTime()) ? null : date;
 	}
@@ -445,43 +487,92 @@ function equalsShallow(objA, objB) {
 	return true;
 }
 //#endregion
-//#region helpers/object/_parsePath.ts
+//#region helpers/object/flatten.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
+function flattenInto(obj, prefix, result) {
+	for (const [key, value] of Object.entries(obj)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (isPlainObject(value) && Object.keys(value).length > 0) flattenInto(value, path, result);
+		else result[path] = value;
+	}
+}
 /**
-* Parses a string path into an array of string/number segments.
+* Flattens a nested object into a single-level object whose keys are the
+* dot-notation path to each leaf value. The inverse of {@link unflatten}.
+*
+* Only **plain objects** are recursed into — arrays, `Date`, `Map`, `RegExp`,
+* class instances, and empty plain objects `{}` are kept as opaque leaf
+* values. This keeps `flatten`/`unflatten` a clean, invertible pair: arrays
+* can't be losslessly told apart from plain objects once reduced to dotted
+* keys, so this implementation doesn't attempt it.
+*
+* Caveat shared by every dotted-path flattening scheme: a key that itself
+* contains a literal `.` is indistinguishable from real nesting once
+* flattened (`{ 'a.b': 1 }` and `{ a: { b: 1 } }` both produce `{ 'a.b': 1 }`).
+*
+* @param obj - The object to flatten
+* @returns A single-level object with dot-notation keys
+* @example
+* flatten({ a: { b: { c: 1 }, d: 2 } })
+* // => { 'a.b.c': 1, 'a.d': 2 }
+* @example
+* flatten({ a: [1, 2], b: new Date(0) })
+* // => { a: [1, 2], b: Date }  (arrays and special objects stay as leaves)
+* @since 3.0.0
+*/
+function flatten(obj) {
+	const result = {};
+	flattenInto(obj, "", result);
+	return result;
+}
+//#endregion
+//#region helpers/object/parsePropertyPath.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+var BRACKET = /\[(\d+)\]/g;
+var MAX_CACHE_SIZE = 500;
+var pathCache = /* @__PURE__ */ new Map();
+/**
+* Parses a dot/bracket-notation property path into an array of string/number
+* key segments — the same notation accepted by {@link get} and {@link set}.
 *
 * - Dot separators (`.`) split segments; each segment becomes a string key.
 * - Bracket indices (`[n]`) become number keys.
 * - A leading `.` is treated as "current level" and stripped before parsing,
 *   so `.[0]` ≡ `[0]` and `.a.b` ≡ `a.b`.
-* - Empty string (or bare `.`) returns `['']` (addresses the `''` key on the root object).
+* - Empty string (or a bare `.`) returns `['']` (addresses the `''` key on the root object).
 * - Consecutive dots (`a..b`) produce an empty-string segment: `['a', '', 'b']`.
-* - Non-bracket text trailing a `]` within the same dot-segment throws a RangeError;
-*   use a dot separator instead (`'a[0].b'` not `'a[0]b'`).
 *
-* @ignore
+* Results are cached (up to 500 distinct path strings, oldest evicted first)
+* since real-world callers tend to reuse a small, fixed set of literal paths.
+*
+* @param path - The dot/bracket-notation path string to parse
+* @returns The parsed key segments
+* @throws {RangeError} When non-bracket text trails the last `]` within a
+*   dot-segment (e.g. `'a[0]b'` is ambiguous — use `'a[0].b'` instead)
 * @example
-* parsePath('a.b.c')       // => ['a', 'b', 'c']        (all strings)
-* parsePath('layers.1.x')  // => ['layers', '1', 'x']   (all strings)
-* parsePath('layers[1].x') // => ['layers', 1, 'x']     (bracket → number)
-* parsePath('.[0]')        // => [0]                     (leading dot stripped)
-* parsePath('a..b')        // => ['a', '', 'b']          (empty segment preserved)
-* parsePath('.')           // => ['']                    (leading dot → empty-string key)
+* parsePropertyPath('a.b.c')       // => ['a', 'b', 'c']
+* parsePropertyPath('layers[1].x') // => ['layers', 1, 'x']
+* parsePropertyPath('.[0]')        // => [0]              (leading dot stripped)
+* parsePropertyPath('a..b')        // => ['a', '', 'b']   (empty segment preserved)
+* @since 3.0.0
 */
-var BRACKET = /\[(\d+)\]/g;
-var parsePathCache = /* @__PURE__ */ new Map();
-function parsePath(path) {
-	const cached = parsePathCache.get(path);
+function parsePropertyPath(path) {
+	const cached = pathCache.get(path);
 	if (cached !== void 0) return cached;
-	const result = Object.freeze(parsePathUncached(path));
-	parsePathCache.set(path, result);
+	const result = Object.freeze(parseUncached(path));
+	if (pathCache.size >= MAX_CACHE_SIZE) pathCache.delete(pathCache.keys().next().value);
+	pathCache.set(path, result);
 	return result;
 }
-function parsePathUncached(path) {
+function parseUncached(path) {
 	if (path === "") return [""];
 	if (path[0] === ".") path = path.slice(1);
 	if (path === "") return [""];
@@ -496,7 +587,7 @@ function parsePathUncached(path) {
 			last = BRACKET.lastIndex;
 		}
 		if (last === 0) result.push(dotSegment);
-		else if (last < dotSegment.length) throw new RangeError(`parsePath: non-bracket text '${dotSegment.slice(last)}' after ']' in segment '${dotSegment}' — use 'a[0].b' instead of 'a[0]b'`);
+		else if (last < dotSegment.length) throw new RangeError(`parsePropertyPath: non-bracket text '${dotSegment.slice(last)}' after ']' in segment '${dotSegment}' — use 'a[0].b' instead of 'a[0]b'`);
 	}
 	return result;
 }
@@ -509,7 +600,7 @@ function parsePathUncached(path) {
 */
 function get(obj, path, defaultValue) {
 	if (obj == null) return defaultValue;
-	const keys = typeof path === "string" ? parsePath(path) : path;
+	const keys = typeof path === "string" ? parsePropertyPath(path) : path;
 	let result = obj;
 	for (const key of keys) {
 		if (result == null || typeof result !== "object") return defaultValue;
@@ -728,6 +819,37 @@ function omit(obj, keys) {
 	return result;
 }
 //#endregion
+//#region helpers/object/omitBy.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Creates a new object without the own enumerable entries for which
+* `predicate` returns `true`.
+*
+* Complements {@link omit} for when the keys to remove aren't known ahead of
+* time — `omit` takes an explicit key list, `omitBy` takes a predicate.
+*
+* @param obj - The source object. `null`/`undefined` pass through unchanged.
+* @param predicate - Called with `(value, key)` for each own enumerable entry
+* @returns A new object without the matching entries
+* @example
+* omitBy({ a: 1, b: undefined, c: 2 }, (value) => value === undefined)
+* // => { a: 1, c: 2 }
+* @since 3.0.0
+*/
+function omitBy(obj, predicate) {
+	if (obj == null) return obj;
+	const result = {};
+	for (const key of Object.keys(obj)) {
+		const typedKey = key;
+		if (!predicate(obj[typedKey], typedKey)) result[key] = obj[typedKey];
+	}
+	return result;
+}
+//#endregion
 //#region helpers/object/pick.ts
 /**
 * This file is part of helpers4.
@@ -744,6 +866,38 @@ function pick(obj, keys) {
 	return result;
 }
 //#endregion
+//#region helpers/object/pickBy.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Creates a new object with only the own enumerable entries for which
+* `predicate` returns `true`.
+*
+* Complements {@link pick} for when the keys to keep aren't known ahead of
+* time — `pick` takes an explicit key list, `pickBy` takes a predicate.
+*
+* @param obj - The source object. `null`/`undefined` pass through unchanged.
+* @param predicate - Called with `(value, key)` for each own enumerable entry
+* @returns A new object with only the matching entries
+* @example
+* pickBy({ a: 1, b: 0, c: 2 }, (value) => value > 0)
+* // => { a: 1, c: 2 }
+* @since 3.0.0
+*/
+function pickBy(obj, predicate) {
+	if (obj == null) return obj;
+	const result = {};
+	for (const key of Object.keys(obj)) {
+		if (UNSAFE_KEYS.has(key)) continue;
+		const typedKey = key;
+		if (predicate(obj[typedKey], typedKey)) result[key] = obj[typedKey];
+	}
+	return result;
+}
+//#endregion
 //#region helpers/guard/isNullish.ts
 /**
 * This file is part of helpers4.
@@ -804,7 +958,7 @@ function safeJsonParse(input, fallback) {
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 function set(obj, path, value) {
-	const keys = typeof path === "string" ? parsePath(path) : path;
+	const keys = typeof path === "string" ? parsePropertyPath(path) : path;
 	if (keys.length === 0) return obj;
 	if (keys.some((k) => typeof k === "string" && UNSAFE_KEYS.has(k))) return obj;
 	let current = obj;
@@ -817,6 +971,85 @@ function set(obj, path, value) {
 	return obj;
 }
 //#endregion
-export { cloneDeep, compact, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, pick, removeUndefinedNull, safeJsonParse, set };
+//#region helpers/object/unflatten.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Rebuilds a nested object from a single-level object whose keys are
+* dot-notation paths. The inverse of {@link flatten}.
+*
+* Uses {@link set} internally, so intermediate nodes are always created as
+* plain objects (never arrays — see {@link flatten}'s doc for why), and any
+* key segment equal to `__proto__`, `constructor`, or `prototype` is silently
+* rejected (same prototype-pollution guard as `set`).
+*
+* @param obj - A single-level object with dot-notation keys
+* @returns The rebuilt nested object
+* @example
+* unflatten({ 'a.b.c': 1, 'a.d': 2 })
+* // => { a: { b: { c: 1 }, d: 2 } }
+* @since 3.0.0
+*/
+function unflatten(obj) {
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) set(result, key, value);
+	return result;
+}
+//#endregion
+//#region helpers/object/unset.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Removes the value at a dot/bracket-notation path or explicit key array,
+* mutating the object in place. Uses the same path syntax as {@link get}/{@link set}.
+*
+* A missing intermediate segment is a no-op (nothing to remove), not an error.
+* As with `set`, any path containing a string segment equal to `__proto__`,
+* `constructor`, or `prototype` is rejected and the object is returned unchanged.
+*
+* The removed key stops appearing in `Object.keys`/`for...in` — unlike setting
+* it to `undefined`, which would keep the key present.
+*
+* @param obj - The object to mutate
+* @param path - Dot/bracket-notation string, or explicit `PropertyKey[]`
+* @returns The same object reference, with the key removed if it existed
+* @example
+* unset({ a: { b: 1, c: 2 } }, 'a.b')
+* // => { a: { c: 2 } }
+* @example
+* unset({ a: 1 }, 'x.y') // path doesn't exist — no-op
+* // => { a: 1 }
+* @since 3.0.0
+*/
+function unset(obj, path) {
+	const keys = typeof path === "string" ? parsePropertyPath(path) : path;
+	if (keys.length === 0) return obj;
+	if (keys.some((key) => typeof key === "string" && UNSAFE_KEYS.has(key))) return obj;
+	let current = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		if (current == null || typeof current !== "object") return obj;
+		current = current[keys[i]];
+	}
+	if (current != null && typeof current === "object") delete current[keys[keys.length - 1]];
+	return obj;
+}
+//#endregion
+//#region helpers/object/update.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function update(obj, path, updater) {
+	return set(obj, path, updater(get(obj, path)));
+}
+//#endregion
+export { clone, cloneDeep, compact, diff, equalsDeep, equalsShallow, flatten, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, omitBy, parsePropertyPath, pick, pickBy, removeUndefinedNull, safeJsonParse, set, unflatten, unset, update };
 
 //# sourceMappingURL=index.js.map