@gershy/clearing 0.0.30 → 0.0.32

package/readme.md

@@ -15,7 +15,7 @@ The clearing module gives you all the features any sane person would want to see
 ## Basic bootstrapping
 
 Clearing uses an unorthodox (controversial??) technique to achieve a lot of convenience.
-Functionality is added by extending native classes and prototypes with _non-enumerable_, _Symbol_ properties like so:
+Functionality is added by extending native classes and prototypes with _non-enumerable_, _Symbol_ properties comparable to the following:
 
 ```ts
 const coolNewHelper = Symbol();
@@ -28,22 +28,23 @@ console.log(obj[coolNewHelper]());
 ```
 
 Extending native classes and prototypes is kind of crazy, but only doing so with non-enumerable,
-Symbol properties maintains compatibility with the vast majority of npm modules. Oh there's one
-more thing - the symbols used to extend functionality are set in the global scope, so they are
-always globally available.
+Symbol properties maintains compatibility with the vast majority of npm modules. All symbols are
+accessible via the `clearing` (or `cl`) global object.
 
-## Exported helpers
-
-In addition to prototype extensions, this module exports several utility helpers for direct import:
+Simply import the clearing module to make all functionality globally available:
 
 ```ts
-import { isCls, inCls, getClsName, getCls, skip, then, safe } from '@gershy/clearing';
+import '@gershy/clearing';
 ```
 
-### `isCls(value, Constructor)`
+## Utility functions
+
+### `clearing.isCls(value, Constructor)`
 Type guard for strict class/constructor matching. Handles primitives, null, undefined, and NaN correctly.
 
 ```ts
+const { isCls } = clearing;
+
 isCls(5,         Number);    // true
 isCls(5,         NaN);       // false
 isCls(5,         String);    // false
@@ -58,20 +59,24 @@ isCls([],        Array);     // true
 isCls(new Map(), Map);       // true
 ```
 
-### `inCls(value, Constructor)`
+### `clearing.inCls(value, Constructor)`
 Type guard for `instanceof` checks (including inheritance).
 
 ```ts
+const { inCls } = clearing;
+
 inCls([], Array); // true
 inCls(new (class X extends Array {})(), Array); // true
 inCls({}, Object); // true
 inCls(5, Number); // false (primitives are not instanceof)
 ```
 
-### `getClsName(value)`
+### `clearing.getClsName(value)`
 Returns the class/constructor name of a value, or special names for null/undefined/NaN.
 
 ```ts
+const { getClsName } = clearing;
+
 getClsName(5); // 'Number'
 getClsName('abc'); // 'String'
 getClsName(null); // 'Null'
@@ -81,94 +86,138 @@ getClsName({}); // 'Object'
 getClsName(Object.create(null)); // 'Prototypeless'
 ```
 
-### `getCls(value)`
+### `clearing.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
+const { getCls } = clearing;
+
+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.
+### `clearing.skip`
+Special value (undefined) used to signal omission in mapping helpers.
 
 ```ts
-import { skip } from '@gershy/clearing';
+const { skip } = clearing;
+
 [1, 2, 3].map(v => v > 1 ? v : skip); // [skip, 2, 3]
 ```
 
-### `then(value, onFulfilled?, onRejected?)`
+### `clearing.then(value, onFulfilled?, onRejected?)`
 Unified handler for both Promise and non-Promise values. Applies `onFulfilled`/`onRejected` as appropriate.
 
 ```ts
+const { then } = clearing;
+
 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?)`
+### `clearing.safe(fn, onRejected?)`
 Runs a function (sync or async), catching errors and returning a Promise. Optionally handles errors with `onRejected`.
 
 ```ts
+const { safe } = clearing;
+
 await safe(() => JSON.parse('{ bad }'), e => 'fallback'); // 'fallback'
 await safe(async () => await fetch('bad-url'), e => null); // null if fetch throws
 ```
 
+## Prototype extensions
+
+Along with utility functions, `@gershy/clearing` adds functionality to native prototypes, keyed by symbols, and exposes those symbols via the `clearing` (or `cl`) globals. These symbols are `unique symbols`, in typescript terms. Note that `unique symbol` is widened only to `symbol` on assignment-to-property-reference:
+
+```ts
+clearing.map; // Typescript knows this is `unique symbol`
+
+const symbol = clearing.map;
+symbol; // Typescript thinks this is a regular `symbol`! Ouch.
+```
+
+In order to gain the sophisticated typing provided by clearing, you must preserve the `unique symbol` typing of all `@gershy/clearing` symbols. My greatest apology to `@gershy/clearing` users it the lack of a succinct way to reference a bunch of symbols at once, while retaining strong typing. For example, the most intuitive way to reference a batch of symbols - via destructuring - is *the easiest way to lose your typing*:
+
+```ts
+const { map, toArr, toObj } = clearing; // Typescript thinks these are regular `symbol`s
+{ a: 1, b: 2 }[map](v => v * 3);        // Typescript thinks this is `any` - very sad!
+```
+
+To preserve your typing you can:
+
+1. Reference directly from the clearing global:
+
+```ts
+{ a: 1, b: 2 }[cl.map](v => v * 3); // Typescript gets `{ a: number, b: number }`!
+```
+
+2. Use explicit typing:
+
+```ts
+const map: typeof clearing.map = clearing.map; // `map` is now a `unique symbol`!
+{ a: 1, b: 2 }[map](v => v * 3); // Typescript gets `{ a: number, b: number }`!
+```
+
+3. Riot against the typescript maintainers for making things work this way (just kidding just kidding, they have their reasonssssss. I mean, kinda. Don't riot. They're smart people.)
+
 ## `Object` extensions
 
 There are currently no extensions on the `Object` class.
 
 ## `Object.prototype` extensions
 
-### `Object.prototype[at]`
+### `Object.prototype[cl.at]`
 
 References a potentially nested own property.
 
 ```ts
 const obj = { a: { b: { c: 'z' } } };
-console.log(obj[at]([ 'a', 'b', 'c' ])); // "z"
+console.log(obj[cl.at]([ 'a', 'b', 'c' ])); // "z"
 ```
 
 A default value can be supplied if nested lookup finds nothing.
 
 ```ts
 const obj = { a: { b: { c: 'z' } } };
-console.log(obj[at]([ 'missing' ], 'default'));        // "default"
-console.log(obj[at]([ 'a', 'lol', 'c' ], 'default'));  // "default"
-console.log(obj[at]([ 'a', 'b', 'haha' ], 'default')); // "default"
+console.log(obj[cl.at]([ 'missing' ], 'default'));        // "default"
+console.log(obj[cl.at]([ 'a', 'lol', 'c' ], 'default'));  // "default"
+console.log(obj[cl.at]([ 'a', 'b', 'haha' ], 'default')); // "default"
 ```
 
-### `Object.prototype[count]`
+### `Object.prototype[cl.count]`
 
 Returns the number of own properties in an object.
 
 ```ts
-console.log({}[count]());                   // 0
-console.log({ a: 1, b: 2 }[count]());       // 2
-console.log({ a: 1, b: 2, c: 3 }[count]()); // 3
+const { count } = clearing;
+
+console.log({                  }[cl.count]()); // 0
+console.log({ a: 1, b: 2       }[cl.count]()); // 2
+console.log({ a: 1, b: 2, c: 3 }[cl.count]()); // 3
 ```
 
-### `Object.prototype[empty]`
+### `Object.prototype[cl.empty]`
 
 Returns whether an object has any properties.
 
 ```ts
-console.log({}[empty]());       // true
-console.log({ a: 1 }[empty]()); // false
+console.log({      }[cl.empty]()); // true
+console.log({ a: 1 }[cl.empty]()); // false
 ```
 
-### `Object.prototype[group]`
+### `Object.prototype[cl.group]`
 
 Splits an object into sub-object groups based on a function returning group names.
 
 ```ts
 const obj = { a: 1, b: 10, c: 3, d: 4, e: 5, f: 6, g: 7, h: 8, i: 9, j: 2 };
 
-console.log(obj[group](n => {
+console.log(obj[cl.group](n => {
   if (n < 4) return 'small';
   if (n < 8) return 'medium';
   return 'big';
@@ -183,90 +232,89 @@ console.log(obj[group](n => {
 */
 ```
 
-### `Object.prototype[has]`
+### `Object.prototype[cl.has]`
 
 Determines own property existence.
 
 ```ts
 const obj = { a: 1, b: 2 };
-console.log(obj[has]('a')); // true
-console.log(obj[has]('b')); // true
-console.log(obj[has]('z')); // false
+console.log(obj[cl.has]('a')); // true
+console.log(obj[cl.has]('b')); // true
+console.log(obj[cl.has]('z')); // false
 ```
 
-### `Object.prototype[map]`
+### `Object.prototype[cl.map]`
 
 Maps over object values, returning a new object. Return `skip` to omit a property.
 
 ```ts
-const { skip } = clearing;
 const obj = { a: 1, b: 2, c: 3 };
-console.log(obj[map](v => v * 2));            // { a: 2, b: 4, c: 6 }
-console.log(obj[map](v => v > 1 ? v : skip)); // { b: 2, c: 3 }
+console.log(obj[cl.map](v => v * 2));            // { a: 2, b: 4, c: 6 }
+console.log(obj[cl.map](v => v > 1 ? v : cl.skip)); // { b: 2, c: 3 }
 ```
 
-### `Object.prototype[mapk]`
+### `Object.prototype[cl.mapk]`
 
 Maps over object entries returning `[key, value]` pairs to construct a new object; allows remapping
 keys.
 
 ```ts
 const obj = { a: 1, b: 2 };
-console.log(obj[mapk]((v, k) => [ k.toUpperCase(), v * 10 ])); // { A: 10, B: 20 }
+console.log(obj[cl.mapk]((v, k) => [ k.toUpperCase(), v * 10 ])); // { A: 10, B: 20 }
 ```
 
-### `Object.prototype[merge]`
+### `Object.prototype[cl.merge]`
 
-Deep merges another object into `this` (mutates in place). Use `skip` global for deletion.
+Deep merges another object into `this` (mutates in place). Use `skip` for deletion.
 
 ```ts
-
 const obj = { a: 1, b: { c: 2, d: 3 } };
-obj[merge]({ b: { c: 100 }, e: 4 });
+obj[cl.merge]({ b: { c: 100 }, e: 4 });
 console.log(obj); // { a: 1, b: { c: 100, d: 3 }, e: 4 }
 
 // Deleting properties
-const { skip } = clearing;
-obj[merge]({ a: skip });
+obj[cl.merge]({ a: skip });
 console.log(obj); // { b: { c: 100, d: 3 }, e: 4 }
 ```
 
-### `Object.prototype[slash]`
+### `Object.prototype[cl.slash]`
 
 Returns a copy of the object with specified keys removed/omitted.
 
 ```ts
 const obj = { a: 1, b: 2, c: 3, d: 4 };
-console.log(obj[slash]([ 'b', 'd' ])); // { a: 1, c: 3 }
+console.log(obj[cl.slash]([ 'b', 'd' ])); // { a: 1, c: 3 }
 ```
 
-### `Object.prototype[slice]`
+### `Object.prototype[cl.slice]`
 
 Returns a copy of the object containing only the specified keys.
 
 ```ts
 const obj = { a: 1, b: 2, c: 3, d: 4 };
-console.log(obj[slice]([ 'b', 'd' ])); // { b: 2, d: 4 }
+console.log(obj[cl.slice]([ 'b', 'd' ])); // { b: 2, d: 4 }
 ```
 
-### `Object.prototype[toArr]`
+### `Object.prototype[cl.toArr]`
 
 Converts an object to an array by mapping over its entries.
 
 ```ts
 const obj = { a: 1, b: 2, c: 3 };
-console.log(obj[toArr]((v, k) => `${k}=${v}`)); // [ 'a=1', 'b=2', 'c=3' ]
+console.log(obj[cl.toArr]((v, k) => `${k}=${v}`)); // [ 'a=1', 'b=2', 'c=3' ]
 ```
 
-### `Object.prototype[Symbol.iterator]`
+### `Object.prototype[cl.walk]`
 
 Makes objects iterable, yielding `[key, value]` pairs.
 
 ```ts
 const obj = { a: 1, b: 2 };
-for (const [ k, v ] of obj) console.log(k, v);
-// "a" 1
-// "b" 2
+for (const [ k, v ] of obj[cl.walk]())
+  // Logs twice:
+  // 1. a 1
+  // 2. b 2
+  console.log(k, v);
 ```
 
 ## `Array` extensions
@@ -275,57 +323,57 @@ There are currently no extensions on the `Array` class.
 
 ## `Array.prototype` extensions
 
-### `Array.prototype[add]`
+### `Array.prototype[cl.add]`
 
 Pushes an item onto the array and returns that item.
 
 ```ts
 const arr = [ 1, 2, 3 ];
-const added = arr[add](4);
+const added = arr[cl.add](4);
 console.log(added); // 4
 console.log(arr);   // [ 1, 2, 3, 4 ]
 ```
 
-### `Array.prototype[count]`
+### `Array.prototype[cl.count]`
 
 Returns the length of the array.
 
 ```ts
-console.log([ 1, 2, 3 ][count]()); // 3
-console.log([][count]());          // 0
+console.log([ 1, 2, 3 ][cl.count]()); // 3
+console.log([][cl.count]());          // 0
 ```
 
-### `Array.prototype[empty]`
+### `Array.prototype[cl.empty]`
 
 Returns whether the array has no elements.
 
 ```ts
-console.log([][empty]());          // true
-console.log([ 1, 2, 3 ][empty]()); // false
+console.log([][cl.empty]());          // true
+console.log([ 1, 2, 3 ][cl.empty]()); // false
 ```
 
-### `Array.prototype[find]`
+### `Array.prototype[cl.find]`
 
 Finds an element matching a predicate, returning `{ found, val, ind }`.
 
 ```ts
 const arr = [ 10, 20, 30, 40 ];
 
-const result = arr[find](v => v > 25);
+const result = arr[cl.find](v => v > 25);
 console.log(result); // { found: true, val: 30, ind: 2 }
 
-const missing = arr[find](v => v > 100);
+const missing = arr[cl.find](v => v > 100);
 console.log(missing); // { found: false, val: null, ind: null }
 ```
 
-### `Array.prototype[group]`
+### `Array.prototype[cl.group]`
 
 Splits an array into sub-arrays based on a function returning group names.
 
 ```ts
 const arr = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ];
 
-console.log(arr[group](n => {
+console.log(arr[cl.group](n => {
   if (n < 4) return 'small';
   if (n < 8) return 'medium';
   return 'big';
@@ -340,49 +388,47 @@ console.log(arr[group](n => {
 */
 ```
 
-### `Array.prototype[has]`
+### `Array.prototype[cl.has]`
 
 Checks if an array includes a value.
 
 ```ts
-console.log([ 1, 2, 3 ][has](2)); // true
-console.log([ 1, 2, 3 ][has](5)); // false
+console.log([ 1, 2, 3 ][cl.has](2)); // true
+console.log([ 1, 2, 3 ][cl.has](5)); // false
 ```
 
 ### `Array.prototype[map]`
 
-Maps over array values. Return `clearing.skip` to omit an element (filter + map in one).
+Maps over array values. Return `cl.skip` to omit an element; it's filter + map in one.
 
 ```ts
 const arr = [ 1, 2, 3, 4, 5 ];
-console.log(arr[map](v => v * 2)); // [ 2, 4, 6, 8, 10 ]
-
-const { skip } = clearing;
-console.log(arr[map](v => v > 2 ? v * 10 : skip)); // [ 30, 40, 50 ]
+console.log(arr[cl.map](v => v * 2));                    // [ 2, 4, 6, 8, 10 ]
+console.log(arr[cl.map](v => v > 2 ? v * 10 : cl.skip)); // [ 30, 40, 50 ]
 ```
 
-### `Array.prototype[rem]`
+### `Array.prototype[cl.rem]`
 
 Removes the first occurrence of a value from the array (mutates in place).
 
 ```ts
 const arr = [ 1, 2, 3, 2, 4 ];
-arr[rem](2);
+arr[cl.rem](2);
 console.log(arr); // [ 1, 3, 2, 4 ]
 ```
 
-### `Array.prototype[toObj]`
+### `Array.prototype[cl.toObj]`
 
 Converts an array to an object by mapping each element to a `[key, value]` pair.
 
 ```ts
 const arr = [ 'a', 'b', 'c' ];
-console.log(arr[toObj]((v, i) => [ v, i ])); // { a: 0, b: 1, c: 2 }
+console.log(arr[cl.toObj]((v, i) => [ v, i ])); // { a: 0, b: 1, c: 2 }
 ```
 
 ## `String` extensions
 
-### `String[baseline]`
+### `String[cl.baseline]`
 
 Allows writing coherent multiline strings with predictable indentation.
 
@@ -393,7 +439,7 @@ const text = (() => {
     
     return (() => {
       
-      return String[baseline](`
+      return String[cl.baseline](`
         | Even though this text is in an indented scope, it will have predictable indentation.
         | 
         | This is achieved by using the pipe ("|") character plus a space as a delimiter for
@@ -411,184 +457,184 @@ const text = (() => {
 })();
 ```
 
-### `String[base32]`, `String[base36]`, `String[base62]`, `String[base64Url]`, `String[base64Std]`
+### `String[cl.base32]`, `String[cl.base36]`, `String[cl.base62]`, `String[cl.base64Url]`, `String[cl.base64Std]`
 
 Character sets for encoding/decoding numbers to strings.
 
 ```ts
-console.log(String[base32]);    // '0123456789abcdefghijklmnopqrstuv'
-console.log(String[base36]);    // '0123456789abcdefghijklmnopqrstuvwxyz'
-console.log(String[base62]);    // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
-console.log(String[base64Url]); // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_'
-console.log(String[base64Std]); // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ+/'
+console.log(String[cl.base32]);    // '0123456789abcdefghijklmnopqrstuv'
+console.log(String[cl.base36]);    // '0123456789abcdefghijklmnopqrstuvwxyz'
+console.log(String[cl.base62]);    // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+console.log(String[cl.base64Url]); // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_'
+console.log(String[cl.base64Std]); // '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ+/'
 ```
 
 ## `String.prototype` extensions
 
-### `String.prototype[code]`
+### `String.prototype[cl.code]`
 
 Returns the character code at a given index (default 0).
 
 ```ts
-console.log('A'[code]());  // 65
-console.log('AB'[code](1)); // 66
+console.log('A'[cl.code]());   // 65
+console.log('AB'[cl.code](1)); // 66
 ```
 
-### `String.prototype[count]`
+### `String.prototype[cl.count]`
 
 Returns the length of the string.
 
 ```ts
-console.log('hello'[count]()); // 5
-console.log(''[count]());      // 0
+console.log('hello'[cl.count]()); // 5
+console.log(''[cl.count]());      // 0
 ```
 
-### `String.prototype[cut]`
+### `String.prototype[cl.cut]`
 
 Splits a string by a delimiter with a maximum number of cuts.
 
 ```ts
-console.log('a:b:c:d:e'[cut](':'));    // [ 'a', 'b:c:d:e' ]
-console.log('a:b:c:d:e'[cut](':', 2)); // [ 'a', 'b', 'c:d:e' ]
-console.log('a:b:c:d:e'[cut](':', Infinity)); // [ 'a', 'b', 'c', 'd', 'e' ]
+console.log('a:b:c:d:e'[cl.cut](':'));           // [ 'a', 'b:c:d:e' ]
+console.log('a:b:c:d:e'[cl.cut](':', 2));        // [ 'a', 'b', 'c:d:e' ]
+console.log('a:b:c:d:e'[cl.cut](':', Infinity)); // [ 'a', 'b', 'c', 'd', 'e' ]
 ```
 
-### `String.prototype[has]`
+### `String.prototype[cl.has]`
 
 Checks if a string contains a substring.
 
 ```ts
-console.log('hello world'[has]('world')); // true
-console.log('hello world'[has]('xyz'));   // false
+console.log('hello world'[cl.has]('world')); // true
+console.log('hello world'[cl.has]('xyz'));   // false
 ```
 
-### `String.prototype[hasHead]`
+### `String.prototype[cl.hasHead]`
 
 Checks if a string starts with a given prefix.
 
 ```ts
-console.log('hello world'[hasHead]('hello')); // true
-console.log('hello world'[hasHead]('world')); // false
+console.log('hello world'[cl.hasHead]('hello')); // true
+console.log('hello world'[cl.hasHead]('world')); // false
 ```
 
-### `String.prototype[hasTail]`
+### `String.prototype[cl.hasTail]`
 
 Checks if a string ends with a given suffix.
 
 ```ts
-console.log('hello world'[hasTail]('world')); // true
-console.log('hello world'[hasTail]('hello')); // false
+console.log('hello world'[cl.hasTail]('world')); // true
+console.log('hello world'[cl.hasTail]('hello')); // false
 ```
 
-### `String.prototype[indent]`
+### `String.prototype[cl.indent]`
 
 Indents each line of a string.
 
 ```ts
 const text = 'line1\nline2\nline3';
 
-console.log(text[indent]());       // 2 spaces (default)
-console.log(text[indent](4));      // 4 spaces
-console.log(text[indent](2, '-')); // '--' prefix
-console.log(text[indent]('>>> ')); // custom prefix
+console.log(text[cl.indent]());         // 2 spaces (default)
+console.log(text[cl.indent](4));        // 4 spaces
+console.log(text[cl.indent](2, '-'));   // '--' prefix
+console.log(text[cl.indent]('>>> ')); // custom prefix
 ```
 
-### `String.prototype[lower]`
+### `String.prototype[cl.lower]`
 
 Converts the string to lowercase.
 
 ```ts
-console.log('HELLO'[lower]()); // 'hello'
+console.log('HELLO'[cl.lower]()); // 'hello'
 ```
 
-### `String.prototype[upper]`
+### `String.prototype[cl.upper]`
 
 Converts the string to uppercase.
 
 ```ts
-console.log('hello'[upper]()); // 'HELLO'
+console.log('hello'[cl.upper]()); // 'HELLO'
 ```
 
-### `String.prototype[padHead]`
+### `String.prototype[cl.padHead]`
 
 Pads the start of the string to a given length.
 
 ```ts
-console.log('5'[padHead](3, '0')); // '005'
+console.log('5'[cl.padHead](3, '0')); // '005'
 ```
 
-### `String.prototype[padTail]`
+### `String.prototype[cl.padTail]`
 
 Pads the end of the string to a given length.
 
 ```ts
-console.log('5'[padTail](3, '0')); // '500'
+console.log('5'[cl.padTail](3, '0')); // '500'
 ```
 
-### `String.prototype[toNum]`
+### `String.prototype[cl.toNum]`
 
 Decodes a string to a BigInt using a given charset.
 
 ```ts
-console.log('ff'[toNum](String[charset]('0123456789abcdef'))); // 255n
-console.log('10'[toNum](String[base62])); // 62n
+console.log('ff'[cl.toNum](String[cl.charset]('0123456789abcdef'))); // 255n
+console.log('10'[cl.toNum](String[cl.base62])); // 62n
 ```
 
 ## `Number` extensions
 
-### `Number[int32]`, `Number[int64]`
+### `Number[cl.int32]`, `Number[cl.int64]`
 
 Constants for 32-bit and 64-bit integer ranges.
 
 ```ts
-console.log(Number[int32]); // 4294967296 (2^32)
-console.log(Number[int64]); // 18446744073709551616 (2^64)
+console.log(Number[cl.int32]); // 4294967296 (2^32)
+console.log(Number[cl.int64]); // 18446744073709551616 (2^64)
 ```
 
 ## `Number.prototype` extensions
 
-### `Number.prototype[char]`
+### `Number.prototype[cl.char]`
 
 Converts a character code to its character.
 
 ```ts
-console.log((65)[char]()); // 'A'
-console.log((97)[char]()); // 'a'
+console.log((65)[cl.char]()); // 'A'
+console.log((97)[cl.char]()); // 'a'
 ```
 
-### `Number.prototype[isInt]`
+### `Number.prototype[cl.isInt]`
 
 Returns whether a number is an integer.
 
 ```ts
-console.log((5)[isInt]());   // true
-console.log((5.1)[isInt]()); // false
+console.log((5)[cl.isInt]());   // true
+console.log((5.1)[cl.isInt]()); // false
 ```
 
-### `Number.prototype[toArr]`
+### `Number.prototype[cl.toArr]`
 
 Creates an array of length `n` by mapping over indices.
 
 ```ts
-console.log((5)[toArr](i => i * 2)); // [ 0, 2, 4, 6, 8 ]
+console.log((5)[cl.toArr](i => i * 2)); // [ 0, 2, 4, 6, 8 ]
 ```
 
-### `Number.prototype[toObj]`
+### `Number.prototype[cl.toObj]`
 
 Creates an object by mapping over indices, returning `[key, value]` pairs.
 
 ```ts
-console.log((3)[toObj](i => [ `key${i}`, i * 10 ])); // { key0: 0, key1: 10, key2: 20 }
+console.log((3)[cl.toObj](i => [ `key${i}`, i * 10 ])); // { key0: 0, key1: 10, key2: 20 }
 ```
 
-### `Number.prototype[toStr]`
+### `Number.prototype[cl.toStr]`
 
 Encodes a number to a string using a given charset.
 
 ```ts
-console.log((255)[toStr](String[charset]('0123456789abcdef'))); // 'ff'
-console.log((62)[toStr](String[base62]));  // '10'
-console.log((5)[toStr](String[base62], 4)); // '0005' (padded)
+console.log((255)[cl.toStr](String[cl.charset]('0123456789abcdef'))); // 'ff'
+console.log((62)[cl.toStr](String[cl.base62]));    // '10'
+console.log((5)[cl.toStr](String[cl.base62], 4));  // '0005' (padded)
 ```
 
 ### `Number.prototype[Symbol.iterator]`
@@ -604,72 +650,72 @@ for (const i of 3) console.log(i);
 console.log([ ...5 ]); // [ 0, 1, 2, 3, 4 ]
 ```
 
-### `Number.prototype[bits]`
+### `Number.prototype[cl.bits]`
 
 Yields the bits of a number (least significant first).
 
 ```ts
-console.log([ ...(13)[bits]() ]); // [ 1, 0, 1, 1 ] (13 is 1101 in binary)
+console.log([ ...(13)[cl.bits]() ]); // [ 1, 0, 1, 1 ] (13 is 1101 in binary)
 ```
 
 ## `BigInt.prototype` extensions
 
-### `BigInt.prototype[toStr]`
+### `BigInt.prototype[cl.toStr]`
 
-Same as `Number.prototype[toStr]`, but for BigInt values.
+Same as `Number.prototype[cl.toStr]`, but for BigInt values.
 
 ```ts
-console.log((1000000000000n)[toStr](String[base62])); // 'bLY38W'
+console.log((1000000000000n)[cl.toStr](String[cl.base62])); // 'bLY38W'
 ```
 ## `Error` extensions
 
-### `Error[assert]`
+### `Error[cl.assert]`
 
 Throws an error if the assertion function returns false.
 
 ```ts
-Error[assert]({ x: 5, y: 10 }, ({ x, y }) => x < y); // passes
-Error[assert]({ x: 10, y: 5 }, ({ x, y }) => x < y); // throws!
+Error[cl.assert]({ x: 5, y: 10 }, ({ x, y }) => x < y); // passes
+Error[cl.assert]({ x: 10, y: 5 }, ({ x, y }) => x < y); // throws!
 ```
 
 ## `Error.prototype` extensions
 
-### `Error.prototype[mod]`
+### `Error.prototype[cl.mod]`
 
 Modifies an error's message and adds properties. Returns the error for chaining.
 
 ```ts
 // Add context to errors:
-throw Error('oops')[mod]({ code: 'err99', context: { userId: 123 } });
+throw Error('oops')[cl.mod]({ code: 'err99', context: { userId: 123 } });
 
 // Overwrite the error message by passing a string, or supplying "message" or "msg" properties:
-throw Error('oops')[mod]('new message');
-throw Error('oops')[mod]({ msg:     'new message', extra: 'data' });
-throw Error('oops')[mod]({ message: 'new message', extra: 'data' });
+throw Error('oops')[cl.mod]('new message');
+throw Error('oops')[cl.mod]({ msg:     'new message', extra: 'data' });
+throw Error('oops')[cl.mod]({ message: 'new message', extra: 'data' });
 
 // Pass a callback to succinctly reference the original message:
-throw Error('oops')[mod](msg => `Modified message! Original: ${msg}`);
-throw Error('oops')[mod](msg => ({
+throw Error('oops')[cl.mod](msg => `Modified message! Original: ${msg}`);
+throw Error('oops')[cl.mod](msg => ({
   msg: `Modified message! Original: ${msg}`,
   extra: 'data'
 }));
 ```
 
-### `Error.prototype[fire]`
+### `Error.prototype[cl.fire]`
 
-Shorthand for `throw error[mod](props)`.
+Shorthand for `throw error[cl.mod](props)`.
 
 ```ts
-Error('something failed')[fire]({ code: 'err99' });
+Error('something failed')[cl.fire]({ code: 'err99' });
 ```
 
-### `Error.prototype[limn]`
+### `Error.prototype[cl.limn]`
 
 Converts an error (and its cause chain) to a plain, json-serializable object.
 
 ```ts
-const err = Error('outer')[mod]({ cause: Error('inner') });
-console.log(err[limn]());
+const err = Error('outer')[cl.mod]({ cause: Error('inner') });
+console.log(err[cl.limn]());
 /*
 {
   form: 'Error',
@@ -680,13 +726,13 @@ console.log(err[limn]());
 */
 ```
 
-### `Error.prototype[suppress]`
+### `Error.prototype[cl.suppress]`
 
 Marks an error (and its causes) as suppressed for custom error handling.
 
 ```ts
 const err = Error('handled gracefully');
-err[suppress]();
+err[cl.suppress]();
 console.log(err[Symbol.for('clearing.err.suppressed')]); // true
 ```
 
@@ -705,20 +751,20 @@ process.on('unhandledException', err => {
 
 ## `Promise` extensions
 
-### `Promise[allArr]`
+### `Promise[cl.allArr]`
 
 Alias for `Promise.all`.
 
 ```ts
-const results = await Promise[allArr]([ fetch('/a'), fetch('/b'), fetch('/c') ]);
+const results = await Promise[cl.allArr]([ fetch('/a'), fetch('/b'), fetch('/c') ]);
 ```
 
-### `Promise[allObj]`
+### `Promise[cl.allObj]`
 
 Like `Promise.all`, but for an object of promises, returning an object of results.
 
 ```ts
-const results = await Promise[allObj]({
+const results = await Promise[cl.allObj]({
   user: fetchUser(),
   posts: fetchPosts(),
   comments: fetchComments()
@@ -726,12 +772,12 @@ const results = await Promise[allObj]({
 console.log(results.user, results.posts, results.comments);
 ```
 
-### `Promise[later]`
+### `Promise[cl.later]`
 
 Creates a promise with externally accessible `resolve` and `reject` functions.
 
 ```ts
-const p = Promise[later]();
+const p = Promise[cl.later]();
 
 setTimeout(() => p.resolve('done!'), 1000);
 
@@ -740,140 +786,140 @@ console.log(await p); // 'done!'
 
 ## `Set.prototype` extensions
 
-### `Set.prototype[count]`
+### `Set.prototype[cl.count]`
 
 Returns the size of the set.
 
 ```ts
-console.log(new Set([ 1, 2, 3 ])[count]()); // 3
+console.log(new Set([ 1, 2, 3 ])[cl.count]()); // 3
 ```
 
-### `Set.prototype[empty]`
+### `Set.prototype[cl.empty]`
 
 Returns whether the set is empty.
 
 ```ts
-console.log(new Set()[empty]());          // true
-console.log(new Set([ 1 ])[empty]()); // false
+console.log(new Set()[cl.empty]());       // true
+console.log(new Set([ 1 ])[cl.empty]()); // false
 ```
 
-### `Set.prototype[find]`
+### `Set.prototype[cl.find]`
 
 Finds an element matching a predicate, returning `{ found, val }`.
 
 ```ts
 const s = new Set([ 10, 20, 30 ]);
-console.log(s[find](v => v > 15)); // { found: true, val: 20 }
+console.log(s[cl.find](v => v > 15)); // { found: true, val: 20 }
 ```
 
-### `Set.prototype[map]`
+### `Set.prototype[cl.map]`
 
 Maps over set values to produce an array.
 
 ```ts
 const s = new Set([ 1, 2, 3 ]);
-console.log(s[map](v => v * 2)); // [ 2, 4, 6 ]
+console.log(s[cl.map](v => v * 2)); // [ 2, 4, 6 ]
 ```
 
-### `Set.prototype[rem]`
+### `Set.prototype[cl.rem]`
 
 Removes a value from the set.
 
 ```ts
 const s = new Set([ 1, 2, 3 ]);
-s[rem](2);
+s[cl.rem](2);
 console.log([ ...s ]); // [ 1, 3 ]
 ```
 
-### `Set.prototype[toArr]`
+### `Set.prototype[cl.toArr]`
 
 Converts a set to an array by mapping over its values.
 
 ```ts
 const s = new Set([ 1, 2, 3 ]);
-console.log(s[toArr](v => v * 10)); // [ 10, 20, 30 ]
+console.log(s[cl.toArr](v => v * 10)); // [ 10, 20, 30 ]
 ```
 
-### `Set.prototype[toObj]`
+### `Set.prototype[cl.toObj]`
 
 Converts a set to an object by mapping each value to a `[key, value]` pair.
 
 ```ts
 const s = new Set([ 'a', 'b', 'c' ]);
-console.log(s[toObj](v => [ v, v.toUpperCase() ])); // { a: 'A', b: 'B', c: 'C' }
+console.log(s[cl.toObj](v => [ v, v.toUpperCase() ])); // { a: 'A', b: 'B', c: 'C' }
 ```
 
 ## `Map.prototype` extensions
 
-### `Map.prototype[add]`
+### `Map.prototype[cl.add]`
 
 Alias for `Map.prototype.set` (for consistency with Set).
 
 ```ts
 const m = new Map();
-m[add]('key', 'value');
+m[cl.add]('key', 'value');
 ```
 
-### `Map.prototype[count]`
+### `Map.prototype[cl.count]`
 
 Returns the size of the map.
 
 ```ts
 const m = new Map([ [ 'a', 1 ], [ 'b', 2 ] ]);
-console.log(m[count]()); // 2
+console.log(m[cl.count]()); // 2
 ```
 
-### `Map.prototype[empty]`
+### `Map.prototype[cl.empty]`
 
 Returns whether the map is empty.
 
 ```ts
-console.log(new Map()[empty]());               // true
-console.log(new Map([ [ 'a', 1 ] ])[empty]()); // false
+console.log(new Map()[cl.empty]());                  // true
+console.log(new Map([ [ 'a', 1 ] ])[cl.empty]()); // false
 ```
 
-### `Map.prototype[find]`
+### `Map.prototype[cl.find]`
 
 Finds an entry matching a predicate, returning `{ found, val, key }`.
 
 ```ts
 const m = new Map([ [ 'a', 10 ], [ 'b', 20 ], [ 'c', 30 ] ]);
-console.log(m[find](v => v > 15)); // { found: true, val: 20, key: 'b' }
+console.log(m[cl.find](v => v > 15)); // { found: true, val: 20, key: 'b' }
 ```
 
-### `Map.prototype[map]`
+### `Map.prototype[cl.map]`
 
 Maps entries to produce an object; iterator receives `(val, key)` and returns `[key, val]`.
 
 ```ts
 const m = new Map([ [ 'a', 1 ], [ 'b', 2 ] ]);
-console.log(m[map]((v, k) => [ k.toUpperCase(), v * 10 ])); // { A: 10, B: 20 }
+console.log(m[cl.map]((v, k) => [ k.toUpperCase(), v * 10 ])); // { A: 10, B: 20 }
 ```
 
-### `Map.prototype[rem]`
+### `Map.prototype[cl.rem]`
 
 Removes an entry from the map by key.
 
 ```ts
 const m = new Map([ [ 'a', 1 ], [ 'b', 2 ] ]);
-m[rem]('a');
-console.log(m[count]()); // 1
+m[cl.rem]('a');
+console.log(m[cl.count]()); // 1
 ```
 
-### `Map.prototype[toArr]`
+### `Map.prototype[cl.toArr]`
 
 Converts a map to an array by mapping over its entries.
 
 ```ts
 const m = new Map([ [ 'a', 1 ], [ 'b', 2 ] ]);
-console.log(m[toArr]((v, k) => `${k}=${v}`)); // [ 'a=1', 'b=2' ]
+console.log(m[cl.toArr]((v, k) => `${k}=${v}`)); // [ 'a=1', 'b=2' ]
 ```
 
-### `Map.prototype[toObj]`
+### `Map.prototype[cl.toObj]`
 
 Converts a map to an object by mapping over its entries.
 
 ```ts
 const m = new Map([ [ 'a', 1 ], [ 'b', 2 ] ]);
-console.log(m[toObj]((v, k) => [ k, v * 100 ])); // { a: 100, b: 200 }
+console.log(m[cl.toObj]((v, k) => [ k, v * 100 ])); // { a: 100, b: 200 }
 ```