@kequtech/tenon-orm 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,9 @@
   or `pg.Pool`; removed `{ url, options }` and `ConnectionUri`. `db.native` is the actual pool;
   results use `rows`, `rowCount`, and `fields`, and error fields use pg names (`table`,
   `constraint`). Native LISTEN uses checked-out clients with application-owned resubscription.
+  Default results are no longer iterable: use `result.rows`, replace metadata `count` with
+  `rowCount`, and update recording helpers. Selected SQL columns named `count` are unchanged. See
+  [transaction adapters](docs/reference.md#adapting-transactional-results) for `{ rows }` consumers.
 - Driver defaults apply, including no acquisition timeout and SQL null for bound `undefined`. The
   parameter ceiling now matches PostgreSQL's 65,535 limit.
 - Regenerate types: temporal reads include numeric infinities, date-only values use Node's local

package/docs/adoption-guide.md

@@ -103,6 +103,16 @@ reference definitions rather than comparing against types regenerated after late
 `generateDefinitions` covers relation metadata, not functions or privileges; include reviewed
 catalog checks for other objects the application needs. Tenon does not perform these comparisons.
 
+Generated declaration text is not a version-stable schema fingerprint: driver mappings and generator
+changes can alter it without schema drift. The schema-summary comments expose SQL definitions, but
+their formatting and PostgreSQL's rendering of those definitions are not a stable comparison format
+either. If an existing adoption guard hashes generated text, preserve its original reference and
+freeze a separate reference for each supported generator version from a disposable replay of the
+immutable checkpoint. Compare the replay's metadata with the reviewed checkpoint before accepting
+the new reference; never derive a replacement from whichever live database is configured. Keep
+independent function and privilege checks, and test both matching adoption and refusal after drift.
+This application guard is separate from Tenon's migration checksums; keep applied SQL unchanged.
+
 ```sh
 npx tenon baseline adopt --directory migrations --namespace app
 npx tenon migrate --directory migrations --namespace app

package/docs/agent-guide.md

@@ -103,7 +103,9 @@ Use `JSON.stringify(value)` for JSON write inputs; arrays otherwise bind as Post
 Bigint and numeric scalars read as strings, while numeric arrays read as numbers and can lose
 precision. Temporal reads use `Date | number` for finite dates and infinities. SQL NULL array
 elements remain JavaScript null. Keep domain validation at the persistence boundary. See
-[value mappings](reference.md#generated-types-and-checking).
+[value mappings](reference.md#generated-types-and-checking) and the
+[JSON/finite-date projection](reference.md#persistence-and-domain-values). For authentication policy
+requiring finite expiry, include `isfinite(expires_at)` alongside the SQL expiry comparison.
 
 ## Transactions and native access
 

package/docs/human-guide.md

@@ -114,6 +114,10 @@ needs a type for what that particular query selects. An annotation is a declarat
 the SQL matches. Without one, result fields are `unknown`. Use the inspection and database-test
 workflow below to check the declared contract against the query's behavior.
 
+Keep storage types conservative and validate them when projecting domain values. The
+[persistence-to-domain example](reference.md#persistence-and-domain-values) shows validated JSON
+writes and reads, finite dates, and an SQL predicate that rejects infinite session expiry.
+
 ## Reuse a query with a function
 
 Use an ordinary function when several callers need the same query. An object input makes the

package/docs/reference.md

@@ -25,7 +25,9 @@ and `close`. The required `connection` accepts:
 const db = createTenon({
   connection: {
     connectionString: connection,
-    connectionTimeoutMillis: 5000,
+    max: 10,
+    idleTimeoutMillis: 30_000,
+    connectionTimeoutMillis: 30_000,
     options: '-c search_path=app,public',
   },
 });
@@ -36,6 +38,9 @@ Strings become pg's `connectionString`; configuration objects pass to `new Pool(
 including no acquisition timeout unless `connectionTimeoutMillis` is configured. Pool timeouts use
 milliseconds. pg parses the URI for connection fields; matching URI values override client
 configuration, including an `options` URI parameter overriding the configuration's `options` string.
+The pool sizes and timeouts above are application choices. Configure pool policy in `PoolConfig`;
+old driver-specific URI settings such as `idle_timeout` do not configure pg's idle timeout. Preserve
+existing URI startup options when appending settings such as UTC and `search_path`.
 Preserve deployment credentials and TLS requirements; see
 [pg connection configuration](https://node-postgres.com/features/connecting).
 
@@ -64,15 +69,91 @@ modes, affected-row guards, SQL checks, and `onQuery`. They follow pg's query co
 not join a Tenon transaction; callback clients expose only `tx.query`.
 
 Use pg's [native APIs](https://node-postgres.com/apis/pool) and compatible cursor/COPY packages when
-needed. For LISTEN, check out a client with `await db.native.connect()`, attach `notification` and
-`error` listeners, and issue `LISTEN` on that client. Keep it checked out while listening; release
-it after `UNLISTEN`. Native queued acquisitions follow pg's shutdown behavior and must be settled by
-their caller before closing. A disconnected client does not reconnect. The application owns
+needed. For LISTEN, check out a client with `await db.native.connect()`, attach `notification`,
+`error`, and `end` listeners, and issue `LISTEN` on that client. Keep it checked out while listening;
+release it after `UNLISTEN`. Native queued acquisitions follow pg's shutdown behavior and must be
+settled by their caller before closing. A disconnected client does not reconnect. The application owns
 resubscription and catch-up; notifications are not replayed.
 
 Close owned pools through `db.close()` for bounded shutdown, including checked-out native clients.
 Borrowed pools and their listeners remain usable after wrapper close until their owner ends them.
 
+### LISTEN lifecycle example
+
+This helper owns a dedicated single-client pool. It returns an intentional-close function only
+after LISTEN is ready. Callbacks are synchronous; notification exceptions are isolated, and an
+unexpected disconnect invalidates this generation once before notifying its consumer. Failed
+connection acquisition or LISTEN setup closes the owned resources and rejects the setup promise.
+
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+
+async function listenForChanges(
+  connectionString: string,
+  onChange: (payload: string | undefined) => void,
+  onDisconnect: (error: Error) => void,
+) {
+  const db = createTenon({
+    connection: { connectionString, max: 1, idleTimeoutMillis: 0, connectionTimeoutMillis: 30_000 },
+  });
+  const client = await db.native.connect().catch(async (error: unknown) => {
+    await db.close();
+    throw error;
+  });
+  let active = true;
+  let closing: Promise<void> | undefined;
+
+  function stop(error?: Error): Promise<void> {
+    if (closing) return closing;
+    active = false;
+    closing = Promise.resolve().then(async () => {
+      try {
+        if (error) onDisconnect(error);
+      } finally {
+        client.release(true);
+        await db.close();
+      }
+    });
+    return closing;
+  }
+
+  const failed = (error: Error) => {
+    if (active) void stop(error).catch(console.error);
+  };
+  client.on('error', failed);
+  client.on('end', () => failed(new Error('The notification connection ended.')));
+  client.on('notification', (event) => {
+    if (!active || event.channel !== 'app_changes') return;
+    try {
+      onChange(event.payload);
+    } catch (error) {
+      console.error(error);
+    }
+  });
+  try {
+    await client.query('LISTEN "app_changes"');
+    if (!active) throw new Error('The notification connection closed during setup.');
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+  return () => stop();
+}
+```
+
+Both failure and intentional close discard the dedicated checkout with `release(true)` before
+closing its pool, so no UNLISTEN is needed and normal shutdown does not wait for Tenon's deadline.
+The active flag suppresses duplicate error/end callbacks and intentional-close notifications.
+Create a new helper instance to recover, and reconcile missed events through persistent data.
+
+This helper's close function is available after readiness. A manager that also supports replacement
+or shutdown while setup is pending must assign a generation token before awaiting setup. Only the
+current generation may change shared readiness/subscription state or notify its consumers. If stale
+setup later succeeds, close that setup's own listener; if it fails or finishes cleanup, leave the
+replacement alone. Invalidate the current token before intentional shutdown. Keep those guards in
+the application's subscription manager. The fixed channel above is trusted; validate and quote
+application-selected channel names before placing them in native SQL.
+
 ## Queries and result modes
 
 `sql<Row>` creates a detached `SqlQuery<Row>` with SQL `text` and ordered `values`; it does not
@@ -104,6 +185,25 @@ alone does not undo an autocommitted write; use `affectedRows` for write bounds
 Functions accepting `QueryClient` can use either `Database` or `Transaction`. Public types also
 include `QueryOptions`, `QueryReturnMode`, and `QueryOutput<Row, Mode>`.
 
+### Adapting transactional results
+
+For a job library or other adapter expecting `{ rows }`, extract the native result's row array:
+
+```ts
+import { unsafeSql, type QueryClient } from '@kequtech/tenon-orm';
+
+async function queryRows(tx: QueryClient, text: string, values: readonly unknown[]) {
+  const result = await tx.query(unsafeSql(text, values));
+  return { rows: result.rows };
+}
+```
+
+Alternatively, request `{ returns: 'many' }` and wrap the returned array in `{ rows }`. Supply the
+callback's `tx` when the adapter's work must commit with application writes. A native pool query
+uses a separate checkout and does not join that transaction. Await adapter calls before returning
+from the callback, retain commit/rollback tests, and make recording helpers return pg-shaped native
+results. The adapter's SQL text must be trusted and values must remain separately bound.
+
 ## SQL parameters and identifiers
 
 Ordinary `sql` interpolations bind values. Do not quote them or write manual `$n` placeholders
@@ -250,6 +350,13 @@ changes. It compares the generated representation, not pending migrations or eve
 Output includes relation/constraint/index summaries and referenced domains, not function bodies,
 grants, or a complete schema fingerprint.
 
+**Generated declarations are not a version-stable schema fingerprint.** TypeScript mappings can
+change without schema drift. The schema-summary comments describe SQL column types, defaults,
+constraints, indexes, and referenced domains independently of those mappings, but their formatting
+and PostgreSQL's rendering of definitions are not a versioned comparison contract either. Preserve
+reviewed generator-specific references if an existing guard hashes this output; see
+[baseline verification](adoption-guide.md#check-and-adopt-an-existing-database).
+
 Generation covers ordinary tables and partitioned roots. Views, foreign tables, and attached
 partitions need query-specific types. A missing namespace fails; an existing empty schema is valid.
 Exact table names are available through `Rows['users']`; valid nonreserved identifiers also receive
@@ -284,6 +391,74 @@ needed.
 Generated types describe storage representations. Text `CHECK` constraints do not become unions, and
 JSON reads remain unknown. Validate values before narrowing to application domain types.
 
+For example, assume this additional table and regenerate `Rows` from the resulting schema:
+
+```sql
+CREATE TABLE public.sessions (
+  id text PRIMARY KEY,
+  data jsonb NOT NULL,
+  expires_at timestamptz NOT NULL
+);
+```
+
+Use the same application validator before encoding a write and when restoring a domain value:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+import type { Rows } from './generated-schema.js';
+
+function sessionData(value: unknown): { userId: string } {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    Array.isArray(value) ||
+    !('userId' in value) ||
+    typeof value.userId !== 'string' ||
+    value.userId.length === 0
+  ) {
+    throw new Error('Expected session data with a nonempty userId');
+  }
+  return { userId: value.userId };
+}
+
+function finiteDate(value: Date | number): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new Error('Expected a finite database timestamp');
+  }
+  return value;
+}
+
+const input = {
+  id: 'example-session',
+  data: JSON.stringify(sessionData({ userId: 'user-42' })),
+  expires_at: new Date(Date.now() + 60_000),
+} satisfies Rows.Insert['sessions'];
+await db.query(sql`INSERT INTO public.sessions ${sql.insertValues(input)}`);
+
+const row = await db.query(
+  sql<Rows['sessions']>`SELECT id, data, expires_at FROM public.sessions
+    WHERE id = ${input.id} AND isfinite(expires_at) AND expires_at > now()`,
+  { returns: 'oneOrNone' },
+);
+const session =
+  row === undefined
+    ? undefined
+    : {
+        id: row.id,
+        data: sessionData(row.data),
+        expiresAt: finiteDate(row.expires_at),
+      };
+```
+
+The generated JSON read remains `unknown` and the timestamp remains `Date | number`. The projection
+validates both without assertions or edits to generated types. Preserve null separately for nullable
+columns. For an authentication policy requiring finite expiry, `isfinite(expires_at)` excludes both
+infinities before the expiry comparison; `expires_at > now()` alone would accept positive infinity.
+Include such predicates in expiry-sensitive updates/deletes too, and test infinite and expired
+values. This example illustrates representation validation; applications must also retain their
+token verification, revocation, and authorization checks. See
+[JSON and PostgreSQL arrays](mutations.md#json-and-postgresql-arrays) for array write boundaries.
+
 Bigint and `count(*)` reads are decimal strings. Use SQL or BigInt for exact arithmetic and decimal
 strings at JSON boundaries; convert to number only when bounded or approximate values are intended.
 

package/package.json

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