@gershy/clearing 0.0.17 → 0.0.19

package/cmp/cjs/main.js

@@ -459,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.js

@@ -450,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.17",
+  "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,7 +34,6 @@
       "require": "./cmp/cjs/main.js"
     }
   },
-  
   "scripts": {
     "test": "npm run ts.check && npx tsx ./src/main.test.ts",
     "ts.check": "npx tsc --noEmit",
@@ -45,4 +44,4 @@
     "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.