@magmacomputing/tempo 1.0.0

package/dist/prototype.library.d.ts

@@ -0,0 +1,33 @@
+import { type SortBy } from './array.library.js';
+import type { Property } from './type.library.js';
+/**
+ * extend an Object's prototype to include new method, if no clash
+ */
+export declare const patch: <T extends Record<"prototype" | "name", any>>(proto: T, property: string, method: Function) => void;
+declare global {
+    interface String {
+        /** remove redundant spaces to a new string */ trimAll(pat?: RegExp): string;
+        /** upper-case first letter of a word */ toProperCase(): string;
+    }
+}
+type GroupFn<T extends Property<any>> = (value: T, index?: number) => PropertyKey;
+type SortFn<T> = (left: T, right: T) => -1 | 0 | 1;
+declare global {
+    interface Array<T> {
+        /** reduce Array to a keyed Object[] */ keyedBy(...keys: (keyof T)[]): Record<PropertyKey, T[]>;
+        /** reduce Array to a keyed Object[], mapped */ keyedBy<S extends Property<T>>(grpfn: GroupFn<S>): Record<PropertyKey, T[]>;
+        /** reduce Array to a keyed single-Object */ lookupBy(...keys: (keyof T)[]): Record<PropertyKey, T>;
+        /** reduce Array to a keyed single-Object, mapped */ lookupBy<S extends Property<T>>(grpfn: GroupFn<S>): Record<PropertyKey, T>;
+        /** return ordered Array */ orderBy(...keys: (PropertyKey | SortBy)[]): T[];
+        /** return ordered Array, mapped */ orderBy<V extends keyof T>(mapfn: SortFn<V>): V[];
+        /** return sorted Array */ sortBy(...keys: (PropertyKey | SortBy)[]): T[];
+        /** return ordered Array, mapped */ sortBy<V extends keyof T>(mapfn: SortFn<V>): V[];
+        /** return new Array with no repeated elements */ distinct(): T[];
+        /** return mapped Array with no repeated elements */ distinct<S>(mapfn: (value: T, index: number, array: T[]) => S, thisArg?: any): S[];
+        /** clear down an Array */ clear(): T[];
+        /** return cartesian-product of Array of Arrays */ cartesian(): T;
+        /** return cartesian-product of Array of Arrays */ cartesian(...args: T[][]): T[];
+        /** tap into an Array */ tap(tapfn: (value: T[]) => void, thisArg?: any): T[];
+    }
+}
+export {};

package/dist/prototype.library.js

@@ -0,0 +1,51 @@
+import { trimAll, toProperCase } from './string.library.js';
+import { asArray, byKey, byLkp, sortKey } from './array.library.js';
+// Prototype extensions
+// Remember to define any imports as a Function Declaration (not a Function Expression)
+// so that they are 'hoisted' prior to extending a prototype
+/**
+ * extend an Object's prototype to include new method, if no clash
+ */
+export const patch = (proto, property, method) => {
+    if (proto.prototype.hasOwnProperty(property)) { // if already defined,
+        if (trimAll(method.toString()) !== trimAll(proto.prototype?.[property]?.toString()))
+            console.warn(`${proto.name}.${property} already defined`); // show warning if different method definition
+    }
+    else {
+        Object.defineProperty(proto.prototype, property, {
+            configurable: false,
+            enumerable: false,
+            writable: false,
+            value: method,
+        });
+    }
+};
+patch(String, 'trimAll', function (pat) { return trimAll(this, pat); });
+patch(String, 'toProperCase', function () { return toProperCase(this); });
+function sorted(...keys) { return sortKey(this, ...keys); }
+patch(Array, 'orderBy', sorted); // order array by named keys
+patch(Array, 'sortBy', sorted); // sort array by named keys
+function keyed(...keys) { return byKey(this, ...keys); }
+function lookup(...keys) { return byLkp(this, ...keys); }
+patch(Array, 'keyedBy', keyed); // reduce array by named keys
+patch(Array, 'lookupBy', lookup); // reduce array by named keys, only one entry per key
+patch(Array, 'tap', function (fn) {
+    fn(this); // run an arbitrary function
+    return this; // then return the original array
+});
+patch(Array, 'clear', function () {
+    this.fill(null).length = 0; // wipe the contents, then set the 'length' to zero
+    return this;
+});
+patch(Array, 'distinct', function (mapfn) {
+    return mapfn
+        ? this.map(mapfn).distinct() // run the mapping selector, then recurse
+        : Array.from(new Set(this)); // eliminate duplicates
+});
+patch(Array, 'cartesian', function (...args) {
+    const [a, b = [], ...c] = args.length === 0 ? this : args;
+    const cartFn = (a, b) => asArray([]).concat(...a.map(d => b.map(e => asArray([]).concat(d, e))));
+    return b.length
+        ? this.cartesian(cartFn(a, b), ...c) // run the cartFn function, then recurse
+        : asArray(a || []); // return the collated result
+});

package/dist/reflection.library.d.ts

@@ -0,0 +1,74 @@
+import type { Obj, KeyOf, ValueOf, EntryOf, Primitives } from './type.library.js';
+/** mutate Object | Array by excluding values with specified primitive 'types' */
+export declare function exclude<T extends Obj>(obj: T, ...types: (Primitives | Lowercase<Primitives>)[]): T;
+/** mutate Object | Array reference with properties removed */
+export declare function omit<T extends Obj>(obj: T): T;
+export declare function omit<T extends Obj>(obj: T, ...keys: PropertyKey[]): T;
+/** remove all ownKeys from an Object | Array */
+export declare function purge<T extends Obj>(obj: T): T;
+/** reset Object */
+export declare function reset<T extends Obj>(orig: T, obj?: T): T & {
+    [x: number]: any;
+    length?: any;
+    toString?: (() => string) | (() => string);
+    toLocaleString?: {
+        (): string;
+        (locales: string | string[], options?: Intl.NumberFormatOptions & Intl.DateTimeFormatOptions): string;
+    } | (() => string);
+    pop?: any;
+    push?: any;
+    concat?: any;
+    join?: any;
+    reverse?: any;
+    shift?: any;
+    slice?: any;
+    sort?: any;
+    splice?: any;
+    unshift?: any;
+    indexOf?: any;
+    lastIndexOf?: any;
+    every?: any;
+    some?: any;
+    forEach?: any;
+    map?: any;
+    filter?: any;
+    reduce?: any;
+    reduceRight?: any;
+    find?: any;
+    findIndex?: any;
+    fill?: any;
+    copyWithin?: any;
+    entries?: any;
+    keys?: any;
+    values?: any;
+    includes?: any;
+    flatMap?: any;
+    flat?: any;
+    at?: any;
+    findLast?: any;
+    findLastIndex?: any;
+    toReversed?: any;
+    toSorted?: any;
+    toSpliced?: any;
+    with?: any;
+    keyedBy?: any;
+    lookupBy?: any;
+    orderBy?: any;
+    sortBy?: any;
+    distinct?: any;
+    clear?: any;
+    cartesian?: any;
+    tap?: any;
+};
+/** array of all enumerable PropertyKeys */
+export declare function ownKeys<T extends Obj>(json: T): KeyOf<T>[];
+/** array of all enumerable object values */
+export declare function ownValues<T extends Obj>(json: T): ValueOf<T>[];
+/** tuple of enumerable entries with string | symbol keys */
+export declare function ownEntries<T extends Obj>(json: T, all?: boolean): EntryOf<T>[];
+/** get a string-array of 'getter' names for an object */
+export declare const getAccessors: (obj?: any) => (string | number | symbol)[];
+/** get a string-array of 'setter' names for an object */
+export declare const setAccessors: (obj?: any) => (string | number | symbol)[];
+/** copy all Own properties (including getters / setters) to a new object */
+export declare const copyObject: <T extends Obj>(target: T, source: T) => T;

package/dist/reflection.library.js

@@ -0,0 +1,97 @@
+import { asType, getType, isEmpty, isFunction, isPrimitive } from './type.library.js';
+/** mutate Object | Array by excluding values with specified primitive 'types' */
+export function exclude(obj, ...types) {
+    const exclusions = types
+        .map(item => item.toLowerCase()) // cast Primitives as Lowercase<Primitives> to aid in matching
+        .distinct();
+    if (obj && typeof obj === 'object') { // only works on Objects and Arrays
+        const keys = [];
+        ownEntries(obj)
+            .forEach(([key, value]) => {
+            const type = getType(value);
+            if (['Object', 'Array'].includes(type)) // recurse into object
+                exclude(value, ...exclusions);
+            if (isPrimitive(value) && exclusions.includes(type.toLowerCase()))
+                keys.push(key);
+        });
+        if (!isEmpty(keys)) // if any values to be excluded
+            omit(obj, ...keys);
+    }
+    return obj; // return Object reference, even though Object has been mutated
+}
+export function omit(obj, ...keys) {
+    const { type, value } = asType(obj);
+    switch (type) {
+        case 'Array':
+            if (isEmpty(keys)) {
+                value.clear(); // clear entire Array
+                break;
+            }
+            keys
+                .sort()
+                .reverse() // remove from end-to-start to preserve indexes
+                .forEach(key => value.splice(Number(key), 1)); // remove Array index
+            break;
+        case 'Object':
+            (isEmpty(keys) ? ownKeys(value) : keys) // if no {keys}, assume all ownKeys
+                .forEach(key => Reflect.deleteProperty(value, key));
+    }
+    return value; // return Object reference, even though Object has been mutated
+}
+/** remove all ownKeys from an Object | Array */
+export function purge(obj) {
+    return omit(obj);
+}
+/** reset Object */
+export function reset(orig, obj) {
+    return Object.assign(purge(orig), { ...obj });
+}
+// These functions are to preserve the typescript 'type' of an object's keys & values
+// and will include both string and symbol keys
+/** array of all enumerable PropertyKeys */
+export function ownKeys(json) {
+    return ownEntries(json).map(([key]) => key);
+}
+/** array of all enumerable object values */
+export function ownValues(json) {
+    return ownEntries(json).map(([_, value]) => value);
+}
+/** tuple of enumerable entries with string | symbol keys */
+export function ownEntries(json, all = false) {
+    if (!json || typeof json !== 'object')
+        return [];
+    const entries = new Map();
+    const limit = all ? 10 : 1; // limit depth of 10 down the prototype chain to prevent infinite loops
+    let depth = 0;
+    let proto = json;
+    do {
+        Reflect
+            .ownKeys(proto)
+            .filter(key => !entries.has(key)) // filter out if already tracking this key
+            .forEach(key => {
+            const desc = Object.getOwnPropertyDescriptor(proto, key);
+            if (desc?.enumerable) // only track enumerable properties
+                entries.set(key, desc.value);
+        });
+        proto = Object.getPrototypeOf(proto);
+    } while (proto && proto !== Object.prototype && ++depth < limit);
+    return [...entries.entries()];
+}
+/** get a string-array of 'getter' names for an object */
+export const getAccessors = (obj = {}) => {
+    return ownAccessors(obj, 'get');
+};
+/** get a string-array of 'setter' names for an object */
+export const setAccessors = (obj = {}) => {
+    return ownAccessors(obj, 'set');
+};
+const ownAccessors = (obj = {}, type) => {
+    const accessors = Object.getOwnPropertyDescriptors(obj.prototype || Object.getPrototypeOf(obj));
+    return ownEntries(accessors)
+        .filter(([_, descriptor]) => isFunction(descriptor[type]))
+        .map(([key, _]) => key);
+};
+/** copy all Own properties (including getters / setters) to a new object */
+export const copyObject = (target, source) => {
+    return Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+};

package/dist/serialize.library.d.ts

@@ -0,0 +1,25 @@
+/** registry of registered classes */
+export declare const Registry: Map<string, Function>;
+/** make a deep-copy, using standard browser or JSON functions */
+export declare function clone<T>(obj: T, opts?: {
+    transfer: any[];
+}): T;
+/** return a copy. remove unsupported values (e.g. \<undefined>, function) */
+export declare function cleanify<T>(obj: T): T;
+/** deep-copy an Object, and optionally replace \<undefined> fields with a Sentinel function call	*/
+export declare function cloneify<T>(obj: T, sentinel?: Function): T;
+/**
+ * For items which are not currently serializable via standard JSON.stringify (Undefined, BigInt, Set, Map, Symbol, etc.)
+ * this creates a stringified, single key:value Object to represent the value; for example  '{ "$BigInt": 123 }'
+ *
+ * Drawbacks:
+ * no support Function / WeakMap / WeakSet / WeakRef
+ * limited support for user-defined Classes (must be specifically registered with @Serialize() decorator)
+ */
+/**
+ * serialize Objects for string-safe stashing in WebStorage, Cache, etc
+ * uses JSON.stringify where available, else returns stringified single key:value Object '{[$type]: value}'
+ */
+export declare function stringify<T>(obj: T): string;
+/** rebuild an Object from its stringified representation */
+export declare function objectify<T>(str: any, sentinel?: Function): T;

package/dist/serialize.library.js

@@ -0,0 +1,266 @@
+import { curry } from './function.library.js';
+import { ownKeys, ownValues, ownEntries } from './reflection.library.js';
+import { isType, asType, isEmpty, isDefined, isUndefined, isNullish, isString, isObject, isArray, isFunction, isSymbolFor, isSymbol } from './type.library.js';
+/** registry of registered classes */
+// DO NOT EDIT THIS VALUE: used by decorator.library.ts
+export const Registry = new Map();
+// be aware that 'structuredClone' preserves \<undefined> values...  
+// and JSON.stringify() does not
+/** make a deep-copy, using standard browser or JSON functions */
+export function clone(obj, opts) {
+    try {
+        return globalThis.structuredClone(obj, opts);
+    }
+    catch {
+        return cleanify(obj); // fallback to JSON functions
+    }
+}
+/** return a copy. remove unsupported values (e.g. \<undefined>, function) */
+export function cleanify(obj) {
+    try {
+        return JSON.parse(JSON.stringify(obj)); // run any toString() methods
+    }
+    catch (error) {
+        console.warn('Could not clean object: ', obj);
+        return { ...obj };
+    }
+}
+/** deep-copy an Object, and optionally replace \<undefined> fields with a Sentinel function call	*/
+export function cloneify(obj, sentinel) {
+    try {
+        return objectify(stringify(obj), sentinel);
+    }
+    catch (error) {
+        console.warn('Could not cloneify object: ', obj);
+        console.warn('stack: ', error.stack);
+        return obj;
+    }
+}
+function replacer(key, obj) { return isEmpty(key) ? obj : stringize(obj); }
+function reviver(_key, val) { return decode(val); }
+// safe-characters [sp " ; < > [ ] ^ { | }]
+const safeList = ['20', '22', '3B', '3C', '3E', '5B', '5D', '5E', '7B', '7C', '7D'];
+/** encode control characters, then replace a safe-subset back to text-string */
+function encode(val) {
+    let enc = encodeURI(val);
+    if (enc.includes('%')) { // if an encoded URI might be in string
+        safeList.forEach(code => {
+            const uri = '%' + code;
+            const reg = new RegExp(uri, 'g');
+            enc = enc.replace(reg, decodeURI(uri));
+        });
+    }
+    return enc;
+}
+/** decode control characters */
+function decode(val) {
+    if (isString(val)) {
+        try {
+            return decodeURI(val); // might fail if badly encoded '%'
+        }
+        catch (error) {
+            // console.warn(`decodeURI: ${(error as Error).message} -> ${val}`);
+        }
+    }
+    return val; // return original value
+}
+/** check type can be stringify'd */
+function isStringable(val) {
+    return !isType(val, 'Function', 'AsyncFunction', 'WeakMap', 'WeakSet', 'WeakRef');
+}
+/** string representation of a single key:value Object */
+function oneKey(type, value) {
+    return `{"$${type}":${value}}`;
+}
+/** Symbols in an Object-key will need special treatment */
+function fromSymbol(key) {
+    return stringize(isSymbol(key) // @@(name) for global, @(name) for local symbols
+        ? `${isSymbolFor(key) ? '@' : ''}@(${key.description ?? ''})`
+        : key);
+}
+const symKey = /^@(@)?\(([^\)]*)\)$/; // pattern to match a stringify'd Symbol
+/** reconstruct a Symbol from a string-representation of a key */
+function toSymbol(value) {
+    const [pat, keyFor, desc] = value.toString().match(symKey) || [null, void 0, void 0];
+    switch (true) {
+        case isSymbol(value): // already a Symbol
+        case isNullish(pat): // incorrectly encoded Symbol
+        case isDefined(keyFor) && isUndefined(desc): // incorrectly encoded global Symbol
+            return value;
+        case isDefined(keyFor): // global Symbol
+            return Symbol.for(desc);
+        case isUndefined(keyFor): // local Symbol
+        default:
+            return Symbol(desc);
+    }
+}
+/**
+ * For items which are not currently serializable via standard JSON.stringify (Undefined, BigInt, Set, Map, Symbol, etc.)
+ * this creates a stringified, single key:value Object to represent the value; for example  '{ "$BigInt": 123 }'
+ *
+ * Drawbacks:
+ * no support Function / WeakMap / WeakSet / WeakRef
+ * limited support for user-defined Classes (must be specifically registered with @Serialize() decorator)
+ */
+/**
+ * serialize Objects for string-safe stashing in WebStorage, Cache, etc
+ * uses JSON.stringify where available, else returns stringified single key:value Object '{[$type]: value}'
+ */
+export function stringify(obj) {
+    return stringize(obj, false);
+}
+/**
+ * internal function to process stringify-requests (and hide second parameter)
+ * where first argument is the object to stringify, and
+ * the second argument is a boolean to indicate if function is being called recursively
+ */
+function stringize(obj, recurse = true) {
+    const arg = asType(obj);
+    const one = curry(oneKey)(arg.type); // curry the oneKey() function
+    switch (arg.type) {
+        case 'String':
+            if (!recurse) { // if a top-level string (e.g. 'true' or '1234')
+                recurse = arg.value === 'true' // ensure true|false|null|1234 are quoted by JSON.stringify
+                    || arg.value === 'false' // so they will be correctly identified during objectify()
+                    || arg.value === 'null'
+                    || parseFloat(arg.value).toString() === arg.value;
+            }
+            return recurse
+                ? JSON.stringify(encode(arg.value)) // encode string for safe-storage
+                : encode(arg.value); // dont JSON.stringify a top-level string
+        case 'Boolean':
+        case 'Null':
+        case 'Number':
+            return JSON.stringify(arg.value); // JSON.stringify will correctly handle these
+        case 'Void':
+        case 'Undefined':
+            return one(JSON.stringify('void')); // preserve 'undefined' values		
+        case 'BigInt':
+            return one(arg.value.toString()); // even though BigInt has a toString method, it is not supported in JSON.stringify
+        case 'Object':
+            const obj = ownEntries(arg.value)
+                .filter(([, val]) => isStringable(val))
+                .map(([key, val]) => `${fromSymbol(key)}: ${stringize(val)}`)
+                .join(',');
+            return `{${obj}}`;
+        case 'Array':
+            const arr = arg.value
+                .filter(val => isStringable(val))
+                .map(val => stringize(val))
+                .join(',');
+            return `[${arr}]`;
+        case 'Map':
+            const map = Array.from(arg.value.entries())
+                .filter(([, val]) => isStringable(val))
+                .map(([key, val]) => `[${stringize(key)}, ${stringize(val)}]`)
+                .join(',');
+            return one(`[${map}]`);
+        case 'Set':
+            const set = Array.from(arg.value.values())
+                .filter(val => isStringable(val))
+                .map(val => stringize(val))
+                .join(',');
+            return one(`[${set}]`);
+        case 'Symbol':
+            return one(fromSymbol(arg.value));
+        case 'RegExp':
+            return one(stringize({ source: arg.value.source, flags: arg.value.flags }));
+        case 'Class':
+        default:
+            const value = arg.value;
+            switch (true) {
+                case !isStringable(value): // Object is not stringify-able
+                    return void 0;
+                case isFunction(value.toString): // Object has its own toString method
+                    const str = value.toString();
+                    return one(str.includes('"') // TODO: improve detection of JSON vs non-JSON strings
+                        ? str
+                        : JSON.stringify(str));
+                case isFunction(value.valueOf): // Object has its own valueOf method		
+                    return one(JSON.stringify(value.valueOf()));
+                case isFunction(value.toJSON): // Object has its own toJSON method
+                    return one(stringize(value.toJSON()));
+                default: // else standard stringify
+                    return one(JSON.stringify(value, replacer));
+            }
+    }
+}
+/** rebuild an Object from its stringified representation */
+export function objectify(str, sentinel) {
+    if (!isString(str))
+        return str; // skip parsing
+    let parse;
+    try {
+        parse = JSON.parse(str, reviver); // catch if cannot parse
+    }
+    catch (error) {
+        if (str.startsWith('"') && str.endsWith('"')) {
+            console.warn(`objectify.parse: -> ${str}, ${error.message}`);
+            return str; // bail-out
+        }
+        else
+            return objectify(`"${str}"`, sentinel); // have another try, quoted
+    }
+    switch (true) {
+        case str.startsWith('{') && str.endsWith('}'): // looks like Object
+        case str.startsWith('[') && str.endsWith(']'): // looks like Array
+            return traverse(parse, sentinel); // recurse into object
+        default:
+            return parse;
+    }
+}
+/** recurse into Object / Array, looking for special single key:value Objects */
+function traverse(obj, sentinel) {
+    if (isObject(obj)) {
+        return typeify(ownEntries(obj)
+            .reduce((acc, [key, val]) => Object.assign(acc, { [toSymbol(key)]: typeify(traverse(val, sentinel)) }), {}), sentinel);
+    }
+    if (isArray(obj)) {
+        return ownValues(obj)
+            .map(val => typeify(traverse(val, sentinel)));
+    }
+    return obj;
+}
+/** rebuild an Object from its single key:value representation */
+function typeify(json, sentinel) {
+    if (!isObject(json) || ownKeys(json).length !== 1)
+        return json; // only JSON Objects, with a single key:value pair
+    const [$type, value] = ownEntries(json)[0];
+    if (!String($type).startsWith('$'))
+        return json; // not a serialized single key:value Object
+    const type = $type.substring(1); // remove '$' prefix
+    switch (type) {
+        case 'String':
+        case 'Boolean':
+        case 'Object':
+        case 'Array':
+            return value; // these types are already handled by traverse()
+        case 'Number':
+            return Number(value);
+        case 'BigInt':
+            return BigInt(value);
+        case 'Null':
+            return null;
+        case 'Undefined':
+        case 'Empty':
+        case 'Void':
+            return sentinel?.(); // run Sentinel function to handle undefined values
+        case 'Date':
+            return new Date(value);
+        case 'RegExp':
+            return new RegExp(value.source, value.flags);
+        case 'Symbol':
+            return toSymbol(value);
+        case 'Map':
+            return new Map(value);
+        case 'Set':
+            return new Set(value);
+        default:
+            const cls = Registry.get($type); // lookup registered Class
+            if (!cls) {
+                console.warn(`objectify: dont know how to deserialize '${type}'`);
+                return json; // return original JSON object
+            }
+            return Reflect.construct(cls, [value]); // create new Class instance
+    }
+}

package/dist/storage.library.d.ts

@@ -0,0 +1,8 @@
+/** select local | session storage */
+export declare function selStorage(store?: 'local' | 'session'): Storage;
+/** get storage */
+export declare function getStorage<T>(): T;
+export declare function getStorage<T>(key: string): T | undefined;
+export declare function getStorage<T>(key: string | undefined, dflt?: T): T;
+/** set / delete storage */
+export declare function setStorage<T>(key: string, val?: T): void;

package/dist/storage.library.js

@@ -0,0 +1,57 @@
+import { objectify, stringify } from './serialize.library.js';
+import { CONTEXT, getContext } from './utility.library.js';
+import { isDefined, isUndefined, isString } from './type.library.js';
+const context = getContext();
+let storage = context.type === CONTEXT.Browser
+    ? context.global?.localStorage //as globalThis.Storage		// default to localStorage in a browser
+    : void 0;
+/** select local | session storage */
+export function selStorage(store = 'local') {
+    const name = (store + 'Storage');
+    return storage = globalThis[name]; // return whichever was selected.
+}
+export function getStorage(key, dflt) {
+    let store;
+    if (isUndefined(key))
+        return dflt ?? {};
+    switch (context.type) {
+        case CONTEXT.Browser:
+            store = storage.getItem(key);
+            break;
+        case CONTEXT.NodeJS:
+            store = context.global.process.env[key];
+            break;
+        case CONTEXT.GoogleAppsScript:
+            store = context.global.PropertiesService?.getUserProperties().getProperty(key);
+            break;
+        default:
+            throw new Error(`Cannot determine Javascript context: ${context.type}`);
+    }
+    return isString(store)
+        ? objectify(store) // rebuild object from its stringified representation
+        : dflt;
+}
+/** set / delete storage */
+export function setStorage(key, val) {
+    const stash = isDefined(val) ? stringify(val) : void 0;
+    const set = isDefined(stash);
+    switch (context.type) {
+        case CONTEXT.Browser:
+            set
+                ? storage.setItem(key, stash)
+                : storage.removeItem(key);
+            break;
+        case CONTEXT.NodeJS:
+            set
+                ? (context.global.process.env[key] = stash)
+                : (delete context.global.process.env[key]);
+            break;
+        case CONTEXT.GoogleAppsScript:
+            set
+                ? context.global.PropertiesService?.getUserProperties().setProperty(key, stash)
+                : context.global.PropertiesService?.getUserProperties().deleteProperty(key);
+            break;
+        default:
+            throw new Error(`Cannot determine Javascript context: ${context.type}`);
+    }
+}

package/dist/string.library.d.ts

@@ -0,0 +1,37 @@
+/**
+ * clean a string to remove some standard control-characters (tab, line-feed, carriage-return) and trim redundant spaces.
+ * allow for optional RegExp to specify additional match
+ */
+export declare function trimAll(str: string | number, pat?: RegExp): string;
+/** every word has its first letter capitalized */
+export declare function toProperCase<T extends string>(...str: T[]): T;
+export declare const toCamelCase: <T extends string>(sentence: T) => T;
+export declare const randomString: (len?: number) => string;
+/** use sprintf-style formatting on a string */
+export declare function sprintf(fmt: string, ...msg: any[]): string;
+export declare function sprintf(...msg: any[]): string;
+/** apply a plural suffix, if greater than '1' */
+export declare const plural: (val: string | number | Record<string, string>, word: string, plural?: string) => string | ((num: string, word: string) => string);
+/** strip a plural suffix, if endsWith 's' */
+export declare const singular: (val: string) => string;
+/** make an Object's values into a Template Literals, and evaluate */
+export declare const makeTemplate: (templateString: Object) => (templateData: Object) => any;
+/** stringify if not nullish */
+export { asString } from './coercion.library.js';
+export declare const toLower: <T>(str: T) => string | T;
+export declare const toUpper: <T>(str: T) => string | T;
+/** assert string is within bounds */
+type StrLen<Min, Max = Min> = string & {
+    __value__: never;
+};
+export declare const strlen: <Min extends number, Max extends number>(str: unknown, min: Min, max?: Max) => StrLen<Min, Max>;
+/**
+ * pad a string with leading character
+ * @param		nbr	input value to pad
+ * @param		len	fill-length (default: 2)
+ * @param		fill	character (default \<space> for string and \<zero> for number)
+ * @returns	fixed-length string padded on the left with fill-character
+ */
+export declare const pad: (nbr?: string | number | bigint, len?: number, fill?: string | number) => string;
+/** pad a string with non-blocking spaces, to help right-align a display */
+export declare const padString: (str: string | number | bigint, pad?: number) => string;