@ambarltd/core 0.1.17

package/dist/test.js

@@ -0,0 +1,470 @@
+import { object } from "@optique/core/constructs";
+import { multiple } from "@optique/core/modifiers";
+import { option } from "@optique/core/primitives";
+import { run as runCli } from "@optique/run";
+import { message } from "@optique/core/message";
+import { randomUUID } from "node:crypto";
+export { run, expect, group, test, parseArgs };
+class Test {
+    name;
+    fun;
+    id;
+    constructor(name, fun) {
+        this.name = name;
+        this.fun = fun;
+        this.id = randomUUID();
+    }
+}
+class Group {
+    name;
+    entries;
+    constructor(name, entries) {
+        this.name = name;
+        this.entries = entries;
+    }
+}
+const test = (x, y) => new Test(x, y);
+const group = (x, y) => new Group(x, y);
+const INDENT = "  ";
+const USE_COLORS = process.stdout.isTTY;
+const PROGRESS_UPDATE_INTERVAL = 500;
+function red(txt) {
+    return USE_COLORS ? `\x1b[31m${txt}\x1b[0m` : txt;
+}
+function green(txt) {
+    return USE_COLORS ? `\x1b[32m${txt}\x1b[0m` : txt;
+}
+function gray(txt) {
+    return USE_COLORS ? `\x1b[90m${txt}\x1b[0m` : txt;
+}
+function italic(txt) {
+    return USE_COLORS ? `\x1b[3m${txt}\x1b[0m` : txt;
+}
+function yellow(txt) {
+    return USE_COLORS ? `\x1b[33m${txt}\x1b[0m` : txt;
+}
+function collectTestInfos(group, parentPath, startOrder) {
+    const currentPath = [...parentPath, group.name];
+    let currentOrder = startOrder;
+    const allInfos = new Map();
+    for (const entry of group.entries) {
+        if (entry instanceof Test) {
+            const fullName = currentPath.concat(entry.name).join(" / ");
+            allInfos.set(entry.id, {
+                fullName,
+                order: currentOrder,
+                state: { type: "not-started" },
+            });
+            currentOrder++;
+        }
+        else if (entry instanceof Group) {
+            const result = collectTestInfos(entry, currentPath, currentOrder);
+            for (const [key, value] of result.infos) {
+                allInfos.set(key, value);
+            }
+            currentOrder = result.nextOrder;
+        }
+    }
+    return { infos: allInfos, nextOrder: currentOrder };
+}
+function buildProgressDisplay(executionInfos) {
+    const total = executionInfos.size;
+    const stats = Array.from(executionInfos.values()).reduce((acc, info) => {
+        if (info.state.type === "finished") {
+            return {
+                ...acc,
+                completed: acc.completed + 1,
+                successes: info.state.failure === null ? acc.successes + 1 : acc.successes,
+                failures: info.state.failure !== null ? acc.failures + 1 : acc.failures,
+            };
+        }
+        else if (info.state.type === "started") {
+            const elapsed = Date.now() - info.state.start;
+            return {
+                ...acc,
+                running: [
+                    ...acc.running,
+                    {
+                        name: info.fullName,
+                        duration: prettyTime(elapsed),
+                        startTime: info.state.start,
+                    },
+                ],
+            };
+        }
+        return acc;
+    }, {
+        completed: 0,
+        successes: 0,
+        failures: 0,
+        running: [],
+    });
+    const recentRunning = stats.running.sort((a, b) => a.startTime - b.startTime).slice(-6);
+    return [
+        gray(`Running ${stats.completed}/${total} ... (${green(`✓ ${stats.successes}`)} / ${red(`✗ ${stats.failures}`)})`),
+        ...recentRunning.map(({ name, duration }) => `  ${name} - ${gray(duration)}`),
+    ];
+}
+function startProgressDisplay(executionInfos) {
+    let lastHeight = 0;
+    let stopped = false;
+    const render = () => {
+        if (stopped)
+            return;
+        const lines = buildProgressDisplay(executionInfos);
+        if (lastHeight > 0) {
+            process.stdout.write(`\x1b[${lastHeight}A`);
+        }
+        for (const line of lines) {
+            process.stdout.write("\r");
+            process.stdout.write("\x1b[2K");
+            process.stdout.write(line);
+            process.stdout.write("\n");
+        }
+        if (lines.length < lastHeight) {
+            const extraLines = lastHeight - lines.length;
+            for (let i = 0; i < extraLines; i++) {
+                process.stdout.write("\r\x1b[2K\n");
+            }
+            process.stdout.write(`\x1b[${extraLines}A`);
+        }
+        lastHeight = lines.length;
+    };
+    render();
+    const interval = setInterval(render, PROGRESS_UPDATE_INTERVAL);
+    return {
+        stop: () => {
+            stopped = true;
+            clearInterval(interval);
+        },
+        clear: () => {
+            if (lastHeight > 0) {
+                process.stdout.write(`\x1b[${lastHeight}A`);
+                process.stdout.write("\x1b[0J");
+                lastHeight = 0;
+            }
+        },
+    };
+}
+/**
+ * Run a test suite. This should be the entry point of a test program.
+ *
+ * A sane, simple testing framework. Instead of a complicated test setup which
+ * finds and compiles files, we do the simplest obvious thing: a function that
+ * takes a list of tests. To run the tests execute a Node.js program that calls
+ * this `run` function.
+ *
+ * ```ts
+ * import { run, test, group, expect, parseArgs } from "@ambarltd/core/test";
+ *
+ * run(parseArgs(), [
+ *   group("trivial tests", [
+ *     test("referential equality", () => expect.equals(1, 3)),
+ *     test("structural equality", () => expect.json_equals({}, {})),
+ *     test("async test", async () => {
+ *       const n = await fetchNumberFromTheInternet();
+ *       expect.equals(1, n);
+ *     }),
+ *   ]),
+ * ]);
+ * ```
+ *
+ * If you want tests in different files, just import them like you would
+ * in a normal program.
+ *
+ * ```ts
+ * import { run } from "@ambarltd/core/test";
+ * import * as unit from "@test/unitTests";
+ * import * as integration from "@test/integrationTests";
+ *
+ * run(parseArgs(), [unit.tests, integration.tests]);
+ * ```
+ */
+async function run(options, groups) {
+    const filters = options.filters || [];
+    const selectedGroups = filterGroups(groups, filters);
+    if (filters.length > 0 && selectedGroups.length === 0) {
+        console.log("No tests matched the provided filters.");
+        process.exit(0);
+    }
+    const collectedData = selectedGroups.reduce((acc, group) => {
+        const result = collectTestInfos(group, [], acc.nextOrder);
+        const mergedMap = new Map([...acc.infos, ...result.infos]);
+        return { infos: mergedMap, nextOrder: result.nextOrder };
+    }, { infos: new Map(), nextOrder: 0 });
+    const executionInfos = collectedData.infos;
+    const totalTests = executionInfos.size;
+    const before = Date.now();
+    const progressDisplay = startProgressDisplay(executionInfos);
+    const results = await Promise.all(selectedGroups.map(group => runGroup(group, executionInfos)));
+    progressDisplay.stop();
+    progressDisplay.clear();
+    process.stdout.write(`\r\x1b[K`);
+    const after = Date.now();
+    logResults(results);
+    const failures = getFailures(results);
+    const failed = failures.length > 0;
+    console.log("");
+    if (!failed) {
+        console.log(green("✓ Success"));
+    }
+    else {
+        console.log("\nFailures:\n");
+        failures.forEach(logFailure);
+        console.log(red("✗ Failed"));
+    }
+    console.log(`Tests:    ${totalTests - failures.length} passed, ${totalTests} total`);
+    console.log(`Duration: ${prettyTime(after - before)}`);
+    process.exit(failed ? 1 : 0);
+}
+function filterGroups(groups, filters) {
+    if (filters.length === 0) {
+        return groups;
+    }
+    return groups.flatMap(group => {
+        const filtered = filterGroup(group, filters, []);
+        return filtered ? [filtered] : [];
+    });
+}
+function logResults(results) {
+    function showLeaf(lvl, name, duration, failure) {
+        const color = failure === null ? green : red;
+        const symbol = failure === null ? "✓" : "✗";
+        console.log(`${INDENT.repeat(lvl)}${color(symbol)} ${name} ${gray(`(${prettyTime(duration)})`)}`);
+    }
+    function showNode(lvl, name, children) {
+        console.log(`${INDENT.repeat(lvl)}${italic(yellow(name))}`);
+        showTrees(lvl + 1, children);
+    }
+    function showTrees(lvl, trees) {
+        trees.forEach(tree => {
+            if (tree.type === "node") {
+                showNode(lvl, tree.name, tree.children);
+            }
+            else {
+                showLeaf(lvl, tree.name, tree.duration, tree.failure);
+            }
+        });
+    }
+    showTrees(0, results);
+}
+function getFailures(results) {
+    function fromOne(path, duration, reason) {
+        return reason === null ? [] : [{ path, reason, duration }];
+    }
+    function fromMany(path, rs) {
+        return rs.flatMap(r => {
+            const rpath = `${path}${path ? " / " : ""}${r.name}`;
+            return r.type === "node" ? fromMany(rpath, r.children) : fromOne(rpath, r.duration, r.failure);
+        });
+    }
+    return fromMany("", results);
+}
+function prettyTime(ms) {
+    const second = 1000;
+    const seconds = ms / second;
+    return `${seconds}s`;
+}
+function indented(str) {
+    return INDENT + str.split("\n").join(`\n${INDENT}`);
+}
+function logFailure({ path, reason, duration }) {
+    console.log(red(`- ${path}`));
+    console.log(indented(`Duration: ${prettyTime(duration)}`));
+    console.log(indented(reason));
+    console.log();
+}
+function filterGroup(group, filters, parents) {
+    const currentPath = joinPath([...parents, group.name]);
+    if (matchesAnyFilter(filters, currentPath)) {
+        return group;
+    }
+    const matchedEntries = [];
+    const pathSegments = [...parents, group.name];
+    for (const entry of group.entries) {
+        if (entry instanceof Group) {
+            const filteredChild = filterGroup(entry, filters, pathSegments);
+            if (filteredChild !== null) {
+                matchedEntries.push(filteredChild);
+            }
+            continue;
+        }
+        if (matchesAnyFilter(filters, joinPath([...pathSegments, entry.name]))) {
+            matchedEntries.push(entry);
+        }
+    }
+    if (matchedEntries.length === 0) {
+        return null;
+    }
+    return new Group(group.name, matchedEntries);
+}
+function matchesAnyFilter(filters, path) {
+    return filters.some(filter => filter.test(path));
+}
+function joinPath(parts) {
+    return parts.join(" / ");
+}
+async function runGroup(group, executionInfos) {
+    const children = await Promise.all(group.entries.map(entry => {
+        if (entry instanceof Test) {
+            return runTest(entry, executionInfos);
+        }
+        else {
+            return runGroup(entry, executionInfos);
+        }
+    }));
+    return {
+        type: "node",
+        name: group.name,
+        children,
+    };
+}
+async function runTest(test, executionInfos) {
+    const info = executionInfos.get(test.id);
+    const start = Date.now();
+    if (info) {
+        executionInfos.set(test.id, {
+            ...info,
+            state: { type: "started", start },
+        });
+    }
+    const failure = await execute(test);
+    const end = Date.now();
+    if (info) {
+        executionInfos.set(test.id, {
+            ...info,
+            state: { type: "finished", start, end, failure },
+        });
+    }
+    return {
+        type: "leaf",
+        name: test.name,
+        failure,
+        duration: end - start,
+    };
+}
+async function execute(test) {
+    try {
+        const r = test.fun();
+        if (r instanceof Promise) {
+            await r;
+        }
+        return null;
+    }
+    catch (e) {
+        const err = e;
+        return err.stack ? err.stack : err.message;
+    }
+}
+// Expectations
+class ExpectationFailure extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExpectationFailure";
+    }
+}
+const expect = {
+    fail: function fail(reason) {
+        throw new ExpectationFailure(reason);
+    },
+    equals: function equals(a, b, label) {
+        if (a === b) {
+            return;
+        }
+        const lbl = label ? `[${label}] ` : "";
+        throw new ExpectationFailure(`${lbl} expected ${a} to equal ${b}`);
+    },
+    deep_equals: function equals(ra, rb) {
+        const a = stringify(ra);
+        const b = stringify(rb);
+        if (a === b) {
+            return;
+        }
+        throw new ExpectationFailure(`expected '${a}' to equal '${b}'`);
+    },
+    greater_than: function greater_than(a, b) {
+        if (a > b) {
+            return;
+        }
+        throw new ExpectationFailure(`expected ${a} to be greater than ${b}`);
+    },
+    not_equals: function not_equals(a, b) {
+        if (a !== b) {
+            return;
+        }
+        throw new ExpectationFailure(`expected ${a} to not equal ${b}`);
+    },
+    json_equals: function json_equals(a, b) {
+        const j_a = JSON.stringify(a);
+        const j_b = JSON.stringify(b);
+        if (j_a == j_b) {
+            return;
+        }
+        throw new ExpectationFailure(`expected ${j_a} to equal ${j_b}`);
+    },
+    contains: function contains(needle, haystack) {
+        if (haystack.includes(needle)) {
+            return;
+        }
+        throw new ExpectationFailure(`expected '${haystack}' to contain '${needle}'`);
+    },
+    throws: function (f, g) {
+        try {
+            f();
+        }
+        catch (e) {
+            g(e);
+            return;
+        }
+        throw new ExpectationFailure("did not throw");
+    },
+};
+function stringify(v) {
+    const str = JSON.stringify(v);
+    if (str.startsWith("Object") || str.startsWith("[Function")) {
+        throw new Error("Value is not meaningfully stringifiable");
+    }
+    return str;
+}
+function extractPattern(input) {
+    if (input.startsWith("/") && input.lastIndexOf("/") > 0) {
+        const lastSlash = input.lastIndexOf("/");
+        const pattern = input.slice(1, lastSlash);
+        const flags = input.slice(lastSlash + 1);
+        return { pattern, flags };
+    }
+    return { pattern: input, flags: "" };
+}
+const regex = {
+    metavar: "REGEX",
+    parse(input) {
+        try {
+            const { pattern, flags } = extractPattern(input);
+            return { success: true, value: new RegExp(pattern, flags) };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                success: false,
+                error: message `Invalid regular expression ${input}: ${reason}`,
+            };
+        }
+    },
+    format(value) {
+        return value.toString();
+    },
+};
+const cliParser = object({
+    matches: multiple(option("-m", "--match", regex)),
+});
+function parseArgs(argv = process.argv.slice(2)) {
+    const config = runCli(cliParser, {
+        args: argv,
+        programName: "backend-tests",
+        help: "both",
+        aboveError: "usage",
+    });
+    return {
+        filters: config.matches,
+    };
+}

package/dist/time.d.ts

@@ -0,0 +1,118 @@
+import * as s from "./json/schema";
+import { type Maybe } from "./maybe";
+type Timezone = string;
+/** Date + time stored as milliseconds passed since 00:00:00 UTC on January 1, 1970. */
+declare class POSIX {
+    readonly value: number;
+    static fromDate(d: Date): POSIX;
+    static fromDuration(d: Duration): POSIX;
+    static now(): POSIX;
+    /** Takes number of milliseconds since epoch. */
+    constructor(value: number);
+    /** Time since Unix epoch (00:00:00 UTC on January 1, 1970). */
+    sinceEpoch(): Duration;
+    toDate(): Date;
+    isAfter(other: POSIX): boolean;
+    greaterThan(other: POSIX): boolean;
+    compare(other: POSIX): number;
+    addDuration(d: Duration): POSIX;
+    subtractDuration(d: Duration): POSIX;
+    difference(other: POSIX): Duration;
+    static fromLocalDateAndTime(date: DateOnly, time: TimeOfDay, timezone: Timezone): POSIX;
+    toUTCDateAndTime(): {
+        date: DateOnly;
+        time: TimeOfDay;
+    };
+    toLocalDateAndTime(timezone: Timezone): {
+        date: DateOnly;
+        time: TimeOfDay;
+    };
+    /** Parse PostgreSQL TIMESTAMPTZ string (e.g., "2026-03-17 10:30:00+00"). */
+    static fromSQLTimestamp(str: string): POSIX | null;
+    /** Convert to PostgreSQL TIMESTAMPTZ string. */
+    toSQLTimestamp(): string;
+    static schema: s.Schema<POSIX>;
+}
+declare class DateOnly {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    constructor(year: number, month: number, day: number);
+    static todayUTC(): DateOnly;
+    static todayLocal(timezone: Timezone): DateOnly;
+    static fromDate(date: Date): DateOnly;
+    pretty(): string;
+    static schema: s.Schema<DateOnly>;
+    greaterThan(other: DateOnly): boolean;
+    compare(other: DateOnly): number;
+    addMonths(months: number): DateOnly;
+}
+declare class TimeOfDay {
+    readonly seconds: number;
+    constructor(seconds: number);
+    static fromParts({ hours, minutes, seconds }: {
+        hours: number;
+        minutes: number;
+        seconds: number;
+    }): TimeOfDay;
+    pretty(): string;
+    getSubSecondPrecision(): number;
+}
+/** A length of time. */
+declare class Duration {
+    private readonly millis;
+    private constructor();
+    static milliseconds(n: number): Duration;
+    static seconds(n: number): Duration;
+    static minutes(n: number): Duration;
+    static hours(n: number): Duration;
+    static days(n: number): Duration;
+    static weeks(n: number): Duration;
+    asMilliseconds(): number;
+    asSeconds(): number;
+    asMinutes(): number;
+    asHours(): number;
+    asDays(): number;
+    asWeeks(): number;
+    add(other: Duration): Duration;
+    subtract(other: Duration): Duration;
+    multiplyBy(n: number): Duration;
+    divideBy(n: number): Duration;
+    greaterThan(other: Duration): boolean;
+    compare(other: Duration): number;
+    /** Quantisation. Divide a duration into buckets of a fixed length. */
+    bucketsOf(length: Duration): {
+        count: number;
+        remainderStart: Duration;
+        remainder: Duration;
+    };
+    /** Returns a non-negative duration. */
+    absolute(): Duration;
+    parts(): {
+        days: number;
+        hours: number;
+        minutes: number;
+        seconds: number;
+        milliseconds: number;
+    };
+    /** Formats duration as ISO-8601 string (e.g., "P1DT2H30M45.123S"). */
+    toISO8601(): string;
+    /**
+     * Formats a duration to a friendly, human readable string.  First argument (`verbosity`) can be
+     * either "short" (e.g. 1w 3d 5h 2m 0s 20ms) or long (e.g. 1 week, 3 days, 5 hours, 2 minutes, 20 milliseconds).
+     *
+     * Options allow for truncation after minutes or seconds.  Additionally, if the truncated duration would
+     * evaluate to zero but not _exactly_ zero (e.g. a duration of 20 seconds when truncated to minutes will
+     * result in 0m), there is an option `show_less_than_when_close_to_zero` which will prefix either "<" (short)
+     * or "less than" long in this case, which is recommended when users are actively "watching the clock".
+     */
+    toFormatted(verbosity: "short" | "long", options?: {
+        truncateAfter?: "minutes" | "seconds";
+        onTruncation?: "show_less_than_when_close_to_zero";
+    }): string;
+    /** Parses ISO-8601 duration string (e.g., "P1DT2H30M45.123S"). */
+    static fromISO8601(str: string): Maybe<Duration>;
+    /** Default: ISO-8601 string (standard, human-readable, interoperable). */
+    static schema: s.Schema<Duration>;
+}
+export { type Timezone, DateOnly, TimeOfDay, POSIX, Duration };