@davidsouther/jiffies 2026.4.1 → 2026.24.1

package/lib/esm/fs.d.ts

@@ -0,0 +1,72 @@
+export type PathLike = string;
+export interface PlatformParts {
+    SEP: string;
+    WD: string;
+    isAbsolute(path: PathLike): boolean;
+}
+export declare const PLATFORM_PARTS_WIN: PlatformParts;
+export declare const PLATFORM_PARTS_UNIX: PlatformParts;
+export declare const PLATFORM_PARTS: PlatformParts;
+export declare const SEP: string;
+export declare const WD: string;
+export declare const isAbsolute: (path: PathLike) => boolean;
+export interface Stats {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    name: string;
+}
+export declare function basename(filename: PathLike): string;
+export interface FileSystemAdapter {
+    stat(path: PathLike): Promise<Stats>;
+    readdir(path: PathLike): Promise<string[]>;
+    scandir(path: PathLike): Promise<Stats[]>;
+    mkdir(path: PathLike): Promise<void>;
+    copyFile(from: PathLike, to: PathLike): Promise<void>;
+    readFile(path: PathLike): Promise<string>;
+    writeFile(path: PathLike, contents: string): Promise<void>;
+    rm(path: PathLike): Promise<void>;
+}
+export declare class FileSystem implements FileSystemAdapter {
+    protected wd: string;
+    protected stack: string[];
+    protected adapter: FileSystemAdapter;
+    constructor(adapter?: FileSystemAdapter);
+    cwd(): string;
+    cd(dir: string): void;
+    pushd(dir: string): void;
+    popd(): void;
+    stat(path: PathLike): Promise<Stats>;
+    scandir(path: PathLike): Promise<Stats[]>;
+    readdir(path: PathLike): Promise<string[]>;
+    mkdir(path: string): Promise<void>;
+    copyFile(from: PathLike, to: PathLike): Promise<void>;
+    readFile(path: PathLike): Promise<string>;
+    writeFile(path: PathLike, contents: string): Promise<void>;
+    rm(path: PathLike): Promise<void>;
+    private p;
+}
+export declare class RecordFileSystemAdapter implements FileSystemAdapter {
+    private fs;
+    constructor(fs?: Record<string, string>);
+    stat(path: PathLike): Promise<Stats>;
+    scandir(path: PathLike): Promise<Stats[]>;
+    readdir(path: PathLike): Promise<string[]>;
+    mkdir(_path: string): Promise<void>;
+    copyFile(from: PathLike, to: PathLike): Promise<void>;
+    readFile(path: PathLike): Promise<string>;
+    writeFile(path: PathLike, contents: string): Promise<void>;
+    rm(path: PathLike): Promise<void>;
+}
+export declare class LocalStorageFileSystemAdapter extends RecordFileSystemAdapter {
+    constructor();
+}
+export type ObjectFileSystem = {
+    [k: string]: string | ObjectFileSystem;
+};
+export declare class ObjectFileSystemAdapter extends RecordFileSystemAdapter {
+    constructor(object: ObjectFileSystem);
+}
+export interface Tree {
+    [k: string]: string | Tree;
+}
+export declare function reset(fs: FileSystem, tree: Tree): Promise<void>;

package/lib/esm/fs.js

@@ -0,0 +1,227 @@
+import { assertExists } from "./assert.js";
+export const PLATFORM_PARTS_WIN = {
+    SEP: "\\",
+    WD: "C:\\\\",
+    isAbsolute: (path) => Boolean(path.match(/^[a-zA-Z]:\\/)),
+};
+export const PLATFORM_PARTS_UNIX = {
+    SEP: "/",
+    WD: "/",
+    isAbsolute: (path) => path[0] === "/",
+};
+export const PLATFORM_PARTS = typeof process !== "undefined" && process.platform === "win32"
+    ? PLATFORM_PARTS_WIN
+    : PLATFORM_PARTS_UNIX;
+export const SEP = PLATFORM_PARTS.SEP;
+export const WD = PLATFORM_PARTS.WD;
+export const isAbsolute = PLATFORM_PARTS.isAbsolute;
+export function basename(filename) {
+    if (filename.endsWith(SEP)) {
+        filename = filename.substring(0, filename.length - 1);
+    }
+    const basename = filename.split(SEP).at(-1) ?? "";
+    return basename;
+}
+function join(...paths) {
+    const pathParts = [];
+    for (const path of paths) {
+        for (const part of path.split(SEP)) {
+            switch (part) {
+                case "":
+                case ".":
+                    break;
+                case "..":
+                    pathParts.pop();
+                    break;
+                default:
+                    pathParts.push(part);
+            }
+        }
+    }
+    return ((PLATFORM_PARTS === PLATFORM_PARTS_UNIX ? SEP : "") + pathParts.join(SEP));
+}
+export class FileSystem {
+    wd = WD;
+    stack = [];
+    adapter;
+    constructor(adapter = new RecordFileSystemAdapter()) {
+        this.adapter = adapter;
+    }
+    cwd() {
+        return this.wd;
+    }
+    cd(dir) {
+        this.wd = this.p(dir);
+    }
+    pushd(dir) {
+        this.stack.push(this.wd);
+        this.cd(dir);
+    }
+    popd() {
+        if (this.stack.length > 0) {
+            this.wd = assertExists(this.stack.pop());
+        }
+    }
+    stat(path) {
+        return this.adapter.stat(this.p(path));
+    }
+    scandir(path) {
+        return this.adapter.scandir(this.p(path));
+    }
+    readdir(path) {
+        return this.adapter.readdir(this.p(path));
+    }
+    mkdir(path) {
+        return this.adapter.mkdir(this.p(path));
+    }
+    copyFile(from, to) {
+        return this.adapter.copyFile(this.p(from), this.p(to));
+    }
+    readFile(path) {
+        return this.adapter.readFile(this.p(path));
+    }
+    writeFile(path, contents) {
+        return this.adapter.writeFile(this.p(path), contents);
+    }
+    rm(path) {
+        return this.adapter.rm(this.p(path));
+    }
+    p(path) {
+        return isAbsolute(path) ? path : join(this.cwd(), path);
+    }
+}
+export class RecordFileSystemAdapter {
+    fs;
+    constructor(fs = {}) {
+        this.fs = fs;
+    }
+    stat(path) {
+        return new Promise((resolve, reject) => {
+            if (this.fs[path]) {
+                return resolve({
+                    name: basename(path),
+                    isDirectory() {
+                        return false;
+                    },
+                    isFile() {
+                        return true;
+                    },
+                });
+            }
+            if (!path.endsWith(SEP))
+                path += SEP;
+            for (const filename of Object.keys(this.fs)) {
+                if (filename.startsWith(path)) {
+                    return resolve({
+                        name: basename(path),
+                        isDirectory() {
+                            return true;
+                        },
+                        isFile() {
+                            return false;
+                        },
+                    });
+                }
+            }
+            reject();
+        });
+    }
+    async scandir(path) {
+        return (await this.readdir(path)).map((name) => {
+            const isFile = this.fs[join(path, name)] !== undefined;
+            return {
+                name,
+                isDirectory() {
+                    return !isFile;
+                },
+                isFile() {
+                    return isFile;
+                },
+            };
+        });
+    }
+    readdir(path) {
+        if (!path.endsWith(SEP))
+            path += SEP;
+        return new Promise((resolve) => {
+            const dir = new Set();
+            for (const filename of Object.keys(this.fs)) {
+                if (filename.startsWith(path)) {
+                    const end = filename.indexOf(SEP, path.length + 1);
+                    const basename = filename.substring(path.length, end === -1 ? undefined : end);
+                    dir.add(basename);
+                }
+            }
+            return resolve([...dir].sort());
+        });
+    }
+    mkdir(_path) {
+        return Promise.resolve();
+    }
+    copyFile(from, to) {
+        return new Promise((resolve) => {
+            this.fs[to] = this.fs[from];
+            resolve();
+        });
+    }
+    readFile(path) {
+        return new Promise((resolve, reject) => {
+            const file = this.fs[path];
+            if (file === undefined) {
+                const error = new Error(`File Not Found ${path}`);
+                reject(error);
+            }
+            else {
+                resolve(file);
+            }
+        });
+    }
+    writeFile(path, contents) {
+        return new Promise((resolve) => {
+            this.fs[path] = contents;
+            resolve();
+        });
+    }
+    rm(path) {
+        return new Promise((resolve) => {
+            delete this.fs[path];
+            resolve();
+        });
+    }
+}
+export class LocalStorageFileSystemAdapter extends RecordFileSystemAdapter {
+    constructor() {
+        super(window.localStorage);
+    }
+}
+export class ObjectFileSystemAdapter extends RecordFileSystemAdapter {
+    constructor(object) {
+        super(reduceObjectFileSystem(object));
+    }
+}
+function reduceObjectFileSystem(object) {
+    const level = {};
+    for (const [k, v] of Object.entries(object)) {
+        if (typeof v === "string") {
+            level[`/${k}`] = v;
+        }
+        else {
+            for (const [k2, v2] of Object.entries(reduceObjectFileSystem(v))) {
+                level[`/${k}${k2}`] = v2;
+            }
+        }
+    }
+    return level;
+}
+export async function reset(fs, tree) {
+    for (const [path, file] of Object.entries(tree)) {
+        if (typeof file === "string") {
+            await fs.writeFile(path, file);
+        }
+        else {
+            fs.cd(path);
+            await reset(fs, file);
+            fs.cd("..");
+        }
+    }
+}

package/lib/esm/fs_node.d.ts

@@ -0,0 +1,15 @@
+import { FileSystem, type FileSystemAdapter, type Stats } from "./fs.ts";
+export declare class NodeFileSystem extends FileSystem {
+    constructor(cd?: string);
+}
+/** Jiffies FileSystemAdapter using NodeJS' fs/promises. */
+export declare class NodeFileSystemAdapter implements FileSystemAdapter {
+    stat(path: string): Promise<Stats>;
+    readdir(path: string): Promise<string[]>;
+    mkdir(path: string): Promise<void>;
+    scandir(path: string): Promise<Stats[]>;
+    copyFile(from: string, to: string): Promise<void>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, contents: string): Promise<void>;
+    rm(path: string): Promise<void>;
+}

package/lib/esm/fs_node.js

@@ -0,0 +1,45 @@
+import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile, } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { FileSystem } from "./fs.js";
+export class NodeFileSystem extends FileSystem {
+    constructor(cd = process.cwd()) {
+        super(new NodeFileSystemAdapter());
+        this.cd(cd);
+    }
+}
+/** Jiffies FileSystemAdapter using NodeJS' fs/promises. */
+export class NodeFileSystemAdapter {
+    async stat(path) {
+        const fsStat = await stat(path);
+        return {
+            name: basename(path),
+            isDirectory() {
+                return fsStat.isDirectory();
+            },
+            isFile() {
+                return !fsStat.isDirectory();
+            },
+        };
+    }
+    readdir(path) {
+        return readdir(path);
+    }
+    async mkdir(path) {
+        await mkdir(path, { recursive: true });
+    }
+    async scandir(path) {
+        return Promise.all((await this.readdir(path)).map((name) => this.stat(join(path, name))));
+    }
+    copyFile(from, to) {
+        return copyFile(from, to);
+    }
+    readFile(path) {
+        return readFile(path, "utf-8");
+    }
+    writeFile(path, contents) {
+        return writeFile(path, contents, "utf-8");
+    }
+    rm(path) {
+        return rm(path, { force: true, recursive: true });
+    }
+}

package/lib/esm/generator.d.ts

@@ -0,0 +1 @@
+export declare function takeWhile<T>(predicate: (t: T) => boolean, iterator: Iterable<T>): Generator<T, void, unknown>;

package/lib/esm/generator.js

@@ -0,0 +1,10 @@
+export function* takeWhile(predicate, iterator) {
+    for (const x of iterator) {
+        if (predicate(x)) {
+            yield x;
+        }
+        else {
+            return;
+        }
+    }
+}

package/lib/esm/lock.d.ts

@@ -0,0 +1 @@
+export declare function lock<CF extends (...args: unknown[]) => unknown>(fn: CF): CF;

package/lib/esm/lock.js

@@ -0,0 +1,23 @@
+const locks = new WeakSet();
+export function lock(fn) {
+    const lockingFn = (...args) => {
+        let ret;
+        let ex = null;
+        if (!locks.has(fn)) {
+            locks.add(fn);
+            try {
+                ret = fn(...args);
+            }
+            catch (e) {
+                ex = e;
+            }
+        }
+        locks.delete(fn);
+        if (ex !== null) {
+            throw ex;
+        }
+        // @ts-expect-error 2454 can't track ret's assignment
+        return ret;
+    };
+    return lockingFn;
+}

package/lib/esm/log.d.ts

@@ -0,0 +1,69 @@
+import { type Display } from "./display.ts";
+export type Log = (message: Display, data?: object) => void;
+export interface Logger {
+    logAt: (level: number, prefix: string, fn?: (logLine: string) => void) => Log;
+    level: number;
+    format: <D extends {
+        name: string;
+        prefix: string;
+        level: number;
+        message: string;
+        source: string;
+    }>(data: D) => string;
+    console: Console;
+    default: (logLine: string) => void;
+    debug: Log;
+    info: Log;
+    warn: Log;
+    error: Log;
+}
+export declare const LEVEL: {
+    UNKNOWN: number;
+    DEBUG: number;
+    VERBOSE: number;
+    INFO: number;
+    WARN: number;
+    ERROR: number;
+    SILENT: number;
+};
+export declare const LEVELS: Record<string, number>;
+export declare function getLogLevel(level?: string): number;
+export declare function basicLogFormatter(data: {
+    name: string;
+    prefix: string;
+    level: number;
+    message: string;
+    source: string;
+}): string;
+export type LoggerFormatFn = <D extends {
+    name: string;
+    prefix: string;
+    level: number;
+    message: string;
+    source: string;
+}>(data: D) => string;
+export interface PrettyLogOptions {
+    /** Render colored, human-shaped lines. Default: !!process.stdout.isTTY. */
+    tty?: boolean;
+    /** Emit ANSI color escapes. Default: same as `tty`. */
+    color?: boolean;
+    /** Injectable clock for deterministic timestamps in tests. Default: new Date. */
+    now?: () => Date;
+}
+/**
+ * Factory returning a {@link LoggerFormatFn} that is pretty + colored on a TTY
+ * and falls back to `JSON.stringify` when not. Options resolve once at
+ * construction (`tty` reads `process.stdout.isTTY`), so production piped output
+ * stays JSON; tests inject `tty`/`color`/`now` for a deterministic colorless
+ * layout assertable without a real terminal.
+ */
+export declare function prettyLogFormatter(options?: PrettyLogOptions): LoggerFormatFn;
+export declare function getLogger(name: string, args?: LoggerFormatFn | {
+    format?: LoggerFormatFn;
+    console?: Console;
+}): Logger;
+export declare const DEFAULT_LOGGER: Logger;
+export declare function debug(message: Display, data?: object): void;
+export declare function info(message: Display, data?: object): void;
+export declare function warn(message: Display, data?: object): void;
+export declare function error(message: Display, data?: object): void;

package/lib/esm/log.js

@@ -0,0 +1,211 @@
+import { display } from "./display.js";
+export const LEVEL = {
+    UNKNOWN: 2,
+    DEBUG: 1,
+    VERBOSE: 1,
+    INFO: 2,
+    WARN: 3,
+    ERROR: 4,
+    SILENT: 5,
+};
+export const LEVELS = {
+    unknown: LEVEL.UNKNOWN,
+    debug: LEVEL.DEBUG,
+    verbose: LEVEL.VERBOSE,
+    info: LEVEL.INFO,
+    warn: LEVEL.WARN,
+    error: LEVEL.ERROR,
+    silent: LEVEL.SILENT,
+};
+export function getLogLevel(level = "") {
+    return (LEVELS[level.toLowerCase()] ??
+        (!Number.isNaN(+level) ? Number(level) : LEVEL.INFO));
+}
+export function basicLogFormatter(data) {
+    return `${data.prefix}: ${data.message}`;
+}
+function findSource() {
+    const err = new Error();
+    // Stack will be:
+    // findSource
+    // logAt
+    // {source}
+    const lines = err.stack?.split("\n") ?? [];
+    const atLines = lines.filter((line) => line.match(/^\s*at/));
+    return atLines[2]?.trim().slice("at ".length) ?? "(unknown)";
+}
+// ── prettyLogFormatter ──────────────────────────────────────────────────────
+// A TTY-aware formatter: compact, color-and-glyph-coded human lines on a
+// terminal, byte-identical JSON.stringify when piped/redirected so machine
+// tooling is unchanged. See docs/developer/2026-06-09-A-log-formatter/design.md.
+// Raw ANSI escapes; no color/log runtime dependency in this library.
+const ANSI = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+};
+// HH:MM:SS.mmm sliced from a UTC ISO 8601 string. Timezone-stable by
+// construction: it never reads local-time accessors, so output depends only on
+// the ISO input, not the runner's TZ.
+function shortClock(iso) {
+    return iso.slice(11, 23);
+}
+// Glyph + color per severity, keyed on the numeric level (DEBUG 1, INFO 2,
+// WARN 3, ERROR 4). Fixed single-column glyph so messages align vertically.
+function levelGlyph(level) {
+    if (level <= LEVEL.DEBUG)
+        return { glyph: "·", color: "dim" };
+    if (level === LEVEL.INFO)
+        return { glyph: "ℹ", color: "green" };
+    if (level === LEVEL.WARN)
+        return { glyph: "⚠", color: "yellow" };
+    return { glyph: "✖", color: "red" };
+}
+function methodColor(method) {
+    switch (method) {
+        case "GET":
+            return "cyan";
+        case "POST":
+            return "green";
+        case "PUT":
+        case "PATCH":
+            return "yellow";
+        case "DELETE":
+            return "red";
+        default:
+            return "white";
+    }
+}
+function statusColor(status) {
+    if (status >= 500)
+        return "red";
+    if (status >= 400)
+        return "yellow";
+    if (status >= 300)
+        return "cyan";
+    return "green";
+}
+// Fields that are pure metadata noise on a human terminal: `name`/`level` are
+// constant or duplicate `prefix`, and `source` resolves to the info() wrapper.
+// `message` is rendered on its own, never echoed into the trailing tail.
+const HUMAN_DROP = new Set(["name", "prefix", "level", "source", "message"]);
+/**
+ * Factory returning a {@link LoggerFormatFn} that is pretty + colored on a TTY
+ * and falls back to `JSON.stringify` when not. Options resolve once at
+ * construction (`tty` reads `process.stdout.isTTY`), so production piped output
+ * stays JSON; tests inject `tty`/`color`/`now` for a deterministic colorless
+ * layout assertable without a real terminal.
+ */
+export function prettyLogFormatter(options = {}) {
+    const tty = options.tty ?? !!process.stdout.isTTY;
+    const color = options.color ?? tty;
+    const now = options.now ?? (() => new Date());
+    const paint = (code, s) => color ? `${ANSI[code]}${s}${ANSI.reset}` : s;
+    return (data) => {
+        if (!tty)
+            return JSON.stringify(data);
+        const record = data;
+        const { glyph, color: glyphColor } = levelGlyph(data.level);
+        const mark = paint(glyphColor, glyph);
+        // Access-log shape: `<glyph> <clock> <METHOD> <path> <client> [status] [ms]`.
+        // Clock comes from the request's `when` ISO (UTC slice), not now().
+        if (data.message === "Request") {
+            const when = typeof record.when === "string" ? record.when : "";
+            const how = typeof record.how === "string" ? record.how : "";
+            const space = how.indexOf(" ");
+            const method = space === -1 ? how : how.slice(0, space);
+            const path = space === -1 ? "" : how.slice(space + 1);
+            const segments = [
+                mark,
+                paint("dim", shortClock(when || now().toISOString())),
+                paint(methodColor(method), method),
+                paint("bold", path),
+            ];
+            if (record.who !== undefined) {
+                segments.push(paint("dim", String(record.who)));
+            }
+            if (record.status !== undefined) {
+                segments.push(paint(statusColor(Number(record.status)), String(record.status)));
+            }
+            if (record.ms !== undefined) {
+                segments.push(paint("dim", `${record.ms}ms`));
+            }
+            return segments.filter((s) => s !== "").join(" ");
+        }
+        // Generic shape: `<glyph> <clock> <message> <dim key=value …>`.
+        const tail = Object.entries(record)
+            .filter(([key]) => !HUMAN_DROP.has(key))
+            .map(([key, value]) => paint("dim", `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`));
+        return [
+            mark,
+            paint("dim", shortClock(now().toISOString())),
+            paint("bold", data.message),
+            ...tail,
+        ].join(" ");
+    };
+}
+export function getLogger(name, args = {
+    format: JSON.stringify,
+    console,
+}) {
+    if (args instanceof Function) {
+        args = { format: args };
+    }
+    const defaultLog = (logLine) => {
+        logger.console.info(logLine);
+    };
+    const logAt = (level, prefix, fn = defaultLog) => (message, data) => level >= (logger.level ?? LEVEL.SILENT)
+        ? fn(logger.format?.({
+            name,
+            prefix,
+            level,
+            message: display(message),
+            ...data,
+            source: findSource(),
+        }))
+        : undefined;
+    const logger = {
+        logAt,
+        default: defaultLog,
+        level: LEVEL.INFO,
+        format: args.format ?? JSON.stringify,
+        console: args.console ?? global.console,
+        debug: logAt(LEVEL.DEBUG, "DEBUG", (l) => logger.console.debug(l)),
+        info: logAt(LEVEL.INFO, "INFO", (l) => logger.console.info(l)),
+        warn: logAt(LEVEL.WARN, "WARN", (l) => logger.console.warn(l)),
+        error: logAt(LEVEL.ERROR, "ERR", (l) => logger.console.error(l)),
+    };
+    return logger;
+}
+export const DEFAULT_LOGGER = getLogger("default", {
+    format: prettyLogFormatter(),
+});
+export function debug(message, data) {
+    if (data)
+        DEFAULT_LOGGER.debug(message, data);
+    else
+        DEFAULT_LOGGER.debug(message);
+}
+export function info(message, data) {
+    if (data)
+        DEFAULT_LOGGER.info(message, data);
+    else
+        DEFAULT_LOGGER.info(message);
+}
+export function warn(message, data) {
+    if (data)
+        DEFAULT_LOGGER.warn(message, data);
+    else
+        DEFAULT_LOGGER.warn(message);
+}
+export function error(message, data) {
+    if (data)
+        DEFAULT_LOGGER.error(message, data);
+    else
+        DEFAULT_LOGGER.error(message);
+}