Add `@fedify/pglite` with `PgliteKvStore`

[2chanhaeng]

Background

PostgresKvStore requires a running PostgreSQL server. For local development, tests, and small single-process deployments, PGlite (PostgreSQL compiled to WebAssembly, @electric-sql/pglite) provides the same SQL without a server and runs on Node.js, Bun, and Deno.

I propose PgliteKvStore in @fedify/pglite. It takes a PGlite client and is otherwise identical to PostgresKvStore, sharing its table schema and default table name (the options only omit unlogged):

const pg = new PGlite("./data/fedify");
const federation = createFederation({
  kv: new PgliteKvStore(pg),
});

Verified

Every SQL statement in kv.ts runs unchanged on PGlite 0.5.8 (PostgreSQL 18.3) under Deno 2.9.5, Node.js 22.23.1, and Bun 1.2.22, including text[]/jsonb/interval parameters.

Differences to handle:

• A bare JavaScript string bound to jsonb fails; values must always be JSON.stringify’d and cast from text.
• Deno needs --allow-read (and --allow-write for on-disk data) to load the WebAssembly module.
• One PGlite instance per data directory; data is not shared across processes.

Work

• Add PgliteKvStore in a new @fedify/pglite package.
• Add testKvStore(), a KvStore conformance suite, to @fedify/testing and run it against MemoryKvStore and PgliteKvStore.

How about PgliteMessageQueue?

Not provided, since separate instances do not share PostgreSQL's usual process and shared-memory state, a queue could not distribute work across processes.

[dahlia]

Thanks for putting this together. I think PGlite support would be useful, but after looking more closely at its process model, I would narrow this proposal to a key–value store in a separate package.

I would put it in @fedify/pglite, rather than @fedify/postgres. The two backends have different clients, connection models, lifecycle rules, and dependency requirements. Following Fedify's existing casing convention, the public class should be named PgliteKvStore. It should accept a caller-created PGlite instance instead of a data-directory path, keeping ownership and close() explicit and avoiding a hidden path-keyed instance registry.

I also would not make a shared cross-package SQL driver a requirement. That would either couple @fedify/pglite back to @fedify/postgres and its postgres peer dependency, or require another package solely for internal plumbing. Sharing the KvStore conformance tests while keeping the client-specific query and lifecycle code separate seems like a better boundary.

More importantly, I do not think we should provide PgliteMessageQueue with PGlite's current process model. The upstream maintainer explains that only one PGlite instance can operate on a data directory at a time, because separate instances do not share PostgreSQL's usual process and shared-memory state. An open upstream pull request aims to add exclusive data-directory locking because concurrent instances can corrupt the database. That change would reject a second process, not synchronize it.

I reproduced the consequence with PGlite 0.5.8 on Node.js 22.23.2. Two independent processes opened the same data directory. Process A inserted a row and issued NOTIFY; A received the notification, while process B received nothing and still counted zero rows one second later. After both processes closed, a new instance saw the row. Periodic polling would not fix this because an already-open instance does not see the other process's writes.

A queue with this behavior cannot distribute work across Fedify processes, uphold orderingKey across workers, or behave safely during horizontal scaling and rolling restarts. The limitation would be easy to miss and could result in stuck or concurrently processed federation work. I would leave PgliteMessageQueue out until PGlite supports real multi-session or multiprocess visibility.

Would you be open to scoping this issue to a new @fedify/pglite package that provides only PgliteKvStore, documented for one PGlite instance in one runtime isolate?

[2chanhaeng]

OK! If PgliteMessageQueue is impossible due to a technical limitation, then no choice. Also, from a usability standpoint, it’s better to just separate it and make it a dependency rather than force a peer dependency installation by adding it to the existing package. I will apply your comment to the implementation.

[dahlia]

@2chanhaeng Could you update the title of this issue?

[2chanhaeng]

Done!