@dbx-tools/postgres 0.9.95 → 0.9.105

package/README.md

@@ -3,14 +3,25 @@
 Connection-correct PostgreSQL primitives for Node.js: advisory locks that hold the
 connection they lock, and a structured topic bus over `LISTEN`/`NOTIFY`.
 
-This package owns reusable PostgreSQL coordination behavior. Prefer its locks,
-topic bus, persistence, identity, and connection helpers over local SQL snippets
-or parallel message envelopes so Node and Python services remain compatible.
+The package provides advisory locks, a typed topic bus, optional message
+persistence, sender identity, and connection helpers for Node services.
 
 Both work against a plain `pg.Pool` or anything structurally compatible with one,
 including the pool AppKit's Lakebase plugin exports — so a Databricks App gets
 them without a second database client or connection pool.
 
+## Quick Start
+
+Run protected work on the same PostgreSQL connection that holds the lock:
+
+```ts
+import { withAdvisoryLock } from "@dbx-tools/postgres";
+
+await withAdvisoryLock(pool, ["invoice", invoiceId], async (client) => {
+  await client.query("UPDATE invoices SET status = 'sent' WHERE id = $1", [invoiceId]);
+});
+```
+
 ## Key Features
 
 - Converts an arbitrary structured key (string, array, object, `Date`, or an
@@ -59,7 +70,7 @@ service-principal and per-user OBO pools. Every login identity that can reach th
 pool must therefore be a member of the configured role, or otherwise have
 permission to `SET ROLE`, before the pool can connect successfully.
 
-## Why Use This Over Native AppKit
+## Use With AppKit Lakebase
 
 Use AppKit `lakebase()` to obtain and refresh the PostgreSQL pool. This package
 does not replace that plugin. Add it when work needs connection-correct advisory
@@ -241,7 +252,7 @@ a listener can never be told about a row it cannot yet read.
 
 | Option             | Default           | Behavior                                                       |
 | ------------------ | ----------------- | -------------------------------------------------------------- |
-| `schema`           | `dbx_message_bus` | Schema the package owns.                                       |
+| `schema`           | `dbx_message_bus` | Schema used for message persistence.                            |
 | `scope`            | `open`            | Which tier's table publishes and history read by default.      |
 | `tables`           | `*_messages`      | Override a tier's table name for a managed installation.       |
 | `ttl`              | `24 hours`        | Per-message expiry. `false` keeps messages until deleted.      |
@@ -314,18 +325,17 @@ shared `dbx_tools_topic_bus` channel.
 `identity.channelName(parts)` exposes the derivation without constructing a bus,
 which is useful for configuration checks and cross-runtime contract tests.
 
-## Why A Separate Package?
+## Connection Lifecycles
 
 Advisory locks are connection-scoped, and that is easy to get wrong invisibly:
 taking the lock with `pool.query()` and doing the protected work with another
 `pool.query()` can use two different connections, so the lock protects nothing and
 the code looks correct. The same applies to `LISTEN`, which is session state a
-pooled query cannot hold. This package owns both lifecycles once, with no
-dependency beyond `pg`, so a consumer that only needs a lock does not pull in a
-message bus, an AppKit runtime, or a queue extension.
+pooled query cannot hold. These helpers keep both lifecycles on dedicated
+connections and depend only on `pg`.
 
-AppKit exposes Lakebase but has no lock helper and no message bus, so there is no
-native surface to prefer here.
+AppKit supplies the Lakebase pool; these helpers add locks and cross-instance
+message delivery on top of it.
 
 ## Module Map
 

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/postgres";
-export const PACKAGE_VERSION = "0.9.95";
+export const PACKAGE_VERSION = "0.9.105";
 export * as advisoryLock from "./src/advisory-lock.ts";
 export * as bindings from "./src/bindings.ts";
 export * as identity from "./src/identity.ts";

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export declare const PACKAGE_IDENTIFIER = "@dbx-tools/postgres";
-export declare const PACKAGE_VERSION = "0.9.95";
+export declare const PACKAGE_VERSION = "0.9.105";
 export * as advisoryLock from "./src/advisory-lock.ts";
 export * as bindings from "./src/bindings.ts";
 export * as identity from "./src/identity.ts";

package/lib/index.js

@@ -2,7 +2,7 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 export const PACKAGE_IDENTIFIER = "@dbx-tools/postgres";
-export const PACKAGE_VERSION = "0.9.95";
+export const PACKAGE_VERSION = "0.9.105";
 export * as advisoryLock from "./src/advisory-lock.js";
 export * as bindings from "./src/bindings.js";
 export * as identity from "./src/identity.js";
@@ -12,4 +12,4 @@ export * as topicBus from "./src/topic-bus.js";
 export { POINTER_VERSION } from "./src/persistence.js";
 export { PostgresTopicBus } from "./src/topic-bus.js";
 export * from "./exports.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxxQkFBcUIsQ0FBQztBQUN4RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsUUFBUSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxZQUFZLE1BQU0sd0JBQXdCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFFBQVEsTUFBTSxtQkFBbUIsQ0FBQztBQUM5QyxPQUFPLEtBQUssUUFBUSxNQUFNLG1CQUFtQixDQUFDO0FBQzlDLE9BQU8sS0FBSyxXQUFXLE1BQU0sc0JBQXNCLENBQUM7QUFDcEQsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUM1QyxPQUFPLEtBQUssUUFBUSxNQUFNLG9CQUFvQixDQUFDO0FBRS9DLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUV2RCxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUV0RCxjQUFjLGNBQWMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCBjb25zdCBQQUNLQUdFX0lERU5USUZJRVIgPSBcIkBkYngtdG9vbHMvcG9zdGdyZXNcIjtcbmV4cG9ydCBjb25zdCBQQUNLQUdFX1ZFUlNJT04gPSBcIjAuOS45NVwiO1xuZXhwb3J0ICogYXMgYWR2aXNvcnlMb2NrIGZyb20gXCIuL3NyYy9hZHZpc29yeS1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBiaW5kaW5ncyBmcm9tIFwiLi9zcmMvYmluZGluZ3MudHNcIjtcbmV4cG9ydCAqIGFzIGlkZW50aXR5IGZyb20gXCIuL3NyYy9pZGVudGl0eS50c1wiO1xuZXhwb3J0ICogYXMgcGVyc2lzdGVuY2UgZnJvbSBcIi4vc3JjL3BlcnNpc3RlbmNlLnRzXCI7XG5leHBvcnQgKiBhcyBzZXNzaW9uIGZyb20gXCIuL3NyYy9zZXNzaW9uLnRzXCI7XG5leHBvcnQgKiBhcyB0b3BpY0J1cyBmcm9tIFwiLi9zcmMvdG9waWMtYnVzLnRzXCI7XG5leHBvcnQgdHlwZSB7IEFkdmlzb3J5TG9ja0tleSwgUGdQb29sTGlrZSwgUGdRdWVyeWFibGUgfSBmcm9tIFwiLi9zcmMvYWR2aXNvcnktbG9jay50c1wiO1xuZXhwb3J0IHsgUE9JTlRFUl9WRVJTSU9OIH0gZnJvbSBcIi4vc3JjL3BlcnNpc3RlbmNlLnRzXCI7XG5leHBvcnQgdHlwZSB7IER1cmF0aW9uSW5wdXQsIFJlc29sdmVkVG9waWNCdXNQZXJzaXN0ZW5jZU9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvcGVyc2lzdGVuY2UudHNcIjtcbmV4cG9ydCB7IFBvc3RncmVzVG9waWNCdXMgfSBmcm9tIFwiLi9zcmMvdG9waWMtYnVzLnRzXCI7XG5leHBvcnQgdHlwZSB7IFRvcGljTWV0YWRhdGEsIFRvcGljTWVzc2FnZSwgVG9waWNQdWJsaXNoSW5wdXQsIFRvcGljTGlzdGVuZXIsIFRvcGljTWV0YWRhdGFQcm92aWRlciwgUG9zdGdyZXNUb3BpY0J1c09wdGlvbnMgfSBmcm9tIFwiLi9zcmMvdG9waWMtYnVzLnRzXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9leHBvcnRzLnRzXCI7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxxQkFBcUIsQ0FBQztBQUN4RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxZQUFZLE1BQU0sd0JBQXdCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFFBQVEsTUFBTSxtQkFBbUIsQ0FBQztBQUM5QyxPQUFPLEtBQUssUUFBUSxNQUFNLG1CQUFtQixDQUFDO0FBQzlDLE9BQU8sS0FBSyxXQUFXLE1BQU0sc0JBQXNCLENBQUM7QUFDcEQsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUM1QyxPQUFPLEtBQUssUUFBUSxNQUFNLG9CQUFvQixDQUFDO0FBRS9DLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUV2RCxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUV0RCxjQUFjLGNBQWMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCBjb25zdCBQQUNLQUdFX0lERU5USUZJRVIgPSBcIkBkYngtdG9vbHMvcG9zdGdyZXNcIjtcbmV4cG9ydCBjb25zdCBQQUNLQUdFX1ZFUlNJT04gPSBcIjAuOS4xMDVcIjtcbmV4cG9ydCAqIGFzIGFkdmlzb3J5TG9jayBmcm9tIFwiLi9zcmMvYWR2aXNvcnktbG9jay50c1wiO1xuZXhwb3J0ICogYXMgYmluZGluZ3MgZnJvbSBcIi4vc3JjL2JpbmRpbmdzLnRzXCI7XG5leHBvcnQgKiBhcyBpZGVudGl0eSBmcm9tIFwiLi9zcmMvaWRlbnRpdHkudHNcIjtcbmV4cG9ydCAqIGFzIHBlcnNpc3RlbmNlIGZyb20gXCIuL3NyYy9wZXJzaXN0ZW5jZS50c1wiO1xuZXhwb3J0ICogYXMgc2Vzc2lvbiBmcm9tIFwiLi9zcmMvc2Vzc2lvbi50c1wiO1xuZXhwb3J0ICogYXMgdG9waWNCdXMgZnJvbSBcIi4vc3JjL3RvcGljLWJ1cy50c1wiO1xuZXhwb3J0IHR5cGUgeyBBZHZpc29yeUxvY2tLZXksIFBnUG9vbExpa2UsIFBnUXVlcnlhYmxlIH0gZnJvbSBcIi4vc3JjL2Fkdmlzb3J5LWxvY2sudHNcIjtcbmV4cG9ydCB7IFBPSU5URVJfVkVSU0lPTiB9IGZyb20gXCIuL3NyYy9wZXJzaXN0ZW5jZS50c1wiO1xuZXhwb3J0IHR5cGUgeyBEdXJhdGlvbklucHV0LCBSZXNvbHZlZFRvcGljQnVzUGVyc2lzdGVuY2VPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3BlcnNpc3RlbmNlLnRzXCI7XG5leHBvcnQgeyBQb3N0Z3Jlc1RvcGljQnVzIH0gZnJvbSBcIi4vc3JjL3RvcGljLWJ1cy50c1wiO1xuZXhwb3J0IHR5cGUgeyBUb3BpY01ldGFkYXRhLCBUb3BpY01lc3NhZ2UsIFRvcGljUHVibGlzaElucHV0LCBUb3BpY0xpc3RlbmVyLCBUb3BpY01ldGFkYXRhUHJvdmlkZXIsIFBvc3RncmVzVG9waWNCdXNPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3RvcGljLWJ1cy50c1wiO1xuZXhwb3J0ICogZnJvbSBcIi4vZXhwb3J0cy50c1wiO1xuIl19

package/package.json

@@ -28,8 +28,8 @@
     "@databricks/appkit": "0.81.0"
   },
   "dependencies": {
-    "@dbx-tools/lakebase": "^0.9.95",
-    "@dbx-tools/shared-core": "^0.9.95",
+    "@dbx-tools/lakebase": "^0.9.105",
+    "@dbx-tools/shared-core": "^0.9.105",
     "pg": "^8.22.0"
   },
   "main": "./lib/index.js",
@@ -70,7 +70,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.95",
+  "version": "0.9.105",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [