@magmacomputing/tempo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magma Computing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# <img src="./img/hourglass-svgrepo-com.svg" width="100px"> <span style="font-size:4em;">Tempo</span>
+
+**Tempo** is a premium, high-performance wrapper around the JavaScript `Temporal` API, providing a fluent and intuitive interface for date-time manipulation and flexible parsing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Temporal](https://img.shields.io/badge/Temporal-Stage%203-blue)](https://tc39.es/proposal-temporal/)
+
+## 🚀 Overview
+
+Working with dates in JavaScript has historically been painful. The new `Temporal` proposal (Stage 3) fixes this, but it can be verbose and strict when parsing strings. 
+
+**Tempo** bridges that gap by providing:
+- **Flexible Parsing**: Interprets almost any date string, including relative ones like "next Friday".
+- **Fluent API**: Chainable methods for adding, subtracting, and setting date-times.
+- **Built-in Plugins**: Access complex date ranges (Quarters, Seasons, Fiscal Years) easily.
+- **Immutable**: Every operation returns a new `Tempo` instance, ensuring thread safety and predictability.
+
+## 📦 Installation
+
+```bash
+npm install @magmacomputing/tempo
+```
+
+## 🛠️ Quick Start
+
+```javascript
+import { Tempo } from '@magmacomputing/tempo';
+
+// Instantiate 
+const now = new Tempo(); 
+const birthday = new Tempo('20-May-1990');
+const nextWeek = new Tempo('next Monday');
+
+// Manipulate
+const later = now.add({ days: 3, hours: 2 });
+const startOfMonth = now.set({ start: 'month' });
+
+// Format
+console.log(now.format('{dd} {mmm} {yyyy}')); // using custom format with tokens: "24 Jan 2026"
+console.log(now.fmt.date);                    // using pre-built formats: "2026-01-24"
+```
+
+## 📚 Documentation
+
+For detailed technical guides, please refer to:
+- [Tempo Class Documentation](./doc/Tempo.md)
+- [Parsing Engine](./doc/Tempo.md#parsing)
+- [Formatting Specs](./doc/Tempo.md#formatting)
+- [Plugin System (Terms)](./doc/Tempo.md#plugins-terms)
+
+## 💬 Contact & Support
+
+If you have a question, find a bug, or want to suggest a new feature:
+
+1. **Bug Reports & Features**: Please open an [Issue](https://github.com/magmacomputing/tempo/issues).
+2. **Questions & Ideas**: Start a thread in [Discussions](https://github.com/magmacomputing/tempo/discussions).
+3. **Direct Contact**: You can reach me at `hello@magmacomputing.com`.
+
+## ⚖️ License
+
+Distributed under the MIT License. See `LICENSE` for more information.

package/dist/array.library.d.ts

@@ -0,0 +1,25 @@
+import type { Property } from './type.library.js';
+/** Coerce {value} into {value[]} ( if not already ), with optional {fill} Object */
+export { asArray } from './coercion.library.js';
+/** insert a value into an Array by its sorted position */
+export declare const sortInsert: <T, K extends keyof T>(arr: T[] | undefined, val: T, key?: K) => T[];
+/** sort Array-of-Objects by multiple keys */
+export interface SortBy {
+    field: string;
+    dir?: 'asc' | 'desc';
+    index?: number | '*';
+    default?: any;
+}
+/** provide a sort-function to order a set of keys */
+export declare function sortBy<T extends Property<T>>(...keys: (PropertyKey | SortBy)[]): (left: T, right: T) => 0 | 1 | -1;
+/** return an array sorted-by a series of keys */
+export declare function sortKey<T extends Property<any>>(array: T[], ...keys: (PropertyKey | SortBy)[]): T[];
+type GroupFn<T extends Property<T>> = (value: T, index?: number) => PropertyKey;
+/** group array of objects by the return value of the passed callback. */
+export declare function byKey<T extends Property<any>>(arr: T[], grpFn: GroupFn<T>): Record<PropertyKey, T[]>;
+/** group array of objects according to a list of key fields. */
+export declare function byKey<T extends Property<any>>(arr: T[], ...keys: (keyof T)[]): Record<PropertyKey, T[]>;
+/** group array of objects by the return value of the passed callback, but only the 'last' entry */
+export declare function byLkp<T extends Property<any>>(arr: T[], grpFn: GroupFn<T>): Record<PropertyKey, T>;
+/**  group array of objects according to a list of key fields, but only the 'last' entry */
+export declare function byLkp<T extends Property<any>>(arr: T[], ...keys: (keyof T)[]): Record<keyof T, T>;

package/dist/array.library.js

@@ -0,0 +1,78 @@
+import { asString } from './coercion.library.js';
+import { extract } from './object.library.js';
+import { ownEntries } from './reflection.library.js';
+import { stringify } from './serialize.library.js';
+import { isNumber, isDate, isTempo, isObject, isDefined, isUndefined, isFunction, nullToValue } from './type.library.js';
+/** Coerce {value} into {value[]} ( if not already ), with optional {fill} Object */
+export { asArray } from './coercion.library.js';
+// adapted from https://jsbin.com/insert/4/edit?js,output
+/** insert a value into an Array by its sorted position */
+export const sortInsert = (arr = [], val, key) => {
+    const obj = isObject(val) && isDefined(key); // array of Objects
+    let low = 0, high = arr.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1; // divide by 2
+        const source = obj
+            ? arr[mid][key] // array of Object values
+            : arr[mid]; // assume Primitive values
+        const target = obj
+            ? val[key]
+            : val;
+        if (source < target)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    arr.splice(low, 0, val); // mutate original Array
+    return arr;
+};
+/** provide a sort-function to order a set of keys */
+export function sortBy(...keys) {
+    const sortOptions = keys // coerce string => SortBy
+        .flat() // flatten Array-of-Array
+        .map(key => isObject(key) ? key : { field: stringify(key) }); // build Array of sort-options
+    return (left, right) => {
+        let result = 0; // 0 = same, -1 = left<right, +1 = left>right
+        sortOptions.forEach(key => {
+            if (result === 0) { // no need to look further if result !== 0
+                const dir = key.dir === 'desc' ? -1 : 1;
+                const field = key.field + (key.index ? `[${key.index}]` : '');
+                const valueA = extract(left, field, nullToValue(key.default, 0));
+                const valueB = extract(right, field, nullToValue(key.default, 0));
+                switch (true) {
+                    case isNumber(valueA) && isNumber(valueB):
+                    case isDate(valueA) && isDate(valueB):
+                    case isTempo(valueA) && isTempo(valueB):
+                        result = dir * (valueA - valueB);
+                        break;
+                    default:
+                        result = dir * asString(valueA)?.localeCompare(asString(valueB));
+                        break;
+                }
+            }
+        });
+        return result;
+    };
+}
+/** return an array sorted-by a series of keys */
+export function sortKey(array, ...keys) {
+    return array.sort(sortBy(...keys));
+}
+export function byKey(arr, fnKey, ...keys) {
+    if (isFunction(fnKey))
+        return Object.groupBy(arr, fnKey);
+    const keyed = [fnKey] // mapFn is a keyof T
+        .concat(keys) // append any trailing keyof T[]
+        .flat(); // flatten Array-of-Array
+    return Object.groupBy(arr, itm => // group an array into an object with named keys
+     keyed
+        .map(key => isUndefined(itm[key]) ? '' : stringify(itm[key]))
+        .join('.'));
+}
+export function byLkp(arr, fnKey, ...keys) {
+    const group = isFunction(fnKey)
+        ? byKey(arr, fnKey) // group by the callback function
+        : byKey(arr, fnKey, ...keys); // group by the list of keys
+    return ownEntries(group)
+        .reduce((acc, [key, grp]) => Object.assign(acc, { [key]: grp?.pop() }), {});
+}

package/dist/buffer.library.d.ts

@@ -0,0 +1,6 @@
+export declare function b64ToUint6(nChr: number): number;
+export declare function base64DecToArr(sBase64: string, nBlocksSize?: number): Uint8Array<ArrayBuffer>;
+export declare function uint6ToB64(nUint6: number): number;
+export declare function base64EncArr(aBytes: Uint8Array): string;
+export declare function UTF8ArrToStr(aBytes: Uint8Array): string;
+export declare function strToUTF8Arr(sDOMStr: string): Uint8Array<ArrayBuffer>;

package/dist/buffer.library.js

@@ -0,0 +1,192 @@
+"use strict";
+// https://developer.mozilla.org/en-US/docs/Glossary/Base64
+// Array of bytes to Base64 string decoding
+export function b64ToUint6(nChr) {
+    return nChr > 64 && nChr < 91
+        ? nChr - 65
+        : nChr > 96 && nChr < 123
+            ? nChr - 71
+            : nChr > 47 && nChr < 58
+                ? nChr + 4
+                : nChr === 43
+                    ? 62
+                    : nChr === 47
+                        ? 63
+                        : 0;
+}
+export function base64DecToArr(sBase64, nBlocksSize) {
+    const sB64Enc = sBase64.replace(/[^A-Za-z0-9+/]/g, "");
+    const nInLen = sB64Enc.length;
+    const nOutLen = nBlocksSize
+        ? Math.ceil(((nInLen * 3 + 1) >> 2) / nBlocksSize) * nBlocksSize
+        : (nInLen * 3 + 1) >> 2;
+    const taBytes = new Uint8Array(nOutLen);
+    let nMod3;
+    let nMod4;
+    let nUint24 = 0;
+    let nOutIdx = 0;
+    for (let nInIdx = 0; nInIdx < nInLen; nInIdx++) {
+        nMod4 = nInIdx & 3;
+        nUint24 |= b64ToUint6(sB64Enc.charCodeAt(nInIdx)) << (6 * (3 - nMod4));
+        if (nMod4 === 3 || nInLen - nInIdx === 1) {
+            nMod3 = 0;
+            while (nMod3 < 3 && nOutIdx < nOutLen) {
+                taBytes[nOutIdx] = (nUint24 >>> ((16 >>> nMod3) & 24)) & 255;
+                nMod3++;
+                nOutIdx++;
+            }
+            nUint24 = 0;
+        }
+    }
+    return taBytes;
+}
+/* Base64 string to array encoding */
+export function uint6ToB64(nUint6) {
+    return nUint6 < 26
+        ? nUint6 + 65
+        : nUint6 < 52
+            ? nUint6 + 71
+            : nUint6 < 62
+                ? nUint6 - 4
+                : nUint6 === 62
+                    ? 43
+                    : nUint6 === 63
+                        ? 47
+                        : 65;
+}
+export function base64EncArr(aBytes) {
+    let nMod3 = 2;
+    let sB64Enc = "";
+    const nLen = aBytes.length;
+    let nUint24 = 0;
+    for (let nIdx = 0; nIdx < nLen; nIdx++) {
+        nMod3 = nIdx % 3;
+        if (nIdx > 0 && ((nIdx * 4) / 3) % 76 === 0) {
+            sB64Enc += "\r\n";
+        }
+        nUint24 |= aBytes[nIdx] << ((16 >>> nMod3) & 24);
+        if (nMod3 === 2 || aBytes.length - nIdx === 1) {
+            sB64Enc += String.fromCodePoint(uint6ToB64((nUint24 >>> 18) & 63), uint6ToB64((nUint24 >>> 12) & 63), uint6ToB64((nUint24 >>> 6) & 63), uint6ToB64(nUint24 & 63));
+            nUint24 = 0;
+        }
+    }
+    return (sB64Enc.substring(0, sB64Enc.length - 2 + nMod3) +
+        (nMod3 === 2 ? "" : nMod3 === 1 ? "=" : "=="));
+}
+/* UTF-8 array to JS string and vice versa */
+export function UTF8ArrToStr(aBytes) {
+    let sView = "";
+    let nPart;
+    const nLen = aBytes.length;
+    for (let nIdx = 0; nIdx < nLen; nIdx++) {
+        nPart = aBytes[nIdx];
+        sView += String.fromCodePoint(nPart > 251 && nPart < 254 && nIdx + 5 < nLen /* six bytes */
+            ? /* (nPart - 252 << 30) may be not so safe in ECMAScript! So…: */
+                (nPart - 252) * 1073741824 +
+                    ((aBytes[++nIdx] - 128) << 24) +
+                    ((aBytes[++nIdx] - 128) << 18) +
+                    ((aBytes[++nIdx] - 128) << 12) +
+                    ((aBytes[++nIdx] - 128) << 6) +
+                    aBytes[++nIdx] -
+                    128
+            : nPart > 247 && nPart < 252 && nIdx + 4 < nLen /* five bytes */
+                ? ((nPart - 248) << 24) +
+                    ((aBytes[++nIdx] - 128) << 18) +
+                    ((aBytes[++nIdx] - 128) << 12) +
+                    ((aBytes[++nIdx] - 128) << 6) +
+                    aBytes[++nIdx] -
+                    128
+                : nPart > 239 && nPart < 248 && nIdx + 3 < nLen /* four bytes */
+                    ? ((nPart - 240) << 18) +
+                        ((aBytes[++nIdx] - 128) << 12) +
+                        ((aBytes[++nIdx] - 128) << 6) +
+                        aBytes[++nIdx] -
+                        128
+                    : nPart > 223 && nPart < 240 && nIdx + 2 < nLen /* three bytes */
+                        ? ((nPart - 224) << 12) +
+                            ((aBytes[++nIdx] - 128) << 6) +
+                            aBytes[++nIdx] -
+                            128
+                        : nPart > 191 && nPart < 224 && nIdx + 1 < nLen /* two bytes */
+                            ? ((nPart - 192) << 6) + aBytes[++nIdx] - 128
+                            : /* nPart < 127 ? */ /* one byte */
+                                nPart);
+    }
+    return sView;
+}
+export function strToUTF8Arr(sDOMStr) {
+    let aBytes;
+    let nChr;
+    const nStrLen = sDOMStr.length;
+    let nArrLen = 0;
+    /* mapping… */
+    for (let nMapIdx = 0; nMapIdx < nStrLen; nMapIdx++) {
+        nChr = sDOMStr.codePointAt(nMapIdx);
+        if (nChr > 65536) {
+            nMapIdx++;
+        }
+        nArrLen +=
+            nChr < 0x80
+                ? 1
+                : nChr < 0x800
+                    ? 2
+                    : nChr < 0x10000
+                        ? 3
+                        : nChr < 0x200000
+                            ? 4
+                            : nChr < 0x4000000
+                                ? 5
+                                : 6;
+    }
+    aBytes = new Uint8Array(nArrLen);
+    /* transcription… */
+    let nIdx = 0;
+    let nChrIdx = 0;
+    while (nIdx < nArrLen) {
+        nChr = sDOMStr.codePointAt(nChrIdx);
+        if (nChr < 128) {
+            /* one byte */
+            aBytes[nIdx++] = nChr;
+        }
+        else if (nChr < 0x800) {
+            /* two bytes */
+            aBytes[nIdx++] = 192 + (nChr >>> 6);
+            aBytes[nIdx++] = 128 + (nChr & 63);
+        }
+        else if (nChr < 0x10000) {
+            /* three bytes */
+            aBytes[nIdx++] = 224 + (nChr >>> 12);
+            aBytes[nIdx++] = 128 + ((nChr >>> 6) & 63);
+            aBytes[nIdx++] = 128 + (nChr & 63);
+        }
+        else if (nChr < 0x200000) {
+            /* four bytes */
+            aBytes[nIdx++] = 240 + (nChr >>> 18);
+            aBytes[nIdx++] = 128 + ((nChr >>> 12) & 63);
+            aBytes[nIdx++] = 128 + ((nChr >>> 6) & 63);
+            aBytes[nIdx++] = 128 + (nChr & 63);
+            nChrIdx++;
+        }
+        else if (nChr < 0x4000000) {
+            /* five bytes */
+            aBytes[nIdx++] = 248 + (nChr >>> 24);
+            aBytes[nIdx++] = 128 + ((nChr >>> 18) & 63);
+            aBytes[nIdx++] = 128 + ((nChr >>> 12) & 63);
+            aBytes[nIdx++] = 128 + ((nChr >>> 6) & 63);
+            aBytes[nIdx++] = 128 + (nChr & 63);
+            nChrIdx++;
+        } /* if (nChr <= 0x7fffffff) */
+        else {
+            /* six bytes */
+            aBytes[nIdx++] = 252 + (nChr >>> 30);
+            aBytes[nIdx++] = 128 + ((nChr >>> 24) & 63);
+            aBytes[nIdx++] = 128 + ((nChr >>> 18) & 63);
+            aBytes[nIdx++] = 128 + ((nChr >>> 12) & 63);
+            aBytes[nIdx++] = 128 + ((nChr >>> 6) & 63);
+            aBytes[nIdx++] = 128 + (nChr & 63);
+            nChrIdx++;
+        }
+        nChrIdx++;
+    }
+    return aBytes;
+}

package/dist/cipher.class.d.ts

@@ -0,0 +1,18 @@
+/** Static-only cryptographic methods */
+export declare class Cipher {
+    #private;
+    /** random UUID */
+    static randomKey: () => string;
+    /** decode base64 back into object */
+    static decodeBase64: <T>(buf?: string) => T;
+    /** encode object into base64 */
+    static encodeBase64: (buf: unknown) => string;
+    static hmac: (source: string | Object, secret: string, alg?: string, len?: number) => Promise<string>;
+    static hash: (source: string | Object, len?: number, alg?: string) => Promise<string>;
+    static encodeBuffer: (str: string) => Uint16Array<ArrayBuffer>;
+    static decodeBuffer: (buf: Uint16Array) => string;
+    static encrypt: (data: any) => Promise<string>;
+    static decrypt: (secret: Promise<ArrayBuffer>) => Promise<string>;
+    static sign: (doc: any) => Promise<string>;
+    static verify: (signature: Promise<ArrayBuffer>, doc: any) => Promise<boolean>;
+}

package/dist/cipher.class.js

@@ -0,0 +1,65 @@
+import { toHex } from './number.library.js';
+import { asString } from './string.library.js';
+import { Immutable, Static } from './class.library.js';
+import { stringify, objectify } from './serialize.library.js';
+import { base64DecToArr, base64EncArr, strToUTF8Arr, UTF8ArrToStr } from './buffer.library.js';
+const crypto = globalThis.crypto;
+const subtle = crypto.subtle;
+const keys = {
+    Algorithm: 'SHA-256',
+    Encoding: 'utf-8',
+    SignKey: 'RSASSA-PKCS1-v1_5',
+    TypeKey: 'AES-GCM',
+};
+/** Static-only cryptographic methods */
+@Immutable
+@Static // prevent instantiation
+export class Cipher {
+    static #cryptoKey = subtle.generateKey({ name: keys.TypeKey, length: 128 }, false, ['encrypt', 'decrypt']);
+    static #vector = crypto.getRandomValues(new Uint8Array(16));
+    static #asymmetricKey = subtle.generateKey({
+        name: keys.SignKey,
+        modulusLength: 2048,
+        publicExponent: new Uint8Array([1, 0, 1]),
+        hash: { name: keys.Algorithm },
+    }, false, ['sign', 'verify']);
+    /** random UUID */
+    static randomKey = () => crypto.randomUUID().split('-')[0];
+    /** decode base64 back into object */
+    static decodeBase64 = (buf = '') => {
+        const uint8 = base64DecToArr(buf); // first, convert to UInt8Array
+        const str = UTF8ArrToStr(uint8); // convert to string
+        return objectify(str); // rebuild the original object
+    };
+    /** encode object into base64 */
+    static encodeBase64 = (buf) => {
+        const str = stringify(buf); // first, stringify the incoming buffer
+        const uint8 = strToUTF8Arr(str); // convert to Uint8Array
+        return base64EncArr(uint8); // convert to string
+    };
+    static hmac = async (source, secret, alg = 'SHA-512', len) => {
+        const encoder = new TextEncoder();
+        const keyData = encoder.encode(secret);
+        const messageData = encoder.encode(asString(source));
+        const key = await subtle.importKey('raw', keyData, { name: 'HMAC', hash: { name: alg } }, false, ['sign']);
+        const signature = await subtle.sign('HMAC', key, messageData);
+        return toHex(Array.from(new Uint8Array(signature)), len);
+    };
+    static hash = async (source, len, alg = 'SHA-256') => {
+        const buffer = Cipher.encodeBuffer(asString(source));
+        const hash = await subtle.digest(alg, buffer);
+        return toHex(Array.from(new Uint8Array(hash)), len);
+    };
+    static encodeBuffer = (str) => new Uint16Array(new TextEncoder().encode(str));
+    static decodeBuffer = (buf) => new TextDecoder(keys.Encoding).decode(buf);
+    static encrypt = async (data) => subtle.encrypt({ name: keys.TypeKey, iv: Cipher.#vector }, await Cipher.#cryptoKey, Cipher.encodeBuffer(data))
+        .then(result => new Uint16Array(result))
+        .then(Cipher.decodeBuffer);
+    static decrypt = async (secret) => subtle.decrypt({ name: keys.TypeKey, iv: Cipher.#vector }, await Cipher.#cryptoKey, await secret)
+        .then(result => new Uint16Array(result))
+        .then(Cipher.decodeBuffer);
+    static sign = async (doc) => subtle.sign(keys.SignKey, (await Cipher.#asymmetricKey).privateKey, Cipher.encodeBuffer(doc))
+        .then(result => new Uint16Array(result))
+        .then(Cipher.decodeBuffer);
+    static verify = async (signature, doc) => subtle.verify(keys.SignKey, (await Cipher.#asymmetricKey).publicKey, await signature, Cipher.encodeBuffer(doc));
+}

package/dist/class.library.d.ts

@@ -0,0 +1,10 @@
+import type { Constructor } from './type.library.js';
+/**
+ * Some interesting Class Decorators
+ */
+/** decorator to freeze a Class to prevent modification */
+export declare function Immutable<T extends Constructor>(value: T, { kind, name, addInitializer }: ClassDecoratorContext<T>): T | void;
+/** register a Class for serialization */
+export declare function Serializable<T extends Constructor>(value: T, { kind, name, addInitializer }: ClassDecoratorContext<T>): T | void;
+/** make a Class not instantiable */
+export declare function Static<T extends Constructor>(value: T, { kind, name }: ClassDecoratorContext<T>): T | void;

package/dist/class.library.js

@@ -0,0 +1,57 @@
+import { Registry } from './serialize.library.js';
+/**
+ * Some interesting Class Decorators
+ */
+/** decorator to freeze a Class to prevent modification */
+export function Immutable(value, { kind, name, addInitializer }) {
+    name = String(name);
+    switch (kind) {
+        case 'class':
+            const wrapper = {
+                [name]: class extends value {
+                    constructor(...args) {
+                        super(...args);
+                        Object.freeze(this); // freeze the instance
+                    }
+                }
+            }[name];
+            addInitializer(() => {
+                Object.freeze(value); // freeze the static properties
+                Object.freeze(value.prototype); // freeze the prototype methods
+                Object.freeze(wrapper); // freeze the wrapper static properties
+                Object.freeze(wrapper.prototype); // freeze the wrapper prototype methods
+            });
+            return wrapper;
+        default:
+            throw new Error(`@Immutable decorating unknown 'kind': ${kind} (${name})`);
+    }
+}
+/** register a Class for serialization */
+export function Serializable(value, { kind, name, addInitializer }) {
+    name = String(name); // cast as String
+    switch (kind) {
+        case 'class':
+            addInitializer(() => Registry.set(`$${name}`, value)); // register the class for serialization, via its toString() method
+            return value;
+        default:
+            throw new Error(`@Serializable decorating unknown 'kind': ${kind} (${name})`);
+    }
+}
+/** make a Class not instantiable */
+export function Static(value, { kind, name }) {
+    name = String(name);
+    switch (kind) {
+        case 'class':
+            const wrapper = {
+                [name]: class extends value {
+                    constructor(...args) {
+                        super(...args);
+                        throw new TypeError(`${name} is not a constructor`);
+                    }
+                }
+            }[name];
+            return wrapper;
+        default:
+            throw new Error(`@Static decorating unknown 'kind': ${kind} (${name})`);
+    }
+}

package/dist/coercion.library.d.ts

@@ -0,0 +1,14 @@
+/** Coerce {value} into {value[]} ( if not already ), with optional {fill} Object */
+export declare function asArray<T>(arr: Exclude<ArrayLike<T>, string> | undefined): T[];
+export declare function asArray<T>(arr: T | Exclude<Iterable<T> | undefined, string>): NonNullable<T>[];
+export declare function asArray<T, K>(arr: Iterable<T> | ArrayLike<T>, fill: K): K[];
+/** stringify if not nullish */
+export declare function asString<T>(str?: T): string;
+/** convert String | Number | BigInt to Number */
+export declare function asNumber(str?: string | number | bigint): number;
+/** convert String | Number to BigInt */
+export declare function asInteger<T extends string | number | bigint>(str?: T): bigint;
+/** test if can convert String to Numeric */
+export declare function isNumeric(str?: string | number | bigint): boolean;
+/** return as Number if possible, else original String */
+export declare const ifNumeric: (str: string | number | bigint, stripZero?: boolean) => string | number;

package/dist/coercion.library.js

@@ -0,0 +1,71 @@
+import { clone, stringify } from './serialize.library.js';
+import { isIntegerLike, isArrayLike, isDefined, isInteger, isIterable, isNullish, isString, isUndefined, asType, isNumber } from './type.library.js';
+export function asArray(arr = [], fill) {
+    switch (true) {
+        case isArrayLike(arr): // allow for {length:nn} objects
+        case isIterable(arr) && !isString(arr): // dont iterate Strings
+            return Array.from(arr, val => {
+                return isUndefined(fill) || isDefined(val)
+                    ? val // if no {fill}, then use {val}
+                    : clone(fill); // clone {fill} to create new Objects
+            });
+        default:
+            return Array.of(arr);
+    }
+}
+/** stringify if not nullish */
+export function asString(str) {
+    return isNullish(str)
+        ? ''
+        : isInteger(str)
+            ? str.toString() + 'n'
+            : stringify(str);
+}
+/** convert String | Number | BigInt to Number */
+export function asNumber(str) {
+    return parseFloat(str?.toString() ?? 'NaN');
+}
+/** convert String | Number to BigInt */
+export function asInteger(str) {
+    const arg = asType(str);
+    switch (arg.type) {
+        case 'BigInt':
+            return arg.value; // already a BigInt
+        case 'Number':
+            return BigInt(Math.trunc(arg.value)); // cast as BigInt
+        case 'String':
+            return (isIntegerLike(arg.value)) // String representation of a BigInt
+                ? BigInt(arg.value.slice(0, -1)) // get rid of trailing 'n'
+                : BigInt(arg.value);
+        default:
+            return str;
+    }
+}
+/** test if can convert String to Numeric */
+export function isNumeric(str) {
+    const arg = asType(str);
+    switch (arg.type) {
+        case 'Number':
+        case 'BigInt':
+            return true;
+        case 'String':
+            return isIntegerLike(arg.value)
+                ? true // is Number | BigInt
+                : !isNaN(asNumber(str)) && isFinite(str); // test if Number
+        default:
+            return false;
+    }
+}
+/** return as Number if possible, else original String */
+export const ifNumeric = (str, stripZero = false) => {
+    switch (true) {
+        case isInteger(str): // BigInt → Number
+            return Number(str);
+        case isNumber(str): // Number → as-is
+            return str;
+        case isNumeric(str) && (!str?.toString().startsWith('0') || stripZero):
+            return asNumber(str); // numeric String → Number
+        default:
+            return str; // non-numeric String → as-is
+    }
+};