okmodel 0.7.0 → 0.9.0

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

@@ -6,6 +6,50 @@
  * object for its records.
  */
 import type { ExtensionObject } from "../../../contracts/catalog/types.js";
+/** One type the definition says the extension provides. */
+export type ExtensionType = {
+    readonly name: string;
+};
+/** One operator the definition says the extension provides. */
+export type ExtensionOperator = {
+    readonly name: string;
+    readonly left?: string;
+    readonly right?: string;
+    readonly result: string;
+};
+/** One function the definition says the extension provides. */
+export type ExtensionFunction = {
+    readonly name: string;
+    readonly args: readonly string[];
+    readonly returns: string;
+};
+/** One index method the definition says the extension provides. */
+export type ExtensionIndexMethod = {
+    readonly name: string;
+    readonly opclass?: string;
+};
+/**
+ * Types, operators, functions, and index methods a definition declares.
+ *
+ * `okm ext test` checks these against the connected server. They are not
+ * catalog objects and they do not change the catalog hash.
+ */
+export type ExtensionProvides = {
+    readonly types?: readonly ExtensionType[];
+    readonly operators?: readonly ExtensionOperator[];
+    readonly functions?: readonly ExtensionFunction[];
+    readonly indexMethods?: readonly ExtensionIndexMethod[];
+};
+/**
+ * Version floors for a definition.
+ *
+ * `postgres` is `>=15`. `version` is an exact pin or a `>=` floor.
+ * `okm ext test` checks both against the connected server (OKM1812).
+ */
+export type ExtensionRequires = {
+    readonly postgres?: string;
+    readonly version?: string;
+};
 /** Options on {@link extension}. */
 export type ExtensionOptions = {
     /** Exact pin (`1.6`) or a floor (`>=0.7`). Omitted means unpinned. */
@@ -18,6 +62,14 @@ export type ExtensionOptions = {
      * The default is `true`. A move of a non-relocatable extension is OKM1814.
      */
     readonly relocatable?: boolean;
+    /**
+     * Floors `okm ext test` checks. Not stored in the catalog record.
+     */
+    readonly requires?: ExtensionRequires;
+    /**
+     * Objects `okm ext test` checks. Not stored in the catalog record.
+     */
+    readonly provides?: ExtensionProvides;
 };
 /**
  * One declared extension.
@@ -30,6 +82,10 @@ export type Extension = {
     readonly schema: string;
     readonly relocatable: boolean;
     readonly version?: string;
+    /** Floors from {@link ExtensionOptions.requires}. Absent when omitted. */
+    readonly requires?: ExtensionRequires;
+    /** Objects from {@link ExtensionOptions.provides}. Absent when omitted. */
+    readonly provides?: ExtensionProvides;
     /**
      * Catalog records for this declaration.
      *

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * The `ltree` extension. `ancestorOf` is `@>` and `descendantOf` is `<@`. This is not the parent-column walk.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { Fragment } from "../ops/fragment.js";
+import type { IndexCall } from "../table.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `ltree` plus the methods the naming overlay selected. */
+export type Ltree = Extension & {
+    /**
+     * `column @> path`. The column is an ancestor of `path`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    ancestorOf(value: string): Fragment;
+    /**
+     * `column <@ path`. The column is a descendant of `path`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    descendantOf(value: string): Fragment;
+    /**
+     * A GiST index with `gist_ltree_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gist(column: string): IndexCall;
+};
+/**
+ * Declares `ltree`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function ltree(options?: ExtensionOptions): Ltree;

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

@@ -0,0 +1,29 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  opArg
+} from "../../../shared/xqacq37x.js";
+import {
+  usingIndex
+} from "../../../shared/h9811jjm.js";
+
+// src/dialects/pg/ext/ltree.ts
+function ltree(options = {}) {
+  const declared = extension2("ltree", options);
+  return {
+    ...declared,
+    ancestorOf(value) {
+      return opArg("@>", value, "ltree");
+    },
+    descendantOf(value) {
+      return opArg("<@", value, "ltree");
+    },
+    gist(column) {
+      return usingIndex(column, "gist", "gist_ltree_ops");
+    }
+  };
+}
+export {
+  ltree
+};

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

@@ -1,6 +1,9 @@
 import {
   extension2
-} from "../../../shared/jgqj11w4.js";
+} from "../../../shared/6f0z3hzh.js";
+import {
+  usingIndex
+} from "../../../shared/h9811jjm.js";
 import {
   tag
 } from "../../../shared/cn0n68ft.js";
@@ -25,18 +28,6 @@ function pgTrgm(options = {}) {
     }
   };
 }
-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/ext/pgcrypto.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `pgcrypto` extension. `digest` compares a hex digest. `fipsMode` needs version 1.4 and PostgreSQL 18.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { Fragment } from "../ops/fragment.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `pgcrypto` plus the methods the naming overlay selected. */
+export type Pgcrypto = Extension & {
+    /**
+     * `encode(digest(column, algorithm), 'hex') = hex`.
+     *
+     * @param algorithm - Digest algorithm, such as `sha256`
+     * @param hex - Expected hex digest
+     * @returns A where fragment
+     */
+    digest(algorithm: string, hex: string): Fragment;
+    /**
+     * `fips_mode()` is true or false on the column's row. Needs pgcrypto 1.4 and PostgreSQL 18.
+     *
+     * @returns A where fragment
+     */
+    fipsMode(): Fragment;
+};
+/**
+ * Declares `pgcrypto`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function pgcrypto(options?: ExtensionOptions): Pgcrypto;

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

@@ -0,0 +1,33 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  assertExtFeature
+} from "../../../shared/kzgrnckd.js";
+import {
+  bareCall,
+  digestEquals
+} from "../../../shared/xqacq37x.js";
+
+// src/dialects/pg/ext/pgcrypto.ts
+function pgcrypto(options = {}) {
+  const declared = extension2("pgcrypto", options);
+  const schema = declared.schema;
+  return {
+    ...declared,
+    digest(algorithm, hex) {
+      return digestEquals(schema, algorithm, hex);
+    },
+    fipsMode() {
+      assertExtFeature(options.version, "fips_mode", {
+        name: "pgcrypto",
+        extension: "1.4",
+        postgres: 18
+      });
+      return bareCall(schema, "fips_mode");
+    }
+  };
+}
+export {
+  pgcrypto
+};

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

@@ -0,0 +1,26 @@
+/**
+ * The `unaccent` extension. `unaccent` folds accents on a text column.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { Fragment } from "../ops/fragment.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `unaccent` plus the methods the naming overlay selected. */
+export type Unaccent = Extension & {
+    /**
+     * `unaccent(column) = unaccent(value)`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    unaccent(value: string): Fragment;
+};
+/**
+ * Declares `unaccent`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function unaccent(options?: ExtensionOptions): Unaccent;

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

@@ -0,0 +1,21 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  fnEqualsArg
+} from "../../../shared/xqacq37x.js";
+
+// src/dialects/pg/ext/unaccent.ts
+function unaccent(options = {}) {
+  const declared = extension2("unaccent", options);
+  const schema = declared.schema;
+  return {
+    ...declared,
+    unaccent(value) {
+      return fnEqualsArg(schema, "unaccent", value);
+    }
+  };
+}
+export {
+  unaccent
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Index tails for extension operator classes.
+ *
+ * The catalog index stores `using …`. The core index factory does not grow a
+ * `using` field. `pg_trgm` and the generated packs share this helper.
+ */
+import type { IndexCall } from "../table.js";
+/**
+ * Quotes one identifier the extension wrote, not a caller string from SQL.
+ *
+ * @param name - Identifier
+ * @returns A double-quoted identifier
+ */
+export declare function quotedIdent(name: string): string;
+/**
+ * An index call whose expression is a `using` tail.
+ *
+ * @param column - SQL column name
+ * @param method - Index method, such as `gin` or `gist`
+ * @param opclass - Operator class, such as `gin_trgm_ops`
+ * @returns The index call
+ */
+export declare function usingIndex(column: string, method: string, opclass: string): IndexCall;

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

@@ -0,0 +1,36 @@
+/**
+ * Default versions and drift signatures for the generated packs.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * Versions are the control-file default on each supported major.
+ */
+/** One object the drift check requires on the connected server. */
+export type ExtSignature = {
+    readonly kind: "function";
+    readonly name: string;
+    readonly args: string;
+} | {
+    readonly kind: "operator";
+    readonly name: string;
+    readonly left: string;
+    readonly right: string;
+} | {
+    readonly kind: "opclass";
+    readonly name: string;
+    readonly method: string;
+};
+/** One generated pack's versions and the objects the drift check names. */
+export type ExtPackRecord = {
+    readonly name: string;
+    readonly versions: {
+        readonly 15: string;
+        readonly 16: string;
+        readonly 17: string;
+        readonly 18: string;
+    };
+    /** Oldest major the base methods exist on. */
+    readonly minPostgres: 15;
+    readonly signatures: readonly ExtSignature[];
+};
+/** Packs this version generates. `vector` is not in the list (D281). */
+export declare const EXT_PACKS: readonly ExtPackRecord[];

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

@@ -0,0 +1,19 @@
+/**
+ * A table owned by another catalog.
+ *
+ * The mark is the same one `withOwner(..., "external")` stores. `schema()`
+ * does not read it. Tooling stamps the catalog and, when `defineConfig`
+ * names a snapshot, keeps this table's namespace and name from that file.
+ */
+import type { AnyTable } from "./table.js";
+/**
+ * Turns a table exported by another catalog into an external definition.
+ *
+ * The table object is the same value: its name and columns stay. SQL for a
+ * managed foreign key is schema-qualified. A plan never creates, alters, or
+ * drops this table. `okm check` verifies it against the snapshot.
+ *
+ * @param table - A `table()` value declared by the owning catalog
+ * @returns The same table, marked external
+ */
+export declare function external<T extends AnyTable>(table: T): T;

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

@@ -5,12 +5,46 @@
  * 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 FragmentIdent } from "../ops/fragment.js";
+import { type Eq } from "../operators.js";
+import type { Window } from "../ops/window.js";
 import type { AnyTable, SqlText } from "../table.js";
 /** One argument of {@link fn}. */
 export type FunctionArgumentInput = {
     readonly name: string;
     readonly type: string;
 };
+/** Postgres types that bind as a number. Anything else binds as text. */
+type NumericReturn = "smallint" | "integer" | "bigint" | "int2" | "int4" | "int8" | "real" | "double precision" | "float4" | "float8" | "numeric";
+/** A select name for {@link FnCall.as}. Numeric returns are numbers. Text stays text. */
+type CallAs<R extends string, A extends string> = R extends NumericReturn | `numeric${string}` ? Window<A, number> : Window<A, string>;
+/**
+ * A typed call.
+ *
+ * It is a `sql` fragment, so `where` accepts it as {@link Eq}. `.as(name)` is
+ * the `select` form. `orderBy` does not: adding the call to that union is one
+ * composite type over the ceiling.
+ *
+ * @typeParam R - Declared return type
+ */
+export type FnCall<R extends string = string> = Eq<never> & {
+    /**
+     * Names the select result.
+     *
+     * @typeParam A - Result key
+     * @param name - Result key. Not a column name
+     * @returns A select entry
+     */
+    as<const A extends string>(name: A): CallAs<R, A>;
+};
+/** One argument value. `ident` names a field. Null is SQL null. */
+type CallValue<T extends string> = T extends "boolean" | "bool" ? boolean | FragmentIdent | null : T extends NumericReturn | `numeric${string}` ? number | FragmentIdent | null : string | FragmentIdent | null;
+/** Argument list of a call, in declaration order. */
+type CallArgs<A extends readonly FunctionArgumentInput[]> = {
+    [I in keyof A]: A[I] extends FunctionArgumentInput ? CallValue<A[I]["type"]> : never;
+};
+/** `fn.slugify(col)`. The value is {@link FnCall}. */
+type FnCaller<A extends readonly FunctionArgumentInput[], R extends string> = (...args: CallArgs<A>) => FnCall<R>;
 /**
  * A table, or one column of a table.
  *
@@ -96,7 +130,10 @@ export type TriggerDeclaration = {
  * @param options - Signature, language, body, and dependencies
  * @returns The definition object `schema({ functions })` stores
  */
-export declare function fn(name: string, options: FunctionOptions): Routine;
+export declare function fn<const A extends readonly FunctionArgumentInput[] = readonly [], const R extends string = string>(name: string, options: FunctionOptions & {
+    readonly arguments?: A;
+    readonly returns: R;
+}): Routine & FnCaller<A, R>;
 /**
  * Declares a trigger.
  *
@@ -105,3 +142,4 @@ export declare function fn(name: string, options: FunctionOptions): Routine;
  * @returns The definition object `schema({ triggers })` stores
  */
 export declare function trigger(name: string, options: TriggerOptions): TriggerDeclaration;
+export {};

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

@@ -1,10 +1,23 @@
 import {
   functionObject,
   triggerObject
-} from "../../../shared/y34a8714.js";
+} from "../../../shared/12z7aznj.js";
+import {
+  quoteIdent2
+} from "../../../shared/fk9vef30.js";
+import {
+  isFragmentParts,
+  sqlExpression,
+  identName
+} from "../../../shared/bsek72fg.js";
 import {
   staticNamespace2
 } from "../../../shared/358zsv4r.js";
+import {
+  isOperator,
+  operatorName,
+  operatorValue
+} from "../../../shared/cn0n68ft.js";
 import {
   assertIdentifier2
 } from "../../../shared/nfzc5z0w.js";
@@ -36,32 +49,111 @@ function fn(name, options) {
   }
   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)
-        })
-      ];
-    }
+  const declared = options.arguments ?? [];
+  const 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)
+      })
+    ];
   };
+  const call = (...args) => invoke(schema, name, declared, options.returns, args);
+  define(call, "name", name);
+  define(call, "schema", schema);
+  define(call, "argTypes", argTypes);
+  define(call, "contribute", contribute);
+  return call;
+}
+function define(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true
+  });
+}
+var NUMERIC_RETURNS = new Set([
+  "smallint",
+  "integer",
+  "bigint",
+  "int2",
+  "int4",
+  "int8",
+  "real",
+  "double precision",
+  "float4",
+  "float8",
+  "numeric"
+]);
+function invoke(schemaName, name, declared, returns, args) {
+  if (args.length !== declared.length) {
+    throw new OkmError2("OKM1120", `Function ${name} expects ${String(declared.length)} arguments.`, { fix: { summary: "Pass one value for each declared argument, in order." } });
+  }
+  const parts = [{ k: "t", s: `${quoteIdent2(schemaName)}.${quoteIdent2(name)}(` }];
+  for (let index = 0;index < args.length; index += 1) {
+    if (index > 0)
+      parts.push({ k: "t", s: ", " });
+    appendArg(parts, args[index], name);
+  }
+  parts.push({ k: "t", s: ")" });
+  const textual = !(NUMERIC_RETURNS.has(returns) || returns.startsWith("numeric("));
+  return sqlExpression(parts, textual);
+}
+function appendArg(parts, value, name) {
+  if (value === null) {
+    parts.push({ k: "n" });
+    return;
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    parts.push({ k: "p", v: String(value) });
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new OkmError2("OKM1120", `Function ${name} needs a finite number.`, {
+        fix: { summary: "Pass a finite number, or leave it out." }
+      });
+    }
+    parts.push({ k: "p", v: String(value) });
+    return;
+  }
+  const field = identName(value);
+  if (field !== undefined) {
+    parts.push({ k: "i", n: field });
+    return;
+  }
+  if (isOperator(value) && operatorName(value) === "sql") {
+    const stored = operatorValue(value);
+    if (isFragmentParts(stored)) {
+      parts.push({ k: "f", parts: stored });
+      return;
+    }
+  }
+  if (isHandle(value)) {
+    assertIdentifier2(value.name, `function ${name}`);
+    parts.push({ k: "i", n: value.name });
+    return;
+  }
+  throw new OkmError2("OKM1121", `Function ${name} received a value it cannot bind.`, {
+    fix: { summary: "Pass a string, number, boolean, null, or ident(field)." }
+  });
+}
+function isHandle(value) {
+  return typeof value === "object" && value !== null && "name" in value && typeof value.name === "string" && value.name.length > 0 && !isOperator(value);
 }
 function trigger(name, options) {
   return {

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

@@ -7,6 +7,7 @@
 export { type PostgresMajor } from "./floor.js";
 export { schema, type BuiltSchema, type SchemaCodecs, type SchemaInput, type SchemaRequires, } from "./schema.js";
 export { withOwner, type DeclaredOwner } from "./owner.js";
+export { external } from "./external.js";
 export { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type FilterOperator, type Table, type TableOptions, } from "./table.js";
 export type { PresetQuery } from "./preset.js";
 export { custom } from "./custom.js";
@@ -57,4 +58,6 @@ export { or } from "./ops/or.js";
 export { overlaps } from "./ops/overlaps.js";
 export { path } from "./ops/path.js";
 export { startsWith } from "./ops/startsWith.js";
+export { fragment, ident, type Fragment } from "./ops/fragment.js";
+export { explain, raw, type ExplainResult } from "./ops/lane.js";
 export { many, manyThrough, morph, morphMany, morphTo, one, type ManyRelation, type ManyThroughRelation, type MorphManyRelation, type MorphRelation, type OneRelation, type RelationCall, } from "./relations.js";