@magmacomputing/tempo 1.0.0

package/dist/string.library.js

@@ -0,0 +1,93 @@
+import { asNumber, asString, isNumeric } from './coercion.library.js';
+import { stringify } from './serialize.library.js';
+import { isString, isObject, assertCondition, assertString, nullToValue } from './type.library.js';
+// General <string> functions
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// This section needs to be Function declarations so that they are hoisted
+// (because they are referenced in prototype.library)
+/**
+ * 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 function trimAll(str, pat) {
+    return str
+        .toString() // coerce to String
+        .replace(pat, '') // remove regexp, if supplied
+        .replace(/\t/g, ' ') // replace <tab> with <space>
+        .replace(/(\r\n|\n|\r)/g, ' ') // replace <return> & <newline>
+        .replace(/\s{2,}/g, ' ') // trim multiple <space>
+        .trim(); // leading/trailing <space>
+}
+/** every word has its first letter capitalized */
+export function toProperCase(...str) {
+    return str
+        .flat() // in case {str} was already an array
+        .map(text => text.replace(/\w\S*/g, word => word.charAt(0).toUpperCase() + word.substring(1).toLowerCase()))
+        .join(' ');
+}
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+const PAT = /[A-Z\xC0-\xD6\xD8-\xDE]?[a-z\xDF-\xF6\xF8-\xFF]+|[A-Z\xC0-\xD6\xD8-\xDE]+(?![a-z\xDF-\xF6\xF8-\xFF])|\d+/g;
+export const toCamelCase = (sentence) => {
+    let [word, ...rest] = sentence.match(PAT) ?? [''];
+    if (isNumeric(word)) {
+        word = rest[0];
+        rest.splice(0, 1);
+    }
+    return (sentence.startsWith('_') ? '_' : '') + word.toLocaleLowerCase() + toProperCase(...rest).replace(/ /g, '');
+};
+const HEX = 16;
+export const randomString = (len = 36) => {
+    let str = '';
+    do // generate random strings
+        str += Math.floor(Math.random() * 10 ** 16).toString(HEX).substring(2, 15);
+    while (str.length < len);
+    return str.substring(0, len);
+};
+export function sprintf(fmt, ...msg) {
+    const regexp = /\$\{(\d)\}/g; // pattern to find "${digit}" parameter markers
+    let sfmt = asString(fmt); // avoid mutate fmt
+    if (!isString(fmt)) { // might be an Object
+        msg.unshift(JSON.stringify(fmt)); // push to start of msg[]
+        sfmt = ''; // reset the string-format
+    }
+    let cnt = 0; // if the format does not contain a corresponding '${digit}' then re-construct the parameters
+    sfmt = sfmt.replace(/%[sj]/g, _ => `\${${cnt++}}`); // flip all the %s or %j to a ${digit} parameter
+    const params = Array.from(sfmt.matchAll(regexp))
+        .map(match => Number(match[1])); // which parameters are in the fmt
+    msg.forEach((_, idx) => {
+        if (!params.includes(idx)) // if more args than params
+            sfmt += `${sfmt.length === 0 ? '' : sfmt.endsWith(':') ? ' ' : ', '}\${${idx}}`; //  append a dummy params to fmt
+    });
+    // 2024-02-21  some Objects do not have a .toString method
+    return sfmt.replace(regexp, (_, idx) => msg[idx]?.toString?.() || stringify(msg[idx]));
+}
+/** apply a plural suffix, if greater than '1' */
+export const plural = (val, word, plural = word + 's') => {
+    const _plural = (num, word, plural = word + 's') => [1, -1].includes(Number(num)) ? word : plural;
+    return isObject(val)
+        ? (num, word) => _plural(num, word, val[word])
+        : _plural(val, word, plural);
+};
+/** strip a plural suffix, if endsWith 's' */
+export const singular = (val) => val.endsWith('s') ? val.slice(0, -1) : val;
+/** make an Object's values into a Template Literals, and evaluate */
+export const makeTemplate = (templateString) => (templateData) => new Function(`{${Object.keys(templateData).join(',')}}`, 'return `' + templateString + '`')(templateData);
+/** stringify if not nullish */
+export { asString } from './coercion.library.js';
+export const toLower = (str) => isString(str) ? asString(str).toLowerCase().trim() : str;
+export const toUpper = (str) => isString(str) ? asString(str).toUpperCase().trim() : str;
+export const strlen = (str, min, max) => {
+    assertString(str);
+    assertCondition(str.length >= min && str.length <= (max ?? min), 'string length is not between specified min and max');
+    return str;
+};
+/**
+ * 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 const pad = (nbr = 0, len = 2, fill) => nbr.toString().padStart(len, nullToValue(fill, isNumeric(nbr) ? '0' : ' ').toString());
+/** pad a string with non-blocking spaces, to help right-align a display */
+export const padString = (str, pad = 6) => (isNumeric(str) ? asNumber(str).toFixed(2).toString() : str.toString() ?? '').padStart(pad, '\u007F');

package/dist/tempo.class.d.ts

@@ -0,0 +1,556 @@
+import type { IntRange, LiteralKey, LooseUnion, NonOptional, Property, Type } from './type.library.js';
+import * as enums from './tempo.config/tempo.enum.js';
+import { Token, Snippet, Layout, Event, Period } from './tempo.config/tempo.default.js';
+import './prototype.library.js';
+/**
+ * # Tempo
+ * **Tempo** is a powerful wrapper around `Temporal.ZonedDateTime` designed for flexible parsing and intuitive manipulation of date-time objects.
+ *
+ * It bridges the gap between raw string/number inputs and the strict requirements of the ECMAScript Temporal API.
+ *
+ * ### Key Features
+ * - **Flexible Parsing**: Interprets strings, numbers, BigInts, and various Temporal objects.
+ * - **Static Utility**: Access to common enums like `WEEKDAY`, `MONTH` and `SEASON`.
+ * - **Fluent API**: Methods for adding, setting, formatting, and comparing date-times.
+ * - **Alias Parsing**: Define custom `events` (e.g., "xmas" → "25 Dec") and `periods` (e.g., "noon" → "12:00") for intuitive parsing.
+ * - **Plugin System**: Extensible via "terms" to provide contextual date calculations (e.g., quarters, seasons, zodiac signs, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Standard parsing
+ * const t1 = new Tempo('2024-05-20');
+ *
+ * // Using an event alias (pre-defined or custom)
+ * const t2 = new Tempo('christmas'); // Dec 25th
+ *
+ * // Using a period alias
+ * const t3 = new Tempo('2024-05-20 midnight'); // 2024-05-20T00:00:00
+ *
+ * // Custom events and periods for this instance
+ * const t4 = new Tempo('birthday', {
+ *   event: [['birthday', '20 May']],
+ *   period: [['tea-time', '15:30']]
+ * })
+ * ```
+ */
+export declare class Tempo {
+    #private;
+    /** Weekday names (short-form) */ static get WEEKDAY(): import("./enumerate.library.js").Enum.wrap<import("./type.library.js").Index<readonly ["All", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]>>;
+    /** Weekday names (long-form) */ static get WEEKDAYS(): import("./enumerate.library.js").Enum.wrap<import("./type.library.js").Index<readonly ["Everyday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]>>;
+    /** Month names (short-form) */ static get MONTH(): import("./enumerate.library.js").Enum.wrap<import("./type.library.js").Index<readonly ["All", "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]>>;
+    /** Month names (long-form) */ static get MONTHS(): import("./enumerate.library.js").Enum.wrap<import("./type.library.js").Index<readonly ["Every", "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]>>;
+    /** Time durations as seconds (singular) */ static get DURATION(): import("./enumerate.library.js").Enum.wrap<{
+        readonly year: 31536000;
+        readonly month: 2628000;
+        readonly week: 604800;
+        readonly day: 86400;
+        readonly hour: 3600;
+        readonly minute: 60;
+        readonly second: 1;
+        readonly millisecond: 0.001;
+        readonly microsecond: 0.000001;
+        readonly nanosecond: 1e-9;
+    }>;
+    /** Time durations as milliseconds (plural) */ static get DURATIONS(): import("./enumerate.library.js").Enum.wrap<{
+        readonly years: number;
+        readonly months: number;
+        readonly weeks: number;
+        readonly days: number;
+        readonly hours: number;
+        readonly minutes: number;
+        readonly seconds: number;
+        readonly milliseconds: number;
+        readonly microseconds: number;
+        readonly nanoseconds: number;
+    }>;
+    /** Quarterly Seasons */ static get SEASON(): import("./enumerate.library.js").Enum.wrap<{
+        readonly Summer: "summer";
+        readonly Autumn: "autumn";
+        readonly Winter: "winter";
+        readonly Spring: "spring";
+    }>;
+    /** Compass cardinal points */ static get COMPASS(): import("./enumerate.library.js").Enum.wrap<{
+        readonly North: "north";
+        readonly East: "east";
+        readonly South: "south";
+        readonly West: "west";
+    }>;
+    /** Tempo to Temporal DateTime Units map */ static get ELEMENT(): import("./enumerate.library.js").Enum.wrap<{
+        readonly yy: "year";
+        readonly mm: "month";
+        readonly ww: "week";
+        readonly dd: "day";
+        readonly hh: "hour";
+        readonly mi: "minute";
+        readonly ss: "second";
+        readonly ms: "millisecond";
+        readonly us: "microsecond";
+        readonly ns: "nanosecond";
+    }>;
+    /** Pre-configured format {name -> string} pairs */ static get FORMAT(): import("./enumerate.library.js").Enum.wrap<{
+        readonly display: "{www}, {dd} {mmm} {yyyy}";
+        readonly weekDate: "{www}, {yyyy}-{mmm}-{dd}";
+        readonly weekTime: "{www}, {yyyy}-{mmm}-{dd} {hh}:{mi}:{ss}";
+        readonly weekStamp: "{www}, {yyyy}-{mmm}-{dd} {hh}:{mi}:{ss}.{ff}";
+        readonly dayMonth: "{dd}-{mmm}";
+        readonly dayDate: "{dd}-{mmm}-{yyyy}";
+        readonly dayTime: "{dd}-{mmm}-{yyyy} {hh}:{mi}:{ss}";
+        readonly logStamp: "{yyyy}{mm}{dd}T{hhmiss}.{ff}";
+        readonly sortTime: "{yyyy}-{mm}-{dd} {hh}:{mi}:{ss}";
+        readonly yearWeek: "{yyyy}{ww}";
+        readonly yearMonth: "{yyyy}{mm}";
+        readonly yearMonthDay: "{yyyy}{mm}{dd}";
+        readonly date: "{yyyy}-{mm}-{dd}";
+        readonly time: "{hh}:{mi}:{ss}";
+    }>;
+    /** some useful Dates */ static get LIMIT(): import("./type.library.js").SecureObject<{
+        readonly maxTempo: bigint;
+        readonly minTempo: bigint;
+    }>;
+    /**
+     * Initializes the global default configuration for all subsequent `Tempo` instances.
+     *
+     * Settings are inherited in this priority:
+     * 1. Reasonable library defaults (defined in tempo.config.js)
+     * 2. Persistent storage (e.g. localStorage), if available.
+     * 3. `options` provided to this method.
+     *
+     * @param options - Configuration overrides to apply globally.
+     * @returns The resolved global configuration.
+     */
+    static init(options?: Tempo.Options): Tempo.Config;
+    /**
+     * Reads `Tempo` options from persistent storage (e.g., localStorage).
+     * @returns The stored configuration or an empty object.
+     */
+    static readStore(key?: string): Partial<{
+        /** localStorage key */ store: string;
+        /** additional console.log for tracking */ debug: boolean | undefined;
+        /** catch or throw Errors */ catch: boolean | undefined;
+        /** Temporal timeZone */ timeZone: string;
+        /** Temporal calendar */ calendar: string;
+        /** locale (e.g. en-AU) */ locale: string;
+        /** pivot year for two-digit years */ pivot: number;
+        /** hemisphere for term.qtr or term.szn */ sphere: Tempo.COMPASS | undefined;
+        /** granularity of timestamps (ms | ns) */ timeStamp: Tempo.TimeStamp;
+        /** locale-names that prefer 'mm-dd-yy' date order */ mdyLocales: string | string[];
+        /** swap parse-order of layouts */ mdyLayouts: Internal.StringTuple[];
+        /** date-time snippets to help compose a Layout */ snippet: Snippet | Internal.PatternOption<string | RegExp>;
+        /** patterns to help parse value */ layout: Layout | Internal.PatternOption<string | RegExp>;
+        /** custom date aliases (events). */ event: Event | Internal.PatternOption<string | Function>;
+        /** custom time aliases (periods). */ period: Period | Internal.PatternOption<string | Function>;
+        /** supplied value to parse */ value: Tempo.DateTime;
+    }>;
+    /**
+     * Writes the provided configuration into persistent storage.
+     * @param config - The options to save.
+     */
+    static writeStore(config?: Tempo.Options, key?: string): void;
+    /**
+     * looks-up or registers a new `Symbol` for a given key.
+     * auto-maintains the `Token` registry for internal consistency.
+     *
+     * @param key - The description for which to retrieve/create a Symbol.
+     */
+    static getSymbol(key?: string | symbol): symbol;
+    /**
+     * translates a {layout} string into an anchored, case-insensitive regular expression.
+     * supports placeholder expansion using the {snippet} registry (e.g., `{yy}`, `{mm}`).
+     */
+    static regexp(layout: string | RegExp, snippet?: Snippet): RegExp;
+    /**
+     * Compares two `Tempo` instances or date-time values.
+     * Useful for sorting or determining chronological order.
+     *
+     * @param tempo1 - The first value to compare.
+     * @param tempo2 - The second value to compare (defaults to 'now').
+     * @returns `-1` if `tempo1 < tempo2`, `0` if tempo1 == tempo2, `1` if `tempo1 > tempo2`.
+     *
+     * @example
+     * ```typescript
+     * const sorted = [t1, t2].sort(Tempo.compare);
+     * ```
+     */
+    static compare(tempo1?: Tempo.DateTime | Tempo.Options, tempo2?: Tempo.DateTime | Tempo.Options): number;
+    /** Creates a new `Tempo` instance. */
+    static from(options?: Tempo.Options): Tempo;
+    static from(tempo: Tempo.DateTime | undefined, options?: Tempo.Options): Tempo;
+    /** Returns current time as epoch nanoseconds (BigInt). */
+    static now(): bigint;
+    /** static Tempo.terms getter */
+    static get terms(): import("./type.library.js").SecureArray<{
+        key: string;
+        scope: string;
+        description: string;
+    }>;
+    /** static Tempo properties getter */
+    static get properties(): import("./type.library.js").SecureArray<string | number | symbol>;
+    /** Tempo global config settings */
+    static get config(): import("./type.library.js").SecureObject<{
+        readonly scope: "global" | "local";
+        readonly debug: boolean | undefined;
+        readonly timeStamp: Tempo.TimeStamp;
+        readonly store: string;
+        readonly catch: boolean | undefined;
+        readonly timeZone: string;
+        readonly calendar: string;
+        readonly locale: string;
+        readonly pivot: number;
+        readonly sphere: Tempo.COMPASS | undefined;
+        readonly snippet: Snippet | Internal.PatternOption<string | RegExp>;
+        readonly layout: Layout | Internal.PatternOption<string | RegExp>;
+        readonly event: Event | Internal.PatternOption<string | Function>;
+        readonly period: Period | Internal.PatternOption<string | Function>;
+    }>;
+    /** Tempo initial default settings */
+    static get default(): import("./type.library.js").SecureObject<import("./type.library.js").SecureObject<Partial<{
+        /** localStorage key */ store: string;
+        /** additional console.log for tracking */ debug: boolean | undefined;
+        /** catch or throw Errors */ catch: boolean | undefined;
+        /** Temporal timeZone */ timeZone: string;
+        /** Temporal calendar */ calendar: string;
+        /** locale (e.g. en-AU) */ locale: string;
+        /** pivot year for two-digit years */ pivot: number;
+        /** hemisphere for term.qtr or term.szn */ sphere: Tempo.COMPASS | undefined;
+        /** granularity of timestamps (ms | ns) */ timeStamp: Tempo.TimeStamp;
+        /** locale-names that prefer 'mm-dd-yy' date order */ mdyLocales: string | string[];
+        /** swap parse-order of layouts */ mdyLayouts: Internal.StringTuple[];
+        /** date-time snippets to help compose a Layout */ snippet: Snippet | Internal.PatternOption<string | RegExp>;
+        /** patterns to help parse value */ layout: Layout | Internal.PatternOption<string | RegExp>;
+        /** custom date aliases (events). */ event: Event | Internal.PatternOption<string | Function>;
+        /** custom time aliases (periods). */ period: Period | Internal.PatternOption<string | Function>;
+        /** supplied value to parse */ value: Tempo.DateTime;
+    }>>>;
+    /**
+     * configuration governing the static 'rules' used when parsing Tempo.DateTime argument
+     */
+    static get parse(): import("./type.library.js").SecureObject<{
+        readonly snippet: {
+            readonly [x: symbol]: RegExp;
+        };
+        readonly layout: {
+            readonly [x: symbol]: "{dd}{sep}?{mm}({sep}?{yy})?|{mod}?({evt})" | "({hh}{mi}?{ss}?{ff}?{mer}?|{per})" | "({dt}){sfx}?" | "({wkd}{sep}+)?{dd}{sep}?{mm}({sep}?{yy})?{sfx}?" | "({wkd}{sep}+)?{mm}{sep}?{dd}({sep}?{yy})?{sfx}?" | "({wkd}{sep}+)?{yy}{sep}?{mm}({sep}?{dd})?{sfx}?" | "{mod}?{wkd}{afx}?{sfx}?" | "{mod}?{dd}{afx}?" | "{nbr}{sep}?{unt}{sep}?{afx}";
+        };
+        readonly event: {
+            readonly [x: string]: string | Function;
+            readonly 'new.?years? ?eve': "31 Dec";
+            readonly nye: "31 Dec";
+            readonly 'new.?years?( ?day)?': "01 Jan";
+            readonly ny: "01 Jan";
+            readonly 'christmas ?eve': "24 Dec";
+            readonly christmas: "25 Dec";
+            readonly 'xmas ?eve': "24 Dec";
+            readonly xmas: "25 Dec";
+            readonly now: (this: any) => Temporal.Instant;
+            readonly today: (this: any) => Temporal.PlainDate;
+            readonly tomorrow: (this: any) => Temporal.PlainDate;
+            readonly yesterday: (this: any) => Temporal.PlainDate;
+        };
+        readonly period: {
+            readonly [x: string]: string | Function;
+            readonly 'mid[ -]?night': "24:00";
+            readonly morning: "8:00";
+            readonly 'mid[ -]?morning': "10:00";
+            readonly 'mid[ -]?day': "12:00";
+            readonly noon: "12:00";
+            readonly 'after[ -]?noon': "3:00pm";
+            readonly evening: "18:00";
+            readonly night: "20:00";
+        };
+        readonly mdyLocales: {
+            locale: string;
+            timeZones: string[];
+        }[];
+        readonly mdyLayouts: Internal.StringTuple[];
+        readonly isMonthDay?: boolean;
+        readonly token: Token;
+        readonly pattern: Internal.RegexpMap;
+        readonly result: Internal.Match[];
+    }>;
+    /** iterate over Tempo properties */
+    static [Symbol.iterator](): ArrayIterator<string | number | symbol>;
+    /** allow for auto-convert of Tempo to BigInt */
+    [Symbol.toPrimitive](hint?: 'string' | 'number' | 'default'): bigint;
+    /** iterate over instance formats */
+    [Symbol.iterator](): ArrayIterator<import("./type.library.js").EntryOf<{
+        [x: string & {}]: string;
+        display: string;
+        weekDate: string;
+        weekTime: string;
+        weekStamp: string;
+        dayMonth: string;
+        dayDate: string;
+        dayTime: string;
+        logStamp: string;
+        sortTime: string;
+        yearWeek: string;
+        yearMonth: string;
+        yearMonthDay: string;
+        date: string;
+        time: string;
+    }>>;
+    get [Symbol.toStringTag](): string;
+    /**
+     * Instantiates a new `Tempo` object.
+     *
+     * @param tempo - The date-time value to parse. Can be a string, number, BigInt, Date, or another Tempo/Temporal object.
+     * @param options - Configuration options for this specific instance.
+     */
+    constructor(options?: Tempo.Options);
+    constructor(tempo: Tempo.DateTime, options?: Tempo.Options);
+    /** 4-digit year (e.g., 2024) */ get yy(): number;
+    /** Month number: Jan=1, Dec=12 */ get mm(): Tempo.mm;
+    /** ISO week number of the year */ get ww(): Tempo.ww;
+    /** Day of the month (1-31) */ get dd(): number;
+    /** Day of the month (alias for `dd`) */ get day(): number;
+    /** Hour of the day (0-23) */ get hh(): Tempo.hh;
+    /** Minutes of the hour (0-59) */ get mi(): Tempo.mi;
+    /** Seconds of the minute (0-59) */ get ss(): Tempo.ss;
+    /** Milliseconds of the second (0-999) */ get ms(): Tempo.ms;
+    /** Microseconds of the millisecond (0-999) */ get us(): Tempo.us;
+    /** Nanoseconds of the microsecond (0-999) */ get ns(): Tempo.ns;
+    /** Fractional seconds (e.g., 0.123456789) */ get ff(): number;
+    /** IANA Time Zone ID (e.g., 'Australia/Sydney') */ get tz(): string;
+    /** Unix timestamp (defaults to milliseconds) */ get ts(): number | bigint;
+    /** Short month name (e.g., 'Jan') */ get mmm(): "All" | "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec";
+    /** Full month name (e.g., 'January') */ get mon(): "May" | "Every" | "January" | "February" | "March" | "April" | "June" | "July" | "August" | "September" | "October" | "November" | "December";
+    /** Short weekday name (e.g., 'Mon') */ get www(): "All" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun";
+    /** Full weekday name (e.g., 'Monday') */ get wkd(): "Everyday" | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday";
+    /** ISO weekday number: Mon=1, Sun=7 */ get dow(): Tempo.Weekday;
+    /** Nanoseconds since Unix epoch (BigInt) */ get nano(): bigint;
+    /** Instance-specific configuration settings */ get config(): Tempo.Config;
+    /** Instance-specific parse rules (merged with global) */ get parse(): Internal.Parse;
+    /** Object containing results from all term plugins */ get term(): Property<any>;
+    /** Formatted results for all pre-defined format codes */ get fmt(): {
+        [x: string & {}]: string;
+        display: string;
+        weekDate: string;
+        weekTime: string;
+        weekStamp: string;
+        dayMonth: string;
+        dayDate: string;
+        dayTime: string;
+        logStamp: string;
+        sortTime: string;
+        yearWeek: string;
+        yearMonth: string;
+        yearMonthDay: string;
+        date: string;
+        time: string;
+    };
+    /** units since epoch */ get epoch(): import("./type.library.js").SecureObject<{
+        /** seconds since epoch */ readonly ss: number;
+        /** milliseconds since epoch */ readonly ms: number;
+        /** microseconds since epoch */ readonly us: number;
+        /** nanoseconds since epoch */ readonly ns: bigint;
+    }>;
+    /** time duration until (with unit, returns number) */ until(until: Tempo.Until, opts?: Tempo.Options): number;
+    /** time duration until another date-time (with unit) */ until(dateTimeOrOpts: Tempo.DateTime | Tempo.Options, until: Tempo.Until): number;
+    /** time duration until (returns Duration) */ until(dateTimeOrOpts?: Tempo.DateTime | Tempo.Options, opts?: Tempo.Options): Tempo.Duration;
+    /** time elapsed since (with unit) */ since(until: Tempo.Until, opts?: Tempo.Options): string;
+    /** time elapsed since another date-time (with unit) */ since(dateTimeOrOpts: Tempo.DateTime | Tempo.Options, until: Tempo.Until): string;
+    /** time elapsed since (without unit) */ since(dateTimeOrOpts?: Tempo.DateTime | Tempo.Options, opts?: Tempo.Options): string;
+    /** applies a format to the current `Tempo` instance. */ format<K extends enums.Format>(fmt: K): Tempo.FormatType<K>;
+    /** returns a new `Tempo` with specific duration added. */ add(mutate: Tempo.Add): Tempo;
+    /** returns a new `Tempo` with specific offsets. */ set(offset: Tempo.Set | Tempo.Add): Tempo;
+    /** `true` if the underlying date-time is valid. */ isValid(): boolean;
+    /** the underlying `Temporal.ZonedDateTime` object. */ toDateTime(): Temporal.ZonedDateTime;
+    /** the date-time as a `Temporal.Instant`. */ toInstant(): Temporal.Instant;
+    /** the date-time as a standard `Date` object. */ toDate(): Date;
+    /** the ISO8601 string representation of the date-time. */ toString(): string;
+    /** Custom JSON serialization for `JSON.stringify`. */ toJSON(): {
+        value: string;
+        /** configuration (global | local) */ scope: "global" | "local";
+        debug: boolean | undefined;
+        timeStamp: Tempo.TimeStamp;
+        store: string;
+        catch: boolean | undefined;
+        timeZone: string;
+        calendar: string;
+        locale: string;
+        pivot: number;
+        sphere: Tempo.COMPASS | undefined;
+        snippet: Snippet | Internal.PatternOption<string | RegExp>;
+        layout: Layout | Internal.PatternOption<string | RegExp>;
+        event: Event | Internal.PatternOption<string | Function>;
+        period: Period | Internal.PatternOption<string | Function>;
+    };
+}
+export declare namespace Tempo {
+    /** the value that Tempo will attempt to interpret as a valid ISO date / time */
+    export type DateTime = string | number | bigint | Date | Tempo | typeof Temporal | Temporal.ZonedDateTimeLike | undefined | null;
+    /** the Options object found in a json-file, or passed to a call to Tempo.Init({}) or 'new Tempo({}) */
+    export type Options = Partial<{
+        /** localStorage key */ store: string;
+        /** additional console.log for tracking */ debug: boolean | undefined;
+        /** catch or throw Errors */ catch: boolean | undefined;
+        /** Temporal timeZone */ timeZone: string;
+        /** Temporal calendar */ calendar: string;
+        /** locale (e.g. en-AU) */ locale: string;
+        /** pivot year for two-digit years */ pivot: number;
+        /** hemisphere for term.qtr or term.szn */ sphere: Tempo.COMPASS | undefined;
+        /** granularity of timestamps (ms | ns) */ timeStamp: Tempo.TimeStamp;
+        /** locale-names that prefer 'mm-dd-yy' date order */ mdyLocales: string | string[];
+        /** swap parse-order of layouts */ mdyLayouts: Internal.StringTuple[];
+        /** date-time snippets to help compose a Layout */ snippet: Snippet | Internal.PatternOption<string | RegExp>;
+        /** patterns to help parse value */ layout: Layout | Internal.PatternOption<string | RegExp>;
+        /** custom date aliases (events). */ event: Event | Internal.PatternOption<string | Function>;
+        /** custom time aliases (periods). */ period: Period | Internal.PatternOption<string | Function>;
+        /** supplied value to parse */ value: Tempo.DateTime;
+    }>;
+    /** drop the setup-only Options */
+    type OptionsKeep = Omit<Options, "value" | "mdyLocales" | "mdyLayouts">;
+    /**
+     * the Config that Tempo will use to interpret a Tempo.DateTime
+     * derived from user-supplied options, else json-stored options, else reasonable-default options
+     */
+    export interface Config extends Required<OptionsKeep> {
+        /** configuration (global | local) */ scope: 'global' | 'local';
+    }
+    /** Timestamp precision */
+    export type TimeStamp = 'ss' | 'ms' | 'us' | 'ns';
+    /** Configuration to use for #until() and #since() argument */
+    export type Unit = Temporal.DateUnit | Temporal.TimeUnit;
+    export type Until = (Tempo.Options & {
+        unit?: Tempo.Unit;
+    }) | Tempo.Unit;
+    export type Mutate = 'start' | 'mid' | 'end';
+    export type Set = Partial<Record<Tempo.Mutate, Tempo.Unit> & Record<'date' | 'time' | 'event' | 'period', string>>;
+    export type Add = Partial<Record<Tempo.Unit, number>>;
+    /** pre-configured format strings */
+    export interface Format {
+        /** www, dd mmm yyyy */ [Tempo.FORMAT.display]: string;
+        /** www, dd mmm yyyy */ display: string;
+        /** www, yyyy-mmm-dd */ [Tempo.FORMAT.weekDate]: string;
+        /** www, yyyy-mmm-dd */ weekDate: string;
+        /** www, yyyy-mmm-dd hh:mi.ss */ [Tempo.FORMAT.weekTime]: string;
+        /** www, yyyy-mmm-dd hh:mi.ss */ weekTime: string;
+        /** www, yyyy-mmm-dd hh:mi:ss.ff */ [Tempo.FORMAT.weekStamp]: string;
+        /** www, yyyy-mmm-dd hh:mi:ss.ff */ weekStamp: string;
+        /** dd-mmm */ [Tempo.FORMAT.dayMonth]: string;
+        /** dd-mmm */ dayMonth: string;
+        /** dd-mmm-yyyy */ [Tempo.FORMAT.dayDate]: string;
+        /** dd-mmm-yyyy */ dayDate: string;
+        /** dd-mmm-yyyy hh:mi:ss */ [Tempo.FORMAT.dayTime]: string;
+        /** dd-mmm-yyyy hh:mi:ss */ dayTime: string;
+        /** yyyymmdd.hhmiss.ff */ [Tempo.FORMAT.logStamp]: string;
+        /** yyyymmdd.hhmiss.ff */ logStamp: string;
+        /** yyyy-mm-dd hh:mi:ss */ [Tempo.FORMAT.sortTime]: string;
+        /** yyyy-mm-dd hh:mi:ss */ sortTime: string;
+        /** yyyyww */ [Tempo.FORMAT.yearWeek]: number;
+        /** yyyyww */ yearWeek: number;
+        /** yyyymm */ [Tempo.FORMAT.yearMonth]: number;
+        /** yyyymm */ yearMonth: number;
+        /** yyyymmdd */ [Tempo.FORMAT.yearMonthDay]: number;
+        /** yyyymmdd */ yearMonthDay: number;
+        /** ww */ [Tempo.ELEMENT.ww]: Tempo.WEEKDAY;
+        /** www */ weekDay: Tempo.WEEKDAY;
+        /** yyyy-mm-dd */ [Tempo.FORMAT.date]: string;
+        /** yyyy-mm-dd */ date: string;
+        /** hh:mi:ss */ [Tempo.FORMAT.time]: string;
+        /** hh:mi:ss */ time: string;
+        /** generic format */ [key: string]: string | number;
+    }
+    export type FormatType<K extends string> = K extends LiteralKey<Format> ? Format[K] : string;
+    export type Modifier = '=' | '-' | '+' | '<' | '<=' | '-=' | '>' | '>=' | '+=' | 'this' | 'next' | 'prev' | 'last' | 'first' | undefined;
+    export type Relative = 'ago' | 'hence' | 'prior';
+    export type mm = IntRange<0, 12>;
+    export type hh = IntRange<0, 24>;
+    export type mi = IntRange<0, 60>;
+    export type ss = IntRange<0, 60>;
+    export type ms = IntRange<0, 999>;
+    export type us = IntRange<0, 999>;
+    export type ns = IntRange<0, 999>;
+    export type ww = IntRange<1, 52>;
+    export type Duration = NonOptional<Temporal.DurationLikeObject> & Record<"iso", string> & Record<"sign", Temporal.Duration["sign"]> & Record<"blank", Temporal.Duration["blank"]> & Record<"unit", string | undefined>;
+    export type WEEKDAY = enums.WEEKDAY;
+    export type WEEKDAYS = enums.WEEKDAYS;
+    export type MONTH = enums.MONTH;
+    export type MONTHS = enums.MONTHS;
+    export type COMPASS = enums.COMPASS;
+    export type ELEMENT = enums.ELEMENT;
+    export type Weekday = enums.Weekday;
+    export type Month = enums.Month;
+    export type Element = enums.Element;
+    export {};
+}
+declare namespace Internal {
+    type StringPattern = string | RegExp;
+    type StringFunction = string | number | Function;
+    type StringTuple = [string, string];
+    type GroupWkd = {
+        wkd?: Tempo.WEEKDAY;
+        mod?: Tempo.Modifier;
+        nbr?: string;
+        sfx?: Tempo.Relative;
+        hh?: string;
+        mi?: string;
+        ss?: string;
+        ms?: string;
+        us?: string;
+        ns?: string;
+        ff?: string;
+        mer?: string;
+    };
+    type GroupDate = {
+        mod?: Tempo.Modifier;
+        nbr?: string;
+        afx?: Tempo.Relative;
+        unt?: string;
+        yy?: string;
+        mm?: string;
+        dd?: string;
+    };
+    type GroupModifier = {
+        mod?: Tempo.Modifier | Tempo.Relative;
+        adjust: number;
+        offset: number;
+        period: number;
+    };
+    type PatternOption<T> = T | Record<string | symbol, T> | PatternOption<T>[];
+    interface Shape {
+        /** current defaults for all Tempo instances */ config: Tempo.Config;
+        /** parsing rules */ parse: Internal.Parse;
+    }
+    /**
+     * Parsing rules
+     * Once a Tempo is instantiated, these values are for debug purposes only
+     */
+    interface Parse {
+        /** Locales which prefer 'mm-dd-yyyy' date-order */ mdyLocales: {
+            locale: string;
+            timeZones: string[];
+        }[];
+        /** Layout names that are switched to mdy */ mdyLayouts: Internal.StringTuple[];
+        /** is a timeZone that prefers 'mmddyyyy' date order */ isMonthDay?: boolean;
+        /** Symbol registry */ token: Token;
+        /** Tempo snippets to aid in parsing */ snippet: Snippet;
+        /** Tempo layout strings */ layout: Layout;
+        /** Map of regex-patterns to match input-string */ pattern: Internal.RegexpMap;
+        /** configured Events */ event: Event;
+        /** configured Periods */ period: Period;
+        /** parsing match result */ result: Internal.Match[];
+    }
+    /** debug a Tempo instantiation */
+    interface Match {
+        /** pattern which matched the input */ match?: string | undefined;
+        /** groups from the pattern match */ groups?: Internal.StringRecord;
+        /** the type of the original input */ type: LooseUnion<Type>;
+        /** the value of the original input */ value: any;
+    }
+    type StringRecord = Record<string, string>;
+    type RegexpMap = Map<symbol, RegExp>;
+}
+export type Params<T> = {
+    (tempo?: Tempo.DateTime, options?: Tempo.Options): T;
+    (options: Tempo.Options): T;
+};
+type Fmt = {
+    <F extends enums.Format>(fmt: F, tempo?: Tempo.DateTime, options?: Tempo.Options): Tempo.FormatType<F>;
+    <F extends enums.Format>(fmt: F, options: Tempo.Options): Tempo.FormatType<F>;
+};
+/** check valid Tempo */ export declare const isTempo: (tempo?: unknown) => tempo is Tempo;
+/** current timestamp (ts) */ export declare const getStamp: Params<number | bigint>;
+/** create new Tempo */ export declare const getTempo: Params<Tempo>;
+/** format a Tempo */ export declare const fmtTempo: Fmt;
+export {};