@kequtech/tenon-orm 0.1.3 → 0.2.0

package/docs/human-guide.md

@@ -1,7 +1,7 @@
 # Using Tenon: a human guide
 
 Tenon lets you use PostgreSQL directly from TypeScript. You write SQL; Tenon binds its inputs and
-executes it through `pg`. This guide follows a small application from its first table to reusable
+executes it through Postgres.js. This guide follows a small application from its first table to reusable
 queries, transactions, and result checking.
 
 Use the [reference](reference.md) when you need exact options or unusual cases. The
@@ -13,8 +13,7 @@ Use the [reference](reference.md) when you need exact options or unusual cases.
 In an existing Node.js 24+ TypeScript project using ESM:
 
 ```sh
-npm install @kequtech/tenon-orm pg
-npm install --save-dev @types/pg
+npm install @kequtech/tenon-orm
 ```
 
 Use PostgreSQL 16+ and TypeScript 6+. Keep your existing strict TypeScript configuration and Node
@@ -31,13 +30,14 @@ export const db = createTenon({ connection });
 ```
 
 Reuse this instance across the application and call `await db.close()` at shutdown. For multiple
-databases, create an instance for each connection. You can also supply an existing `pg.Pool`; your
+databases, create an instance for each connection. You can also supply an existing Postgres.js client; your
 application then closes that pool.
 
 ## Create a table
 
-If you already have a schema and migration runner, you can keep them. For a new schema, create a
-migration:
+If you already have a schema and migration runner, you can keep them. For new schemas, prefer plural
+`snake_case` table names and `snake_case` column names. Tenon preserves your schema's exact names.
+Create a migration:
 
 ```sh
 npx tenon new create_users
@@ -47,7 +47,7 @@ Fill the generated files:
 
 ```sql
 -- migrations/0001_create_users.up.sql
-CREATE TABLE public."User" (
+CREATE TABLE public.users (
   id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
   email text NOT NULL UNIQUE,
   active boolean NOT NULL DEFAULT true
@@ -56,7 +56,7 @@ CREATE TABLE public."User" (
 
 ```sql
 -- migrations/0001_create_users.down.sql
-DROP TABLE public."User";
+DROP TABLE public.users;
 ```
 
 For development, add a script to `package.json` that applies migrations and updates generated types:
@@ -87,10 +87,10 @@ import { sql } from '@kequtech/tenon-orm';
 import { db } from './db.js';
 
 const email = 'reader@example.test';
-await db.query(sql`INSERT INTO public."User" (email) VALUES (${email})`);
+await db.query(sql`INSERT INTO public.users (email) VALUES (${email})`);
 const user = await db.query(
   sql<{ id: number; email: string }>`
-    SELECT id, email FROM public."User" WHERE email = ${email}
+    SELECT id, email FROM public.users WHERE email = ${email}
   `,
   { returns: 'oneOrNone' },
 );
@@ -101,20 +101,20 @@ separately from the SQL text, even when the value contains SQL.
 
 The type describes one selected row. `returns: 'oneOrNone'` gives you that row or `undefined`; it
 throws if the query returns more than one row. Use `'one'` when absence should also be an error,
-`'many'` for an array, or omit `returns` for the full driver result with `.rows` and `.rowCount`.
+`'many'` for an array, or omit `returns` for the native result array with `.count` and `.columns`.
 These options do not change your SQL.
 
 Generated table types can help describe projections without repeating every field:
 
 ```ts
-import type { User } from './generated-schema.js';
-type UserSummary = Pick<User, 'id' | 'email'>;
+import type { Rows } from './generated-schema.js';
+type UserSummary = Pick<Rows['users'], 'id' | 'email'>;
 ```
 
 You can then write `sql<UserSummary>`. A table type describes the full table; a join or aggregate
 needs a type for what that particular query selects. An annotation is a declaration, not proof that
-the SQL matches. Without one, result fields are `unknown`. The checking workflow below can generate
-and verify it.
+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.
 
 ## Reuse a query with a function
 
@@ -123,15 +123,14 @@ supplied values easy to read:
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { User } from './generated-schema.js';
+import type { Rows } from './generated-schema.js';
 
-type UserSummary = Pick<User, 'id' | 'email'>;
+type UserSummary = Pick<Rows['users'], 'id' | 'email'>;
 
 export function userByEmail(client: QueryClient, { email }: { email: string }) {
-  return client.query(
-    sql<UserSummary>`SELECT id, email FROM public."User" WHERE email = ${email}`,
-    { returns: 'oneOrNone' },
-  );
+  return client.query(sql<UserSummary>`SELECT id, email FROM public.users WHERE email = ${email}`, {
+    returns: 'oneOrNone',
+  });
 }
 
 const user = await userByEmail(db, { email: 'reader@example.test' });
@@ -147,7 +146,7 @@ await db.transaction(async (tx) => {
   const user = await userByEmail(tx, { email: 'reader@example.test' });
   if (!user) throw new Error('User not found');
 
-  await tx.query(sql`UPDATE public."User" SET active = false WHERE id = ${user.id}`, {
+  await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${user.id}`, {
     affectedRows: { exact: 1 },
   });
 });
@@ -172,11 +171,11 @@ aligned, with `DEFAULT` for missing cells.
 ```ts
 import type { Rows } from './generated-schema.js';
 
-const input: Rows.Insert['User'] = { email: 'another@example.test' };
-await db.query(sql`INSERT INTO public."User" ${sql.insertValues(input, ['email'])}`);
+const input: Rows.Insert['users'] = { email: 'another@example.test' };
+await db.query(sql`INSERT INTO public.users ${sql.insertValues(input, ['email'])}`);
 
-const patch: Pick<Rows.Update['User'], 'active'> = { active: false };
-await db.query(sql`UPDATE public."User" SET ${sql.assignments(patch, ['active'])}
+const patch: Pick<Rows.Update['users'], 'active'> = { active: false };
+await db.query(sql`UPDATE public.users SET ${sql.assignments(patch, ['active'])}
   WHERE email = ${input.email}`);
 ```
 
@@ -190,36 +189,23 @@ choose which fields to write; they do not validate the complete object. See the
 
 ## Check your SQL and result types
 
-There are three different jobs here:
-
-- Tenon executes queries and binds values.
-- TypeScript checks the application code and the result types you declare.
-- SafeQL checks the SQL against your database and verifies or generates those types.
+Use `describeQuery({ connection, query })` on the completed query object, or
+`npx tenon describe query.sql` on a SQL file, to inspect the server's parameter and result types.
+This works with dynamic fragments and needs no additional checking setup. Match the application's
+connection settings and keep database assertions for actual rows, nulls, JSON, permissions, and
+transaction effects. See [query inspection](query-inspection.md).
 
-SafeQL is optional development tooling run by ESLint. Tenon's adapter supports queries, constant
-fragments, and mutation helpers; `tenon/check-composition` reports queries it cannot inspect.
-Follow the one-time [SQL checking setup](reference.md#sql-checking-with-safeql).
-
-Use the application's existing lint commands. If it has none, the setup shows `lint` and `lint:fix`.
-They run ESLint, including all other enabled rules. Once configured, the normal workflow is:
+TypeScript checks the application code and the result types you declare. Describe reports
+PostgreSQL metadata; it does not generate or verify a TypeScript annotation. Use generated table
+types where appropriate, declare projections explicitly, and check complete returned rows in tests.
 
 1. Run `npm run db:migrate` against the development/test database.
-2. Run `npm run lint` to find SQL errors and missing or incorrect annotations.
-3. Use `npm run lint:fix` to generate or repair annotations, then review the diff.
-4. Run TypeScript and database tests. CI runs the check without fixing files.
-
-For example, SafeQL can turn `sql` followed by a query selecting `id, email` into
-`sql<{ id: number; email: string }>` based on your actual schema. It can detect a renamed column or
-an incorrect declared result type before the query runs.
-
-Input validation and database tests still matter. Checking a query does not prove that a request is
-authorized, that its values are valid, or that returned JSON has an application-specific shape.
+2. Inspect the completed SQL and review the reported types and unresolved findings.
+3. Run TypeScript and database tests. Keep these checks in routine CI validation.
 
-The checker supports constant fragments and `sql.join` with inline arrays. Runtime-built lists and
-fragment-returning functions remain outside static analysis. Keep result annotations and database
-tests for those queries; when using the checker, suppress `tenon/check-composition` only on the
-tested query with a reason. Runtime-built mutation inputs need inline selected columns for SQL
-checking. See the [checking reference](reference.md#supported-sql-and-limitations) for details.
+Input validation and authorization remain application responsibilities. Describe cannot establish
+that a request is authorized, that its values are valid, or that returned JSON has an
+application-specific shape.
 
 ## Reuse or assemble parts of SQL when needed
 
@@ -227,7 +213,7 @@ For fixed conditions, write them directly:
 
 ```ts
 const users = await db.query(
-  sql<UserSummary>`SELECT id, email FROM public."User" WHERE active = ${true}`,
+  sql<UserSummary>`SELECT id, email FROM public.users WHERE active = ${true}`,
   { returns: 'many' },
 );
 ```
@@ -238,9 +224,9 @@ its count:
 
 ```ts
 const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
-const page = sql<UserSummary>`SELECT id, email FROM public."User"
+const page = sql<UserSummary>`SELECT id, email FROM public.users
   WHERE ${search} ORDER BY id LIMIT ${limit}`;
-const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
+const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
   WHERE ${search}`;
 ```
 
@@ -258,7 +244,7 @@ for (const term of terms) {
   filters.push(sql.fragment`email ILIKE ${'%' + term + '%'}`);
 }
 
-const query = sql<UserSummary>`SELECT id, email FROM public."User"
+const query = sql<UserSummary>`SELECT id, email FROM public.users
   WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
 ```
 

package/docs/mutations.md

@@ -34,10 +34,10 @@ entire input object contains only allowed keys. Keep narrower application input
 `tenon generate` also provides `Rows.Update['profiles']`. Use `Pick` to limit a patch to fields
 the caller may edit, for example `Pick<Rows.Update['profiles'], 'name' | 'bio'>`. Generated inputs
 understand defaults, nullability, domains, and generated columns. They use write representations:
-timestamps accept `Date | string`, bigint accepts `string | bigint`, and JSON uses serialized text.
+timestamps accept `Date | string`, bigint accepts `string | bigint`, and JSON accepts native JavaScript values through Tenon's exported `JSONValue` type.
 See the [input-type reference](reference.md#insert-and-update-inputs) for the complete mapping.
 
-## Input types, SQL checking, and runtime validation
+## Input types and runtime validation
 
 Apply input types with an annotation, `satisfies`, or a helper generic argument. Generating the
 file alone does not check every write. Narrow the fields each operation accepts:
@@ -55,9 +55,9 @@ function createProfile(client: QueryClient, input: ProfileInput) {
 ```
 
 Here `id` and `score` are assumed to be integers. TypeScript rejects an incompatible typed input
-such as `{ name: 'Ada', score: true }`. SafeQL checks selected columns and `RETURNING`; it does not
-inspect runtime values. Validate external inputs before calling this function and keep database
-constraints and application authorization in place.
+such as `{ name: 'Ada', score: true }`. Inspect the completed SQL with `describeQuery` and test its
+returned rows and write effects against the database. Validate external inputs before calling this
+function and keep database constraints and application authorization in place.
 
 **Selected columns can discard required fields.** For a table requiring integer `id` and text
 `name` and `location`, this input is valid but the query fails:
@@ -115,22 +115,22 @@ database default; that alone does not decide what an upsert should overwrite.
 
 ## JSONB arrays and PostgreSQL arrays
 
-Tenon preserves pg's value conversion. A JavaScript array binds as a PostgreSQL array. To write an
-array into a JSON/JSONB column, serialize it explicitly:
+SQL context determines whether a bound JavaScript array is a PostgreSQL array or a JSON value.
+Pass native JavaScript values; Postgres.js serializes them for the target type:
 
 ```ts
 const handles = ['ada', 'lin'];
 await db.query(
   sql`INSERT INTO deliveries ${sql.insertValues({
-    recipients_json: JSON.stringify(handles), // jsonb column
+    recipients_json: handles, // jsonb column
     recipient_handles: handles, // text[] column
   })}`,
 );
 ```
 
-Objects used as JSON values retain pg's ordinary JSON conversion. The helper does not infer JSON
-versus array encoding from the table schema. Generated JSON input types use serialized text for
-consistent handling of objects and arrays. Validate JSON contents in the application.
+Objects used as JSON values retain Postgres.js's ordinary JSON conversion. The helper does not need runtime schema metadata. Generated JSON input types use Tenon's exported
+`JSONValue` type, excluding SQL null for nonnullable columns. Pre-serialized text becomes a JSON
+string; use SQL such as `'null'::jsonb` when JSON null is required. Validate JSON contents in the application.
 
 ## Batches in one transaction
 
@@ -146,7 +146,7 @@ await db.transaction(async (tx) => {
 ```
 
 A failure rolls back all batches. The helper rejects an empty batch; this loop makes no insert
-calls for empty input. The query-wide limit is 65,535 bound parameters, including parameters outside
+calls for empty input. Each query accepts at most 65,533 bound parameters, including parameters outside
 the mutation fragment. An oversized query reports its actual count, for example
-`at most 65535 bound parameters; received 65536`. Defaults consume no parameters. Account for the
+`at most 65533 bound parameters; received 65534`. Defaults consume no parameters. Account for the
 selected columns and surrounding query when choosing a batch size; Tenon never splits queries automatically.

package/docs/query-inspection.md

@@ -0,0 +1,128 @@
+# Inspect and test queries
+
+`describeQuery` asks PostgreSQL what a completed SQL statement accepts and returns, without
+binding its values or executing it. Use it while writing a query or in a database test. It handles
+the actual SQL produced by fragments, helpers, loops, and conditional filters.
+Its `postgres` driver installs with Tenon; no extra
+consumer dependency or configuration is needed. Calling inspection opens a separate connection.
+
+## Inspect the query you will execute
+
+```ts
+import { describeQuery, sql } from '@kequtech/tenon-orm';
+
+const connection = process.env.DATABASE_URL;
+if (!connection) throw new Error('DATABASE_URL is required');
+
+const query = sql<{ id: number; total: string }>`
+  SELECT ${42}::integer AS id, count(*) AS total FROM pg_catalog.pg_class
+`;
+const description = await describeQuery({ connection, query });
+// description.columns reports number/string read types; nullability remains unknown.
+```
+
+For an application, pass the same query object that will go to `db.query`. Use representative inputs when calling its query-building
+function. Keep authorization policy centralized inside that builder or its fragments.
+
+`query` accepts a SQL string or an object with a `text` property, including a Tenon `SqlQuery`.
+For SQL strings, use PostgreSQL placeholders such as `$1`. PostgreSQL infers their types from SQL
+context; `SELECT $1::integer AS id` can be described without supplying a value. Ordinary Tenon
+templates bind values with `${value}`.
+
+Inspection does not read the type argument of `sql<Row>`, validate `query.values`, or compare an
+annotation with the result. A successful description is useful schema/type evidence, not proof
+that the query will execute or do the intended job.
+
+## Match the application's context
+
+```ts
+const description = await describeQuery({
+  connection,
+  query,
+  session: { searchPath: 'mail,public', timeZone: 'UTC' },
+  timeouts: { connectMs: 3000, statementMs: 5000, lockMs: 1000 },
+});
+```
+
+Reuse the application's connection URI and the source of its session settings. All overrides are
+optional. Connection URI startup options are preserved. `session.role` can assume a role when the
+connecting account has permission; omitted settings use the new connection's defaults. `SET ROLE`
+does not load that role's login defaults. Unknown options and invalid settings fail explicitly.
+
+The result's `context` reports the database, login/effective roles, configured and resolved search
+paths, timezone, and effective server timeouts. Compare these with the execution connection.
+Inspection reports `mode: 'separate-session'` and `readMappings: 'postgres'`. SQL NULL array
+elements are represented as JavaScript null.
+
+The default connection/authentication limit is 3 seconds. Every server statement, including
+metadata reads, has a 5-second limit, and each lock wait a 1-second limit. Cleanup is bounded to
+1 second. Timeout overrides are positive integer milliseconds; URI settings cannot disable these
+bounds. Limits apply to individual operations, not one overall deadline.
+
+The API owns and closes its connection. It does not borrow an application client or a Tenon transaction.
+Temporary tables, uncommitted changes, transaction-local settings, custom parsers, and other
+pool-only state are not inherited. `PGOPTIONS` environment settings are not automatically copied;
+use URI startup options or explicit session values. Standard read mappings describe Postgres.js
+values, so custom parser behavior needs a deliberate application decision.
+
+## Read the result
+
+| Field                   | Meaning                                                                                                                                                                     |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parameters`            | Parameter type OIDs, qualified PostgreSQL type names, and Postgres.js read representations. These are not accepted JavaScript input contracts.                              |
+| `columns`               | Ordered output names, PostgreSQL types, Postgres.js read representations, and source-column metadata where available.                                                       |
+| `columns[].nullability` | Always `"unknown"`. A source column's `notNull` constraint does not establish result nullability.                                                                           |
+| `rowType`               | A conservative `DescribedRow` TypeScript declaration. Fields include null; JSON/unmapped types stay unknown. Null when there are no output columns or names are duplicated. |
+| `issues`                | Findings with stable `code` fields, human-readable messages, and relevant column/type details.                                                                              |
+| `context`               | The separate inspection session's effective settings and read mapping profile.                                                                                              |
+
+Use issue codes for tooling; message text is descriptive:
+
+- `nullability-unknown`: result nullability has not been established.
+- `shape-unknown`: listed columns have unknown read types; JSON object structure is not inferred.
+- `unmapped-type`: the PostgreSQL type/OID lacks a verified Postgres.js mapping.
+- `duplicate-column`: repeated names would overwrite earlier values in object rows.
+
+Source `notNull` remains informational. Outer joins, grouping, and expressions can introduce nulls.
+An empty result set supplies no runtime samples. Unknown mappings and duplicate names are findings
+to handle explicitly, not a successful verification of a handwritten result type.
+
+## CLI
+
+Save the statement in `query.sql`, using `$1`, `$2`, and so on for parameters:
+
+```sql
+SELECT $1::integer AS id, count(*) AS total FROM pg_catalog.pg_class;
+```
+
+Supply `DATABASE_URL` through the application's normal environment setup:
+
+```sh
+npx tenon describe query.sql
+npx tenon describe query.sql --search-path mail,public --time-zone UTC
+```
+
+The CLI prints the description as JSON. Options are `--role`, `--search-path`, `--time-zone`,
+`--connect-timeout-ms`, `--statement-timeout-ms`, and `--lock-timeout-ms`. Migration/generation
+options such as `--namespace` and `--check` are rejected. No environment files are loaded.
+
+Exit code 0 means PostgreSQL described the statement, even if the report contains unresolved
+issues. Exit code 1 means input, connection, timeout, or PostgreSQL analysis failed. No query values
+are bound and no inspected statement is executed, including writes and locking statements.
+
+## Keep execution assertions
+
+For each meaningful query-builder variant, describe the finished SQL and run it through the
+application's actual Tenon/Postgres.js connection against its test database. Assert complete relevant rows
+and effects: nulls, JSON contents, precision, ordering, empty results, ownership, and rollback.
+Include absent relationships, pagination ties, and empty aggregates where relevant. Keep those
+tests alongside the query and run the application's normal TypeScript compiler.
+
+Description can succeed for an invalid bound value, a write that violates a constraint, or an
+operation the runtime role may not execute. Execution tests establish behavior for the exercised
+inputs; they are not a proof for every possible input. Inspecting one variant does not cover
+other branches or detect stale TypeScript annotations elsewhere in the application.
+
+Describe does not bind runtime values. Cast standalone parameter projections, for example
+`SELECT $1::boolean AS enabled`, so SQL establishes their types. Execution can otherwise infer a
+type from a JavaScript value that an inspection without values cannot establish.