okmodel 0.6.0 → 0.8.0

package/dist/contracts/connection.d.ts

@@ -24,8 +24,10 @@ export declare function isConnectionErrno(code: string): boolean;
 /**
  * Reports whether `error` is a dropped or refused connection.
  *
- * Constraint failures are not connection failures. `23505` stays a unique
- * violation even when it is raised at commit.
+ * The decision is a driver `code` ({@link isConnectionErrno}, including
+ * `CONNECT_TIMEOUT`, or `ERR_POSTGRES_CONNECTION_CLOSED`) or a SQLSTATE in
+ * class `08` or `57P01`–`57P03`. A server SQLSTATE outside that set is never
+ * a lost connection. Message text is not read.
  *
  * @param error - Caught value
  * @returns `true` when no session remains
@@ -35,10 +37,9 @@ export declare function isConnectionFailure(error: unknown): boolean;
  * Reports whether the connection is gone after `error`, or the outcome of a
  * statement on it is unknown (`outcome_unknown`).
  *
- * It reads what {@link isConnectionFailure} reads, plus the messages node-postgres
- * ("Connection terminated unexpectedly") and Bun.sql (`ERR_POSTGRES_CONNECTION_CLOSED`)
- * give, and the error's `cause`. Nothing more should be sent to such a connection:
- * not a rollback, not a reset. Loaded with the code that reserves a connection.
+ * It reads what {@link isConnectionFailure} reads, and the error's `cause`.
+ * Nothing more should be sent to such a connection: not a rollback, not a
+ * reset. Loaded with the code that reserves a connection.
  *
  * @param error - Caught value
  * @returns `true` when the session cannot be used again

package/dist/contracts/error.d.ts

@@ -31,7 +31,7 @@ export type ColumnCode = (typeof COLUMN_CODES)[number];
  * These are spec §21 codes. They are a type only, so the runtime entry does
  * not gain a second registry.
  */
-export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
+export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1125" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
 /** Kinds from spec §14, in category order. */
 export declare const ERROR_KINDS: readonly ["invalid", "not_null", "check", "foreign_key", "unique", "exclusion", "conflict", "not_found", "not_unique", "forbidden", "serialization", "deadlock", "lock_timeout", "timeout", "cancelled", "unavailable", "schema_drift", "driver", "read_only", "outcome_unknown"];
 /** One spec §14 kind. */

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

@@ -0,0 +1,68 @@
+/**
+ * Postgres majors a schema may name, and the features that read them.
+ *
+ * 15–18 are the majors okmodel runs. A major outside that range is refused
+ * when `schema()` runs. Messages read these numbers. They do not repeat them.
+ */
+/** Majors `minPostgres` and `requires.postgres` accept, oldest first. */
+export declare const POSTGRES_MAJORS: readonly [15, 16, 17, 18];
+/** A major {@link POSTGRES_MAJORS} allows. */
+export type PostgresMajor = (typeof POSTGRES_MAJORS)[number];
+/**
+ * Oldest major connect accepts when the schema names no floor.
+ *
+ * A server below this is OKM1803.
+ */
+export declare const POSTGRES_FLOOR = 15;
+/**
+ * `uuidv7()` database default.
+ *
+ * Add the next feature constant beside this one, and name it on the minPostgres page.
+ */
+export declare const UUIDV7_POSTGRES = 18;
+/**
+ * Accepts a major from {@link POSTGRES_MAJORS}.
+ *
+ * @param value - Candidate from schema input
+ * @returns Whether `value` is 15, 16, 17, or 18
+ */
+export declare function isPostgresMajor(value: unknown): value is PostgresMajor;
+/**
+ * Reads a stored `>=N` floor.
+ *
+ * `readFloor`, `refuseUuidV7`, and `acceptServer` share this parse.
+ *
+ * @param postgres - Stored or input range
+ * @returns The major, or `NaN` when the text is not `>=` plus digits
+ */
+export declare function parsePostgresFloor(postgres: string | undefined): number;
+/**
+ * Stores a major as `>=N`.
+ *
+ * @param major - Allowed major
+ * @returns The stored floor text
+ */
+export declare function formatPostgresFloor(major: number): string;
+/**
+ * Definition error for a floor outside 15–18.
+ *
+ * @returns OKM1060 message
+ */
+export declare function minPostgresDefinition(): string;
+/**
+ * Sentence for a `uuidv7()` default the declared floor does not allow.
+ *
+ * @returns The OKM1812 message
+ */
+export declare function uuidv7NeedsPostgres(): string;
+/**
+ * Connect refusal when the server is below the schema floor.
+ *
+ * OKM1802 and OKM1803 share this sentence. OKM1803 passes {@link POSTGRES_FLOOR}.
+ * Loaded with the connect check, not with `schema()`.
+ *
+ * @param server - Major the server reported
+ * @param need - Major the schema requires
+ * @returns The message
+ */
+export declare function serverNeedsPostgres(server: number, need: number): string;

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 {
+  isFragmentParts,
+  sqlExpression,
+  identName
+} from "../../../shared/bsek72fg.js";
+import {
+  quoteIdent
+} from "../../../shared/sjk86yrx.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: `${quoteIdent(schemaName)}.${quoteIdent(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

@@ -4,6 +4,7 @@
  * Column types, codecs, picklists, `table()`, and `schema()`.
  * Each builder is a separate export so a bundle can keep only the ones it calls.
  */
+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 { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type FilterOperator, type Table, type TableOptions, } from "./table.js";
@@ -27,6 +28,8 @@ export { domain, enumColumn as enum } from "./enum.js";
 export { t } from "./namespace.js";
 export * as arr from "./ops/arr-ns.js";
 export * as json from "./ops/json-ns.js";
+export { bucket, type Bucket, type BucketUnit, type WeekStart } from "./ops/bucket.js";
+export { denseRank, rank, rowNumber, runningTotal, type Window, type WindowOrder, } from "./ops/window.js";
 export { between } from "./ops/between.js";
 export { containedBy } from "./ops/containedBy.js";
 export { contains } from "./ops/contains.js";
@@ -43,6 +46,8 @@ export { ilike } from "./ops/ilike.js";
 export { inList } from "./ops/inList.js";
 export { like } from "./ops/like.js";
 export { matches } from "./ops/matches.js";
+export { relevance } from "./ops/relevance.js";
+export type { SearchMatch } from "./operators.js";
 export { lt } from "./ops/lt.js";
 export { lte } from "./ops/lte.js";
 export { none } from "./ops/none.js";
@@ -52,4 +57,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 { many, manyThrough, one, type ManyRelation, type ManyThroughRelation, type OneRelation, type RelationCall, } from "./relations.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";