okmodel 0.0.0 → 0.1.1

package/dist/dialects/pg/integer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * smallint, integer, and bigint.
+ *
+ * Bigint defaults to a decimal string. `as` selects number or bigint.
+ */
+import { type ColumnBuilder, type IdentityFlags, type PlainFlags } from "./column.js";
+/** How a bigint value is represented in TypeScript. */
+export type BigintAs = "string" | "number" | "bigint";
+/**
+ * 16-bit integer.
+ *
+ * @returns A smallint column
+ */
+export declare function smallint(): ColumnBuilder<number, PlainFlags>;
+/**
+ * 32-bit integer.
+ *
+ * @returns An integer column
+ */
+export declare function integer(): ColumnBuilder<number, PlainFlags>;
+/** TypeScript value for a bigint codec mode. */
+export type BigintValue<TAs extends BigintAs> = TAs extends "number" ? number : TAs extends "bigint" ? bigint : string;
+/**
+ * 64-bit integer. The default codec is a decimal string.
+ *
+ * @typeParam TAs - `string`, `number`, or `bigint`
+ * @param options - `as` overrides the TypeScript representation
+ * @returns A bigint column
+ */
+export declare function bigint<const TAs extends BigintAs = "string">(options?: {
+    readonly as?: TAs;
+}): ColumnBuilder<BigintValue<TAs>, PlainFlags>;
+/**
+ * `bigint` identity column, `GENERATED ALWAYS AS IDENTITY`.
+ *
+ * Insert and update omit it. The codec follows the same `as` modes as {@link bigint}.
+ *
+ * @typeParam TAs - `string`, `number`, or `bigint`
+ * @param options - Codec selection
+ * @returns An identity column
+ */
+export declare function identity<const TAs extends BigintAs = "string">(options?: {
+    readonly as?: TAs;
+}): ColumnBuilder<BigintValue<TAs>, IdentityFlags>;
+/**
+ * Encodes a bigint decimal string.
+ *
+ * @param value - Decimal integer
+ * @returns The same spelling when it is a canonical integer
+ */
+export declare function encodeBigintString(value: string): string;
+/**
+ * Decodes a bigint decimal string.
+ *
+ * @param wire - Decimal integer
+ * @returns The same spelling
+ */
+export declare function decodeBigintString(wire: string): string;
+/**
+ * Encodes a safe integer as a bigint literal.
+ *
+ * @param value - Safe integer
+ * @returns Decimal text
+ */
+export declare function encodeBigintNumber(value: number): string;
+/**
+ * Decodes a bigint literal that fits in a safe integer.
+ *
+ * @param wire - Decimal integer
+ * @returns A safe integer
+ */
+export declare function decodeBigintNumber(wire: string): number;
+/**
+ * Encodes a native bigint.
+ *
+ * @param value - Bigint
+ * @returns Decimal text
+ */
+export declare function encodeBigintValue(value: bigint): string;
+/**
+ * Decodes a bigint literal to a native bigint.
+ *
+ * @param wire - Decimal integer
+ * @returns A bigint
+ */
+export declare function decodeBigintValue(wire: string): bigint;
+/**
+ * Encodes an integer that must lie in a closed range.
+ *
+ * @param value - Integer
+ * @param min - Inclusive lower bound
+ * @param max - Inclusive upper bound
+ * @param role - Type name used in the error
+ * @returns Decimal text
+ */
+export declare function integerToken(value: number, min: number, max: number, role: string): string;

package/dist/dialects/pg/introspect.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Reads a Postgres schema into a catalog.
+ *
+ * Copied partition primary keys and inherited indexes are not objects: a
+ * relation that is a child in `pg_inherits` is skipped, and so is an index
+ * that is itself inherited (M0-06). Expressions come back from `pg_get_expr`
+ * and `pg_get_constraintdef`, which is the database's normalised text (D128).
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+/** A connection that can run one query. Parameters are `$1`, `$2`, … */
+export type CatalogQuery = {
+    /**
+     * Runs one query.
+     *
+     * @param text - SQL
+     * @param params - Bound parameters
+     * @returns Rows as objects keyed by the select aliases
+     */
+    query(text: string, params?: readonly string[]): Promise<readonly Record<string, unknown>[]>;
+};
+/**
+ * Introspects one concrete schema.
+ *
+ * Identities use `logical`, not the concrete schema name, so two scratch
+ * schemas compare. The default logical namespace is `public`.
+ *
+ * @param runner - Database connection
+ * @param concrete - Schema to read
+ * @param logical - Namespace stored on the catalog identities
+ * @returns A checked catalog
+ */
+export declare function introspectSchema(runner: CatalogQuery, concrete: string, logical?: string): Promise<Catalog>;
+/**
+ * Applies one expression as a check and reads Postgres's reprint.
+ *
+ * Two authoring spellings of the same predicate compare equal after this.
+ * A different predicate does not.
+ *
+ * @param runner - Database connection
+ * @param expression - Check expression without the `CHECK` keyword
+ * @returns The reprinted expression, without the `CHECK` keyword
+ */
+export declare function reprintCheck(runner: CatalogQuery, expression: string): Promise<string>;

package/dist/dialects/pg/json.d.ts

@@ -0,0 +1,43 @@
+/**
+ * json, jsonb, and the bigint JSON replacer.
+ */
+import { type ColumnBuilder, type PlainFlags } from "./column.js";
+/**
+ * `JSON.stringify` replacer that writes bigint as a decimal string.
+ *
+ * `JSON.stringify` throws on a bigint. Projects that choose `bigint: "bigint"`
+ * pass this to `JSON.stringify`.
+ *
+ * @param _key - Property name. Unused
+ * @param value - Value about to be serialised
+ * @returns A string for bigint, otherwise the value
+ */
+export declare function jsonReplacer(_key: string, value: unknown): unknown;
+/**
+ * JSON text. `T` is the TypeScript shape; the codec does not check it.
+ *
+ * @typeParam T - JSON value type
+ * @returns A json column
+ */
+export declare function json<T = unknown>(): ColumnBuilder<T, PlainFlags>;
+/**
+ * Binary JSON. `T` is the TypeScript shape; the codec does not check it.
+ *
+ * @typeParam T - JSON value type
+ * @returns A jsonb column
+ */
+export declare function jsonb<T = unknown>(): ColumnBuilder<T, PlainFlags>;
+/**
+ * Encodes JSON. Bigint values become decimal strings.
+ *
+ * @param value - JSON value
+ * @returns JSON text
+ */
+export declare function encodeJson(value: unknown): string;
+/**
+ * Decodes JSON text.
+ *
+ * @param wire - JSON text
+ * @returns The parsed value
+ */
+export declare function decodeJson(wire: string): unknown;

package/dist/dialects/pg/keys.d.ts

@@ -0,0 +1,32 @@
+/**
+ * UUID keys.
+ */
+import { type ColumnBuilder, type IdFlags, type PlainFlags } from "./column.js";
+/**
+ * UUID primary key with default `uuidv7()`.
+ *
+ * Insert and update omit it, and it is guarded.
+ *
+ * @returns An id column
+ */
+export declare function id(): ColumnBuilder<string, IdFlags>;
+/**
+ * UUID text, with no default.
+ *
+ * @returns A uuid column
+ */
+export declare function uuid(): ColumnBuilder<string, PlainFlags>;
+/**
+ * Encodes a UUID as lowercase hex with hyphens.
+ *
+ * @param value - UUID text
+ * @returns Canonical UUID
+ */
+export declare function encodeUuid(value: string): string;
+/**
+ * Decodes UUID text.
+ *
+ * @param wire - UUID text
+ * @returns Canonical UUID
+ */
+export declare function decodeUuid(wire: string): string;

package/dist/dialects/pg/misuse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Column and codec failures from spec section 21 (D130).
+ *
+ * OKM1060 is an invalid column definition. OKM1061 is a reserved option this
+ * version does not implement. OKM1210 is a value a codec rejects.
+ * Messages name the accepted values.
+ */
+/** Invalid length, precision, scale, rank, qualifier, or value list. */
+export declare const COLUMN_DEFINITION_CODE = "OKM1060";
+/** A table or schema option reserved for a later prompt. */
+export declare const RESERVED_OPTION_CODE = "OKM1061";
+/** A codec rejected a value. */
+export declare const CODEC_VALUE_CODE = "OKM1210";
+/**
+ * Throws OKM1060.
+ *
+ * @param message - What is wrong with the column definition, including accepted values
+ */
+export declare function definition(message: string): never;
+/**
+ * Throws OKM1061.
+ *
+ * @param message - Which option is reserved, and the prompt or milestone that adds it
+ */
+export declare function unavailable(message: string): never;
+/**
+ * Throws OKM1210.
+ *
+ * @param message - What the codec refused, including accepted values
+ */
+export declare function rejected(message: string): never;

package/dist/dialects/pg/model.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime table model the read path compiles against.
+ *
+ * `schema()` fills it once. Query planning does not walk column builders again.
+ */
+/** One column the planner can filter, select, decode, and write. */
+export type ColumnModel = {
+    /** Field name. */
+    readonly field: string;
+    /** SQL name, already checked as an identifier. */
+    readonly sql: string;
+    /** Catalog type, used when a value is projected through JSON. */
+    readonly dataType: string;
+    /** Codec encode. Identity text still returns the same string. */
+    readonly encode: (value: unknown) => string;
+    /**
+     * Codec decode.
+     *
+     * Omitted when the wire text is the TypeScript value, so a row does not
+     * call a codec it does not need.
+     */
+    readonly decode: ((wire: string) => unknown) | undefined;
+    /** Excluded from a default select. Named selects still return it. */
+    readonly hidden: boolean;
+    /** Refused when present in insert or update input. */
+    readonly guarded: boolean;
+    /** Included in insert and update. Guarded, generated, and omitted columns are not. */
+    readonly writable: boolean;
+};
+/**
+ * A resolved relation.
+ *
+ * The join is always `related.{remote} = this.{local}`.
+ */
+export type RelationModel = {
+    readonly name: string;
+    readonly kind: "one" | "many";
+    /** Related table's TypeScript name. */
+    readonly table: string;
+    /** SQL names on this table. */
+    readonly local: readonly string[];
+    /** SQL names on the related table. */
+    readonly remote: readonly string[];
+};
+/** One table, keyed by its TypeScript name on the schema. */
+export type TableModel = {
+    readonly name: string;
+    readonly sql: string;
+    /** Primary-key field names, in catalog order. */
+    readonly primary: readonly string[];
+    /**
+     * Field lists that `onConflict.on` may name.
+     *
+     * Each list is a primary key or a unique constraint. Order is the catalog order.
+     */
+    readonly uniques: readonly (readonly string[])[];
+    readonly columns: readonly ColumnModel[];
+    readonly relations: readonly RelationModel[];
+};
+/** Schema fields the read path and `connect()` read. */
+export type QuerySchema = {
+    readonly "~byName": {
+        readonly [name: string]: {
+            readonly "~row": unknown;
+        };
+    };
+    readonly model: Readonly<Record<string, TableModel>>;
+    readonly requires?: {
+        readonly postgres?: string;
+    } | undefined;
+};

package/dist/dialects/pg/namespace.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `t` namespace from spec section 6.4.
+ *
+ * Importing `t` pulls every builder. Import one builder when an application
+ * uses only that type.
+ */
+import { boolean, bytea } from "./bool.js";
+import { custom } from "./custom.js";
+import { double, numeric, real } from "./decimal.js";
+import { domain, enumColumn } from "./enum.js";
+import { line, point } from "./geometry.js";
+import { bigint, identity, integer, smallint } from "./integer.js";
+import { json, jsonb } from "./json.js";
+import { id, uuid } from "./keys.js";
+import { cidr, inet, macaddr, macaddr8 } from "./network.js";
+import { daterange, int4range, int8range, numrange, tstzrange } from "./range.js";
+import { ltree, tsvector } from "./search.js";
+import { char, citext, text, varchar } from "./text.js";
+import { date, interval, time, timestamp, timestamptz, timetz } from "./time.js";
+/**
+ * Postgres column builders.
+ */
+export declare const t: {
+    id: typeof id;
+    identity: typeof identity;
+    uuid: typeof uuid;
+    smallint: typeof smallint;
+    integer: typeof integer;
+    bigint: typeof bigint;
+    numeric: typeof numeric;
+    real: typeof real;
+    double: typeof double;
+    text: typeof text;
+    varchar: typeof varchar;
+    char: typeof char;
+    citext: typeof citext;
+    boolean: typeof boolean;
+    bytea: typeof bytea;
+    json: typeof json;
+    jsonb: typeof jsonb;
+    timestamptz: typeof timestamptz;
+    timestamp: typeof timestamp;
+    date: typeof date;
+    time: typeof time;
+    timetz: typeof timetz;
+    interval: typeof interval;
+    tstzrange: typeof tstzrange;
+    daterange: typeof daterange;
+    int4range: typeof int4range;
+    int8range: typeof int8range;
+    numrange: typeof numrange;
+    inet: typeof inet;
+    cidr: typeof cidr;
+    macaddr: typeof macaddr;
+    macaddr8: typeof macaddr8;
+    point: typeof point;
+    line: typeof line;
+    tsvector: typeof tsvector;
+    ltree: typeof ltree;
+    enum: typeof enumColumn;
+    domain: typeof domain;
+    custom: typeof custom;
+};

package/dist/dialects/pg/network.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Network address columns. Values are canonical text.
+ */
+import { type ColumnBuilder, type PlainFlags } from "./column.js";
+/**
+ * IPv4 or IPv6 host, with an optional prefix.
+ *
+ * @returns An inet column
+ */
+export declare function inet(): ColumnBuilder<string, PlainFlags>;
+/**
+ * IPv4 or IPv6 network. A prefix is required.
+ *
+ * @returns A cidr column
+ */
+export declare function cidr(): ColumnBuilder<string, PlainFlags>;
+/**
+ * 48-bit MAC address, lowercase.
+ *
+ * @returns A macaddr column
+ */
+export declare function macaddr(): ColumnBuilder<string, PlainFlags>;
+/**
+ * 64-bit MAC address, lowercase.
+ *
+ * @returns A macaddr8 column
+ */
+export declare function macaddr8(): ColumnBuilder<string, PlainFlags>;

package/dist/dialects/pg/operators.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tagged filter operators (spec §10.1, D125).
+ *
+ * The brand is a symbol. JSON cannot create one, so request data cannot add
+ * an operator or traverse a relation. A plain object stays OKM1121.
+ */
+declare const brand: unique symbol;
+declare const RUNTIME: unique symbol;
+/** Operator names the read path compiles. */
+export type OperatorName = "eq" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "contains" | "endsWith" | "like" | "ilike" | "inList" | "notIn" | "not" | "or" | "has" | "none" | "every" | "inc";
+/** A tagged operator. `value` is the operand the helper stored. */
+export type Tagged<Name extends OperatorName, V> = {
+    readonly [brand]: Name;
+    readonly value: V;
+};
+/** Equality, including json and jsonb (D125). */
+export type Eq<V> = Tagged<"eq", V>;
+/** One-sided comparison. */
+export type Compare<Name extends "lt" | "lte" | "gt" | "gte", V> = Tagged<Name, V>;
+/** Inclusive range. */
+export type Between<V> = Tagged<"between", readonly [V, V]>;
+/** A literal pattern. `%`, `_`, and `\` in the value are escaped. */
+export type Pattern<Name extends "startsWith" | "contains" | "endsWith"> = Tagged<Name, string>;
+/** A raw `LIKE` or `ILIKE` pattern. The caller owns the wildcards. */
+export type RawPattern<Name extends "like" | "ilike"> = Tagged<Name, string>;
+/** Membership. An empty list matches nothing. */
+export type InList<V> = Tagged<"inList", readonly V[]>;
+/** The complement of {@link InList}. An empty list matches everything. */
+export type NotIn<V> = Tagged<"notIn", readonly V[]>;
+/** Negation of null, a value, or another operator. */
+export type Not<V> = Tagged<"not", V>;
+/** Disjunction. Each branch is a where object. */
+export type Or<V> = Tagged<"or", readonly V[]>;
+/** A relation filter. The value is the related table's where. */
+export type RelationFilter<Name extends "has" | "none" | "every", V> = Tagged<Name, V>;
+type AnyTagged = {
+    readonly [RUNTIME]: OperatorName;
+    readonly value: unknown;
+};
+/**
+ * Reports whether `value` is a tagged operator.
+ *
+ * @param value - A where operand
+ * @returns `true` when a helper created it
+ */
+export declare function isOperator(value: unknown): value is AnyTagged;
+/**
+ * Reads the operator name.
+ *
+ * @param value - A value {@link isOperator} accepted
+ * @returns The helper that created it
+ */
+export declare function operatorName(value: AnyTagged): OperatorName;
+/**
+ * Reads the operand.
+ *
+ * @param value - A value {@link isOperator} accepted
+ * @returns The operand the helper stored
+ */
+export declare function operatorValue(value: AnyTagged): unknown;
+/**
+ * Tags an operator. Each helper lives in its own module so unused ones drop out.
+ *
+ * @typeParam Name - Operator name
+ * @typeParam V - Operand
+ * @param name - Operator name
+ * @param value - Operand
+ * @returns A tagged operator
+ */
+export declare function tag<Name extends OperatorName, V>(name: Name, value: V): Tagged<Name, V>;
+export {};

package/dist/dialects/pg/ops/between.d.ts

@@ -0,0 +1,10 @@
+import { type Between } from "../operators.js";
+/**
+ * Inclusive range.
+ *
+ * @typeParam V - Operand
+ * @param from - Lower bound
+ * @param to - Upper bound
+ * @returns A tagged operator
+ */
+export declare function between<const V>(from: V, to: V): Between<V>;

package/dist/dialects/pg/ops/contains.d.ts

@@ -0,0 +1,8 @@
+import { type Pattern } from "../operators.js";
+/**
+ * Case-sensitive substring. `%`, `_`, and `\` in `value` are escaped.
+ *
+ * @param value - Literal substring
+ * @returns A tagged operator
+ */
+export declare function contains(value: string): Pattern<"contains">;

package/dist/dialects/pg/ops/endsWith.d.ts

@@ -0,0 +1,8 @@
+import { type Pattern } from "../operators.js";
+/**
+ * Case-sensitive suffix. `%`, `_`, and `\` in `value` are escaped.
+ *
+ * @param value - Literal suffix
+ * @returns A tagged operator
+ */
+export declare function endsWith(value: string): Pattern<"endsWith">;

package/dist/dialects/pg/ops/eq.d.ts

@@ -0,0 +1,9 @@
+import { type Eq } from "../operators.js";
+/**
+ * Equality. This is the form for json and jsonb (D125).
+ *
+ * @typeParam V - Operand
+ * @param value - Value to compare
+ * @returns A tagged operator
+ */
+export declare function eq<const V>(value: V): Eq<V>;

package/dist/dialects/pg/ops/every.d.ts

@@ -0,0 +1,9 @@
+import { type RelationFilter } from "../operators.js";
+/**
+ * Every related row matches. True when there are no related rows.
+ *
+ * @typeParam V - Related where
+ * @param where - Filter on the related table
+ * @returns A relation filter
+ */
+export declare function every<const V>(where: V): RelationFilter<"every", V>;

package/dist/dialects/pg/ops/gt.d.ts

@@ -0,0 +1,9 @@
+import { type Compare } from "../operators.js";
+/**
+ * Greater than.
+ *
+ * @typeParam V - Operand
+ * @param value - Lower bound, exclusive
+ * @returns A tagged operator
+ */
+export declare function gt<const V>(value: V): Compare<"gt", V>;

package/dist/dialects/pg/ops/gte.d.ts

@@ -0,0 +1,9 @@
+import { type Compare } from "../operators.js";
+/**
+ * Greater than or equal.
+ *
+ * @typeParam V - Operand
+ * @param value - Lower bound, inclusive
+ * @returns A tagged operator
+ */
+export declare function gte<const V>(value: V): Compare<"gte", V>;

package/dist/dialects/pg/ops/has.d.ts

@@ -0,0 +1,9 @@
+import { type RelationFilter } from "../operators.js";
+/**
+ * Related rows exist.
+ *
+ * @typeParam V - Related where
+ * @param where - Filter on the related table
+ * @returns A relation filter
+ */
+export declare function has<const V>(where: V): RelationFilter<"has", V>;

package/dist/dialects/pg/ops/ilike.d.ts

@@ -0,0 +1,8 @@
+import { type RawPattern } from "../operators.js";
+/**
+ * Raw `ILIKE` pattern. Wildcards are not escaped.
+ *
+ * @param pattern - Pattern the caller wrote
+ * @returns A tagged operator
+ */
+export declare function ilike(pattern: string): RawPattern<"ilike">;

package/dist/dialects/pg/ops/inList.d.ts

@@ -0,0 +1,9 @@
+import { type InList } from "../operators.js";
+/**
+ * Membership. An empty list matches nothing and does not become `IN ()`.
+ *
+ * @typeParam V - Element
+ * @param values - Accepted values
+ * @returns A tagged operator
+ */
+export declare function inList<const V>(values: readonly V[]): InList<V>;

package/dist/dialects/pg/ops/inc.d.ts

@@ -0,0 +1,13 @@
+import { type Tagged } from "../operators.js";
+/** Adds to the stored number. `undefined` in `set` still leaves the field unchanged. */
+export type Inc<V> = Tagged<"inc", V>;
+/**
+ * Atomic increment used in `update` `set` (spec §11).
+ *
+ * JSON and array operators are not this helper.
+ *
+ * @typeParam V - Amount
+ * @param value - Amount to add
+ * @returns A tagged operator
+ */
+export declare function inc<const V>(value: V): Inc<V>;

package/dist/dialects/pg/ops/like.d.ts

@@ -0,0 +1,8 @@
+import { type RawPattern } from "../operators.js";
+/**
+ * Raw `LIKE` pattern. Wildcards are not escaped.
+ *
+ * @param pattern - Pattern the caller wrote
+ * @returns A tagged operator
+ */
+export declare function like(pattern: string): RawPattern<"like">;

package/dist/dialects/pg/ops/lt.d.ts

@@ -0,0 +1,9 @@
+import { type Compare } from "../operators.js";
+/**
+ * Less than.
+ *
+ * @typeParam V - Operand
+ * @param value - Upper bound, exclusive
+ * @returns A tagged operator
+ */
+export declare function lt<const V>(value: V): Compare<"lt", V>;

package/dist/dialects/pg/ops/lte.d.ts

@@ -0,0 +1,9 @@
+import { type Compare } from "../operators.js";
+/**
+ * Less than or equal.
+ *
+ * @typeParam V - Operand
+ * @param value - Upper bound, inclusive
+ * @returns A tagged operator
+ */
+export declare function lte<const V>(value: V): Compare<"lte", V>;

package/dist/dialects/pg/ops/none.d.ts

@@ -0,0 +1,9 @@
+import { type RelationFilter } from "../operators.js";
+/**
+ * No related row matches.
+ *
+ * @typeParam V - Related where
+ * @param where - Filter on the related table
+ * @returns A relation filter
+ */
+export declare function none<const V>(where: V): RelationFilter<"none", V>;

package/dist/dialects/pg/ops/not.d.ts

@@ -0,0 +1,9 @@
+import { type Not } from "../operators.js";
+/**
+ * Negation. `not(null)` is `IS NOT NULL`.
+ *
+ * @typeParam V - Operand
+ * @param value - Null, a value, or another operator
+ * @returns A tagged operator
+ */
+export declare function not<const V>(value: V): Not<V>;

package/dist/dialects/pg/ops/notIn.d.ts

@@ -0,0 +1,9 @@
+import { type NotIn } from "../operators.js";
+/**
+ * Complement of {@link inList}. An empty list matches everything.
+ *
+ * @typeParam V - Element
+ * @param values - Rejected values
+ * @returns A tagged operator
+ */
+export declare function notIn<const V>(values: readonly V[]): NotIn<V>;