okmodel 0.2.1 → 0.4.0

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

@@ -7,6 +7,15 @@
  * and `pg_get_constraintdef`, which is the database's normalised text (D128).
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
+/** Which cluster roles the catalog owns. */
+export type IntrospectOptions = {
+    /**
+     * Role names this catalog creates and alters.
+     *
+     * When omitted, roles, grants, and default privileges are not read.
+     */
+    readonly managedRoles?: readonly string[];
+};
 /** A connection that can run one query. Parameters are `$1`, `$2`, … */
 export type CatalogQuery = {
     /**
@@ -29,7 +38,7 @@ export type CatalogQuery = {
  * @param logical - Namespace stored on the catalog identities
  * @returns A checked catalog
  */
-export declare function introspectSchema(runner: CatalogQuery, concrete: string, logical?: string): Promise<Catalog>;
+export declare function introspectSchema(runner: CatalogQuery, concrete: string, logical?: string, options?: IntrospectOptions): Promise<Catalog>;
 /**
  * Applies one expression as a check and reads Postgres's reprint.
  *

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

@@ -7,7 +7,7 @@
 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" | "and" | "has" | "none" | "every" | "inc" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey" | "path" | "matches" | "json.set" | "arr.append" | "arr.remove";
+export type OperatorName = "eq" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "contains" | "endsWith" | "like" | "ilike" | "inList" | "notIn" | "not" | "or" | "and" | "has" | "none" | "every" | "inc" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey" | "path" | "matches" | "similar" | "wordSimilar" | "json.set" | "arr.append" | "arr.remove";
 /** A tagged operator. `value` is the operand the helper stored. */
 export type Tagged<Name extends OperatorName, V> = {
     readonly [brand]: Name;
@@ -48,6 +48,13 @@ export type MatchValue = {
 };
 /** `@@` against a tsvector column. */
 export type Matches = Tagged<"matches", MatchValue>;
+/** Text stored on a `pg_trgm` operator. `schema` is the extension's install schema. */
+export type TrigramQuery = {
+    readonly query: string;
+    readonly schema: string;
+};
+/** `pg_trgm` `%` or `<%`. */
+export type Trigram<Name extends "similar" | "wordSimilar"> = Tagged<Name, TrigramQuery>;
 /** `jsonb_set` path and the new value. */
 export type JsonSetValue<V> = {
     readonly path: readonly string[];

package/dist/dialects/pg/role/check.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Role checks for `okm doctor` and apply preflight.
+ *
+ * Both run before any catalog statement. `connect()` does not call them.
+ */
+import type { DriverPool } from "../../../contracts/driver.js";
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+import type { RolesInput } from "./index.js";
+/** A pool or a reserved connection. Both can run one statement. */
+type Runner = Pick<DriverPool, "execute">;
+/**
+ * Checks named roles, `CREATEROLE`, and the application role's privileges.
+ *
+ * A missing external role is reported. A managed role that is absent is not:
+ * the plan creates it. OKM1825 is raised only when the object exists and the
+ * privilege is missing.
+ *
+ * @param runner - Database connection
+ * @param roles - `defineConfig({ roles })`
+ * @param objects - Catalog, including grants
+ */
+export declare function assertRoleHealth(runner: Runner, roles: RolesInput, objects: readonly CatalogObject[]): Promise<void>;
+/**
+ * Refuses to apply role changes when the acting role lacks `CREATEROLE`.
+ *
+ * @param runner - Database connection
+ * @param role - The role that will run `CREATE ROLE` or `ALTER ROLE`
+ */
+export declare function assertCreateRole(runner: Runner, role: string): Promise<void>;
+/**
+ * Reads `current_user`.
+ *
+ * @param runner - Database connection
+ * @returns The role this session is acting as
+ */
+export declare function currentUser(runner: Runner): Promise<string>;
+/**
+ * Reports whether `pg_roles` has the name.
+ *
+ * @param runner - Database connection
+ * @param name - Role name
+ * @returns `true` when the role exists
+ */
+export declare function roleExists(runner: Runner, name: string): Promise<boolean>;
+export {};

package/dist/dialects/pg/role/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `roles: { migration, app }`.
+ *
+ * The object contributes role, grant, and default-privilege records. `schema()`
+ * does not import this module. Tooling calls {@link attachRoles} when the
+ * config names roles.
+ */
+import type { Catalog, CatalogObject } from "../../../contracts/catalog/types.js";
+/** A role the plan creates and alters. It is never dropped. */
+export type ManagedRole = {
+    readonly name: string;
+    /** `LOGIN` when true. The default is `NOLOGIN`. */
+    readonly login?: boolean;
+    /** `INHERIT` when not `false`. */
+    readonly inherit?: boolean;
+};
+/**
+ * Roles named by `defineConfig`.
+ *
+ * A string is external: it must already exist. A name listed in `managed` is
+ * created when `pg_roles` does not have it.
+ */
+export type RolesInput = {
+    /** Role that runs migrations. */
+    readonly migration: string;
+    /** Role the application connects as. */
+    readonly app: string;
+    /** Roles this catalog creates and alters. */
+    readonly managed?: readonly ManagedRole[];
+};
+/**
+ * Adds role, grant, and default-privilege objects to a catalog.
+ *
+ * Grants and default privileges are for {@link RolesInput.app} on every
+ * managed table, view, materialized view, sequence, and function. Fine-grained
+ * grants are not accepted here.
+ *
+ * @param source - Catalog from `schema()`
+ * @param input - Migration role, application role, and managed roles
+ * @returns A catalog that includes those objects
+ */
+export declare function attachRoles(source: Catalog, input: RolesInput): Catalog;
+/**
+ * Catalog records for one `roles` configuration.
+ *
+ * @param input - Migration role, application role, and managed roles
+ * @param built - Objects already in the catalog
+ * @returns Role, grant, and default-privilege records
+ */
+export declare function contributeRoles(input: RolesInput, built: readonly CatalogObject[]): readonly CatalogObject[];

package/dist/dialects/pg/role/sql.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SQL for roles, grants, and default privileges.
+ *
+ * The plan calls these. `SET ROLE` is not one of them: the runner issues it
+ * once, outside the plan (D119).
+ */
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+/** Statements the planner inserts around the rest of the catalog. */
+export type PrivilegeSql = {
+    /** Revokes, run while the objects still exist. */
+    readonly revoke: readonly PrivilegeStatement[];
+    /** Role creates, role alters, and default privileges. Before new tables. */
+    readonly prepare: readonly PrivilegeStatement[];
+    /** Grants on objects that exist, or that this plan creates first. */
+    readonly grant: readonly PrivilegeStatement[];
+};
+/** One privilege statement and the planner kind it is. */
+export type PrivilegeStatement = {
+    readonly sql: string;
+    readonly kind: "revoke" | "revoke-default" | "create-role" | "alter-role" | "grant-default" | "grant";
+};
+/**
+ * Diffs role, grant, and default-privilege objects into SQL.
+ *
+ * A role is created only when it is managed and absent. It is altered only
+ * when both sides are managed. It is never dropped. Grants and default
+ * privileges are revoked and granted. None of the statements use
+ * `IF NOT EXISTS`.
+ *
+ * @param before - Previous catalog objects
+ * @param after - Next catalog objects
+ * @param schema - Concrete schema name
+ * @param recreated - Identity keys this plan drops and creates. Postgres drops
+ * grants with the object, so those grants are issued again after it exists
+ * @returns Statements in three groups
+ */
+export declare function privilegeSql(before: readonly CatalogObject[], after: readonly CatalogObject[], schema: string, recreated?: ReadonlySet<string>): PrivilegeSql;
+/**
+ * Role name in `create role`, when the statement is one.
+ *
+ * @param sql - One plan statement
+ * @returns The role, or `undefined` when the statement is not `CREATE ROLE`
+ */
+export declare function createdRoleName(sql: string): string | undefined;
+/**
+ * Reports whether a statement creates or alters a role.
+ *
+ * @param sql - One plan statement
+ * @returns `true` for `CREATE ROLE` and `ALTER ROLE`
+ */
+export declare function changesRole(sql: string): boolean;

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

@@ -28,6 +28,13 @@ export type IndexCall = {
      * Absent on an ordinary index.
      */
     readonly predicate?: string;
+    /**
+     * Raw index tail an extension may set on the call.
+     *
+     * A `using …` tail is the extension's index method. The core factory does
+     * not read it. `compileIndexes` copies the field onto the catalog index.
+     */
+    readonly expression?: string;
     /**
      * Marks the index unique.
      *
@@ -105,7 +112,13 @@ export type TableOptions<TColumns> = {
      */
     readonly presets?: PresetMap<RowFrom<TColumns>>;
     readonly policies?: unknown;
-    readonly reference?: unknown;
+    /**
+     * Rows the application requires to exist.
+     *
+     * Apply inserts a row when its key is missing. It does not update or delete.
+     * The rows stay on the schema. They are not a diff in the catalog.
+     */
+    readonly reference?: ReferenceOption;
     /** `one` and `many`. Other relation kinds stay reserved. */
     readonly relations?: unknown;
 };
@@ -200,6 +213,16 @@ export type InsertFrom<TColumns> = {
 export type UpdateFrom<TColumns, TKey extends string = never> = {
     readonly [K in keyof TColumns as K extends TKey ? never : ColumnUpdateOf<TColumns[K]> extends never ? never : K]: ColumnUpdateOf<TColumns[K]>;
 };
+/**
+ * Rows declared with the table option `reference`.
+ *
+ * `key` is one column name or several, in constraint order. `rows` are the
+ * values apply inserts when that key is absent.
+ */
+export type ReferenceOption = {
+    readonly key: string | readonly string[];
+    readonly rows: readonly Readonly<Record<string, string | number | boolean | null>>[];
+};
 /**
  * Declares a table.
  *

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

@@ -81,6 +81,15 @@ export type ColumnTenancy = {
      * @param ctx - Names, scope, and the table map
      */
     hook(target: Record<string, unknown>, ctx: SchemaHookCtx): void;
+    /**
+     * Treats a view that exposes the tenant key as tenant-scoped.
+     *
+     * The predicate then applies to reads of that view. A view that does not
+     * expose the key is refused earlier (OKM1820) unless it is `global`.
+     *
+     * @param name - Client name of the view
+     */
+    scopeView(name: string): void;
     missing(table: string): never;
 };
 /**

package/dist/dialects/pg/view/client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Read model and client hook for a declared view.
+ *
+ * `schema()` calls `install` and the client calls `hook`. Neither path is
+ * imported by a featureless app. Writes are not copied onto the handle.
+ */
+import type { ColumnTenancy } from "../tenancy.js";
+import type { SchemaHook, TableModel } from "../model.js";
+import { type AnyTable } from "../table.js";
+/** What `schema()` passes when it binds a view. */
+export type ViewInstall = (model: {
+    [name: string]: TableModel;
+}, tenancy: ColumnTenancy | undefined, tables: readonly AnyTable[], casing: "snake" | undefined, scoped: Set<string>) => void;
+/**
+ * Client name, read model, and the hook that moves the handle under `views`.
+ *
+ * @param name - SQL name of the view
+ * @param columns - Declared output columns
+ * @param query - Author SQL
+ * @param tenancy - `global("reason")`, when the view opts out
+ * @returns Methods stored on the declaration
+ */
+export declare function viewClient(name: string, columns: readonly {
+    readonly name: string;
+    readonly type: string;
+}[], query: string, tenancy: unknown): {
+    readonly field: string;
+    readonly install: ViewInstall;
+    readonly hook: SchemaHook;
+};

package/dist/dialects/pg/view/depend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Column dependencies of a view, read from `pg_depend`.
+ *
+ * Postgres records them on the view's rewrite rule. The edge is column
+ * granularity when that column is a catalog object.
+ */
+import type { CatalogObject, Namespace, ObjectIdentity } from "../../../contracts/catalog/types.js";
+/**
+ * Reads a query cell as text.
+ *
+ * @param value - A driver cell
+ * @returns The string, or empty when the cell is not a scalar
+ */
+export declare function cellText(value: unknown): string;
+/**
+ * `pg_depend` rows for views and materialized views in one schema.
+ *
+ * `$1` is the concrete schema name. `refobjsubid > 0` keeps column edges.
+ */
+export declare const VIEW_DEPENDENCIES = "\n  select v.relname as view, t.relname as table, a.attname as column\n  from pg_depend d\n  join pg_rewrite r on r.oid = d.objid and d.classid = 'pg_rewrite'::regclass\n  join pg_class v on v.oid = r.ev_class\n  join pg_class t on t.oid = d.refobjid and d.refclassid = 'pg_class'::regclass\n  join pg_attribute a on a.attrelid = t.oid and a.attnum = d.refobjsubid\n  join pg_namespace n on n.oid = v.relnamespace\n  where n.nspname = $1\n    and v.relkind in ('v', 'm')\n    and d.refobjsubid > 0\n    and v.oid <> t.oid\n    and t.relkind in ('r', 'p', 'v', 'm')\n";
+/**
+ * Turns dependency rows into edges that exist in `objects`.
+ *
+ * A table column becomes a column edge. A view that is itself a catalog
+ * object becomes an object edge. Anything else is omitted: the catalog
+ * refuses an edge whose target is missing.
+ *
+ * @param rows - Rows from {@link VIEW_DEPENDENCIES}
+ * @param namespace - Logical namespace stored on the edges
+ * @param objects - Catalog the edges must point into
+ * @returns Edges keyed by view name
+ */
+export declare function viewDependencyEdges(rows: readonly Readonly<Record<string, unknown>>[], namespace: Namespace, objects: readonly CatalogObject[]): Map<string, ObjectIdentity[]>;
+/** Logical public namespace. Tests and the default schema use it. */
+export declare const PUBLIC: Namespace;

package/dist/dialects/pg/view/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `okmodel/view`.
+ *
+ * `view()` and `materializedView()` return objects that produce their own
+ * catalog records. `schema()` only asks each declared object for those records.
+ * DDL, diffing, and scratch verification stay out of this module's callers
+ * until a plan or a check loads them.
+ */
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+import type { SchemaHook } from "../model.js";
+import type { SqlText } from "../table.js";
+import { type ViewInstall } from "./client.js";
+/** One declared output column. `type` is the Postgres type name. */
+export type ViewColumnInput = {
+    readonly name: string;
+    readonly type: string;
+};
+/** Options for {@link view}. */
+export type ViewOptions = {
+    readonly columns: readonly ViewColumnInput[];
+    readonly query: SqlText | string;
+    /** Schema. The default is `public`. */
+    readonly schema?: string;
+    /**
+     * Opts the view out of tenancy.
+     *
+     * A view that reads a tenant table and does not expose the tenant key is
+     * OKM1820 unless this is `global("reason")`.
+     */
+    readonly tenancy?: unknown;
+};
+/**
+ * One declared view.
+ *
+ * `contribute` builds the catalog record. Column dependencies are filled
+ * from `pg_depend` by scratch verification, not at this call.
+ */
+export type ViewDeclaration = {
+    readonly name: string;
+    readonly schema: string;
+    /**
+     * Catalog record for this declaration.
+     *
+     * @param peers - The `schema({ views })` list
+     * @param built - Objects the schema has already staged
+     * @returns The view record
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+    /** Publishes the read model. `schema()` calls it. */
+    install: ViewInstall;
+    /** Moves the read handle under `db.views`. */
+    hook: SchemaHook;
+};
+/** One index owned by a materialized view. */
+export type MaterializedViewIndexInput = {
+    readonly name?: string;
+    readonly columns: readonly string[];
+    readonly unique?: boolean;
+};
+/** Options for {@link materializedView}. */
+export type MaterializedViewOptions = ViewOptions & {
+    readonly indexes?: readonly MaterializedViewIndexInput[];
+    /**
+     * Populate mode.
+     *
+     * `"concurrently"` plans `REFRESH MATERIALIZED VIEW CONCURRENTLY` and
+     * requires a unique index (OKM1822). Omitted still populates, without
+     * `CONCURRENTLY`.
+     */
+    readonly refresh?: "concurrently";
+};
+/**
+ * One declared materialized view.
+ *
+ * Identity is `(namespace, name)`. Indexes are separate catalog objects.
+ */
+export type MaterializedViewDeclaration = {
+    readonly name: string;
+    readonly schema: string;
+    /**
+     * Catalog records for this declaration.
+     *
+     * @param peers - The `schema({ views })` list
+     * @param built - Objects the schema has already staged
+     * @returns The materialized view and its indexes
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+    /** Publishes the read model. `schema()` calls it. */
+    install: ViewInstall;
+    /** Moves the read handle under `db.views`. */
+    hook: SchemaHook;
+};
+/**
+ * Declares a view as SQL with output columns.
+ *
+ * The query is stored as written. A scratch database reads `pg_depend` and
+ * `pg_get_viewdef` before a plan treats the body as canonical.
+ *
+ * @param name - View name
+ * @param options - Columns and query
+ * @returns The definition object `schema({ views })` stores
+ */
+export declare function view(name: string, options: ViewOptions): ViewDeclaration;
+/**
+ * Declares a materialized view.
+ *
+ * Creation is `WITH NO DATA`. Populate is a later plan step. `refresh:
+ * "concurrently"` without a unique index is OKM1822.
+ *
+ * @param name - Materialized view name
+ * @param options - Columns, query, indexes, and refresh mode
+ * @returns The definition object `schema({ views })` stores
+ */
+export declare function materializedView(name: string, options: MaterializedViewOptions): MaterializedViewDeclaration;