@filelayer/core 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -21,9 +21,74 @@ embarrassing. A changelog that only records features is a marketing document.
 
 ---
 
-## [Unreleased] — group grant subjects (RFC-001)
-
-Breaking schema change, additive API. Migration: `MIGRATIONS.md` Entry 2.
+## [Unreleased]
+
+Two things: **packaging** — the published tarball now has no runtime
+dependencies at all — and **group grant subjects** (RFC-001), a breaking schema
+change with an additive API whose migration is `MIGRATIONS.md` Entry 2.
+
+### Changed — packaging
+
+- **`@electric-sql/pglite` is no longer a runtime dependency.** It was the only
+  one, and it should never have been one: it is an embedded WebAssembly
+  PostgreSQL, and a library whose entire premise is "run it against your own
+  Postgres" has no business putting a second Postgres into every production
+  `node_modules`. It is used by exactly two functions — `createTestDb()` and the
+  `Filelayer.quickstart()` built on it — and both are development helpers.
+  - It is now a **`devDependency`** (the suite needs it) *and* an **optional
+    peer dependency** (`peerDependenciesMeta.optional: true`). A consumer who
+    wants `createTestDb()` is told what to install and at which version range; a
+    consumer who does not gets no install warning and no WASM blob.
+  - **Installing `@filelayer/core` now installs one package.** Asserted from
+    inside the installed copy by the release gate and by the packaging job, so
+    a runtime dependency cannot be reintroduced without a red build.
+  - **Nothing about the public API changed.** `createTestDb`, `SCHEMA_PATH` and
+    `loadSchemaSql` are exported exactly as before, and production code — a
+    `pg.Pool` (or anything satisfying `Queryable`) passed to `new Filelayer()` —
+    never touches the removed dependency. If you use `quickstart()` or
+    `createTestDb()`, add
+    `npm install --save-dev "@electric-sql/pglite@^0.3.11"`.
+- **`createTestDb()` without PGlite installed now explains itself.** It used to
+  surface Node's raw `ERR_MODULE_NOT_FOUND` from inside `dist/`, naming a
+  package the caller never asked for. It now throws an error that names
+  `@electric-sql/pglite`, gives the exact install command, says why the package
+  is optional, and points at the production alternative (`pg.Pool` plus
+  `psql -f node_modules/@filelayer/core/schema.sql`). The original resolution
+  error is preserved as `cause`. A resolution failure *inside* PGlite — a broken
+  install rather than a missing one — is passed through untouched.
+- **The release gate now runs the whole lifecycle twice, in both shapes.** Once
+  in the shape a production consumer installs — the packed tarball and nothing
+  else, no embedded database on disk, driven against a real PostgreSQL server
+  through `pg` — and once through `Filelayer.quickstart()` after explicitly
+  installing the optional peer dependency. The assertions are written once and
+  run in both. It also asserts that a missing optional peer produces no install
+  warning, and that `createTestDb()`'s error names the package and the command.
+
+### Added — testing
+
+- **The live S3/R2 suite now runs in CI.** `test/s3-live.test.ts` has always
+  skipped itself without credentials; it now has a job that runs it when the
+  repository secrets are present. This is the code path every download goes
+  through, and a local harness that verifies signatures cannot speak for TLS,
+  real IAM evaluation, R2's divergences from S3, read-after-write visibility or
+  the error codes a real store returns.
+  - **A fork does not go red.** Secrets are unavailable to pull requests from
+    forks, so the job decides for itself whether it has credentials and skips
+    the work if not.
+  - **The skip is visible.** It is written to the job summary and raised as a
+    workflow notice, naming the missing secrets. A green tick that ran nothing
+    is worse than an honest "skipped: no credentials", because the two look
+    identical. The converse is checked too: credentials present and the suite
+    skipping itself anyway is a **failure**, not a pass.
+  - **`docs/LIVE-S3-TESTS.md`** is the single place the bucket, the minimal R2
+    token / IAM policy and the exact secret names are specified. The test file
+    header used to restate them and now points at it.
+  - The multipart test (~11 MB of uploads) runs on a nightly schedule and on
+    manual dispatch, rather than on every push.
+- Fixed while wiring the above: an *empty* `FILELAYER_TEST_S3_PREFIX` — what a
+  workflow hands you for an unset repository variable — was taken as a real
+  value by `??`, rooting every test key at `/` instead of under the prefix the
+  cleanup deletes.
 
 ### Fixed
 
@@ -103,6 +168,134 @@ Breaking schema change, additive API. Migration: `MIGRATIONS.md` Entry 2.
 
 ---
 
+## [0.4.1] — 2026-09-06
+
+A single defect, in the first command a new user runs. Nothing else changed: no
+API change, no schema change, no behaviour change. If you already have a working
+install, this release does nothing for you.
+
+### Fixed
+
+- **The documented command for installing PGlite could not resolve against the
+  peer range this package declares.** `0.4.0` declares
+  `peerDependencies: { "@electric-sql/pglite": "^0.3.11" }`, as an optional peer.
+  The install command in the `createTestDb()` error message, in `README.md`, in
+  `docs/QUICKSTART.md`, in `llms.txt` and in the changelog entry above carried no
+  version at all. PGlite's `latest` on npm is `0.5.8`, outside `^0.3.11`, so
+  following our own written instructions could put a version on disk that the
+  declared range does not admit — and npm then refuses the whole tree:
+
+  ```
+  npm error Could not resolve dependency:
+  npm error peerOptional @electric-sql/pglite@"^0.3.11" from @filelayer/core@0.4.0
+  ```
+
+  It is deterministic for anyone whose project already has PGlite, or who asks
+  for a specific version, and it is a hard stop about sixty seconds in. Every
+  install command in this repository is now version-explicit:
+
+  ```bash
+  npm install --save-dev "@electric-sql/pglite@^0.3.11"
+  ```
+
+  The quotes are for the shell, not for npm — `^` is a glob operator under `zsh`
+  with `extendedglob` and an escape character in `cmd.exe`, and a command that
+  breaks in a common shell is the same defect wearing a different hat.
+
+### Not changed, deliberately
+
+- **The peer range is still `^0.3.11`. PGlite 0.5.x is not supported.** Before
+  choosing between widening the range and fixing the instructions, the full
+  suite was run against `0.5.8`. It does not pass. `tsc --noEmit` is clean and
+  every assertion that executes passes, but seven test files are killed by the
+  operating system and the run aborts after 92 of 313 tests. Reproduced in
+  isolation with 3.6 GB free, so it is not a plain out-of-memory: one suite runs
+  20 of 21 subtests green and is then killed. Against `0.3.16` the identical
+  suite is 313 of 313.
+
+  We have not diagnosed it further, because the supported range is the decision
+  in front of us and the cause is upstream. What we will not do is widen the
+  range to whatever npm installs by default and describe an untested
+  configuration as supported. When 0.5.x passes, the range moves and this entry
+  gets a successor.
+
+### Added
+
+- **`tools/check-install-commands.mjs`, wired into `npm run verify`.** It reads
+  every tracked file and fails the build if an install command names a
+  version-constrained package without a version constraint, or pins one to a
+  range that is not the range `packages/core/package.json` declares. The
+  comparison is semver intervals rather than string equality and runs in both
+  directions, so widening the peer range without updating the documentation
+  fails, and so does the reverse. No network and no install: it is a check on
+  what we wrote, evaluated against what we declared.
+
+  It carries a negative control that runs on every invocation, before the real
+  scan: fourteen commands whose correct classification is known — including the
+  exact unversioned command `0.4.0` shipped, in each of the five forms it was
+  written in — plus seven pieces of text that must *not* be read as install
+  commands. If the detector misclassifies any of them the check exits `2` and
+  says the detector is broken rather than reporting a clean repository. A
+  checker that has never rejected anything is a green tick of unknown value.
+
+### Changed
+
+- **The release gate now runs the documented command instead of its own.**
+  `tools/verify-release.mjs` reads the install command out of `README.md` at run
+  time and executes that string in its empty consumer directory. It used to
+  write its own equivalent, which is why a green gate and a broken instruction
+  could coexist for a whole release: the gate was testing a command no user
+  would ever type.
+- **The gate also installs in the other order.** Phases 1 and 2 install the
+  package first and PGlite second, and in that order npm can rescue a bad
+  instruction by quietly walking `latest` back into the peer range — which is
+  precisely how `0.4.0`'s command passed. A new phase does it the other way
+  round, in a second directory that has never contained anything: the documented
+  command first, then `@filelayer/core` on top. There is nothing left to rescue
+  there, so the resolution failure is either real or absent. It asserts, too,
+  that the version actually installed satisfies the declared range, because an
+  install that succeeds by giving the reader something other than what they
+  asked for is still a broken instruction.
+- `README.md`, `docs/QUICKSTART.md` and the `createTestDb()` error message now
+  state the supported range in words as well as in the command: the 0.3.x line
+  is supported, 0.5.x is not, and the reason is that the suite does not pass
+  against it.
+
+---
+
+## [0.4.0] — 2026-09-06
+
+### Changed
+
+- **`@electric-sql/pglite` is no longer a runtime dependency.** It is now a
+  dev dependency and an *optional* peer. The published package declares zero
+  runtime dependencies. A library whose premise is "run it against your own
+  Postgres" should not install an embedded WASM Postgres into every production
+  deployment; it did, and that was wrong.
+  `createTestDb()` and `Filelayer.quickstart()` still need it, and now say so
+  with an actionable message instead of a module-resolution error. If you use
+  either in tests, add
+  `npm install --save-dev "@electric-sql/pglite@^0.3.11"`. Nothing
+  else changes; production code paths never imported it.
+
+  *(The command in this entry originally omitted the version constraint. That
+  omission is the defect fixed in 0.4.1, and the command has been corrected here
+  so that nobody reading the history copies the broken one.)*
+
+### Added
+
+- A CI job that exercises the S3/R2 storage adapter against live object storage
+  when credentials are configured, and states plainly in the build summary when
+  they are not. See `docs/LIVE-S3-TESTS.md`.
+- `TRUST.md` — the current state of this project in numbers, including the ones
+  that are zero, and what would change them.
+
+### Fixed
+
+- `FILELAYER_TEST_S3_PREFIX` used `??` rather than `||`, so the empty string CI
+  supplies for an unset variable became a real value and rooted test objects at
+  the bucket root instead of under the prefix cleanup deletes.
+
 ## [0.3.0] — 2026-09-05
 
 The release that makes the package installable, and the one that closes the

package/NOTICE

@@ -16,20 +16,23 @@ and anyone reviewing this distribution's licence obligations. It is
 NOT a required attribution notice under Apache-2.0 section 4(d), and
 redistributors of Filelayer do not inherit an obligation to reproduce it.
 
-Filelayer has exactly one runtime dependency:
+Filelayer has NO runtime dependencies. Installing @filelayer/core installs
+@filelayer/core and nothing else. One third-party package is used, and only
+outside production:
 
   @electric-sql/pglite
     PostgreSQL compiled to WebAssembly, used for the embedded database in
-    `Filelayer.quickstart()` and in the test suite.
+    `Filelayer.quickstart()`, in `createTestDb()` and in the test suite.
     Licensed under the Apache License, Version 2.0.
     https://github.com/electric-sql/pglite
 
-  It is declared as a normal npm dependency and is installed from the
-  registry by the consumer. No part of it is vendored into, copied into, or
-  redistributed inside this repository or the published tarball, so this
-  distribution is not a Derivative Work of it. It ships no NOTICE file of
-  its own, so Apache-2.0 section 4(d) imposes no propagation requirement
-  even where a redistributor bundles it.
+  It is declared as a devDependency and as an OPTIONAL peer dependency, so a
+  consumer who does not call those two helpers never installs it. When it is
+  installed it comes from the registry. No part of it is vendored into,
+  copied into, or redistributed inside this repository or the published
+  tarball, so this distribution is not a Derivative Work of it. It ships no
+  NOTICE file of its own, so Apache-2.0 section 4(d) imposes no propagation
+  requirement even where a redistributor bundles it.
 
 No other third-party code is vendored, copied or embedded in this
 distribution. The comparison implementations under `benchmark/` are original

package/README.md

@@ -12,6 +12,9 @@
      resolve on their own with no edit here. The licence badge is live now. -->
 
 > ## ⚠️ Alpha — developer preview. Not production software.
+
+> **[Should you depend on this?](https://github.com/filelayer/filelayer/blob/main/TRUST.md)** — the real numbers, including the ones
+> that are zero, and exactly what would change them.
 >
 > We would rather you trust us later for good reasons than trust us now for bad
 > ones, so here is the honest state of this project.
@@ -184,6 +187,26 @@ declarations in `dist/`; the TypeScript source and the full test suite are in
 the tarball as well, so every claim on this page is inspectable from what you
 installed.
 
+**That install has zero runtime dependencies.** Filelayer talks to *your*
+Postgres and *your* bucket, so it ships neither. The throwaway instance below is
+the one exception: `quickstart()` runs on an embedded WebAssembly Postgres,
+declared as an *optional peer dependency* so that it never lands in a production
+`node_modules`. Add it if you want the throwaway instance, and skip it
+otherwise — `createTestDb()` will tell you, by name, if you need it:
+
+```bash
+npm install --save-dev "@electric-sql/pglite@^0.3.11"
+```
+
+**Install PGlite with that version constraint.** Filelayer supports the
+**0.3.x** line, which is what `peerDependencies` declares and what the suite runs
+against. **0.5.x is not supported**: we ran the full suite against 0.5.8 and it
+does not pass, so the range has not been widened. PGlite's `latest` on npm is a
+0.5.x release, so omitting the constraint can install a version outside the
+supported range — and npm then refuses the whole tree with `ERESOLVE`. The quotes
+are for your shell, not for npm: `^` is a glob operator under `zsh` with
+`extendedglob` and an escape character in `cmd.exe`.
+
 ```ts
 import { Filelayer } from '@filelayer/core';
 
@@ -278,11 +301,13 @@ tarball, so the grant travels with the artifact rather than only with the
 repository. There are no per-file licence headers — the grant is carried by
 `LICENSE`, `NOTICE` and the `license` field of every `package.json`.
 
-**Dependencies.** Filelayer has exactly one runtime dependency,
-[`@electric-sql/pglite`](https://github.com/electric-sql/pglite), itself
-Apache-2.0. It is installed from the registry rather than vendored, ships no
-`NOTICE` file of its own, and is recorded in ours for convenience. No
-third-party code is copied or embedded anywhere in this repository.
+**Dependencies.** Filelayer has **no runtime dependencies**. Its one third-party
+package, [`@electric-sql/pglite`](https://github.com/electric-sql/pglite)
+(Apache-2.0), is a `devDependency` and an *optional peer dependency*: the test
+suite and `quickstart()` run on it, and a production install does not contain
+it. It is installed from the registry rather than vendored, ships no `NOTICE`
+file of its own, and is recorded in ours for convenience. No third-party code is
+copied or embedded anywhere in this repository.
 
 ## Contributing, security and conduct
 

package/dist/db.d.ts

@@ -135,6 +135,10 @@ export declare function loadSchemaSql(): Promise<string>;
  * real enums, real arrays, real rules, real transactional semantics. The one
  * thing it is NOT is multi-process, which matters for exactly one test; see
  * test/security.test.ts, "atomic download cap", for what that weakens.
+ *
+ * REQUIRES the optional peer dependency `@electric-sql/pglite`. Production code
+ * does not need it: hand `new Filelayer(...)` your own `pg.Pool`, or anything
+ * else that satisfies `Queryable`, and this function is never reached.
  */
 export declare function createTestDb(): Promise<{
     db: Queryable & {

package/dist/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAMH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACpE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,EAAG,SAAQ,SAAS;IACnC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;IAC7B,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChD;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,EAAE,IAAI,EAAE,CAE5C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBACZ,KAAK,EAAE,OAAO;CAK3B;AAoBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAqCZ;AA6CD,eAAO,MAAM,WAAW,QAAiC,CAAC;AAE1D,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAErD;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC;IAC5C,EAAE,EAAE,SAAS,GAAG;QAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAC3C,GAAG,EAAE,OAAO,CAAC;CACd,CAAC,CAOD"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAMH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACpE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,EAAG,SAAQ,SAAS;IACnC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;IAC7B,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChD;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,EAAE,IAAI,EAAE,CAE5C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBACZ,KAAK,EAAE,OAAO;CAK3B;AAoBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAqCZ;AA6CD,eAAO,MAAM,WAAW,QAAiC,CAAC;AAE1D,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAErD;AAiDD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC;IAC5C,EAAE,EAAE,SAAS,GAAG;QAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAC3C,GAAG,EAAE,OAAO,CAAC;CACd,CAAC,CAMD"}

package/dist/db.js

@@ -198,6 +198,51 @@ export const SCHEMA_PATH = join(HERE, '..', 'schema.sql');
 export async function loadSchemaSql() {
     return readFile(SCHEMA_PATH, 'utf8');
 }
+/**
+ * The one package this library needs and deliberately does not depend on.
+ *
+ * PGlite is an embedded WASM build of PostgreSQL. It is what `createTestDb()`
+ * and `Filelayer.quickstart()` run on, and it is superb for that -- but a
+ * library whose premise is "point it at YOUR Postgres" has no business putting
+ * a second Postgres into every production `node_modules`. So it is declared as
+ * an OPTIONAL PEER DEPENDENCY: named, version-ranged and discoverable, but not
+ * installed for anyone who never calls the two helpers that use it.
+ *
+ * The cost of that choice is this constant and the `catch` below. Without them
+ * the failure mode for a consumer who calls `createTestDb()` is a raw
+ * ERR_MODULE_NOT_FOUND naming a package they never asked for, from a stack
+ * inside our `dist`, and no indication that installing one thing fixes it.
+ */
+const PGLITE = '@electric-sql/pglite';
+/**
+ * The install command a caller is handed, spelled out in full.
+ *
+ * The version constraint is not decoration. PGlite's `latest` on npm is a 0.5.x
+ * release and this package declares `peerDependencies` of `^0.3.11`, so an
+ * install with no constraint on it can land a version outside the declared
+ * range -- at which point npm refuses the whole tree with ERESOLVE and the
+ * developer is stuck one minute in, having typed what we told them to type.
+ * That happened; it is the defect 0.4.1 fixes.
+ *
+ * The range is a literal rather than a template so that
+ * `tools/check-install-commands.mjs` can read it out of this file and fail the
+ * build if it ever stops matching `peerDependencies` in package.json. The two
+ * are the same fact written in two places, and the check is what keeps them
+ * one fact.
+ *
+ * The quotes are for the shell, not for npm: `^` is a glob operator under zsh
+ * with `extendedglob`, and an escape character in cmd.exe.
+ */
+const PGLITE_INSTALL = 'npm install --save-dev "@electric-sql/pglite@^0.3.11"';
+/** True when `err` is Node refusing to resolve `spec`, and not some other failure. */
+function isModuleNotFound(err, spec) {
+    const code = err?.code;
+    if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND')
+        return false;
+    // A resolution failure *inside* pglite itself is a broken install, not a
+    // missing one, and must not be reported as "run npm install".
+    return String(err.message ?? '').includes(spec);
+}
 /**
  * Create an in-process Postgres (PGlite) with the Filelayer schema applied.
  *
@@ -205,13 +250,52 @@ export async function loadSchemaSql() {
  * real enums, real arrays, real rules, real transactional semantics. The one
  * thing it is NOT is multi-process, which matters for exactly one test; see
  * test/security.test.ts, "atomic download cap", for what that weakens.
+ *
+ * REQUIRES the optional peer dependency `@electric-sql/pglite`. Production code
+ * does not need it: hand `new Filelayer(...)` your own `pg.Pool`, or anything
+ * else that satisfies `Queryable`, and this function is never reached.
  */
 export async function createTestDb() {
-    const { PGlite } = await import('@electric-sql/pglite');
-    const { pgcrypto } = await import('@electric-sql/pglite/contrib/pgcrypto');
+    const { PGlite, pgcrypto } = await importPglite();
     const pg = await PGlite.create({ extensions: { pgcrypto } });
     const sql = await loadSchemaSql();
     await pg.exec(sql);
     return { db: pg, raw: pg };
 }
+async function importPglite() {
+    try {
+        const [mod, contrib] = await Promise.all([
+            import('@electric-sql/pglite'),
+            import('@electric-sql/pglite/contrib/pgcrypto'),
+        ]);
+        return { PGlite: mod.PGlite, pgcrypto: contrib.pgcrypto };
+    }
+    catch (err) {
+        if (!isModuleNotFound(err, PGLITE))
+            throw err;
+        throw new Error(`createTestDb() needs "${PGLITE}", which is not installed.\n` +
+            `\n` +
+            `  ${PGLITE_INSTALL}\n` +
+            `\n` +
+            `The version is part of the command. @filelayer/core supports the 0.3.x line\n` +
+            `of ${PGLITE}; 0.5.x is not supported, because the test suite does\n` +
+            `not pass against it. Installing without the constraint can resolve to a\n` +
+            `version outside the supported range, and npm then refuses the install with\n` +
+            `ERESOLVE rather than giving you a working tree.\n` +
+            `\n` +
+            `It is an OPTIONAL peer dependency of @filelayer/core, on purpose: it is an\n` +
+            `embedded WASM PostgreSQL used by createTestDb() and Filelayer.quickstart()\n` +
+            `for tests and local development, and shipping it to production installs of\n` +
+            `a library that talks to your own Postgres would be wrong.\n` +
+            `\n` +
+            `In production, do not call this. Pass your own database instead:\n` +
+            `\n` +
+            `  import { Pool } from 'pg';\n` +
+            `  new Filelayer(new Pool({ connectionString: process.env.DATABASE_URL }), storage, opts)\n` +
+            `\n` +
+            `and apply the schema once with:\n` +
+            `\n` +
+            `  psql "$DATABASE_URL" -f node_modules/@filelayer/core/schema.sql\n`, { cause: err });
+    }
+}
 //# sourceMappingURL=db.js.map

package/dist/db.js.map

@@ -1 +1 @@
-{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@filelayer/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Multi-tenant file authorization and lifecycle for Postgres: one decision point for public and private files, revocable URLs, delegated share links and a hash-chained audit trail.",
   "license": "Apache-2.0",
   "type": "module",
@@ -67,10 +67,16 @@
     "typecheck": "tsc --noEmit",
     "verify": "npm run typecheck && npm test && npm run build"
   },
-  "dependencies": {
+  "peerDependencies": {
     "@electric-sql/pglite": "^0.3.11"
   },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.11",
     "typescript": "^5.7.0",
     "@types/node": "^22.10.0"
   }

package/src/db.ts

@@ -250,6 +250,53 @@ export async function loadSchemaSql(): Promise<string> {
   return readFile(SCHEMA_PATH, 'utf8');
 }
 
+/**
+ * The one package this library needs and deliberately does not depend on.
+ *
+ * PGlite is an embedded WASM build of PostgreSQL. It is what `createTestDb()`
+ * and `Filelayer.quickstart()` run on, and it is superb for that -- but a
+ * library whose premise is "point it at YOUR Postgres" has no business putting
+ * a second Postgres into every production `node_modules`. So it is declared as
+ * an OPTIONAL PEER DEPENDENCY: named, version-ranged and discoverable, but not
+ * installed for anyone who never calls the two helpers that use it.
+ *
+ * The cost of that choice is this constant and the `catch` below. Without them
+ * the failure mode for a consumer who calls `createTestDb()` is a raw
+ * ERR_MODULE_NOT_FOUND naming a package they never asked for, from a stack
+ * inside our `dist`, and no indication that installing one thing fixes it.
+ */
+const PGLITE = '@electric-sql/pglite';
+
+/**
+ * The install command a caller is handed, spelled out in full.
+ *
+ * The version constraint is not decoration. PGlite's `latest` on npm is a 0.5.x
+ * release and this package declares `peerDependencies` of `^0.3.11`, so an
+ * install with no constraint on it can land a version outside the declared
+ * range -- at which point npm refuses the whole tree with ERESOLVE and the
+ * developer is stuck one minute in, having typed what we told them to type.
+ * That happened; it is the defect 0.4.1 fixes.
+ *
+ * The range is a literal rather than a template so that
+ * `tools/check-install-commands.mjs` can read it out of this file and fail the
+ * build if it ever stops matching `peerDependencies` in package.json. The two
+ * are the same fact written in two places, and the check is what keeps them
+ * one fact.
+ *
+ * The quotes are for the shell, not for npm: `^` is a glob operator under zsh
+ * with `extendedglob`, and an escape character in cmd.exe.
+ */
+const PGLITE_INSTALL = 'npm install --save-dev "@electric-sql/pglite@^0.3.11"';
+
+/** True when `err` is Node refusing to resolve `spec`, and not some other failure. */
+function isModuleNotFound(err: unknown, spec: string): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND') return false;
+  // A resolution failure *inside* pglite itself is a broken install, not a
+  // missing one, and must not be reported as "run npm install".
+  return String((err as Error).message ?? '').includes(spec);
+}
+
 /**
  * Create an in-process Postgres (PGlite) with the Filelayer schema applied.
  *
@@ -257,15 +304,59 @@ export async function loadSchemaSql(): Promise<string> {
  * real enums, real arrays, real rules, real transactional semantics. The one
  * thing it is NOT is multi-process, which matters for exactly one test; see
  * test/security.test.ts, "atomic download cap", for what that weakens.
+ *
+ * REQUIRES the optional peer dependency `@electric-sql/pglite`. Production code
+ * does not need it: hand `new Filelayer(...)` your own `pg.Pool`, or anything
+ * else that satisfies `Queryable`, and this function is never reached.
  */
 export async function createTestDb(): Promise<{
   db: Queryable & { close(): Promise<void> };
   raw: unknown;
 }> {
-  const { PGlite } = await import('@electric-sql/pglite');
-  const { pgcrypto } = await import('@electric-sql/pglite/contrib/pgcrypto');
+  const { PGlite, pgcrypto } = await importPglite();
   const pg = await PGlite.create({ extensions: { pgcrypto } });
   const sql = await loadSchemaSql();
   await pg.exec(sql);
   return { db: pg as unknown as Queryable & { close(): Promise<void> }, raw: pg };
 }
+
+async function importPglite(): Promise<{
+  PGlite: typeof import('@electric-sql/pglite').PGlite;
+  pgcrypto: typeof import('@electric-sql/pglite/contrib/pgcrypto').pgcrypto;
+}> {
+  try {
+    const [mod, contrib] = await Promise.all([
+      import('@electric-sql/pglite'),
+      import('@electric-sql/pglite/contrib/pgcrypto'),
+    ]);
+    return { PGlite: mod.PGlite, pgcrypto: contrib.pgcrypto };
+  } catch (err) {
+    if (!isModuleNotFound(err, PGLITE)) throw err;
+    throw new Error(
+      `createTestDb() needs "${PGLITE}", which is not installed.\n` +
+        `\n` +
+        `  ${PGLITE_INSTALL}\n` +
+        `\n` +
+        `The version is part of the command. @filelayer/core supports the 0.3.x line\n` +
+        `of ${PGLITE}; 0.5.x is not supported, because the test suite does\n` +
+        `not pass against it. Installing without the constraint can resolve to a\n` +
+        `version outside the supported range, and npm then refuses the install with\n` +
+        `ERESOLVE rather than giving you a working tree.\n` +
+        `\n` +
+        `It is an OPTIONAL peer dependency of @filelayer/core, on purpose: it is an\n` +
+        `embedded WASM PostgreSQL used by createTestDb() and Filelayer.quickstart()\n` +
+        `for tests and local development, and shipping it to production installs of\n` +
+        `a library that talks to your own Postgres would be wrong.\n` +
+        `\n` +
+        `In production, do not call this. Pass your own database instead:\n` +
+        `\n` +
+        `  import { Pool } from 'pg';\n` +
+        `  new Filelayer(new Pool({ connectionString: process.env.DATABASE_URL }), storage, opts)\n` +
+        `\n` +
+        `and apply the schema once with:\n` +
+        `\n` +
+        `  psql "$DATABASE_URL" -f node_modules/@filelayer/core/schema.sql\n`,
+      { cause: err },
+    );
+  }
+}

package/test/s3-live.test.ts

@@ -10,36 +10,21 @@
  * WHAT A MAINTAINER MUST SET
  * -----------------------------------------------------------------------------
  *
- * REQUIRED (all five, or the suite skips):
+ * The bucket, the token permissions and the exact secret names are specified in
+ * ONE place -- `docs/LIVE-S3-TESTS.md` -- and this file deliberately does not
+ * restate them. Two copies of a setup procedure drift, and the copy that drifts
+ * is the one nobody followed most recently.
  *
- *   FILELAYER_TEST_S3_ENDPOINT           https://<account>.r2.cloudflarestorage.com
- *                                        or https://s3.<region>.amazonaws.com
- *   FILELAYER_TEST_S3_BUCKET             a bucket that may be written to and
- *                                        emptied. USE A DEDICATED TEST BUCKET.
- *   FILELAYER_TEST_S3_REGION             'auto' for R2, the real region for AWS
- *   FILELAYER_TEST_S3_ACCESS_KEY_ID
- *   FILELAYER_TEST_S3_SECRET_ACCESS_KEY
+ * What this file reads, and nothing more:
  *
- * OPTIONAL:
+ *   REQUIRED, all five or the suite skips:
+ *     FILELAYER_TEST_S3_ENDPOINT, FILELAYER_TEST_S3_BUCKET,
+ *     FILELAYER_TEST_S3_REGION, FILELAYER_TEST_S3_ACCESS_KEY_ID,
+ *     FILELAYER_TEST_S3_SECRET_ACCESS_KEY
  *
- *   FILELAYER_TEST_S3_SESSION_TOKEN      for STS / temporary credentials
- *   FILELAYER_TEST_S3_PATH_STYLE         'false' to exercise virtual-hosted
- *                                        addressing (AWS default style).
- *                                        Defaults to path-style, which is what
- *                                        R2 requires.
- *   FILELAYER_TEST_S3_PREFIX             key prefix. Defaults to
- *                                        'filelayer-ci/'. Everything the suite
- *                                        writes lives under it and is deleted
- *                                        afterwards.
- *   FILELAYER_TEST_S3_MULTIPART          '1' to run the multipart test, which
- *                                        uploads ~11 MB. Off by default so the
- *                                        suite stays cheap on every push;
- *                                        turn it ON in the nightly job.
- *
- * IAM PERMISSIONS REQUIRED on the bucket:
- *   s3:PutObject, s3:GetObject, s3:DeleteObject, s3:ListBucket,
- *   s3:AbortMultipartUpload  (multipart cleanup),
- *   s3:ListBucketMultipartUploads (only if you enable the multipart test)
+ *   OPTIONAL:
+ *     FILELAYER_TEST_S3_SESSION_TOKEN, FILELAYER_TEST_S3_PATH_STYLE,
+ *     FILELAYER_TEST_S3_PREFIX, FILELAYER_TEST_S3_MULTIPART
  *
  * -----------------------------------------------------------------------------
  * WHY THIS FILE EXISTS EVEN THOUGH test/storage.test.ts PASSES
@@ -75,9 +60,12 @@ const missing = REQUIRED.filter((k) => !env[k]);
 const enabled = missing.length === 0;
 const skip = enabled
   ? false
-  : `live S3 credentials not present (missing: ${missing.join(', ')}); see the header of this file`;
+  : `live S3 credentials not present (missing: ${missing.join(', ')}); see docs/LIVE-S3-TESTS.md`;
 
-const PREFIX = (env['FILELAYER_TEST_S3_PREFIX'] ?? 'filelayer-ci/').replace(/\/*$/, '/');
+// `||`, not `??`: a workflow that forwards an unset repository variable hands
+// us the EMPTY STRING, and `'' ?? default` is `''` -- which would root every
+// test key at '/' instead of under the prefix that gets cleaned up.
+const PREFIX = (env['FILELAYER_TEST_S3_PREFIX'] || 'filelayer-ci/').replace(/\/*$/, '/');
 const RUN = `${PREFIX}${Date.now()}-${Math.random().toString(36).slice(2, 8)}/`;
 const MULTIPART = env['FILELAYER_TEST_S3_MULTIPART'] === '1';