okmodel 0.0.0 → 0.1.0

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

@@ -0,0 +1,9 @@
+import { type Or } from "../operators.js";
+/**
+ * Disjunction of where objects.
+ *
+ * @typeParam V - One branch
+ * @param branches - Where objects, or-ed
+ * @returns A tagged operator
+ */
+export declare function or<const V>(branches: readonly V[]): Or<V>;

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

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

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

@@ -0,0 +1,24 @@
+/**
+ * SQL literal quoting for catalog default expressions.
+ *
+ * Only single quotes are escaped. Postgres `standard_conforming_strings` is
+ * on, so a backslash stays a backslash.
+ */
+/**
+ * Wraps text in a SQL string literal.
+ *
+ * @param value - Raw text
+ * @returns A single-quoted literal
+ */
+export declare function quoteLiteral(value: string): string;
+/**
+ * Quotes one element of a Postgres array literal.
+ *
+ * Bare tokens are integers, decimals, and booleans. Everything else is a
+ * double-quoted element.
+ *
+ * @param encoded - Element text from the scalar codec
+ * @param raw - When true, a numeric or boolean token may stay bare
+ * @returns One array-literal element
+ */
+export declare function arrayElement(encoded: string, raw: boolean): string;

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

@@ -0,0 +1,50 @@
+/**
+ * Postgres range columns.
+ *
+ * A range is either empty or a pair of bounds. Unbounded sides use null.
+ */
+import { type ColumnBuilder, type PlainFlags } from "./column.js";
+/**
+ * A range value.
+ *
+ * @typeParam T - Bound type
+ */
+export type Range<T> = {
+    readonly empty: true;
+} | {
+    readonly empty: false;
+    readonly lower: T | null;
+    readonly upper: T | null;
+    readonly lowerInclusive: boolean;
+    readonly upperInclusive: boolean;
+};
+/**
+ * Timestamp with time zone range.
+ *
+ * @returns A tstzrange column
+ */
+export declare function tstzrange(): ColumnBuilder<Range<Temporal.Instant>, PlainFlags>;
+/**
+ * Date range.
+ *
+ * @returns A daterange column
+ */
+export declare function daterange(): ColumnBuilder<Range<Temporal.PlainDate>, PlainFlags>;
+/**
+ * 32-bit integer range.
+ *
+ * @returns An int4range column
+ */
+export declare function int4range(): ColumnBuilder<Range<number>, PlainFlags>;
+/**
+ * 64-bit integer range. Bounds are decimal strings.
+ *
+ * @returns An int8range column
+ */
+export declare function int8range(): ColumnBuilder<Range<string>, PlainFlags>;
+/**
+ * Numeric range. Bounds are decimal strings.
+ *
+ * @returns A numrange column
+ */
+export declare function numrange(): ColumnBuilder<Range<string>, PlainFlags>;

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

@@ -0,0 +1,45 @@
+/**
+ * `one` and `many` relations.
+ *
+ * They name a table. `schema()` resolves the foreign key. An ambiguous key
+ * is OKM1021. `manyThrough` arrives in 0.2. `morph` stays reserved.
+ */
+/** A to-one relation. `field` is the local foreign key when the table has several. */
+export type OneRelation<TTable extends string = string> = {
+    readonly kind: "one";
+    readonly table: TTable;
+    readonly field: string | undefined;
+};
+/** A to-many relation. `field` is the foreign key on the other table. */
+export type ManyRelation<TTable extends string = string> = {
+    readonly kind: "many";
+    readonly table: TTable;
+    readonly field: string | undefined;
+};
+/** A relation `table()` stores. */
+export type RelationCall = OneRelation | ManyRelation;
+/**
+ * Declares a to-one relation by table name.
+ *
+ * @typeParam TTable - Related table
+ * @param table - Related table name
+ * @param field - Local foreign-key field, when more than one key points there
+ * @returns The relation `schema()` resolves
+ */
+export declare function one<const TTable extends string>(table: TTable, field?: string): OneRelation<TTable>;
+/**
+ * Declares a to-many relation by table name.
+ *
+ * @typeParam TTable - Related table
+ * @param table - Related table name
+ * @param field - Foreign-key field on that table, when more than one key points here
+ * @returns The relation `schema()` resolves
+ */
+export declare function many<const TTable extends string>(table: TTable, field?: string): ManyRelation<TTable>;
+/**
+ * Reports whether `value` is a relation helper result.
+ *
+ * @param value - One entry of `relations`
+ * @returns `true` for `one` and `many`
+ */
+export declare function isRelationCall(value: unknown): value is RelationCall;

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

@@ -0,0 +1,77 @@
+/**
+ * `schema()` compiles tables into one catalog.
+ *
+ * Work happens here, not in `table()` and not at import.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type TableModel } from "./model.js";
+import { type AnyTable } from "./table.js";
+/** Codec defaults from spec section 6.6. */
+export type SchemaCodecs = {
+    readonly bigint: "string" | "number" | "bigint";
+    readonly numeric: "string" | "number";
+    readonly timestamps: "temporal";
+};
+/** Engine requirement recorded for connect. */
+export type SchemaRequires = {
+    readonly postgres?: string;
+};
+/**
+ * Input for {@link schema}.
+ *
+ * Later keys are part of the type and rejected when present.
+ *
+ * @typeParam TTables - Tables in declaration order
+ */
+export type SchemaInput<TTables extends readonly AnyTable[]> = {
+    readonly tables: TTables;
+    readonly requires?: SchemaRequires;
+    readonly casing?: "snake";
+    readonly codecs?: {
+        readonly bigint?: SchemaCodecs["bigint"];
+        readonly numeric?: SchemaCodecs["numeric"];
+        readonly timestamps?: SchemaCodecs["timestamps"];
+    };
+    readonly types?: "emitted" | "inferred";
+    readonly traits?: unknown;
+    readonly tenancy?: unknown;
+    readonly validation?: unknown;
+    readonly extensions?: unknown;
+    readonly functions?: unknown;
+    readonly triggers?: unknown;
+    readonly views?: unknown;
+};
+/**
+ * A compiled schema.
+ *
+ * `~byName` is what `Row`, `Insert`, and `Update` index. `catalog` is the
+ * document `catalogHash` and `serializeCatalog` accept.
+ *
+ * @typeParam TTables - Tables in declaration order
+ */
+export type BuiltSchema<TTables extends readonly AnyTable[]> = {
+    readonly "~byName": {
+        readonly [T in TTables[number] as T["~name"]]: T;
+    };
+    readonly catalog: Catalog;
+    readonly types: "emitted" | "inferred";
+    readonly casing: "snake" | undefined;
+    readonly codecs: SchemaCodecs;
+    readonly requires: SchemaRequires | undefined;
+    readonly tables: TTables;
+    /** Query model. Built once, beside the catalog document. */
+    readonly model: {
+        readonly [T in TTables[number] as T["~name"]]: TableModel;
+    };
+};
+/**
+ * Compiles tables into a catalog.
+ *
+ * Names, dependencies, and provenance are fixed here. Calling it twice on
+ * the same tables returns equal catalog bytes.
+ *
+ * @typeParam TTables - Tables in declaration order
+ * @param config - Tables, casing, codecs, and the row-type mode
+ * @returns The schema and its catalog
+ */
+export declare function schema<const TTables extends readonly AnyTable[]>(config: SchemaInput<TTables>): BuiltSchema<TTables>;

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

@@ -0,0 +1,23 @@
+/**
+ * Full-text search and ltree.
+ */
+import { type ColumnBuilder, type PlainFlags } from "./column.js";
+/**
+ * Full-text vector. The value is the vector text.
+ *
+ * @returns A tsvector column
+ */
+export declare function tsvector(): ColumnBuilder<string, PlainFlags>;
+/**
+ * Label tree. The column depends on the `ltree` extension.
+ *
+ * @returns An ltree column
+ */
+export declare function ltree(): ColumnBuilder<string, PlainFlags>;
+/**
+ * Encodes an ltree path.
+ *
+ * @param value - Labels separated by dots
+ * @returns The same path when every label is valid
+ */
+export declare function encodeLtree(value: string): string;

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

@@ -0,0 +1,201 @@
+/**
+ * `table()`, index calls, and check text.
+ *
+ * `table()` stores the columns. It does not build catalog objects.
+ * `schema()` does that.
+ */
+import { type ColumnInsertOf, type ColumnRowOf, type ColumnUpdateOf } from "./column.js";
+import { type RelationCall } from "./relations.js";
+/**
+ * A column as seen by `indexes` and `checks`.
+ *
+ * `name` is the SQL name `schema()` will store.
+ */
+export type ColumnHandle = {
+    readonly name: string;
+};
+/**
+ * An index declared on a table.
+ */
+export type IndexCall = {
+    readonly columns: readonly string[];
+    readonly isUnique: boolean;
+    /**
+     * Marks the index unique.
+     *
+     * @returns The same columns, unique
+     */
+    unique(): IndexCall;
+};
+/**
+ * Text stored for a check constraint.
+ *
+ * The database normalises it later. Here it is the author's text.
+ */
+export type SqlText = {
+    readonly text: string;
+};
+/** Values an {@link sql} template may interpolate. */
+export type SqlValue = string | number | boolean | null | ColumnHandle | SqlText;
+/**
+ * Options `table()` stores.
+ *
+ * Keys that belong to a later prompt are accepted and rejected at runtime.
+ *
+ * @typeParam TColumns - Columns of this table
+ */
+export type TableOptions<TColumns> = {
+    readonly indexes?: (columns: Handles<TColumns>) => readonly IndexCall[];
+    readonly checks?: {
+        readonly [name: string]: (columns: Handles<TColumns>) => SqlText;
+    };
+    readonly unique?: {
+        readonly [name: string]: readonly (keyof TColumns & string)[];
+    };
+    readonly sqlName?: string;
+    readonly renamedFrom?: string;
+    readonly comment?: string;
+    readonly validate?: unknown;
+    readonly validation?: unknown;
+    readonly traits?: unknown;
+    readonly omitDefaults?: unknown;
+    readonly tenancy?: unknown;
+    readonly computed?: unknown;
+    readonly presets?: unknown;
+    readonly policies?: unknown;
+    readonly reference?: unknown;
+    /** `one` and `many`. Other relation kinds stay reserved. */
+    readonly relations?: unknown;
+};
+/**
+ * Column handles keyed by field name.
+ *
+ * @typeParam TColumns - Columns of this table
+ */
+export type Handles<TColumns> = {
+    readonly [K in keyof TColumns]: ColumnHandle;
+};
+/**
+ * A table value.
+ *
+ * `~row`, `~insert`, and `~update` are the shapes `Row`, `Insert`, and
+ * `Update` read. They are computed here, once, from the column flags.
+ *
+ * @typeParam TName - Table name
+ * @typeParam TColumns - Column builders
+ * @typeParam TRelations - Relations declared on this table
+ */
+export type Table<TName extends string, TColumns, TRelations extends Readonly<Record<string, RelationCall>> = Readonly<Record<string, never>>> = {
+    readonly "~name": TName;
+    readonly "~columns": TColumns;
+    readonly "~row": RowFrom<TColumns>;
+    readonly "~insert": InsertFrom<TColumns>;
+    readonly "~update": UpdateFrom<TColumns>;
+    readonly "~relations": TRelations;
+    readonly name: TName;
+    readonly columns: TColumns;
+    readonly options?: TableOptions<TColumns>;
+};
+/**
+ * Any table `schema()` can compile.
+ */
+export type AnyTable = {
+    readonly "~name": string;
+    readonly "~row": unknown;
+    readonly "~insert": unknown;
+    readonly "~update": unknown;
+    readonly "~relations"?: Readonly<Record<string, RelationCall>>;
+    readonly name: string;
+    readonly columns: Readonly<Record<string, object>>;
+    readonly options?: object;
+};
+/**
+ * Row shape. Hidden columns are omitted.
+ *
+ * @typeParam TColumns - Column builders
+ */
+export type RowFrom<TColumns> = {
+    readonly [K in keyof TColumns as ColumnRowOf<TColumns[K]> extends never ? never : K]: ColumnRowOf<TColumns[K]>;
+};
+/**
+ * Insert shape. Omitted columns are dropped. Optional ones include `undefined`.
+ *
+ * @typeParam TColumns - Column builders
+ */
+export type InsertFrom<TColumns> = {
+    readonly [K in keyof TColumns as ColumnInsertOf<TColumns[K]> extends never ? never : K]: ColumnInsertOf<TColumns[K]>;
+};
+/**
+ * Update shape. Omitted columns are dropped. The rest include `undefined`.
+ *
+ * @typeParam TColumns - Column builders
+ */
+export type UpdateFrom<TColumns> = {
+    readonly [K in keyof TColumns as ColumnUpdateOf<TColumns[K]> extends never ? never : K]: ColumnUpdateOf<TColumns[K]>;
+};
+/**
+ * Declares a table.
+ *
+ * The catalog objects are built in `schema()`, not here.
+ *
+ * @typeParam TName - Table name
+ * @typeParam TColumns - Column builders
+ * @param name - Table name used by references and row types
+ * @param columns - Columns keyed by field name
+ * @param options - Indexes, checks, unique constraints, and names
+ * @returns The table
+ */
+export declare function table<const TName extends string, const TColumns extends Readonly<Record<string, object>>>(name: TName, columns: TColumns): Table<TName, TColumns, Readonly<Record<string, never>>>;
+export declare function table<const TName extends string, const TColumns extends Readonly<Record<string, object>>, const TOptions extends TableOptions<TColumns>>(name: TName, columns: TColumns, options: TOptions): Table<TName, TColumns, RelationsOf<TOptions>>;
+/**
+ * Relation map stored on a table.
+ *
+ * Absent relations are an empty map, so a table without `relations` does not
+ * grow a conditional at every call.
+ *
+ * @typeParam TOptions - Options argument, or `undefined`
+ */
+type RelationsOf<TOptions> = TOptions extends {
+    readonly relations: infer R;
+} ? R extends Readonly<Record<string, RelationCall>> ? R : Readonly<Record<string, never>> : Readonly<Record<string, never>>;
+/**
+ * Declares an index from column handles.
+ *
+ * @param columns - Columns in index order
+ * @returns An index call `schema()` compiles
+ */
+export declare function index(...columns: readonly ColumnHandle[]): IndexCall;
+/**
+ * Captures a check expression as text.
+ *
+ * Column handles become their SQL names. This is not a query builder.
+ *
+ * @param strings - Literal parts
+ * @param values - Interpolated columns, text, or numbers
+ * @returns The expression `schema()` stores
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: readonly SqlValue[]): SqlText;
+/**
+ * Converts a camelCase field name to snake_case.
+ *
+ * @param name - Field or table name
+ * @returns The SQL spelling used when `casing` is `"snake"`
+ */
+export declare function snakeCase(name: string): string;
+/**
+ * Type name emitted for a table: `tasks` becomes `Tasks`.
+ *
+ * @param name - Table name
+ * @returns A TypeScript identifier
+ */
+export declare function emittedTypeName(name: string): string;
+/**
+ * Rejects options a later prompt owns, and unknown keys.
+ *
+ * @param options - Author object
+ * @param known - Keys this prompt implements
+ * @param later - Keys reserved for a named prompt
+ * @param where - Table or schema name used in the message
+ */
+export declare function rejectLater(options: object, known: ReadonlySet<string>, later: Readonly<Record<string, string>>, where: string): void;
+export {};

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

@@ -0,0 +1,211 @@
+/**
+ * Temporal codecs. `Temporal` is read when a value is encoded or decoded.
+ */
+/** A time of day with a numeric UTC offset. Temporal has no timetz value. */
+export type TimeWithOffset = {
+    readonly time: Temporal.PlainTime;
+    readonly offset: string;
+};
+/** Fractional seconds accepted by the date/time builders. */
+export type TimePrecision = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Checks a fractional-second precision.
+ *
+ * @param precision - Digits, or omitted
+ * @param role - Column type name
+ * @returns The precision, or undefined when omitted
+ */
+export declare function timePrecision(precision: number | undefined, role: string): TimePrecision | undefined;
+/**
+ * Encodes an instant.
+ *
+ * @param value - Instant
+ * @param precision - Fractional digits, or full precision when omitted
+ * @returns ISO-8601 text
+ */
+export declare function encodeInstant(value: Temporal.Instant, precision?: TimePrecision): string;
+/**
+ * Decodes an instant.
+ *
+ * @param wire - ISO-8601 text
+ * @returns An instant
+ */
+export declare function decodeInstant(wire: string): Temporal.Instant;
+/**
+ * Encodes a timestamp without time zone.
+ *
+ * @param value - Local date and time
+ * @param precision - Fractional digits
+ * @returns ISO-8601 text without a zone
+ */
+export declare function encodeDateTime(value: Temporal.PlainDateTime, precision?: TimePrecision): string;
+/**
+ * Decodes a timestamp without time zone.
+ *
+ * @param wire - ISO-8601 text
+ * @returns A plain date-time
+ */
+export declare function decodeDateTime(wire: string): Temporal.PlainDateTime;
+/**
+ * Encodes a date.
+ *
+ * @param value - Date
+ * @returns `YYYY-MM-DD`
+ */
+export declare function encodeDate(value: Temporal.PlainDate): string;
+/**
+ * Decodes a date.
+ *
+ * @param wire - `YYYY-MM-DD`
+ * @returns A date
+ */
+export declare function decodeDate(wire: string): Temporal.PlainDate;
+/**
+ * Encodes a time of day.
+ *
+ * @param value - Time
+ * @param precision - Fractional digits
+ * @returns `HH:MM:SS` text
+ */
+export declare function encodeTime(value: Temporal.PlainTime, precision?: TimePrecision): string;
+/**
+ * Decodes a time of day.
+ *
+ * @param wire - Time text
+ * @returns A time
+ */
+export declare function decodeTime(wire: string): Temporal.PlainTime;
+/**
+ * Encodes a time with offset.
+ *
+ * @param value - Time and offset
+ * @param precision - Fractional digits
+ * @returns Time text plus `±HH:MM`
+ */
+export declare function encodeTimeZone(value: TimeWithOffset, precision?: TimePrecision): string;
+/**
+ * Decodes a time with offset.
+ *
+ * @param wire - Time text plus an offset
+ * @returns Time and offset
+ */
+export declare function decodeTimeZone(wire: string): TimeWithOffset;
+/**
+ * Encodes a duration as an ISO-8601 duration.
+ *
+ * @param value - Duration
+ * @returns ISO-8601 text Postgres accepts for interval
+ */
+export declare function encodeDuration(value: Temporal.Duration): string;
+/**
+ * Decodes an ISO-8601 duration.
+ *
+ * @param wire - Duration text
+ * @returns A duration
+ */
+export declare function decodeDuration(wire: string): Temporal.Duration;
+/**
+ * Postgres interval field qualifier.
+ *
+ * @param fields - Qualifier such as `day to second`
+ * @returns The same qualifier when it is known
+ */
+export declare function intervalFields(fields: string): string;
+/**
+ * Temporal is in the runtime (Node and Bun) and not in this repository's
+ * TypeScript libs. These declarations name the methods the codecs call.
+ */
+declare global {
+    /** Instant, plain date-time, date, time, and duration. */
+    namespace Temporal {
+        /** UTC instant. */
+        interface Instant {
+            /**
+             * @param options - Fractional digits to keep
+             * @returns ISO-8601 text
+             */
+            toString(options?: {
+                readonly fractionalSecondDigits?: number;
+            }): string;
+        }
+        /** Date and time without a zone. */
+        interface PlainDateTime {
+            /**
+             * @param options - Fractional digits to keep
+             * @returns ISO-8601 text
+             */
+            toString(options?: {
+                readonly fractionalSecondDigits?: number;
+            }): string;
+        }
+        /** Calendar date. */
+        interface PlainDate {
+            /**
+             * @returns `YYYY-MM-DD`
+             */
+            toString(): string;
+            /**
+             * @param duration - Days to add
+             * @returns A later or earlier date
+             */
+            add(duration: {
+                readonly days: number;
+            }): Temporal.PlainDate;
+        }
+        /** Time of day. */
+        interface PlainTime {
+            /**
+             * @param options - Fractional digits to keep
+             * @returns Time text
+             */
+            toString(options?: {
+                readonly fractionalSecondDigits?: number;
+            }): string;
+        }
+        /** ISO-8601 duration. */
+        interface Duration {
+            /**
+             * @returns ISO-8601 duration text
+             */
+            toString(): string;
+        }
+    }
+    /** Temporal constructors used by the codecs. */
+    var Temporal: {
+        readonly Instant: {
+            /**
+             * @param item - ISO-8601 instant
+             * @returns An instant
+             */
+            from(item: string): Temporal.Instant;
+        };
+        readonly PlainDateTime: {
+            /**
+             * @param item - ISO-8601 date-time
+             * @returns A plain date-time
+             */
+            from(item: string): Temporal.PlainDateTime;
+        };
+        readonly PlainDate: {
+            /**
+             * @param item - `YYYY-MM-DD`
+             * @returns A date
+             */
+            from(item: string): Temporal.PlainDate;
+        };
+        readonly PlainTime: {
+            /**
+             * @param item - Time text
+             * @returns A time
+             */
+            from(item: string): Temporal.PlainTime;
+        };
+        readonly Duration: {
+            /**
+             * @param item - ISO-8601 duration
+             * @returns A duration
+             */
+            from(item: string): Temporal.Duration;
+        };
+    };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Text, varchar, char, and citext.
+ */
+import { type ColumnBuilder, type PlainFlags } from "./column.js";
+/**
+ * Unbounded text.
+ *
+ * @returns A text column
+ */
+export declare function text(): ColumnBuilder<string, PlainFlags>;
+/**
+ * Bounded text. The TypeScript type stays `string`. Encode rejects a longer value.
+ *
+ * @param length - Maximum characters, at least 1
+ * @returns A varchar column
+ */
+export declare function varchar(length: number): ColumnBuilder<string, PlainFlags>;
+/**
+ * Fixed-length character. Encode rejects a longer value and does not pad.
+ *
+ * @param length - Characters, at least 1
+ * @returns A char column
+ */
+export declare function char(length: number): ColumnBuilder<string, PlainFlags>;
+/**
+ * Case-insensitive text. The column depends on the `citext` extension.
+ *
+ * @returns A citext column
+ */
+export declare function citext(): ColumnBuilder<string, PlainFlags>;
+/**
+ * Returns text unchanged.
+ *
+ * @param value - Text
+ * @returns The same text
+ */
+export declare function encodeText(value: string): string;
+/**
+ * Returns wire text unchanged.
+ *
+ * @param wire - Text
+ * @returns The same text
+ */
+export declare function decodeText(wire: string): string;