okmodel 0.5.1 → 0.7.0

package/dist/runtime/tenancy/path.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Path tenancy.
+ *
+ * A table with `tenancy: via("project.organization")` has no tenant column.
+ * Reads and writes add `EXISTS` along that relation path. An insert checks the
+ * parent in the same statement. The featureless app does not import this file.
+ */
+import { type AnyTable } from "../../dialects/pg/table.js";
+import type { TenancyText, TenantCall } from "../../dialects/pg/tenancy.js";
+/** How `columnTenancy()` classified a table before the rewrite. */
+export type TableKind = "tenant" | "global" | "path";
+/** One step from a path table toward the tenant table. */
+export type PathHop = {
+    /** Table that declares this step. */
+    readonly child: string;
+    /** Table this step points at. */
+    readonly parent: string;
+    /** Foreign-key field on `child`. */
+    readonly localField: string;
+    /** Field on `parent` that the foreign key matches. */
+    readonly remoteField: string;
+    /** SQL name stored on the local column, when the builder set one. */
+    readonly localSql: string | undefined;
+    /** SQL name stored on the remote column, when the builder set one. */
+    readonly remoteSql: string | undefined;
+    /** SQL name stored on the parent table, when the table set one. */
+    readonly parentSql: string | undefined;
+    /** Encodes the local field when an update points it at a new parent. */
+    readonly encode: (value: string) => string;
+};
+/** A resolved `via` path. */
+export type PathChain = {
+    /** The `via` text, unchanged. */
+    readonly via: string;
+    /** Steps from the path table to the tenant table. At most three. */
+    readonly hops: readonly PathHop[];
+};
+/** What the column strategy asks of a resolved path. */
+export type PathPlan = {
+    /** Tenant tables a path ends on, and the declared key that must stay unique. */
+    readonly endpoints: ReadonlyMap<string, readonly string[]>;
+    /** Path table, when `name` was resolved. */
+    isPath(name: string): boolean;
+    /** Steps from `name` to the tenant table. */
+    hops(name: string): readonly PathHop[] | undefined;
+    /** Rewrites one path table: foreign key into the tenant table, and the index. */
+    adjust(item: AnyTable): AnyTable;
+    /**
+     * Writes `EXISTS` for a path table.
+     *
+     * @returns `true` when `table` is a path table and the predicate was written
+     */
+    writeExists(input: ExistsInput): boolean;
+};
+type ExistsInput = {
+    readonly table: string;
+    readonly alias: string;
+    readonly fieldSql: (field: string) => string | undefined;
+    readonly scope: TenantCall | undefined;
+    readonly sink: TenancyText;
+    readonly appended: boolean;
+    readonly lock: boolean;
+    readonly keys: readonly string[];
+    readonly encodeKey: (key: string, value: string) => string;
+    /** New parent values, keyed by the path table's foreign-key field. */
+    readonly assigned?: Readonly<Record<string, string>>;
+};
+/**
+ * Resolves every `via()` table.
+ *
+ * A path that does not end at a tenant table, a missing relation, a cycle, or
+ * more than three hops is OKM1705. The caller rewrites tenant tables after this
+ * and adds a unique on each endpoint's declared key.
+ *
+ * @param tables - Tables passed to `schema()`
+ * @param kind - Classification, including `"path"`
+ * @returns The plan the predicate and the rewrite share
+ */
+export declare function compilePaths(tables: readonly AnyTable[], kind: ReadonlyMap<string, TableKind>): PathPlan;
+/**
+ * Declared primary key, before tenancy adds its columns.
+ *
+ * @param item - Table as passed to `schema()`
+ * @returns Field names, in declaration order
+ */
+export declare function declaredPrimary(item: AnyTable): readonly string[];
+export {};

package/dist/runtime/tenancy/rls.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Row-level security tenancy (`rlsTenancy()`).
+ *
+ * The column predicate stays on every statement. Policies are the backstop.
+ * A column-only import does not load this file.
+ */
+import { OkmError } from "../../contracts/error.js";
+import type { DriverConnection, ExecuteOptions, ExecuteResult, Statement, WireValue } from "../../contracts/driver.js";
+import type { ColumnTenancy } from "../../dialects/pg/tenancy.js";
+/** Why {@link RlsRoleError} refused the role. */
+export type RlsRoleReason = "owner" | "superuser" | "bypassrls";
+/**
+ * OKM1707. The role would not be subject to the policies.
+ *
+ * `reason` says which check failed. Superuser wins over `BYPASSRLS`, which
+ * wins over table owner.
+ */
+export declare class RlsRoleError extends OkmError {
+    readonly reason: RlsRoleReason;
+    /**
+     * @param reason - Which privilege bypassed row-level security
+     * @param endpoint - Endpoint that answered the check. The message names it
+     */
+    constructor(reason: RlsRoleReason, endpoint?: string);
+}
+/**
+ * Row-level security for `schema({ tenancy })`.
+ *
+ * One uuid key. The column predicate matches `columnTenancy`. Policies,
+ * `set_config`, and the role check load with this import. Combining it with
+ * `via()` or `compositeTenancy()` is a definition error.
+ *
+ * @typeParam Key - Field name of the tenant key
+ * @param input - Field name and `uuid`
+ * @returns The object `schema()` applies
+ */
+export declare function rlsTenancy<const Key>(input: {
+    readonly key: Key extends readonly unknown[] ? "rlsTenancy() takes one key. Combining it with compositeTenancy or via() is not supported yet." : Key extends string ? Key : "rlsTenancy() key must be a field name.";
+    readonly type: "uuid";
+}): ColumnTenancy & {
+    readonly key: Key extends string ? Key : string;
+};
+/**
+ * Runs one statement inside `BEGIN READ ONLY` after the tenant setting.
+ *
+ * The caller releases the connection. A failure rolls the transaction back.
+ *
+ * @param conn - Reserved connection
+ * @param text - User statement
+ * @param params - Wire parameters
+ * @param prelude - `set_config` statement
+ * @param options - Deadline and cancellation, without a route hint
+ * @returns The user statement's result
+ */
+export declare function runReadOnly(conn: DriverConnection, text: string, params: readonly WireValue[] | undefined, prelude: Statement, options: ExecuteOptions | undefined): Promise<ExecuteResult>;
+/**
+ * Streams one query inside `BEGIN READ ONLY` after the tenant setting.
+ *
+ * Rows come back in chunks of 64. The caller releases the connection.
+ *
+ * @param conn - Reserved connection
+ * @param text - User query
+ * @param params - Wire parameters
+ * @param prelude - `set_config` statement
+ * @returns Row chunks
+ */
+export declare function streamHeld(conn: DriverConnection, text: string, params: readonly WireValue[] | undefined, prelude: Statement): AsyncGenerator<readonly (readonly WireValue[])[]>;

package/dist/runtime/tenancy/via.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Path tenancy (`via()`).
+ *
+ * A table passes `tenancy: via("project.organization")`. This file owns the
+ * path compiler. A column-only app does not import it.
+ */
+import type { AnyTable } from "../../dialects/pg/table.js";
+import type { TableRewriteContext } from "./context.js";
+/**
+ * Isolates a table through relations instead of a tenant column.
+ *
+ * The path is at most three to-one steps and must end at a tenant table.
+ * `schema()` resolves it while it rewrites. A bad path is OKM1705.
+ *
+ * @typeParam Path - Relation path, such as `"project.organization"`
+ * @param path - Steps from this table to the tenant table, separated by `.`
+ * @returns The marker `table({ tenancy })` stores
+ */
+export declare function via<const Path extends string>(path: Path): {
+    readonly via: Path;
+    rewrite(table: AnyTable, ctx: TableRewriteContext): AnyTable;
+};

package/dist/runtime/text-search.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `search` on `find` and `count`.
+ *
+ * Loaded on the first call that passes `search`. It rewrites the call into
+ * `matches` and, when `find` has no `orderBy`, `relevance` plus the primary
+ * key. The SQL compiler is the one those helpers already use.
+ */
+import type { QuerySchema } from "../dialects/pg/model.js";
+import { type ReadCall } from "./plan.js";
+/**
+ * Rewrites `search` into `matches` and `relevance`.
+ *
+ * `count` keeps the caller's order, which it does not emit. An explicit
+ * `orderBy` on `find` replaces the automatic ranking.
+ *
+ * @param schema - Connected schema
+ * @param call - The read, with `search` set
+ * @returns The same read, without `search`
+ */
+export declare function applyTextSearch(schema: QuerySchema, call: ReadCall): ReadCall;

package/dist/runtime/traits/index.d.ts

@@ -5,6 +5,7 @@
  * does not import it does not load these columns.
  */
 import { type PresetMap } from "../../dialects/pg/preset.js";
+import type { QuerySchema, SchemaHookCtx } from "../../dialects/pg/model.js";
 import type { AnyTable, RowFrom } from "../../dialects/pg/table.js";
 import { attachArchive } from "../archive-handle.js";
 import { type Trait, type TraitContext, type TraitModel } from "../../dialects/pg/trait.js";
@@ -131,3 +132,82 @@ export declare function archivable(options?: ArchivableOptions): {
     rewrite(tables: readonly AnyTable[], casing: "snake" | undefined, schemaTraits: readonly object[] | undefined): readonly AnyTable[];
     hook: typeof attachArchive;
 };
+/**
+ * Adds `version` and checks it on every update.
+ *
+ * The column starts at 1. An update passes the version it read and the write
+ * bumps it. A stale version is category `conflict` and changes nothing.
+ * Input cannot set `version`.
+ *
+ * @returns The versioned trait
+ */
+export declare function versioned(): {
+    readonly name: string;
+    readonly fields: {
+        readonly version: import("../../dialects/pg/column.js").ColumnBuilder<number, import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").PlainFlags, "hasDefault">, "guarded">>;
+    };
+    readonly touch?: readonly "version"[];
+    readonly sealed?: readonly "version"[];
+    apply(model: TraitModel, ctx: TraitContext): void;
+    contribute(peers: unknown, built: unknown): readonly unknown[];
+};
+/**
+ * Adds `position` and `move`.
+ *
+ * New rows go at the end of the group. `move` places a row before or after
+ * another in that group. `find` and `page` order by `position` when the
+ * caller does not pass `orderBy`. Input cannot set `position`.
+ *
+ * @param groupBy - Column that splits the order. Omit it for one list
+ * @returns The sortable trait
+ */
+export declare function sortable(groupBy?: string): {
+    name: string;
+    fields: {
+        readonly position: import("../../dialects/pg/column.js").ColumnBuilder<number, import("../../dialects/pg/column.js").FlagTrue<import("../../dialects/pg/column.js").PlainFlags, "guarded">>;
+    };
+    touch?: readonly "position"[];
+    sealed?: readonly "position"[];
+    contribute(peers: unknown, built: unknown): readonly unknown[];
+    group?: string;
+    "~sort": true;
+    apply(model: TraitModel, ctx: TraitContext): void;
+    /**
+     * Adds the unique position index after tenancy has widened uniques.
+     *
+     * @param tables - Tables after the tenancy rewrite
+     * @param casing - Schema casing
+     * @param schemaTraits - Traits from `schema()`, when any were passed
+     * @returns The rewritten tables
+     */
+    rewrite(tables: readonly AnyTable[], casing: "snake" | undefined, schemaTraits: readonly object[] | undefined): readonly AnyTable[];
+    hook: typeof attachSort;
+};
+/**
+ * Adds `move` and the default position order on a sortable table.
+ *
+ * @param target - The table handle being built
+ * @param ctx - Table name and the session
+ */
+declare function attachSort(target: Record<string, unknown>, ctx: SchemaHookCtx): void;
+declare module "../types.js" {
+    interface TableExtras<S extends QuerySchema, K extends keyof S["~byName"] & string> {
+        /**
+         * Moves one row before or after another in the same group.
+         *
+         * The result is the row's position after the move. A missing id is
+         * `not_found`. An anchor in another group is OKM1120.
+         *
+         * @param id - Primary key of the row to move, without the tenant key
+         * @param place - `{ before }` or `{ after }`, the anchor's primary key
+         * @returns The position after the move
+         */
+        move(id: unknown, place: {
+            readonly before: unknown;
+        } | {
+            readonly after: unknown;
+        }): Promise<{
+            readonly position: number;
+        }>;
+    }
+}

package/dist/runtime/traits/index.js

@@ -1,31 +1,35 @@
-import"../../shared/8bwbwy8h.js";
+import"../../shared/qq3899ht.js";
 import {
   checkPresetNames,
   duplicatePreset
-} from "../../shared/nsva2a6b.js";
+} from "../../shared/znm0bpp5.js";
 import {
   checkTrait
 } from "../../shared/n0dgs0pb.js";
 import {
   quoteIdent
-} from "../../shared/8xsbagad.js";
+} from "../../shared/9s0ypp87.js";
+import {
+  pathEndpoint
+} from "../../shared/rhs3xe4k.js";
 import {
   functionObject,
   triggerObject
-} from "../../shared/9x25fxhc.js";
+} from "../../shared/y34a8714.js";
 import {
+  integer2,
   timestamptz2
-} from "../../shared/1g0drakv.js";
+} from "../../shared/vqrjpcqn.js";
 import {
   uuid2
-} from "../../shared/dyj86cmj.js";
+} from "../../shared/hyh73qk6.js";
 import {
   snakeCase
-} from "../../shared/ntneex2a.js";
+} from "../../shared/rpycarcr.js";
 import {
   ColumnBuilder2,
   retarget
-} from "../../shared/c9z5g0fm.js";
+} from "../../shared/ywr8hmey.js";
 import {
   definition,
   unavailable
@@ -33,15 +37,17 @@ import {
 import {
   staticNamespace2,
   compareText
-} from "../../shared/t4tbsy9h.js";
+} from "../../shared/358zsv4r.js";
 import {
   queryHandle,
   attachHttp,
   settleCall
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/tbrvgw6z.js";
 import {
-  installArchiveInspect
-} from "../../shared/gbtcc2d7.js";
+  installArchiveInspect,
+  indexes,
+  isRecord
+} from "../../shared/67txcrcw.js";
 import {
   fitIdentifier2
 } from "../../shared/nfzc5z0w.js";
@@ -66,6 +72,9 @@ function rewriteArchivable(self, tables, casing, schemaTraits, cascade) {
   });
 }
 function rewriteOne(item, cascade, byName, accepted, edges, casing, schemaTraits, archiveSql, idSql, predicate) {
+  if (Object.hasOwn(item, pathEndpoint)) {
+    throw new OkmError2("OKM1705", `Table ${item.name} is the end of a path and cannot be archivable().`, { fix: { summary: `Leave ${item.name} out of archivable().` } });
+  }
   const links = childLinks(item, cascade, byName, accepted, edges, casing, schemaTraits, archiveSql, idSql);
   const parents = parentLinks(item, byName, edges, casing, schemaTraits, archiveSql, idSql);
   const primary = primaryFields(item);
@@ -459,13 +468,13 @@ function refuse(host, table) {
 }
 var archiveMod;
 function loadArchive() {
-  archiveMod ??= import("../../shared/0t22wwh1.js");
+  archiveMod ??= import("../../shared/bm22fvzr.js");
   return archiveMod;
 }
 async function settle(host, table, mods) {
   if (mods.uses === undefined)
     return mods;
-  const { resolve } = await import("../../shared/r6nwkxnt.js");
+  const { resolve } = await import("../../shared/m7n9h2a5.js");
   return { ...mods, presets: resolve(host.schema, table, mods.uses).wheres };
 }
 async function run(host, op, table, input, options, mods) {
@@ -478,6 +487,93 @@ async function run(host, op, table, input, options, mods) {
   }
 }
 
+// src/runtime/sort-bind.ts
+function rewriteSortable(self, tables, casing, schemaTraits, group) {
+  return tables.map((item) => {
+    if (!applies2(self, item, schemaTraits))
+      return item;
+    refusePath(item);
+    return withIndex(item, casing, schemaTraits, group);
+  });
+}
+function applies2(self, item, schemaTraits) {
+  const options = item.options;
+  const own = Array.isArray(options?.traits) ? options.traits : [];
+  if (own.includes(self))
+    return true;
+  if (options?.omitDefaults !== undefined)
+    return false;
+  return schemaTraits?.includes(self) ?? false;
+}
+function refusePath(item) {
+  const tenancy = item.options?.tenancy;
+  if (typeof tenancy === "object" && tenancy !== null && "via" in tenancy) {
+    definition(`sortable() on ${item.name} does not combine with via(). Position needs the tenant columns on the row.`);
+  }
+}
+function withIndex(item, casing, schemaTraits, group) {
+  const options = item.options;
+  const prior = options?.indexes;
+  const tenantKeys = options?.tenantKeys ?? [];
+  const fields = [];
+  for (const field of tenantKeys)
+    if (!fields.includes(field))
+      fields.push(field);
+  if (group !== undefined && !fields.includes(group))
+    fields.push(group);
+  fields.push("position");
+  const predicate = archivedPredicate(item, casing, schemaTraits);
+  const indexes = (handles) => {
+    const calls = prior === undefined ? [] : prior(handles);
+    const columns = fields.map((field) => {
+      const handle = handles[field];
+      if (handle === undefined) {
+        definition(`sortable() on ${item.name} needs a column named ${field}.`);
+      }
+      return handle.name;
+    });
+    return [...Array.isArray(calls) ? calls : [], uniqueIndex(columns, predicate)];
+  };
+  return {
+    ...item,
+    options: { ...options, indexes }
+  };
+}
+function archivedPredicate(item, casing, schemaTraits) {
+  if (!archivable(item, schemaTraits))
+    return;
+  return casing === "snake" ? "(archived_at IS NULL)" : '("archivedAt" IS NULL)';
+}
+function archivable(item, schemaTraits) {
+  const options = item.options;
+  const own = Array.isArray(options?.traits) ? options.traits : [];
+  for (const trait of own)
+    if (marked2(trait))
+      return true;
+  if (options?.omitDefaults !== undefined)
+    return false;
+  if (schemaTraits === undefined)
+    return false;
+  for (const trait of schemaTraits)
+    if (marked2(trait))
+      return true;
+  return false;
+}
+function marked2(value) {
+  return value["~archive"] === true;
+}
+function uniqueIndex(columns, predicate) {
+  const call = {
+    columns,
+    isUnique: true,
+    ...predicate !== undefined ? { predicate } : {},
+    unique() {
+      return call;
+    }
+  };
+  return call;
+}
+
 // src/runtime/traits/index.ts
 function trait(name, input) {
   if (input.presets !== undefined)
@@ -555,7 +651,7 @@ function timestamps(options) {
 function stamped() {
   return timestamptz2().defaultSql("now()").guarded();
 }
-function archivable(options) {
+function archivable2(options) {
   installArchiveContributions();
   const cascade = readCascade(options);
   const base = trait("archivable", {
@@ -579,6 +675,78 @@ function archivable(options) {
   };
   return self;
 }
+function versioned() {
+  return trait("versioned", {
+    fields: {
+      version: integer2().defaultSql("1").guarded()
+    },
+    sealed: ["version"]
+  });
+}
+function sortable(groupBy) {
+  if (groupBy !== undefined && groupBy.length === 0) {
+    definition("sortable() groupBy must be a column name.");
+  }
+  if (groupBy === "position")
+    definition("sortable() cannot group by position.");
+  const base = trait("sortable", {
+    fields: {
+      position: integer2().guarded()
+    },
+    sealed: ["position"]
+  });
+  const self = {
+    ...base,
+    ...groupBy !== undefined ? { group: groupBy } : {},
+    "~sort": true,
+    apply(model, ctx) {
+      if (groupBy !== undefined && !Object.hasOwn(model.columns, groupBy)) {
+        definition(`sortable() on ${ctx.table} needs a column named ${groupBy}.`);
+      }
+      base.apply(model, ctx);
+    },
+    rewrite(tables, casing, schemaTraits) {
+      return rewriteSortable(self, tables, casing, schemaTraits, groupBy);
+    },
+    hook: attachSort
+  };
+  return self;
+}
+function attachSort(target, ctx) {
+  const tableName = ctx.table;
+  const session = ctx.session;
+  if (tableName === undefined || session === undefined)
+    return;
+  const host = session;
+  const table = indexes(host.schema).get(tableName);
+  if (table === undefined)
+    return;
+  let sortableTable = false;
+  for (const item of table.model.traits ?? []) {
+    if (item.name === "sortable")
+      sortableTable = true;
+  }
+  if (!sortableTable)
+    return;
+  const order = { position: "asc" };
+  for (const field of table.model.primary) {
+    if (field !== "position")
+      order[field] = "asc";
+  }
+  wrapOrder(target, "find", order);
+  wrapOrder(target, "page", order);
+  const view = ctx.view;
+  target.move = (id, place) => import("../../shared/9y3mmmh1.js").then((mod) => mod.move(host, tableName, id, place, view));
+}
+function wrapOrder(target, key, order) {
+  const previous = target[key];
+  if (typeof previous !== "function")
+    return;
+  target[key] = (options = {}) => {
+    const next = isRecord(options) && options.orderBy !== undefined ? options : { ...options, orderBy: order };
+    return previous.call(target, next);
+  };
+}
 function readCascade(options) {
   if (options === undefined)
     return [];
@@ -641,7 +809,9 @@ function addFields(name, fields, model, ctx) {
   }
 }
 export {
-  archivable,
+  archivable2 as archivable,
+  sortable,
   timestamps,
-  trait
+  trait,
+  versioned
 };

package/dist/runtime/tree.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `descendants` and `ancestors` (spec §13 tool 11).
+ *
+ * One recursive statement walks a self-relation's parent column. A row already
+ * on the path is not entered again, so a cycle in the data returns. `depth`
+ * stops the walk earlier. `ltree` is not read: the extension is a later index,
+ * and this statement does not require it.
+ *
+ * Tenancy and the active set apply on the start row, on every step, and on
+ * the rows that come back. `where` and presets filter those rows and do not
+ * cut the walk short. A missing id returns no rows, including with `self`.
+ * The root has no ancestors. Loaded on the first call.
+ */
+import type { ColumnModel } from "../dialects/pg/model.js";
+import { type Mods, type Session } from "./client.js";
+import { type ArchiveView, type Indexed } from "./plan.js";
+/**
+ * Builds the handle for one `descendants` or `ancestors` call.
+ *
+ * @param session - Client session
+ * @param table - Table name
+ * @param options - The packed call: the id, the direction, and the caller's options
+ * @param mods - Presets, signal, and timeout
+ * @param view - Archive visibility
+ * @returns A handle that resolves to the walked rows
+ */
+export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined): Promise<unknown> & Record<string, unknown>;
+/**
+ * The primary key the caller passes, without the tenant key.
+ *
+ * A tree walk and `sync` both address one column. A composite key beside the
+ * tenant key is refused.
+ *
+ * @param session - Client session, for the tenant key
+ * @param table - The table
+ * @returns That column
+ */
+export declare function identityColumn(session: Session, table: Indexed): ColumnModel;