@adecore/utils 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 - present Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @adecore/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small helpers without dependencies: atomic file writes, path containment, the order of async work and reading a thrown value. Each lives at its own subpath; `async`, `errors` and `record` run in a page, `fs` and `path` need Node or Bun.
+
+```sh
+bun add @adecore/utils
+```
+
+Licensed under FSL-1.1-MIT, see [LICENSE](./LICENSE).
+
+```ts
+import { writeAtomic } from '@adecore/utils/fs';
+import { isBelow } from '@adecore/utils/path';
+
+if (isBelow(folder, target)) {
+    await writeAtomic(target, JSON.stringify(state), 0o600, { durable: true });
+}
+```
+
+`isBelow` compares text and reads nothing from the disk. Resolve real paths first when a link could lead out of the folder.
+
+Read the [overview](https://adecore.dev/utils/).

package/dist/async.d.ts

@@ -0,0 +1,12 @@
+export { KeyedSerializer, Serializer } from './serializer.ts';
+export { SingleFlight } from './single-flight.ts';
+export declare function wait(ms: number, signal?: AbortSignal): Promise<void>;
+export interface DeadlineTimer {
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare function withDeadline<T>(promise: Promise<T>, ms: number, message: string, timer?: DeadlineTimer): Promise<T>;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T>;
+export type Timer = (ms: number, run: () => void) => () => void;
+export declare const cancellableTimeout: Timer;
+export declare const unrefTimeout: Timer;

package/dist/async.js

@@ -0,0 +1,46 @@
+import { asError } from './errors.js';
+export { KeyedSerializer, Serializer } from './serializer.js';
+export { SingleFlight } from './single-flight.js';
+/*
+ * Resolves after `ms`, or at once when the signal is raised. An abort resolves instead of rejecting:
+ * every caller is a loop that checks the signal itself on its next turn.
+ */
+export function wait(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+const SYSTEM_TIMER = {
+    setTimeout: (run, ms) => setTimeout(run, ms),
+    clearTimeout: (handle) => clearTimeout(handle)
+};
+/* The timer is cleared either way, so a call that answers at once does not hold the process until its deadline. */
+export function withDeadline(promise, ms, message, timer = SYSTEM_TIMER) {
+    return new Promise((resolve, reject) => {
+        const handle = timer.setTimeout(() => reject(new Error(message)), ms);
+        promise.then((value) => {
+            timer.clearTimeout(handle);
+            resolve(value);
+        }, (e) => {
+            timer.clearTimeout(handle);
+            reject(asError(e));
+        });
+    });
+}
+export function withTimeout(promise, ms, message) {
+    return withDeadline(promise, ms, message);
+}
+export const cancellableTimeout = (ms, run) => {
+    const timer = setTimeout(run, ms);
+    return () => clearTimeout(timer);
+};
+/* The same, without holding the process open for it. */
+export const unrefTimeout = (ms, run) => {
+    const timer = setTimeout(run, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+};

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare function hasErrorCode(e: unknown, ...codes: string[]): boolean;
+export declare function isNotFound(e: unknown): boolean;
+export declare function describeError(error: unknown, debug: boolean): string;
+export declare function asError(thrown: unknown): Error;

package/dist/errors.js

@@ -0,0 +1,29 @@
+/*
+ * How a thrown value is read. These helpers use no platform API, so a page imports them as well as a
+ * process. A message for a person to read and a host-wide choice to print stacks stay with their owners.
+ */
+/* Whether `e` carries one of `codes` as its `code`, the way Node and Bun mark a system error. */
+export function hasErrorCode(e, ...codes) {
+    return typeof e === 'object' && e !== null && 'code' in e && codes.includes(e.code);
+}
+export function isNotFound(e) {
+    return hasErrorCode(e, 'ENOENT');
+}
+/*
+ * The message of an error, or its whole stack with `debug` set. Bun prints an Error object handed to the
+ * console with a code frame of the bundle it came from, which in a compiled binary is a few lines of
+ * minified source, so an error is turned into a string first.
+ */
+export function describeError(error, debug) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    if (debug) {
+        return error.stack ?? `${error.name}: ${error.message}`;
+    }
+    return error.message === '' ? error.name : error.message;
+}
+/* What was thrown, as an Error a rejection can carry. */
+export function asError(thrown) {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}

package/dist/fs.d.ts

@@ -0,0 +1,14 @@
+export declare function isBusyRename(e: unknown): boolean;
+export declare function tempNameFor(target: string): string;
+export interface WriteAtomicOptions {
+    durable?: boolean;
+}
+export declare function syncDirectory(path: string): Promise<void>;
+export declare function writeAtomic(target: string, content: string | Uint8Array, mode?: number, options?: WriteAtomicOptions): Promise<void>;
+export declare function replaceSync(temp: string, target: string, rename?: (from: string, to: string) => void): void;
+export declare function writeAtomicSync(target: string, content: string | Uint8Array, mode?: number): void;
+export declare function removeFile(path: string, remove?: (path: string, options: {
+    force: true;
+}) => Promise<void>): Promise<void>;
+export declare function fileExists(path: string): Promise<boolean>;
+export declare function entryExists(path: string): Promise<boolean>;

package/dist/fs.js

@@ -0,0 +1,161 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, openSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { lstat, open, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { wait } from './async.js';
+import { hasErrorCode } from './errors.js';
+// Windows can refuse a rename while a watcher or an indexer holds the target; a few short retries cover it.
+const RENAME_RETRIES = 5;
+const RENAME_RETRY_MS = 40;
+// Node has no synchronous sleep; a wait on a value nobody changes is one.
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/* Whether a rename failed because another process holds the file open for a moment, as Windows reports it. */
+export function isBusyRename(e) {
+    return hasErrorCode(e, 'EPERM', 'EBUSY', 'EACCES');
+}
+/* A temporary name is still opened exclusively: an unpredictable name alone cannot protect a write. */
+export function tempNameFor(target) {
+    return `${target}.${process.pid}-${randomUUID()}.tmp`;
+}
+async function createTemp(target, mode) {
+    for (let attempt = 0;; attempt++) {
+        const path = tempNameFor(target);
+        try {
+            return { path, handle: await open(path, 'wx', mode) };
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EEXIST') || attempt >= 31) {
+                throw error;
+            }
+        }
+    }
+}
+// Windows cannot open a directory to flush it, and NTFS journals the rename itself.
+export async function syncDirectory(path) {
+    if (process.platform === 'win32') {
+        return;
+    }
+    const handle = await open(path, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/*
+ * A crash between the two steps leaves a stray temp file, never a half-written file. That holds for
+ * a process that dies; after a power cut APFS and ext4 can still hold an empty target, unless the
+ * write is durable.
+ */
+export async function writeAtomic(target, content, mode = 0o600, options = {}) {
+    const { path: temp, handle } = await createTemp(target, mode);
+    try {
+        try {
+            await handle.writeFile(content);
+            if (options.durable) {
+                await handle.sync();
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        for (let attempt = 0;; attempt++) {
+            try {
+                await rename(temp, target);
+                break;
+            }
+            catch (e) {
+                if (!isBusyRename(e) || attempt >= RENAME_RETRIES) {
+                    throw e;
+                }
+                await wait(RENAME_RETRY_MS);
+            }
+        }
+        if (options.durable) {
+            await syncDirectory(dirname(target));
+        }
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+/*
+ * The same rename, without a turn of the event loop. A `bun --watch` reload restarts a module before
+ * an awaited write comes back, and an exit path is gone before one lands, so what has to be on disk
+ * before the process turns around goes through here.
+ */
+export function replaceSync(temp, target, rename = renameSync) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            rename(temp, target);
+            return;
+        }
+        catch (e) {
+            if (!isBusyRename(e) || attempt >= RENAME_RETRIES) {
+                throw e;
+            }
+            sleepSync(RENAME_RETRY_MS);
+        }
+    }
+}
+export function writeAtomicSync(target, content, mode = 0o600) {
+    for (let attempt = 0;; attempt++) {
+        const temp = tempNameFor(target);
+        let descriptor;
+        try {
+            descriptor = openSync(temp, 'wx', mode);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'EEXIST') && attempt < 31) {
+                continue;
+            }
+            throw error;
+        }
+        try {
+            try {
+                writeFileSync(descriptor, content);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+            replaceSync(temp, target);
+            return;
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+}
+// Bun on Windows fails a forced rm with EFAULT while another delete of the same file is pending; it goes either way.
+export async function removeFile(path, remove = rm) {
+    try {
+        await remove(path, { force: true });
+    }
+    catch (e) {
+        if (!hasErrorCode(e, 'EFAULT')) {
+            throw e;
+        }
+    }
+}
+export async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/* Whether anything is at the path, a link that leads nowhere included, where `fileExists` follows the link. */
+export async function entryExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/path.d.ts

@@ -0,0 +1,3 @@
+export declare function climbsOut(rel: string): boolean;
+export declare function isWithin(folder: string, path: string): boolean;
+export declare function isBelow(folder: string, path: string): boolean;

package/dist/path.js

@@ -0,0 +1,20 @@
+import { isAbsolute, relative, sep } from 'node:path';
+/*
+ * Where one path lies against another, compared as text after `path.relative` resolved and normalized
+ * both, with the platform's separator, drive letters and case rules. Nothing here reads the disk, so a
+ * symbolic link inside the folder still counts as inside: a caller that serves or writes a file checks
+ * its real path or holds a handle on it.
+ */
+/* Whether a path `relative` gave leaves the folder it was taken from; a name such as `..cache` does not. */
+export function climbsOut(rel) {
+    return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+/* Whether `path` is `folder` or lies below it. */
+export function isWithin(folder, path) {
+    return !climbsOut(relative(folder, path));
+}
+/* Whether `path` lies below `folder`, the folder itself not counted. */
+export function isBelow(folder, path) {
+    const rel = relative(folder, path);
+    return rel !== '' && !climbsOut(rel);
+}

package/dist/record.d.ts

@@ -0,0 +1 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/record.js

@@ -0,0 +1,4 @@
+/* A plain object read off the wire or a file, whose fields are still unchecked; an array is not one. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/serializer.d.ts

@@ -0,0 +1,10 @@
+export declare class Serializer {
+    private chain;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    idle(): Promise<void>;
+}
+export declare class KeyedSerializer {
+    private readonly chains;
+    get size(): number;
+    run<T>(key: string, work: () => Promise<T>): Promise<T>;
+}

package/dist/serializer.js

@@ -0,0 +1,38 @@
+/*
+ * One writer at a time: the next piece of work starts once the one before it settled, whether that
+ * one kept its promise or not, and every caller hears its own result. Two changes in a row never
+ * read the same file and drop one of them.
+ */
+export class Serializer {
+    chain = Promise.resolve();
+    run(work) {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => undefined);
+        return next;
+    }
+    /* Resolves once what is queued has settled, without adding work of its own. */
+    idle() {
+        return this.chain.then(() => undefined, () => undefined);
+    }
+}
+/* The same per key, for a store whose records are written one by one and never wait on each other. */
+export class KeyedSerializer {
+    chains = new Map();
+    /* How many keys still have work queued or running. */
+    get size() {
+        return this.chains.size;
+    }
+    run(key, work) {
+        const previous = this.chains.get(key) ?? Promise.resolve();
+        const next = previous.then(work, work);
+        const settled = next.catch(() => undefined);
+        this.chains.set(key, settled);
+        // A key whose chain ran out leaves nothing behind, or the map grows with every id ever written.
+        void settled.then(() => {
+            if (this.chains.get(key) === settled) {
+                this.chains.delete(key);
+            }
+        });
+        return next;
+    }
+}

package/dist/single-flight.d.ts

@@ -0,0 +1,6 @@
+export declare class SingleFlight<T> {
+    private readonly flights;
+    get(key: string): Promise<T> | undefined;
+    has(key: string): boolean;
+    run(key: string, work: () => Promise<T>): Promise<T>;
+}

package/dist/single-flight.js

@@ -0,0 +1,27 @@
+/*
+ * Work that runs once per key at a time: a caller that asks while it runs shares its outcome, and
+ * a key that settled leaves nothing behind.
+ */
+export class SingleFlight {
+    flights = new Map();
+    /* The run in flight for `key`, if any. */
+    get(key) {
+        return this.flights.get(key);
+    }
+    has(key) {
+        return this.flights.has(key);
+    }
+    run(key, work) {
+        const running = this.flights.get(key);
+        if (running !== undefined) {
+            return running;
+        }
+        const flight = work().finally(() => {
+            if (this.flights.get(key) === flight) {
+                this.flights.delete(key);
+            }
+        });
+        this.flights.set(key, flight);
+        return flight;
+    }
+}

package/dist/text.d.ts

@@ -0,0 +1,2 @@
+export declare function isHighSurrogate(code: number): boolean;
+export declare function isLowSurrogate(code: number): boolean;

package/dist/text.js

@@ -0,0 +1,8 @@
+/* The first half of a surrogate pair, a UTF-16 code unit that cannot stand alone. */
+export function isHighSurrogate(code) {
+    return code >= 0xd800 && code <= 0xdbff;
+}
+/* The second half of a surrogate pair. */
+export function isLowSurrogate(code) {
+    return code >= 0xdc00 && code <= 0xdfff;
+}

package/package.json

@@ -1,6 +1,65 @@
 {
-  "name": "@adecore/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@adecore/utils",
+    "version": "0.0.1",
+    "description": "Small helpers without dependencies: atomic file writes, path containment, async ordering and error reading.",
+    "license": "FSL-1.1-MIT",
+    "author": "Bas Milius",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/basmilius/adecore.git",
+        "directory": "packages/utils"
+    },
+    "bugs": {
+        "url": "https://github.com/basmilius/adecore/issues"
+    },
+    "homepage": "https://adecore.dev/utils/",
+    "type": "module",
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "src",
+        "!src/**/*.test.ts"
+    ],
+    "exports": {
+        "./async": {
+            "source": "./src/async.ts",
+            "types": "./dist/async.d.ts",
+            "default": "./dist/async.js"
+        },
+        "./errors": {
+            "source": "./src/errors.ts",
+            "types": "./dist/errors.d.ts",
+            "default": "./dist/errors.js"
+        },
+        "./fs": {
+            "source": "./src/fs.ts",
+            "types": "./dist/fs.d.ts",
+            "default": "./dist/fs.js"
+        },
+        "./path": {
+            "source": "./src/path.ts",
+            "types": "./dist/path.d.ts",
+            "default": "./dist/path.js"
+        },
+        "./record": {
+            "source": "./src/record.ts",
+            "types": "./dist/record.d.ts",
+            "default": "./dist/record.js"
+        },
+        "./text": {
+            "source": "./src/text.ts",
+            "types": "./dist/text.d.ts",
+            "default": "./dist/text.js"
+        }
+    },
+    "scripts": {
+        "build": "bun scripts/build.ts",
+        "typecheck": "bun check --no-script",
+        "test": "bun test --conditions=source"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.4.4",
+        "@types/node": "^26.6.6",
+        "typescript": "^7.0.2"
+    }
+}

package/src/async.ts

@@ -0,0 +1,72 @@
+import { asError } from './errors.ts';
+
+export { KeyedSerializer, Serializer } from './serializer.ts';
+export { SingleFlight } from './single-flight.ts';
+
+/*
+ * Resolves after `ms`, or at once when the signal is raised. An abort resolves instead of rejecting:
+ * every caller is a loop that checks the signal itself on its next turn.
+ */
+export function wait(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+
+        signal?.addEventListener(
+            'abort',
+            () => {
+                clearTimeout(timer);
+                resolve();
+            },
+            { once: true }
+        );
+    });
+}
+
+export interface DeadlineTimer {
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+
+const SYSTEM_TIMER: DeadlineTimer = {
+    setTimeout: (run, ms) => setTimeout(run, ms),
+    clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>)
+};
+
+/* The timer is cleared either way, so a call that answers at once does not hold the process until its deadline. */
+export function withDeadline<T>(promise: Promise<T>, ms: number, message: string, timer: DeadlineTimer = SYSTEM_TIMER): Promise<T> {
+    return new Promise((resolve, reject) => {
+        const handle = timer.setTimeout(() => reject(new Error(message)), ms);
+
+        promise.then(
+            (value) => {
+                timer.clearTimeout(handle);
+                resolve(value);
+            },
+            (e: unknown) => {
+                timer.clearTimeout(handle);
+                reject(asError(e));
+            }
+        );
+    });
+}
+
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+    return withDeadline(promise, ms, message);
+}
+
+/* Runs `run` after `ms` and answers how to call it off. */
+export type Timer = (ms: number, run: () => void) => () => void;
+
+export const cancellableTimeout: Timer = (ms, run) => {
+    const timer = setTimeout(run, ms);
+
+    return () => clearTimeout(timer);
+};
+
+/* The same, without holding the process open for it. */
+export const unrefTimeout: Timer = (ms, run) => {
+    const timer = setTimeout(run, ms);
+    timer.unref?.();
+
+    return () => clearTimeout(timer);
+};

package/src/errors.ts

@@ -0,0 +1,35 @@
+/*
+ * How a thrown value is read. These helpers use no platform API, so a page imports them as well as a
+ * process. A message for a person to read and a host-wide choice to print stacks stay with their owners.
+ */
+
+/* Whether `e` carries one of `codes` as its `code`, the way Node and Bun mark a system error. */
+export function hasErrorCode(e: unknown, ...codes: string[]): boolean {
+    return typeof e === 'object' && e !== null && 'code' in e && codes.includes(e.code as string);
+}
+
+export function isNotFound(e: unknown): boolean {
+    return hasErrorCode(e, 'ENOENT');
+}
+
+/*
+ * The message of an error, or its whole stack with `debug` set. Bun prints an Error object handed to the
+ * console with a code frame of the bundle it came from, which in a compiled binary is a few lines of
+ * minified source, so an error is turned into a string first.
+ */
+export function describeError(error: unknown, debug: boolean): string {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+
+    if (debug) {
+        return error.stack ?? `${error.name}: ${error.message}`;
+    }
+
+    return error.message === '' ? error.name : error.message;
+}
+
+/* What was thrown, as an Error a rejection can carry. */
+export function asError(thrown: unknown): Error {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}

package/src/fs.ts

@@ -0,0 +1,184 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, openSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { lstat, open, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { wait } from './async.ts';
+import { hasErrorCode } from './errors.ts';
+
+// Windows can refuse a rename while a watcher or an indexer holds the target; a few short retries cover it.
+const RENAME_RETRIES = 5;
+const RENAME_RETRY_MS = 40;
+
+// Node has no synchronous sleep; a wait on a value nobody changes is one.
+function sleepSync(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/* Whether a rename failed because another process holds the file open for a moment, as Windows reports it. */
+export function isBusyRename(e: unknown): boolean {
+    return hasErrorCode(e, 'EPERM', 'EBUSY', 'EACCES');
+}
+
+/* A temporary name is still opened exclusively: an unpredictable name alone cannot protect a write. */
+export function tempNameFor(target: string): string {
+    return `${target}.${process.pid}-${randomUUID()}.tmp`;
+}
+
+export interface WriteAtomicOptions {
+    /* Flushed to the disk before and after the rename, for a file whose loss costs a person their work. */
+    durable?: boolean;
+}
+
+async function createTemp(target: string, mode: number) {
+    for (let attempt = 0; ; attempt++) {
+        const path = tempNameFor(target);
+
+        try {
+            return { path, handle: await open(path, 'wx', mode) };
+        } catch (error) {
+            if (!hasErrorCode(error, 'EEXIST') || attempt >= 31) {
+                throw error;
+            }
+        }
+    }
+}
+
+// Windows cannot open a directory to flush it, and NTFS journals the rename itself.
+export async function syncDirectory(path: string): Promise<void> {
+    if (process.platform === 'win32') {
+        return;
+    }
+
+    const handle = await open(path, 'r');
+
+    try {
+        await handle.sync();
+    } finally {
+        await handle.close();
+    }
+}
+
+/*
+ * A crash between the two steps leaves a stray temp file, never a half-written file. That holds for
+ * a process that dies; after a power cut APFS and ext4 can still hold an empty target, unless the
+ * write is durable.
+ */
+export async function writeAtomic(target: string, content: string | Uint8Array, mode = 0o600, options: WriteAtomicOptions = {}): Promise<void> {
+    const { path: temp, handle } = await createTemp(target, mode);
+
+    try {
+        try {
+            await handle.writeFile(content);
+
+            if (options.durable) {
+                await handle.sync();
+            }
+        } finally {
+            await handle.close();
+        }
+
+        for (let attempt = 0; ; attempt++) {
+            try {
+                await rename(temp, target);
+
+                break;
+            } catch (e) {
+                if (!isBusyRename(e) || attempt >= RENAME_RETRIES) {
+                    throw e;
+                }
+
+                await wait(RENAME_RETRY_MS);
+            }
+        }
+
+        if (options.durable) {
+            await syncDirectory(dirname(target));
+        }
+    } finally {
+        await rm(temp, { force: true });
+    }
+}
+
+/*
+ * The same rename, without a turn of the event loop. A `bun --watch` reload restarts a module before
+ * an awaited write comes back, and an exit path is gone before one lands, so what has to be on disk
+ * before the process turns around goes through here.
+ */
+export function replaceSync(temp: string, target: string, rename: (from: string, to: string) => void = renameSync): void {
+    for (let attempt = 0; ; attempt++) {
+        try {
+            rename(temp, target);
+
+            return;
+        } catch (e) {
+            if (!isBusyRename(e) || attempt >= RENAME_RETRIES) {
+                throw e;
+            }
+
+            sleepSync(RENAME_RETRY_MS);
+        }
+    }
+}
+
+export function writeAtomicSync(target: string, content: string | Uint8Array, mode = 0o600): void {
+    for (let attempt = 0; ; attempt++) {
+        const temp = tempNameFor(target);
+        let descriptor: number;
+
+        try {
+            descriptor = openSync(temp, 'wx', mode);
+        } catch (error) {
+            if (hasErrorCode(error, 'EEXIST') && attempt < 31) {
+                continue;
+            }
+
+            throw error;
+        }
+
+        try {
+            try {
+                writeFileSync(descriptor, content);
+            } finally {
+                closeSync(descriptor);
+            }
+
+            replaceSync(temp, target);
+
+            return;
+        } finally {
+            rmSync(temp, { force: true });
+        }
+    }
+}
+
+// Bun on Windows fails a forced rm with EFAULT while another delete of the same file is pending; it goes either way.
+export async function removeFile(path: string, remove: (path: string, options: { force: true }) => Promise<void> = rm): Promise<void> {
+    try {
+        await remove(path, { force: true });
+    } catch (e) {
+        if (!hasErrorCode(e, 'EFAULT')) {
+            throw e;
+        }
+    }
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+    try {
+        await stat(path);
+
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/* Whether anything is at the path, a link that leads nowhere included, where `fileExists` follows the link. */
+export async function entryExists(path: string): Promise<boolean> {
+    try {
+        await lstat(path);
+
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/path.ts

@@ -0,0 +1,25 @@
+import { isAbsolute, relative, sep } from 'node:path';
+
+/*
+ * Where one path lies against another, compared as text after `path.relative` resolved and normalized
+ * both, with the platform's separator, drive letters and case rules. Nothing here reads the disk, so a
+ * symbolic link inside the folder still counts as inside: a caller that serves or writes a file checks
+ * its real path or holds a handle on it.
+ */
+
+/* Whether a path `relative` gave leaves the folder it was taken from; a name such as `..cache` does not. */
+export function climbsOut(rel: string): boolean {
+    return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
+/* Whether `path` is `folder` or lies below it. */
+export function isWithin(folder: string, path: string): boolean {
+    return !climbsOut(relative(folder, path));
+}
+
+/* Whether `path` lies below `folder`, the folder itself not counted. */
+export function isBelow(folder: string, path: string): boolean {
+    const rel = relative(folder, path);
+
+    return rel !== '' && !climbsOut(rel);
+}

package/src/record.ts

@@ -0,0 +1,4 @@
+/* A plain object read off the wire or a file, whose fields are still unchecked; an array is not one. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/serializer.ts

@@ -0,0 +1,49 @@
+/*
+ * One writer at a time: the next piece of work starts once the one before it settled, whether that
+ * one kept its promise or not, and every caller hears its own result. Two changes in a row never
+ * read the same file and drop one of them.
+ */
+export class Serializer {
+    private chain: Promise<unknown> = Promise.resolve();
+
+    run<T>(work: () => Promise<T>): Promise<T> {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => undefined);
+
+        return next;
+    }
+
+    /* Resolves once what is queued has settled, without adding work of its own. */
+    idle(): Promise<void> {
+        return this.chain.then(
+            () => undefined,
+            () => undefined
+        );
+    }
+}
+
+/* The same per key, for a store whose records are written one by one and never wait on each other. */
+export class KeyedSerializer {
+    private readonly chains = new Map<string, Promise<unknown>>();
+
+    /* How many keys still have work queued or running. */
+    get size(): number {
+        return this.chains.size;
+    }
+
+    run<T>(key: string, work: () => Promise<T>): Promise<T> {
+        const previous = this.chains.get(key) ?? Promise.resolve();
+        const next = previous.then(work, work);
+        const settled = next.catch(() => undefined);
+        this.chains.set(key, settled);
+
+        // A key whose chain ran out leaves nothing behind, or the map grows with every id ever written.
+        void settled.then(() => {
+            if (this.chains.get(key) === settled) {
+                this.chains.delete(key);
+            }
+        });
+
+        return next;
+    }
+}

package/src/single-flight.ts

@@ -0,0 +1,33 @@
+/*
+ * Work that runs once per key at a time: a caller that asks while it runs shares its outcome, and
+ * a key that settled leaves nothing behind.
+ */
+export class SingleFlight<T> {
+    private readonly flights = new Map<string, Promise<T>>();
+
+    /* The run in flight for `key`, if any. */
+    get(key: string): Promise<T> | undefined {
+        return this.flights.get(key);
+    }
+
+    has(key: string): boolean {
+        return this.flights.has(key);
+    }
+
+    run(key: string, work: () => Promise<T>): Promise<T> {
+        const running = this.flights.get(key);
+
+        if (running !== undefined) {
+            return running;
+        }
+
+        const flight = work().finally(() => {
+            if (this.flights.get(key) === flight) {
+                this.flights.delete(key);
+            }
+        });
+        this.flights.set(key, flight);
+
+        return flight;
+    }
+}

package/src/text.ts

@@ -0,0 +1,9 @@
+/* The first half of a surrogate pair, a UTF-16 code unit that cannot stand alone. */
+export function isHighSurrogate(code: number): boolean {
+    return code >= 0xd800 && code <= 0xdbff;
+}
+
+/* The second half of a surrogate pair. */
+export function isLowSurrogate(code: number): boolean {
+    return code >= 0xdc00 && code <= 0xdfff;
+}