tr-pg-name-value-store 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+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
+
+Initial implementation, ready for testing.
+
+### 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).
+- 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timo J. Rinne <tri@iki.fi>
+
+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

@@ -0,0 +1,170 @@
+# tr-pg-name-value-store
+
+A persistent **name → value store** backed by a single PostgreSQL table. A thin,
+durable getter/setter: values are stored as `JSONB`, so a value may be anything
+JSON can carry (number, string, boolean, object, array, or `null`) and is
+returned as the corresponding JavaScript value.
+
+- **Self-maintaining schema.** The table is created idempotently by the class
+  itself on first use — no manual setup, no migrations. A pre-existing table is
+  *verified, never altered*.
+- **Multiple named stores.** A namespace gives each store its own table in the
+  same database.
+- **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
+  the value `null`.
+
+## Install
+
+```sh
+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`).
+
+## Quick start
+
+```ts
+import { Pool } from 'pg';
+import { PgNameValueStore } from 'tr-pg-name-value-store';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const store = new PgNameValueStore(pool, { namespace: 'myapp' });
+
+await store.set('greeting', 'hello');
+await store.get('greeting');            // → 'hello'
+
+await store.set('config', { retries: 3, tags: ['a', 'b'] });
+await store.get('config');              // → { retries: 3, tags: ['a', 'b'] }
+
+const previous = await store.set('greeting', 'hi'); // → 'hello' (the old value)
+await store.remove('greeting');         // → 'hi'   (the removed value)
+await store.get('greeting');            // → undefined
+```
+
+## Value model
+
+A stored value is any JSON-serializable JavaScript value: `number`, `string`,
+`boolean`, `object`, `array`, or `null`.
+
+- **Presence vs. `null`.** A name that has never been set (or has been removed)
+  reads back as `undefined`. A name explicitly set to JSON `null` reads back as
+  `null`. "The value does not exist" is always represented as the row being
+  absent — there is no SQL `NULL` value.
+- **`undefined` is not a value.** `set(name, undefined)` throws `TypeError`; use
+  `remove(name)` to delete. (Inside `update`, a callback that *returns*
+  `undefined` is the one place `undefined` is meaningful — it means *delete*.)
+- **JSONB normalization.** PostgreSQL normalizes JSONB on storage: object keys
+  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).
+
+## API
+
+### `new PgNameValueStore(pool, options?)`
+
+Constructs a store over a pg `Pool`. Performs no I/O. Options:
+
+| Option      | Type     | Default | Meaning |
+|-------------|----------|---------|---------|
+| `namespace` | `string` | none    | Backing table is `<namespace>_name_value_store`. Must match `/^[a-z][a-z0-9_]*$/`, ≤ 41 chars. Throws `TypeError` if invalid. Omit for the bare table `name_value_store`. |
+
+### `init(): Promise<void>`
+
+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).
+
+### `get(name): Promise<value>`
+
+Resolves to the current value, or `undefined` if `name` has no value.
+
+### `set(name, value): Promise<previous>`
+
+Stores `value` (insert or overwrite); resolves to the previous value, or
+`undefined` if there was none. Throws `TypeError` if `value` is `undefined` or
+not JSON-serializable (writing nothing).
+
+### `remove(name): Promise<previous>`
+
+Deletes `name`; resolves to its previous value, or `undefined` if it had none.
+
+### `update(name, callback): Promise<previous>`
+
+Atomic read-modify-write. Fetches the current value, calls
+`callback(current)` (awaiting a returned promise), then commits one outcome
+based on what the callback does:
+
+| Callback…                                              | Effect                          | `update`…                          |
+|--------------------------------------------------------|---------------------------------|------------------------------------|
+| 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 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);
+
+// conditional update; abort with no change and no error
+await store.update('config', (cfg) => {
+  if (!cfg) throw null;                 // graceful cancel
+  return { ...(cfg as object), seen: true };
+});
+
+// delete via update
+await store.update('stale', () => undefined);
+```
+
+### `removeAll(): Promise<void>`
+
+Removes every pair from this store's namespace. Other namespaces are untouched.
+
+## Multiple stores
+
+Each namespace is an independent store with its own table:
+
+```ts
+const sessions = new PgNameValueStore(pool, { namespace: 'sessions' });
+const settings = new PgNameValueStore(pool, { namespace: 'settings' });
+// sessions.* and settings.* never collide; removeAll() on one leaves the other intact
+```
+
+## 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. |
+| `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.
+
+## Schema
+
+One table per namespace (`{{ns}}` is `<namespace>_`, or empty):
+
+```sql
+CREATE TABLE {{ns}}name_value_store (
+  name       TEXT        NOT NULL,
+  v          JSONB       NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (name)
+);
+```
+
+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`.
+
+## License
+
+MIT © Timo J. Rinne &lt;tri@iki.fi&gt;

package/dist/generated/sql.d.ts

@@ -0,0 +1 @@
+export declare const TABLES_SQL = "-- tr-pg-name-value-store: bootstrap DDL.\n--\n-- FROZEN: this file must never change in a way that alters the shape of an\n-- existing table. Everything here is idempotent (create-if-absent); the module\n-- verifies the shape of a pre-existing table and refuses to touch it on any\n-- mismatch. No ALTER, no DROP \u2014 ever.\n--\n-- {{ns}} is the namespace prefix (e.g. \"myapp_\"), empty by default. It is\n-- expanded by the module after strict identifier validation.\n\n-- One row per name. The value lives in `v` as JSONB; a JSON null is stored as\n-- the JSONB scalar 'null' (still NOT NULL at the SQL level), which lets the\n-- store tell a stored null apart from an absent name. \"The value does not\n-- exist\" is always represented as row absence \u2014 a SQL NULL never appears in v.\nCREATE TABLE IF NOT EXISTS {{ns}}name_value_store (\n  name       TEXT        NOT NULL,\n  v          JSONB       NOT NULL,\n  updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (name)\n);\n";

package/dist/generated/sql.js

@@ -0,0 +1,5 @@
+"use strict";
+// AUTO-GENERATED by scripts/embed-sql.mjs from sql/*.sql — do not edit.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TABLES_SQL = void 0;
+exports.TABLES_SQL = "-- tr-pg-name-value-store: bootstrap DDL.\n--\n-- FROZEN: this file must never change in a way that alters the shape of an\n-- existing table. Everything here is idempotent (create-if-absent); the module\n-- verifies the shape of a pre-existing table and refuses to touch it on any\n-- mismatch. No ALTER, no DROP — ever.\n--\n-- {{ns}} is the namespace prefix (e.g. \"myapp_\"), empty by default. It is\n-- expanded by the module after strict identifier validation.\n\n-- One row per name. The value lives in `v` as JSONB; a JSON null is stored as\n-- the JSONB scalar 'null' (still NOT NULL at the SQL level), which lets the\n-- store tell a stored null apart from an absent name. \"The value does not\n-- exist\" is always represented as row absence — a SQL NULL never appears in v.\nCREATE TABLE IF NOT EXISTS {{ns}}name_value_store (\n  name       TEXT        NOT NULL,\n  v          JSONB       NOT NULL,\n  updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (name)\n);\n";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { PgNameValueStore, type PgNameValueStoreOptions, type UpdateCallback, } from './pg-name-value-store';
+export { SchemaMismatchError } from './schema';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaMismatchError = exports.PgNameValueStore = void 0;
+var pg_name_value_store_1 = require("./pg-name-value-store");
+Object.defineProperty(exports, "PgNameValueStore", { enumerable: true, get: function () { return pg_name_value_store_1.PgNameValueStore; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "SchemaMismatchError", { enumerable: true, get: function () { return schema_1.SchemaMismatchError; } });

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

@@ -0,0 +1,102 @@
+import type { Pool } from 'pg';
+/** Construction options for {@link PgNameValueStore}. */
+export interface PgNameValueStoreOptions {
+    /**
+     * Optional store namespace, allowing multiple independent stores in the same
+     * database. The backing table is named `<namespace>_name_value_store`. Must
+     * match `/^[a-z][a-z0-9_]*$/` and be at most 41 characters. Default: no prefix
+     * (the bare table name `name_value_store`).
+     */
+    namespace?: string;
+}
+/**
+ * The mutation callback passed to {@link PgNameValueStore.update}. Receives the
+ * current value (`undefined` if the name has no value) and returns the next
+ * value. See {@link PgNameValueStore.update} for the full outcome contract:
+ *
+ * - return a JSON-serializable value (not `undefined`) → store it;
+ * - return `undefined` → remove the name;
+ * - throw `null` or `undefined` → cancel (no change), no error surfaced;
+ * - throw anything else → cancel (no change), the error is re-thrown;
+ * - return a non-serializable value → cancel (no change), a `TypeError` is thrown.
+ */
+export type UpdateCallback = (current: unknown) => unknown | Promise<unknown>;
+/**
+ * A persistent name → value store backed by a single PostgreSQL table.
+ *
+ * Values are stored as JSONB, so a value may be anything JSON can carry
+ * (number, string, boolean, object, array, or `null`) and is returned as the
+ * corresponding JavaScript value. The store distinguishes *no value*
+ * (`undefined`) from the value `null`.
+ *
+ * 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.
+ */
+export declare class PgNameValueStore {
+    #private;
+    /**
+     * @param pool    a connected pg `Pool`; the store does not manage its lifecycle.
+     * @param options see {@link PgNameValueStoreOptions}. Throws `TypeError` on an
+     *                invalid `namespace`. Performs no I/O.
+     */
+    constructor(pool: Pool, options?: PgNameValueStoreOptions);
+    /**
+     * Idempotently ensures the schema exists and matches the expected shape
+     * (throws `SchemaMismatchError` on a conflicting pre-existing table), then
+     * resolves. Safe to call repeatedly and concurrently across processes
+     * (serialized by a per-namespace advisory lock). Every other method calls
+     * this internally on first use, so calling it explicitly is optional — useful
+     * to surface schema/connection errors eagerly at startup. A failed `init()`
+     * is not cached; a subsequent call retries.
+     */
+    init(): Promise<void>;
+    /**
+     * 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`).
+     */
+    get(name: string): Promise<unknown>;
+    /**
+     * Stores `value` as the new value of `name` (insert or overwrite) and
+     * 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(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.
+     */
+    remove(name: string): Promise<unknown>;
+    /**
+     * Atomic read-modify-write. Fetches the current value, invokes `cb(current)`
+     * (awaiting a returned promise), then commits exactly one outcome:
+     *
+     * - `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.
+     *
+     * 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`.
+     */
+    update(name: string, cb: UpdateCallback): Promise<unknown>;
+    /**
+     * Removes every name/value pair from this store (a single `DELETE`). Resolves
+     * to `void`. Affects only this store's namespace; other namespaces' tables
+     * are untouched.
+     */
+    removeAll(): Promise<void>;
+}

package/dist/schema.d.ts

@@ -0,0 +1,30 @@
+import type { Pool } from 'pg';
+/**
+ * Thrown when a pre-existing table with this store's (namespaced) name does not
+ * match the shape this module expects. The module never alters or drops an
+ * existing table; resolving a mismatch is up to the operator.
+ */
+export declare class SchemaMismatchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a namespace and returns the identifier prefix ("" or "<ns>_").
+ *
+ * The namespace is interpolated into DDL/DML, so this validation is the
+ * injection guard: reject, never quote or escape around it.
+ */
+export declare function namespacePrefix(namespace?: string): string;
+/**
+ * Deterministically derives a 64-bit signed advisory-lock key from a string.
+ * Used both for per-namespace init serialization and for per-name update
+ * serialization. A (vanishingly improbable) collision only over-serializes
+ * unrelated keys; it never affects correctness.
+ */
+export declare function lockKey(s: string): bigint;
+/**
+ * Idempotently ensures the store schema for the given namespace prefix: a
+ * pre-existing table is shape-verified (never altered), an absent one is
+ * created. Runs in a single transaction serialized by a per-namespace advisory
+ * lock, so concurrent initializers across processes are safe.
+ */
+export declare function ensureSchema(pool: Pool, prefix: string): Promise<void>;

package/dist/schema.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaMismatchError = void 0;
+exports.namespacePrefix = namespacePrefix;
+exports.lockKey = lockKey;
+exports.ensureSchema = ensureSchema;
+const node_crypto_1 = require("node:crypto");
+const sql_1 = require("./generated/sql");
+/**
+ * Thrown when a pre-existing table with this store's (namespaced) name does not
+ * match the shape this module expects. The module never alters or drops an
+ * existing table; resolving a mismatch is up to the operator.
+ */
+class SchemaMismatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SchemaMismatchError';
+    }
+}
+exports.SchemaMismatchError = SchemaMismatchError;
+const NAMESPACE_RE = /^[a-z][a-z0-9_]*$/;
+// The longest identifier the module causes PostgreSQL to generate is the
+// auto-named primary-key index "<ns>name_value_store_pkey". To stay within the
+// 63-byte identifier limit (beyond which PostgreSQL silently truncates), the
+// namespace may use at most 63 - len("name_value_store_pkey") - 1 chars. Derived
+// from the constant so it stays correct if a longer identifier is ever added.
+const LONGEST_SUFFIX = 'name_value_store_pkey';
+const NAMESPACE_MAX_LENGTH = 63 - LONGEST_SUFFIX.length - 1;
+/**
+ * Validates a namespace and returns the identifier prefix ("" or "<ns>_").
+ *
+ * The namespace is interpolated into DDL/DML, so this validation is the
+ * injection guard: reject, never quote or escape around it.
+ */
+function namespacePrefix(namespace) {
+    if (namespace === undefined || namespace === '')
+        return '';
+    if (typeof namespace !== 'string' || !NAMESPACE_RE.test(namespace)) {
+        throw new TypeError(`invalid namespace ${JSON.stringify(namespace)}: must match ${NAMESPACE_RE}`);
+    }
+    if (namespace.length > NAMESPACE_MAX_LENGTH) {
+        throw new TypeError(`invalid namespace: at most ${NAMESPACE_MAX_LENGTH} characters allowed ` +
+            `(got ${namespace.length})`);
+    }
+    return `${namespace}_`;
+}
+function expand(sql, prefix) {
+    return sql.replace(/\{\{ns\}\}/g, prefix);
+}
+/**
+ * Deterministically derives a 64-bit signed advisory-lock key from a string.
+ * Used both for per-namespace init serialization and for per-name update
+ * serialization. A (vanishingly improbable) collision only over-serializes
+ * unrelated keys; it never affects correctness.
+ */
+function lockKey(s) {
+    return (0, node_crypto_1.createHash)('sha256').update(s).digest().readBigInt64BE(0);
+}
+function namespaceLockKey(prefix) {
+    return lockKey(`tr-pg-name-value-store:init:${prefix}`);
+}
+// The frozen shape of the store table (see sql/tables.sql). A pre-existing
+// table is verified against this; any mismatch is a hard error.
+const EXPECTED_COLUMNS = [
+    { name: 'name', dataType: 'text', nullable: false },
+    { name: 'v', dataType: 'jsonb', nullable: false },
+    { name: 'updated_at', dataType: 'timestamp with time zone', nullable: false },
+];
+/**
+ * Verifies that a pre-existing store table matches the frozen shape. Runs
+ * BEFORE the bootstrap DDL so a wrong table fails with a clear error instead of
+ * a confusing one from a later insert. Absent table: a no-op (the
+ * create-if-absent DDL will create it).
+ */
+async function verifyTableShape(client, prefix) {
+    const table = `${prefix}name_value_store`;
+    const res = await client.query(`SELECT column_name, data_type, is_nullable
+       FROM information_schema.columns
+      WHERE table_schema = current_schema() AND table_name = $1
+      ORDER BY ordinal_position`, [table]);
+    if (res.rowCount === 0)
+        return; // Absent: bootstrap DDL will create it.
+    const got = res.rows.map((c) => `${c.column_name} ${c.data_type}${c.is_nullable === 'YES' ? '' : ' not null'}`);
+    const want = EXPECTED_COLUMNS.map((c) => `${c.name} ${c.dataType}${c.nullable ? '' : ' not null'}`);
+    if (got.join(', ') !== want.join(', ')) {
+        throw new SchemaMismatchError(`existing table "${table}" does not match the expected shape and will ` +
+            `not be touched.\n  expected: ${want.join(', ')}\n  found:    ${got.join(', ')}`);
+    }
+}
+/**
+ * Idempotently ensures the store schema for the given namespace prefix: a
+ * pre-existing table is shape-verified (never altered), an absent one is
+ * created. Runs in a single transaction serialized by a per-namespace advisory
+ * lock, so concurrent initializers across processes are safe.
+ */
+async function ensureSchema(pool, prefix) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query('SELECT pg_advisory_xact_lock($1)', [
+            namespaceLockKey(prefix).toString(),
+        ]);
+        await verifyTableShape(client, prefix);
+        await client.query(expand(sql_1.TABLES_SQL, prefix));
+        await client.query('COMMIT');
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "tr-pg-name-value-store",
+    "version": "0.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",
+        "key-value",
+        "kv",
+        "store",
+        "persistent",
+        "jsonb",
+        "postgresql",
+        "postgres",
+        "pg"
+    ],
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "sql",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "embed-sql": "node scripts/embed-sql.mjs",
+        "prebuild": "npm run embed-sql",
+        "build": "tsc -p tsconfig.json",
+        "pretest": "npm run embed-sql",
+        "test": "vitest run",
+        "prepack": "npm run build"
+    },
+    "peerDependencies": {
+        "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"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rinne/node-tr-pg-name-value-store.git"
+    },
+    "author": {
+        "name": "Timo J. Rinne",
+        "email": "tri@iki.fi",
+        "url": "https://github.com/rinne/"
+    },
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/rinne/node-tr-pg-name-value-store/issues"
+    },
+    "homepage": "https://github.com/rinne/node-tr-pg-name-value-store#readme"
+}

package/sql/tables.sql

@@ -0,0 +1,20 @@
+-- tr-pg-name-value-store: bootstrap DDL.
+--
+-- FROZEN: this file must never change in a way that alters the shape of an
+-- existing table. Everything here is idempotent (create-if-absent); the module
+-- verifies the shape of a pre-existing table and refuses to touch it on any
+-- mismatch. No ALTER, no DROP — ever.
+--
+-- {{ns}} is the namespace prefix (e.g. "myapp_"), empty by default. It is
+-- expanded by the module after strict identifier validation.
+
+-- One row per name. The value lives in `v` as JSONB; a JSON null is stored as
+-- the JSONB scalar 'null' (still NOT NULL at the SQL level), which lets the
+-- store tell a stored null apart from an absent name. "The value does not
+-- exist" is always represented as row absence — a SQL NULL never appears in v.
+CREATE TABLE IF NOT EXISTS {{ns}}name_value_store (
+  name       TEXT        NOT NULL,
+  v          JSONB       NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (name)
+);