tr-pg-name-value-store 0.0.0 → 1.0.0

package/CHANGELOG.md

@@ -4,20 +4,35 @@ All notable changes to this project are documented in this file. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.0.0] - Unreleased
+## [1.0.0] - 2026-09-07
 
-Initial implementation, ready for testing.
+Initial release.
 
 ### Added
 
 - `PgNameValueStore` class constructed from a pg `Pool`, with a self-maintaining,
   never-migrated schema (one `name_value_store` table per namespace; pre-existing
-  tables are verified, never altered).
+  tables are verified, never altered; a matching operator-created table is
+  adopted as-is).
 - Async API: `init`, `get`, `set`, `remove`, `update`, `removeAll`.
 - JSONB value storage for any JSON value; `undefined` (no value) is kept distinct
   from a stored JSON `null` via row presence.
-- Atomic `update(name, callback)` read-modify-write, serialized per name by a
-  PostgreSQL advisory lock, with graceful cancel (callback throws `null`/
-  `undefined`), delete (callback returns `undefined`), and error pass-through.
-- `SchemaMismatchError` for a conflicting pre-existing table.
-- Integration test suite (vitest) and documentation.
+- Exact previous-value contract: `set`, `remove` and `update` each resolve to the
+  value they replaced. All writes to the same name run in a transaction on a
+  dedicated connection under a per-`(namespace, name)` advisory lock, so they are
+  strictly serialized across processes and the previous value is always the one
+  left by the immediately preceding write. Writes to different names, and all
+  reads, are never blocked.
+- Atomic `update(name, callback)` read-modify-write with graceful cancel
+  (callback throws `null`/`undefined`), delete (callback returns `undefined`),
+  and error pass-through.
+- Name validation: a non-empty string of at most 1024 bytes of UTF-8 without
+  `U+0000`, rejected with `TypeError` before any I/O.
+- `SchemaMismatchError` for a conflicting pre-existing table. A failed `init()`
+  is not cached; the next call retries.
+- Integration test suite (vitest) against a real PostgreSQL — a throwaway local
+  cluster by default, or any server via `TR_PG_NAME_VALUE_STORE_TEST_URL` (a
+  compose file for PostgreSQL 16 is included). Verified on PostgreSQL 9.6, 16
+  and 18.
+
+[1.0.0]: https://github.com/rinne/node-tr-pg-name-value-store/releases/tag/v1.0.0

package/README.md

@@ -10,6 +10,10 @@ returned as the corresponding JavaScript value.
   *verified, never altered*.
 - **Multiple named stores.** A namespace gives each store its own table in the
   same database.
+- **Exact previous values.** Every write (`set`, `remove`, `update`) resolves to
+  the value it replaced. Writes to the same name are serialized across all
+  processes sharing the database, so that previous value is always the one left
+  by the immediately preceding write.
 - **Atomic read-modify-write.** `update()` runs a callback inside a transaction,
   serialized per name, so concurrent updates compose correctly.
 - **Presence vs. `null`.** The store distinguishes *no value* (`undefined`) from
@@ -22,7 +26,8 @@ npm install tr-pg-name-value-store pg
 ```
 
 `pg` is a peer dependency (`>= 8`). Requires Node `>= 18` and PostgreSQL `>= 9.5`
-(for `INSERT … ON CONFLICT`).
+(for `INSERT … ON CONFLICT`). The test suite runs against PostgreSQL 9.6, 16 and
+18.
 
 ## Quick start
 
@@ -60,6 +65,15 @@ A stored value is any JSON-serializable JavaScript value: `number`, `string`,
   are reordered, insignificant whitespace is dropped, duplicate keys collapse to
   the last, and numbers are canonicalized. A value read back is *semantically*
   equal but may not be textually identical to the value written (e.g. key order).
+- **No `U+0000` in strings.** PostgreSQL's `jsonb` cannot store the NUL character
+  inside a string; the server's error propagates unchanged and nothing is written.
+
+## Names
+
+A name is any non-empty string of at most **1024 bytes of UTF-8** (so up to 1024
+ASCII characters, fewer for non-ASCII) that does not contain `U+0000`. Anything
+else throws `TypeError` before any I/O. Within those bounds names are opaque:
+case-sensitive, whitespace-significant, any punctuation or Unicode.
 
 ## API
 
@@ -76,11 +90,13 @@ Constructs a store over a pg `Pool`. Performs no I/O. Options:
 Idempotently ensures the schema (creating the table if absent, verifying it if
 present). Called automatically on first use of any method; call it explicitly to
 surface schema/connection errors at startup. Safe to call repeatedly and
-concurrently (across processes too).
+concurrently (across processes too). A failed `init()` is not cached; the next
+call retries.
 
 ### `get(name): Promise<value>`
 
-Resolves to the current value, or `undefined` if `name` has no value.
+Resolves to the current value, or `undefined` if `name` has no value. A single
+lock-free `SELECT` that reads the latest committed value.
 
 ### `set(name, value): Promise<previous>`
 
@@ -103,14 +119,9 @@ based on what the callback does:
 | returns a JSON-serializable value (not `undefined`)    | stores it                       | resolves to the previous value     |
 | returns `undefined`                                    | removes the name                | resolves to the previous value     |
 | returns a non-serializable value (function, `BigInt`, …) | nothing (rolled back)         | throws `TypeError`                 |
-| throws `null` or `undefined`                           | nothing (rolled back)           | resolves to the previous value     |
+| throws `null` or `undefined`                           | nothing (graceful cancel)       | resolves to the previous value     |
 | throws anything else                                   | nothing (rolled back)           | re-throws that value unchanged     |
 
-The whole sequence runs in one transaction on a dedicated pooled connection.
-Concurrent updates of the **same** name are serialized by a per-name advisory
-lock, so each callback sees the committed result of the previous one — including
-the create-from-absent case.
-
 ```ts
 // atomic counter (creates from absent, then increments)
 await store.update('hits', (n) => (typeof n === 'number' ? n : 0) + 1);
@@ -125,10 +136,33 @@ await store.update('config', (cfg) => {
 await store.update('stale', () => undefined);
 ```
 
+The callback must not write to the **same name** through this or any other
+store instance — it would wait forever on the lock the callback itself holds.
+Writes to other names, and reads of anything, are fine.
+
 ### `removeAll(): Promise<void>`
 
 Removes every pair from this store's namespace. Other namespaces are untouched.
 
+## Concurrency
+
+Every write to a given name — `set`, `remove`, and `update` — runs in its own
+transaction on a dedicated pooled connection and holds a per-`(namespace, name)`
+transaction-scoped advisory lock (`pg_advisory_xact_lock`) for its duration.
+Writes to the same name are therefore strictly serialized, across every process
+that shares the database, and each one observes exactly the committed result of
+the one before it. That is what makes the *previous value* contract exact and
+what lets `update` callbacks compose (including the create-from-absent case,
+which a row lock alone cannot cover).
+
+Writes to different names never block each other. `get` is a single lock-free
+statement. `removeAll` is a single bulk `DELETE` that does not take per-name
+locks; it waits for in-flight writes on individual rows like any other statement
+would.
+
+Advisory-lock keys are derived in Node (SHA-256 of the namespace and name) — no
+server-side extension is required.
+
 ## Multiple stores
 
 Each namespace is an independent store with its own table:
@@ -139,15 +173,20 @@ const settings = new PgNameValueStore(pool, { namespace: 'settings' });
 // sessions.* and settings.* never collide; removeAll() on one leaves the other intact
 ```
 
+Several instances over the same namespace (in one process or many) share the
+same data and the same per-name serialization.
+
 ## Errors
 
 | Error                 | When |
 |-----------------------|------|
-| `TypeError`           | Invalid namespace; invalid name (not a non-empty string, or > 1024 chars); a `set` value or `update` return that is not JSON-serializable. |
+| `TypeError`           | Invalid namespace; invalid name (not a non-empty string, more than 1024 bytes of UTF-8, or containing `U+0000`); a `set` value or `update` return that is not JSON-serializable; an `update` callback that is not a function. |
 | `SchemaMismatchError` | A table with this namespace's name already exists with a different shape. It is left untouched. Exported by the package. |
 | re-thrown value       | `update` re-throws any non-`null`/`undefined` value its callback throws. |
 
 Operational/connection failures propagate from the underlying `pg` calls.
+Argument validation errors are thrown synchronously by the constructor and as
+rejected promises by every other method, always before any I/O.
 
 ## Schema
 
@@ -163,7 +202,32 @@ CREATE TABLE {{ns}}name_value_store (
 ```
 
 The module issues only `CREATE TABLE IF NOT EXISTS` and verifies the columns of
-a pre-existing table against this shape — it never runs `ALTER` or `DROP`.
+a pre-existing table against this shape — it never runs `ALTER` or `DROP`. A
+matching table created by an operator (with any existing rows) is adopted as-is.
+`updated_at` is maintained on every write for operational inspection; it has no
+public accessor.
+
+## Development
+
+```sh
+npm install
+npm test            # embeds sql/, typechecks src + tests, runs vitest
+npm run build       # emits dist/
+npm pack --dry-run  # audit the tarball contents before publishing
+```
+
+The tests run against a real PostgreSQL. By default a throwaway cluster is
+bootstrapped with `initdb`/`pg_ctl` in a temp directory (PostgreSQL server
+binaries must be on `PATH`) and torn down afterwards. To use an existing server
+instead — for example the bundled compose file — point
+`TR_PG_NAME_VALUE_STORE_TEST_URL` at an admin connection; a scratch database
+named `tr_pg_name_value_store_test` is (re)created on it:
+
+```sh
+docker compose -f test/docker-compose.yml up -d
+TR_PG_NAME_VALUE_STORE_TEST_URL=postgres://postgres:postgres@localhost:5434/postgres npm test
+docker compose -f test/docker-compose.yml down
+```
 
 ## License
 

package/dist/pg-name-value-store.d.ts

@@ -32,6 +32,15 @@ export type UpdateCallback = (current: unknown) => unknown | Promise<unknown>;
  * The constructor takes a pg `Pool`; the schema (one table per namespace) is
  * created automatically and idempotently on first use, or via an explicit
  * {@link init} call. An existing table is never altered — only verified.
+ *
+ * **Concurrency.** Every write to a given name — {@link set}, {@link remove},
+ * and {@link update} — runs in its own transaction on a dedicated pooled
+ * connection, serialized with all other writes to the same name (in any
+ * process sharing the database) by a per-(namespace, name) advisory lock. The
+ * *previous value* each of them resolves to is therefore exact: it is the value
+ * left by the immediately preceding write. Writes to different names never
+ * block each other. {@link get} is a single lock-free statement that reads the
+ * latest committed value.
  */
 export declare class PgNameValueStore {
     #private;
@@ -54,7 +63,7 @@ export declare class PgNameValueStore {
     /**
      * Resolves to the current value of `name`, or `undefined` if `name` has no
      * value. A name explicitly set to JSON `null` resolves to `null` (distinct
-     * from `undefined`).
+     * from `undefined`). A single lock-free `SELECT`.
      */
     get(name: string): Promise<unknown>;
     /**
@@ -62,14 +71,15 @@ export declare class PgNameValueStore {
      * resolves to the **previous** value, or `undefined` if there was none.
      *
      * `value` must be JSON-serializable and must not be `undefined`; otherwise
-     * `set` throws `TypeError` and writes nothing. Performed as a single
-     * statement, so it is atomic.
+     * `set` throws `TypeError` and writes nothing. Serialized with every other
+     * write to the same name (see the class docs), so the previous value is
+     * exactly the value left by the preceding write.
      */
     set(name: string, value: unknown): Promise<unknown>;
     /**
      * Removes `name` from the store and resolves to its previous value, or
      * `undefined` if `name` had no value. Removing an absent name is a no-op that
-     * resolves to `undefined`. A single `DELETE … RETURNING`; atomic.
+     * resolves to `undefined`. Serialized with every other write to the same name.
      */
     remove(name: string): Promise<unknown>;
     /**
@@ -78,19 +88,23 @@ export declare class PgNameValueStore {
      *
      * - `cb` returns a JSON-serializable value (not `undefined`) → store it;
      * - `cb` returns `undefined` → remove `name`;
-     * - `cb` returns a non-serializable value → roll back, throw `TypeError`;
-     * - `cb` throws `null`/`undefined` → roll back (graceful cancel), no error;
-     * - `cb` throws anything else → roll back, re-throw that value unchanged.
+     * - `cb` returns a non-serializable value → no change, throw `TypeError`;
+     * - `cb` throws `null`/`undefined` → no change (graceful cancel), no error;
+     * - `cb` throws anything else → no change, re-throw that value unchanged.
      *
      * On every non-throwing outcome (store, remove, or graceful cancel) `update`
      * resolves to the value that was in the database **before** the call (or
      * `undefined` if there was none).
      *
      * The whole sequence runs in one transaction on a dedicated pooled
-     * connection. Concurrent updates of the same `name` are serialized by a
-     * per-(namespace, name) transaction-scoped advisory lock, so each callback
-     * sees the committed result of the previous update — including the
-     * create-from-absent case. An existing row is additionally taken `FOR UPDATE`.
+     * connection, serialized with every other write to the same name by the
+     * per-(namespace, name) advisory lock, so each callback sees the committed
+     * result of the previous write — including the create-from-absent case. An
+     * existing row is additionally taken `FOR UPDATE`.
+     *
+     * The callback must not write to the **same name** through this or any other
+     * store instance (it would wait on the lock the callback itself holds); writes
+     * to other names are fine.
      */
     update(name: string, cb: UpdateCallback): Promise<unknown>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tr-pg-name-value-store",
-    "version": "0.0.0",
+    "version": "1.0.0",
     "description": "Persistent name/value store on PostgreSQL. JSONB values, self-maintaining never-migrated schema, atomic read-modify-write, multiple named stores per database.",
     "keywords": [
         "name-value",
@@ -29,7 +29,8 @@
         "embed-sql": "node scripts/embed-sql.mjs",
         "prebuild": "npm run embed-sql",
         "build": "tsc -p tsconfig.json",
-        "pretest": "npm run embed-sql",
+        "typecheck": "tsc -p tsconfig.test.json",
+        "pretest": "npm run embed-sql && npm run typecheck",
         "test": "vitest run",
         "prepack": "npm run build"
     },
@@ -37,11 +38,11 @@
         "pg": ">=8"
     },
     "devDependencies": {
-        "@types/node": "^20.0.0",
-        "@types/pg": "^8.10.0",
-        "pg": "^8.11.0",
-        "typescript": "^5.4.0",
-        "vitest": "^4.1.8"
+        "@types/node": "^20.19.0",
+        "@types/pg": "^8.23.0",
+        "pg": "^8.23.0",
+        "typescript": "^5.9.0",
+        "vitest": "^4.1.0"
     },
     "repository": {
         "type": "git",