okmodel 0.6.0 → 0.7.0

package/dist/dialects/pg/index.js

@@ -1,12 +1,31 @@
+import {
+  searchValue
+} from "../../shared/dzj09cye.js";
+import {
+  rowNumber2,
+  rank2,
+  denseRank2,
+  runningTotal2
+} from "../../shared/9a4ae4p8.js";
 import {
   jsonReplacer2,
   json2,
   jsonb2
 } from "../../shared/9628a9xt.js";
+import {
+  bucket2
+} from "../../shared/nbw1z4yd.js";
 import {
   withOwner2
 } from "../../shared/xqve9598.js";
 import {
+  smallint2,
+  integer2,
+  bigint2,
+  identity2,
+  encodeBigintString,
+  decodeBigintString,
+  integerToken,
   encodeInstant,
   decodeInstant,
   encodeDate,
@@ -17,22 +36,25 @@ import {
   time2,
   timetz2,
   interval2
-} from "../../shared/5yv4k6a6.js";
+} from "../../shared/vqrjpcqn.js";
 import {
   schema2
-} from "../../shared/hazqqecq.js";
+} from "../../shared/xnxsed62.js";
 import {
   domainType
 } from "../../shared/ywspezzx.js";
 import {
   one2,
   many2,
-  manyThrough2
-} from "../../shared/k68eedmy.js";
+  manyThrough2,
+  morph2,
+  morphMany2,
+  morphTo2
+} from "../../shared/exn3sd90.js";
 import {
   id2,
   uuid2
-} from "../../shared/2jd1sn0e.js";
+} from "../../shared/hyh73qk6.js";
 import {
   text2,
   varchar2,
@@ -49,7 +71,6 @@ import {
 import {
   ColumnBuilder2,
   required,
-  openColumn,
   formatType
 } from "../../shared/ywr8hmey.js";
 import {
@@ -95,146 +116,6 @@ function custom(spec) {
     ...spec.extension !== undefined ? { extension: spec.extension } : {}
   });
 }
-// src/dialects/pg/integer.ts
-function smallint() {
-  return required({
-    baseType: "smallint",
-    encode: (value) => integerToken(value, -32768, 32767, "smallint"),
-    decode: (wire) => decodeBounded(wire, -32768, 32767, "smallint"),
-    sqlForm: "raw"
-  });
-}
-function integer() {
-  return required({
-    baseType: "integer",
-    encode: (value) => integerToken(value, -2147483648, 2147483647, "integer"),
-    decode: (wire) => decodeBounded(wire, -2147483648, 2147483647, "integer"),
-    sqlForm: "raw"
-  });
-}
-function bigint(options) {
-  const mode = options?.as ?? "string";
-  if (mode === "number") {
-    return required({
-      baseType: "bigint",
-      encode: encodeBigintNumber,
-      decode: decodeBigintNumber,
-      sqlForm: "raw",
-      typeLabel: "number"
-    });
-  }
-  if (mode === "bigint") {
-    return required({
-      baseType: "bigint",
-      encode: encodeBigintValue,
-      decode: decodeBigintValue,
-      sqlForm: "raw",
-      typeLabel: "bigint"
-    });
-  }
-  if (mode !== "string") {
-    definition(`bigint as ${String(mode)} must be string, number, or bigint.`);
-  }
-  return required({
-    baseType: "bigint",
-    encode: encodeBigintString,
-    decode: decodeBigintString,
-    sqlForm: "raw"
-  });
-}
-function identity(options) {
-  const mode = options?.as ?? "string";
-  if (mode === "number") {
-    return openColumn({
-      ...identityFlags(),
-      encode: encodeBigintNumber,
-      decode: decodeBigintNumber,
-      typeLabel: "number"
-    });
-  }
-  if (mode === "bigint") {
-    return openColumn({
-      ...identityFlags(),
-      encode: encodeBigintValue,
-      decode: decodeBigintValue,
-      typeLabel: "bigint"
-    });
-  }
-  if (mode !== "string") {
-    definition(`identity as ${String(mode)} must be string, number, or bigint.`);
-  }
-  return openColumn({
-    ...identityFlags(),
-    encode: encodeBigintString,
-    decode: decodeBigintString
-  });
-}
-function encodeBigintString(value) {
-  parseBigint(value);
-  return value;
-}
-function decodeBigintString(wire) {
-  return encodeBigintString(wire);
-}
-function encodeBigintNumber(value) {
-  if (!Number.isSafeInteger(value)) {
-    rejected(`bigint number ${String(value)} must be an integer from ${String(Number.MIN_SAFE_INTEGER)} to ${String(Number.MAX_SAFE_INTEGER)}.`);
-  }
-  return String(value);
-}
-function decodeBigintNumber(wire) {
-  const parsed = parseBigint(wire);
-  const value = Number(parsed);
-  if (!Number.isSafeInteger(value)) {
-    rejected(`bigint ${wire} must be an integer from ${String(Number.MIN_SAFE_INTEGER)} to ${String(Number.MAX_SAFE_INTEGER)} when as is number.`);
-  }
-  return value;
-}
-function encodeBigintValue(value) {
-  return value.toString();
-}
-function decodeBigintValue(wire) {
-  return parseBigint(wire);
-}
-function integerToken(value, min, max, role) {
-  if (!Number.isInteger(value) || value < min || value > max) {
-    rejected(`${role} ${String(value)} must be an integer from ${String(min)} to ${String(max)}.`);
-  }
-  return String(value);
-}
-function decodeBounded(wire, min, max, role) {
-  if (!integerText().test(wire)) {
-    rejected(`${role} ${wire} must be an integer, for example 0 or -12.`);
-  }
-  const value = Number(wire);
-  integerToken(value, min, max, role);
-  return value;
-}
-function identityFlags() {
-  return {
-    baseType: "bigint",
-    nullable: false,
-    hasDefault: true,
-    generated: false,
-    guarded: false,
-    hidden: false,
-    omitWrite: true,
-    sqlForm: "raw",
-    identity: { always: true },
-    primaryKey: true
-  };
-}
-function parseBigint(wire) {
-  if (!integerText().test(wire)) {
-    rejected(`bigint ${wire} must be an integer with no leading zeros, for example 0 or -12.`);
-  }
-  return BigInt(wire);
-}
-function integerText() {
-  integerPattern ??= /^-?(?:0|[1-9]\d*)$/;
-  return integerPattern;
-}
-var integerPattern;
 // src/dialects/pg/finite.ts
 function decimalText(value, role) {
   if (!Number.isFinite(value)) {
@@ -761,11 +642,11 @@ function canonicalScalar(typeName) {
 // src/dialects/pg/namespace.ts
 var t = {
   id: id2,
-  identity,
+  identity: identity2,
   uuid: uuid2,
-  smallint,
-  integer,
-  bigint,
+  smallint: smallint2,
+  integer: integer2,
+  bigint: bigint2,
   numeric,
   real,
   double,
@@ -887,11 +768,11 @@ function like(pattern) {
 }
 // src/dialects/pg/ops/matches.ts
 function matches(query, options) {
-  return tag("matches", {
-    query,
-    mode: options?.mode ?? "websearch",
-    config: options?.config
-  });
+  return tag("matches", searchValue(query, options));
+}
+// src/dialects/pg/ops/relevance.ts
+function relevance(query, options) {
+  return tag("relevance", searchValue(query, options));
 }
 // src/dialects/pg/ops/lt.ts
 function lt(value) {
@@ -938,8 +819,9 @@ export {
   ColumnBuilder2 as ColumnBuilder,
   exports_arr_ns as arr,
   between,
-  bigint,
+  bigint2 as bigint,
   boolean,
+  bucket2 as bucket,
   bytea,
   char2 as char,
   cidr,
@@ -949,6 +831,7 @@ export {
   custom,
   date2 as date,
   daterange,
+  denseRank2 as denseRank,
   domain,
   double,
   endsWith,
@@ -961,7 +844,7 @@ export {
   hasAnyKey,
   hasKey,
   id2 as id,
-  identity,
+  identity2 as identity,
   ilike,
   inList,
   inc,
@@ -969,7 +852,7 @@ export {
   inet,
   int4range,
   int8range,
-  integer,
+  integer2 as integer,
   interval2 as interval,
   exports_json_ns as json,
   jsonReplacer2 as jsonReplacer,
@@ -984,6 +867,9 @@ export {
   many2 as many,
   manyThrough2 as manyThrough,
   matches,
+  morph2 as morph,
+  morphMany2 as morphMany,
+  morphTo2 as morphTo,
   none,
   not,
   notIn,
@@ -994,9 +880,13 @@ export {
   overlaps,
   path,
   point,
+  rank2 as rank,
   real,
+  relevance,
+  rowNumber2 as rowNumber,
+  runningTotal2 as runningTotal,
   schema2 as schema,
-  smallint,
+  smallint2 as smallint,
   sql2 as sql,
   startsWith,
   t,

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

@@ -8,15 +8,18 @@ export type IdDefault = "uuidv7" | "uuidv4" | "none";
 /**
  * Primary key.
  *
- * With no options, the database default is `uuidv7()` unless
- * `schema({ defaults: { id } })` says otherwise. `uuidv4` stores
- * `gen_random_uuid()` (built in from Postgres 13). `none` takes the id on
- * insert. A client generator (`uuidv4`, `uuidv7`, or `okid(...)` from
- * `okmodel/ids`) is filled on insert and stored with no database default.
- * OKID is `text` with collation `C`. A database default is omitted from
- * insert and update. `none` is required on insert and omitted from update.
+ * With no options, the database default is `gen_random_uuid()` unless
+ * `schema({ defaults: { id } })` says otherwise. That function is built in
+ * from Postgres 13, so a bare call works on every supported major. `uuidv7`
+ * stores `uuidv7()` and needs Postgres 18 (`minPostgres: 18`). Pick it for a large write-heavy
+ * table: the ids are time-ordered and the index stays local. Random ids are
+ * fine elsewhere. `none` takes the id on insert. A client generator
+ * (`uuidv4`, `uuidv7`, or `okid(...)` from `okmodel/ids`) is filled on insert
+ * and stored with no database default. OKID is `text` with collation `C`. A
+ * database default is omitted from insert and update. `none` is required on
+ * insert and omitted from update.
  *
- * @param options - Which default to store. Omitted means the schema default, or `uuidv7()`
+ * @param options - Which default to store. Omitted means the schema default, or `gen_random_uuid()`
  * @returns An id column
  */
 export declare function id(): ColumnBuilder<string, IdFlags>;

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

@@ -63,6 +63,39 @@ export type ColumnModel = {
      */
     readonly accepts?: readonly string[] | undefined;
 };
+/**
+ * One table a morph include can return.
+ *
+ * `type` is the table's TypeScript name, which is what the type column stores.
+ */
+export type MorphTarget = {
+    readonly type: string;
+    readonly table: string;
+    /** SQL name of the target table. */
+    readonly sql: string;
+    /** SQL name of the target's single primary-key column. */
+    readonly keySql: string;
+};
+/**
+ * A polymorphic pair: a type column and an id column.
+ *
+ * `to` is the owner side (one of several tables). `many` is the reverse on a target.
+ * Absent on every other relation, so a normal relation does not carry it.
+ */
+export type MorphModel = {
+    readonly direction: "to" | "many";
+    /** Column stem. The fields are `${name}Type` and `${name}Id`. */
+    readonly name: string;
+    readonly typeField: string;
+    readonly idField: string;
+    /** SQL name of the type column. */
+    readonly typeSql: string;
+    /** SQL name of the id column. */
+    readonly idSql: string;
+    /** On a reverse many, the table name stored in the type column. */
+    readonly typeValue?: string;
+    readonly targets: readonly MorphTarget[];
+};
 /**
  * A resolved relation.
  *
@@ -77,6 +110,13 @@ export type RelationModel = {
     readonly local: readonly string[];
     /** SQL names on the related table. */
     readonly remote: readonly string[];
+    /**
+     * Set on a morph relation.
+     *
+     * The include planner reads `to`. A reverse many reads `many` and emits
+     * through {@link RelationModel.through}.
+     */
+    readonly morph?: MorphModel;
     /**
      * Set on a `manyThrough` relation.
      *

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

@@ -0,0 +1,43 @@
+/**
+ * Resolver and emitters of a `morph` relation.
+ *
+ * The relation object carries both. `schema()` calls the resolver, and the
+ * planner calls the emitter with its own helpers, so a schema that never
+ * calls `morph` or `morphMany` does not ship this module. A target in another
+ * tenant or archived never shows: the include planner applies those predicates
+ * to each target, the same way it does for any relation.
+ */
+import type { RelationModel } from "./model.js";
+import type { RelationScope } from "./relations.js";
+/**
+ * Resolves `morph(name, targets)` on the table that holds the type and id columns.
+ *
+ * @param scope - What `schema()` knows
+ * @param name - Column stem: `${name}Type` and `${name}Id`
+ * @param targets - Closed list of target table names
+ * @returns The resolved to-one relation
+ */
+export declare function resolveMorph(scope: RelationScope, name: string, targets: readonly string[]): RelationModel;
+/**
+ * Resolves `morphMany(table, name)` on a target table.
+ *
+ * The many reads the owner table's type and id columns. The owner must declare
+ * `morph(name, targets)` and list this table.
+ *
+ * @param scope - What `schema()` knows. `owner` is the target table
+ * @param table - Table that holds the type and id columns
+ * @param name - Column stem declared on that table
+ * @returns The resolved to-many relation
+ */
+export declare function resolveMorphMany(scope: RelationScope, table: string, name: string): RelationModel;
+/**
+ * Refuses `morphTo` when the name, type, or id is missing.
+ *
+ * `null` used to throw a TypeError on `.length`. An empty name or type stays
+ * OKM1020. A null or non-string id, or a null type, is OKM1120.
+ *
+ * @param name - Column stem
+ * @param type - Target table name
+ * @param id - That table's primary key
+ */
+export declare function assertMorphTo(name: unknown, type: unknown, id: unknown): void;

package/dist/dialects/pg/operator-fit.d.ts

@@ -58,9 +58,9 @@ export declare function assertNoControl(value: string, role: string): void;
  */
 export declare function assertBoundText(value: string, role: string): void;
 /**
- * Rejects a regconfig name that is not an identifier.
+ * Rejects a text search language that is not an identifier.
  *
- * @param config - Text search configuration
+ * @param config - Language name, such as `english`
  */
 export declare function assertRegconfig(config: string): void;
 /**

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" | "similar" | "wordSimilar" | "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" | "relevance" | "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;
@@ -38,16 +38,23 @@ export type PathValue<V> = {
 };
 /** `col #>> segments` compared with `op`. */
 export type Path<V extends string | number | boolean> = Tagged<"path", PathValue<V>>;
-/** How `matches` turns query text into a tsquery. */
-export type MatchMode = "websearch" | "plain" | "phrase";
-/** Full-text query. `config` is a regconfig name when set. */
+/**
+ * How search text is matched.
+ *
+ * `natural` is web-search style. `all-words` requires every word. `phrase`
+ * keeps the words in order. `advanced` is PostgreSQL query syntax.
+ */
+export type SearchMatch = "natural" | "all-words" | "phrase" | "advanced";
+/** Text to look for, how to match it, and the text search language when one was passed. */
 export type MatchValue = {
     readonly query: string;
-    readonly mode: MatchMode;
-    readonly config: string | undefined;
+    readonly match: SearchMatch;
+    readonly language: string | undefined;
 };
-/** `@@` against a tsvector column. */
+/** `@@` against a search column. */
 export type Matches = Tagged<"matches", MatchValue>;
+/** Order by how well a search column matches. Most relevant first. */
+export type Relevance = Tagged<"relevance", MatchValue>;
 /** Text stored on a `pg_trgm` operator. `schema` is the extension's install schema. */
 export type TrigramQuery = {
     readonly query: string;

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

@@ -0,0 +1,65 @@
+/**
+ * Time bucket for `aggregate` `groupBy` (spec §10, §13 tool 4).
+ *
+ * The brand is a symbol. JSON cannot create one, so a request cannot add a
+ * bucket. A plain object in `groupBy` stays OKM1120. The SQL loads with the
+ * first `aggregate()` whose `groupBy` contains a bucket.
+ */
+declare const brand: unique symbol;
+/** Calendar and clock units `bucket` accepts. */
+export type BucketUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+/** Week that starts on Monday (ISO), Sunday, or Saturday. */
+export type WeekStart = "monday" | "sunday" | "saturday";
+/**
+ * A `bucket()` call.
+ *
+ * `C` is the column, `U` the unit, and `A` the result key.
+ */
+export type Bucket<C extends string, U extends string, A extends string> = {
+    readonly [brand]: C;
+    readonly unit: U;
+    readonly as: A;
+};
+/** What {@link bucket} stores. The aggregate chunk reads this. */
+export type BucketInput = {
+    readonly column: unknown;
+    readonly unit: unknown;
+    readonly as: unknown;
+    readonly tz: unknown;
+    readonly weekStart: unknown;
+};
+/**
+ * Groups a timestamp or date column by a calendar or clock unit.
+ *
+ * `tz` is required for `timestamptz` and refused for `date`. `timestamp`
+ * without a zone is refused. `as` is the result key. `__proto__`, `constructor`,
+ * `toString`, and `hasOwnProperty` are refused when the aggregate runs.
+ * `weekStart` applies only
+ * to `week` and defaults to Monday. A NULL timestamp is its own group: the
+ * `as` key is present and the value is null.
+ *
+ * Day, week, month, quarter, and year come back as `Temporal.PlainDate` (the
+ * local date the period starts). Second, minute, and hour come back as
+ * `Temporal.Instant` (the period start).
+ *
+ * @typeParam C - Column name
+ * @typeParam U - Unit
+ * @typeParam A - Result key
+ * @param column - Field to bucket
+ * @param unit - Period
+ * @param options - Zone, result key, and week start
+ * @returns A tagged bucket. Pass it in `groupBy`
+ */
+export declare function bucket<const C extends string, const U extends BucketUnit, const A extends string>(column: C, unit: U, options: {
+    readonly tz?: string;
+    readonly as: A;
+    readonly weekStart?: WeekStart;
+}): Bucket<C, U, A>;
+/**
+ * Reports whether `value` is a {@link bucket} call.
+ *
+ * @param value - One `groupBy` entry
+ * @returns `true` when {@link bucket} created it
+ */
+export declare function isBucket(value: unknown): value is BucketInput;
+export {};

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

@@ -2,9 +2,9 @@ import { type Tagged } from "../operators.js";
 /** Adds to the stored number. `undefined` in `set` still leaves the field unchanged. */
 export type Inc<V> = Tagged<"inc", V>;
 /**
- * Atomic increment used in `update` `set` (spec §11).
+ * Adds to a stored number in `update` `set` (spec §11).
  *
- * JSON and array operators are not this helper.
+ * A null number stays null. JSON and array operators are not this helper.
  *
  * @typeParam V - Amount
  * @param value - Amount to add

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

@@ -1,16 +1,13 @@
-import { type MatchMode, type Matches } from "../operators.js";
+import { type Matches } from "../operators.js";
+import { type SearchOptions } from "./search-query.js";
 /**
- * Full-text match (`@@`) for a tsvector column.
+ * Full-text match for a search column.
  *
- * The default mode is `websearch_to_tsquery`, which does not throw on user
- * input. `"plain"` uses `plainto_tsquery` and `"phrase"` uses `phraseto_tsquery`.
- * A text column is not searched here.
+ * The default match is natural, which does not throw on user input. A plain
+ * text column is not searched here. `relevance` orders by the same match.
  *
- * @param query - Search text
- * @param options - Mode and regconfig name
- * @returns A tagged operator
+ * @param query - Text to look for
+ * @param options - How to match, and the text search language
+ * @returns A tagged operator for `where`
  */
-export declare function matches(query: string, options?: {
-    readonly mode?: MatchMode;
-    readonly config?: string;
-}): Matches;
+export declare function matches(query: string, options?: SearchOptions): Matches;

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

@@ -0,0 +1,13 @@
+import { type Relevance } from "../operators.js";
+import { type SearchOptions } from "./search-query.js";
+/**
+ * Orders a search column by how well it matches.
+ *
+ * Most relevant first. Pass it as an `orderBy` value. `find({ search })`
+ * compiles to `matches` plus this, so the SQL is the same.
+ *
+ * @param query - Text to look for
+ * @param options - How to match, and the text search language. Same words as `matches`
+ * @returns A tagged order
+ */
+export declare function relevance(query: string, options?: SearchOptions): Relevance;

package/dist/dialects/pg/ops/search-query.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared operand for `matches` and `relevance`.
+ *
+ * Both helpers store this shape. The SQL compiler reads it once, so `search`
+ * and the two helpers emit the same text.
+ */
+import type { MatchValue, SearchMatch } from "../operators.js";
+/** Options `matches` and `relevance` take. */
+export type SearchOptions = {
+    /** How to match. Omitted means `natural`. */
+    readonly match?: SearchMatch;
+    /** Text search language, such as `english`. Omitted uses the database default. */
+    readonly language?: string;
+};
+/**
+ * Stores the text, the match, and the language.
+ *
+ * @param query - Text to look for
+ * @param options - Match and language. Omitted means natural, database language
+ * @returns The operand both helpers tag
+ */
+export declare function searchValue(query: string, options?: SearchOptions): MatchValue;