okmodel 0.5.1 → 0.6.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/traits/index.js

@@ -1,4 +1,4 @@
-import"../../shared/8bwbwy8h.js";
+import"../../shared/qq3899ht.js";
 import {
   checkPresetNames,
   duplicatePreset
@@ -8,24 +8,27 @@ import {
 } 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 {
   timestamptz2
-} from "../../shared/1g0drakv.js";
+} from "../../shared/5yv4k6a6.js";
 import {
   uuid2
-} from "../../shared/dyj86cmj.js";
+} from "../../shared/2jd1sn0e.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 +36,15 @@ import {
 import {
   staticNamespace2,
   compareText
-} from "../../shared/t4tbsy9h.js";
+} from "../../shared/358zsv4r.js";
 import {
   queryHandle,
   attachHttp,
   settleCall
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/j60w0dvr.js";
 import {
   installArchiveInspect
-} from "../../shared/gbtcc2d7.js";
+} from "../../shared/2z7wv5tj.js";
 import {
   fitIdentifier2
 } from "../../shared/nfzc5z0w.js";
@@ -66,6 +69,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,7 +465,7 @@ function refuse(host, table) {
 }
 var archiveMod;
 function loadArchive() {
-  archiveMod ??= import("../../shared/0t22wwh1.js");
+  archiveMod ??= import("../../shared/mb2ycs1p.js");
   return archiveMod;
 }
 async function settle(host, table, mods) {

package/dist/runtime/types.d.ts

@@ -647,6 +647,16 @@ type ViewApi<Row> = {
         readonly where?: FieldWhere<Row>;
     }): Read<boolean>;
 };
+/**
+ * `refresh()` on a materialized view.
+ *
+ * No arguments. It runs `REFRESH MATERIALIZED VIEW`, with `CONCURRENTLY` when
+ * the view declares `refresh: "concurrently"`. It is a write, so it uses the
+ * primary. It is not tenant-scoped: a scoped client still refreshes the whole view.
+ */
+type MaterializedViewApi<Row> = ViewApi<Row> & {
+    refresh(): Promise<void>;
+};
 /** `db.views`, typed from `schema({ views })`. Absent when the schema declares none. */
 type ViewsClient<S> = S extends {
     readonly "~views": infer V extends readonly unknown[];
@@ -654,7 +664,9 @@ type ViewsClient<S> = S extends {
     readonly views: {
         readonly [D in V[number] as D extends {
             readonly name: infer N extends string;
-        } ? CamelName<N> : never]: ViewApi<Show<ViewRow<D>>>;
+        } ? CamelName<N> : never]: D extends {
+            readonly "~kind": "materialized";
+        } ? MaterializedViewApi<Show<ViewRow<D>>> : ViewApi<Show<ViewRow<D>>>;
     };
 } : unknown;
 /** A client whose tables are already inside one tenant or an unscoped reason. */

package/dist/runtime/validate/index.js

@@ -1,12 +1,12 @@
 import {
   validationGate
-} from "../../shared/9m80mkac.js";
+} from "../../shared/ze4hxsmy.js";
 import {
   addSchemaHook
-} from "../../shared/5enne4ma.js";
+} from "../../shared/hazqqecq.js";
 import {
   queryHandle
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/j60w0dvr.js";
 import {
   OkmError2
 } from "../../shared/52szzakm.js";
@@ -14,7 +14,7 @@ import {
 // src/runtime/validate/load.ts
 var engine;
 function loadEngine() {
-  engine ??= import("../../shared/8rsy3hxz.js");
+  engine ??= import("../../shared/h15jx9bc.js");
   return engine;
 }
 

package/dist/runtime/write.d.ts

@@ -39,7 +39,7 @@ export type PreparedWrite = {
     readonly statements: readonly Statement[];
     readonly options: ExecuteOptions | undefined;
     /** Set when `finish` can refuse a statement that already ran. `batch` refuses such a write (D183). */
-    readonly checked?: "restore" | "expect";
+    readonly checked?: "restore" | "expect" | "parent";
     finish(results: readonly ExecuteResult[]): unknown;
 };
 /**