@gershy/clearing 0.0.1

package/clearing.ts

@@ -0,0 +1,765 @@
+'use strict';
+
+// version [0]
+
+if (!global['~clearing']) {
+  global['~clearing'] = true;
+
+  Object.assign(global, {
+    
+    AsyncFunction: (async () => {}).constructor,
+    GeneratorFunction: (function*(){})().constructor,
+    AsyncGeneratorFunction: (async function*(){})().constructor,
+    C: Object.freeze({
+      def: (obj, prop, value, opts={}) => Object.defineProperty(obj, prop, { value, configurable: true, ...opts }),
+      skip: undefined,
+      'Promise.all': Promise.all.bind(Promise),
+      'Error.prototype.toString': Error.prototype.toString
+    }),
+    skip: undefined,
+
+    // Flow controls, sync/async interoperability
+    onto: (val, fn) => (fn(val), val),
+    safe: (fn, onErr: (err: Error) => void) => {
+      
+      // Returns `fn()` with error handling provided by `onErr` regardless
+      // of whether `fn()` results in a Promise or an immediate value
+      
+      let p = new Promise(r => r('abc'));
+      p.catch()
+      try              { let val = fn(); return isForm(val, Promise) ? val.fail(onErr) : val; }
+      catch (err: any) { return onErr(err); }
+      
+    },
+    soon: fn => fn ? Promise.resolve().then(fn) : Promise.resolve(),
+    then: (val, rsv=Function.stub, rjc?: (...args: any[]) => any) => {
+      
+      // Act on `val` regardless of whether it's a Promise or an immediate
+      // value; return `rsv(val)` either immediately or as a Promise;
+      
+      // Promises are returned with `then`/`fail` handling
+      if (val instanceof Promise) return val.then(rsv).catch(rjc);
+      
+      // No `rjc` means no `try`/`catch` handling
+      if (!rjc) return rsv(val);
+      
+      try { return rsv(val); } catch (err) { return rjc(err); }
+      
+    },
+    thenAll: (vals, ...args /* rsv, rjc */) => {
+      if (vals.seek(v => v instanceof Promise).found) vals = Promise.all(vals);
+      return (then as any)(vals, ...args);
+    },
+
+    // Forms
+    form: ({ name, has={}, pars=has, props=()=>({}) }: { name: string, has?: { [key: string]: any }, pars?: any, props?: any }) => {
+      
+      let reservedFormProps = [ 'constructor', 'Form' ];
+      
+      // Ensure every ParForm is truly a Form
+      for (let [ k, Form ] of pars) if (!Form || !Form['~forms']) throw Error(`Invalid Form: "${k}" (it's Form is ${getFormName(Form)})`);
+      
+      // // TODO: This is definitely faster than `eval`, but it prevents the
+      // // names of Forms from displaying correctly in the console
+      // let Form = function(...p) { return (this && this.constructor === Form) ? this.init(...p) : new Form(...p); }
+      // Object.defineProperty(Form, 'name', { value: name, writable: false, enumerable: true });
+      let fName = name.replace(/[^a-zA-Z0-9]/g, '$');
+      let Form = eval(
+        `let ${fName} = function ${fName}(...p) { return (this && this.Form === Form) ? this.init(...p) : new Form(...p); }; ${fName};`
+      );
+      
+      Form['~forms'] = Set([ Form ]);
+      Form.prototype = Object.create(null);
+      
+      // We'll store a Set of inherited static props for each static key
+      let statics = Object.create(null);
+      
+      // Loop over all ParentForms; for each:
+      // - add to `Form['~forms']` to enable `hasForm` testing
+      // - collect static properties (to apply to `name` later)
+      // - map to a representation of its prototype (to supply Parent
+      //   prototype methods to overriding methods)
+      let protos = Object.assign({}, pars);
+      for (let parName in pars) {
+        
+        let { '~forms': parForms, ...parProps } = pars[parName];
+        
+        // Add all ParentForms to the ~forms Set (facilitates `hasType`)
+        for (let ParForm of parForms) Form['~forms'].add(ParForm);
+        
+        // Collect the rest of the properties
+        for (let [ k, v ] of parProps) {
+          if (!statics[k]) statics[k] = Set();
+          statics[k].add(v);
+        }
+        
+        // `protoDef` sets non-enumerable prototype properties
+        // Iterate non-enumerable props via `Object.getOwnPropertyNames`
+        let proto = pars[parName].prototype;
+        protos[parName] = Object.fromEntries(Object.getOwnPropertyNames(proto).map( n => [ n, proto[n] ] ));
+        
+      }
+      pars = null;
+      
+      // If `props` is a function it becomes the result of its call
+      if (isForm(props, Function)) {
+        
+        // Apply any immediately-unambiguous static properties to `Form`
+        // so they are available to the function body of `props`
+        let immediateStatics: [ string, any ][] = [];
+        for (let k in statics) if (statics[k].size === 1) {
+          immediateStatics.push([ k, [ ...statics[k] ][0] ]);
+        }
+        Object.assign(Form, Object.fromEntries(immediateStatics));
+        
+        props = (props as any)(protos, Form);
+        
+      }
+      
+      // Ensure we have valid "props", and all prop names are valid
+      if (!isForm(props, Object)) throw Error(`Couldn't resolve "props" to Object`);
+      for (let prop of reservedFormProps) if (({}).has.call(props, prop)) throw Error(`Used reserved "${prop}" key`);
+      
+      // Iterate all props of ParForm prototypes; collect inherited ones
+      let propsByName = {};
+      for (let [ formName, proto ] of protos) for (let [ propName, prop ] of proto) {
+        
+        // Skip reserved names (they certainly exist in `formProto`!)
+        if (reservedFormProps.has(propName)) continue;
+        
+        // Store all props under the same name in the same Set
+        if (!({}).has.call(propsByName, propName)) propsByName[propName] = Set();
+        propsByName[propName].add(prop);
+        
+      }
+      
+      // `propsByName` already has all ParForm props; now add in the props
+      // unique to the Form being created!
+      // TODO: Allow classes to define getters + setters??? Should really
+      // be iterating `Object.getOwnPropertyDescriptors(props)` rather
+      // than `props` itself...
+      for (let [ propName, prop ] of props) {
+        
+        if (prop === skip) throw Error(`Provided ${name} @ ${propName} as skip`);
+        
+        // `propName` values iterated here will be unique; `props` is an
+        // object, and must have unique keys. Note `Set` is used to ignore
+        // duplicate properties with the same identity (these would mean
+        // that multiple ancestors define the property, but they define it
+        // to the exact same value!)
+        if (propName[0] === '$') statics[propName.slice(1)] = Set([ prop ]); // Guaranteed to be singular
+        else                     propsByName[propName] = Set([ prop ]);      // Guaranteed to be singular
+        
+      }
+      
+      // At this point ambiguous static props should be resolved
+      for (let k in statics) if (statics[k].size > 1) throw Error(`Multiple static props named "${k}" inherited by Form ${name} (define ${name}.$${k}!)`);
+      
+      if (!({}).has.call(propsByName, 'init')) throw Error('No "init" method available');
+      
+      for (let [ propName, propsOfThatName ] of propsByName) {
+        
+        // If there are collidable props under this name there can only be
+        // one! Multiple collidable props indicates the prop needs to be
+        // defined directly on `Form.prototype`, guaranteeing singularity.
+        // If *no* collidable props are set, use any non-collidable prop
+        let collisionProps = propsOfThatName.toArr(v => (v && v['~noFormCollision']) ? skip : v);
+        
+        // If there are no collision props we still may be able to assign
+        // one of the "no form collision" props; this is useful as calling
+        // the "uncolliding" method gives useful feedback (e.g. "function
+        // not implemented") whereas not defining anything would result in
+        // trying to call `undefined` as a function
+        if (collisionProps.length === 0) {
+          
+          let utilProp = propsOfThatName.seek(v => !!v).val;
+          if (utilProp) collisionProps = [ utilProp ];
+          else          continue;
+          
+        } else if (collisionProps.length > 1) {
+          
+          let definingForms = collisionProps.map(prop => Form['~forms'].seek(ParForm => ParForm.prototype[propName] === prop).val);
+          throw Error([
+            `Form ${name} has ambiguous "${propName}" property `,
+            `from ${collisionProps.length} ParentForms `,
+            `(${definingForms.map(Form => Form ? Form.name : '???').join(', ')}). `,
+            `Define ${name}.prototype.${propName}.`
+          ].join(''));
+          
+        }
+        
+        C.def(Form.prototype, propName, collisionProps[0], { enumerable: false, writable: true });
+        
+      }
+      
+      C.def(Form.prototype, 'Form', Form, { enumerable: false, writable: true });
+      C.def(Form.prototype, 'constructor', Form, { enumerable: false, writable: true });
+      Object.freeze(Form.prototype);
+      
+      // Would be very satisifying to freeze `Form`, but the current
+      // pattern of defining specialized subclasses:
+      //    |     FnSrc.Tmp1 = form(...);
+      // relies on `Form` being mutable :(
+      // TODO: MapSrc and MemSrc are being refactored... maybe do this??
+      for (let k in statics) statics[k] = [ ...statics[k] ][0];
+      Object.assign(Form, statics);
+      // Object.freeze(Form);
+      
+      return Form;
+      
+    },
+    getFormName: f => {
+      if (f === null) return 'Null';
+      if (f === undefined) return 'Undef';
+      if (f !== f) return 'UndefNum';
+      return Object.getPrototypeOf(f)?.constructor.name ?? 'Prototypeless'; // e.g. `getFormName(Object.plain()) === 'Prototypeless'`
+    },
+    isForm: (fact, Form) => {
+      
+      // NaN only matches against the NaN primitive (not the Number Form)
+      if (fact !== fact) return Form !== Form;
+      if (fact == null) return false;
+      
+      return Object.getPrototypeOf(fact).constructor === (Form.Native ?? Form);
+      
+    },
+    hasForm: (fact, FormOrCls) => {
+      
+      if (fact == null) return false;
+      
+      // `fact` may either be a fact/Form, or an instance/Cls. In case a
+      // fact/instance was given, the "constructor" property points us to
+      // the appropriate Form/Cls. We name this value "Form", although it
+      // is ambiguously a Form/Cls.
+      let Form = (Object.getPrototypeOf(fact)?.constructor === Function) ? fact : fact.constructor;
+      if (Form === FormOrCls) return true;
+      
+      // If a "~forms" property exists `FormOrCls` is specifically a Form
+      // and inheritance can be checked by existence in the set
+      if (Form?.['~forms']) return Form['~forms'].has(FormOrCls);
+      
+      // No "forms" property; FormOrCls is specifically a Cls. Inheritance
+      // can be checked using `instanceof`; prefer to compare against a
+      // "Native" property (which facilitates "newless" instances)
+      return (fact instanceof (FormOrCls.Native || FormOrCls));
+      
+    },
+
+    // Keep access
+    keep: () => null,
+
+    // Configuration
+    conf: () => null,
+
+    // Timing
+    getMs: Date.now,
+    getDate: (ms=getMs()) => {
+      let [ yr, mo, dy, hr, mn, sc, ap ] = (new Date(ms)).toLocaleString().split(/[^0-9apm]+/i); // TODO: Happens to work on local and remote, but should probably just provide locale opts??
+      hr = (parseInt(hr, 10) + (ap[0].lower() === 'p' ? 12 : 0)).toString().padHead(2, '0');
+      return `${yr}-${mo}-${dy} ${hr}:${mn}:${sc}`;
+    },
+
+    // Room loading
+    mapCmpToSrc: (file, row, col) => ({ file, row, col, context: null }),
+
+    // Urls
+    uriRaw: ({ path='', cacheBust, query }) => {
+      let url = '';
+      if (cacheBust)               url += `/!${cacheBust}`;
+      if (path)                    url += `/${path}`;
+      if (query && !query.empty()) url += '?' + query.toArr((v, k) => `${k}=${v}`).join('&'); // Note: DON'T encode here!
+      return url;
+    },
+
+    // Util
+    denumerate: (obj, prop) => C.def(obj, prop, obj[prop], { enumerable: false }),
+    formatAnyValue: val => { try { return valToJson(val); } catch (err) { return '<unformattable>'; } },
+    valToJson: JSON.stringify,
+    jsonToVal: JSON.parse,
+    valToSer: JSON.stringify,
+    serToVal: JSON.parse
+    
+  });
+
+  let protoDefs = (Cls, vals) => {
+    
+    if ('$$' in vals) {
+      
+      // Convert, e.g., 'padHead:padStart,padTail:padEnd' into:
+      //    | {
+      //    |   padHead: String.prototype['padStart'],
+      //    |   padTail: String.prototype['padEnd']
+      //    | }
+      
+      let v = Object.fromEntries(vals['$$'].split(',').map(v => (v = v.split(':'), [ v[0], Cls.prototype[v[1]] ])));
+      delete vals['$$'];
+      Object.assign(vals, v);
+      
+    }
+    
+    let keys = Reflect.ownKeys(vals);
+    for (let key of keys) if (isForm(key, String) && key[0] === '$') Cls[key.slice(1)] = vals[key];
+    
+    // Avoid making more properties available on `global` - if a typo
+    // winds up referring to a global property the bug which results
+    // can be highly unexpected!
+    if (Cls === global.constructor) for (let key of keys) if (key[0] !== '$') global[key] = skip;
+    
+    Object.defineProperties(Cls.prototype, Object.fromEntries(
+      keys
+        .filter(key => key[0] !== '$')
+        .map(key => [ key, { enumerable: false, writable: true, value: vals[key] } ])
+    ));
+    
+  };
+  protoDefs(Object, {
+    
+    $stub: Object.freeze({}),
+    $plain: obj => obj ? Object.assign(Object.create(null), obj) : Object.create(null),
+    
+    $$: 'has:hasOwnProperty',
+    
+    at(k, def=skip) {
+      if (k?.constructor === Array && isForm(k, Array)) {
+        let ret = this;
+        for (let p of k) { if (!ret.has(p)) return def; ret = ret[p]; }
+        return ret;
+      }
+      return this.has(k) ? this[k] : def;
+    },
+    each(fn) { for (let [ k, v ] of this) fn(v, k); },
+    map(fn) { // Iterator: (val, key) => val
+      let ret = Object.assign({}, this);
+      for (let k in ret) { let v = fn(ret[k], k); if (v !== skip) ret[k] = v; else delete ret[k]; }
+      return ret;
+    },
+    mapk(fn) { // Iterator: (val, k) => [ k, v ]
+      let arr: any[] = [];
+      for (let k in this) { let v = fn(this[k], k); if (v !== skip) arr.push(v); }
+      return Object.fromEntries(arr);
+    },
+    toArr(fn) { // Iterator: (val, k) => [ k, v ]
+      let ret: any[] = [];
+      for (let k in this) { let v = fn(this[k], k); if (v !== skip) ret.push(v); }
+      return ret;
+    },
+    slice(p) { // TODO: Rename to "subset"?
+      
+      // >> { 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);
+      
+    },
+    omit(p) {
+      
+      let obj = { ...this };
+      for (let k of p) delete obj[k];
+      return obj;
+      
+    },
+    find(f) { // Iterator: (val, key) => bool; returns { found, val=null, key=null }
+      for (let k in this) if (f(this[k], k)) return { found: true, val: this[k], key: k };
+      return { found: false, val: null, k: null };
+    },
+    empty() { for (let k in this) return false; return true; },
+    gain(...objs) {
+      // Note for performance we combine all source Objects first, to
+      // reduce the number of items that need to be checked for skips -
+      // probably worth the overhead of calling `Object.assign` x2
+      let gain = Object.assign({}, ...objs);
+      for (let k in gain) if (gain[k] === skip) delete gain[k];
+      return Object.assign(this, gain);
+    },
+    merge(o) { // Modifies `this` in-place
+      for (let [ k, v ] of o) {
+        // `skip` can be passed to remove properties
+        if (v === skip) { delete this[k]; continue; }
+        
+        // Incoming non-Object properties are simple
+        if (!isForm(v, Object)) { this[k] = v; continue; }
+        
+        // `v` is an Object; existing non-Object replaced with `{}`
+        if (!isForm(this[k], Object) || !this.has(k)) this[k] = {};
+        
+        // And simply recurse!
+        this[k].merge(v);
+      }
+      return this;
+    },
+    built() {
+      let result = {};
+      for (let [ k, v ] of this) {
+        let dive = k.split('.');
+        let last = dive.pop();
+        let ptr = result;
+        for (let cmp of dive) ptr = (ptr.has(cmp) && ptr[cmp] != null) ? ptr[cmp] : (ptr[cmp] = {});
+        ptr[last] = isForm(v, Object) ? v.built() : v;
+      }
+      return result;
+    },
+    * unbuilt(dive=[]) {
+      for (let [ k, val ] of this) {
+        if (isForm(val, Object)) yield* val.unbuilt([ ...dive, k ]);
+        else                     yield { dive: [ ...dive, k ], val };
+      }
+    },
+    count() { let c = 0; for (let k in this) c++; return c; },
+    categorize(fn) { // Iterator: (val, key) => '<categoryTerm>'
+      
+      //  { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6, g: 7, h: 8, i: 9, j: 10 }.categorize(n => {
+      //    if (n < 4) return 'small';
+      //    if (n < 8) return 'medium';
+      //    return 'big';
+      //  });
+      //  >> { small: { a: 1, b: 2, c: 3 }, medium: { d: 4, e: 5, f: 6, g: 7 }, big: { h: 8, i: 9, j: 10 } }
+      
+      let ret = {};
+      for (let [ k, v ] of this) {
+        let t = fn(v, k);
+        if (!ret.has(t)) ret[t] = {};
+        ret[t][k] = v;
+      }
+      return ret;
+      
+    },
+    *[Symbol.iterator]() { for (let k in this) yield [ k, this[k] ]; }
+    
+  });
+  protoDefs(Array, {
+    
+    $stub: Object.freeze([]),
+    $from: Array.from, // (it, fn) => (isForm(it, Array) ? it : [ ...it ]).map(fn),
+    
+    $$: 'each:forEach,has:includes',
+    
+    map(it) { // Iterator: (val, ind) => val
+      let ret: any[] = [];
+      let len = this.length;
+      for (let i = 0; i < len; i++) { let v = it(this[i], i); if (v !== skip) ret.push(v); }
+      return ret;
+    },
+    toArr(it) { return this.map(it); }, // Can't inherit Object.prototype.toArr - it passes keys as Strings!
+    toObj(it) { // Iterator: (val, ind) => [ key0, val0 ]
+      let ret: any[] = [];
+      let len = this.length;
+      for (let i = 0; i < len; i++) { let v = it(this[i], i); if (v !== skip) ret.push(v); }
+      return Object.fromEntries(ret);
+    },
+    
+    seek(f) { // Iterator: (val, ind) => bool; returns { found=false, val=null, ind=null }
+      let n = this.length;
+      for (let i = 0; i < n; i++) if (f(this[i], i)) return { found: true, val: this[i], ind: i };
+      return { found: false, val: null, ind: null };
+    },
+    all(fn=Boolean) { return this.every(fn); },
+    any(fn=Boolean) { return this.some(fn); },
+    sift(fn=Boolean) { return this.filter(fn); },
+    empty() { return !this.length; },
+    add(...args) { this.push(...args); return args[0]; },
+    rem(val) { let ind = this.indexOf(val); if (ind > -1) this.splice(ind, 1); },
+    gain(...arrs) { for (let arr of arrs) this.push(...arr); return this; },
+    count() { return this.length; },
+    valSort(fn) { return this.sort((a, b) => fn(a) - fn(b)); },
+    categorize(fn) { // Iterator: val => '<categoryTerm>'
+      
+      //  [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ].categorize(n => {
+      //    if (n < 4) return 'small';
+      //    if (n < 8) return 'medium';
+      //    return 'big';
+      //  });
+      //  >> { small: [ 1, 2, 3 ], medium: [ 4, 5, 6, 7 ], big: [ 8, 9, 10 ] }
+      
+      let ret = {};
+      for (let elem of this) { let t = fn(elem); if (!ret.has(t)) ret[t] = []; ret[t].push(elem); }
+      return ret;
+      
+    },
+    equals(arr) {
+      if (this.length !== arr.length) return false;
+      for (let i = 0; i < this.length; i++)
+        if (this[i] !== arr[i]) return false;
+      return true;
+    }
+    
+  });
+  protoDefs(String, {
+    
+    $multiline: str => {
+      
+      let lines = str.replace(/\r/g, '').split('\n');
+      
+      // Trim any leading empty lines
+      while (lines.length && !lines[0].trim()) lines = lines.slice(1);
+      
+      // Count leading whitespace chars on first line with content
+      let initSpace = 0;
+      while (lines[0][initSpace] === ' ') initSpace++;
+      
+      let ret = lines.map(ln => ln.slice(initSpace)).join('\n');
+      return ret.trimTail();
+      
+    },
+    $baseline: (str, seq='| ') => {
+      
+      return str.split('\n').map(ln => {
+        ln = ln.trimHead();
+        if (!ln.startsWith(seq)) return skip; // After whitespace should come `seq`; ignore lines not containing `seq`!
+        return ln.slice(seq.length).trimTail(); // Trim off the baseline; remove tailing whitespace
+      }).join('\n');
+      
+    },
+    $charset: str => {
+      let cache = Map<string, bigint>();
+      return {
+        str,
+        size: BigInt(str.length),
+        charVal: (c: string) => {
+          if (!cache.has(c)) {
+            let ind = str.indexOf(c);
+            if (ind < 0) throw Error('Char outside charset');
+            cache.set(c, BigInt(ind));
+          }
+          return cache.get(c);
+        },
+        valChar: (n: bigint) => {
+          if (n < 0 || n >= str.length) throw Error('Val outside charset');
+          return str[n as any as number];
+        }
+      };
+    },
+    $base32: '0123456789abcdefghijklmnopqrstuv',
+    $base36: '0123456789abcdefghijklmnopqrstuvwxyz',
+    $base62: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ',
+    $base64: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ=-',
+    
+    $$: 'has:includes,hasHead:startsWith,hasTail:endsWith,padHead:padStart,padTail:padEnd,trimHead:trimStart,trimTail:trimEnd,upper:toUpperCase,lower:toLowerCase',
+    
+    cut(delim, cuts=1) { // e.g. `cuts === 1` produces Array of length 2
+      // `cuts` defines # of cuts (resulting array length is `num + 1`)
+      let split = this.split(delim, cuts < Infinity ? cuts : skip);
+      let numDelimsSplit = split.length - 1;
+      let lenConsumed = 0
+        + split.reduce((a, s) => a + s.length, 0)
+        + delim.length * numDelimsSplit;
+      if (lenConsumed < this.length) split = [ ...split, this.slice(lenConsumed + delim.length) ];
+      return split;
+    },
+    code(ind=0) { return this.charCodeAt(0); },
+    count() { return this.length; },
+    indent(...args /* amt=2, char=' ' | indentStr=' '.repeat(2) */) {
+      
+      if (!this) return this; // No-op on empty String (otherwise it would transform a 0-line string to a 1-line string)
+      let indentStr: string;
+      if (isForm(args[0], String)) { indentStr = args[0]; }
+      else                         { let [ amt=2, char=' ' ] = args; indentStr = char.repeat(amt); }
+      return this.split('\n').map(ln => `${indentStr}${ln}`).join('\n');
+      
+    },
+    encodeInt(charset: string | CharSet=String.base62) {
+      
+      if (isForm(charset, String)) charset = String.charset(charset);
+      
+      let base = charset.size;
+      if (base === 1n) return this.count();
+      
+      let sum = 0n;
+      let n = this.length;
+      for (let ind = 0; ind < n; ind++)
+        // Earlier values of `i` represent higher places same as with written numbers further left
+        // digits are more significant
+        // The value of the place `i` is `ind - 1`
+        sum += (base ** BigInt(n - ind - 1)) * charset.charVal(this[ind]);
+      return sum;
+      
+    },
+    reencode(srcCharset: string | CharSet, trgCharset: string | CharSet) {
+      return this.encodeInt(srcCharset).encodeStr(trgCharset);
+    }
+    
+  });
+  protoDefs(Number, {
+    
+    $int32: Math.pow(2, 32),
+    $int64: Math.pow(2, 64),
+    
+    char() { return String.fromCharCode(this); },
+    each(fn) { for (let i = 0; i < this; i++) fn(i); },
+    toArr(fn) { let arr = new Array(this || 0); for (let i = 0; i < this; i++) arr[i] = fn(i); return arr; },
+    toObj(fn) { // Iterator: n => [ key, val ]
+      let ret: [ string, any ][] = [];
+      for (let i = 0; i < this; i++) { let v = fn(i); if (v !== skip) ret.push(v); }
+      return Object.fromEntries(ret);
+    },
+    encodeStr(charset: string | CharSet, padLen=0) {
+      
+      // Note that base-1 requires 0 to map to the empty string. This also
+      // means that, for `n >= 1`:
+      //      |       (n).encodeStr(singleChr)
+      // is always equivalent to
+      //      |       singleChr.repeat(n - 1)
+      
+      if (isForm(charset, String)) charset = String.charset(charset);
+      
+      let base = charset.size;
+      if (base === 1n && padLen) throw Error(`Can't pad when using base-1 encoding`);
+      
+      if (this !== this) return (base === 1n) ? '' : charset[0].repeat(Math.max(padLen, 1));
+      
+      let num = this.constructor === BigInt ? this : BigInt(Math.floor(this));
+      let digits: string[] = [];
+      while (num) { digits.push(charset.valChar(num % base)); num /= base; }
+      return digits.reverse().join('').padHead(padLen, charset.str[0]);
+      
+    },
+    isInteger() { return this === Math.round(this); }, // No bitwise shortcut - it disrupts Infinity
+    * [Symbol.iterator]() { for (let i = 0; i < this; i++) yield i; },
+    * bits() { let n = this >= 0 ? this : -this; while (n) { yield n & 1; n = n >> 1; } },
+    
+    map: undefined // Prevent `Number(...).map`
+    
+  });
+  protoDefs(BigInt, {
+    
+    encodeStr: Number.prototype.encodeStr
+    
+  });
+  protoDefs(Function, {
+    
+    $stub: v => v,
+    $createStub: v => () => v,
+    bound(...args) { return this.bind(null, ...args); }
+    
+  });
+  protoDefs(Error, {
+    
+    $stackTraceLimit: 150,
+    
+    mod(props: any = {} /* { cause, msg, message, ...more } */) {
+      
+      if (isForm(props, Function)) props = props(this.message, this);
+      if (isForm(props, String)) props = { message: props };
+      
+      let { 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
+      //   an Array or Object!
+      // - Assign `moreProps` to transfer any other properties
+      // - Add `message` prop
+      // - Only add `cause` prop if `cause` is non-null
+      return Object.assign(this, hasForm(cause, Error) ? cause : {}, moreProps, cause ? { message, cause } : { message });
+      
+    },
+    propagate(props /* { cause, msg, message, ...more } */) { throw this.mod(props); },
+    suppress() {
+      this['~suppressed'] = true;
+      
+      if (!this.cause) return;
+      let causes = (hasForm(this.cause, Error) ? [ this.cause ] : this.cause);
+      causes.each(err => err.suppress());
+    }
+    
+  });
+
+  let newlessProtoDefs = (Cls, vals) => {
+    
+    // Extend prototypes and allow instantiation without "new"
+    
+    let name = Cls.name;
+    let Newless = global[name] = function(...args) { return new Cls(...args); } as any;
+    C.def(Newless, 'name', name);
+    Newless.Native = Cls;
+    Newless.prototype = Cls.prototype;
+    
+    protoDefs(Newless, vals);
+    
+  };
+  newlessProtoDefs(Promise, {
+    
+    $all: (prms, mapFn=null) => {
+      
+      if (mapFn) prms = prms.map(mapFn);
+      
+      if (isForm(prms, Array)) return C['Promise.all'](prms).then(a => a.toArr(v => v)); // Remove any `skip` results
+      
+      if (isForm(prms, Object)) {
+        
+        // Need to get `keys` here in case `obj` mutates before resolution
+        let keys = Object.keys(prms);
+        return C['Promise.all'](Object.values(prms))
+          .then(vals => { let ret = {}; for (let [ i, k ] of keys.entries()) ret[k] = vals[i]; return ret; });
+        
+      }
+      
+      throw Error(`Unexpected parameter for Promise.all: ${getFormName(prms)}`);
+      
+    },
+    $resolve: Promise.resolve,
+    $reject: Promise.reject,
+    $later: (resolve, reject) => {
+      let p = Promise((...a) => [ resolve, reject ] = a);
+      return Object.assign(p, { resolve, reject });
+    },
+    
+    $$: 'route:then,fail:catch'
+    
+  });
+  newlessProtoDefs(Set, {
+    
+    $stub: { count: () => 0, add: Function.stub, rem: Function.stub, has: () => false, values: () => Array.stub },
+    
+    $$: 'each:forEach,rem:delete',
+    
+    map(fn) { // Iterator: (val, ind) => val0
+      let ret: any[] = [], ind = 0;
+      for (let v of this) { v = fn(v, ind++); if (v !== skip) ret.push(v); }
+      return ret;
+    },
+    find(fn) { // Iterator: (val) => bool; returns { found, val }
+      for (let val of this) if (fn(val)) return { found: true, val };
+      return { found: false, val: null };
+    },
+    count() { return this.size; },
+    empty() { return !this.size; },
+    toArr(...args) { return this.map(...args); },
+    toObj(fn) {
+      let ret: any[] = [];
+      for (let v of this) { v = fn(v); if (v !== skip) ret.push(v); }
+      return Object.fromEntries(ret);
+    }
+    
+  });
+  newlessProtoDefs(Map, {
+    
+    $stub: { count: () => 0, set: Function.stub, rem: Function.stub, has: () => false, values: () => Array.stub },
+    
+    $$: 'each:forEach,add:set,rem:delete',
+    
+    map(fn) { // Iterator: (val, key) => [ key0, val0 ]
+      let ret: any = [];
+      for (let [ k, v ] of this) { v = fn(v, k); if (v !== skip) ret.push(v); }
+      return Object.fromEntries(ret);
+    },
+    find(f) { // Iterator: (val, key) => bool; returns { found, val, key }
+      for (let [ k, v ] of this) if (f(v, k)) return { found: true, val: v, key: k };
+      return { found: false, val: null, key: null };
+    },
+    count() { return this.size; },
+    empty() { return !this.size; },
+    toObj(...args) { return this.map(...args); },
+    toArr(fn) { // Iterator: (val, key) => val0
+      let ret: any[] = [];
+      for (let [ k, v ] of this) { v = fn(v, k); if (v !== skip) ret.push(v); }
+      return ret;
+    }
+    
+  });
+  newlessProtoDefs(GeneratorFunction, {
+    each(fn) { for (let v of this) fn(v); },
+    toArr(fn) { return [ ...this ].map(fn); },
+    toObj(fn) {
+      let ret = {};
+      for (let v of this) { v = fn(v); if (v !== skip) ret[v[0]] = v[1]; }
+      return ret;
+    }
+  });
+}

package/global.d.ts

@@ -0,0 +1,197 @@
+// Util
+type fn = (...args: any[]) => any;
+type obj = { [key: string]: any };
+type maybeFn<T> = T | ((...args: any[]) => T);
+type maybeFnResolved<T> = T extends (...args: any[]) => any ?  ReturnType<T> : T;
+type MaybePromise<T> = T | Promise<T>;
+
+// Forms
+type formConfig = {
+  name: string,
+  has: { [key: string]: any },
+  props: { [key: string]: any }
+};
+type Form<props extends {}, initArgs extends any[], state extends {}> = {
+  '~props': maybeFnResolved<props>,
+  '~initArgs': initArgs,
+  '~state': state,
+  (...a: initArgs): formInstance<Form<props, initArgs, state>>,
+  new (...a: initArgs): formInstance<Form<props, initArgs, state>>
+};
+type formInstance<MyForm extends Form> = { '~form': MyForm }
+  & { [ key in keyof MyForm['~props'] ]: MyForm['~props'][key] }
+  & { [ key in keyof MyForm['~state'] ]: MyForm['~state'][key] };
+
+// Globals
+declare const global: any;
+declare const window: any;
+declare const getFormName: (f: any) => string;
+declare const denumerate: (val: any, name: string) => void;
+declare const skip: never;
+declare const isForm: {
+  (val: any, arr: FunctionConstructor): val is fn;
+  (val: any, obj: ObjectConstructor): val is { [key: string]: any };
+  (val: any, str: StringConstructor): val is string;
+  (val: any, num: NumberConstructor): val is number;
+  (val: any, arr: ArrayConstructor): val is any[];
+  <T>(val: any, prm: PromiseConstructor): val is Promise<T>;
+  <T>(val: any, t: T): val is T;
+}
+declare const hasForm: {
+  (val: any, t: any): boolean;
+}
+declare const form: <initArgs extends any[], state extends {}>(c: formConfig) => Form<formConfig['props'], initArgs, state>;
+declare const formatAnyValue: (val: any) => string;
+declare const C: {
+  def: fn
+};
+declare const getMs: () => number;
+declare const getDate: () => string;
+declare const then: (val: any, resolve: fn, reject?: fn) => any;
+declare const valToJson: (val: any) => string;
+declare const valToSer: (val: any) => string;
+declare const jsonToVal: (val: string | Buffer | null) => any;
+declare const GeneratorFunction: any;
+declare const global: { [key: string|symbol]: any } & {
+  skip: typeof skip,
+  GeneratorFunction: typeof GeneratorFunction,
+  isForm: typeof isForm,
+  hasForm: typeof hasForm,
+  formatAnyValue: typeof formatAnyValue,
+  then: typeof then,
+  getMs: typeof getMs,
+  getDate: typeof getDate,
+  valToJson: typeof valToJson,
+  jsonToVal: typeof jsonToVal,
+  C: typeof C,
+  denumerate: typeof denumerate
+};
+
+interface JSON {
+  parse: (val: Buffer) => any
+}
+
+interface Array<T> {
+  any: (fn: fn) => boolean,
+  has: (val: T) => boolean,
+  add: (val: T) => void,
+  count: () => number,
+  valSort: (fn: (val: T) => number) => Array<T>,
+  find: (fn: fn) => ({ found: true, val: T } | { found: false }),
+  each: (fn: (val: T) => void) => void,
+  empty: () => boolean,
+  equals: <Z>(arr: Array<T>) => Z extends T ? boolean : false,
+  toObj: (fn: fn) => any,
+  seek: (fn: (val: T) => any) => { found: boolean, val: T | undefined, ind: number },
+}
+interface ArrayConstructor {
+  stub: any[]
+}
+
+interface Error {
+  mod: (props: { [key: string]: any }) => Error
+  propagate: (props?: { [key: string]: any }) => never
+}
+
+interface FunctionConstructor {
+  stub: (...args: any[]) => any
+}
+interface Function {
+  bound: fn
+}
+
+interface GeneratorFunctionConstructor {
+}
+
+interface Number {
+  encodeStr: (str: string | CharSet, len?: number) => string,
+  each: (fn: (n: number) => void) => void,
+  toArr: <T>(fn: (n: number) => T) => T[]
+}
+interface NumberConstructor {
+  int32: number
+}
+
+interface BigInt {
+  encodeStr: Number[encodeStr]
+}
+
+interface ObjectConstructor {
+}
+interface Object {
+  empty: () => boolean,
+  has: (k: string) => boolean,
+  map: (fn: (val: any, key: string) => any) => any,
+  mapk: (fn: (val: any, key: string) => [ string, any ]) => any,
+  at: (k: string | string[], def?: any) => any,
+  plain: (obj?: any) => any,
+  slice: <T>(this: T, keys: (keyof T)[]) => Partial<T>,
+  omit: <T>(this: T, keys: (keyof T)[]) => Partial<T>,
+  toArr: <T extends (v: any, k: string) => any>(fn: T) => ReturnType<T>[],
+  built: () => Object,
+  merge: <T>(val: T) => Object & T,
+  gain: (...args: any[]) => any,
+  [Symbol.iterator]: () => Iterator<[ string, any]>
+}
+
+interface Promise<T> {
+  fail: Promise<T>['catch'],
+}
+
+interface PromiseLater<T=void> extends Promise<T> {
+  resolve: T extends void ? () => void : (v: T) => void,
+  reject: (err: any) => void
+}
+interface PromiseConstructor {
+  <T>(fn: (resolve: (v: T) => void, reject: (err: any) => void) => any): Promise<T>,
+  later: <T=void>() => PromiseLater<T>,
+  all: {
+    <T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]>;
+    
+    //<T>(arr: Promise<T>[]): Promise<T[]>,
+    //<T>(obj: { [key: string]: Promise<T> }): Promise<{ [key: string]: T }>
+  }
+}
+
+interface SetConstructor {
+  <T>(arr?: T[]): Set<T>
+}
+interface Set<T> {
+  toArr: (fn: (val: T, ind: number) => void) => T[],
+  rem: (val: T) => void
+}
+
+interface MapConstructor {
+  <K, V>(arr?: [ K, V ][]): Map<K, V>
+}
+interface Map<K, V> {
+  add: (k: K, v: V) => void,
+  toArr: <T>(fn: (val: V, key: K) => T) => T[],
+  rem: (key: K) => void
+}
+
+type CharSet = { str: string, size: bigint, charVal: (c: string) => bigint, valChar: (n: bigint) => string };
+interface String {
+  count(): number,
+  padHead(n: number, s?: string): string,
+  padTail(n: number, s?: string): string,
+  encodeInt: (chrs: string | CharSet) => bigint,
+  reencode: (src: string | CharSet, trg: string | CharSet) => string,
+  trimHead(): string,
+  trimTail(): string,
+  hasHead(head: string): boolean,
+  upper(): string,
+  lower(): string,
+  cut(str: string, cuts?: number): string[],
+  indent: {
+    (amount: number, char?: string): string,
+    (str: string): string
+  }
+}
+interface StringConstructor {
+  charset: (str: string) => CharSet,
+  base32: string,
+  base62: string,
+  baseline: (str: string) => str,
+  multiline: (str: string) => str,
+}

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@gershy/clearing",
+  "version": "0.0.1",
+  "description": "Simplified js basics",
+  "main": "main.ts",
+  "scripts": {
+    "test": "node ./test/main.ts"
+  },
+  "author": "Gershom Maes",
+  "license": "ISC"
+}