embedded-postgres-node 0.0.0-stage → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Fergus Strange
+
+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,114 @@
-# Temporary Holding Version
+# embedded-postgres-node
 
-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.
+Real PostgreSQL for Node.js tests, supervised by the [embedded-postgres v2 CLI](https://github.com/fergusstrange/embedded-postgres/releases/tag/v2.0.0-alpha.1). TypeScript types, ESM and CommonJS, dynamic ports, explicit async cleanup, and **zero runtime npm dependencies**. Use your own PostgreSQL driver, test runner and migration framework.
+
+**Alpha:** `0.1.0-alpha.2` pins CLI `v2.0.0-alpha.1` with verified SHA-256 checksums for all six platforms. The API may change before a stable release. Prereleases use npm's `next` tag.
+
+## Install
+
+```sh
+npm install --save-dev --save-exact embedded-postgres-node@0.1.0-alpha.2
+```
+
+To run the examples from this repository:
+
+```sh
+# In this repository; use Node 22 or 24.
+npm ci
+npm run build
+node --test examples/node-test.mjs
+```
+
+The first startup downloads and verifies the pinned CLI, then acquires PostgreSQL through the CLI's own verified manifest. Later starts reuse verified caches. Consumers do not need Go. PostgreSQL's native runtime-library requirements still apply. No package install script downloads or executes binaries.
+
+`startPostgres()` works without CLI configuration. An explicit `cli: { path }` or `EMBEDDED_POSTGRES_CLI` overrides the default release. To test unpublished source changes in another project, run `npm pack` here and install the resulting tarball there.
+
+## A database for a test
+
+```js
+import { withPostgres } from 'embedded-postgres-node';
+import pg from 'pg'; // Install your own driver as a development dependency.
+
+await withPostgres({}, async database => {
+  const pool = new pg.Pool({ connectionString: database.connectionUrl });
+  try {
+    await pool.query('CREATE TABLE widgets (id integer PRIMARY KEY)');
+    // Run migrations and tests here.
+  } finally {
+    await pool.end();
+  }
+});
+```
+
+`withPostgres` returns your callback's result and awaits cleanup on success or failure. If both fail, it throws an `AggregateError` containing both errors. There are no framework-specific core dependencies or implicit global signal handlers.
+
+For suite-level setup, use `startPostgres()` in your runner's setup hook and `await database.stop()` in teardown. Close pools first. Increase the runner's hook timeout to allow initial binary downloads; share a server only when tests isolate their own schemas or data. Each separately started instance gets its own disposable directory and dynamic port.
+
+Runnable examples:
+
+- [node:test suite](examples/node-test.mjs)
+- [Vitest suite](examples/vitest.test.mjs) and [config](examples/vitest.config.mjs)
+- [Jest suite (CommonJS)](examples/jest.test.cjs) and [config](examples/jest.config.cjs)
+- [Explicit try/finally and scoped helper](examples/scoped.mjs)
+- [User-owned migration and extension setup](examples/migrations.mjs)
+
+## Explicit ownership
+
+```js
+import { startPostgres } from 'embedded-postgres-node';
+
+const database = await startPostgres();
+try {
+  // database.connectionUrl is a credential. Do not log or snapshot it.
+  // database.port is available after an authenticated readiness check.
+} finally {
+  await database.stop(); // Idempotent, including concurrent calls.
+}
+```
+
+An optional `signal` controls the entire database lifetime. Cancellation requests cleanup and reports `PostgresError` with `code: 'ABORTED'`. The signal's reason is not copied into diagnostics. `database.closed` always resolves to an exit result, including errors, so a background failure cannot cause an unhandled promise rejection. Observe it for long-lived suites; `stop()` also reports any failure. `[Symbol.asyncDispose]()` delegates to `stop()` for TypeScript `await using` or runtimes supporting that syntax.
+
+## Configuration
+
+```ts
+const database = await startPostgres({
+  cli: { cacheDir: '/path/to/shared-cli-cache' }, // Optional; uses the pinned CLI.
+  postgresVersion: '18.6.0',
+  database: 'application_test',
+  port: 0,
+  storage: { type: 'disposable', workDir: '/tmp/test-work' },
+  cacheDir: '/path/to/shared-postgres-cache',
+  parameters: { max_connections: '40' },
+  startTimeoutMs: 120_000,
+  stopTimeoutMs: 10_000,
+});
+```
+
+Defaults select a dynamic port and a random password. `workDir` is a parent for private disposable children; it is never recursively erased by the wrapper. For persistence, choose `storage: { type: 'persistent', dataDir: '/path/to/data' }` **and explicit `database`, `username`, and `password`**. Data and the adjacent CLI lease file survive shutdown. Reuse the same credentials on restart; deleting persistent data is your responsibility.
+
+`binaries` supplies an existing PostgreSQL distribution containing `bin/`. `runAs: { uid, gid }` selects an existing non-root Unix account; the wrapper does not invoke sudo or create users. `cliOptions` provides advanced flags, for example `{ offline: true, 'socket-dir': '/tmp/sockets' }`. The CLI rejects unknown flags. Protocol, timeouts, credentials, configuration files and core options cannot be overridden through this escape hatch. Ambient `EP_*` variables are removed from the child environment; use the typed options and explicit escape hatch. Other environment variables are inherited, with additions through `env`.
+
+See the [full API](docs/api.md), [binary acquisition](docs/binaries.md), and [integration and migration guide](docs/integration.md).
+
+## Cleanup and diagnostics
+
+The wrapper spawns `run --json --parent-stdin`, keeps stdin open until teardown, parses protocol 1 incrementally, and waits for **both `stopped` and process exit**. Shutdown uses its own deadline, even after cancellation. The default outer shutdown deadline is `stopTimeoutMs + 5 seconds`; an override must exceed `stopTimeoutMs + 2 seconds`. If it expires, the wrapper terminates only its retained CLI child and reports that PostgreSQL cleanup cannot be confirmed. It waits up to two further seconds for process/pipe closure.
+
+A Node crash or forced Node termination closes the ownership pipe; the CLI and its independent supervisor perform cleanup. Whole-machine failure, simultaneous termination of the supervisor and PostgreSQL, or an unresponsive supervisor cannot be promised graceful cleanup. See [upstream lifecycle limits](https://github.com/fergusstrange/embedded-postgres/blob/v2.0.0-alpha.1/docs/cli.md). Normal application shutdown should await `stop()`; no import installs process signal handlers. If your application owns signals, install handlers there.
+
+Errors expose a stable `code`, a descriptive `message`, and a bounded `stderr` tail. Known passwords and PostgreSQL URLs are redacted; raw protocol, argv, abort reasons and child error causes are not included. Arbitrary custom programs can emit other secrets, so review diagnostics before sharing them. The instance's normal JSON serialization and inspection omit the connection URL; reading the property still returns the real credential.
+
+## Support and development
+
+Node 22 and 24 are the supported LTS lines as of 2026-10-05 ([official schedule](https://github.com/nodejs/Release#release-schedule)); Node 20 is EOL, and Node 26 is not yet LTS. CI is configured for both LTS versions on Linux, macOS and Windows, each on x64 and ARM64. Windows ARM64 uses a native CLI and x64 PostgreSQL under emulation. Linux PostgreSQL runtime libraries are still required; Alpine/musl needs a compatible distribution. See [upstream non-root and native requirements](https://github.com/fergusstrange/embedded-postgres/blob/v2.0.0-alpha.1/docs/non-root.md).
+
+```sh
+npm run check             # Coverage >=90% and installed-tarball smoke/type checks
+npm run check:release     # Fresh verified downloads, real SQL, offline reuse from installed tarball
+npm run test:integration  # Requires EMBEDDED_POSTGRES_CLI; fails if missing
+npm run test:examples     # Runs all three runners and both hook/scoped examples
+```
+
+Integration tests run SQL and verify port/workspace cleanup after teardown, startup failure, abort and Node parent death, plus persistent restarts. The [validation record](docs/validation.md) includes local and native CI results. [Contributing](CONTRIBUTING.md) explains the pinned upstream development build and CI. [Release preparation](docs/releasing.md) describes the review gate; nothing is published automatically on push.
+
+MIT licensed. PostgreSQL distributions retain their own licenses.

package/dist/cjs/binary.d.ts

@@ -0,0 +1,24 @@
+export type CliPlatform = 'linux-amd64' | 'linux-arm64' | 'darwin-amd64' | 'darwin-arm64' | 'windows-amd64' | 'windows-arm64';
+export interface CliRelease {
+    /** Exact published v2 tag. There is deliberately no implicit latest release. */
+    version: string;
+    /** Trusted SHA-256 pins, copied from reviewed upstream release checksums.txt. */
+    checksums: Readonly<Partial<Record<CliPlatform, string>>>;
+    /** Directory containing VERSION/ASSET, defaulting to upstream GitHub releases. */
+    baseUrl?: string;
+}
+/** Reviewed upstream release; every platform asset was checked against checksums.txt. */
+export declare const DEFAULT_CLI_RELEASE: Readonly<CliRelease>;
+export type CliSource = {
+    path: string;
+} | {
+    /** Omit to use this package's reviewed DEFAULT_CLI_RELEASE. */
+    release?: CliRelease;
+    cacheDir?: string;
+    offline?: boolean;
+    downloadTimeoutMs?: number;
+};
+export declare function cliPlatform(platform?: string, arch?: string): CliPlatform;
+export declare function cliAsset(target: CliPlatform): string;
+/** Explicit source, then EMBEDDED_POSTGRES_CLI, then the package's pinned release. */
+export declare function resolveCli(source?: CliSource, signal?: AbortSignal): Promise<string>;

package/dist/cjs/binary.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLI_RELEASE = void 0;
+exports.cliPlatform = cliPlatform;
+exports.cliAsset = cliAsset;
+exports.resolveCli = resolveCli;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.js");
+/** Reviewed upstream release; every platform asset was checked against checksums.txt. */
+exports.DEFAULT_CLI_RELEASE = Object.freeze({
+    version: 'v2.0.0-alpha.1',
+    checksums: Object.freeze({
+        'linux-amd64': '69ef1bd6ca8ec00acf74fe90a5b6204657caa833934aada36591000b90daa7c6',
+        'linux-arm64': '9bb6f2febcf3ce92b678c25aa1e06ae2e0a46a728b6da3ef31709aed2a2493a5',
+        'darwin-amd64': '0f28163e7f346f444d7b3e790205df22e4e92d88acd2de15bd650fa45b114ffb',
+        'darwin-arm64': '97866b33b4a59a5f60a807b55593af162d65f4e4f903696f2c1f638c01de19c0',
+        'windows-amd64': '787e744b5c1c8ae88f77a043d0e3400a220e07e9ce4d03a55b9073a97f4cee6e',
+        'windows-arm64': '07ee6b62c24c0e1a61a3523cf6331560b8a0f64ab780bb5ee6240541a568364d',
+    }),
+});
+function cliPlatform(platform = process.platform, arch = process.arch) {
+    const os = platform === 'win32' ? 'windows' : platform;
+    const cpu = arch === 'x64' ? 'amd64' : arch;
+    if (!['linux', 'darwin', 'windows'].includes(os) || !['amd64', 'arm64'].includes(cpu)) {
+        throw new errors_js_1.PostgresError('BINARY', 'CLI supports Linux, macOS and Windows on x64 and arm64');
+    }
+    return `${os}-${cpu}`;
+}
+function cliAsset(target) {
+    return `embedded-postgres_${target.replace('-', '_')}${target.startsWith('windows-') ? '.exe' : ''}`;
+}
+async function digest(path) {
+    try {
+        const hash = (0, node_crypto_1.createHash)('sha256');
+        for await (const chunk of (0, node_fs_1.createReadStream)(path))
+            hash.update(chunk);
+        return hash.digest('hex');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+const maximumBytes = 128 * 1024 * 1024;
+function validateUrl(url, allowQuery = false) {
+    if (url.username || url.password || (!allowQuery && url.search) || url.hash || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))) {
+        throw new errors_js_1.PostgresError('CONFIG', 'CLI downloads require HTTPS (HTTP is allowed only for loopback mirrors), without credentials, query or fragment');
+    }
+}
+async function download(url, signal) {
+    for (let redirects = 0; redirects <= 5; redirects++) {
+        validateUrl(url, true); // GitHub's asset CDN uses signed query parameters.
+        const response = await fetch(url, { signal, redirect: 'manual' });
+        if (![301, 302, 303, 307, 308].includes(response.status))
+            return response;
+        await response.body?.cancel();
+        const location = response.headers.get('location');
+        if (!location)
+            throw new errors_js_1.PostgresError('BINARY', 'CLI download redirect has no location');
+        url = new URL(location, url);
+    }
+    throw new errors_js_1.PostgresError('BINARY', 'CLI download has too many redirects');
+}
+/** Explicit source, then EMBEDDED_POSTGRES_CLI, then the package's pinned release. */
+async function resolveCli(source, signal) {
+    if (signal?.aborted)
+        throw new errors_js_1.PostgresError('ABORTED', 'CLI resolution aborted');
+    source ??= process.env.EMBEDDED_POSTGRES_CLI ? { path: process.env.EMBEDDED_POSTGRES_CLI } : {};
+    if ('path' in source) {
+        if (!source.path || source.path.includes('\0'))
+            throw new errors_js_1.PostgresError('CONFIG', 'cli.path must name an executable');
+        const path = (0, node_path_1.resolve)(source.path);
+        try {
+            await (0, promises_1.access)(path, node_fs_2.constants.X_OK);
+        }
+        catch {
+            throw new errors_js_1.PostgresError('BINARY', 'Local CLI is missing or not executable');
+        }
+        return path;
+    }
+    const release = source.release ?? exports.DEFAULT_CLI_RELEASE;
+    if (!/^v2\.\d+\.\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(release.version))
+        throw new errors_js_1.PostgresError('CONFIG', 'CLI release must be an exact v2 tag');
+    const target = cliPlatform();
+    const expected = release.checksums[target]?.toLowerCase();
+    if (!expected || !/^[a-f0-9]{64}$/.test(expected))
+        throw new errors_js_1.PostgresError('CONFIG', 'A trusted SHA-256 checksum is required for this CLI platform');
+    const timeout = (0, errors_js_1.positiveTimeout)(source.downloadTimeoutMs ?? 120_000, 'downloadTimeoutMs');
+    let base;
+    try {
+        base = new URL(release.baseUrl ?? 'https://github.com/fergusstrange/embedded-postgres/releases/download/');
+    }
+    catch {
+        throw new errors_js_1.PostgresError('CONFIG', 'Invalid CLI release base URL');
+    }
+    validateUrl(base);
+    base.pathname = base.pathname.replace(/\/?$/, '/');
+    const asset = cliAsset(target);
+    const directory = (0, node_path_1.join)((0, node_path_1.resolve)(source.cacheDir ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.cache', 'embedded-postgres-node')), release.version, expected);
+    const destination = (0, node_path_1.join)(directory, asset);
+    let temporary;
+    try {
+        if (await digest(destination) === expected) {
+            await (0, promises_1.chmod)(destination, 0o700);
+            return destination;
+        }
+        if (source.offline)
+            throw new errors_js_1.PostgresError('BINARY', 'Verified CLI is unavailable in the offline cache');
+        await (0, promises_1.mkdir)(directory, { recursive: true, mode: 0o700 });
+        temporary = (0, node_path_1.join)(directory, `.${asset}.${(0, node_crypto_1.randomUUID)()}.tmp`);
+        const downloadSignal = AbortSignal.any([AbortSignal.timeout(timeout), ...(signal ? [signal] : [])]);
+        const response = await download(new URL(`${release.version}/${asset}`, base), downloadSignal);
+        if (!response.ok || !response.body) {
+            await response.body?.cancel();
+            throw new errors_js_1.PostgresError('BINARY', `CLI download failed (HTTP ${response.status}); verify that the pinned release has been published`);
+        }
+        if (Number(response.headers.get('content-length')) > maximumBytes) {
+            await response.body.cancel();
+            throw new errors_js_1.PostgresError('BINARY', 'CLI download exceeds 128 MiB');
+        }
+        const file = await (0, promises_1.open)(temporary, 'wx', 0o700);
+        const hash = (0, node_crypto_1.createHash)('sha256');
+        let size = 0;
+        try {
+            for await (const chunk of response.body) {
+                size += chunk.byteLength;
+                if (size > maximumBytes)
+                    throw new errors_js_1.PostgresError('BINARY', 'CLI download exceeds 128 MiB');
+                hash.update(chunk);
+                await file.writeFile(chunk);
+            }
+        }
+        finally {
+            await file.close();
+        }
+        if (hash.digest('hex') !== expected)
+            throw new errors_js_1.PostgresError('BINARY', 'CLI checksum mismatch; downloaded binary was not installed');
+        // Atomic replacement; concurrent callers install identical verified bytes.
+        try {
+            await (0, promises_1.rename)(temporary, destination);
+        }
+        catch (error) {
+            if (await digest(destination) !== expected)
+                throw error;
+        }
+        return destination;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw new errors_js_1.PostgresError('ABORTED', 'CLI resolution aborted');
+        if (error instanceof errors_js_1.PostgresError)
+            throw error;
+        if (error.name === 'TimeoutError')
+            throw new errors_js_1.PostgresError('TIMEOUT', 'CLI download deadline exceeded');
+        throw new errors_js_1.PostgresError('BINARY', 'Unable to resolve CLI binary; check network and cache permissions');
+    }
+    finally {
+        if (temporary)
+            await (0, promises_1.rm)(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=binary.js.map

package/dist/cjs/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../../.local/build/src/binary.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport { createReadStream } from 'node:fs';\nimport { access, chmod, mkdir, open, rename, rm } from 'node:fs/promises';\nimport { constants } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join, resolve } from 'node:path';\nimport { PostgresError, positiveTimeout } from './errors.js';\n\nexport type CliPlatform = 'linux-amd64' | 'linux-arm64' | 'darwin-amd64' | 'darwin-arm64' | 'windows-amd64' | 'windows-arm64';\nexport interface CliRelease {\n  /** Exact published v2 tag. There is deliberately no implicit latest release. */\n  version: string;\n  /** Trusted SHA-256 pins, copied from reviewed upstream release checksums.txt. */\n  checksums: Readonly<Partial<Record<CliPlatform, string>>>;\n  /** Directory containing VERSION/ASSET, defaulting to upstream GitHub releases. */\n  baseUrl?: string;\n}\n\n/** Reviewed upstream release; every platform asset was checked against checksums.txt. */\nexport const DEFAULT_CLI_RELEASE: Readonly<CliRelease> = Object.freeze({\n  version: 'v2.0.0-alpha.1',\n  checksums: Object.freeze({\n    'linux-amd64': '69ef1bd6ca8ec00acf74fe90a5b6204657caa833934aada36591000b90daa7c6',\n    'linux-arm64': '9bb6f2febcf3ce92b678c25aa1e06ae2e0a46a728b6da3ef31709aed2a2493a5',\n    'darwin-amd64': '0f28163e7f346f444d7b3e790205df22e4e92d88acd2de15bd650fa45b114ffb',\n    'darwin-arm64': '97866b33b4a59a5f60a807b55593af162d65f4e4f903696f2c1f638c01de19c0',\n    'windows-amd64': '787e744b5c1c8ae88f77a043d0e3400a220e07e9ce4d03a55b9073a97f4cee6e',\n    'windows-arm64': '07ee6b62c24c0e1a61a3523cf6331560b8a0f64ab780bb5ee6240541a568364d',\n  }),\n});\n\nexport type CliSource = { path: string } | {\n  /** Omit to use this package's reviewed DEFAULT_CLI_RELEASE. */\n  release?: CliRelease;\n  cacheDir?: string;\n  offline?: boolean;\n  downloadTimeoutMs?: number;\n};\n\nexport function cliPlatform(platform: string = process.platform, arch: string = process.arch): CliPlatform {\n  const os = platform === 'win32' ? 'windows' : platform;\n  const cpu = arch === 'x64' ? 'amd64' : arch;\n  if (!['linux', 'darwin', 'windows'].includes(os) || !['amd64', 'arm64'].includes(cpu)) {\n    throw new PostgresError('BINARY', 'CLI supports Linux, macOS and Windows on x64 and arm64');\n  }\n  return `${os}-${cpu}` as CliPlatform;\n}\n\nexport function cliAsset(target: CliPlatform): string {\n  return `embedded-postgres_${target.replace('-', '_')}${target.startsWith('windows-') ? '.exe' : ''}`;\n}\n\nasync function digest(path: string): Promise<string | undefined> {\n  try {\n    const hash = createHash('sha256');\n    for await (const chunk of createReadStream(path)) hash.update(chunk);\n    return hash.digest('hex');\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;\n    throw error;\n  }\n}\n\nconst maximumBytes = 128 * 1024 * 1024;\nfunction validateUrl(url: URL, allowQuery = false): void {\n  if (url.username || url.password || (!allowQuery && url.search) || url.hash || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))) {\n    throw new PostgresError('CONFIG', 'CLI downloads require HTTPS (HTTP is allowed only for loopback mirrors), without credentials, query or fragment');\n  }\n}\n\nasync function download(url: URL, signal: AbortSignal): Promise<Response> {\n  for (let redirects = 0; redirects <= 5; redirects++) {\n    validateUrl(url, true); // GitHub's asset CDN uses signed query parameters.\n    const response = await fetch(url, { signal, redirect: 'manual' });\n    if (![301, 302, 303, 307, 308].includes(response.status)) return response;\n    await response.body?.cancel();\n    const location = response.headers.get('location');\n    if (!location) throw new PostgresError('BINARY', 'CLI download redirect has no location');\n    url = new URL(location, url);\n  }\n  throw new PostgresError('BINARY', 'CLI download has too many redirects');\n}\n\n/** Explicit source, then EMBEDDED_POSTGRES_CLI, then the package's pinned release. */\nexport async function resolveCli(source?: CliSource, signal?: AbortSignal): Promise<string> {\n  if (signal?.aborted) throw new PostgresError('ABORTED', 'CLI resolution aborted');\n  source ??= process.env.EMBEDDED_POSTGRES_CLI ? { path: process.env.EMBEDDED_POSTGRES_CLI } : {};\n  if ('path' in source) {\n    if (!source.path || source.path.includes('\\0')) throw new PostgresError('CONFIG', 'cli.path must name an executable');\n    const path = resolve(source.path);\n    try { await access(path, constants.X_OK); } catch { throw new PostgresError('BINARY', 'Local CLI is missing or not executable'); }\n    return path;\n  }\n  const release = source.release ?? DEFAULT_CLI_RELEASE;\n  if (!/^v2\\.\\d+\\.\\d+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(release.version)) throw new PostgresError('CONFIG', 'CLI release must be an exact v2 tag');\n  const target = cliPlatform();\n  const expected = release.checksums[target]?.toLowerCase();\n  if (!expected || !/^[a-f0-9]{64}$/.test(expected)) throw new PostgresError('CONFIG', 'A trusted SHA-256 checksum is required for this CLI platform');\n  const timeout = positiveTimeout(source.downloadTimeoutMs ?? 120_000, 'downloadTimeoutMs');\n  let base: URL;\n  try { base = new URL(release.baseUrl ?? 'https://github.com/fergusstrange/embedded-postgres/releases/download/'); } catch { throw new PostgresError('CONFIG', 'Invalid CLI release base URL'); }\n  validateUrl(base);\n  base.pathname = base.pathname.replace(/\\/?$/, '/');\n  const asset = cliAsset(target);\n  const directory = join(resolve(source.cacheDir ?? join(homedir(), '.cache', 'embedded-postgres-node')), release.version, expected);\n  const destination = join(directory, asset);\n  let temporary: string | undefined;\n  try {\n    if (await digest(destination) === expected) {\n      await chmod(destination, 0o700);\n      return destination;\n    }\n    if (source.offline) throw new PostgresError('BINARY', 'Verified CLI is unavailable in the offline cache');\n    await mkdir(directory, { recursive: true, mode: 0o700 });\n    temporary = join(directory, `.${asset}.${randomUUID()}.tmp`);\n    const downloadSignal = AbortSignal.any([AbortSignal.timeout(timeout), ...(signal ? [signal] : [])]);\n    const response = await download(new URL(`${release.version}/${asset}`, base), downloadSignal);\n    if (!response.ok || !response.body) {\n      await response.body?.cancel();\n      throw new PostgresError('BINARY', `CLI download failed (HTTP ${response.status}); verify that the pinned release has been published`);\n    }\n    if (Number(response.headers.get('content-length')) > maximumBytes) {\n      await response.body.cancel();\n      throw new PostgresError('BINARY', 'CLI download exceeds 128 MiB');\n    }\n    const file = await open(temporary, 'wx', 0o700);\n    const hash = createHash('sha256');\n    let size = 0;\n    try {\n      for await (const chunk of response.body) {\n        size += chunk.byteLength;\n        if (size > maximumBytes) throw new PostgresError('BINARY', 'CLI download exceeds 128 MiB');\n        hash.update(chunk);\n        await file.writeFile(chunk);\n      }\n    } finally { await file.close(); }\n    if (hash.digest('hex') !== expected) throw new PostgresError('BINARY', 'CLI checksum mismatch; downloaded binary was not installed');\n    // Atomic replacement; concurrent callers install identical verified bytes.\n    try { await rename(temporary, destination); } catch (error) {\n      if (await digest(destination) !== expected) throw error;\n    }\n    return destination;\n  } catch (error) {\n    if (signal?.aborted) throw new PostgresError('ABORTED', 'CLI resolution aborted');\n    if (error instanceof PostgresError) throw error;\n    if ((error as Error).name === 'TimeoutError') throw new PostgresError('TIMEOUT', 'CLI download deadline exceeded');\n    throw new PostgresError('BINARY', 'Unable to resolve CLI binary; check network and cache permissions');\n  } finally {\n    if (temporary) await rm(temporary, { force: true });\n  }\n}\n"]}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,9 @@
+export type ErrorCode = 'CONFIG' | 'BINARY' | 'SPAWN' | 'PROTOCOL' | 'STARTUP' | 'TIMEOUT' | 'ABORTED' | 'EXIT' | 'SHUTDOWN';
+/** Diagnostics deliberately omit command arguments, raw protocol and error causes. */
+export declare class PostgresError extends Error {
+    readonly code: ErrorCode;
+    readonly stderr: string;
+    constructor(code: ErrorCode, message: string, stderr?: string);
+}
+export declare function redact(text: string, secrets: readonly string[]): string;
+export declare function positiveTimeout(value: number, name: string): number;

package/dist/cjs/errors.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresError = void 0;
+exports.redact = redact;
+exports.positiveTimeout = positiveTimeout;
+/** Diagnostics deliberately omit command arguments, raw protocol and error causes. */
+class PostgresError extends Error {
+    code;
+    stderr;
+    constructor(code, message, stderr = '') {
+        super(message);
+        this.name = 'PostgresError';
+        this.code = code;
+        this.stderr = stderr;
+    }
+}
+exports.PostgresError = PostgresError;
+function redact(text, secrets) {
+    // Redact complete URLs, including Unix-socket URLs and query parameters.
+    let result = text.replace(/postgres(?:ql)?:\/\/[^\s"'<>]+/gi, '[redacted connection URL]');
+    for (const secret of secrets) {
+        if (secret) {
+            result = result.split(secret).join('[redacted]');
+            result = result.split(encodeURIComponent(secret)).join('[redacted]');
+        }
+    }
+    return result;
+}
+function positiveTimeout(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647) {
+        throw new PostgresError('CONFIG', `${name} must be an integer between 1 and 2147483647 milliseconds`);
+    }
+    return value;
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../.local/build/src/errors.ts"],"names":[],"mappings":";;;;;AAEA,sFAAsF;AACtF,mBAA2B,SAAQ,KAAK;IAC7B,IAAI,CAAY;IAChB,MAAM,CAAS;IACxB,YAAY,IAAe,EAAE,OAAe,EAAE,MAAM,GAAG,EAAE;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;;AAED,gBAAuB,IAAY,EAAE,OAA0B;IAC7D,yEAAyE;IACzE,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,kCAAkC,EAAE,2BAA2B,CAAC,CAAC;IAC3F,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,yBAAgC,KAAa,EAAE,IAAY;IACzD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,aAAa,EAAE,CAAC;QACvE,MAAM,IAAI,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,2DAA2D,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["export type ErrorCode = 'CONFIG' | 'BINARY' | 'SPAWN' | 'PROTOCOL' | 'STARTUP' | 'TIMEOUT' | 'ABORTED' | 'EXIT' | 'SHUTDOWN';\n\n/** Diagnostics deliberately omit command arguments, raw protocol and error causes. */\nexport class PostgresError extends Error {\n  readonly code: ErrorCode;\n  readonly stderr: string;\n  constructor(code: ErrorCode, message: string, stderr = '') {\n    super(message);\n    this.name = 'PostgresError';\n    this.code = code;\n    this.stderr = stderr;\n  }\n}\n\nexport function redact(text: string, secrets: readonly string[]): string {\n  // Redact complete URLs, including Unix-socket URLs and query parameters.\n  let result = text.replace(/postgres(?:ql)?:\\/\\/[^\\s\"'<>]+/gi, '[redacted connection URL]');\n  for (const secret of secrets) {\n    if (secret) {\n      result = result.split(secret).join('[redacted]');\n      result = result.split(encodeURIComponent(secret)).join('[redacted]');\n    }\n  }\n  return result;\n}\n\nexport function positiveTimeout(value: number, name: string): number {\n  if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647) {\n    throw new PostgresError('CONFIG', `${name} must be an integer between 1 and 2147483647 milliseconds`);\n  }\n  return value;\n}\n"]}

package/dist/cjs/index.d.ts

@@ -0,0 +1,7 @@
+export { startPostgres, withPostgres } from './lifecycle.js';
+export type { PostgresInstance, ExitResult } from './lifecycle.js';
+export type { PostgresOptions } from './options.js';
+export { resolveCli, cliPlatform, DEFAULT_CLI_RELEASE } from './binary.js';
+export type { CliSource, CliRelease, CliPlatform } from './binary.js';
+export { PostgresError } from './errors.js';
+export type { ErrorCode } from './errors.js';

package/dist/cjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresError = exports.DEFAULT_CLI_RELEASE = exports.cliPlatform = exports.resolveCli = exports.withPostgres = exports.startPostgres = void 0;
+var lifecycle_js_1 = require("./lifecycle.js");
+Object.defineProperty(exports, "startPostgres", { enumerable: true, get: function () { return lifecycle_js_1.startPostgres; } });
+Object.defineProperty(exports, "withPostgres", { enumerable: true, get: function () { return lifecycle_js_1.withPostgres; } });
+var binary_js_1 = require("./binary.js");
+Object.defineProperty(exports, "resolveCli", { enumerable: true, get: function () { return binary_js_1.resolveCli; } });
+Object.defineProperty(exports, "cliPlatform", { enumerable: true, get: function () { return binary_js_1.cliPlatform; } });
+Object.defineProperty(exports, "DEFAULT_CLI_RELEASE", { enumerable: true, get: function () { return binary_js_1.DEFAULT_CLI_RELEASE; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "PostgresError", { enumerable: true, get: function () { return errors_js_1.PostgresError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../.local/build/src/index.ts"],"names":[],"mappings":";;;AAAA,+CAA6D;AAApD,6GAAA,aAAa,OAAA;AAAE,4GAAA,YAAY,OAAA;AAGpC,yCAA2E;AAAlE,uGAAA,UAAU,OAAA;AAAE,wGAAA,WAAW,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAErD,yCAA4C;AAAnC,0GAAA,aAAa,OAAA","sourcesContent":["export { startPostgres, withPostgres } from './lifecycle.js';\nexport type { PostgresInstance, ExitResult } from './lifecycle.js';\nexport type { PostgresOptions } from './options.js';\nexport { resolveCli, cliPlatform, DEFAULT_CLI_RELEASE } from './binary.js';\nexport type { CliSource, CliRelease, CliPlatform } from './binary.js';\nexport { PostgresError } from './errors.js';\nexport type { ErrorCode } from './errors.js';\n"]}

package/dist/cjs/lifecycle.d.ts

@@ -0,0 +1,21 @@
+import { PostgresError } from './errors.js';
+import type { PostgresOptions } from './options.js';
+export interface ExitResult {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stopped: boolean;
+    readonly error?: PostgresError;
+}
+export interface PostgresInstance extends AsyncDisposable {
+    /** A credential: do not log or snapshot it. */
+    readonly connectionUrl: string;
+    readonly port: number;
+    /** Resolves on termination; never rejects, so ignoring it cannot cause an unhandled rejection. */
+    readonly closed: Promise<ExitResult>;
+    /** Closes stdin and waits for stopped and process exit. Repeated calls share one result. */
+    stop(): Promise<void>;
+}
+/** Start a database whose lifetime is owned by the caller (or its AbortSignal). */
+export declare function startPostgres(options?: PostgresOptions): Promise<PostgresInstance>;
+/** User-owned migrations/pools belong inside fn; close pools before fn returns. */
+export declare function withPostgres<T>(options: PostgresOptions, fn: (postgres: PostgresInstance) => Promise<T>): Promise<T>;