@magmacomputing/tempo 1.0.0

package/dist/enumerate.library.d.ts

@@ -0,0 +1,64 @@
+import type { Index, Prettify, Entry, Invert, Property, CountOf, KeyOf, ValueOf, EntryOf, LooseKey, WellKnownSymbols } from './type.library.js';
+/** used to identify the Enumify type */ declare const tag: "Enumify";
+/** This is the prototype signature for an Enum object. */ type Proto<T extends Property<any>> = Readonly<{
+    /** count of Enum keys */ count(): CountOf<KeyOf<T>>;
+    /** array of Enum keys */ keys(): KeyOf<T>[];
+    /** array of Enum values */ values(): ValueOf<T>[];
+    /** tuple of Enum entries */ entries(): EntryOf<T>[];
+    /** new Enum with inverted key-values except invert() */ invert(): Prettify<Invert<T> & Omit<Proto<T>, "invert">>;
+    /** serialized Enum */ toString(): string;
+    /** key exists in Enum */ has<K extends LooseKey<keyof T>>(key: K): boolean;
+    /** value exists in Enum */ includes<V extends LooseKey<T[keyof T]>>(value: V): boolean;
+    /** reverse lookup of Enum key by value */ keyOf<V extends ValueOf<T>>(value: V): Invert<T>[V];
+    /** loop over Enum entries */ forEach(fn: (entry: EntryOf<T>, index: number, enumify: Enum.wrap<T>) => void, thisArg?: any): void;
+    /** subset of Enum entries */ filter(fn: (entry: EntryOf<T>, index: number, enumify: Enum.wrap<T>) => boolean, thisArg?: any): Enum.wrap<T>;
+    /** map of Enum entries */ map<U>(fn: (entry: EntryOf<T>, index: number, enumify: Enum.wrap<T>) => [PropertyKey, U] | U, thisArg?: any): any;
+    /** iterator for Enum */ [Symbol.iterator](): Iterator<Entry<T extends {} ? T : never>, EntryOf<T>>;
+    /** string tag */ [Symbol.toStringTag]: typeof tag;
+}>;
+/** namespace for Enum type-helpers */
+type Methods<T extends Property<any> = any> = Omit<Proto<T>, WellKnownSymbols>;
+export declare namespace Enum {
+    /** Enum properties & methods */ type wrap<T extends Property<any>> = props<T> & Methods<T>;
+    /** Enum methods (filtered) */ type methods<T extends Property<any> = any> = keyof Methods<T>;
+    /** Enum own properties */ type props<T extends Property<any>> = Readonly<T>;
+}
+/** Argument can be an array of PropertyKeys */ type ArrayArg = ReadonlyArray<PropertyKey>;
+/** Argument can be a JSON object */ type ObjectArg = Record<PropertyKey, any>;
+/**
+ * # Enumify
+ * The intent of this function is to provide Javascript-supported syntax for an object to behave as a read-only Enum.
+ * It can be used instead of Typescript's Enum (which must be compiled down to plain Javascript, and is not supported in NodeJS)
+ *
+ * @example
+ * ```typescript
+ * const SEASON = enumify({ Spring: 'spring', Summer: 'summer', Autumn: 'autumn', Winter: 'winter' });
+ * type SEASON = ValueOf<typeof SEASON>
+ * ```
+ *
+ * | Method | Value |
+ * | :--- | :---- |
+ * | `SEASON.keys()` | ['Spring', 'Summer', 'Autumn', 'Winter'] |
+ * | `SEASON.values()` | ['spring', 'summer', 'autumn', 'winter'] |
+ * | `SEASON.entries()` | ['Spring','spring'], ['Summer','summer'], ['Autumn','autumn'], ['Winter','winter']] |
+ * | `SEASON.count()` | 4 |
+ * | `SEASON.keyOf(SEASON.Summer)` | 'Summer' (using the Enum value directly) |
+ * | `SEASON.keyOf('summer')` | 'Summer' (using a string value) |
+ * | `SEASON.toString()` | '{"Spring": "spring", "Summer": "summer", "Autumn": "autumn", "Winter": "winter"}' |
+ * | `SEASON.invert() ` | enumify({spring: 'Spring', summer: 'Summer', autumn: 'Autumn', winter: 'Winter'}) |
+ * | `SEASON.has('xxx')` | false (using an invalid key) |
+ * | `SEASON.includes('summer')` | true (using a string value) |
+ * | `Object.prototype.toString.call(SEASON).slice(8,-1)` | 'Enumify' |
+ *
+ * @template T - The structure of the enumeration (Array or Object)
+ * if Array, Values will be the array indices.  if Object, keys and values are preserved.
+ * @param {T} list - The list of keys (Array) or key-value pairs (Object) to enumify
+ * @returns {Enum.wrap<T>} A frozen object enhanced with enumeration methods
+ */
+export declare function enumify<const T extends ArrayArg>(list: T): Enum.wrap<Index<T>>;
+export declare function enumify<const T extends ObjectArg>(list: T): Enum.wrap<T>;
+/** create an entry in the Serialization Registry to describe how to rebuild an Enum */
+export declare class Enumify {
+    constructor(list: Property<any>);
+}
+export {};

package/dist/enumerate.library.js

@@ -0,0 +1,54 @@
+import { secure } from './utility.library.js';
+import { Serializable } from './class.library.js';
+import { stringify } from './serialize.library.js';
+import { memoizeMethod } from './function.library.js';
+import { ownKeys, ownValues, ownEntries } from './reflection.library.js';
+import { asType, isArray } from './type.library.js';
+/** used to identify the Enumify type */ const tag = 'Enumify';
+/**
+ * This is the prototype implementation for an Enum object.
+ * It contains just the methods / symbols we need, without standard Object methods like `hasOwnProperty`, etc.
+ */
+const ENUM = secure(Object.create(null, {
+    count: memoizeMethod('count', function () { return ownKeys(this).length; }),
+    keys: memoizeMethod('keys', function () { return ownKeys(this); }),
+    values: memoizeMethod('values', function () { return ownValues(this); }),
+    entries: memoizeMethod('entries', function () { return ownEntries(this); }),
+    invert: memoizeMethod('invert', function () { return enumify(this.entries().reduce((acc, [key, val]) => ({ ...acc, [val]: key }), {})); }),
+    toString: memoizeMethod('toString', function () { return stringify({ ...this }); }),
+    has: value(function (key) { return this.keys().includes(key); }),
+    includes: value(function (search) { return this.values().includes(search); }),
+    keyOf: value(function (search) { return this.invert()[search]; }),
+    forEach: value(function (fn, thisArg) { this.entries().forEach((entry, index) => fn.call(thisArg, entry, index, this)); }),
+    filter: value(function (fn, thisArg) { return enumify(this.entries().reduce((acc, entry, index) => (fn.call(thisArg, entry, index, this) ? Object.assign(acc, { [entry[0]]: entry[1] }) : acc), {})); }),
+    map: value(function (fn, thisArg) { return enumify(this.entries().reduce((acc, entry, index) => { const res = fn.call(thisArg, entry, index, this); return Object.assign(acc, isArray(res) && res.length === 2 ? { [res[0]]: res[1] } : { [entry[0]]: res }); }, {})); }),
+    [Symbol.iterator]: value(function () { return this.entries()[Symbol.iterator](); }),
+    [Symbol.toStringTag]: value(tag),
+}));
+/** define a Descriptor for an Enum's method */
+function value(value) {
+    return Object.assign({ enumerable: false, configurable: false, writable: false, value });
+}
+export function enumify(list) {
+    const arg = asType(list);
+    const stash = {};
+    switch (arg.type) {
+        case 'Object':
+            Object.assign(stash, arg.value);
+            break;
+        case 'Array':
+            arg.value // reduce Array to an Object with indexes as values
+                .reduce((_, itm, idx) => Object.assign(stash, { [itm]: idx }), stash);
+            break;
+        default:
+            throw new Error(`enumify requires an Object or Array as input: received ${arg.type} instead`);
+    }
+    return secure(Object.create(ENUM, Object.getOwnPropertyDescriptors(stash)));
+}
+/** create an entry in the Serialization Registry to describe how to rebuild an Enum */
+@Serializable
+export class Enumify {
+    constructor(list) {
+        return enumify(list);
+    }
+}

package/dist/function.library.d.ts

@@ -0,0 +1,9 @@
+import { type Property } from './type.library.js';
+type Curry<Args extends any[], Res> = Args extends [infer FirstArg, ...infer RestArgs] ? (arg: FirstArg) => Curry<RestArgs, Res> : Res;
+/** curry a Function to allow partial calls */
+export declare function curry<Args extends any[], Res>(fn: (...args: Args) => Res): Curry<Args, Res>;
+/** generic function to memoize repeated function calls */
+export declare function memoizeFunction<F extends (...args: any[]) => any>(fn: F): (...args: unknown[]) => ReturnType<F> | undefined;
+/** define a Descriptor for an Object's memoized-method */
+export declare function memoizeMethod<T>(name: PropertyKey, fn: (this: Property<any>, ...args: any[]) => T): PropertyDescriptor;
+export {};

package/dist/function.library.js

@@ -0,0 +1,49 @@
+import { secure } from './utility.library.js';
+import { isUndefined } from './type.library.js';
+/** curry a Function to allow partial calls */
+export function curry(fn) {
+    return function curried(...args) {
+        return (args.length >= fn.length)
+            ? fn(...args)
+            : (...nextArgs) => curried(...args, ...nextArgs);
+    };
+}
+/** generic function to memoize repeated function calls */
+export function memoizeFunction(fn) {
+    const cache = new Map(); // using a Map for better key handling than plain objects
+    return function (...args) {
+        const key = JSON.stringify(args); // create a unique key from arguments
+        console.log('memoize: ', key);
+        if (!cache.has(key)) {
+            // @ts-ignore
+            const result = fn.apply(this, args); // call the original function with the correct context
+            console.log('set: ', result);
+            cache.set(key, Object.freeze(result)); // stash the result for subsequent calls
+        }
+        else
+            console.log('get: ', cache.get(key));
+        return cache.get(key);
+    };
+}
+const wm = new WeakMap();
+/** define a Descriptor for an Object's memoized-method */
+export function memoizeMethod(name, fn) {
+    return {
+        enumerable: true,
+        configurable: false,
+        writable: false,
+        value: function (...args) {
+            const key = `${String(name)},${JSON.stringify(args)}`;
+            let cache = wm.get(this);
+            if (!cache) { // add a new object into the WeakMap
+                cache = Object.create(null);
+                wm.set(this, cache);
+            }
+            if (isUndefined(cache[key])) { // first time for this method
+                cache[key] = fn.apply(this, args); // evaluate the method
+                secure(cache[key]); // freeze the returned value
+            }
+            return cache[key];
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { Tempo } from './tempo.class.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Tempo } from './tempo.class.js';
+// Add any other intended public exports here. 
+// For now, Tempo is the primary interface.

package/dist/logify.class.d.ts

@@ -0,0 +1,33 @@
+import { type ValueOf } from './type.library.js';
+declare const Method: {
+    readonly Log: "log";
+    readonly Info: "info";
+    readonly Warn: "warn";
+    readonly Debug: "debug";
+    readonly Error: "error";
+};
+/**
+ * provide standard logging methods to the console for a class
+ */
+export declare class Logify {
+    #private;
+    /**
+     * if {catch:true} then show a warning on the console and return
+     * otherwise show an error on the console and re-throw the error
+     */
+    catch(...msg: any[]): void;
+    /** console.log */ log: (...args: any[]) => void;
+    /** console.info */ info: (...args: any[]) => void;
+    /** console.warn */ warn: (...args: any[]) => void;
+    /** console.debug */ debug: (...args: any[]) => void;
+    /** console.error */ error: (...args: any[]) => void;
+    constructor(self?: Logify.Constructor | string, opts?: Logify.Constructor);
+}
+export declare namespace Logify {
+    type Method = ValueOf<typeof Method>;
+    interface Constructor {
+        debug?: boolean | undefined;
+        catch?: boolean | undefined;
+    }
+}
+export {};

package/dist/logify.class.js

@@ -0,0 +1,53 @@
+import { Immutable } from './class.library.js';
+import { asType } from './type.library.js';
+const Method = {
+    Log: 'log',
+    Info: 'info',
+    Warn: 'warn',
+    Debug: 'debug',
+    Error: 'error',
+};
+/**
+ * provide standard logging methods to the console for a class
+ */
+@Immutable
+export class Logify {
+    #name;
+    #opts = {};
+    #log(method, ...msg) {
+        if (this.#opts.debug)
+            console[method](this.#name, ...msg);
+    }
+    /**
+     * if {catch:true} then show a warning on the console and return
+     * otherwise show an error on the console and re-throw the error
+     */
+    catch(...msg) {
+        if (this.#opts.catch) {
+            this.warn(...msg); // show a warning on the console
+            return; // safe-return
+        }
+        this.error(...msg); // this goes to the console
+        throw new Error(`${this.#name}${msg}`); // this goes back to the caller
+    }
+    /** console.log */ log = this.#log.bind(this, Method.Log);
+    /** console.info */ info = this.#log.bind(this, Method.Info);
+    /** console.warn */ warn = this.#log.bind(this, Method.Warn);
+    /** console.debug */ debug = this.#log.bind(this, Method.Debug);
+    /** console.error */ error = this.#log.bind(this, Method.Error);
+    constructor(self, opts = {}) {
+        const arg = asType(self);
+        switch (arg.type) {
+            case 'String':
+                this.#name = arg.value;
+                break;
+            // @ts-ignore
+            case 'Object':
+                Object.assign(opts, arg.value);
+            default:
+                this.#name = (self ?? this).constructor.name.concat(': ') ?? '';
+        }
+        this.#opts.debug = opts.debug ?? false; // default debug to 'false'
+        this.#opts.catch = opts.catch ?? false; // default catch to 'false'								
+    }
+}

package/dist/number.library.d.ts

@@ -0,0 +1,16 @@
+import type { TValues } from './type.library.js';
+/** convert String | Number | BigInt to Number */
+export { asNumber, asInteger, isNumeric, ifNumeric } from './coercion.library.js';
+/** show Hex value of a number */
+export declare const toHex: (num?: TValues<number>, len?: number) => string;
+/** apply an Ordinal suffix */
+export declare const suffix: (idx: number) => string;
+/** split a value into an array */
+export declare function split<T extends number>(nbr: T, chr?: string, zero?: boolean): number[];
+export declare function split<T extends string>(nbr: T, chr?: string, zero?: boolean): (string | number)[];
+/** fix a string to set decimal precision */
+export declare const fix: (nbr?: string | number, max?: number) => string;
+/** remove ':' from an HH:MI string, return as number */
+export declare const asTime: (hhmi: string | number) => number;
+/** format a value as currency */
+export declare const asCurrency: (str: string | number, scale?: number, currency?: string) => string;

package/dist/number.library.js

@@ -0,0 +1,36 @@
+import { asArray, asNumber, ifNumeric } from './coercion.library.js';
+/** convert String | Number | BigInt to Number */
+export { asNumber, asInteger, isNumeric, ifNumeric } from './coercion.library.js';
+/** show Hex value of a number */
+export const toHex = (num = [], len) => asArray(num) // ensure array
+    .flat(1_000_000) // flatten any arrays to arbitrary depth
+    .filter(Number.isInteger) // ensure integers	
+    .map(val => (val + 0x100).toString(16).slice(-2))
+    .join('')
+    .toLowerCase()
+    .substring(0, len ?? Number.MAX_SAFE_INTEGER);
+/** apply an Ordinal suffix */
+export const suffix = (idx) => {
+    const str = String(idx ?? ''); // so we can use 'endsWith'
+    switch (true) {
+        case str.endsWith('1') && !str.endsWith('11'):
+            return str + 'st';
+        case str.endsWith('2') && !str.endsWith('12'):
+            return str + 'nd';
+        case str.endsWith('3') && !str.endsWith('13'):
+            return str + 'rd';
+        default:
+            return str + 'th';
+    }
+};
+export function split(nbr, chr = '.', zero = true) {
+    return nbr?.toString().split(chr).map(val => ifNumeric(val, zero))
+        || [];
+}
+;
+/** fix a string to set decimal precision */
+export const fix = (nbr = 0, max = 2) => asNumber(nbr).toFixed(max);
+/** remove ':' from an HH:MI string, return as number */
+export const asTime = (hhmi) => Number(String(hhmi).replace(':', ''));
+/** format a value as currency */
+export const asCurrency = (str, scale = 2, currency = 'AUD') => str.toLocaleString(void 0, { style: 'currency', currency, maximumFractionDigits: scale });

package/dist/object.library.d.ts

@@ -0,0 +1,37 @@
+import type { Extend, Property } from './type.library.js';
+/** Get nested value */
+export declare function extract<T>(obj: any, path: string | number, dflt?: T): T;
+/** remove quotes around property names */
+export declare const unQuoteObj: (obj: any) => string;
+/** copy enumerable properties to a new Object */
+export declare const asObject: <T>(obj?: Record<PropertyKey, any>) => T;
+/** deep-compare object values for equality */
+export declare const isEqual: (obj1?: any, obj2?: any) => boolean;
+/** find all methods on an Object */
+export declare const getMethods: (obj: any, all?: boolean) => PropertyKey[];
+/** extract only defined values from Object */
+export declare function ifDefined<T extends Property<any>>(obj: T): T;
+/** extract a subset of keys from an object */
+export declare const pick: <T extends Property<T>, K extends string>(obj: T, ...keys: K[]) => Partial<T>;
+/** extract a named key from an array of objects */
+export declare const pluck: <T, K extends keyof T>(objs: T[], key: K) => T[K][];
+/** extend an object with the properties of another */
+export declare const extend: <T extends {}, U>(obj: T, ...objs: U[]) => T;
+export declare const countProperties: (obj?: {}) => number;
+/**
+ * helper to define objects with fixed literal properties
+ * and a loose index signature for further extensions.
+ * @example
+ * ```
+ * const obj = looseIndex<string,string>()({ foo: 'bar', bar: 'foo' });
+ * type obj = typeof obj
+ * ```
+ */
+export declare function looseIndex<K extends PropertyKey = string, V = any>(): <const T extends object>(obj: T | (() => T)) => Extend<T, K, V>;
+export declare function looseIndex<const T extends object>(obj: T | (() => T)): Extend<T, string, any>;
+export declare namespace looseIndex {
+    var stringSymbol: <const T extends object>(obj: T | (() => T)) => Extend<T, string, symbol>;
+    var symbolRegExp: <const T extends object>(obj: T | (() => T)) => Extend<T, symbol, RegExp>;
+    var symbolString: <const T extends object>(obj: T | (() => T)) => Extend<T, symbol, string>;
+    var stringString: <const T extends object>(obj: T | (() => T)) => Extend<T, string, string>;
+}

package/dist/object.library.js

@@ -0,0 +1,94 @@
+import { ownKeys, ownEntries } from './reflection.library.js';
+import { isObject, isArray, isReference, isFunction, isDefined, isEmpty, isNullish } from './type.library.js';
+/** Get nested value */
+export function extract(obj, path, dflt) {
+    if (isEmpty(path))
+        return obj; // finished searching
+    if (!isObject(obj) && !isArray(obj))
+        return obj;
+    return path
+        .toString()
+        .replace(/\[([^\[\]]*)\]/g, '.$1.') // convert [indexes] to properties
+        .split('.')
+        .filter(field => !isEmpty(field)) // remove empty fields
+        .reduce((acc, field) => acc?.[field] ?? null, obj) ?? dflt;
+}
+/** remove quotes around property names */
+export const unQuoteObj = (obj) => {
+    return JSON.stringify(obj)
+        ?.replace(/"([^"]+)":/g, '$1: ')
+        ?.replace(/,/g, ', ');
+};
+/** copy enumerable properties to a new Object */
+export const asObject = (obj) => {
+    if (isNullish(obj) || !isObject(obj))
+        return obj;
+    const temp = isArray(obj) ? [] : {};
+    ownKeys(obj)
+        .forEach(key => temp[key] = asObject(obj[key]));
+    return temp;
+};
+/** deep-compare object values for equality */
+export const isEqual = (obj1 = {}, obj2 = {}) => {
+    const keys = new Set(); // union of unique keys from both Objects
+    const keys1 = isFunction(obj1.keys) ? Array.from(obj1.keys()) : ownKeys(obj1);
+    const keys2 = isFunction(obj2.keys) ? Array.from(obj2.keys()) : ownKeys(obj2);
+    keys1.forEach(key => keys.add(key));
+    keys2.forEach(key => keys.add(key));
+    return [...keys] // cast as Array
+        .every(key => {
+        const val1 = obj1[key];
+        const val2 = obj2[key];
+        return isReference(val1) && isReference(val2)
+            ? isEqual(val1, val2) // recurse into object
+            : val1 === val2;
+    });
+};
+/** find all methods on an Object */
+export const getMethods = (obj, all = false) => {
+    const properties = new Set();
+    let currentObj = obj;
+    do {
+        Object
+            .getOwnPropertyNames(currentObj)
+            .map(key => properties.add(key));
+    } while (all && (currentObj = Object.getPrototypeOf(currentObj)));
+    return [...properties.keys()]
+        .filter(key => isFunction(obj[key]));
+};
+/** extract only defined values from Object */
+export function ifDefined(obj) {
+    return ownEntries(obj)
+        .reduce((acc, [key, val]) => {
+        if (isDefined(val))
+            acc[key] = val;
+        return acc;
+    }, {});
+}
+/** extract a subset of keys from an object */
+export const pick = (obj, ...keys) => {
+    const ownKeys = Object.getOwnPropertyNames(obj);
+    return keys.reduce((acc, key) => {
+        if (ownKeys.includes(key))
+            acc[key] = obj[key];
+        return acc;
+    }, {});
+};
+/** extract a named key from an array of objects */
+export const pluck = (objs, key) => objs.map(obj => obj[key]);
+/** extend an object with the properties of another */
+export const extend = (obj, ...objs) => Object.assign(obj, ...objs);
+export const countProperties = (obj = {}) => ownKeys(obj).length;
+export function looseIndex(arg) {
+    if (isDefined(arg))
+        return isFunction(arg) ? arg() : arg;
+    return (obj) => isFunction(obj) ? obj() : obj;
+}
+/** loose object with symbols values */
+looseIndex.stringSymbol = looseIndex();
+/** loose object with symbol keys and RegExp values */
+looseIndex.symbolRegExp = looseIndex();
+/** loose object with symbol keys and string values */
+looseIndex.symbolString = looseIndex();
+/** loose object with string keys and string values */
+looseIndex.stringString = looseIndex();

package/dist/pledge.class.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Wrap a Promise's resolve/reject/finally methods for later fulfilment.
+ * with useful methods for tracking the state of the Promise, chaining fulfilment, etc.
+ ```
+     new Pledge<T>({tag: string, onResolve?: () => void, onReject?: () => void, onSettle?: () => void})
+     new Pledge<T>(tag?: string)
+ ```
+ */
+export declare class Pledge<T> {
+    #private;
+    static STATE: import("./type.library.js").SecureObject<{
+        readonly Pending: symbol;
+        readonly Resolved: symbol;
+        readonly Rejected: symbol;
+    }>;
+    /** initialize future Pledge instances */
+    static init(arg?: Pledge.Constructor | string): Pledge.Status<typeof Pledge>;
+    static get status(): Pledge.Status<typeof Pledge>;
+    constructor(arg?: Pledge.Constructor | string);
+    get [Symbol.toStringTag](): string;
+    [Symbol.dispose](): void;
+    get status(): Pledge.Status<T>;
+    get promise(): Promise<T>;
+    get state(): string | undefined;
+    get isPending(): boolean;
+    get isResolved(): boolean;
+    get isRejected(): boolean;
+    get isSettled(): boolean;
+    toString(): string;
+    resolve(value: T): Promise<T>;
+    reject(error: any): Promise<T>;
+    then(fn: Function): void;
+}
+export declare namespace Pledge {
+    type Resolve = (val?: any) => any;
+    type Reject = (err: Error) => any;
+    type Settle = () => void;
+    type Constructor = {
+        tag?: string;
+        onResolve?: Pledge.Resolve | Pledge.Resolve[];
+        onReject?: Pledge.Reject | Pledge.Reject[];
+        onSettle?: Pledge.Settle | Pledge.Settle[];
+        debug?: boolean | undefined;
+        catch?: boolean | undefined;
+    };
+    interface Status<T> {
+        tag?: string;
+        debug?: boolean | undefined;
+        catch?: boolean | undefined;
+        state: symbol;
+        settled?: T;
+        error?: Error;
+    }
+}

package/dist/pledge.class.js

@@ -0,0 +1,131 @@
+import { Logify } from './logify.class.js';
+import { asArray } from './array.library.js';
+import { sprintf } from './string.library.js';
+import { ifDefined } from './object.library.js';
+import { secure } from './utility.library.js';
+import { cleanify } from './serialize.library.js';
+import { Immutable } from './class.library.js';
+import { isEmpty, isObject } from './type.library.js';
+/**
+ * Wrap a Promise's resolve/reject/finally methods for later fulfilment.
+ * with useful methods for tracking the state of the Promise, chaining fulfilment, etc.
+ ```
+     new Pledge<T>({tag: string, onResolve?: () => void, onReject?: () => void, onSettle?: () => void})
+     new Pledge<T>(tag?: string)
+ ```
+ */
+@Immutable
+export class Pledge {
+    #pledge;
+    #status = {};
+    #dbg;
+    static #static = {};
+    static STATE = secure({
+        Pending: Symbol('pending'),
+        Resolved: Symbol('resolved'),
+        Rejected: Symbol('rejected')
+    });
+    /** initialize future Pledge instances */
+    static init(arg) {
+        if (isObject(arg)) {
+            if (isEmpty(arg))
+                Pledge.#static = {}; // reset static values
+            Object.assign(Pledge.#static, ifDefined({ tag: arg.tag, debug: arg.debug, catch: arg.catch, }), ifDefined({ onResolve: arg.onResolve, onReject: arg.onReject, onSettle: arg.onSettle, }));
+        }
+        else {
+            Object.assign(Pledge.#static, ifDefined({ tag: arg, }));
+        }
+        if (Pledge.#static.debug)
+            console.log('Pledge: ', Pledge.#static); // debug
+        return Pledge.status;
+    }
+    static get status() {
+        return Pledge.#static;
+    }
+    /** use catch:boolean to determine whether to throw or return  */
+    #catch(...msg) {
+        if (this.status.catch) {
+            this.#dbg.warn(...msg); // catch, but warn {error}
+            return;
+        }
+        this.#dbg.error(...msg); // assume {error}
+        throw new Error(sprintf('pledge: ', ...msg));
+    }
+    constructor(arg) {
+        this.#pledge = Promise.withResolvers();
+        this.#status = { state: Pledge.STATE.Pending, ...Pledge.#static };
+        if (isObject(arg)) {
+            this.#dbg = new Logify({ debug: arg.debug, catch: arg.catch });
+            Object.assign(this.#status, ifDefined({ tag: Pledge.#static.tag, debug: Pledge.#static.debug, catch: Pledge.#static.catch }), ifDefined({ tag: arg.tag, debug: arg.debug, catch: arg.catch, }));
+            asArray(Pledge.#static.onResolve) // stack any static onResolve actions
+                .concat(asArray(arg.onResolve)) // stack any instance onResolve actions
+                .forEach(resolve => this.#pledge.promise.then(resolve));
+            asArray(Pledge.#static.onReject) // stack any static onReject actions
+                .concat(asArray(arg.onReject)) // stack any instance onReject actions
+                .forEach(reject => this.#pledge.promise.catch(reject));
+            asArray(Pledge.#static.onSettle) // stack any static onSettle actions
+                .concat(asArray(arg.onSettle)) // stack any instance onSettle actions
+                .forEach(settle => this.#pledge.promise.finally(settle));
+            if (this.#status.catch) // stack a 'catch-all'
+                this.#pledge.promise.catch(_ => this.#catch(this.#status, this.#status.error));
+        }
+        else {
+            this.#dbg = new Logify();
+            Object.assign(this.#status, ifDefined({ tag: arg ?? Pledge.#static.tag, }));
+        }
+        Object.freeze(this); // make this instance immutable
+    }
+    get [Symbol.toStringTag]() {
+        return 'Pledge';
+    }
+    [Symbol.dispose]() {
+        if (this.isPending)
+            this.reject(new Error(`Pledge disposed`)); // discard pending Pledge (to notify wait-ers)
+    }
+    get status() {
+        return cleanify(this.#status);
+    }
+    get promise() {
+        return this.#pledge.promise;
+    }
+    get state() {
+        return this.#status.state.description;
+    }
+    get isPending() {
+        return this.#status.state === Pledge.STATE.Pending;
+    }
+    get isResolved() {
+        return this.#status.state === Pledge.STATE.Resolved;
+    }
+    get isRejected() {
+        return this.#status.state === Pledge.STATE.Rejected;
+    }
+    get isSettled() {
+        return this.#status.state !== Pledge.STATE.Pending;
+    }
+    toString() {
+        return JSON.stringify(this.status);
+    }
+    resolve(value) {
+        if (this.isPending) {
+            this.#status.settled = value;
+            this.#status.state = Pledge.STATE.Resolved;
+            this.#pledge.resolve(value); // resolve, then trigger any Pledge.onResolve, then Pledge.onSettle
+        }
+        else
+            this.#dbg.warn(this.#status, `Pledge was already ${this.state}`);
+        return this.#pledge.promise;
+    }
+    reject(error) {
+        if (this.isPending) {
+            this.#status.error = error;
+            this.#status.state = Pledge.STATE.Rejected;
+            this.#pledge.reject(error); // reject, then trigger any Pledge.onReject, then Pledge.onSettle
+        }
+        else
+            this.#dbg.warn(this.#status, `Pledge was already ${this.state}`);
+        return this.#pledge.promise;
+    }
+    then(fn) {
+    }
+}