@gershy/clearing 0.0.16 → 0.0.19

package/cmp/cjs/main.d.ts

@@ -16,5 +16,15 @@ export declare const getCls: (i: any) => any;
 export declare const isCls: ClsCheck;
 export declare const inCls: ClsCheck;
 export declare const skip: undefined;
+type Then = {
+    <V, R0 = V, R1 = never>(val: Promise<V>, rsv?: (v: V) => R0, rjc?: (e: any) => R1): Promise<R0 | R1>;
+    <V, R0 = V, R1 = never>(val: V, rsv?: (v: V) => R0, rjc?: (e: any) => R1): R0 | R1;
+};
+export declare const then: Then;
+type Safe = {
+    <V, R0 = never>(fn: () => Promise<V>, rjc?: (e: any) => R0): Promise<V | R0>;
+    <V, R0 = never>(fn: () => V, rjc?: (e: any) => R0): Promise<V | R0>;
+};
+export declare const safe: Safe;
 declare const applyClearing: () => void;
 export default applyClearing;

package/cmp/cjs/main.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.skip = exports.inCls = exports.isCls = exports.getCls = exports.getClsName = void 0;
+exports.safe = exports.then = exports.skip = exports.inCls = exports.isCls = exports.getCls = exports.getClsName = void 0;
 const getClsName = i => {
     if (i === null)
         return 'Null';
@@ -27,6 +27,30 @@ exports.isCls = isCls;
 const inCls = (i, C) => i instanceof C;
 exports.inCls = inCls;
 exports.skip = undefined;
+const then = (val, rsv = (v => v), rjc = ((e) => { throw e; })) => {
+    // Act on `val` regardless of whether it's a Promise or immediate value; return `rsv(val)`
+    // either immediately or as a Promise
+    if ((0, exports.inCls)(val, Promise))
+        return val.then(rsv).catch(rjc);
+    try {
+        return rsv(val);
+    }
+    catch (err) {
+        return rjc(err);
+    }
+};
+exports.then = then;
+const safe = (fn, rjc = e => { throw e; }) => {
+    // Execute a function which returns a value either synchronously or asynchronously; in both cases
+    // allows errors occurring from function execution to be handled
+    try {
+        return (0, exports.then)(fn(), v => v, rjc);
+    }
+    catch (err) {
+        return rjc(err);
+    }
+};
+exports.safe = safe;
 const applyClearing = (() => {
     const global = globalThis;
     // Prevent multiple installations...
@@ -435,7 +459,7 @@ const applyClearing = (() => {
             return Object.assign(this, (0, exports.inCls)(cause, Error) ? cause : {}, moreProps, cause ? { message, cause } : { message });
         },
         [suppress]() {
-            this[Symbol.for('clearing.err.suppressed')] = true;
+            this[Symbol.for('@gershy.clearing.err.suppressed')] = true;
             if (this.cause) {
                 const causes = (0, exports.inCls)(this.cause, Error) ? [this.cause] : this.cause;
                 for (const err of causes)

package/cmp/mjs/main.d.ts

@@ -16,5 +16,15 @@ export declare const getCls: (i: any) => any;
 export declare const isCls: ClsCheck;
 export declare const inCls: ClsCheck;
 export declare const skip: undefined;
+type Then = {
+    <V, R0 = V, R1 = never>(val: Promise<V>, rsv?: (v: V) => R0, rjc?: (e: any) => R1): Promise<R0 | R1>;
+    <V, R0 = V, R1 = never>(val: V, rsv?: (v: V) => R0, rjc?: (e: any) => R1): R0 | R1;
+};
+export declare const then: Then;
+type Safe = {
+    <V, R0 = never>(fn: () => Promise<V>, rjc?: (e: any) => R0): Promise<V | R0>;
+    <V, R0 = never>(fn: () => V, rjc?: (e: any) => R0): Promise<V | R0>;
+};
+export declare const safe: Safe;
 declare const applyClearing: () => void;
 export default applyClearing;

package/cmp/mjs/main.js

@@ -20,6 +20,28 @@ export const isCls = (i, C) => {
 };
 export const inCls = (i, C) => i instanceof C;
 export const skip = undefined;
+export const then = (val, rsv = (v => v), rjc = ((e) => { throw e; })) => {
+    // Act on `val` regardless of whether it's a Promise or immediate value; return `rsv(val)`
+    // either immediately or as a Promise
+    if (inCls(val, Promise))
+        return val.then(rsv).catch(rjc);
+    try {
+        return rsv(val);
+    }
+    catch (err) {
+        return rjc(err);
+    }
+};
+export const safe = (fn, rjc = e => { throw e; }) => {
+    // Execute a function which returns a value either synchronously or asynchronously; in both cases
+    // allows errors occurring from function execution to be handled
+    try {
+        return then(fn(), v => v, rjc);
+    }
+    catch (err) {
+        return rjc(err);
+    }
+};
 const applyClearing = (() => {
     const global = globalThis;
     // Prevent multiple installations...
@@ -428,7 +450,7 @@ const applyClearing = (() => {
             return Object.assign(this, inCls(cause, Error) ? cause : {}, moreProps, cause ? { message, cause } : { message });
         },
         [suppress]() {
-            this[Symbol.for('clearing.err.suppressed')] = true;
+            this[Symbol.for('@gershy.clearing.err.suppressed')] = true;
             if (this.cause) {
                 const causes = inCls(this.cause, Error) ? [this.cause] : this.cause;
                 for (const err of causes)

package/cmp/sideEffects.d.ts

@@ -204,7 +204,7 @@ declare global {
   
   interface PromiseConstructor {
     [allArr]: PromiseConstructor['all'],
-    [allObj]: <O extends { [K: string]: Promise<any> }>(obj: O) => Promise<{ [K in keyof O]: Awaited<O[K]> }>,
+    [allObj]: <O extends { [K: string]: Promise<any> }>(obj: O) => Promise<{ [K in keyof O]: Exclude<Awaited<O[K]>, Skip> }>,
     [later]: <T=void>() => PromiseLater<T>
   }
   interface Promise<T> {}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gershy/clearing",
-  "version": "0.0.16",
+  "version": "0.0.19",
+  "versionCommit": "ccce646c1a4bc2ec3f349a1b02a8498a930c373e",
   "description": "Adds the features you always wish javascript had!",
   "keywords": [
     "clearing",
@@ -22,7 +23,6 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  
   "type": "module",
   "files": [
     "cmp"
@@ -34,15 +34,14 @@
       "require": "./cmp/cjs/main.js"
     }
   },
-  
   "scripts": {
     "test": "npm run ts.check && npx tsx ./src/main.test.ts",
     "ts.check": "npx tsc --noEmit",
-    "build.cjs": "tsc -p ts/tsconfig.cjs.json",
-    "build.mjs": "tsc -p ts/tsconfig.mjs.json",
-    "build": "node ./build.js removeCmp && npm run build.cjs && npm run build.mjs && node ./build.js finalizeExportVariants",
+    "build.cjs": "tsc -p build/tsconfig.cjs.json",
+    "build.mjs": "tsc -p build/tsconfig.mjs.json",
+    "build": "node ./build/act.js removeCmp && npm run build.cjs && npm run build.mjs && node ./build/act.js finalizeExportVariants",
     "git.pub": "npm run test && git add --all && git commit -m \"automated\" && git push",
     "npm.login": "npm login",
     "npm.pub": "npm run test && npm run build && npm publish --access public"
   }
-}
+}

package/readme.md

@@ -32,6 +32,92 @@ Symbol properties maintains compatibility with the vast majority of npm modules.
 more thing - the symbols used to extend functionality are set in the global scope, so they are
 always globally available.
 
+## Exported helpers
+
+In addition to prototype extensions, this module exports several utility helpers for direct import:
+
+```ts
+import { isCls, inCls, getClsName, getCls, skip, then, safe } from '@gershy/clearing';
+```
+
+### `isCls(value, Constructor)`
+Type guard for strict class/constructor matching. Handles primitives, null, undefined, and NaN correctly.
+
+```ts
+isCls(5,         Number);    // true
+isCls(5,         NaN);       // false
+isCls(5,         String);    // false
+isCls('abc',     String);    // true
+isCls(null,      null);      // true
+isCls(undefined, undefined); // true
+isCls(null,      undefined); // false
+isCls(undefined, null);      // false
+isCls(NaN,       NaN);       // true
+isCls({},        Object);    // true
+isCls([],        Array);     // true
+isCls(new Map(), Map);       // true
+```
+
+### `inCls(value, Constructor)`
+Type guard for `instanceof` checks (including inheritance).
+
+```ts
+inCls([], Array); // true
+inCls(new (class X extends Array {})(), Array); // true
+inCls({}, Object); // true
+inCls(5, Number); // false (primitives are not instanceof)
+```
+
+### `getClsName(value)`
+Returns the class/constructor name of a value, or special names for null/undefined/NaN.
+
+```ts
+getClsName(5); // 'Number'
+getClsName('abc'); // 'String'
+getClsName(null); // 'Null'
+getClsName(undefined); // 'Undef'
+getClsName(NaN); // 'Nan'
+getClsName({}); // 'Object'
+getClsName(Object.create(null)); // 'Prototypeless'
+```
+
+### `getCls(value)`
+Returns the constructor function of a value, or null if not available.
+
+```ts
+getCls(5); // Number
+getCls('abc'); // String
+getCls(null); // null
+getCls(undefined); // null
+getCls({}); // Object
+getCls(Object.create(null)); // null
+```
+
+### `skip`
+Special exported value (undefined) used to signal omission in mapping helpers.
+
+```ts
+import { skip } from '@gershy/clearing';
+[1, 2, 3].map(v => v > 1 ? v : skip); // [skip, 2, 3]
+```
+
+### `then(value, onFulfilled?, onRejected?)`
+Unified handler for both Promise and non-Promise values. Applies `onFulfilled`/`onRejected` as appropriate.
+
+```ts
+then(Promise.resolve(5), v => v * 2); // Promise resolving to 10
+then(5, v => v * 2); // 10
+then(Promise.reject('fail'), undefined, e => 'fallback'); // Promise resolving to 'fallback'
+```
+
+### `safe(fn, onRejected?)`
+Runs a function (sync or async), catching errors and returning a Promise. Optionally handles errors with `onRejected`.
+
+```ts
+await safe(() => JSON.parse('{ bad }'), e => 'fallback'); // 'fallback'
+await safe(async () => await fetch('bad-url'), e => null); // null if fetch throws
+```
+
 ## `Object` extensions
 
 There are currently no extensions on the `Object` class.