@kequtech/tenon-orm 0.4.0 → 0.4.2

package/docs/schema-types.md

@@ -0,0 +1,263 @@
+# Schema types and values
+
+Tenon can generate TypeScript declarations from an existing PostgreSQL schema. Generation is
+optional and works with any migration runner. It describes table storage; your query still defines
+the selected columns, joins, and expressions.
+
+## Generate and check a file
+
+Use the application's configured database instance, after migrations have committed:
+
+```ts
+await db.generateTypes({ out: 'src/generated-schema.d.ts' });
+await db.generateTypes({ out: 'src/generated-schema.d.ts', check: true });
+```
+
+The first call writes declarations. The second rejects if they are missing or stale, without
+rewriting them. Use it in CI to verify committed output. The
+[getting-started script](human-guide.md#generate-types) provides a complete command-line wrapper.
+
+`namespace` defaults to `public`, independently of runtime `search_path`. Pass it explicitly for a
+different schema. Paths resolve from the working directory. Keep exact output unchanged and exclude
+it from automatic formatting.
+
+Generation uses the instance's pool and codecs. It is available on `db`, outside callback
+transactions. It uses a repeatable-read catalog snapshot and shares the migration advisory lock;
+use a direct or session-pooled connection. It needs no migration files or Tenon history.
+
+Tenon creates parent directories and replaces the entire output file atomically. With `check: true`,
+it creates no directories, writes no files, and includes a bounded diff for stale output. An optional
+`onWarning(message)` can be synchronous or asynchronous; the default is `console.warn`. Warning
+handler failures reject generation before output changes. Other filesystem errors propagate.
+
+For source text without file handling, use
+`generateDefinitions({ connection, namespace?, onWarning? }): Promise<string>`. Pass the configured
+pool or connection options to retain runtime read mappings.
+
+## Read the generated types
+
+For the table from [Getting started](human-guide.md#create-and-apply-a-migration), the important
+parts of the generated declaration look like this:
+
+```ts
+import type { Parameter } from '@kequtech/tenon-orm';
+
+export type Database = {
+  users: {
+    row: {
+      id: number;
+      email: string;
+      active: boolean;
+    };
+    insert: {
+      id?: never;
+      email: string | Parameter;
+      active?: boolean | Parameter | undefined;
+    };
+    update: {
+      id?: never;
+      email?: string | Parameter | undefined;
+      active?: boolean | Parameter | undefined;
+    };
+  };
+};
+```
+
+The real file also contains schema-summary comments for the tables, columns, keys, indexes,
+constraints, and relevant domain definitions. Generation includes ordinary tables and partitioned
+roots in one schema; it excludes attached partitions, views, materialized views, and Tenon's history
+table. It does not generate models, relationship methods, migrations, or validators.
+
+Use the types explicitly:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+import type { Database } from './generated-schema.js';
+
+type UserSummary = Pick<Database['users']['row'], 'id' | 'email'>;
+const input = { email: 'reader@example.test' } satisfies Database['users']['insert'];
+
+const user = await db.query(
+  sql<UserSummary>`INSERT INTO public.users ${sql.insertValues(input)} RETURNING id, email`,
+  { returns: 'one' },
+);
+```
+
+A table's `row` type describes its complete stored row. Use `Pick` for a projection and a separate
+type for joins or aggregates. `sql<Row>` does not check that your SQL returns that shape. See
+[query checking](query-checking.md) and [database tests](query-inspection.md#test-the-same-statement).
+
+### Application aliases
+
+Keep shorter names in a handwritten module so regeneration preserves them:
+
+```ts
+// src/schema-types.ts
+import type { Database } from './generated-schema.js';
+
+export type UserRow = Database['users']['row'];
+export type UserInsert = Database['users']['insert'];
+export type UserUpdate = Database['users']['update'];
+```
+
+The generated `Database` is a schema map, distinct from Tenon's runtime `Database` interface. If a
+module needs both, alias one of the imports.
+
+## Insert and update inputs
+
+Insert fields are required when writable, nonnullable, and without a default. Other writable insert
+fields and all writable update fields are optional, with explicit undefined accepted even under
+`exactOptionalPropertyTypes`.
+
+- Computed columns and `GENERATED ALWAYS` identity columns use optional `never` fields.
+- Serial and `GENERATED BY DEFAULT` identity fields are optional on insert and writable on update.
+  Other primary keys remain writable.
+- Domain defaults count; column defaults take precedence. Write nullability respects the domain
+  chain as well as the column.
+- Every writable field accepts an explicit `Parameter` in addition to its plain input types.
+
+Apply types through an annotation, `satisfies`, or a helper generic. Merely generating a file does
+not check writes. Use `Pick` or `Omit` for application restrictions, and validate external input.
+The types do not enforce CHECK constraints, JSON members, authorization, or a nonempty patch.
+
+The [mutation helpers](mutations.md) omit undefined fields for updates and use defaults for missing
+insert values. A selected column list can discard a required input even when the full object is
+well typed; PostgreSQL still enforces constraints.
+
+## Value mappings
+
+These are the default driver representations. SQL NULL is `null`; nullable generated columns add
+null to their type. Input encoding and output decoding are separate choices.
+
+| PostgreSQL value                                            | Default read                                           | Plain write input                                             |
+| ----------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
+| smallint, integer, serial, oid                              | `number`                                               | `number`                                                      |
+| bigint, bigserial, `count(*)`                               | Exact `string`                                         | Exact string or bigint                                        |
+| numeric/decimal                                             | `string`                                               | String or bigint                                              |
+| real, double precision                                      | `number`                                               | Finite number                                                 |
+| boolean                                                     | `boolean`                                              | Boolean                                                       |
+| text, UUID, other textual types                             | `string`                                               | String                                                        |
+| enum                                                        | Catalog label union in default-registry generated rows | Label union                                                   |
+| date, timestamp, timestamptz                                | `string`                                               | String, Date, or supported Temporal value                     |
+| time, interval                                              | `string`                                               | String or supported Temporal value                            |
+| timetz                                                      | `string`                                               | String                                                        |
+| json/jsonb                                                  | `unknown`                                              | Encoded JSON string; use `json(value)` for a parameter        |
+| bytea                                                       | `Uint8Array`                                           | Uint8Array                                                    |
+| Supported built-in arrays                                   | Recursive readonly `PgArray<T>`                        | Encoded PostgreSQL array text; use `param` for an array value |
+| Unrecognized types and dynamic enum/domain/extension arrays | Wire-text `string`                                     | Encoded string or explicit parameter                          |
+
+Generated inputs conservatively describe column-compatible representations; an explicit `Parameter`
+is accepted for every writable column. PostgreSQL checks ranges and text formats. Plain undefined,
+objects, and arrays are rejected as bound parameters. See [JSON and arrays](mutations.md#json-and-postgresql-arrays).
+
+Bigint and numeric arrays retain exact strings. Use `BigInt(value)` for exact integer arithmetic;
+convert to number only after checking the safe integer range. Command `rowCount` is a number or null,
+independent of SQL aggregate values; counts beyond the safe integer range reject rather than round.
+
+Temporal strings preserve precision and infinity spellings. Date inputs encode in UTC; use a calendar
+date string or corresponding Temporal plain value when an instant is not intended. Inputs do not
+change output types. JSON numbers follow JavaScript number precision; parsed JSON null and SQL NULL
+both become null. For raw JSON text or Date/bigint outputs, configure codecs.
+
+## Custom codecs
+
+Configure the registry on the application's connection. For example:
+
+```ts
+import { builtin, createTenon, defaultCodecs } from '@kequtech/tenon-orm';
+
+const codecs = defaultCodecs.with(builtin.int8BigInt).with(builtin.timestamptzDate);
+const db = createTenon({ connection: { connectionString: connection, codecs } });
+```
+
+Int8 now reads as bigint, and timestamptz reads as a millisecond-precision Date. Regenerate using this
+instance. Scalar overrides affect derived built-in arrays; explicit array overrides win. Date and
+Temporal output codecs reject infinity and values outside their supported ranges.
+
+For Temporal, import `createTemporalCodecs` from Tenon and supply a native or compatible polyfill
+implementation. Tenon does not install a polyfill or change globals. A polyfill can provide its own
+generated type namespace:
+
+```ts
+import { Temporal } from '@js-temporal/polyfill';
+import { createTemporalCodecs, defaultCodecs } from '@kequtech/tenon-orm';
+
+const temporal = createTemporalCodecs(Temporal, {
+  typescriptNamespace: 'import("@js-temporal/polyfill").Temporal',
+});
+const codecs = defaultCodecs.with(temporal.date).with(temporal.timestamptz);
+```
+
+Install the polyfill only if the application needs it. With native Temporal, the consuming TypeScript
+configuration needs the corresponding Temporal library declarations.
+
+A custom text codec can declare `text.typescript` to describe its non-NULL output. Generation and
+checking consume the registry's metadata. An unidentified decoder warns and becomes `unknown`;
+a declared representation is trusted, not runtime validation. Under a custom registry, enum output
+may remain string because a decoder can transform labels; enum write inputs retain catalog choices.
+
+Use the same registry for execution, generation, inspection, and source checking. Relative type-import
+expressions resolve from the generated file for saved declarations and from the tsconfig directory
+for checking. Prefer a package or configured alias that resolves in both places. Tenon does not
+execute referenced modules. See [custom-codec checking](query-checking.md#programmatic-use-and-custom-codecs).
+
+Catalog queries use default result decoding on the same borrowed session, so application codecs do
+not alter Tenon's metadata inputs. Output codec choices do not select input encoders.
+
+## Persistence and domain values
+
+Storage types can be broader than application types. Text CHECK constraints do not become unions,
+and JSON reads stay unknown. Validate external data before writing and database data before narrowing
+it to a domain type.
+
+For an additional `public.sessions(id text PRIMARY KEY, data jsonb NOT NULL, expires_at timestamptz
+NOT NULL)` table, a JSON validator can be shared by writes and reads:
+
+```ts
+import { json, sql } from '@kequtech/tenon-orm';
+
+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 };
+}
+
+const id = 'example-session';
+const expiresAt = new Date(Date.now() + 60_000);
+await db.query(sql`INSERT INTO public.sessions (id, data, expires_at)
+  VALUES (${id}, ${json(sessionData({ userId: 'user-42' }))}, ${expiresAt})`);
+
+const row = await db.query(
+  sql<{ id: string; data: unknown; expires_at: string }>`
+    SELECT id, data, expires_at FROM public.sessions
+    WHERE id = ${id} AND isfinite(expires_at) AND expires_at > now()
+  `,
+  { returns: 'oneOrNone' },
+);
+if (row) {
+  const data = sessionData(row.data);
+  const expiry = new Date(row.expires_at);
+  if (!Number.isFinite(expiry.getTime())) throw new Error('Expected a finite timestamp');
+  // data.userId and expiry now have validated application representations.
+}
+```
+
+`isfinite` excludes positive infinity, which would otherwise pass `expires_at > now()`. Keep the
+same policy in expiry-sensitive updates/deletes. Test expired and infinite values, and retain the
+application's authentication and authorization checks.
+
+## What freshness checks establish
+
+`check: true` compares the exact generated file with output from this database and codec registry.
+It does not check query annotations, pending migrations, functions, privileges, or every database
+object. A driver or generator update can change output without schema drift. Review generated diffs
+after upgrades. Generated text and schema-summary formatting are not version-stable schema
+fingerprints; see [baseline verification](adoption-guide.md#check-and-adopt-an-existing-database).

package/docs/sql.md

@@ -0,0 +1,212 @@
+# Writing queries
+
+Tenon executes PostgreSQL SQL. A query has SQL text, separately bound values, and an optional
+TypeScript type for one returned row. Examples use the `public.users` table from
+[Getting started](human-guide.md) and an existing `db` instance.
+
+## Bind values
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+
+const email = 'reader@example.test';
+const query = sql<{ id: number; email: string }>`
+  SELECT id, email FROM public.users WHERE email = ${email}
+`;
+// query.text: SQL containing WHERE email = $1
+// query.values: ['reader@example.test']
+const user = await db.query(query, { returns: 'oneOrNone' });
+```
+
+Constructing `query` does not contact PostgreSQL. Execute it with `db.query` or `tx.query`. Do not
+quote interpolations or write `$1` placeholders inside templates.
+
+Plain inputs accept null, strings, finite numbers, bigint, booleans, valid Date values, supported
+Temporal values, and Uint8Array. Arrays and objects need explicit encoders; undefined is not a bound
+SQL value. See [JSON and arrays](mutations.md#json-and-postgresql-arrays). Bound data must remain
+unchanged until the query settles.
+
+## Choose the result you need
+
+Use `one` for exactly one row, `oneOrNone` for zero or one, and `many` for an array. The default
+`native` result provides rows and command metadata:
+
+```ts
+const result = await db.query(sql`UPDATE public.users SET active = false WHERE id = ${42}`);
+console.log(result.command, result.rowCount); // UPDATE, number of affected rows
+```
+
+The modes check rows actually returned. An `UPDATE` without `RETURNING` returns no rows even when
+it changes data. Modes do not add `RETURNING` or `LIMIT`. See the
+[result reference](reference.md#queries-and-result-modes) for exact types.
+
+Reuse queries with functions that accept `QueryClient`, so the same function can receive `db` or
+`tx`. The [getting-started example](human-guide.md#reuse-a-query) shows this pattern.
+
+## Join related tables
+
+Add this example table in a migration:
+
+```sql
+CREATE TABLE public.posts (
+  id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  user_id integer NOT NULL REFERENCES public.users(id),
+  title text NOT NULL
+);
+```
+
+Select and alias the columns you want. There is no relationship configuration or automatic loading:
+
+```ts
+type PostWithAuthor = { id: number; title: string; authorEmail: string };
+
+const posts = await db.query(
+  sql<PostWithAuthor>`
+    SELECT p.id, p.title, u.email AS "authorEmail"
+    FROM public.posts AS p
+    JOIN public.users AS u ON u.id = p.user_id
+    WHERE u.active = ${true}
+    ORDER BY p.id
+  `,
+  { returns: 'many' },
+);
+```
+
+Use unique column names; selecting both `p.id` and `u.id` without aliases produces duplicate names,
+which the driver rejects. Quoted aliases preserve camelCase. An outer join can introduce null even
+for a source column declared `NOT NULL`; reflect that in the query's result type:
+
+```ts
+type UserWithPost = { userId: number; title: string | null };
+const rows = await db.query(
+  sql<UserWithPost>`
+    SELECT u.id AS "userId", p.title
+    FROM public.users AS u
+    LEFT JOIN public.posts AS p ON p.user_id = u.id
+    ORDER BY u.id, p.id
+  `,
+  { returns: 'many' },
+);
+```
+
+A user with several posts appears several times. Group rows in application code or use PostgreSQL
+aggregation when a nested result is needed. JSON aggregate output is `unknown` by default; validate
+it before narrowing to an application type.
+
+## Aggregate values
+
+```ts
+const totals = await db.query(
+  sql<{ userId: number; total: string }>`
+    SELECT u.id AS "userId", count(p.id) AS total
+    FROM public.users AS u
+    LEFT JOIN public.posts AS p ON p.user_id = u.id
+    GROUP BY u.id
+    ORDER BY u.id
+  `,
+  { returns: 'many' },
+);
+```
+
+`count(p.id)` counts matched posts, including zero for a user without posts. `count(*)` would also
+count that user's outer-join row. Both return PostgreSQL bigint, decoded as an exact string. Other
+aggregate result types depend on PostgreSQL's selected function and input type; use
+[inspection](query-inspection.md) when unsure.
+
+## Paginate with an explicit order
+
+For an integer ID cursor, validate `afterId` and `pageSize` in application code, then bind them:
+
+```ts
+async function usersAfter(afterId: number, pageSize: number) {
+  if (!Number.isInteger(afterId) || afterId < 0) throw new Error('Invalid cursor');
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+    throw new Error('Page size must be between 1 and 100');
+  }
+  return db.query(
+    sql<{ id: number; email: string }>`
+      SELECT id, email FROM public.users
+      WHERE id > ${afterId} ORDER BY id LIMIT ${pageSize}
+    `,
+    { returns: 'many' },
+  );
+}
+```
+
+Start with `afterId = 0`, then use the last returned ID for the next page. A unique ordering makes
+page boundaries deterministic. For another sort column, include a unique tiebreaker and carry both
+values in the cursor. Tenon does not add pagination or ordering.
+
+## Compose SQL fragments
+
+A fragment carries SQL and its bound values. It cannot execute alone and has no result type:
+
+```ts
+const pattern = '%example%';
+const condition = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
+const page = sql<{ id: number; email: string }>`
+  SELECT id, email FROM public.users WHERE ${condition} ORDER BY id LIMIT ${20}
+`;
+const total = sql<{ total: string }>`SELECT count(*) AS total FROM public.users WHERE ${condition}`;
+```
+
+Use `sql.join` for a list of conditions. It supports `'AND'`, `'OR'`, and `','`, without adding
+parentheses:
+
+```ts
+const terms = ['reader', 'example'];
+const filters = [sql.fragment`active = ${true}`];
+for (const term of terms) {
+  filters.push(sql.fragment`email ILIKE ${'%' + term + '%'}`);
+}
+const query = sql<{ id: number }>`
+  SELECT id FROM public.users WHERE ${sql.join(filters, 'AND')} ORDER BY id
+`;
+```
+
+The initial condition keeps the list nonempty. If every condition is optional, choose a complete
+query without `WHERE` when the list is empty. Retain required authorization conditions in every
+branch. `sql.join([])` and blank fragments fail. Parenthesize groups when mixing `AND` and `OR`.
+Parameters are numbered correctly across nested and repeated fragments.
+
+Runtime loops and dynamic fragment lists execute normally but remain unchecked by the optional
+[source checker](query-checking.md#supported-composition). Test their meaningful variants against
+the database. Fixed queries are easier to follow when composition is unnecessary.
+
+## Select names and SQL syntax safely
+
+Values and identifiers are different. Use `identifier` for approved schema/table/column names:
+
+```ts
+import { identifier } from '@kequtech/tenon-orm';
+
+const table = identifier('public', 'users');
+const query = sql<{ id: number }>`SELECT id FROM ${table} WHERE active = ${true}`;
+```
+
+This quotes `"public"."users"` as two components. It does not authorize access; map application
+choices to approved names before using it. Each component must contain 1–63 UTF-8 bytes and no NUL.
+
+Choose SQL syntax such as sort direction from fixed alternatives:
+
+```ts
+const descending = true;
+const direction = descending ? sql.fragment`DESC` : sql.fragment`ASC`;
+const query = sql<{ id: number }>`SELECT id FROM public.users ORDER BY id ${direction}`;
+```
+
+Interpolating the string `'DESC'` binds a value and does not create SQL syntax. Complete `sql`
+queries cannot be nested; use fragments for partial statements.
+
+## Execute SQL supplied by another component
+
+```ts
+import { unsafeSql } from '@kequtech/tenon-orm';
+
+const query = unsafeSql<{ id: number }>('SELECT id FROM public.users WHERE email = $1', [email]);
+```
+
+Use trusted SQL text and an explicit values array, including `[]` when there are no parameters.
+Never concatenate request data into the text. Tenon executes one statement per query; migrations
+have a separate multi-statement runner. For an adapter inside a transaction, see
+[transactional result adapters](reference.md#adapting-transactional-results).

package/package.json

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