@adrdp/pg-rest 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -1,99 +1,64 @@
-import { n as DbSession, r as Row, t as DbAdapter } from "./adapter-SqPs6SuJ.js";
+import { n as DbSession, r as Row, t as DbAdapter } from "./adapter-C2udR5IT.js";
+import { a as ForeignKey, c as SchemaCache, i as Column, o as FunctionDef, s as Relation, t as GenerateTypesOptions } from "./types-DaNxiC7H.js";
 
 //#region src/parse/request.d.ts
 type Method = "GET" | "HEAD" | "POST" | "PATCH" | "PUT" | "DELETE" | "OPTIONS";
 //#endregion
-//#region src/schema.d.ts
-interface Column {
-  readonly name: string;
-  /** Result of `format_type`, e.g. `integer`, `character varying(10)`, `text[]`. */
-  readonly type: string;
-  readonly nullable: boolean;
-  readonly hasDefault: boolean;
-  /** SQL text of the default expression, when there is one. */
-  readonly defaultExpr: string | null;
-  readonly generated: boolean;
-  readonly comment: string | null;
-  readonly position: number;
-}
-type RelationKind = "table" | "view" | "matview" | "foreign" | "partitioned";
-interface Relation {
-  readonly schema: string;
-  readonly name: string;
-  readonly kind: RelationKind;
-  readonly columns: ReadonlyArray<Column>;
-  readonly pk: ReadonlyArray<string>;
-  readonly uniques: ReadonlyArray<ReadonlyArray<string>>;
-  readonly insertable: boolean;
-  readonly updatable: boolean;
-  readonly deletable: boolean;
-  readonly comment: string | null;
-}
-interface ForeignKey {
-  readonly name: string;
-  readonly schema: string;
-  readonly table: string;
-  readonly cols: ReadonlyArray<string>;
-  readonly fschema: string;
-  readonly ftable: string;
-  readonly fcols: ReadonlyArray<string>;
+//#region src/errors.d.ts
+/**
+ * Error body, in the exact shape PostgREST returns:
+ * `{ code, message, details, hint }`.
+ */
+interface ErrorBody {
+  readonly code: string;
+  readonly message: string;
+  readonly details: string | null;
+  readonly hint: string | null;
 }
-interface FunctionArg {
-  readonly name: string;
-  readonly type: string;
-  readonly hasDefault: boolean;
-  readonly variadic: boolean;
+/**
+ * Thrown by the pure parts of the library (parsers, SQL builders). It is
+ * converted into an {@link ApiError} at the request boundary.
+ */
+declare class PgRestError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly details: string | null;
+  readonly hint: string | null;
+  readonly headers: Readonly<Record<string, string>>;
+  constructor(status: number, code: string, message: string, details?: string | null, hint?: string | null, headers?: Readonly<Record<string, string>>);
+  get body(): ErrorBody;
 }
-interface FunctionDef {
-  readonly schema: string;
-  readonly name: string;
-  readonly args: ReadonlyArray<FunctionArg>;
-  readonly returnType: string;
-  readonly returnsSet: boolean;
-  /** True if the function returns a composite / record / TABLE(...) row type. */
-  readonly returnsComposite: boolean;
-  readonly returnsVoid: boolean;
-  readonly volatility: "immutable" | "stable" | "volatile";
-  readonly comment: string | null;
-  /** The table when the function's only parameter is a table row (computed relationships). */
-  readonly argRelation?: {
-    readonly schema: string;
-    readonly name: string;
-  };
-  /** The table whose rows the function returns. */
-  readonly returnRelation?: {
-    readonly schema: string;
-    readonly name: string;
-  };
-  /** Planner row estimate; 1 on a set-returning function makes a computed relationship to-one. */
-  readonly rows: number;
-  /** Scalar functions returning a domain named like a media type (`"text/plain"`, …): the raw value is the body. */
-  readonly returnMediaType?: {
-    readonly name: string;
-    readonly bytea: boolean;
-  };
+/** An error that has already been mapped to an HTTP response. */
+declare class ApiError extends Error {
+  readonly _tag = "ApiError";
+  readonly status: number;
+  readonly body: ErrorBody;
+  readonly headers: Readonly<Record<string, string>>;
+  constructor(fields: {
+    readonly status: number;
+    readonly body: ErrorBody;
+    readonly headers: Readonly<Record<string, string>>;
+  });
 }
-/** A custom media type handler: an aggregate named after the media type that returns a domain (see PostgREST's "custom media types"). */
-interface MediaHandler {
-  readonly schema: string;
-  /** The aggregate's name, i.e. the media type (for example `text/plain`, or the catch-all). */
-  readonly mediaType: string;
-  /** The table whose rows it aggregates, or `undefined` for `anyelement`. */
-  readonly argRelation?: {
-    readonly schema: string;
-    readonly name: string;
-  };
-  /** True when the domain wraps `bytea` (the body is binary). */
-  readonly bytea: boolean;
+/** Failure talking to the database, carrying Postgres error fields. */
+interface DbErrorInfo {
+  /** SQLSTATE, e.g. "23505", or a custom code such as "PT401" / "PGRST". */
+  readonly sqlState: string;
+  readonly message: string;
+  readonly detail?: string | undefined;
+  readonly hint?: string | undefined;
 }
-interface SchemaCache {
-  readonly mediaHandlers: ReadonlyArray<MediaHandler>;
-  readonly schemas: ReadonlyArray<string>;
-  readonly relations: ReadonlyMap<string, Relation>;
-  readonly foreignKeys: ReadonlyArray<ForeignKey>;
-  readonly functions: ReadonlyMap<string, ReadonlyArray<FunctionDef>>;
+/** Normalized error thrown by a {@link DbAdapter}. */
+declare class DbQueryError extends Error implements DbErrorInfo {
+  readonly sqlState: string;
+  readonly detail?: string | undefined;
+  readonly hint?: string | undefined;
+  constructor(sqlState: string, message: string, detail?: string | undefined, hint?: string | undefined);
 }
 //#endregion
+//#region src/sql/write.d.ts
+type JsonObject = Record<string, unknown>;
+//#endregion
 //#region src/core.d.ts
 /** Who is making the request, as far as the database is concerned. */
 interface RequestContext {
@@ -113,7 +78,8 @@ interface PreRequestInfo {
   readonly claims: Readonly<Record<string, unknown>>;
   readonly method: Method;
   readonly path: string;
-  readonly request: Request;
+  /** The HTTP request, when the call came through `handle()`. In-process `query()` calls have none. */
+  readonly request?: Request | undefined;
 }
 interface CoreConfig {
   readonly schemas: ReadonlyArray<string>;
@@ -134,56 +100,552 @@ interface CoreConfig {
   readonly serverUrl?: string | undefined;
 }
 //#endregion
-//#region src/errors.d.ts
+//#region src/query.d.ts
+/** A value a filter compares against. */
+type Scalar = string | number | boolean | null;
+/** The PostgREST filter operators (https://docs.postgrest.org/en/v16/references/api/tables_views.html#operators). */
+type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "match" | "imatch" | "in" | "is" | "isdistinct" | "fts" | "plfts" | "phfts" | "wfts" | "cs" | "cd" | "ov" | "sl" | "sr" | "nxl" | "nxr" | "adj";
+/** An operator with its modifiers: `not.`, a quantifier (`eq(any)`) or a text-search config (`fts(english)`). */
+interface FilterSpec {
+  readonly op: FilterOp;
+  readonly value?: Scalar | ReadonlyArray<Scalar> | undefined;
+  /** Invert the operator (`not.eq.1`). */
+  readonly not?: boolean | undefined;
+  /** Apply the operator to every element of an array column (`eq(any)`). */
+  readonly quantifier?: "any" | "all" | undefined;
+  /** Text-search configuration: `{ op: "fts", config: "english", value: "cat" }` -> `fts(english).cat`. */
+  readonly config?: string | undefined;
+}
 /**
- * Error body, in the exact shape PostgREST returns:
- * `{ code, message, details, hint }`.
+ * One condition. A plain value means `eq` (and `null` means `is.null`); a tuple is
+ * `[operator, value]`; the object form adds the modifiers.
  */
-interface ErrorBody {
-  readonly code: string;
-  readonly message: string;
-  readonly details: string | null;
-  readonly hint: string | null;
-}
+type Filter = Scalar | readonly [FilterOp, Scalar | ReadonlyArray<Scalar>] | FilterSpec;
 /**
- * Thrown by the pure parts of the library (parsers, SQL builders). It is
- * converted into an {@link ApiError} at the request boundary.
+ * Conditions on columns, ANDed together, plus the reserved keys `and` and `or` which
+ * take a list of nested groups. A key may be a dotted path into an embedded resource
+ * (`"orders.total"`), exactly like the query string.
  */
-declare class PgRestError extends Error {
+interface Where {
+  readonly [column: string]: Filter | ReadonlyArray<Where> | undefined;
+}
+/** `"created"`, or the object form for a direction and null placement. */
+type Order = string | {
+  readonly column: string;
+  readonly desc?: boolean | undefined;
+  readonly nulls?: "first" | "last" | undefined;
+};
+/** Columns to return. A string is a column (`"id"`, `"name->>first"`, `"total::text"`, `"label:name"`). */
+type Select = ReadonlyArray<string | {
+  readonly [relation: string]: Select | Embed;
+}>;
+/** An embedded resource, with its own columns, filters, order and paging. */
+interface Embed {
+  readonly select?: Select | undefined;
+  /** Drop parent rows that have no match (`!inner`). */
+  readonly inner?: boolean | undefined;
+  /** Merge the embedded columns into the parent row (`...rel(*)`). */
+  readonly spread?: boolean | undefined;
+  /** Disambiguate the relationship: a foreign key name, or the table to join through. */
+  readonly hint?: string | undefined;
+  /** Rename the resource in the output (`client:clients(*)`). */
+  readonly as?: string | undefined;
+  readonly where?: Where | undefined;
+  readonly order?: ReadonlyArray<Order> | undefined;
+  readonly limit?: number | undefined;
+  readonly offset?: number | undefined;
+}
+/** What a write returns: the affected rows, or nothing. */
+type QueryReturning = "representation" | "minimal";
+interface Common$1 {
+  /** One of the exposed schemas. Defaults to the first one. */
+  readonly schema?: string | undefined;
+  readonly select?: Select | undefined;
+  readonly where?: Where | undefined;
+  readonly order?: ReadonlyArray<Order> | undefined;
+  readonly limit?: number | undefined;
+  readonly offset?: number | undefined;
+  /** Return one object instead of an array. 0 or 2+ rows is a 406 `PGRST116`, like `vnd.pgrst.object+json`. */
+  readonly single?: boolean | undefined;
+  /** Also count the matching rows, ignoring paging (`Prefer: count=`). */
+  readonly count?: "exact" | "planned" | "estimated" | undefined;
+  /** Leave `null` fields out of the result (`nulls=stripped`). */
+  readonly stripNulls?: boolean | undefined;
+  /** Refuse the call if it would affect more rows than this (`Prefer: max-affected`). */
+  readonly maxAffected?: number | undefined;
+  /** Run the statement in this time zone (`Prefer: timezone=`). */
+  readonly timezone?: string | undefined;
+}
+/** Read rows from a table or view. */
+interface SelectQuery extends Common$1 {
+  readonly table: string;
+  readonly action?: "select" | undefined;
+}
+/** Insert rows, or upsert them with `action: "upsert"`. */
+interface InsertQuery extends Common$1 {
+  readonly table: string;
+  readonly action: "insert" | "upsert";
+  readonly rows: JsonObject | ReadonlyArray<JsonObject>;
+  /** Columns the conflict is resolved on (`on_conflict`). Defaults to the primary key. */
+  readonly onConflict?: ReadonlyArray<string> | undefined;
+  /** Only insert these columns, ignoring any other key in `rows`. */
+  readonly columns?: ReadonlyArray<string> | undefined;
+  /** What to do with columns missing from `rows`: their `DEFAULT` (the default) or `null`. */
+  readonly missing?: "default" | "null" | undefined;
+  readonly returning?: QueryReturning | undefined;
+}
+/** Update the rows matching `where`. */
+interface UpdateQuery extends Common$1 {
+  readonly table: string;
+  readonly action: "update";
+  readonly set: JsonObject;
+  readonly returning?: QueryReturning | undefined;
+}
+/** Delete the rows matching `where`. */
+interface DeleteQuery extends Common$1 {
+  readonly table: string;
+  readonly action: "delete";
+  readonly returning?: QueryReturning | undefined;
+}
+/** Call a function, like `POST /rpc/name`. `select`, `where` and `order` apply to its result. */
+interface RpcQuery extends Common$1 {
+  readonly rpc: string;
+  readonly args?: Readonly<Record<string, unknown>> | undefined;
+}
+type QueryInput = SelectQuery | InsertQuery | UpdateQuery | DeleteQuery | RpcQuery;
+/** What a query returned. `count` is set only when it was asked for. */
+interface QueryResult<T$1 = unknown> {
+  /** The rows, the single object when `single` is set, or `null` when there is no body. */
+  readonly data: T$1;
+  /** Rows matching the filters, ignoring `limit`/`offset`. */
+  readonly count?: number | undefined;
+  /** The status the same call would answer with over HTTP (201 after an insert, 204 after a minimal write...). */
   readonly status: number;
-  readonly code: string;
-  readonly details: string | null;
-  readonly hint: string | null;
-  readonly headers: Readonly<Record<string, string>>;
-  constructor(status: number, code: string, message: string, details?: string | null, hint?: string | null, headers?: Readonly<Record<string, string>>);
-  get body(): ErrorBody;
 }
-/** An error that has already been mapped to an HTTP response. */
-declare class ApiError extends Error {
-  readonly _tag = "ApiError";
+/**
+ * What a query returned, as a value instead of an exception: exactly one of `data` and `error`
+ * is set, so narrowing on `error` leaves `data` non-null.
+ */
+type QuerySafeResult<T$1 = unknown> = (QueryResult<T$1> & {
+  readonly error: null;
+}) | {
+  readonly data: null;
+  readonly error: QueryError;
+  readonly count?: undefined;
+  /** The status the failure would have answered with over HTTP. */
   readonly status: number;
-  readonly body: ErrorBody;
-  readonly headers: Readonly<Record<string, string>>;
-  constructor(fields: {
-    readonly status: number;
-    readonly body: ErrorBody;
-    readonly headers: Readonly<Record<string, string>>;
+};
+/** A query that failed, with the PostgREST error body and the input that produced it. */
+declare class QueryError extends ApiError {
+  readonly input: QueryInput;
+  constructor(input: QueryInput, api: ApiError, options?: {
+    readonly cause?: unknown;
   });
 }
-/** Failure talking to the database, carrying Postgres error fields. */
-interface DbErrorInfo {
-  /** SQLSTATE, e.g. "23505", or a custom code such as "PT401" / "PGRST". */
-  readonly sqlState: string;
-  readonly message: string;
-  readonly detail?: string | undefined;
-  readonly hint?: string | undefined;
+//#endregion
+//#region src/typed.d.ts
+/**
+ * The types `generateTypes` emits, as constraints. They describe a database, not a query: see
+ * {@link TypedQuery} for what a call may say, and {@link QueryData} for what it returns.
+ */
+interface AnyRelation {
+  readonly row: Record<string, unknown>;
+  readonly insert: Record<string, unknown>;
+  readonly update: Record<string, unknown>;
+  readonly pk: ReadonlyArray<string>;
+  readonly insertable: boolean;
+  readonly updatable: boolean;
+  readonly deletable: boolean;
+  readonly rel: Record<string, {
+    readonly rel: string;
+    readonly to: "one" | "many";
+  }>;
 }
-/** Normalized error thrown by a {@link DbAdapter}. */
-declare class DbQueryError extends Error implements DbErrorInfo {
-  readonly sqlState: string;
-  readonly detail?: string | undefined;
-  readonly hint?: string | undefined;
-  constructor(sqlState: string, message: string, detail?: string | undefined, hint?: string | undefined);
+interface AnySignature {
+  readonly args: unknown;
+  readonly returns: unknown;
+  readonly set: boolean;
+}
+interface AnySchema {
+  readonly relations: Record<string, AnyRelation>;
+  readonly functions: Record<string, ReadonlyArray<AnySignature>>;
+}
+/** What `createPgRest<Db>` expects: the type `generateTypes` exports. */
+interface AnyDatabase {
+  readonly default: string;
+  readonly schemas: Record<string, AnySchema>;
+}
+type Schema<Db extends AnyDatabase> = keyof Db["schemas"] & string;
+type Relations<Db extends AnyDatabase, S$1 extends Schema<Db>> = Db["schemas"][S$1]["relations"];
+type Functions<Db extends AnyDatabase, S$1 extends Schema<Db>> = Db["schemas"][S$1]["functions"];
+type Table<Db extends AnyDatabase, S$1 extends Schema<Db>> = keyof Relations<Db, S$1> & string;
+type Row$1<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = Relations<Db, S$1>[T$1]["row"];
+type Column$1<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = keyof Row$1<Db, S$1, T$1> & string;
+type Embeds<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = Relations<Db, S$1>[T$1]["rel"];
+/** The relation an embedded name points at, if it is one of this schema's. */
+type Target<Db extends AnyDatabase, S$1 extends Schema<Db>, E$1> = E$1 extends {
+  rel: infer R;
+} ? R extends Table<Db, S$1> ? R : never : never;
+type UnionToIntersection<U$1> = (U$1 extends unknown ? (x: U$1) => void : never) extends ((x: infer I) => void) ? I : never;
+/** Flatten an intersection into one object, so hovers and errors read as a plain row. */
+type Flatten<T$1> = T$1 extends object ? { [K in keyof T$1]: T$1[K] } & {} : T$1;
+/**
+ * One item of a `select`. Columns, `alias:column`, `*`, and embedded resources as
+ * `{ relation: [...] }` or `{ relation: { select, inner, limit, ... } }`.
+ *
+ * PostgREST's other string forms -- casts, JSON paths, aggregates -- are not described here: they
+ * change the type of the value or invent a column, and parsing them from a string literal would
+ * cost more than it gives. Use an untyped instance for those.
+ */
+type SelectItem<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = "*" | Column$1<Db, S$1, T$1> | `${string}:${Column$1<Db, S$1, T$1>}` | { readonly [E in keyof Embeds<Db, S$1, T$1>]?: Embed$1<Db, S$1, Target<Db, S$1, Embeds<Db, S$1, T$1>[E]>> };
+type SelectList<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = ReadonlyArray<SelectItem<Db, S$1, T$1>>;
+/** An embedded resource: its columns, or an object with its own filters and paging. */
+type EmbedOptions<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = {
+  /** The columns of the embedded resource, and its own embeds. Defaults to all of them. */
+  readonly select?: SelectList<Db, S$1, T$1>;
+  /** `!inner`: drop the parent rows that have no match here. A to-one embed stops being nullable. */
+  readonly inner?: boolean;
+  /** Which relationship to follow, when more than one leads here: a foreign key name, or a table. */
+  readonly hint?: string;
+  /** Filters on the embedded rows, not on the parent's. */
+  readonly where?: Where$1<Db, S$1, T$1>;
+  /** How to sort the embedded rows. */
+  readonly order?: ReadonlyArray<Order$1<Db, S$1, T$1>>;
+  /** At most this many embedded rows per parent row. */
+  readonly limit?: number;
+  /** Skip this many embedded rows per parent row. */
+  readonly offset?: number;
+};
+/**
+ * An embedded resource: its columns, or the long form with its own filters and paging.
+ *
+ * `as` and `spread` are exclusive, because PostgREST's grammar has no way to write both:
+ * `...alias:table(*)` does not parse (`PGRST100`), so a type that accepted it would promise
+ * something the request cannot express.
+ */
+type Embed$1<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = SelectList<Db, S$1, T$1> | (EmbedOptions<Db, S$1, T$1> & {
+  /** Rename the resource in the result. The inferred key follows. */
+  readonly as?: string;
+  readonly spread?: never;
+}) | (EmbedOptions<Db, S$1, T$1> & {
+  /**
+   * `...rel(*)`: merge these columns into the parent row instead of nesting them. Spreading a
+   * to-many relationship turns each column into an array of its values.
+   */
+  readonly spread: true;
+  readonly as?: never;
+});
+/** The columns of `Items` picked out of a plain row, `alias:column` renamed, `*` taking them all. */
+type PickedFrom<R$1, Items$1> = Items$1 extends ReadonlyArray<unknown> ? Flatten<UnionToIntersection<{ [I in keyof Items$1]: Items$1[I] extends "*" ? R$1 : Items$1[I] extends keyof R$1 & string ? { [K in Items$1[I]]: R$1[K] } : Items$1[I] extends `${infer A}:${infer C}` ? C extends keyof R$1 & string ? { [K in A]: R$1[C] } : unknown : unknown }[number]>> : R$1;
+/** What a function's result may be asked for: its columns, if it has any. */
+type RowSelect<R$1> = R$1 extends object ? ReadonlyArray<"*" | (keyof R$1 & string) | `${string}:${keyof R$1 & string}`> : never;
+/** The row a `select` produces: the picked columns, the aliases renamed, the embeds nested. */
+type Selected<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Items$1> = Items$1 extends ReadonlyArray<unknown> ? Flatten<UnionToIntersection<{ [I in keyof Items$1]: ItemOf<Db, S$1, T$1, Items$1[I]> }[number]>> : Row$1<Db, S$1, T$1>;
+type ItemOf<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Item> = Item extends "*" ? Row$1<Db, S$1, T$1> : Item extends Column$1<Db, S$1, T$1> ? { [K in Item]: Row$1<Db, S$1, T$1>[K] } : Item extends `${infer A}:${infer C}` ? C extends Column$1<Db, S$1, T$1> ? { [K in A]: Row$1<Db, S$1, T$1>[C] } : unknown : Item extends object ? Embedded<Db, S$1, T$1, Item> : unknown;
+/** Keys of an embed object that are spread into the parent, and the ones that stay nested. */
+type SpreadKeys<Item> = { [E in keyof Item]: Item[E] extends {
+  spread: true;
+} ? E : never }[keyof Item];
+type NestedKeys<Item> = { [E in keyof Item]: Item[E] extends {
+  spread: true;
+} ? never : E }[keyof Item];
+/** One `{ relation: ... }` item: nested resources under their own key, spread ones merged in. */
+type Embedded<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Item> = NestedPart<Db, S$1, T$1, Item> & SpreadPart<Db, S$1, T$1, Item>;
+/**
+ * Each half is skipped when it has no keys: a key-remapped mapped type over an empty key set is not
+ * the empty object -- it carries a string index signature, which would spread to the whole row.
+ */
+type NestedPart<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Item> = [NestedKeys<Item>] extends [never] ? unknown : { [E in NestedKeys<Item> & keyof Item & keyof Embeds<Db, S$1, T$1> as Item[E] extends {
+  as: infer A extends string;
+} ? A : E]: EmbedOf<Db, S$1, Target<Db, S$1, Embeds<Db, S$1, T$1>[E]>, Embeds<Db, S$1, T$1>[E], Item[E]> };
+type SpreadPart<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Item> = [SpreadKeys<Item>] extends [never] ? unknown : UnionToIntersection<{ [E in SpreadKeys<Item> & keyof Item & keyof Embeds<Db, S$1, T$1>]: SpreadOf<Db, S$1, Target<Db, S$1, Embeds<Db, S$1, T$1>[E]>, Embeds<Db, S$1, T$1>[E], Item[E]> }[SpreadKeys<Item> & keyof Item & keyof Embeds<Db, S$1, T$1>]>;
+/**
+ * A spread embed has no key of its own: its columns join the parent row. Spreading a to-many
+ * relationship turns each of them into an array of that column's values.
+ */
+type SpreadOf<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Rel, Spec> = Rel extends {
+  to: "many";
+} ? Arrayed<SpreadRow<Db, S$1, T$1, Spec>> : SpreadRow<Db, S$1, T$1, Spec>;
+type SpreadRow<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Spec> = Spec extends {
+  select: infer Items;
+} ? Selected<Db, S$1, T$1, Items> : Row$1<Db, S$1, T$1>;
+type Arrayed<R$1> = { [K in keyof R$1]: R$1[K][] };
+type EmbedOf<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>, Rel, Spec> = Spec extends ReadonlyArray<unknown> ? Shaped<Rel, Spec, Selected<Db, S$1, T$1, Spec>> : Spec extends {
+  select: infer Items;
+} ? Shaped<Rel, Spec, Selected<Db, S$1, T$1, Items>> : Shaped<Rel, Spec, Row$1<Db, S$1, T$1>>;
+/**
+ * A to-many embed is an array. A to-one embed is the row, or null when there is no match -- unless
+ * the join is `inner`, which drops the parent rows that have none.
+ */
+type Shaped<Rel, Spec, R$1> = Rel extends {
+  to: "many";
+} ? R$1[] : Spec extends {
+  inner: true;
+} ? R$1 : R$1 | null;
+/** A condition on a column: the value itself (`eq`), a `[operator, value]` tuple, or the full form. */
+type Filter$1<V> = V | null | readonly [FilterOp, V | ReadonlyArray<V> | null] | {
+  readonly op: FilterOp;
+  readonly value?: V | ReadonlyArray<V> | null;
+  readonly not?: boolean;
+  readonly quantifier?: "any" | "all";
+  readonly config?: string;
+};
+type WhereOf<R$1, EmbedKeys extends string> = { readonly [K in keyof R$1 & string]?: Filter$1<R$1[K]> } & {
+  readonly and?: ReadonlyArray<WhereOf<R$1, EmbedKeys>>;
+  readonly or?: ReadonlyArray<WhereOf<R$1, EmbedKeys>>;
+} & {
+  /**
+   * A filter on an embedded resource, by its dotted path, the way the query string writes it. The
+   * column belongs to the other resource, so only the shape of the condition is checked here --
+   * prefer the embed's own `where`, which knows its columns.
+   */
+readonly [K in `${EmbedKeys}.${string}`]?: Filter$1<Scalar> };
+type OrderOf<R$1> = (keyof R$1 & string) | `${keyof R$1 & string}.${"asc" | "desc"}` | `${keyof R$1 & string}.${"asc" | "desc"}.${"nullsfirst" | "nullslast"}` | {
+  readonly column: keyof R$1 & string;
+  readonly desc?: boolean;
+  readonly nulls?: "first" | "last";
+};
+type Where$1<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = WhereOf<Row$1<Db, S$1, T$1>, keyof Embeds<Db, S$1, T$1> & string>;
+type Order$1<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = OrderOf<Row$1<Db, S$1, T$1>>;
+interface Common {
+  /** At most this many rows. A read that is capped answers `206` with a `Content-Range`. */
+  readonly limit?: number;
+  /** Skip this many rows. Needs an `order` to mean anything stable. */
+  readonly offset?: number;
+  /**
+   * Return one object instead of an array. Anything other than exactly one row is a `406`
+   * (`PGRST116`), so `data` is the row itself, never `undefined`.
+   */
+  readonly single?: boolean;
+  /**
+   * Also count the rows the filters match, ignoring `limit`/`offset`, into `count`:
+   * `"exact"` counts them, `"planned"` asks the planner, `"estimated"` takes the planner's
+   * number only when it is above `maxRows`.
+   */
+  readonly count?: "exact" | "planned" | "estimated";
+  /** Leave `null` fields out of the result rather than spelling them out. */
+  readonly stripNulls?: boolean;
+  /** Refuse the call -- and roll it back -- if it would affect more rows than this (`PGRST124`). */
+  readonly maxAffected?: number;
+  /** Run the statement in this time zone, which is what `timestamptz` values are rendered in. */
+  readonly timezone?: string;
+}
+/** `schema` is optional for the default schema and required for any other. */
+type AtSchema<Db extends AnyDatabase, S$1 extends Schema<Db>> = S$1 extends Db["default"] ? {
+  readonly schema?: S$1;
+} : {
+  readonly schema: S$1;
+};
+/**
+ * Everything a query on one relation may say. Reads and writes share **one** member per table on
+ * purpose: when several members of the union carry the same `table` value, TypeScript cannot pick
+ * one from the discriminant, and the editor then offers every table's columns inside `select` and
+ * `where`. What the separate shapes used to enforce is enforced by {@link WriteRules} instead.
+ */
+type TableQuery<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = Common & AtSchema<Db, S$1> & {
+  /**
+   * The table or view to read or write. It is what restricts everything below: `select`, `where`
+   * and `order` only accept this relation's columns, and `rows`/`set` its writable ones.
+   */
+  readonly table: T$1;
+  /** Never both: the discriminant has to exist on every member for the editor to pick one. */
+  readonly rpc?: never;
+  /**
+   * What to do. `"select"` (the default) reads; `"insert"` and `"upsert"` take `rows`, `"update"`
+   * takes `set`, `"delete"` takes neither. A write returns its rows unless `returning: "minimal"`.
+   */
+  readonly action?: "select" | "insert" | "upsert" | "update" | "delete";
+  /**
+   * The columns to return, and the resources to embed. A string is a column (`"title"`) or a
+   * renamed one (`"name:title"`); `"*"` takes them all; `{ tags: ["label"] }` embeds a related
+   * resource, and `{ tags: { select, inner, where, order, limit, as, spread } }` is its long form.
+   *
+   * `data` is inferred from exactly this: pick two columns and the rows have two keys.
+   */
+  readonly select?: SelectList<Db, S$1, T$1>;
+  /**
+   * Which rows, by column. A plain value means `eq` (and `null` means `is.null`),
+   * `["gte", 3]` names an operator, and `{ op, value, not, quantifier, config }` is the long form.
+   * `and` and `or` take a list of nested groups; a dotted key filters an embedded resource.
+   */
+  readonly where?: Where$1<Db, S$1, T$1>;
+  /** How to sort: `"created"`, `"created.desc"`, or `{ column, desc, nulls }`. */
+  readonly order?: ReadonlyArray<Order$1<Db, S$1, T$1>>;
+  /**
+   * What to insert: one object or many. Generated and `GENERATED ALWAYS AS IDENTITY` columns are
+   * absent, and a column with a default or a nullable one is optional.
+   */
+  readonly rows?: Relations<Db, S$1>[T$1]["insert"] | ReadonlyArray<Relations<Db, S$1>[T$1]["insert"]>;
+  /** The columns to change, for an `"update"`. The rows are the ones `where` matches. */
+  readonly set?: Relations<Db, S$1>[T$1]["update"];
+  /** For an `"upsert"`, the columns the conflict is resolved on. Defaults to the primary key. */
+  readonly onConflict?: ReadonlyArray<Column$1<Db, S$1, T$1>>;
+  /** Insert only these columns, ignoring any other key in `rows` (and so making a bulk insert uniform). */
+  readonly columns?: ReadonlyArray<Column$1<Db, S$1, T$1>>;
+  /** What a column missing from `rows` gets: its `DEFAULT` (the default here) or `null`. */
+  readonly missing?: "default" | "null";
+  /** Whether a write answers with the rows it touched (the default here) or with nothing. */
+  readonly returning?: "representation" | "minimal";
+};
+/**
+ * The payload each action needs, and refuses: `rows` belongs to an insert or an upsert, `set` to an
+ * update, and a read has no business with either. Required here rather than in the shape, because
+ * an optional property that must sometimes be present cannot be said in one object type.
+ */
+type WriteRules<Db extends AnyDatabase, Q> = (Q extends {
+  action: "insert" | "upsert";
+} ? {
+  readonly rows: WriteShape<Db, Q, "insert"> | ReadonlyArray<WriteShape<Db, Q, "insert">>;
+} : {
+  readonly rows?: never;
+  readonly onConflict?: never;
+  readonly columns?: never;
+  readonly missing?: never;
+}) & (Q extends {
+  action: "update";
+} ? {
+  readonly set: WriteShape<Db, Q, "update">;
+} : {
+  readonly set?: never;
+}) & (Q extends {
+  action: "insert" | "upsert" | "update" | "delete";
+} ? unknown : {
+  readonly returning?: never;
+});
+type Rpc<Db extends AnyDatabase, S$1 extends Schema<Db>, F$1 extends keyof Functions<Db, S$1> & string> = Common & AtSchema<Db, S$1> & {
+  /**
+   * The function to call, like `POST /rpc/name`. Its arguments and its result come from the
+   * signature the catalog carries, overloads included.
+   */
+  readonly rpc: F$1;
+  /**
+   * `table` is absent from a function call, but it must still be *declared*: a union where some
+   * members lack the discriminant altogether is one TypeScript will not narrow, and the editor
+   * then offers every table's columns inside `select`.
+   */
+  readonly table?: never;
+  /** A function call has no action: it is whatever the function does. */
+  readonly action?: never;
+  /** The arguments, by name. A parameter with a `DEFAULT` is optional. */
+  readonly args?: Functions<Db, S$1>[F$1][number]["args"];
+  /**
+   * A function's result is a row like any other, so it takes the same three. These apply to the
+   * rows it returns, not to its arguments -- and a scalar function has no columns to ask for.
+   */
+  readonly select?: RowSelect<Functions<Db, S$1>[F$1][number]["returns"]>;
+  /** Filters on the rows the function returned, by their column. */
+  readonly where?: WhereOf<Functions<Db, S$1>[F$1][number]["returns"], never>;
+  /** How to sort the rows the function returned. */
+  readonly order?: ReadonlyArray<OrderOf<Functions<Db, S$1>[F$1][number]["returns"]>>;
+};
+/** The keys any member of a union accepts (`keyof` a union keeps only the common ones). */
+type KeysOfUnion<U$1> = U$1 extends unknown ? keyof U$1 : never;
+/**
+ * Inference through a type parameter checks assignability, which does not flag excess properties:
+ * `{ table: "t", limitt: 10 }` would type-check and the misspelled field would be dropped in
+ * silence. Intersecting this makes any unknown key `never`, so it has to be reported.
+ */
+type NoExtraKeys<Q, Allowed> = { readonly [K in Exclude<keyof Q, KeysOfUnion<Allowed>>]: never };
+/** The insert or update shape of the relation a query writes to. */
+type WriteShape<Db extends AnyDatabase, Q, Field extends "insert" | "update"> = Q extends {
+  table: infer T;
+} ? T extends Table<Db, SchemaIn<Db, Q>> ? Relations<Db, SchemaIn<Db, Q>>[T][Field] : never : never;
+/**
+ * The same guard, for the payload of a write: `rows: { id: 42, ... }` on a generated column, or any
+ * other key the relation does not accept, would otherwise reach the database and be refused there.
+ */
+type NoExtraPayload<Db extends AnyDatabase, Q> = (Q extends {
+  rows: infer R;
+} ? {
+  readonly rows: R extends ReadonlyArray<unknown> ? { readonly [I in keyof R]: R[I] & NoExtraKeys<R[I], WriteShape<Db, Q, "insert">> } : R & NoExtraKeys<R, WriteShape<Db, Q, "insert">>;
+} : unknown) & (Q extends {
+  set: infer U;
+} ? {
+  readonly set: U & NoExtraKeys<U, WriteShape<Db, Q, "update">>;
+} : unknown);
+/** What a `where` may be keyed by: this relation's columns, a group, or an embedded dotted path. */
+type WhereKeys<Db extends AnyDatabase, S$1 extends Schema<Db>, T$1 extends Table<Db, S$1>> = Column$1<Db, S$1, T$1> | "and" | "or" | `${keyof Embeds<Db, S$1, T$1> & string}.${string}`;
+/**
+ * A condition on something that is not a column of this relation. An unknown key inside `where` is
+ * not reported by assignability either -- `{ "titel": true }` would reach the database and come
+ * back as a `42703`. The columns of the relation the query names, so after its `table`.
+ */
+type NoExtraWhereKeys<Db extends AnyDatabase, Q> = Q extends {
+  where: infer W;
+} ? Q extends {
+  table: infer T;
+} ? T extends Table<Db, SchemaIn<Db, Q>> ? {
+  readonly where: W & { readonly [K in Exclude<keyof W, WhereKeys<Db, SchemaIn<Db, Q>, T>>]: never };
+} : unknown : unknown : unknown;
+/** Every query this database allows, as a union discriminated by `table` or `rpc`. */
+type TypedQuery<Db extends AnyDatabase> = { [S in Schema<Db>]: { [T in Table<Db, S>]: TableQuery<Db, S, T> }[Table<Db, S>] | { [F in keyof Functions<Db, S> & string]: Rpc<Db, S, F> }[keyof Functions<Db, S> & string] }[Schema<Db>];
+type SchemaIn<Db extends AnyDatabase, Q> = Q extends {
+  schema: infer S;
+} ? S extends Schema<Db> ? S : never : Db["default"] & Schema<Db>;
+/** The overloads of the function a query calls. */
+type Signatures<Db extends AnyDatabase, Q> = Q extends {
+  rpc: infer F;
+} ? F extends keyof Functions<Db, SchemaIn<Db, Q>> & string ? Functions<Db, SchemaIn<Db, Q>>[F][number] : never : never;
+/** One row of the answer, before `single` decides whether it comes alone. */
+type RowOut<Db extends AnyDatabase, Q> = Q extends {
+  rpc: string;
+} ? Q extends {
+  select: infer Items;
+} ? PickedFrom<Signatures<Db, Q>["returns"], Items> : Signatures<Db, Q>["returns"] : Q extends {
+  table: infer T;
+} ? T extends Table<Db, SchemaIn<Db, Q>> ? Q extends {
+  select: infer Items;
+} ? Selected<Db, SchemaIn<Db, Q>, T, Items> : Row$1<Db, SchemaIn<Db, Q>, T> : never : never;
+/**
+ * What `data` holds: the rows, one object with `single`, and `null` for a write that was asked to
+ * return nothing or a function that returns `void`.
+ */
+type QueryData<Db extends AnyDatabase, Q> = Q extends {
+  returning: "minimal";
+} ? null : Q extends {
+  single: true;
+} ? RowOut<Db, Q> : Q extends {
+  rpc: string;
+} ? [Signatures<Db, Q>["set"]] extends [true] ? RowOut<Db, Q>[] : RowOut<Db, Q> : RowOut<Db, Q>[];
+/**
+ * A {@link PgRestInstance} whose `query` and `querySafe` are typed by a generated database type:
+ * `table` and `rpc` are the ones that exist, `select` and `where` only name real columns and
+ * relationships, and `data` is inferred from the `select`.
+ *
+ * `handle` is unchanged: HTTP requests are strings from outside and cannot be typed.
+ */
+interface TypedPgRestInstance<Db extends AnyDatabase> extends Omit<PgRestInstance, "query" | "querySafe"> {
+  /**
+   * Run a query, in-process. `table` (or `rpc`) decides what the rest may say: `select`, `where` and
+   * `order` take this relation's columns and the resources a foreign key leads to, `rows` and `set`
+   * its writable columns. `data` is inferred from the `select`, nesting included.
+   *
+   * `ctx` is who is asking -- `{ role, claims, settings }` -- applied with `set_config`, so row
+   * level security and privileges work as they do over HTTP. They are the database's business: no
+   * type here knows what a role may do.
+   *
+   * Failures **throw** a `QueryError` carrying the PostgREST status and body. Use
+   * {@link TypedPgRestInstance.querySafe} to get them as a value instead.
+   *
+   * @example
+   * const { data } = await pgRest.query({
+   *   table: "todos",
+   *   select: ["id", "title", { tags: ["label"] }],
+   *   where: { done: false },
+   *   limit: 10,
+   * });
+   * // data: Array<{ id: number; title: string; tags: Array<{ label: string }> }>
+   */
+  query<const Q extends TypedQuery<Db>>(input: Q & NoExtraKeys<Q, TypedQuery<Db>> & NoExtraPayload<Db, Q> & NoExtraWhereKeys<Db, Q> & WriteRules<Db, Q>, ctx?: RequestContext): Promise<QueryResult<QueryData<Db, Q>>>;
+  /**
+   * {@link TypedPgRestInstance.query} with the failure as a value: `{ data, error }`, where exactly
+   * one of the two is set, so `if (error)` leaves `data` non-null. It never rejects.
+   *
+   * @example
+   * const { data, error } = await pgRest.querySafe({ table: "todos", select: ["id"] });
+   * if (error) return c.json(error.body, error.status);
+   */
+  querySafe<const Q extends TypedQuery<Db>>(input: Q & NoExtraKeys<Q, TypedQuery<Db>> & NoExtraPayload<Db, Q> & NoExtraWhereKeys<Db, Q> & WriteRules<Db, Q>, ctx?: RequestContext): Promise<QuerySafeResult<QueryData<Db, Q>>>;
 }
 //#endregion
 //#region src/service.d.ts
@@ -246,14 +708,64 @@ interface PgRestInstance {
    * `resolveContext` is used; otherwise the request runs as the anonymous role.
    */
   handle(request: Request, ctx?: RequestContext): Promise<Response>;
+  /**
+   * Run a query described by an object, in-process: no `Request`, no URL, no HTTP status.
+   * It goes through the same parser, the same SQL and the same error mapping as
+   * {@link PgRestInstance.handle}, so the database sees the same thing either way.
+   *
+   * Only the HTTP envelope is gone, which is also what it cannot do: content negotiation
+   * (CSV, GeoJSON, custom media types), `EXPLAIN` plans and OpenAPI stay on `handle`.
+   *
+   * Failures throw a {@link QueryError}: an `Error` carrying the PostgREST status, body
+   * (`code`, `message`, `details`, `hint`) and the input that produced it.
+   */
+  query<T$1 = unknown>(input: QueryInput, ctx?: RequestContext): Promise<QueryResult<T$1>>;
+  /**
+   * {@link PgRestInstance.query} with the failure as a value instead of an exception:
+   * `const { data, error } = await pgRest.querySafe({ table: "todos" })`. Exactly one of the two
+   * is set, so `if (error)` leaves `data` non-null. The error is the same {@link QueryError}.
+   *
+   * It never rejects: an error the library did not foresee comes back as a 500 `error` carrying the
+   * original under `cause`, so checking `error` is enough and no `try`/`catch` is needed.
+   */
+  querySafe<T$1 = unknown>(input: QueryInput, ctx?: RequestContext): Promise<QuerySafeResult<T$1>>;
   /** Re-read the database catalog (after migrations). */
   reloadSchema(): Promise<void>;
   /** The current introspected schema. */
   schemaCache(): Promise<SchemaCache>;
+  /**
+   * TypeScript types for this database, as the text of a module. Write it next to your code, keep
+   * it in version control, and hand the type it exports to `createPgRest<Database>` so queries
+   * check themselves. Run it again after a migration.
+   *
+   * ```ts
+   * writeFileSync("src/db.types.ts", await pgRest.generateTypes({ name: "Database" }));
+   * ```
+   *
+   * The generator is loaded on demand, so a server that never calls this never pays for it. The
+   * same function is exported standalone as `@adrdp/pg-rest/types` for when you hold a
+   * {@link SchemaCache} rather than an instance.
+   */
+  generateTypes(options?: GenerateTypesOptions): Promise<string>;
   /** Stop the handler. The database adapter is left open: close it yourself. */
   close(): Promise<void>;
 }
-/** Create a PostgREST-compatible handler over a Postgres database. */
-declare const createPgRest: (options: PgRestOptions) => Promise<PgRestInstance>;
+interface CreatePgRest {
+  (options: PgRestOptions): Promise<PgRestInstance>;
+  /**
+   * With a database type from `generateTypes` (`@adrdp/pg-rest/types`), `query` and `querySafe`
+   * are typed by it: `table` and `rpc` are the ones that exist, `select`, `where` and `order` only
+   * name real columns and relationships, and `data` is inferred from the `select`.
+   */
+  <Db extends AnyDatabase>(options: PgRestOptions): Promise<TypedPgRestInstance<Db>>;
+}
+/**
+ * Create a PostgREST-compatible handler over a Postgres database.
+ *
+ * `createPgRest<Db>(options)` returns the same instance with `query` and `querySafe` typed by a
+ * generated database type; the cast is the whole of that difference, since types never reach
+ * runtime and the two instances are one object.
+ */
+declare const createPgRest: CreatePgRest;
 //#endregion
-export { ApiError, type Column, type DbAdapter, DbQueryError, type DbSession, type ErrorBody, type ForeignKey, type FunctionDef, PgRestError, PgRestInstance, PgRestOptions, type PreRequestInfo, type Relation, type RequestContext, type Row, type SchemaCache, SchemaLoadError, createPgRest };
+export { type AnyDatabase, type AnyRelation, type AnySchema, type AnySignature, ApiError, type Column, CreatePgRest, type DbAdapter, DbQueryError, type DbSession, type DeleteQuery, type Embed, type ErrorBody, type Filter, type FilterOp, type FilterSpec, type ForeignKey, type FunctionDef, type InsertQuery, type Order, PgRestError, PgRestInstance, PgRestOptions, type PreRequestInfo, type QueryData, QueryError, type QueryInput, type QueryResult, type QueryReturning, type QuerySafeResult, type Relation, type RequestContext, type Row, type RpcQuery, type Scalar, type SchemaCache, SchemaLoadError, type Select, type SelectQuery, type TypedPgRestInstance, type TypedQuery, type UpdateQuery, type Where, createPgRest };