@kequtech/tenon-orm 0.1.4 → 0.2.0

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.