@gershy/clearing 0.0.15 → 0.0.17

package/cmp/cjs/main.d.ts

@@ -1,3 +1,30 @@
 import '../sideEffects.js';
+type ClsCheck = {
+    (i: unknown, num: BooleanConstructor): i is boolean;
+    (i: unknown, num: NumberConstructor): i is number;
+    (i: unknown, str: StringConstructor): i is string;
+    (i: unknown, buff: BufferConstructor): i is Buffer;
+    (i: unknown, arr: ArrayConstructor): i is any[];
+    (i: unknown, obj: ObjectConstructor): i is Obj<unknown>;
+    (i: unknown, fn: FunctionConstructor): i is Fn;
+    (i: unknown, fn: SymbolConstructor): i is symbol;
+    <T>(i: unknown, prm: PromiseConstructor): i is Promise<T>;
+    <C extends abstract new (...args: any) => any>(i: unknown, cls: C): i is InstanceType<C>;
+};
+export declare const getClsName: (i: any) => any;
+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,5 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.safe = exports.then = exports.skip = exports.inCls = exports.isCls = exports.getCls = exports.getClsName = void 0;
+const getClsName = i => {
+    if (i === null)
+        return 'Null';
+    if (i === undefined)
+        return 'Undef';
+    if (i !== i)
+        return 'Nan';
+    return Object.getPrototypeOf(i)?.constructor.name ?? 'Prototypeless';
+};
+exports.getClsName = getClsName;
+const getCls = i => Object.getPrototypeOf(i)?.constructor ?? null;
+exports.getCls = getCls;
+const isCls = (i, C) => {
+    // NaN only matches against the NaN primitive (not the Number Form)
+    if (i !== i)
+        return C !== C;
+    // `null` and `undefined` only match to themselves
+    if (i == null)
+        return i === C;
+    // Otherwise strictly check the constructor
+    return Object.getPrototypeOf(i).constructor === C;
+};
+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...
@@ -61,42 +112,20 @@ const applyClearing = (() => {
         // </SYMBOLS>
     ];
     const syms = Object.fromEntries(symNames.map(term => [term, Symbol(`${pfx}:${term}`)]));
-    const getClsName = i => {
-        if (i === null)
-            return 'Null';
-        if (i === undefined)
-            return 'Undef';
-        if (i !== i)
-            return 'Nan';
-        return Object.getPrototypeOf(i)?.constructor.name ?? 'Prototypeless';
-    };
-    const getCls = i => Object.getPrototypeOf(i)?.constructor ?? null;
-    const isCls = (i, C) => {
-        // NaN only matches against the NaN primitive (not the Number Form)
-        if (i !== i)
-            return C !== C;
-        // `null` and `undefined` only match to themselves
-        if (i == null)
-            return i === C;
-        // Otherwise strictly check the constructor
-        return Object.getPrototypeOf(i).constructor === C;
-    };
-    const inCls = (i, C) => i instanceof C;
-    const skip = undefined;
-    Object.assign(global, { ...syms, clearing: { getClsName, getCls, isCls, inCls } });
+    Object.assign(global, { ...syms });
     const protoDefs = (Cls, def) => {
         let protoVals = [];
         let classVals = [];
         for (const key of Reflect.ownKeys(def)) {
-            if (key !== '$' && !isCls(key, Symbol))
-                throw Object.assign(Error('invalid proto key'), { Cls, keyClsName: getClsName(key), key });
+            if (key !== '$' && !(0, exports.isCls)(key, Symbol))
+                throw Object.assign(Error('invalid proto key'), { Cls, keyClsName: (0, exports.getClsName)(key), key });
             if (key !== '$') {
                 protoVals.push([key, def[key]]);
             }
             else {
                 for (const k of Reflect.ownKeys(def[key])) {
-                    if (!isCls(k, Symbol))
-                        throw Object.assign(Error('invalid class key'), { Cls, keyClsName: getClsName(k), key: k });
+                    if (!(0, exports.isCls)(k, Symbol))
+                        throw Object.assign(Error('invalid class key'), { Cls, keyClsName: (0, exports.getClsName)(k), key: k });
                     classVals.push([k, def[key][k]]);
                 }
             }
@@ -107,9 +136,9 @@ const applyClearing = (() => {
                 Object.defineProperty(target, sym, { enumerable: false, value });
     };
     protoDefs(Object, {
-        [at](cmps, def = skip) {
+        [at](cmps, def = exports.skip) {
             let ptr = this;
-            if (!isCls(cmps, Array))
+            if (!(0, exports.isCls)(cmps, Array))
                 cmps = [cmps];
             for (const c of cmps) {
                 if (ptr[has](c))
@@ -133,7 +162,7 @@ const applyClearing = (() => {
             const ret = {};
             for (const [k, v] of this) {
                 const g = fn(v, k);
-                if (g === skip)
+                if (g === exports.skip)
                     continue;
                 if (!ret[has](g))
                     ret[g] = {};
@@ -146,7 +175,7 @@ const applyClearing = (() => {
             const ret = Object.assign({}, this);
             for (const k in ret) {
                 const v = fn(ret[k], k);
-                if (v !== skip)
+                if (v !== exports.skip)
                     ret[k] = v;
                 else
                     delete ret[k];
@@ -157,7 +186,7 @@ const applyClearing = (() => {
             const arr = [];
             for (const k in this) {
                 const r = fn(this[k], k);
-                if (r !== skip)
+                if (r !== exports.skip)
                     arr.push(r);
             }
             return Object.fromEntries(arr);
@@ -165,17 +194,17 @@ const applyClearing = (() => {
         [merge](o) {
             for (const [k, v] of o) {
                 // `skip` can be passed to remove properties
-                if (v === skip) {
+                if (v === exports.skip) {
                     delete this[k];
                     continue;
                 }
                 // Incoming non-Object properties are simple
-                if (!isCls(v, Object)) {
+                if (!(0, exports.isCls)(v, Object)) {
                     this[k] = v;
                     continue;
                 }
                 // `v` is an Object; existing non-Object replaced with `{}`
-                if (!this[has](k) || !isCls(this[k], Object))
+                if (!this[has](k) || !(0, exports.isCls)(this[k], Object))
                     this[k] = {};
                 // And simply recurse!
                 this[k][merge](v);
@@ -191,13 +220,13 @@ const applyClearing = (() => {
         [slice](p) {
             // >> { a: 1, b: 2, c: 3, d: 4 }.slice([ 'b', 'd' ]);
             // { b: 2, d: 4 }
-            return p[toObj](p => this[has](p) ? [p, this[p]] : skip);
+            return p[toObj](p => this[has](p) ? [p, this[p]] : exports.skip);
         },
         [toArr](fn) {
             const ret = [];
             for (const k in this) {
                 const r = fn(this[k], k);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return ret;
@@ -226,7 +255,7 @@ const applyClearing = (() => {
             const ret = {};
             for (const elem of this) {
                 const g = fn(elem);
-                if (g === skip)
+                if (g === exports.skip)
                     continue;
                 if (!ret[has](g))
                     ret[g] = [];
@@ -240,7 +269,7 @@ const applyClearing = (() => {
             const len = this.length;
             for (let i = 0; i < len; i++) {
                 const r = it(this[i], i);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return ret;
@@ -252,7 +281,7 @@ const applyClearing = (() => {
             const len = this.length;
             for (let i = 0; i < len; i++) {
                 const r = it(this[i], i);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return Object.fromEntries(ret);
@@ -264,7 +293,7 @@ const applyClearing = (() => {
                 return str.split('\n')[map](ln => {
                     const ind = ln.indexOf(seq);
                     if (ind === -1)
-                        return skip;
+                        return exports.skip;
                     return ln.slice(ind + seq.length);
                 }).join('\n');
             },
@@ -299,7 +328,7 @@ const applyClearing = (() => {
         [count]() { return this.length; },
         [cut](delim, cuts = 1) {
             // `cuts` defines # of cuts (resulting array length is `num + 1`)
-            const split = this.split(delim, cuts < Infinity ? cuts : skip);
+            const split = this.split(delim, cuts < Infinity ? cuts : exports.skip);
             const numDelimsSplit = split.length - 1;
             const lenConsumed = 0
                 + split.reduce((a, s) => a + s.length, 0)
@@ -315,7 +344,7 @@ const applyClearing = (() => {
             if (!this)
                 return this; // No-op on empty String (otherwise it would transform a 0-line string to a 1-line string)
             let indentStr;
-            if (isCls(args[0], String)) {
+            if ((0, exports.isCls)(args[0], String)) {
                 indentStr = args[0];
             }
             else {
@@ -328,7 +357,7 @@ const applyClearing = (() => {
         [padHead]: String.prototype.padStart,
         [padTail]: String.prototype.padEnd,
         [toNum](cs = String[base62]) {
-            if (isCls(cs, String))
+            if ((0, exports.isCls)(cs, String))
                 cs = String[charset](cs);
             const base = cs.size;
             if (base === 1n)
@@ -354,7 +383,7 @@ const applyClearing = (() => {
             const ret = [];
             for (let i = 0; i < this; i++) {
                 const r = fn(i);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return Object.fromEntries(ret);
@@ -365,7 +394,7 @@ const applyClearing = (() => {
             //      |       (n).encodeStr(singleChr)
             // is always equivalent to
             //      |       singleChr.repeat(n - 1)
-            if (isCls(cs, String))
+            if ((0, exports.isCls)(cs, String))
                 cs = String[charset](cs);
             const base = cs.size;
             if (base === 1n && padLen)
@@ -409,17 +438,17 @@ const applyClearing = (() => {
             seen.set(this, 'cycle(Error)');
             const { message, stack, cause, ...props } = this;
             return {
-                form: getClsName(this),
+                form: (0, exports.getClsName)(this),
                 msg: message,
-                trace: stack?.split('\n').slice(1)[map](v => v.trim() ?? skip) ?? [],
+                trace: stack?.split('\n').slice(1)[map](v => v.trim() ?? exports.skip) ?? [],
                 ...props,
                 cause: !cause ? null : cause[limn](seen)
             };
         },
         [mod](props = {} /* { cause, msg, message, ...more } */) {
-            if (isCls(props, Function))
+            if ((0, exports.isCls)(props, Function))
                 props = props(this.message, this);
-            if (isCls(props, String))
+            if ((0, exports.isCls)(props, String))
                 props = { message: props };
             const { cause = null, msg = null, message = msg ?? this.message, ...moreProps } = props;
             // - Assign `cause` to transfer props like fs "code" props, etc. - watch out, `cause` may be
@@ -427,12 +456,12 @@ const applyClearing = (() => {
             // - Assign `moreProps` to transfer any other properties
             // - Add `message` prop
             // - Only add `cause` prop if `cause` is non-null
-            return Object.assign(this, inCls(cause, Error) ? cause : {}, moreProps, cause ? { message, cause } : { message });
+            return Object.assign(this, (0, exports.inCls)(cause, Error) ? cause : {}, moreProps, cause ? { message, cause } : { message });
         },
         [suppress]() {
             this[Symbol.for('clearing.err.suppressed')] = true;
             if (this.cause) {
-                const causes = inCls(this.cause, Error) ? [this.cause] : this.cause;
+                const causes = (0, exports.inCls)(this.cause, Error) ? [this.cause] : this.cause;
                 for (const err of causes)
                     err[suppress]();
             }
@@ -448,7 +477,7 @@ const applyClearing = (() => {
                 return Promise.all(Object.values(obj)).then(vals => {
                     const ret = {};
                     for (const [i, k] of keys.entries())
-                        if (vals[i] !== skip)
+                        if (vals[i] !== exports.skip)
                             ret[k] = vals[i];
                     return ret;
                 });
@@ -473,7 +502,7 @@ const applyClearing = (() => {
             let ind = 0;
             for (const item of this) {
                 const r = fn(item, ind++);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return ret;
@@ -484,7 +513,7 @@ const applyClearing = (() => {
             let ind = 0;
             for (const item of this) {
                 const r = fn(item, ind++);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return ret;
@@ -493,7 +522,7 @@ const applyClearing = (() => {
             const ret = [];
             for (const item of this) {
                 const r = fn(item);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return Object.fromEntries(ret);
@@ -513,7 +542,7 @@ const applyClearing = (() => {
             const ret = [];
             for (const [k, v] of this) {
                 const r = fn(v, k);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return Object.fromEntries(ret);
@@ -523,7 +552,7 @@ const applyClearing = (() => {
             const ret = [];
             for (const [k, v] of this) {
                 const r = fn(v, k);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return ret;
@@ -532,7 +561,7 @@ const applyClearing = (() => {
             const ret = [];
             for (const [k, v] of this) {
                 const r = fn(v, k);
-                if (r !== skip)
+                if (r !== exports.skip)
                     ret.push(r);
             }
             return Object.fromEntries(ret);

package/cmp/mjs/main.d.ts

@@ -1,3 +1,30 @@
 import '../sideEffects.js';
+type ClsCheck = {
+    (i: unknown, num: BooleanConstructor): i is boolean;
+    (i: unknown, num: NumberConstructor): i is number;
+    (i: unknown, str: StringConstructor): i is string;
+    (i: unknown, buff: BufferConstructor): i is Buffer;
+    (i: unknown, arr: ArrayConstructor): i is any[];
+    (i: unknown, obj: ObjectConstructor): i is Obj<unknown>;
+    (i: unknown, fn: FunctionConstructor): i is Fn;
+    (i: unknown, fn: SymbolConstructor): i is symbol;
+    <T>(i: unknown, prm: PromiseConstructor): i is Promise<T>;
+    <C extends abstract new (...args: any) => any>(i: unknown, cls: C): i is InstanceType<C>;
+};
+export declare const getClsName: (i: any) => any;
+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

@@ -1,3 +1,47 @@
+export const getClsName = i => {
+    if (i === null)
+        return 'Null';
+    if (i === undefined)
+        return 'Undef';
+    if (i !== i)
+        return 'Nan';
+    return Object.getPrototypeOf(i)?.constructor.name ?? 'Prototypeless';
+};
+export const getCls = i => Object.getPrototypeOf(i)?.constructor ?? null;
+export const isCls = (i, C) => {
+    // NaN only matches against the NaN primitive (not the Number Form)
+    if (i !== i)
+        return C !== C;
+    // `null` and `undefined` only match to themselves
+    if (i == null)
+        return i === C;
+    // Otherwise strictly check the constructor
+    return Object.getPrototypeOf(i).constructor === 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...
@@ -59,29 +103,7 @@ const applyClearing = (() => {
         // </SYMBOLS>
     ];
     const syms = Object.fromEntries(symNames.map(term => [term, Symbol(`${pfx}:${term}`)]));
-    const getClsName = i => {
-        if (i === null)
-            return 'Null';
-        if (i === undefined)
-            return 'Undef';
-        if (i !== i)
-            return 'Nan';
-        return Object.getPrototypeOf(i)?.constructor.name ?? 'Prototypeless';
-    };
-    const getCls = i => Object.getPrototypeOf(i)?.constructor ?? null;
-    const isCls = (i, C) => {
-        // NaN only matches against the NaN primitive (not the Number Form)
-        if (i !== i)
-            return C !== C;
-        // `null` and `undefined` only match to themselves
-        if (i == null)
-            return i === C;
-        // Otherwise strictly check the constructor
-        return Object.getPrototypeOf(i).constructor === C;
-    };
-    const inCls = (i, C) => i instanceof C;
-    const skip = undefined;
-    Object.assign(global, { ...syms, clearing: { getClsName, getCls, isCls, inCls } });
+    Object.assign(global, { ...syms });
     const protoDefs = (Cls, def) => {
         let protoVals = [];
         let classVals = [];

package/cmp/sideEffects.d.ts

@@ -26,37 +26,6 @@ declare global {
     charVal: (c: string) => bigint,
     valChar: (n: bigint) => string
   };
-  type ClsCheck = {
-    (i: unknown, num:    BooleanConstructor):  i is boolean,
-    (i: unknown, num:    NumberConstructor):   i is number,
-    (i: unknown, str:    StringConstructor):   i is string,
-    (i: unknown, buff:   BufferConstructor):   i is Buffer,
-    (i: unknown, arr:    ArrayConstructor):    i is any[],
-    (i: unknown, obj:    ObjectConstructor):   i is Obj<unknown>,
-    (i: unknown, fn:     FunctionConstructor): i is Fn,
-    (i: unknown, fn:     SymbolConstructor):   i is symbol,
-    <T>(i: unknown, prm: PromiseConstructor):  i is Promise<T>,
-    <C extends abstract new (...args: any) => any>(i: unknown, cls: C): i is InstanceType<C>
-  };
-  const clearing: {
-    
-    getClsName: (i: any) => string,
-    getCls: {
-      (i: number):               NumberConstructor,
-      (i: string):               StringConstructor,
-      (i: Buffer):               BufferConstructor,
-      (i: any[]):                ArrayConstructor,
-      (i: { [K: string]: any }): ObjectConstructor,
-      (i: (...a: any[]) => any): FunctionConstructor,
-      (i: Promise<any>):         PromiseConstructor,
-      <T>(i: T):                 { new (...args: any[]): T }
-    },
-    isCls: ClsCheck,
-    inCls: ClsCheck,
-    
-    skip: Skip
-    
-  };
   
   // <SYMBOLS> :: declarations :: /const ([a-zA-Z0-9]+)[ ]*[:][ ]*unique symbol;/
   const add:       unique symbol;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gershy/clearing",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Adds the features you always wish javascript had!",
   "keywords": [
     "clearing",
@@ -22,22 +22,25 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
+  
   "type": "module",
   "files": [
     "cmp"
   ],
+  "types": "./cmp/mjs/main.d.ts",
   "exports": {
     ".": {
       "import": "./cmp/mjs/main.js",
       "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"