@lowdefy/helpers 6.0.0 → 6.2.0

package/dist/builtinMessages.js

@@ -24,6 +24,7 @@
     'errorPage.name': 'Error',
     'errorPage.message': 'An error has occurred.',
     'errorPage.homeLink': 'Return to home page',
+    'server.genericError': 'Something went wrong.',
     // Agent runtime — surfaces in browser as HTTP error responses / streamed errors
     'agent.runtime.methodNotAllowed': 'Only POST requests are supported.',
     'agent.runtime.invalidPath': 'Invalid agent path',

package/dist/extractErrorProps.js

@@ -46,8 +46,22 @@ function symbolMarker(val) {
 }
 const MAX_CAUSE_DEPTH = 3;
 const MAX_OBJECT_DEPTH = 5;
-const NO_OMIT = [];
-function cleanValue(val, seen, objectDepth, causeDepth, omit) {
+// Today's fields in today's order. The own `cause` key is skipped in the spread
+// so an assigned (and therefore enumerable) cause is not listed twice.
+function defaultProjection(err) {
+    const props = {
+        message: err.message,
+        name: err.name,
+        stack: err.stack,
+        cause: err.cause
+    };
+    for (const key of Object.keys(err)){
+        if (key === 'cause') continue;
+        props[key] = err[key];
+    }
+    return props;
+}
+function cleanValue(val, seen, objectDepth, causeDepth, project) {
     if (objectDepth > MAX_OBJECT_DEPTH) return '[Truncated]';
     if (typeof val === 'function') return functionMarker(val);
     if (typeof val === 'bigint') return bigintMarker(val);
@@ -56,81 +70,73 @@ function cleanValue(val, seen, objectDepth, causeDepth, omit) {
     if (seen.has(val)) return '[Circular]';
     seen.add(val);
     if (Array.isArray(val)) {
-        return val.map((item)=>cleanValue(item, seen, objectDepth + 1, causeDepth, omit));
+        return val.map((item)=>cleanValue(item, seen, objectDepth + 1, causeDepth, project));
     }
     if (val instanceof Date) return val;
-    if (val instanceof Error) return _extractErrorProps(val, seen, objectDepth, causeDepth, omit);
+    if (val instanceof Error) return _extractErrorProps(val, seen, objectDepth, causeDepth, project);
     if (!isPlainObject(val)) return classInstanceMarker(val);
     const cleaned = {};
     for (const [k, v] of Object.entries(val)){
-        const cv = cleanValue(v, seen, objectDepth + 1, causeDepth, omit);
+        const cv = cleanValue(v, seen, objectDepth + 1, causeDepth, project);
         if (cv !== undefined) cleaned[k] = cv;
     }
     return cleaned;
 }
-function _extractErrorProps(err, seen, objectDepth, causeDepth, omit) {
+function cleanCause(cause, seen, objectDepth, causeDepth, project) {
+    if (!(cause instanceof Error)) {
+        return cleanValue(cause, seen, objectDepth + 1, causeDepth, project);
+    }
+    if (seen.has(cause)) return '[Circular]';
+    if (causeDepth >= MAX_CAUSE_DEPTH) return '[Truncated]';
+    return _extractErrorProps(cause, seen, objectDepth, causeDepth + 1, project);
+}
+function cleanPropValue(value, seen, objectDepth, causeDepth, project) {
+    if (typeof value === 'function') return functionMarker(value);
+    if (typeof value === 'bigint') return bigintMarker(value);
+    if (typeof value === 'symbol') return symbolMarker(value);
+    if (value === null || typeof value !== 'object') return value;
+    if (value instanceof Date) return value;
+    if (Array.isArray(value)) return cleanValue(value, seen, objectDepth + 1, causeDepth, project);
+    if (value instanceof Error) {
+        if (seen.has(value)) return '[Circular]';
+        return _extractErrorProps(value, seen, objectDepth, causeDepth, project);
+    }
+    if (isPlainObject(value)) return cleanValue(value, seen, objectDepth + 1, causeDepth, project);
+    // 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.
+    return classInstanceMarker(value);
+}
+function _extractErrorProps(err, seen, objectDepth, causeDepth, project) {
     if (!err) return err;
     seen.add(err);
     // 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;
+    // walk's; this function only cleans the entries it is handed. An entry the
+    // projection leaves out is never built, so a dropped cause is never
+    // deep-copied and never marked in `seen`.
+    const projected = (project ?? defaultProjection)(err);
     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' || omitted.includes(key)) continue;
-        const value = err[key];
-        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, omit);
-        } else if (value instanceof Error) {
-            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, omit);
+    for (const [key, value] of Object.entries(projected)){
+        if (value === undefined) continue;
+        if (key === 'cause') {
+            props.cause = cleanCause(value, seen, objectDepth, causeDepth, project);
         } 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);
+            props[key] = cleanPropValue(value, seen, objectDepth, causeDepth, project);
         }
     }
     return props;
 }
-// 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);
+// project: (err) => object - the props to emit for THIS error node, called once
+// per node. Entries are cleaned as own properties are: Errors recurse through
+// the same `project`, the returned `cause` is walked in place of the original,
+// and `undefined` entries are dropped. Returning neither `message` nor `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`. Leave either out and a round-trip
+// yields plain objects.
+function extractErrorProps(err, { project } = {}) {
+    return _extractErrorProps(err, new Set(), 0, 0, project);
 }
 export default extractErrorProps;

package/dist/index.js

@@ -25,8 +25,10 @@ import getOperatorType from './getOperatorType.js';
 import { isReserved, ReservedKeyError } from './ReservedKeyError.js';
 import joinPath from './joinPath.js';
 import LRUCache from './LRUCache.js';
+import mapPlainValues from './mapPlainValues.js';
 import mergeObjects from './mergeObjects.js';
 import omit from './omit.js';
+import projectCaughtError from './projectCaughtError.js';
 import serializer from './serializer.js';
 import set from './set.js';
 import setKey from './setKey.js';
@@ -39,4 +41,4 @@ 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, getKey, getLocaleDateFormat, getLocaleDecimalSeparator, getLocaleGroupSeparator, getOperatorType, isReserved, joinPath, LRUCache, mergeObjects, omit, ReservedKeyError, serializer, set, setKey, splitPath, stableStringify, swap, translate, type, unset, unsetKey, urlQuery, wait };
+export { applyArrayIndices, builtinMessages, cachedPromises, extractErrorProps, get, getKey, getLocaleDateFormat, getLocaleDecimalSeparator, getLocaleGroupSeparator, getOperatorType, isReserved, joinPath, LRUCache, mapPlainValues, mergeObjects, omit, projectCaughtError, ReservedKeyError, serializer, set, setKey, splitPath, stableStringify, swap, translate, type, unset, unsetKey, urlQuery, wait };

package/dist/mapPlainValues.js

@@ -0,0 +1,51 @@
+/*
+  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.
+*/ // type.isObject also accepts class instances, whose internals a copy would expose.
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function mapNode(value, key, visit, copies) {
+    const visited = visit(value, key);
+    if (visited !== value) return visited;
+    if (!Array.isArray(value) && !isPlainObject(value)) return value;
+    // Reusing the copy of an object already seen keeps shared references and cycles
+    // intact instead of recursing forever.
+    if (copies.has(value)) return copies.get(value);
+    if (Array.isArray(value)) {
+        const mappedArray = [];
+        copies.set(value, mappedArray);
+        value.forEach((item)=>{
+            mappedArray.push(mapNode(item, undefined, visit, copies));
+        });
+        return mappedArray;
+    }
+    const mappedObject = {};
+    copies.set(value, mappedObject);
+    Object.entries(value).forEach(([entryKey, item])=>{
+        mappedObject[entryKey] = mapNode(item, entryKey, visit, copies);
+    });
+    return mappedObject;
+}
+// Copies the plain objects and arrays in a value, calling visit(value, key) on every
+// node first - key is the object key, undefined for the root and array items. A
+// different return replaces the node; the same value is kept, and descended into
+// when it is a plain object or array. Class instances, Dates and Errors are kept
+// by reference. The input is never mutated.
+function mapPlainValues(value, visit) {
+    return mapNode(value, undefined, visit, new Map());
+}
+export default mapPlainValues;

package/dist/projectCaughtError.js

@@ -0,0 +1,84 @@
+/*
+  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 { lowdefyErrorTypes, readErrorCodes } from '@lowdefy/errors';
+import mapPlainValues from './mapPlainValues.js';
+import type from './type.js';
+function identity(value) {
+    return value;
+}
+function scrubStrings(value, scrub) {
+    return mapPlainValues(value, (item)=>type.isString(item) ? scrub(item) : item);
+}
+// Own-key lookup: an error named after an Object.prototype member, such as
+// 'constructor', must fall back to Error rather than pick up that member.
+function prototypeFor(name) {
+    if (Object.hasOwn(lowdefyErrorTypes, name)) {
+        return lowdefyErrorTypes[name].prototype;
+    }
+    return Error.prototype;
+}
+function projectNode(error, scrub, seen) {
+    seen.add(error);
+    const projected = Object.create(prototypeFor(error.name));
+    // Non-enumerable, as on a constructed Error, so JSON.stringify skips it: an
+    // `_error` sent to a plugin as data (an HTTP body, a database insert) then
+    // carries no message. Assigning it would make it enumerable, which is also
+    // why this does not go through serializer.copy.
+    Object.defineProperty(projected, 'message', {
+        value: scrub(error.message),
+        enumerable: false,
+        writable: true,
+        configurable: true
+    });
+    const { code, statusCode } = readErrorCodes(error);
+    const fields = {
+        name: error.name,
+        code: type.isString(code) ? scrub(code) : code,
+        statusCode,
+        // The server's error sink sets `handled` once it has logged the error, and
+        // the client skips reporting a handled error back to the server. A rethrown
+        // `_error` without it would be logged a second time.
+        handled: error.handled
+    };
+    for (const [key, value] of Object.entries(fields)){
+        if (!type.isUndefined(value)) projected[key] = value;
+    }
+    const { cause } = error;
+    if (type.isError(cause)) {
+        if (!seen.has(cause)) projected.cause = projectNode(cause, scrub, seen);
+    } else if (error.name === 'UserError') {
+        // The author wrote a UserError's cause and metaData in config; any other
+        // class's non-Error cause is library data, such as a response body.
+        if (!type.isUndefined(cause)) projected.cause = scrubStrings(cause, scrub);
+    }
+    if (error.name === 'UserError' && !type.isUndefined(error.metaData)) {
+        projected.metaData = scrubStrings(error.metaData, scrub);
+    }
+    return projected;
+}
+// The value `_error` reads: the caught error rebuilt with only the fields a
+// routine or catch list branches on. `received`, `configKey`, `location`,
+// `source`, `config` and `stack` are left out - `received` can hold a token
+// fetched at runtime that the scrub does not know. The result is an Error, so
+// wherever config sends it on, the serializer's wire policy applies to it.
+function projectCaughtError(error, { scrub = identity } = {}) {
+    if (!type.isError(error)) {
+        return projectCaughtError(new Error(String(error)), {
+            scrub
+        });
+    }
+    return projectNode(error, scrub, new Set());
+}
+export default projectCaughtError;

package/dist/serializer.js

@@ -12,23 +12,10 @@
   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 { ActionError, BlockError, BuildError, ConfigError, ConfigWarning, LowdefyInternalError, OperatorError, PluginError, RequestError, ServiceError, UserError } from '@lowdefy/errors';
+*/ import { lowdefyErrorTypes } from '@lowdefy/errors';
 import extractErrorProps from './extractErrorProps.js';
 import type from './type.js';
 import stableStringify from './stableStringify.js';
-const lowdefyErrorTypes = {
-    ActionError,
-    BlockError,
-    BuildError,
-    ConfigError,
-    ConfigWarning,
-    LowdefyInternalError,
-    OperatorError,
-    PluginError,
-    RequestError,
-    ServiceError,
-    UserError
-};
 function propsToError(data) {
     const ErrorClass = lowdefyErrorTypes[data.name] || Error;
     const error = Object.create(ErrorClass.prototype);
@@ -41,7 +28,7 @@ function propsToError(data) {
     }
     return error;
 }
-const makeReplacer = ({ replacer, isoStringDates, skipMarkers, omitErrorProps } = {})=>(key, value)=>{
+const makeReplacer = ({ replacer, isoStringDates, skipMarkers, projectError } = {})=>(key, value)=>{
         let dateReplacer = (date)=>({
                 '~d': date.valueOf()
             });
@@ -57,7 +44,7 @@ const makeReplacer = ({ replacer, isoStringDates, skipMarkers, omitErrorProps }
         if (type.isError(newValue)) {
             return {
                 '~e': extractErrorProps(newValue, {
-                    omit: omitErrorProps
+                    project: projectError
                 })
             };
         }
@@ -224,7 +211,7 @@ const serialize = (json, options = {})=>{
     return JSON.parse(JSON.stringify(json, makeReplacer({
         replacer: options.replacer,
         isoStringDates: options.isoStringDates,
-        omitErrorProps: options.omitErrorProps
+        projectError: options.projectError
     })));
 };
 const serializeToString = (json, options = {})=>{
@@ -240,7 +227,7 @@ const serializeToString = (json, options = {})=>{
             replacer: makeReplacer({
                 replacer: options.replacer,
                 skipMarkers: options.skipMarkers,
-                omitErrorProps: options.omitErrorProps
+                projectError: options.projectError
             }),
             space: options.space
         });
@@ -249,7 +236,7 @@ const serializeToString = (json, options = {})=>{
         replacer: options.replacer,
         isoStringDates: options.isoStringDates,
         skipMarkers: options.skipMarkers,
-        omitErrorProps: options.omitErrorProps
+        projectError: options.projectError
     }), options.space);
 };
 const deserialize = (json, options = {})=>{
@@ -265,7 +252,7 @@ const copy = (json, options = {})=>{
     if (type.isDate(json)) return new Date(json.valueOf());
     return JSON.parse(JSON.stringify(json, makeReplacer({
         replacer: options.replacer,
-        omitErrorProps: options.omitErrorProps
+        projectError: options.projectError
     })), makeReviver(options.reviver));
 };
 const serializer = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/helpers",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -31,7 +31,7 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/errors": "6.0.0",
+    "@lowdefy/errors": "6.2.0",
     "intl-messageformat": "11.2.7"
   },
   "devDependencies": {