@kequtech/tenon-orm 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.1
+
+- Added readonly `db.native` access to Tenon's existing Postgres.js client for LISTEN, cursors,
+  COPY, and other native features without another driver installation. Native calls use the pool
+  directly and bypass Tenon's query guards and observation; transaction clients expose only `query`.
+- Connection ownership is unchanged: `db.close()` ends owned clients and their listeners, while
+  borrowed clients remain usable until their owner ends them.
+
 ## 0.2.0
 
 Changes since 0.1.0, including improvements shipped in 0.1.1–0.1.4.

package/README.md

@@ -43,6 +43,10 @@ This standalone example assumes the table exists. In a server, reuse an instance
 close it at shutdown, not after each request. Use `returns: 'many'` for an array, `'one'` when a row
 must exist, or omit the option for the driver's full result.
 
+Use [`db.native`](docs/reference.md#native-driver-access) to access the underlying Postgres.js client
+for LISTEN, cursors, COPY, and other native features without installing another driver. Native calls
+use the pool directly and bypass Tenon's query and transaction guards.
+
 Tenon also provides:
 
 - Transactions and affected-row limits that roll back rejected writes.

package/dist/database.js

@@ -29,6 +29,7 @@ export function createTenon(options) {
     };
     return {
         ...createClient(query, options.onQuery),
+        native: pool,
         async transaction(callback) {
             checkOpen();
             return withTransaction(pool, (query) => callback(createClient(query, options.onQuery)));

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type postgres from 'postgres';
 import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';
@@ -12,6 +13,8 @@ export interface QueryClient {
 }
 export type Transaction = QueryClient;
 export type Database = Transaction & {
+    /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
+    readonly native: postgres.Sql;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
     close(): Promise<void>;

package/docs/adoption-guide.md

@@ -33,6 +33,10 @@ queries or generate types; keep the existing migration runner if that is the int
    migration tooling until the migration transition below is complete, if that transition is part of
    the work.
 
+For driver features such as LISTEN or COPY, use [`db.native`](reference.md#native-driver-access).
+Preserve the application's notification recovery and resource ownership. Native pool queries do
+not join Tenon transactions; use `tx.query` for operations that must commit together.
+
 ## Replace local write helpers
 
 Use `sql.insertValues(rows)` and `sql.assignments(patch)` in place of local object-to-SQL utilities:

package/docs/agent-guide.md

@@ -45,6 +45,12 @@ supplied clients remain application-owned. The driver retains its native connect
 outstanding work before closing. Environment files are not loaded automatically. Qualify SQL names
 or configure `search_path`; CLI `--namespace` does not change runtime query names.
 
+Use `db.native` for Postgres.js features such as LISTEN, cursors, and COPY without another driver
+installation. It is the existing pool-level client. Native calls bypass Tenon's guards and `onQuery`,
+and do not join a Tenon transaction; transaction callbacks expose only `tx.query`. `db.close()` ends
+owned clients and their listeners; borrowed clients stay application-owned. Follow the
+[native access contract](reference.md#native-driver-access) for initialization and shutdown.
+
 ## Query contracts
 
 ```ts

package/docs/reference.md

@@ -16,7 +16,7 @@ setup; Tenon needs no special compiler configuration. `"type": "module"` and Typ
 npm install @kequtech/tenon-orm
 ```
 
-`createTenon({ connection, onQuery? })` returns a `Database` with `query`, `transaction`, and
+`createTenon({ connection, onQuery? })` returns a `Database` with `query`, `transaction`, `native`, and
 `close`. The required `connection` accepts a URL, Postgres.js options, or an existing Postgres.js client. An
 explicit `{}` selects the driver's environment defaults. Tenon does not load environment files
 automatically.
@@ -27,6 +27,37 @@ remain application-owned. Finish outstanding work before closing. Postgres.js ha
 Qualify SQL names or configure the driver's `search_path`. The CLI's `--namespace` selects the
 schema used by tooling, not a runtime query namespace.
 
+## Native driver access
+
+`db.native` is the underlying Postgres.js client, typed as `postgres.Sql`. The property is readonly
+in TypeScript. It exposes the existing pool without creating another client or requiring a separate
+driver installation. A supplied client is returned by identity. Use native APIs for LISTEN, cursors,
+COPY, and other driver features; their behavior follows the included `postgres@3.4.9`.
+
+```ts
+const db = createTenon({ connection });
+await db.native.listen('updates', handlePayload, refreshAfterSubscription);
+// At application shutdown, after outstanding work finishes:
+await db.close();
+```
+
+Postgres.js LISTEN creates a dedicated physical connection alongside the query pool. Applications
+own notification parsing, authorization, callback failures, and catch-up after resubscription. See
+the [Postgres.js native API](https://github.com/porsager/postgres/tree/v3.4.9#listen--notify).
+
+Native calls bypass Tenon's result contracts, affected-row guards, SQL boundary checks, and
+`onQuery` observation. They use native preparation defaults. `db.native` always refers to the pool,
+including inside `db.transaction`: its queries do not join that transaction. Transaction callbacks
+expose only `tx.query`; use that for work that must commit or roll back together.
+
+Native access is immediate and does not initialize Tenon's array correction. The first Tenon query
+or transaction installs that correction on the shared client; already prepared native statements
+can retain earlier parsers. Raw calls otherwise follow native driver behavior.
+
+`db.close()` ends a Tenon-owned client and its native listeners. With a borrowed client, it closes
+only the Tenon wrapper: native queries and listeners remain usable until their owner calls
+`db.native.end()`. Calling `end()` directly also ends the client used by Tenon.
+
 ## Queries and result modes
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",