@dbx-tools/core 0.6.64 → 0.6.66

package/README.md

@@ -1,6 +1,7 @@
 # @dbx-tools/core
 
-Node-only core helpers for process execution and project discovery.
+Node-only core helpers for binary installation, process execution, and project
+discovery.
 
 Import this package when code needs `node:child_process`, `node:fs`, or
 `node:path`. Browser-safe utilities live in
@@ -16,6 +17,36 @@ Key features:
   the current working directory.
 - Safe filesystem stat and project naming helpers for CLIs and projen synth.
 - YAML/JSON brand-context discovery and loading with shared Zod validation.
+- Idempotent executable downloads with zip/tar extraction and atomic installs.
+- Keyed mutual exclusion across the main thread and its worker threads.
+
+## Install A Binary
+
+```ts
+import { chmod } from "node:fs/promises";
+import { join } from "node:path";
+
+import { bin } from "@dbx-tools/core";
+
+const executable = await bin.ensure("tool", releaseUrl, {
+  autoUnpackage: true,
+  selector: async ({ source }) => {
+    const path = join(source, "tool");
+    await chmod(path, 0o755);
+    return path;
+  },
+});
+```
+
+`bin.ensure()` installs to `$HOME/.<name>/bin/<name>` and returns its `root`,
+`binDir`, and executable `path`. An existing executable returns immediately, so
+a URL resolver is only called when installation is necessary. Concurrent
+callers use `processLock` with a check-lock-check-load sequence, preventing
+duplicate downloads across the main thread and wired workers. Direct downloads
+are selected by default. Zip, tar, tar.gz, and tgz archives can be unpacked
+automatically; a single-file archive needs no selector, while a selector can
+choose and prepare a binary from a larger archive. The selected file must be
+executable before it is atomically moved into place.
 
 ## Load Brand Context
 
@@ -80,6 +111,50 @@ const argv = exec.shlex('pnpm exec prettier --write "README.md"');
 `shlex()` is a small parser for command strings that need to become argv arrays.
 Prefer explicit argv arrays when possible.
 
+## Serialize Work Across Threads
+
+```ts
+import { processLock } from "@dbx-tools/core";
+
+await processLock.withProcessLock(["cache", name], async () => {
+  if (!(await exists(name))) await build(name);
+});
+```
+
+`withProcessLock()` runs the callback while holding the named lock, releasing it
+when the callback settles. Callers sharing a key are serialized; distinct keys
+run concurrently. The key is any value with a stable identity - a string, a
+`["invoice", id]` tuple, a config object - canonicalized by `object.toStableKey`,
+so structure counts: `["invoice", 7]` and `"invoice_7"` are different locks.
+
+Use it instead of a module-level promise chain when worker threads are involved.
+A promise chain only serializes the thread it lives on, so a worker pool runs one
+callback per thread; the coordinator here is shared, so the key admits one
+callback for the whole process.
+
+Workers opt in when they are constructed:
+
+```ts
+import { Worker } from "node:worker_threads";
+
+new Worker(url, processLock.processLockWorkerOptions({ workerData: { tenant } }));
+```
+
+That preserves your own `workerData` and `transferList`, and lets the worker lock
+during module initialization. For a worker you did not construct, call
+`attachProcessLock(worker)` and have the worker `await processLockAttached()`
+first - the port arrives by message, so it is not available quite as early.
+
+A thread that exits while holding a lock releases it, so a crashed worker cannot
+wedge a key. Locks are held only as long as the callback runs, and an idle lock
+never keeps the process from exiting.
+
+The scope is the THREADS of one process - `withProcessLock` shares nothing with a
+second `node` invocation or another replica. When the critical section spans a
+deployment, use
+[`@dbx-tools/postgres`](../postgres)'s `withAdvisoryLock`, which puts the arbiter
+in PostgreSQL where every replica can see it.
+
 ## Discover Project Roots
 
 ```ts
@@ -97,6 +172,11 @@ basename. `project.stat()` returns `undefined` instead of throwing.
 ## Modules
 
 - `exec` - async/sync process spawning, stdio handling, abort wiring, and shlex.
+- `bin` - executable download, optional archive extraction, selection, and
+  atomic installation.
 - `project` - root discovery, project naming, git-remote parsing, and safe
   filesystem stat.
 - `brand` - YAML/JSON discovery, parsing, validation, and asset path resolution.
+- `processLock` - keyed mutual exclusion across the main thread and its workers,
+  with worker wiring (`processLockWorkerOptions`, `attachProcessLock`,
+  `processLockAttached`).

package/index.ts

@@ -2,10 +2,13 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 
+export * as bin from "./src/bin.ts";
 export * as brand from "./src/brand.ts";
 export * as exec from "./src/exec.ts";
 export * as file from "./src/file.ts";
+export * as processLock from "./src/process-lock.ts";
 export * as project from "./src/project.ts";
+export type { BinContext, BinSelectionContext, BinSelector, BinOptions, BinUrl } from "./src/bin.ts";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.ts";
 export type { BrandContext, BrandContextInput } from "./src/brand.ts";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.ts";

package/lib/index.d.ts

@@ -1,7 +1,10 @@
+export * as bin from "./src/bin.ts";
 export * as brand from "./src/brand.ts";
 export * as exec from "./src/exec.ts";
 export * as file from "./src/file.ts";
+export * as processLock from "./src/process-lock.ts";
 export * as project from "./src/project.ts";
+export type { BinContext, BinSelectionContext, BinSelector, BinOptions, BinUrl } from "./src/bin.ts";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.ts";
 export type { BrandContext, BrandContextInput } from "./src/brand.ts";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.ts";

package/lib/index.js

@@ -1,10 +1,12 @@
 // GENERATED by projen watch - DO NOT EDIT.
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
+export * as bin from "./src/bin.js";
 export * as brand from "./src/brand.js";
 export * as exec from "./src/exec.js";
 export * as file from "./src/file.js";
+export * as processLock from "./src/process-lock.js";
 export * as project from "./src/project.js";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.js";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFDNUMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLGlCQUFpQixFQUFFLHNCQUFzQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFeEksT0FBTyxFQUFFLDJCQUEyQixFQUFFLE1BQU0sZUFBZSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgYnJhbmQgZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgKiBhcyBleGVjIGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlIGZyb20gXCIuL3NyYy9maWxlLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9qZWN0IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG5leHBvcnQgeyBCcmFuZENvbnRleHRTY2hlbWEsIGRlZmF1bHRCcmFuZENvbnRleHQsIHBhcnNlQnJhbmRDb250ZXh0LCBicmFuZENvbnRleHRKc29uU2NoZW1hLCBicmFuZENvbnRleHRQcm9tcHQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHsgQ09NTUFORF9OT1RfRk9VTkRfRVhJVF9DT0RFIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY1N0ZGlvLCBMaW5lSGFuZGxlciwgU3RkaW9PcHRpb24sIEV4ZWNSZXN1bHQsIENoaWxkUHJvY2Vzc1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgUHJvamVjdENvbnRleHQgfSBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxXQUFXLE1BQU0sdUJBQXVCLENBQUM7QUFDckQsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUU1QyxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsbUJBQW1CLEVBQUUsaUJBQWlCLEVBQUUsc0JBQXNCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUV4SSxPQUFPLEVBQUUsMkJBQTJCLEVBQUUsTUFBTSxlQUFlLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBiaW4gZnJvbSBcIi4vc3JjL2Jpbi50c1wiO1xuZXhwb3J0ICogYXMgYnJhbmQgZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgKiBhcyBleGVjIGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlIGZyb20gXCIuL3NyYy9maWxlLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9jZXNzTG9jayBmcm9tIFwiLi9zcmMvcHJvY2Vzcy1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9qZWN0IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG5leHBvcnQgdHlwZSB7IEJpbkNvbnRleHQsIEJpblNlbGVjdGlvbkNvbnRleHQsIEJpblNlbGVjdG9yLCBCaW5PcHRpb25zLCBCaW5VcmwgfSBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgeyBCcmFuZENvbnRleHRTY2hlbWEsIGRlZmF1bHRCcmFuZENvbnRleHQsIHBhcnNlQnJhbmRDb250ZXh0LCBicmFuZENvbnRleHRKc29uU2NoZW1hLCBicmFuZENvbnRleHRQcm9tcHQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHsgQ09NTUFORF9OT1RfRk9VTkRfRVhJVF9DT0RFIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY1N0ZGlvLCBMaW5lSGFuZGxlciwgU3RkaW9PcHRpb24sIEV4ZWNSZXN1bHQsIENoaWxkUHJvY2Vzc1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgUHJvamVjdENvbnRleHQgfSBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuIl19

package/lib/src/bin.d.ts

@@ -0,0 +1,31 @@
+/** Stable paths for an installed binary. */
+export interface BinContext {
+    root: string;
+    binDir: string;
+    path: string;
+}
+/** Temporary download and extraction paths supplied to a custom selector. */
+export interface BinSelectionContext {
+    destination: BinContext;
+    downloadPath: string;
+    source: string;
+}
+/**
+ * Select the executable from a download or unpacked archive. A selector may
+ * also prepare the file, such as applying its executable mode.
+ */
+export type BinSelector = (context: BinSelectionContext) => string | Promise<string>;
+/** Options for {@link ensure}. */
+export interface BinOptions {
+    autoUnpackage?: boolean;
+    selector?: BinSelector;
+    homeDir?: string;
+}
+/** A URL resolved only when the executable is not already installed. */
+export type BinUrl = string | (() => string | Promise<string>);
+/**
+ * Return an existing executable or install it atomically under
+ * `$HOME/.<name>/bin/<name>`. Installation uses a check-lock-check-load
+ * sequence so concurrent callers resolve and download the binary only once.
+ */
+export declare function ensure(name: string, url: BinUrl, options?: BinOptions): Promise<BinContext>;

package/lib/src/bin.js

@@ -0,0 +1,130 @@
+/**
+ * Install and reuse executable binaries under a per-tool home directory.
+ *
+ * @module
+ */
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, copyFile, mkdir, mkdtemp, readdir, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import extractZip from "extract-zip";
+import { x as extractTar } from "tar";
+import { withProcessLock } from "./process-lock.js";
+function context(name, homeDir) {
+    if (!name || basename(name) !== name || name === "." || name === "..") {
+        throw new TypeError(`invalid binary name: ${name}`);
+    }
+    const root = join(homeDir, `.${name}`);
+    const binDir = join(root, "bin");
+    return { root, binDir, path: join(binDir, name) };
+}
+async function isExecutable(path) {
+    try {
+        if (!(await stat(path)).isFile())
+            return false;
+        await access(path, constants.F_OK | constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function downloadName(url, name) {
+    try {
+        const candidate = basename(decodeURIComponent(new URL(url).pathname));
+        return candidate && Buffer.byteLength(candidate) <= 200 ? candidate : name;
+    }
+    catch {
+        return name;
+    }
+}
+async function unpack(archive, destination) {
+    const filename = archive.toLowerCase();
+    if (filename.endsWith(".zip")) {
+        await extractZip(archive, { dir: destination });
+        return;
+    }
+    if (filename.endsWith(".tar") || filename.endsWith(".tar.gz") || filename.endsWith(".tgz")) {
+        await extractTar({ file: archive, cwd: destination });
+        return;
+    }
+    throw new Error(`unsupported binary archive: ${basename(archive)}`);
+}
+async function filesUnder(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await filesUnder(path)));
+        }
+        else if (entry.isFile()) {
+            files.push(path);
+        }
+    }
+    return files;
+}
+async function selectSingleFile(source) {
+    const files = await filesUnder(source);
+    const selected = files.at(0);
+    if (files.length !== 1 || !selected) {
+        throw new Error(`binary archive must contain one file, found ${files.length}`);
+    }
+    return selected;
+}
+async function selectedBin(destination, url, temp, options) {
+    const name = downloadName(url, basename(destination.path));
+    const downloadPath = join(temp, name);
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`binary download failed (${response.status})`);
+    }
+    await writeFile(downloadPath, Buffer.from(await response.arrayBuffer()), { mode: 0o755 });
+    let source = downloadPath;
+    if (options.autoUnpackage) {
+        source = join(temp, `unpacked-${randomUUID()}`);
+        await mkdir(source);
+        await unpack(downloadPath, source);
+    }
+    if (options.selector) {
+        return options.selector({ destination, downloadPath, source });
+    }
+    return options.autoUnpackage ? selectSingleFile(source) : source;
+}
+/**
+ * Return an existing executable or install it atomically under
+ * `$HOME/.<name>/bin/<name>`. Installation uses a check-lock-check-load
+ * sequence so concurrent callers resolve and download the binary only once.
+ */
+export async function ensure(name, url, options = {}) {
+    const destination = context(name, options.homeDir ?? homedir());
+    if (await isExecutable(destination.path))
+        return destination;
+    return withProcessLock(["bin.ensure", destination.path], async () => {
+        if (await isExecutable(destination.path))
+            return destination;
+        const resolvedUrl = typeof url === "function" ? await url() : url;
+        const temp = await mkdtemp(join(tmpdir(), `${name}-`));
+        let staged;
+        try {
+            const selected = await selectedBin(destination, resolvedUrl, temp, options);
+            if (!(await isExecutable(selected))) {
+                throw new Error(`selected binary is not executable: ${selected}`);
+            }
+            await mkdir(destination.binDir, { recursive: true });
+            staged = join(destination.binDir, `.${name}-${randomUUID()}`);
+            await copyFile(selected, staged);
+            await chmod(staged, (await stat(selected)).mode);
+            await rename(staged, destination.path);
+            staged = undefined;
+            return destination;
+        }
+        finally {
+            if (staged)
+                await rm(staged, { force: true });
+            await rm(temp, { recursive: true, force: true });
+        }
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmluLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2Jpbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7OztHQUlHO0FBQ0gsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUN6QyxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sU0FBUyxDQUFDO0FBQ3BDLE9BQU8sRUFDTCxNQUFNLEVBQ04sS0FBSyxFQUNMLFFBQVEsRUFDUixLQUFLLEVBQ0wsT0FBTyxFQUNQLE9BQU8sRUFDUCxNQUFNLEVBQ04sRUFBRSxFQUNGLElBQUksRUFDSixTQUFTLEdBQ1YsTUFBTSxrQkFBa0IsQ0FBQztBQUMxQixPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLFNBQVMsQ0FBQztBQUMxQyxPQUFPLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUUzQyxPQUFPLFVBQVUsTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxFQUFFLENBQUMsSUFBSSxVQUFVLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFdEMsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBZ0NwRCxTQUFTLE9BQU8sQ0FBQyxJQUFZLEVBQUUsT0FBZTtJQUM1QyxJQUFJLENBQUMsSUFBSSxJQUFJLFFBQVEsQ0FBQyxJQUFJLENBQUMsS0FBSyxJQUFJLElBQUksSUFBSSxLQUFLLEdBQUcsSUFBSSxJQUFJLEtBQUssSUFBSSxFQUFFLENBQUM7UUFDdEUsTUFBTSxJQUFJLFNBQVMsQ0FBQyx3QkFBd0IsSUFBSSxFQUFFLENBQUMsQ0FBQztJQUN0RCxDQUFDO0lBQ0QsTUFBTSxJQUFJLEdBQUcsSUFBSSxDQUFDLE9BQU8sRUFBRSxJQUFJLElBQUksRUFBRSxDQUFDLENBQUM7SUFDdkMsTUFBTSxNQUFNLEdBQUcsSUFBSSxDQUFDLElBQUksRUFBRSxLQUFLLENBQUMsQ0FBQztJQUNqQyxPQUFPLEVBQUUsSUFB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RSxJQUFJLEVBQUUsT0FBTyxDQUFDLENBQUM7WUFDNUUsSUFBSSxDQUFDLENBQUMsTUFBTSxZQUFZLENBQUMsUUFBUSxDQUFDLENBQUMsRUFBRSxDQUFDO2dCQUNwQyxNQUFNLElBQUksS0FBSyxDQUFDLHNDQUFzQyxRQUFRLEVBQUUsQ0FBQyxDQUFDO1lBQ3BFLENBQUM7WUFFRCxNQUFNLEtBQUssQ0FBQyxXQUFXLENBQUMsTUFBTSxFQUFFLEVBQUUsU0FBUyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7WUFDckQsTUFBTSxHQUFHLElBQUksQ0FBQyxXQUFXLENBQUMsTUFBTSxFQUFFLElBQUksSUFBSSxJQUFJLFVBQVUsRUFBRSxFQUFFLENBQUMsQ0FBQztZQUM5RCxNQUFNLFFBQVEsQ0FBQyxRQUFRLEVBQUUsTUFBTSxDQUFDLENBQUM7WUFDakMsTUFBTSxLQUFLLENBQUMsTUFBTSxFQUFFLENBQUMsTUFBTSxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsQ0FBQztZQUNqRCxNQUFNLE1BQU0sQ0FBQyxNQUFNLEVBQUUsV0FBVyxDQUFDLElBQUksQ0FBQyxDQUFDO1lBQ3ZDLE1BQU0sR0FBRyxTQUFTLENBQUM7WUFDbkIsT0FBTyxXQUFXLENBQUM7UUFDckIsQ0FBQztnQkFBUyxDQUFDO1lBQ1QsSUFBSSxNQUFNO2dCQUFFLE1BQU0sRUFBRSxDQUFDLE1BQU0sRUFBRSxFQUFFLEtBQUssRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDO1lBQzlDLE1BQU0sRUFBRSxDQUFDLElBQUksRUFBRSxFQUFFLFNBQVMsRUFBRSxJQUFJLEVBQUUsS0FBSyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7UUFDbkQsQ0FBQztJQUNILENBQUMsQ0FBQyxDQUFDO0FBQ0wsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogSW5zdGFsbCBhbmQgcmV1c2UgZXhlY3V0YWJsZSBiaW5hcmllcyB1bmRlciBhIHBlci10b29sIGhvbWUgZGlyZWN0b3J5LlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuaW1wb3J0IHsgcmFuZG9tVVVJRCB9IGZyb20gXCJub2RlOmNyeXB0b1wiO1xuaW1wb3J0IHsgY29uc3RhbnRzIH0gZnJvbSBcIm5vZGU6ZnNcIjtcbmltcG9ydCB7XG4gIGFjY2VzcyxcbiAgY2htb2QsXG4gIGNvcHlGaWxlLFxuICBta2RpcixcbiAgbWtkdGVtcCxcbiAgcmVhZGRpcixcbiAgcmVuYW1lLFxuICBybSxcbiAgc3RhdCxcbiAgd3JpdGVGaWxlLFxufSBmcm9tIFwibm9kZTpmcy9wcm9taXNlc1wiO1xuaW1wb3J0IHsgaG9tZWRpciwgdG1wZGlyIH0gZnJvbSBcIm5vZGU6b3NcIjtcbmltcG9ydCB7IGJhc2VuYW1lLCBqb2luIH0gZnJvbSBcIm5vZGU6cGF0aFwiO1xuXG5pbXBvcnQgZXh0cmFjdFppcCBmcm9tIFwiZXh0cmFjdC16aXBcIjtcbmltcG9ydCB7IHggYXMgZXh0cmFjdFRhciB9IGZyb20gXCJ0YXJcIjtcblxuaW1wb3J0IHsgd2l0aFByb2Nlc3NMb2NrIH0gZnJvbSBcIi4vcHJvY2Vzcy1sb2NrLnRzXCI7XG5cbi8qKiBTdGFibGUgcGF0aHMgZm9yIGFuIGluc3RhbGxlZCBiaW5hcnkuICovXG5leHBvcnQgaW50ZXJmYWNlIEJpbkNvbnRleHQge1xuICByb290OiBzdHJpbmc7XG4gIGJpbkRpcjogc3RyaW5nO1xuICBwYXRoOiBzdHJpbmc7XG59XG5cbi8qKiBUZW1wb3JhcnkgZG93bmxvYWQgYW5kIGV4dHJhY3Rpb24gcGF0aHMgc3VwcGxpZWQgdG8gYSBjdXN0b20gc2VsZWN0b3IuICovXG5leHBvcnQgaW50ZXJmYWNlIEJpblNlbGVjdGlvbkNvbnRleHQge1xuICBkZXN0aW5hdGlvbjogQmluQ29udGV4dDtcbiAgZG93bmxvYWRQYXRoOiBzdHJpbmc7XG4gIHNvdXJjZTogc3RyaW5nO1xufVxuXG4vKipcbiAqIFNlbGVjdCB0aGUgZXhlY3V0YWJsZSBmcm9tIGEgZG93bmxvYWQgb3IgdW5wYWNrZWQgYXJjaGl2ZS4gQSBzZWxlY3RvciBtYXlcbiAqIGFsc28gcHJlcGFyZSB0aGUgZmlsZSwgc3VjaCBhcyBhcHBseWluZyBpdHMgZXhlY3V0YWJsZSBtb2RlLlxuICovXG5leHBvcnQgdHlwZSBCaW5TZWxlY3RvciA9IChjb250ZXh0OiBCaW5TZWxlY3Rpb25Db250ZXh0KSA9PiBzdHJpbmcgfCBQcm9taXNlPHN0cmluZz47XG5cbi8qKiBPcHRpb25zIGZvciB7QGxpbmsgZW5zdXJlfS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQmluT3B0aW9ucyB7XG4gIGF1dG9VbnBhY2thZ2U/OiBib29sZWFuO1xuICBzZWxlY3Rvcj86IEJpblNlbGVjdG9yO1xuICBob21lRGlyPzogc3RyaW5nO1xufVxuXG4vKiogQSBVUkwgcmVzb2x2ZWQgb25seSB3aGVuIHRoZSBleGVjdXRhYmxlIGlzIG5vdCBhbHJlYWR5IGluc3RhbGxlZC4gKi9cbmV4cG9ydCB0eXBlIEJpblVybCA9IHN0cmluZyB8ICgoKSA9PiBzdHJpbmcgfCBQcm9taXNlPHN0cmluZz4pO1xuXG5mdW5jdGlvbiBjb250ZXh0KG5hbWU6IHN0cmluZywgaG9tZURpcjogc3RyaW5nKTogQmluQ29udGV4dCB7XG4gIGlmICghbmFtZSB8fCBiYXNlbmFtZShuYW1lKSAhPT0gbmFtZSB8fCBuYW1lID09PSBcIi5cIiB8fCBuYW1lID09PSBcIi4uXCIpIHtcbiAgICB0aHJvdyBuZXcgVHlwZUVycm9yKGBpbnZhbGlkIGJpbmFyeSBuYW1lOiAke25hbWV9YCk7XG4gIH1cbiAgY29uc3Qgcm9vdCA9IGpvaW4oaG9tZURpciwgYC4ke25hbWV9YCk7XG4gIGNvbnN0IGJpbkRpciA9IGpvaW4ocm9vdCwgXCJiaW5cIik7XG4gIHJldHVybiB7IHJvb3QsIGJpbkRpciwgcGF0aDogam9pbihiaW5EaXIsIG5hbWUpIH07XG59XG5cbmFzeW5jIGZ1bmN0aW9uIGlzRXhlY3V0YWJsZShwYXRoOiBzdHJpbmcpOiBQcm9taXNlPGJvb2xlYW4+IHtcbiAgdHJ5IHtcbiAgICBpZiAoIShhd2FpdCBzdGF0KHBhdGgpKS5pc0ZpbGUoKSkgcmV0dXJuIGZhbHNlO1xuICAgIGF3YWl0IGFjY2VzcyhwYXRoLCBjb25zdGFudHMuRl9PSyB8IGNvbnN0YW50cy5YX09LKTtcbiAgICByZXR1cm4gdHJ1ZTtcbiAgfSBjYXRjaCB7XG4gICAgcmV0dXJuIGZhbHNlO1xuICB9XG59XG5cbmZ1bmN0aW9uIGRvd25sb2FkTmFtZSh1cmw6IHN0cmluZywgbmFtZTogc3RyaW5nKTogc3RyaW5nIHtcbiAgdHJ5IHtcbiAgICBjb25zdCBjYW5kaWRhdGUgPSBiYXNlbmFtZShkZWNvZGVVUklDb21wb25lbnQobmV3IFVSTCh1cmwpLnBhdGhuYW1lKSk7XG4gICAgcmV0dXJuIGNhbmRpZGF0ZSAmJiBCdWZmZXIuYnl0ZUxlbmd0aChjYW5kaWRhdGUpIDw9IDIwMCA/IGNhbmRpZGF0ZSA6IG5hbWU7XG4gIH0gY2F0Y2gge1xuICAgIHJldHVybiBuYW1lO1xuICB9XG59XG5cbmFzeW5jIGZ1bmN0aW9uIHVucGFjayhhcmNoaXZlOiBzdHJpbmcsIGRlc3RpbmF0aW9uOiBzdHJpbmcpOiBQcm9taXNlPHZvaWQ+IHtcbiAgY29uc3QgZmlsZW5hbWUgPSBhcmNoaXZlLnRvTG93ZXJDYXNlKCk7XG4gIGlmIChmaWxlbmFtZS5lbmRzV2l0aChcIi56aXBcIikpIHtcbiAgICBhd2FpdCBleHRyYWN0WmlwKGFyY2hpdmUsIHsgZGlyOiBkZXN0aW5hdGlvbiB9KTtcbiAgICByZXR1cm47XG4gIH1cbiAgaWYgKGZpbGVuYW1lLmVuZHNXaXRoKFwiLnRhclwiKSB8fCBmaWxlbmFtZS5lbmRzV2l0aChcIi50YXIuZ3pcIikgfHwgZmlsZW5hbWUuZW5kc1dpdGgoXCIudGd6XCIpKSB7XG4gICAgYXdhaXQgZXh0cmFjdFRhcih7IGZpbGU6IGFyY2hpdmUsIGN3ZDogZGVzdGluYXRpb24gfSk7XG4gICAgcmV0dXJuO1xuICB9XG4gIHRocm93IG5ldyBFcnJvcihgdW5zdXBwb3J0ZWQgYmluYXJ5IGFyY2hpdmU6ICR7YmFzZW5hbWUoYXJjaGl2ZSl9YCk7XG59XG5cbmFzeW5jIGZ1bmN0aW9uIGZpbGVzVW5kZXIocm9vdDogc3RyaW5nKTogUHJvbWlzZTxzdHJpbmdbXT4ge1xuICBjb25zdCBlbnRyaWVzID0gYXdhaXQgcmVhZGRpcihyb290LCB7IHdpdGhGaWxlVHlwZXM6IHRydWUgfSk7XG4gIGNvbnN0IGZpbGVzOiBzdHJpbmdbXSA9IFtdO1xuICBmb3IgKGNvbnN0IGVudHJ5IG9mIGVudHJpZXMpIHtcbiAgICBjb25zdCBwYXRoID0gam9pbihyb290LCBlbnRyeS5uYW1lKTtcbiAgICBpZiAoZW50cnkuaXNEaXJlY3RvcnkoKSkge1xuICAgICAgZmlsZXMucHVzaCguLi4oYXdhaXQgZmlsZXNVbmRlcihwYXRoKSkpO1xuICAgIH0gZWxzZSBpZiAoZW50cnkuaXNGaWxlKCkpIHtcbiAgICAgIGZpbGVzLnB1c2gocGF0aCk7XG4gICAgfVxuICB9XG4gIHJldHVybiBmaWxlcztcbn1cblxuYXN5bmMgZnVuY3Rpb24gc2VsZWN0U2luZ2xlRmlsZShzb3VyY2U6IHN0cmluZyk6IFByb21pc2U8c3RyaW5nPiB7XG4gIGNvbnN0IGZpbGVzID0gYXdhaXQgZmlsZXNVbmRlcihzb3VyY2UpO1xuICBjb25zdCBzZWxlY3RlZCA9IGZpbGVzLmF0KDApO1xuICBpZiAoZmlsZXMubGVuZ3RoICE9PSAxIHx8ICFzZWxlY3RlZCkge1xuICAgIHRocm93IG5ldyBFcnJvcihgYmluYXJ5IGFyY2hpdmUgbXVzdCBjb250YWluIG9uZSBmaWxlLCBmb3VuZCAke2ZpbGVzLmxlbmd0aH1gKTtcbiAgfVxuICByZXR1cm4gc2VsZWN0ZWQ7XG59XG5cbmFzeW5jIGZ1bmN0aW9uIHNlbGVjdGVkQmluKFxuICBkZXN0aW5hdGlvbjogQmluQ29udGV4dCxcbiAgdXJsOiBzdHJpbmcsXG4gIHRlbXA6IHN0cmluZyxcbiAgb3B0aW9uczogQmluT3B0aW9ucyxcbik6IFByb21pc2U8c3RyaW5nPiB7XG4gIGNvbnN0IG5hbWUgPSBkb3dubG9hZE5hbWUodXJsLCBiYXNlbmFtZShkZXN0aW5hdGlvbi5wYXRoKSk7XG4gIGNvbnN0IGRvd25sb2FkUGF0aCA9IGpvaW4odGVtcCwgbmFtZSk7XG4gIGNvbnN0IHJlc3BvbnNlID0gYXdhaXQgZmV0Y2godXJsKTtcbiAgaWYgKCFyZXNwb25zZS5vaykge1xuICAgIHRocm93IG5ldyBFcnJvcihgYmluYXJ5IGRvd25sb2FkIGZhaWxlZCAoJHtyZXNwb25zZS5zdGF0dXN9KWApO1xuICB9XG4gIGF3YWl0IHdyaXRlRmlsZShkb3dubG9hZFBhdGgsIEJ1ZmZlci5mcm9tKGF3YWl0IHJlc3BvbnNlLmFycmF5QnVmZmVyKCkpLCB7IG1vZGU6IDBvNzU1IH0pO1xuXG4gIGxldCBzb3VyY2UgPSBkb3dubG9hZFBhdGg7XG4gIGlmIChvcHRpb25zLmF1dG9VbnBhY2thZ2UpIHtcbiAgICBzb3VyY2UgPSBqb2luKHRlbXAsIGB1bnBhY2tlZC0ke3JhbmRvbVVVSUQoKX1gKTtcbiAgICBhd2FpdCBta2Rpcihzb3VyY2UpO1xuICAgIGF3YWl0IHVucGFjayhkb3dubG9hZFBhdGgsIHNvdXJjZSk7XG4gIH1cblxuICBpZiAob3B0aW9ucy5zZWxlY3Rvcikge1xuICAgIHJldHVybiBvcHRpb25zLnNlbGVjdG9yKHsgZGVzdGluYXRpb24sIGRvd25sb2FkUGF0aCwgc291cmNlIH0pO1xuICB9XG4gIHJldHVybiBvcHRpb25zLmF1dG9VbnBhY2thZ2UgPyBzZWxlY3RTaW5nbGVGaWxlKHNvdXJjZSkgOiBzb3VyY2U7XG59XG5cbi8qKlxuICogUmV0dXJuIGFuIGV4aXN0aW5nIGV4ZWN1dGFibGUgb3IgaW5zdGFsbCBpdCBhdG9taWNhbGx5IHVuZGVyXG4gKiBgJEhPTUUvLjxuYW1lPi9iaW4vPG5hbWU+YC4gSW5zdGFsbGF0aW9uIHVzZXMgYSBjaGVjay1sb2NrLWNoZWNrLWxvYWRcbiAqIHNlcXVlbmNlIHNvIGNvbmN1cnJlbnQgY2FsbGVycyByZXNvbHZlIGFuZCBkb3dubG9hZCB0aGUgYmluYXJ5IG9ubHkgb25jZS5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGVuc3VyZShcbiAgbmFtZTogc3RyaW5nLFxuICB1cmw6IEJpblVybCxcbiAgb3B0aW9uczogQmluT3B0aW9ucyA9IHt9LFxuKTogUHJvbWlzZTxCaW5Db250ZXh0PiB7XG4gIGNvbnN0IGRlc3RpbmF0aW9uID0gY29udGV4dChuYW1lLCBvcHRpb25zLmhvbWVEaXIgPz8gaG9tZWRpcigpKTtcbiAgaWYgKGF3YWl0IGlzRXhlY3V0YWJsZShkZXN0aW5hdGlvbi5wYXRoKSkgcmV0dXJuIGRlc3RpbmF0aW9uO1xuXG4gIHJldHVybiB3aXRoUHJvY2Vzc0xvY2soW1wiYmluLmVuc3VyZVwiLCBkZXN0aW5hdGlvbi5wYXRoXSwgYXN5bmMgKCkgPT4ge1xuICAgIGlmIChhd2FpdCBpc0V4ZWN1dGFibGUoZGVzdGluYXRpb24ucGF0aCkpIHJldHVybiBkZXN0aW5hdGlvbjtcblxuICAgIGNvbnN0IHJlc29sdmVkVXJsID0gdHlwZW9mIHVybCA9PT0gXCJmdW5jdGlvblwiID8gYXdhaXQgdXJsKCkgOiB1cmw7XG4gICAgY29uc3QgdGVtcCA9IGF3YWl0IG1rZHRlbXAoam9pbih0bXBkaXIoKSwgYCR7bmFtZX0tYCkpO1xuICAgIGxldCBzdGFnZWQ6IHN0cmluZyB8IHVuZGVmaW5lZDtcbiAgICB0cnkge1xuICAgICAgY29uc3Qgc2VsZWN0ZWQgPSBhd2FpdCBzZWxlY3RlZEJpbihkZXN0aW5hdGlvbiwgcmVzb2x2ZWRVcmwsIHRlbXAsIG9wdGlvbnMpO1xuICAgICAgaWYgKCEoYXdhaXQgaXNFeGVjdXRhYmxlKHNlbGVjdGVkKSkpIHtcbiAgICAgICAgdGhyb3cgbmV3IEVycm9yKGBzZWxlY3RlZCBiaW5hcnkgaXMgbm90IGV4ZWN1dGFibGU6ICR7c2VsZWN0ZWR9YCk7XG4gICAgICB9XG5cbiAgICAgIGF3YWl0IG1rZGlyKGRlc3RpbmF0aW9uLmJpbkRpciwgeyByZWN1cnNpdmU6IHRydWUgfSk7XG4gICAgICBzdGFnZWQgPSBqb2luKGRlc3RpbmF0aW9uLmJpbkRpciwgYC4ke25hbWV9LSR7cmFuZG9tVVVJRCgpfWApO1xuICAgICAgYXdhaXQgY29weUZpbGUoc2VsZWN0ZWQsIHN0YWdlZCk7XG4gICAgICBhd2FpdCBjaG1vZChzdGFnZWQsIChhd2FpdCBzdGF0KHNlbGVjdGVkKSkubW9kZSk7XG4gICAgICBhd2FpdCByZW5hbWUoc3RhZ2VkLCBkZXN0aW5hdGlvbi5wYXRoKTtcbiAgICAgIHN0YWdlZCA9IHVuZGVmaW5lZDtcbiAgICAgIHJldHVybiBkZXN0aW5hdGlvbjtcbiAgICB9IGZpbmFsbHkge1xuICAgICAgaWYgKHN0YWdlZCkgYXdhaXQgcm0oc3RhZ2VkLCB7IGZvcmNlOiB0cnVlIH0pO1xuICAgICAgYXdhaXQgcm0odGVtcCwgeyByZWN1cnNpdmU6IHRydWUsIGZvcmNlOiB0cnVlIH0pO1xuICAgIH1cbiAgfSk7XG59XG4iXX0=

package/lib/src/process-lock.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Keyed mutual exclusion across the main thread and its worker threads.
+ *
+ * {@link withProcessLock} serializes callbacks that share a key: one runs at a
+ * time, the rest queue in arrival order, and different keys proceed
+ * concurrently. Unlike a plain in-module `Promise` chain, the queue is shared by
+ * every thread wired up through {@link processLockWorkerOptions}, so a worker
+ * pool cannot run two callbacks for the same key at once.
+ *
+ * The name says `process`: this coordinates the THREADS of one Node process. It
+ * is not cross-process and not cross-host - a second `node` invocation, or a
+ * second app replica, has its own coordinator and shares nothing. When the scope
+ * is a deployment rather than a process, use
+ * `@dbx-tools/postgres`'s `withAdvisoryLock`, which puts the arbiter in
+ * PostgreSQL where every replica can see it.
+ *
+ * The main thread owns the only coordinator. Each participating thread gets one
+ * `MessagePort` to it, and a lock is granted by a message back over that port.
+ * Consequently:
+ *
+ *   - the lock is ADVISORY, like Postgres advisory locks - it protects a
+ *     critical section only insofar as every writer takes the same key;
+ *   - fairness is FIFO per key, since the coordinator queues waiters in the
+ *     order their requests arrive;
+ *   - a thread that dies while holding a lock releases it, because its port
+ *     closing is what hands the key to the next waiter (see
+ *     {@link LockCoordinator.removePort}).
+ *
+ * @module
+ */
+import { type Worker, type WorkerOptions } from "node:worker_threads";
+/**
+ * Run `fn` while holding the lock named by `key`, releasing it when `fn`
+ * settles.
+ *
+ * Callers sharing a key are serialized across the main thread and every worker
+ * started through {@link processLockWorkerOptions}; distinct keys never block
+ * each other. Returns whatever `fn` returns and propagates what it throws, so it
+ * drops into an existing expression without restructuring.
+ *
+ * `key` is any value with a stable identity - a string, a `["invoice", id]`
+ * tuple, a config object - canonicalized by `object.toStableKey`, the same rule
+ * `@dbx-tools/postgres` uses for advisory-lock ids and channel names. Structure
+ * is part of the identity: `["invoice", 7]` and `"invoice_7"` are different
+ * locks.
+ *
+ * @example
+ * await withProcessLock(["cache", name], async () => {
+ *   if (!(await exists(name))) await build(name);
+ * });
+ */
+export declare function withProcessLock<T>(key: unknown, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Add the coordinator port to a `Worker`'s options so the worker can lock
+ * immediately - during module initialization, before any message is handled.
+ *
+ * Preserves the caller's `workerData` and `transferList`; the port is
+ * transferred, as `MessagePort` cannot be cloned.
+ *
+ * @example
+ * new Worker(url, processLockWorkerOptions({ workerData: { tenant } }));
+ */
+export declare function processLockWorkerOptions(options?: WorkerOptions): WorkerOptions;
+/**
+ * Wire an ALREADY-RUNNING worker into the lock, for a worker this code did not
+ * construct (a pool from a library, say).
+ *
+ * Prefer {@link processLockWorkerOptions}: the port arrives with a message, so
+ * the worker cannot lock during module initialization and must await
+ * {@link processLockAttached} first. The worker side needs no other change -
+ * `withProcessLock` works normally once the port lands.
+ */
+export declare function attachProcessLock(worker: Worker): void;
+/**
+ * In a worker, resolve once the {@link attachProcessLock} port has arrived.
+ *
+ * Only needed on the attach path, and safe to await regardless: it returns
+ * immediately when the worker already has a port (the
+ * {@link processLockWorkerOptions} case) or when called on the main thread, so
+ * shared worker code does not branch on how it was started.
+ *
+ * A `parentPort` listener keeps the worker alive, which is CORRECT here and
+ * deliberately not unref'd: this promise is pending work, and a worker allowed to
+ * exit while awaiting its port would die silently instead of locking. The
+ * listener is removed as soon as the port lands, so the worker is free to exit
+ * again the moment the wait is over.
+ */
+export declare function processLockAttached(): Promise<void>;