@lowdefy/helpers 5.5.1 → 5.6.0

package/dist/extractErrorProps.js

@@ -16,62 +16,121 @@
     const proto = Object.getPrototypeOf(val);
     return proto === Object.prototype || proto === null;
 }
+// `||`, not `??`: an anonymous class has the empty string as its constructor
+// name, not undefined, and a marker whose only payload is the type name must
+// not be emitted as '[Object: ]'.
+function classInstanceMarker(val) {
+    return `[Object: ${val.constructor?.name || 'unknown'}]`;
+}
+// A function is never passed through: `get` would hand a live closure over
+// server state to app config. (serializer.copy only throws on a function at
+// the top level; nested, it silently drops the key or turns it into null in
+// an array - since this output is always an object, that vanished key, not a
+// throw, was the real pre-fix failure.) Same empty-string fallback as
+// classInstanceMarker - an anonymous function's `name` is '' rather than
+// undefined.
+function functionMarker(val) {
+    return `[Function: ${val.name || 'unknown'}]`;
+}
+// A bigint's digits are its whole content, not internals, so the marker
+// includes the value rather than just naming the type.
+function bigintMarker(val) {
+    return `[BigInt: ${val}]`;
+}
+// `.description` gives the bare description; `String(sym)` would wrap it as
+// 'Symbol(description)', polluting the marker's payload. Same empty-string
+// fallback as the other markers - a descriptionless symbol's `description` is
+// undefined, and `Symbol('')`'s is '', so both must fall back to 'unknown'.
+function symbolMarker(val) {
+    return `[Symbol: ${val.description || 'unknown'}]`;
+}
 const MAX_CAUSE_DEPTH = 3;
 const MAX_OBJECT_DEPTH = 5;
-function cleanValue(val, seen, objectDepth, causeDepth) {
+const NO_OMIT = [];
+function cleanValue(val, seen, objectDepth, causeDepth, omit) {
     if (objectDepth > MAX_OBJECT_DEPTH) return '[Truncated]';
+    if (typeof val === 'function') return functionMarker(val);
+    if (typeof val === 'bigint') return bigintMarker(val);
+    if (typeof val === 'symbol') return symbolMarker(val);
     if (val === null || typeof val !== 'object') return val;
     if (seen.has(val)) return '[Circular]';
     seen.add(val);
     if (Array.isArray(val)) {
-        return val.map((item)=>cleanValue(item, seen, objectDepth + 1, causeDepth));
+        return val.map((item)=>cleanValue(item, seen, objectDepth + 1, causeDepth, omit));
     }
     if (val instanceof Date) return val;
-    if (val instanceof Error) return _extractErrorProps(val, seen, objectDepth, causeDepth);
-    if (!isPlainObject(val)) return `[Object: ${val.constructor?.name ?? 'unknown'}]`;
+    if (val instanceof Error) return _extractErrorProps(val, seen, objectDepth, causeDepth, omit);
+    if (!isPlainObject(val)) return classInstanceMarker(val);
     const cleaned = {};
     for (const [k, v] of Object.entries(val)){
-        const cv = cleanValue(v, seen, objectDepth + 1, causeDepth);
+        const cv = cleanValue(v, seen, objectDepth + 1, causeDepth, omit);
         if (cv !== undefined) cleaned[k] = cv;
     }
     return cleaned;
 }
-function _extractErrorProps(err, seen, objectDepth, causeDepth) {
+function _extractErrorProps(err, seen, objectDepth, causeDepth, omit) {
     if (!err) return err;
     seen.add(err);
-    const props = {
-        message: err.message,
-        name: err.name,
-        stack: err.stack
-    };
-    if (err.cause !== undefined) {
-        if (err.cause instanceof Error && !seen.has(err.cause) && causeDepth < MAX_CAUSE_DEPTH) {
-            props.cause = _extractErrorProps(err.cause, seen, objectDepth, causeDepth + 1);
-        } else if (!(err.cause instanceof Error)) {
-            props.cause = cleanValue(err.cause, seen, objectDepth + 1, causeDepth);
+    // Called at every error node rather than once for the walk, so a caller's
+    // policy can key on the node itself - its class, or its own cause value.
+    // Which fields an audience may see is the caller's decision, never this
+    // walk's; this function only applies the keys it is handed. Omitted fields
+    // are skipped before they are built, so a dropped cause is never deep-copied
+    // and never marked in `seen`.
+    const omitted = omit?.(err) ?? NO_OMIT;
+    const props = {};
+    if (!omitted.includes('message')) props.message = err.message;
+    if (!omitted.includes('name')) props.name = err.name;
+    if (!omitted.includes('stack')) props.stack = err.stack;
+    if (err.cause !== undefined && !omitted.includes('cause')) {
+        if (!(err.cause instanceof Error)) {
+            props.cause = cleanValue(err.cause, seen, objectDepth + 1, causeDepth, omit);
+        } else if (seen.has(err.cause)) {
+            props.cause = '[Circular]';
+        } else if (causeDepth >= MAX_CAUSE_DEPTH) {
+            props.cause = '[Truncated]';
+        } else {
+            props.cause = _extractErrorProps(err.cause, seen, objectDepth, causeDepth + 1, omit);
         }
     }
     for (const key of Object.keys(err)){
-        if (key === 'cause') continue;
+        if (key === 'cause' || omitted.includes(key)) continue;
         const value = err[key];
-        if (value === null || typeof value !== 'object') {
+        if (typeof value === 'function') {
+            props[key] = functionMarker(value);
+        } else if (typeof value === 'bigint') {
+            props[key] = bigintMarker(value);
+        } else if (typeof value === 'symbol') {
+            props[key] = symbolMarker(value);
+        } else if (value === null || typeof value !== 'object') {
             props[key] = value;
         } else if (value instanceof Date) {
             props[key] = value;
         } else if (Array.isArray(value)) {
-            props[key] = cleanValue(value, seen, objectDepth + 1, causeDepth);
+            props[key] = cleanValue(value, seen, objectDepth + 1, causeDepth, omit);
         } else if (value instanceof Error) {
-            if (!seen.has(value)) {
-                props[key] = _extractErrorProps(value, seen, objectDepth, causeDepth);
+            if (seen.has(value)) {
+                props[key] = '[Circular]';
+            } else {
+                props[key] = _extractErrorProps(value, seen, objectDepth, causeDepth, omit);
             }
         } else if (isPlainObject(value)) {
-            props[key] = cleanValue(value, seen, objectDepth + 1, causeDepth);
+            props[key] = cleanValue(value, seen, objectDepth + 1, causeDepth, omit);
+        } else {
+            // A class instance (Socket, Agent, ClientRequest, ...). Its internals are never exposed —
+            // only the type name — but the key must not vanish: an absent key is indistinguishable
+            // from "no such field", and this output is now read by `get` as app-visible config data.
+            props[key] = classInstanceMarker(value);
         }
-    // Skip class instances (Socket, Agent, ClientRequest, etc.)
     }
     return props;
 }
-function extractErrorProps(err) {
-    return _extractErrorProps(err, new Set(), 0, 0);
+// omit: (err) => string[] - the field names to leave off THIS error node, called
+// once per node. Returning 'message' or 'name' is legal but degrades the wire
+// format rather than just trimming it: serializer's propsToError revives a cause
+// as an Error only when it has a `message`, and looks the Lowdefy error class up
+// by `name`. Omit either and a round-trip yields plain objects.
+function extractErrorProps(err, { omit } = {}) {
+    return _extractErrorProps(err, new Set(), 0, 0, omit);
 }
 export default extractErrorProps;

package/dist/get.js

@@ -32,95 +32,86 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
-import typeTest from './type.js';
+import type from './type.js';
+import extractErrorProps from './extractErrorProps.js';
 import serializer from './serializer.js';
-function join(segs, joinChar, options) {
-    if (typeof options.join === 'function') {
-        return options.join(segs);
-    }
-    return segs[0] + joinChar + segs[1];
-}
-function split(path, splitChar, options) {
-    if (typeof options.split === 'function') {
-        return options.split(path);
-    }
-    return path.split(splitChar);
+import splitPath from './splitPath.js';
+import { isReserved, ReservedKeyError } from './ReservedKeyError.js';
+// "May I step into this value to reach a child?" Plain objects, arrays and errors are traversable;
+// functions, Date, URL, Map, Set, RegExp, Promise, Buffer and typed arrays are not, because
+// serializing their internals is information disclosure. Class instances are NOT excluded:
+// type.isObject cannot distinguish them from plain objects, since kindOf maps every
+// `[object Object]` tag to 'object', so an instance's own properties are reachable. Narrowing the
+// predicate is a cross-cutting decision - mergeObjects sits on the same type.isObject boundary -
+// and is tracked separately. Note the predicate cannot close the disclosure case anyway: when the
+// live object is the endpoint of the path it is returned (and under copy, serialized) without
+// isTraversable ever being consulted. Error is handled by forLookup, which converts it to plain
+// data before a lookup.
+// Kept local rather than shared with set/unset - a module imported by all three trips a Jest ESM
+// module-cache bug in operators-js' mocked re-imports.
+function isTraversable(value) {
+    return type.isObject(value) || Array.isArray(value) || value instanceof Error;
 }
-function isValid(key, target, options) {
-    if (typeof options.isValid === 'function') {
-        return options.isValid(key, target);
+// A lookup on an Error reads the error's plain-data form, so `name` resolves (it is own on the
+// extracted props, inherited on the instance) and an own key holding a class instance arrives as
+// a marker rather than a live object. Applied only where a lookup happens, so an error that is
+// the endpoint of the path is returned as an Error - `_actions: x.error` is unchanged.
+function forLookup(value) {
+    if (value instanceof Error) {
+        return extractErrorProps(value);
     }
-    return true;
-}
-function isValidObject(val) {
-    return typeTest.isObject(val) || Array.isArray(val) || typeof val === 'function';
+    return value;
 }
 function getter(target, path, options) {
-    if (typeTest.isNone(path) || !isValidObject(target)) {
-        return typeof options.default !== 'undefined' ? options.default : undefined;
+    if (type.isNone(path) || !isTraversable(target)) {
+        return options.default;
     }
-    if (typeof path === 'number') {
+    if (type.isNumber(path)) {
         path = String(path);
     }
-    const isArray = Array.isArray(path);
-    const isString = typeof path === 'string';
-    const splitChar = options.separator || '.';
-    const joinChar = options.joinChar || (typeof splitChar === 'string' ? splitChar : '.');
-    if (isString && path in target) {
-        return isValid(path, target, options) ? target[path] : options.default;
+    if (!type.isString(path)) {
+        return options.default;
     }
-    const segs = isArray ? path : split(path, splitChar, options);
+    const segs = splitPath(path);
+    // Scanned before the walk so a reserved key is rejected even when it is an own property - the
+    // reserved rule is about illegal input, not about what the target holds. This also means a
+    // literal dotted key whose segments include a reserved name, such as 'a.constructor', throws
+    // rather than resolving; set and unset reject it identically. A rejoined candidate always
+    // contains a dot, so it can never equal a reserved name; scanning the split segments stays
+    // sufficient.
+    const reservedSeg = segs.find(isReserved);
+    if (!type.isNone(reservedSeg)) {
+        throw new ReservedKeyError(reservedSeg);
+    }
+    let current = forLookup(target);
     const len = segs.length;
     let idx = 0;
-    do {
-        let prop = segs[idx];
-        if (typeof prop === 'number') {
-            prop = String(prop);
+    while(idx < len){
+        let candidate = segs[idx];
+        let next = idx + 1;
+        // The strict segment wins if present. On a miss, grow the candidate one segment at a time
+        // looking for a literal dotted key - shortest-first, no backtracking, so segments are
+        // consumed monotonically and the walk stays a single forward pass.
+        while(!Object.hasOwn(current, candidate) && next < len){
+            candidate = `${candidate}.${segs[next]}`;
+            next += 1;
         }
-        while(prop && prop.slice(-1) === '\\'){
-            idx += 1;
-            prop = join([
-                prop.slice(0, -1),
-                segs[idx] || ''
-            ], joinChar, options);
+        if (!Object.hasOwn(current, candidate)) {
+            return options.default;
         }
-        if (prop in target) {
-            if (!isValid(prop, target, options)) {
-                return options.default;
-            }
-            target = target[prop];
-        } else {
-            let hasProp = false;
-            let n = idx + 1;
-            while(n < len){
-                prop = join([
-                    prop,
-                    segs[n]
-                ], joinChar, options);
-                n += 1;
-                hasProp = prop in target;
-                if (hasProp) {
-                    if (!isValid(prop, target, options)) {
-                        return options.default;
-                    }
-                    target = target[prop];
-                    idx = n - 1;
-                    break;
-                }
-            }
-            if (!hasProp) {
+        current = current[candidate];
+        idx = next;
+        if (idx < len) {
+            if (!isTraversable(current)) {
                 return options.default;
             }
+            current = forLookup(current);
         }
-    // eslint-disable-next-line no-plusplus
-    }while (++idx < len && isValidObject(target))
-    if (idx === len) {
-        return target;
     }
-    return options.default;
+    return current;
 }
 function get(target, path, options) {
-    if (!typeTest.isObject(options)) {
+    if (!type.isObject(options)) {
         options = {
             default: options
         };

package/dist/getKey.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import type from './type.js';
+import { isReserved, ReservedKeyError } from './ReservedKeyError.js';
+// Reads a single literal key off a plain object. Dots are not path separators.
+function getKey(target, key, defaultValue) {
+    if (!type.isObject(target)) {
+        throw new TypeError('getKey: target must be a plain object');
+    }
+    if (!type.isString(key)) {
+        throw new TypeError('getKey: key must be a string');
+    }
+    // Rejected even on null-proto targets, where the read would be safe: a caller seeing
+    // ReservedKeyError always knows the key was rejected, regardless of target shape.
+    if (isReserved(key)) {
+        throw new ReservedKeyError(key);
+    }
+    // Own-property read so inherited Object.prototype members never leak as values.
+    if (Object.hasOwn(target, key)) {
+        return target[key];
+    }
+    return defaultValue;
+}
+export default getKey;

package/dist/index.js

@@ -17,19 +17,25 @@ import builtinMessages from './builtinMessages.js';
 import cachedPromises from './cachedPromises.js';
 import extractErrorProps from './extractErrorProps.js';
 import get from './get.js';
+import getKey from './getKey.js';
 import getLocaleDateFormat from './getLocaleDateFormat.js';
 import getLocaleDecimalSeparator from './getLocaleDecimalSeparator.js';
 import getLocaleGroupSeparator from './getLocaleGroupSeparator.js';
+import { isReserved, ReservedKeyError } from './ReservedKeyError.js';
+import joinPath from './joinPath.js';
 import LRUCache from './LRUCache.js';
 import mergeObjects from './mergeObjects.js';
 import omit from './omit.js';
 import serializer from './serializer.js';
 import set from './set.js';
+import setKey from './setKey.js';
+import splitPath from './splitPath.js';
 import stableStringify from './stableStringify.js';
 import swap from './swap.js';
 import translate from './translate.js';
 import type from './type.js';
 import unset from './unset.js';
+import unsetKey from './unsetKey.js';
 import urlQuery from './urlQuery.js';
 import wait from './wait.js';
-export { applyArrayIndices, builtinMessages, cachedPromises, extractErrorProps, get, getLocaleDateFormat, getLocaleDecimalSeparator, getLocaleGroupSeparator, LRUCache, mergeObjects, omit, serializer, set, stableStringify, swap, translate, type, unset, urlQuery, wait };
+export { applyArrayIndices, builtinMessages, cachedPromises, extractErrorProps, get, getKey, getLocaleDateFormat, getLocaleDecimalSeparator, getLocaleGroupSeparator, isReserved, joinPath, LRUCache, mergeObjects, omit, ReservedKeyError, serializer, set, setKey, splitPath, stableStringify, swap, translate, type, unset, unsetKey, urlQuery, wait };

package/dist/joinPath.js

@@ -0,0 +1,24 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import type from './type.js';
+function joinPath(segments) {
+    if (!type.isArray(segments)) {
+        throw new TypeError(`joinPath: segments must be an array. Received ${JSON.stringify(segments)}.`);
+    }
+    // Escape the escape character first, then the separator, so a segment ending in a
+    // backslash cannot swallow the dot that follows it when splitPath reads it back.
+    return segments.map((segment)=>String(segment).replace(/\\/g, '\\\\').replace(/\./g, '\\.')).join('.');
+}
+export default joinPath;

package/dist/mergeObjects.js

@@ -12,14 +12,62 @@
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-*/ // TODO: do we want this lodash dep in helpers?
-import merge from 'lodash.merge';
+*/ // Imported from the source module, not index.js, to avoid a circular import.
+import { isReserved } from './ReservedKeyError.js';
 import type from './type.js';
-const mergeObjects = (objects)=>{
-    let merged = objects;
+// Plain objects and arrays are the config data model and are always copied; every other value is
+// an opaque leaf, shared by reference. This restores what lodash.merge provided - it cloned
+// plain-object and array source values into the destination while aliasing everything else. The
+// split is not "is it a class instance" but type.isObject's own boundary: kindOf sorts a value as
+// a plain object whenever it fails every built-in check and its Symbol.toStringTag tail check
+// reads '[object Object]'. Date, RegExp, Map, Set, Error, Promise, typed arrays, Buffer, URL and
+// any class that sets Symbol.toStringTag are shared by reference; a plain user class is not - it
+// has no such tag, so it is copied and flattened into a bare object, losing its prototype.
+//
+// clone only walks Object.keys/array indices, so it carries own enumerable string keys forward
+// and drops everything else: non-enumerable markers such as the build's `~k`/`~r`/`~l` keys, and
+// symbol keys. Nothing merges those markers today, but a future caller that does would lose them
+// silently. clone also always produces an object with Object.prototype, so a null-prototype
+// object (e.g. Object.create(null), used deliberately for pollution hardening) loses that
+// hardening if it passes through a merge; nothing does today.
+function clone(value) {
+    if (type.isArray(value)) {
+        return value.map(clone);
+    }
+    if (!type.isObject(value)) {
+        return value;
+    }
+    const result = {};
+    for (const key of Object.keys(value)){
+        if (isReserved(key)) continue;
+        result[key] = clone(value[key]);
+    }
+    return result;
+}
+function deepMerge(target, source) {
+    const result = {};
+    for (const key of Object.keys(target)){
+        if (isReserved(key)) continue;
+        result[key] = clone(target[key]);
+    }
+    for (const key of Object.keys(source)){
+        // Value-side pollution guard. The reserved name arrives as data inside a merged value,
+        // not as a path a developer typed, so dropping it misroutes nothing — skip, don't throw.
+        if (isReserved(key)) continue;
+        if (type.isObject(result[key]) && type.isObject(source[key])) {
+            result[key] = deepMerge(result[key], source[key]);
+        } else {
+            // Everything that is not a plain object is a leaf, arrays included: a later array
+            // replaces an earlier one rather than index-merging into it.
+            result[key] = clone(source[key]);
+        }
+    }
+    return result;
+}
+function mergeObjects(objects) {
     if (type.isArray(objects)) {
-        merged = merge(...objects.filter((obj)=>type.isObject(obj)));
+        return objects.filter((obj)=>type.isObject(obj)).reduce((merged, obj)=>deepMerge(merged, obj), {});
     }
-    return merged;
-};
+    return objects;
+}
 export default mergeObjects;

package/dist/serializer.js

@@ -41,7 +41,7 @@ function propsToError(data) {
     }
     return error;
 }
-const makeReplacer = (customReplacer, isoStringDates, skipMarkers)=>(key, value)=>{
+const makeReplacer = ({ replacer, isoStringDates, skipMarkers, omitErrorProps } = {})=>(key, value)=>{
         let dateReplacer = (date)=>({
                 '~d': date.valueOf()
             });
@@ -51,12 +51,14 @@ const makeReplacer = (customReplacer, isoStringDates, skipMarkers)=>(key, value)
                 });
         }
         let newValue = value;
-        if (customReplacer) {
-            newValue = customReplacer(key, value);
+        if (replacer) {
+            newValue = replacer(key, value);
         }
         if (type.isError(newValue)) {
             return {
-                '~e': extractErrorProps(newValue)
+                '~e': extractErrorProps(newValue, {
+                    omit: omitErrorProps
+                })
             };
         }
         if (type.isObject(newValue)) {
@@ -217,7 +219,13 @@ const serialize = (json, options = {})=>{
             '~d': json.valueOf()
         };
     }
-    return JSON.parse(JSON.stringify(json, makeReplacer(options.replacer, options.isoStringDates)));
+    // skipMarkers is deliberately not threaded here - serialize has never applied
+    // it, and its callers depend on markers surviving.
+    return JSON.parse(JSON.stringify(json, makeReplacer({
+        replacer: options.replacer,
+        isoStringDates: options.isoStringDates,
+        omitErrorProps: options.omitErrorProps
+    })));
 };
 const serializeToString = (json, options = {})=>{
     if (type.isUndefined(json)) return json;
@@ -229,11 +237,20 @@ const serializeToString = (json, options = {})=>{
     }
     if (options.stable) {
         return stableStringify(json, {
-            replacer: makeReplacer(options.replacer, undefined, options.skipMarkers),
+            replacer: makeReplacer({
+                replacer: options.replacer,
+                skipMarkers: options.skipMarkers,
+                omitErrorProps: options.omitErrorProps
+            }),
             space: options.space
         });
     }
-    return JSON.stringify(json, makeReplacer(options.replacer, options.isoStringDates, options.skipMarkers), options.space);
+    return JSON.stringify(json, makeReplacer({
+        replacer: options.replacer,
+        isoStringDates: options.isoStringDates,
+        skipMarkers: options.skipMarkers,
+        omitErrorProps: options.omitErrorProps
+    }), options.space);
 };
 const deserialize = (json, options = {})=>{
     if (type.isUndefined(json)) return json;
@@ -246,7 +263,10 @@ const deserializeFromString = (str, options = {})=>{
 const copy = (json, options = {})=>{
     if (type.isUndefined(json)) return undefined;
     if (type.isDate(json)) return new Date(json.valueOf());
-    return JSON.parse(JSON.stringify(json, makeReplacer(options.replacer)), makeReviver(options.reviver));
+    return JSON.parse(JSON.stringify(json, makeReplacer({
+        replacer: options.replacer,
+        omitErrorProps: options.omitErrorProps
+    })), makeReviver(options.reviver));
 };
 const serializer = {
     copy,