okmodel 0.2.1 → 0.4.0

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

@@ -2,7 +2,7 @@
  * Enum and domain columns.
  *
  * The catalog column type is the type name. Compile records a dependency on
- * the enum, and `schema()` stores that enum as a catalog type.
+ * the type, and the column's `emit` adds that type when the catalog is built.
  */
 import { type ColumnBuilder, type ColumnFlags, type PlainFlags } from "./column.js";
 /**
@@ -17,14 +17,16 @@ import { type ColumnBuilder, type ColumnFlags, type PlainFlags } from "./column.
  */
 export declare function enumColumn<const TValues extends readonly string[]>(name: string, values: TValues): ColumnBuilder<TValues[number], PlainFlags>;
 /**
- * A named domain over a scalar column.
+ * A named domain over a column type.
  *
- * Domains are not catalog objects in this version. Calling the builder fails
- * with OKM1061 until 0.3, when a domain becomes a `type` subkind (D141).
+ * The TypeScript row type and the codec are the base column's. The catalog
+ * column type is the domain name, and the domain is a `type` object (D141).
+ * An enum base is OKM1060. Changing the base type of an existing domain is
+ * OKM1020 when the plan is built.
  *
  * @param name - Domain name
- * @param base - Scalar column the domain is based on
- * @param check - Domain check expression
- * @returns A domain column with the base codec, once 0.3 supports it
+ * @param base - Column the domain is based on
+ * @param check - Domain check expression, stored as written
+ * @returns A domain column
  */
-export declare function domain<TValue, TFlags extends ColumnFlags>(_name: string, _base: ColumnBuilder<TValue, TFlags>, _check: string): ColumnBuilder<TValue, PlainFlags>;
+export declare function domain<TValue, TFlags extends ColumnFlags>(name: string, base: ColumnBuilder<TValue, TFlags>, check: string): ColumnBuilder<TValue, TFlags>;

package/dist/dialects/pg/ext/citext.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `citext` extension.
+ *
+ * Case-insensitive equality is the column's ordinary `eq` once the type is
+ * `citext`. This module declares the extension so that column can build.
+ */
+import { type Extension, type ExtensionOptions } from "./index.js";
+/**
+ * Declares `citext`.
+ *
+ * @param options - Schema and version pin. The version differs by Postgres major, so the default is unpinned.
+ * @returns The extension object
+ */
+export declare function citext(options?: ExtensionOptions): Extension;

package/dist/dialects/pg/ext/citext.js

@@ -0,0 +1,11 @@
+import {
+  extension2
+} from "../../../shared/ycatkxmq.js";
+
+// src/dialects/pg/ext/citext.ts
+function citext(options = {}) {
+  return extension2("citext", options);
+}
+export {
+  citext
+};

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

@@ -0,0 +1,52 @@
+/**
+ * `okmodel/ext`.
+ *
+ * `extension()` returns an object that produces its own catalog record.
+ * Duplicate and undeclared-use checks run here. Core only asks each declared
+ * object for its records.
+ */
+import type { ExtensionObject } from "../../../contracts/catalog/types.js";
+/** Options on {@link extension}. */
+export type ExtensionOptions = {
+    /** Exact pin (`1.6`) or a floor (`>=0.7`). Omitted means unpinned. */
+    readonly version?: string;
+    /** Install schema. The default is `public`. */
+    readonly schema?: string;
+    /**
+     * Whether the extension may move.
+     *
+     * The default is `true`. A move of a non-relocatable extension is OKM1814.
+     */
+    readonly relocatable?: boolean;
+};
+/**
+ * One declared extension.
+ *
+ * Methods on a built-in, such as `pgTrgm.similar`, are the typed API. They
+ * are not stored in the catalog record.
+ */
+export type Extension = {
+    readonly name: string;
+    readonly schema: string;
+    readonly relocatable: boolean;
+    readonly version?: string;
+    /**
+     * Catalog records for this declaration.
+     *
+     * @param peers - The `schema({ extensions })` list
+     * @param built - Objects the schema has already staged
+     * @returns The extension record
+     */
+    contribute(peers: unknown, built: unknown): readonly ExtensionObject[];
+};
+/**
+ * Declares an extension by name.
+ *
+ * A bare declaration has the full lifecycle and no typed operators. Built-ins
+ * wrap this and add their own methods.
+ *
+ * @param name - Extension name, such as `citext` or `vector`
+ * @param options - Schema, version pin, and whether it may move
+ * @returns The definition object `schema({ extensions })` stores
+ */
+export declare function extension(name: string, options?: ExtensionOptions): Extension;

package/dist/dialects/pg/ext/index.js

@@ -0,0 +1,6 @@
+import {
+  extension2
+} from "../../../shared/ycatkxmq.js";
+export {
+  extension2 as extension
+};

package/dist/dialects/pg/ext/pg-trgm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The `pg_trgm` extension.
+ *
+ * `similar` and `wordSimilar` are where-operators. Their SQL lives in the
+ * lazy operator module. Index methods set the catalog `expression` to a
+ * `using …` tail; the core index factory does not grow a `using` field.
+ */
+import { type Tagged } from "../operators.js";
+import type { IndexCall } from "../table.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** Operand stored on a trigram operator. */
+export type TrigramQuery = {
+    readonly query: string;
+    readonly schema: string;
+};
+/** `pg_trgm` plus its operators and index methods. */
+export type PgTrgm = Extension & {
+    /**
+     * `column % query`.
+     *
+     * @param query - The text to compare
+     * @returns A tagged where-operator
+     */
+    similar(query: string): Tagged<"similar", TrigramQuery>;
+    /**
+     * `column <% query`.
+     *
+     * @param query - The text to compare
+     * @returns A tagged where-operator
+     */
+    wordSimilar(query: string): Tagged<"wordSimilar", TrigramQuery>;
+    /**
+     * A GIN index with `gin_trgm_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gin(column: string): IndexCall;
+    /**
+     * A GiST index with `gist_trgm_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gist(column: string): IndexCall;
+};
+/**
+ * Declares `pg_trgm`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its operators
+ */
+export declare function pgTrgm(options?: ExtensionOptions): PgTrgm;

package/dist/dialects/pg/ext/pg-trgm.js

@@ -0,0 +1,42 @@
+import {
+  extension2
+} from "../../../shared/ycatkxmq.js";
+import {
+  tag
+} from "../../../shared/cn0n68ft.js";
+
+// src/dialects/pg/ext/pg-trgm.ts
+function pgTrgm(options = {}) {
+  const declared = extension2("pg_trgm", options);
+  const schema = declared.schema;
+  return {
+    ...declared,
+    similar(query) {
+      return tag("similar", { query, schema });
+    },
+    wordSimilar(query) {
+      return tag("wordSimilar", { query, schema });
+    },
+    gin(column) {
+      return usingIndex(column, "gin", "gin_trgm_ops");
+    },
+    gist(column) {
+      return usingIndex(column, "gist", "gist_trgm_ops");
+    }
+  };
+}
+function usingIndex(column, method, opclass) {
+  const quoted = `"${column.replaceAll('"', '""')}"`;
+  const call = {
+    columns: [column],
+    isUnique: false,
+    expression: `using ${method} (${quoted} ${opclass})`,
+    unique() {
+      return call;
+    }
+  };
+  return call;
+}
+export {
+  pgTrgm
+};

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

@@ -0,0 +1,107 @@
+/**
+ * `okmodel/fn`.
+ *
+ * `fn()` and `trigger()` return objects that produce their own catalog
+ * records. `schema()` only asks each declared object for those records.
+ */
+import type { CatalogObject, FunctionLanguage, FunctionSecurity, FunctionVolatility, TriggerEvent, TriggerLevel, TriggerTiming } from "../../../contracts/catalog/types.js";
+import type { AnyTable, SqlText } from "../table.js";
+/** One argument of {@link fn}. */
+export type FunctionArgumentInput = {
+    readonly name: string;
+    readonly type: string;
+};
+/**
+ * A table, or one column of a table.
+ *
+ * A table is an object dependency. `{ table, column }` is a column dependency.
+ * `column` is the SQL name.
+ */
+export type DependsOn = AnyTable | {
+    readonly table: AnyTable;
+    readonly column: string;
+};
+/** Options for {@link fn}. */
+export type FunctionOptions = {
+    readonly arguments?: readonly FunctionArgumentInput[];
+    readonly returns: string;
+    readonly language: FunctionLanguage;
+    readonly volatility?: FunctionVolatility;
+    readonly security?: FunctionSecurity;
+    /** Required when `security` is `"definer"` (OKM1823). */
+    readonly searchPath?: string;
+    readonly body: SqlText | string;
+    /**
+     * Tables and columns the body uses.
+     *
+     * Required for plpgsql (OKM1824). Omitted for `LANGUAGE sql` that begins
+     * with `BEGIN ATOMIC`; those edges are read from `pg_depend`.
+     */
+    readonly dependsOn?: readonly DependsOn[];
+    /** Schema. The default is `public`. */
+    readonly schema?: string;
+};
+/**
+ * One declared function.
+ *
+ * `contribute` builds the catalog record. Overloads differ by argument types.
+ */
+export type Routine = {
+    readonly name: string;
+    readonly schema: string;
+    readonly argTypes: readonly string[];
+    /**
+     * Catalog record for this declaration.
+     *
+     * @param peers - The `schema({ functions })` list
+     * @param built - Objects the schema has already staged
+     * @returns The function record
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+};
+/** Options for {@link trigger}. */
+export type TriggerOptions = {
+    readonly on: AnyTable;
+    readonly timing: TriggerTiming;
+    readonly events: readonly TriggerEvent[];
+    readonly level: TriggerLevel;
+    /** `UPDATE OF` columns. SQL names. Each one is a column dependency. */
+    readonly updateOf?: readonly string[];
+    readonly when?: SqlText | string;
+    readonly calls: Routine;
+};
+/**
+ * One declared trigger.
+ *
+ * Identity is `(table, name)`.
+ */
+export type TriggerDeclaration = {
+    readonly name: string;
+    /**
+     * Catalog record for this declaration.
+     *
+     * @param peers - The `schema({ triggers })` list
+     * @param built - Objects the schema has already staged
+     * @returns The trigger record
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+};
+/**
+ * Declares a function.
+ *
+ * plpgsql without `dependsOn` is OKM1824. `security: "definer"` without
+ * `searchPath` is OKM1823.
+ *
+ * @param name - Function name
+ * @param options - Signature, language, body, and dependencies
+ * @returns The definition object `schema({ functions })` stores
+ */
+export declare function fn(name: string, options: FunctionOptions): Routine;
+/**
+ * Declares a trigger.
+ *
+ * @param name - Trigger name, unique on its table
+ * @param options - Table, timing, events, and the function it calls
+ * @returns The definition object `schema({ triggers })` stores
+ */
+export declare function trigger(name: string, options: TriggerOptions): TriggerDeclaration;

package/dist/dialects/pg/fn/index.js

@@ -0,0 +1,175 @@
+import {
+  functionObject,
+  triggerObject
+} from "../../../shared/9x25fxhc.js";
+import {
+  staticNamespace2
+} from "../../../shared/t4tbsy9h.js";
+import {
+  OkmError2
+} from "../../../shared/52szzakm.js";
+
+// src/dialects/pg/fn/index.ts
+function fn(name, options) {
+  const language = options.language;
+  const body = bodyText(options.body);
+  const atomic = language === "sql" && /^\s*begin\s+atomic\b/i.test(body);
+  if (language === "plpgsql" && options.dependsOn === undefined) {
+    throw new OkmError2("OKM1824", `Function ${name} is plpgsql and has no dependsOn. Postgres does not record dependencies inside the body.`, {
+      fix: {
+        summary: "List dependsOn. LANGUAGE sql with BEGIN ATOMIC is inferred and does not need the list."
+      }
+    });
+  }
+  if (options.security === "definer" && (options.searchPath === undefined || options.searchPath.trim().length === 0)) {
+    throw new OkmError2("OKM1823", `Function ${name} is security definer and has no search_path.`, {
+      fix: { summary: "Set search_path on the function to the schemas it is allowed to see." }
+    });
+  }
+  const argTypes = (options.arguments ?? []).map((argument) => argument.type);
+  const schema = options.schema ?? "public";
+  return {
+    name,
+    schema,
+    argTypes,
+    contribute(peers, built) {
+      assertPeers(peers, "functions");
+      const namespace = staticNamespace2(schema);
+      const provenance = { origin: "file", name };
+      return [
+        functionObject({
+          namespace,
+          name,
+          ...options.arguments !== undefined ? { arguments: options.arguments } : {},
+          returns: options.returns,
+          language,
+          ...options.volatility !== undefined ? { volatility: options.volatility } : {},
+          ...options.security !== undefined ? { security: options.security } : {},
+          ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
+          body,
+          ...atomic ? { atomic: true } : {},
+          provenance,
+          dependencies: dependencyEdges(options.dependsOn, built)
+        })
+      ];
+    }
+  };
+}
+function trigger(name, options) {
+  return {
+    name,
+    contribute(peers, built) {
+      assertPeers(peers, "triggers");
+      const parent = tableRef(options.on, built);
+      const namespace = staticNamespace2(options.calls.schema);
+      const calls = {
+        namespace,
+        name: options.calls.name,
+        argTypes: options.calls.argTypes
+      };
+      if (!hasIdentity(built, { kind: "function", ...calls })) {
+        throw new OkmError2("OKM1020", `Trigger ${name} calls ${options.calls.name}, which is not in the catalog.`, { fix: { summary: "List the function in schema({ functions }) before the trigger." } });
+      }
+      for (const column of options.updateOf ?? []) {
+        if (!hasIdentity(built, { kind: "column", parent, name: column })) {
+          throw new OkmError2("OKM1020", `Trigger ${name} names column ${column}, which ${parent.name} does not have.`, { fix: { summary: "Name a column of the table the trigger is on." } });
+        }
+      }
+      return [
+        triggerObject({
+          parent,
+          name,
+          timing: options.timing,
+          events: options.events,
+          level: options.level,
+          calls,
+          ...options.updateOf !== undefined ? { updateOf: options.updateOf } : {},
+          ...options.when !== undefined ? { when: bodyText(options.when) } : {},
+          provenance: { origin: "file", name }
+        })
+      ];
+    }
+  };
+}
+function bodyText(body) {
+  return typeof body === "string" ? body : body.text;
+}
+function assertPeers(peers, option) {
+  if (!Array.isArray(peers)) {
+    throw new OkmError2("OKM1020", `schema({ ${option} }) must be a list.`, {
+      fix: { summary: `Pass an array to schema({ ${option} }).` }
+    });
+  }
+}
+function dependencyEdges(dependsOn, built) {
+  if (dependsOn === undefined)
+    return [];
+  return dependsOn.map((item) => {
+    if ("column" in item && "table" in item) {
+      const parent = tableRef(item.table, built);
+      const edge = { kind: "column", parent, name: item.column };
+      if (!hasIdentity(built, edge)) {
+        throw new OkmError2("OKM1020", `dependsOn names column ${item.column}, which ${parent.name} does not have.`, { fix: { summary: "Name a column of a table in this schema." } });
+      }
+      return edge;
+    }
+    const parent = tableRef(item, built);
+    return { kind: "table", namespace: parent.namespace, name: parent.name };
+  });
+}
+function tableRef(table, built) {
+  if (!Array.isArray(built)) {
+    throw new OkmError2("OKM1020", `Table ${table.name} is not in the catalog.`, {
+      fix: { summary: "List the table in schema({ tables })." }
+    });
+  }
+  for (const object of built) {
+    if (!isRecord(object) || object.kind !== "table")
+      continue;
+    const identity = object.identity;
+    const provenance = object.provenance;
+    if (!isRecord(identity) || !isRecord(provenance))
+      continue;
+    if (provenance.origin === "file" && provenance.name === table.name && typeof identity.name === "string") {
+      const namespace = identity.namespace;
+      if (isRecord(namespace) && namespace.form === "static" && typeof namespace.name === "string") {
+        return { namespace: staticNamespace2(namespace.name), name: identity.name };
+      }
+    }
+  }
+  throw new OkmError2("OKM1020", `Table ${table.name} is not in the catalog.`, {
+    fix: { summary: "List the table in schema({ tables })." }
+  });
+}
+function hasIdentity(built, identity) {
+  if (!Array.isArray(built))
+    return false;
+  for (const object of built) {
+    if (!isRecord(object) || !isRecord(object.identity))
+      continue;
+    if (same(object.identity, identity))
+      return true;
+  }
+  return false;
+}
+function same(left, right) {
+  if (left.kind !== right.kind)
+    return false;
+  if (right.kind === "function") {
+    return left.name === right.name && JSON.stringify(left.argTypes) === JSON.stringify(right.argTypes);
+  }
+  if (right.kind === "column") {
+    const parent = left.parent;
+    return left.name === right.name && isRecord(parent) && parent.name === right.parent.name;
+  }
+  if (right.kind === "table")
+    return left.name === right.name;
+  return false;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  fn,
+  trigger
+};

package/dist/dialects/pg/fn/touch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The trigger and function `timestamps({ enforce: "trigger" })` contributes.
+ *
+ * One function per updated-column SQL name. One trigger per table. Provenance
+ * is the timestamps trait. The body writes `new.<column> = now()`.
+ */
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+/**
+ * Catalog records for tables that carry the timestamps trait.
+ *
+ * @param built - Objects already staged, including columns
+ * @returns The function and one trigger per table, or nothing when no table opted in
+ */
+export declare function timestampRecords(built: unknown): readonly CatalogObject[];

package/dist/dialects/pg/index.js

@@ -2,7 +2,7 @@ import {
   jsonReplacer2,
   json2,
   jsonb2
-} from "../../shared/yw5c610b.js";
+} from "../../shared/gjthds9j.js";
 import {
   encodeInstant,
   decodeInstant,
@@ -14,17 +14,25 @@ import {
   time2,
   timetz2,
   interval2
-} from "../../shared/xkz8g6by.js";
-import {
-  id2,
-  uuid2
-} from "../../shared/ps43134h.js";
+} from "../../shared/1g0drakv.js";
 import {
   one2,
   many2,
   manyThrough2,
   schema2
-} from "../../shared/7mht49yd.js";
+} from "../../shared/3p4b1fg0.js";
+import {
+  domainType
+} from "../../shared/g7ez901n.js";
+import {
+  id2,
+  uuid2
+} from "../../shared/dyj86cmj.js";
+import {
+  table2,
+  index2,
+  sql2
+} from "../../shared/jsd07prz.js";
 import {
   text2,
   varchar2,
@@ -32,25 +40,27 @@ import {
   citext2,
   encodeText,
   decodeText
-} from "../../shared/sacqha1y.js";
-import {
-  table2,
-  index2,
-  sql2
-} from "../../shared/x9v1qgeb.js";
+} from "../../shared/4m9fn52z.js";
 import {
   ColumnBuilder2,
   required,
-  openColumn
-} from "../../shared/dd4f8mnx.js";
+  openColumn,
+  formatType
+} from "../../shared/c9z5g0fm.js";
 import {
   definition,
-  unavailable,
   rejected
-} from "../../shared/xatfg0gn.js";
+} from "../../shared/tmbdywx0.js";
+import {
+  sameNamespace2,
+  compareText
+} from "../../shared/t4tbsy9h.js";
 import {
   tag
 } from "../../shared/cn0n68ft.js";
+import {
+  catalogError2
+} from "../../shared/52szzakm.js";
 var __defProp = Object.defineProperty;
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
@@ -664,8 +674,83 @@ function enumColumn(name, values) {
     sqlForm: "quote"
   });
 }
-function domain(_name, _base, _check) {
-  unavailable("t.domain() is not available yet. It arrives in 0.3.");
+function domain(name, base, check) {
+  if (name.length === 0)
+    definition("domain name must be a non-empty type name.");
+  if (check.length === 0)
+    definition("domain check must be a non-empty expression.");
+  if (base.state.enumLabels !== undefined) {
+    definition("A domain cannot use an enum as its base in this version. Use a scalar column type.");
+  }
+  const baseSql = canonicalBase(formatType(base.state.baseType, base.state.dims));
+  const extension = base.state.extension;
+  const inner = base.state.baseType;
+  const nested = base.state.domain !== undefined;
+  return new ColumnBuilder2({
+    ...base.state,
+    baseType: name,
+    dims: 0,
+    typeDependency: name,
+    enumLabels: undefined,
+    domain: {
+      base: baseSql,
+      check,
+      emit(namespace, provenance, objects) {
+        base.state.domain?.emit?.(namespace, provenance, objects);
+        const dependencies = [];
+        if (extension !== undefined)
+          dependencies.push({ kind: "extension", name: extension });
+        if (nested)
+          dependencies.push({ kind: "type", namespace, name: inner });
+        const built = domainType({
+          namespace,
+          name,
+          base: baseSql,
+          check,
+          provenance,
+          ...dependencies.length > 0 ? { dependencies } : {}
+        });
+        const index = objects.findIndex((object) => object.kind === "type" && object.identity.name === name && sameNamespace2(object.identity.namespace, namespace));
+        const previous = index >= 0 ? objects[index] : undefined;
+        if (previous !== undefined && previous.kind === "type") {
+          const definition = previous.definition;
+          if (!("base" in definition) || definition.base !== baseSql || definition.check !== check) {
+            catalogError2("OKM1020", `Domain ${name} is ${"base" in definition ? definition.base : "an enum"} on ${previous.provenance.name} and ${baseSql} on ${provenance.name}. One domain has one base and one check.`);
+          }
+          if (compareText(provenance.name, previous.provenance.name) < 0)
+            objects[index] = built;
+          return;
+        }
+        objects.push(built);
+      }
+    }
+  });
+}
+function canonicalBase(typeName) {
+  const bracket = typeName.indexOf("[");
+  const scalar = bracket === -1 ? typeName : typeName.slice(0, bracket);
+  const suffix = bracket === -1 ? "" : typeName.slice(bracket);
+  return canonicalScalar(scalar) + suffix;
+}
+function canonicalScalar(typeName) {
+  const varchar = /^varchar\((\d+)\)$/.exec(typeName);
+  if (varchar !== null)
+    return `character varying(${varchar[1] ?? ""})`;
+  const fixed = /^char\((\d+)\)$/.exec(typeName);
+  if (fixed !== null)
+    return `character(${fixed[1] ?? ""})`;
+  const timed = /^(timestamptz|timestamp|timetz|time)(\(\d+\))?$/.exec(typeName);
+  if (timed === null)
+    return typeName;
+  const name = timed[1];
+  const precision = timed[2] ?? "";
+  if (name === "timestamptz")
+    return `timestamp${precision} with time zone`;
+  if (name === "timestamp")
+    return `timestamp${precision} without time zone`;
+  if (name === "timetz")
+    return `time${precision} with time zone`;
+  return `time${precision} without time zone`;
 }
 // src/dialects/pg/namespace.ts
 var t = {