Merge pull request #1020 from 2chanhaeng/pglite

Add `@fedify/pglite` with `PgliteKvStore`

Author: dahlia

.github/CODEOWNERS

@@ -80,6 +80,7 @@
 /packages/amqp/                                           @dahlia
 /packages/denokv/                                         @dahlia @2chanhaeng
 /packages/mysql/                                          @dahlia
+/packages/pglite/                                         @dahlia @2chanhaeng
 /packages/postgres/                                       @dahlia @2chanhaeng
 /packages/redis/                                          @dahlia @2chanhaeng
 /packages/sqlite/                                         @dahlia @2chanhaeng

CHANGES.md

@@ -258,6 +258,17 @@ To be released.
     explicit recovery for unobservable dead-letter failures.
     [[#930], [#934]]
 
+### @fedify/pglite
+
+ -  Added the `@fedify/pglite` package with `PgliteKvStore`, a `KvStore` backed
+    by an embedded PGlite database.  It accepts a caller-created PGlite instance
+    and is intended for a single PGlite instance in a single runtime isolate; a
+    message queue is not provided because PGlite does not share data between
+    processes.  [[#1018], [#1020] by ChanHaeng Lee\]
+
+[#1018]: https://github.com/fedify-dev/fedify/issues/1018
+[#1020]: https://github.com/fedify-dev/fedify/issues/1020
+
 ### @fedify/postgres
 
  -  Added `PostgresKvStore.cas()`, including atomic creation, replacement, and
@@ -311,6 +322,9 @@ To be released.
 
 ### @fedify/testing
 
+ -  Added `testKvStore()`, a conformance test suite for `KvStore`
+    implementations, complementing `testMessageQueue()`.
+    [[#1018], [#1020] by ChanHaeng Lee\]
  -  Fixed the CommonJS testing utilities build so it no longer requires
     `@js-temporal/polyfill` at runtime.  The build now bundles
     `temporal-polyfill`, while type declarations rely on the standard

changes.d/pglite/pglite-kv-store.md

@@ -0,0 +1,5 @@
+ -  Added the `@fedify/pglite` package with `PgliteKvStore`, a `KvStore` backed
+    by an embedded PGlite database.  It accepts a caller-created PGlite instance
+    and is intended for a single PGlite instance in a single runtime isolate; a
+    message queue is not provided because PGlite does not share data between
+    processes.  [[#1018], [#1020] by ChanHaeng Lee]

changes.d/testing/kv-store-tester.md

@@ -0,0 +1,3 @@
+ -  Added `testKvStore()`, a conformance test suite for `KvStore`
+    implementations, complementing `testMessageQueue()`.
+    [[#1018], [#1020] by ChanHaeng Lee]

cspell.json

@@ -86,6 +86,7 @@
     "optique",
     "oxlint",
     "oxlintrc",
+    "pglite",
     "phensley",
     "Pico",
     "Pixelfed",

deno.json

@@ -21,6 +21,7 @@
     "./packages/mysql",
     "./packages/netlify",
     "./packages/nuxt",
+    "./packages/pglite",
     "./packages/postgres",
     "./packages/redis",
     "./packages/relay",
@@ -45,6 +46,7 @@
   "imports": {
     "@cloudflare/workers-types": "npm:@cloudflare/workers-types@^4.20260511.1",
     "@david/dax": "jsr:@david/dax@^0.46.1",
+    "@electric-sql/pglite": "npm:@electric-sql/pglite@^0.5.8",
     "@fxts/core": "npm:@fxts/core@^1.21.1",
     "@hongminhee/localtunnel": "jsr:@hongminhee/localtunnel@^0.3.0",
     "@js-temporal/polyfill": "npm:@js-temporal/polyfill@^0.5.1",
@@ -61,6 +63,8 @@
     "@optique/core": "jsr:@optique/core@^1.1.0",
     "@optique/discover": "jsr:@optique/discover@^1.1.0",
     "@optique/run": "jsr:@optique/run@^1.1.0",
+    "@solidjs/start/middleware": "npm:@solidjs/start@^1.3.0/middleware",
+    "@solidjs/start/server": "npm:@solidjs/start@^1.3.0/server",
     "@standard-schema/spec": "jsr:@standard-schema/spec@^1.1.0",
     "@std/assert": "jsr:@std/assert@^1.0.13",
     "@std/async": "jsr:@std/async@^1.0.13",
@@ -69,11 +73,10 @@
     "@std/path": "jsr:@std/path@^1.0.6",
     "@std/testing": "jsr:@std/testing@^0.224.0",
     "@std/yaml": "jsr:@std/yaml@^1.0.8",
+    "@types/emscripten": "npm:@types/emscripten@^1.41.1",
     "@types/node": "npm:@types/node@^22.16.0",
     "amqplib": "npm:amqplib@^0.10.9",
     "asn1js": "npm:asn1js@^3.0.10",
-    "@solidjs/start/middleware": "npm:@solidjs/start@^1.3.0/middleware",
-    "@solidjs/start/server": "npm:@solidjs/start@^1.3.0/server",
     "astro": "npm:astro@^7.0.0",
     "byte-encodings": "npm:byte-encodings@^1.0.11",
     "chalk": "npm:chalk@^5.6.2",

deno.lock

@@ -306,6 +306,74 @@ const federation = createFederation<void>({
 
 [`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore
 
+### [`PgliteKvStore`]
+
+*This API is available since Fedify 2.4.0.*
+
+To use the [`PgliteKvStore`], install the *@fedify/pglite* package and PGlite:
+
+::: code-group
+
+~~~~ bash [Deno]
+deno add jsr:@fedify/pglite npm:@electric-sql/pglite
+~~~~
+
+~~~~ bash [npm]
+npm add @fedify/pglite @electric-sql/pglite
+~~~~
+
+~~~~ bash [pnpm]
+pnpm add @fedify/pglite @electric-sql/pglite
+~~~~
+
+~~~~ bash [Yarn]
+yarn add @fedify/pglite @electric-sql/pglite
+~~~~
+
+~~~~ bash [Bun]
+bun add @fedify/pglite @electric-sql/pglite
+~~~~
+
+:::
+
+[`PgliteKvStore`] uses an embedded PGlite database without requiring a
+PostgreSQL server.  It uses the same schema and default table name as
+[`PostgresKvStore`], so data can be migrated to PostgreSQL without converting
+the key–value records.
+
+Best for
+:   Development and testing, single-process deployments, and embedded or
+    desktop applications that need PostgreSQL-compatible storage without a
+    PostgreSQL server.
+
+Pros
+:   No server installation, PostgreSQL-compatible SQL, and the same schema as
+    [`PostgresKvStore`].
+
+Cons
+:   Only one process and PGlite instance can open a data directory, data are
+    not shared between processes, and horizontal scaling is not supported.
+
+~~~~ typescript twoslash
+import { PGlite } from "@electric-sql/pglite";
+import { createFederation } from "@fedify/fedify";
+import { PgliteKvStore } from "@fedify/pglite";
+
+const pg = new PGlite("./data/fedify");
+const federation = createFederation<void>({
+  kv: new PgliteKvStore(pg),
+  // ... other options
+});
+~~~~
+
+> [!WARNING]
+> The caller owns the PGlite instance and must close it during application
+> shutdown after pending store operations finish.  Do not open the same data
+> directory from multiple worker processes.  Use one PGlite instance per data
+> directory and runtime isolate.
+
+[`PgliteKvStore`]: https://jsr.io/@fedify/pglite/doc/kv/~/PgliteKvStore
+
 ### [`MysqlKvStore`]
 
 *This API is available since Fedify 2.1.0.*