okmodel 0.5.1 → 0.6.0

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

@@ -1,197 +1,33 @@
+import {
+  viewClient
+} from "../../../shared/x3jc53kg.js";
 import {
   viewObject,
   materializedViewObject,
   materializedViewIndex
-} from "../../../shared/y005b761.js";
-import {
-  encodeUuid,
-  decodeUuid
-} from "../../../shared/dyj86cmj.js";
-import {
-  snakeCase
-} from "../../../shared/ntneex2a.js";
-import {
-  encodeText,
-  decodeText
-} from "../../../shared/4m9fn52z.js";
+} from "../../../shared/zy8r7qvz.js";
 import {
   staticNamespace2
-} from "../../../shared/t4tbsy9h.js";
+} from "../../../shared/358zsv4r.js";
 import {
   OkmError2
 } from "../../../shared/52szzakm.js";
 
-// src/dialects/pg/view/client.ts
-function viewClient(name, columns, query, tenancy) {
-  const field = camelCase(name);
-  const marked = readGlobal(name, tenancy);
-  return {
-    field,
-    install(model, scope, tables, casing, scoped) {
-      if (Object.hasOwn(model, field)) {
-        throw new OkmError2("OKM1023", `View ${name} uses the client name ${field}.`, {
-          fix: { summary: "Give the view a name that no table uses." }
-        });
-      }
-      const exposes = exposesKey(columns, scope);
-      if (scope !== undefined && readsTenant(query, tables, casing, scoped)) {
-        if (!exposes && marked === undefined) {
-          throw new OkmError2("OKM1820", `View ${name} reads a tenant table and does not expose ${scope.key}.`, {
-            fix: {
-              summary: "Expose the tenant key so the predicate can be applied, or declare global(reason)."
-            }
-          });
-        }
-        if (exposes) {
-          scope.scopeView(field);
-          scoped.add(name);
-        }
-      }
-      model[field] = {
-        name: field,
-        sql: name,
-        primary: [],
-        uniques: [],
-        columns: columnModels(columns, scope),
-        relations: []
-      };
-    },
-    hook(target, ctx) {
-      publish(field, target, ctx);
-    }
-  };
-}
-function publish(field, target, ctx) {
-  if (ctx.tables === undefined || ctx.table !== undefined)
-    return;
-  const handle = ctx.tables[field];
-  if (typeof handle !== "object" || handle === null)
-    return;
-  const source = handle;
-  const views = target.views;
-  const map = typeof views === "object" && views !== null ? views : {};
-  map[field] = {
-    find: source.find,
-    one: source.one,
-    count: source.count,
-    exists: source.exists
-  };
-  target.views = map;
-  delete ctx.tables[field];
-  delete target[field];
-}
-function columnModels(columns, tenancy) {
-  const seen = new Set;
-  const models = [];
-  for (const column of columns) {
-    const field = fieldName(column.name, tenancy);
-    if (seen.has(field)) {
-      throw new OkmError2("OKM1020", `View column ${column.name} repeats ${field}.`, {
-        fix: { summary: "Declare each output column once." }
-      });
-    }
-    seen.add(field);
-    const uuid = column.type.toLowerCase() === "uuid";
-    const key = tenancy !== undefined && field === tenancy.key;
-    models.push({
-      field,
-      sql: column.name,
-      dataType: column.type,
-      encode: uuid ? (value) => encodeUuid(textValue(value)) : (value) => encodeText(textValue(value)),
-      decode: uuid ? decodeUuid : decodeText,
-      hidden: false,
-      sensitive: false,
-      guarded: key,
-      writable: false,
-      guardUpdate: false
-    });
-  }
-  return models;
-}
-function exposesKey(columns, tenancy) {
-  if (tenancy === undefined)
-    return false;
-  return columns.some((column) => fieldName(column.name, tenancy) === tenancy.key);
-}
-function readsTenant(query, tables, casing, scoped) {
-  for (const name of scoped) {
-    if (mentions(query, name))
-      return true;
-  }
-  for (const table of tables) {
-    const mark = table.options?.tenancy;
-    if (isGlobalMark(mark))
-      continue;
-    const sql = casing === "snake" ? snakeCase(table.name) : table.name;
-    if (mentions(query, sql) || mentions(query, table.name))
-      return true;
-  }
-  return false;
-}
-function readGlobal(name, tenancy) {
-  if (tenancy === undefined)
-    return;
-  if (!isGlobalMark(tenancy)) {
-    throw new OkmError2("OKM1020", `View ${name} tenancy must be global("reason").`, {
-      fix: { summary: 'Pass global("reason") from okmodel/tenancy, or omit tenancy.' }
-    });
-  }
-  return tenancy.reason;
-}
-function isGlobalMark(value) {
-  if (typeof value !== "object" || value === null)
-    return false;
-  const record = value;
-  return record.kind === "global" && typeof record.reason === "string" && record.reason.trim().length > 0;
-}
-function fieldName(column, tenancy) {
-  const field = camelCase(column);
-  if (tenancy !== undefined && (column === tenancy.key || field === tenancy.key))
-    return tenancy.key;
-  return field;
-}
-function camelCase(name) {
-  let out = "";
-  let upper = false;
-  for (const char of name) {
-    if (char === "_") {
-      upper = out.length > 0;
-      continue;
-    }
-    out += upper ? char.toUpperCase() : char;
-    upper = false;
-  }
-  return out;
-}
-function mentions(query, name) {
-  let pattern = '(^|[^A-Za-z0-9_])"?';
-  for (const char of name) {
-    if ("\\^$[]().*+?|{}".includes(char))
-      pattern += "\\";
-    pattern += char;
-  }
-  pattern += '"?(?![A-Za-z0-9_])';
-  return new RegExp(pattern).test(query);
-}
-function textValue(value) {
-  if (typeof value !== "string") {
-    throw new OkmError2("OKM1121", "A view column value must be text.", {
-      fix: { summary: "Pass a string." }
-    });
-  }
-  return value;
-}
-
 // src/dialects/pg/view/index.ts
 function view(name, options) {
   const schema = options.schema ?? "public";
   const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
   const query = bodyText(options.query);
-  const bound = viewClient(name, options.columns, query, options.tenancy);
+  const bound = viewClient(name, options.columns, query, options.tenancy, "plain");
+  let securityInvoker = false;
   return {
     name,
     schema,
-    install: bound.install,
+    "~kind": "view",
+    install(model, tenancy, tables, casing, scoped) {
+      bound.install(model, tenancy, tables, casing, scoped);
+      securityInvoker = tenancy?.strategy === "rls" && scoped.has(name);
+    },
     hook: bound.hook,
     contribute(peers, built) {
       assertPeers(peers);
@@ -203,7 +39,8 @@ function view(name, options) {
           name,
           columns,
           query,
-          provenance
+          provenance,
+          ...securityInvoker ? { securityInvoker: true } : {}
         })
       ];
     }
@@ -213,7 +50,12 @@ function materializedView(name, options) {
   const schema = options.schema ?? "public";
   const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
   const query = bodyText(options.query);
-  const bound = viewClient(name, options.columns, query, options.tenancy);
+  if (options.refresh !== undefined && options.refresh !== "concurrently") {
+    throw new OkmError2("OKM1120", `Materialized view ${name} refresh must be "concurrently".`, {
+      fix: { summary: 'Omit refresh, or pass refresh: "concurrently" with a unique index.' }
+    });
+  }
+  const bound = viewClient(name, options.columns, query, options.tenancy, options.refresh === "concurrently" ? "concurrently" : "blocking");
   const indexes = options.indexes ?? [];
   if (options.refresh === "concurrently" && !indexes.some((index) => index.unique === true)) {
     throw new OkmError2("OKM1822", `Materialized view ${name} refreshes concurrently and has no unique index.`, { fix: { summary: "Add a unique index, or refresh without CONCURRENTLY." } });
@@ -229,6 +71,7 @@ function materializedView(name, options) {
   return {
     name,
     schema,
+    "~kind": "materialized",
     install: bound.install,
     hook: bound.hook,
     contribute(peers, built) {

package/dist/dialects/pg/view/refresh.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `REFRESH MATERIALIZED VIEW` for one view handle.
+ *
+ * Loaded the first time `refresh()` runs. A featureless app, and an app that
+ * never calls it, do not import this module. The name is unqualified so the
+ * session `search_path` selects the schema, matching a view `find`.
+ */
+/**
+ * Refreshes one materialized view on the primary.
+ *
+ * `CONCURRENTLY` when the declaration asked for it. The statement timeout is
+ * the client's, the same ceiling a write uses. A database failure is mapped
+ * and logged like any other statement.
+ *
+ * The refresh runs on a reserved primary connection with `app.unscoped` set
+ * in that same transaction. Under `FORCE ROW LEVEL SECURITY` the owner would
+ * otherwise refresh zero rows. `CONCURRENTLY` cannot run inside a transaction,
+ * so that form sets the session value and clears it before release.
+ *
+ * @param session - Pool, timeout, and logger from the client
+ * @param name - SQL name of the materialized view
+ * @param concurrently - True when the view declares `refresh: "concurrently"`
+ */
+export declare function refreshView(session: object, name: string, concurrently: boolean): Promise<void>;

package/dist/runtime/batch.d.ts

@@ -12,7 +12,7 @@ import { type Session } from "./client.js";
  * Runs write handles as one atomic unit.
  *
  * @param session - Client session
- * @param ops - Write handles: `insert`, `update`, `delete`, `archive`. A `restore`, or a write with `expect`, is OKM1121 (D183)
+ * @param ops - Write handles: `insert`, `update`, `delete`, `archive`. A `restore`, a write with `expect`, or `refresh()` is OKM1121 (D183, D239)
  * @param options - `signal` and `timeout` for the whole batch
  * @param replica - Set by `.replica()`. A batch needs the primary (OKM1840)
  * @returns One result per operation, in order

package/dist/runtime/conflict.d.ts

@@ -18,10 +18,10 @@ export type ConflictPlan = {
  * @param table - Target table
  * @param value - The option the caller passed
  * @param allow - Guarded fields this write may set
- * @param tenantKey - The tenant key on a tenant schema, which every unique includes
+ * @param tenantKey - The tenant key, or every tenant key when the schema has several. A unique that includes them matches when `on` names the other columns. The target keeps the keys, in the unique's order. Naming a key is OKM1104.
  * @returns The plan, or `undefined` for the default `"error"`
  */
-export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>, tenantKey?: string): ConflictPlan | undefined;
+export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>, tenantKey?: string | readonly string[]): ConflictPlan | undefined;
 /**
  * Appends the conflict clause, or wraps a first-or-create insert.
  *

package/dist/runtime/drift.d.ts

@@ -29,3 +29,12 @@ export declare function assertCompatible(pool: DriverPool, schema: QuerySchema,
     readonly catalog?: CatalogArtifact;
     readonly catalogDir?: string;
 }, options: ExecuteOptions | undefined): Promise<void>;
+/**
+ * Directory of `catalog.hash` and `catalog.json`.
+ *
+ * A trailing `/` or `\` is removed so the joined file name is one path.
+ *
+ * @param catalogDir - Directory the caller passed, or the default `.okm`
+ * @returns The directory, without a trailing slash
+ */
+export declare function artifactDir(catalogDir: string | undefined): string;

package/dist/runtime/inflight.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Refuses a positive timeout on a driver that cannot cancel.
+ *
+ * `tx({ timeout })` and `batch({ timeout })` load this with the call. The
+ * connect graph does not. The message stays the one {@link noTimeout} throws.
+ */
+import type { DriverPool } from "../contracts/driver.js";
+/**
+ * Throws OKM1120 when `timeout` is positive and the driver cannot cancel.
+ *
+ * @param pool - Driver the call will use
+ * @param timeout - Milliseconds, when the caller passed one
+ */
+export declare function refuseUncancellableTimeout(pool: DriverPool, timeout: number | undefined): Promise<void>;

package/dist/runtime/pg/bun.js

@@ -1,9 +1,10 @@
+import"../../shared/8dqhth8c.js";
 import {
   DriverError2
 } from "../../shared/31vm914h.js";
 import {
   open5
-} from "../../shared/k8v5v5wj.js";
+} from "../../shared/32cnm7kn.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
@@ -11,12 +12,12 @@ import {
 } from "../../shared/cgbamx3e.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/j60w0dvr.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open5));
+    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open5));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open5({

package/dist/runtime/pg/pg.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/31vm914h.js";
 import {
   open4
-} from "../../shared/96qcj21c.js";
+} from "../../shared/1z04fa85.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
@@ -11,12 +11,12 @@ import {
 } from "../../shared/cgbamx3e.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/j60w0dvr.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open4));
+    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open4));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open4({

package/dist/runtime/pg/pglite.js

@@ -1,9 +1,10 @@
+import"../../shared/8dqhth8c.js";
 import {
   DriverError2
 } from "../../shared/31vm914h.js";
 import {
   open3
-} from "../../shared/87jvvhnt.js";
+} from "../../shared/5j36z8dn.js";
 import {
   PGLITE_CAPABILITIES,
   readCapability2,
@@ -11,12 +12,12 @@ import {
 } from "../../shared/cgbamx3e.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/j60w0dvr.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open3));
+    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open3));
   }
   const pool = isPool(target) ? target : await open3({
     ...target !== undefined ? { dataDir: target } : {},

package/dist/runtime/pg/postgresjs.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/31vm914h.js";
 import {
   open2
-} from "../../shared/krxx77g0.js";
+} from "../../shared/wkme6tep.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
@@ -11,12 +11,12 @@ import {
 } from "../../shared/cgbamx3e.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/j60w0dvr.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open2));
+    return import("../../shared/929h19xp.js").then((mod) => mod.default(target, options, open2));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open2({

package/dist/runtime/plan.d.ts

@@ -18,6 +18,7 @@ export type RouteConstraint = "auto" | "primary" | "replica";
  */
 export type CallScope = {
     readonly value: string;
+    readonly values?: Readonly<Record<string, string>>;
 } | {
     readonly unscoped: string;
 };
@@ -249,6 +250,15 @@ export declare function emitJoin(sink: Sink, parent: string, child: string, rela
 export declare function emitWhere(schema: QuerySchema, table: Indexed, where: unknown, sink: Sink, alias: string, depth: number, appended?: boolean, extra?: Keyset): void;
 export declare function emitOrder(table: Indexed, orderBy: unknown, sink: Sink, alias: string): void;
 export declare function emitPrimaryOrder(table: Indexed, sink: Sink, alias: string): void;
+/**
+ * Refuses a hidden field in `where` or `orderBy`.
+ *
+ * `"filter"` is `hidden({ filterable: true })` and is allowed here.
+ * Aggregate loads this on its first call and applies it before the groupBy rule.
+ *
+ * @param column - The field the caller named
+ */
+export declare function refuseHidden(column: ColumnModel): void;
 export type ParsedInclude = {
     readonly name: string;
     readonly relation: RelationModel;
@@ -289,18 +299,15 @@ export declare function quote(name: string): string;
 export declare function list(names: readonly string[]): string;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /**
- * Whether `where` constrains a row.
+ * Throws OKM1121 for an `or()` that is not an array, or for an empty branch.
  *
- * A field value is a leaf. Anything other than `undefined` counts, including
- * `null`, objects, arrays, and operators. The walk does not enter a field value.
- * It enters the where object's own keys, `and`, `or`, and `not` when `not` is
- * the where itself. An `or()` branch with no predicate is OKM1121. `or([])`
- * matches nothing.
+ * The write and archive predicate walk uses the same throw. It lives here
+ * because the read planner throws it too, and that planner stays in this module.
  *
- * @param where - Caller filter, or one `and` / `or` / `not` operand
- * @returns `false` when the filter matches every row
+ * @param empty - `true` when a branch has no predicate
+ * @returns Never
  */
-export declare function effectivePredicate(where: unknown): boolean;
+export declare function orFail(empty: boolean): never;
 /**
  * Records the fix text for a code thrown from a chunk that loads on first use.
  *
@@ -316,6 +323,7 @@ export declare function registerFailFix(code: QueryCode, summary: string): void;
  *
  * @param code - Spec code
  * @param message - What failed
+ * @param fix - Fix sentence for this call. Omitted, the sentence registered for `code` is used
  */
-export declare function fail(code: QueryCode, message: string): never;
+export declare function fail(code: QueryCode, message: string, fix?: string): never;
 export {};

package/dist/runtime/predicate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether a `where` constrains a row.
+ *
+ * Write and archive load this module. A read does not. The walk is the same
+ * one those paths used when it lived in the planner.
+ */
+/**
+ * Whether `where` constrains a row.
+ *
+ * A field value is a leaf. Anything other than `undefined` counts, including
+ * `null`, objects, arrays, and operators. The walk does not enter a field value.
+ * It enters the where object's own keys, `and`, `or`, and `not` when `not` is
+ * the where itself. An `or()` branch with no predicate is OKM1121. `or([])`
+ * matches nothing.
+ *
+ * @param where - Caller filter, or one `and` / `or` / `not` operand
+ * @returns `false` when the filter matches every row
+ */
+export declare function effectivePredicate(where: unknown): boolean;

package/dist/runtime/safety/index.js

@@ -1,6 +1,6 @@
 import {
   callerLocation
-} from "../../shared/k7dwkhvq.js";
+} from "../../shared/y6jdds7g.js";
 import {
   installSafetyHook
 } from "../../shared/a5sxz52y.js";

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

@@ -0,0 +1,26 @@
+/**
+ * Composite tenancy (`compositeTenancy()`).
+ *
+ * Every tenant table carries the key list, in that order. A column-only app
+ * does not import this file. `via()` is a separate import: this file calls a
+ * table's own `rewrite` and does not load the path compiler.
+ */
+import type { ColumnTenancy } from "../../dialects/pg/tenancy.js";
+/**
+ * Composite tenancy for `schema({ tenancy })`.
+ *
+ * Every table gains each key unless it passes `global("reason")` or `via()`.
+ * The keys are guarded uuids, in this order. Insert fills them from `for()`.
+ * Reads and writes filter on every key.
+ *
+ * @typeParam Keys - Field names, at least one
+ * @param input - The key list and `uuid`
+ * @returns The object `schema()` applies
+ */
+export declare function compositeTenancy<const Keys extends readonly [string, ...string[]]>(input: {
+    readonly key: Keys;
+    readonly type: "uuid";
+}): ColumnTenancy & {
+    readonly key: Keys[number];
+    readonly keys: Keys;
+};

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

@@ -0,0 +1,16 @@
+/**
+ * What a table tenancy `rewrite` receives.
+ *
+ * `columnTenancy()` and `compositeTenancy()` pass it. `via()` reads it.
+ * This file is types only, so it is not in a bundle.
+ */
+import type { AnyTable } from "../../dialects/pg/table.js";
+import type { ColumnTenancy } from "../../dialects/pg/tenancy.js";
+/** Context for one table whose tenancy mark carries `rewrite`. */
+export type TableRewriteContext = {
+    readonly tables: readonly AnyTable[];
+    readonly keys: readonly string[];
+    readonly encodes: readonly ((value: string) => string)[];
+    readonly api: ColumnTenancy;
+    readonly extras: Map<string, readonly string[]>;
+};

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

@@ -22,16 +22,20 @@ export declare function global(reason: string): {
 /**
  * Column tenancy for `schema({ tenancy })`.
  *
- * Every table gains `key` unless it passes `global("reason")`. The key is a
- * guarded uuid. Insert fills it from `for()`. Reads and writes filter on it.
+ * Every table gains `key` unless it passes `global("reason")` or `via()`.
+ * The key is a guarded uuid. Insert fills it from `for()`. Reads and writes
+ * filter on it. A list of keys is `compositeTenancy()`.
  *
  * @typeParam Key - Field name of the tenant key
  * @param input - Field name and `uuid`
  * @returns The object `schema()` applies
  */
-export declare function columnTenancy<const Key extends string>(input: {
-    readonly key: Key;
+export declare function columnTenancy<const Key>(input: {
+    readonly key: Key extends readonly unknown[] ? "columnTenancy() takes one key. Use compositeTenancy()." : Key extends string ? Key : "columnTenancy() key must be a field name.";
     readonly type: "uuid";
 }): ColumnTenancy & {
-    readonly key: Key;
+    readonly key: Key extends string ? Key : string;
 };
+export { compositeTenancy } from "./composite.js";
+export { via } from "./via.js";
+export { RlsRoleError, rlsTenancy, type RlsRoleReason } from "./rls.js";