okmodel 0.1.0 → 0.2.1

package/dist/runtime/validate/index.js

@@ -0,0 +1,175 @@
+import {
+  validationGate
+} from "../../shared/3a5ne750.js";
+import {
+  addSchemaHook
+} from "../../shared/7mht49yd.js";
+import {
+  queryHandle
+} from "../../shared/mxmcdsh5.js";
+import {
+  OkmError2
+} from "../../shared/52szzakm.js";
+
+// src/runtime/validate/load.ts
+var engine;
+function loadEngine() {
+  engine ??= import("../../shared/n47rd821.js");
+  return engine;
+}
+
+// src/runtime/validate/hook.ts
+var VALIDATION_HOOK = 1;
+function attachValidation(target, ctx) {
+  if (attachValidation["~v"] !== VALIDATION_HOOK)
+    return;
+  const name = ctx.table;
+  const session = ctx.session;
+  const schema = session?.schema;
+  if (name === undefined || schema === undefined)
+    return;
+  const source = schema.tables.find((item) => item.name === name);
+  const model = schema.model[name];
+  if (source === undefined || model === undefined || validationGate(schema.validation, source) === undefined) {
+    return;
+  }
+  const insert = target.insert;
+  const update = target.update;
+  if (typeof insert !== "function" || typeof update !== "function")
+    return;
+  const wrapped = guardWrite(insert, "insert", model, source, schema.validation);
+  wrapped.validate = (body) => stand(model, source, schema.validation, "insert", body, "valid");
+  wrapped.check = (body) => stand(model, source, schema.validation, "insert", body, "check");
+  wrapped.pick = (...keys) => ({
+    validate: (body) => stand(model, source, schema.validation, "insert", body, "valid", keys),
+    check: (body) => stand(model, source, schema.validation, "insert", body, "check", keys)
+  });
+  wrapped.omit = (...keys) => ({
+    validate: (body) => stand(model, source, schema.validation, "insert", body, "valid", undefined, keys),
+    check: (body) => stand(model, source, schema.validation, "insert", body, "check", undefined, keys)
+  });
+  wrapped["~standard"] = {
+    version: 1,
+    vendor: "okmodel",
+    async validate(value) {
+      try {
+        return {
+          value: await stand(model, source, schema.validation, "insert", value, "valid")
+        };
+      } catch (error) {
+        if (error instanceof OkmError2 && error.issues !== undefined)
+          return { issues: error.issues };
+        throw error;
+      }
+    }
+  };
+  target.insert = wrapped;
+  const wrappedUpdate = guardWrite(update, "update", model, source, schema.validation);
+  wrappedUpdate.validate = (body) => stand(model, source, schema.validation, "update", body, "valid");
+  target.update = wrappedUpdate;
+}
+function stand(model, source, schemaFlag, op, body, mode, pick, omit) {
+  return loadEngine().then((mod) => mod.stand(model, source, schemaFlag, op, body, mode, pick, omit));
+}
+function guardWrite(original, op, model, source, schemaFlag) {
+  const wrapped = (data, options = {}) => {
+    const rest = dropValidate(options);
+    if (skipped(options))
+      return original(data, rest);
+    return chain((ok, fail) => {
+      loadEngine().then((mod) => {
+        mod.prepare(model, source, schemaFlag, op, data).then((next) => ok(original(next, rest)), fail);
+      }, fail);
+    });
+  };
+  return wrapped;
+}
+function chain(start) {
+  let slot;
+  let pending;
+  const ready = () => {
+    pending ??= new Promise((resolve, reject) => {
+      start((handle) => {
+        slot = handle;
+        resolve();
+      }, reject);
+    });
+    return pending;
+  };
+  const taken = () => {
+    if (slot === undefined)
+      throw new Error("Validation did not produce a write.");
+    return slot;
+  };
+  return queryHandle(() => ready().then(() => taken()), {
+    sql: () => ready().then(() => taken().sql()),
+    expect(count) {
+      return chain((ok, fail) => {
+        ready().then(() => ok(taken().expect(count)), fail);
+      });
+    },
+    all(reason) {
+      return chain((ok, fail) => {
+        ready().then(() => ok(taken().all(reason)), fail);
+      });
+    }
+  });
+}
+attachValidation["~v"] = VALIDATION_HOOK;
+function skipped(options) {
+  return options.validate === false;
+}
+function dropValidate(options) {
+  if (!("validate" in options))
+    return options;
+  const record = options;
+  const { validate: _drop, ...rest } = record;
+  return rest;
+}
+
+// src/runtime/validate/bind.ts
+var armed = false;
+function armValidation() {
+  if (armed)
+    return;
+  armed = true;
+  addSchemaHook(attachValidation);
+}
+
+// src/runtime/validate/rules.ts
+var v = {
+  trim() {
+    armValidation();
+    return { k: "trim" };
+  },
+  lowercase() {
+    armValidation();
+    return { k: "lower" };
+  },
+  email(key) {
+    armValidation();
+    return { k: "email", key };
+  },
+  min(n, key) {
+    armValidation();
+    return { k: "min", n, key };
+  },
+  rule(fn, path, key) {
+    armValidation();
+    return { k: "rule", fn, path, key };
+  },
+  onInsert(rule) {
+    armValidation();
+    return rule === undefined ? { k: "phase", op: "insert" } : { k: "when", op: "insert", rule };
+  },
+  onUpdate(rule) {
+    armValidation();
+    return rule === undefined ? { k: "phase", op: "update" } : { k: "when", op: "update", rule };
+  }
+};
+
+// src/runtime/validate/index.ts
+armValidation();
+export {
+  v
+};

package/dist/runtime/validate/load.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The only static reference to the validation engine.
+ *
+ * A no-validation app does not import this module, so its total graph does
+ * not include the engine chunk. A failed import rejects the call that asked
+ * for it, and the same promise is reused so a later call fails the same way.
+ */
+/**
+ * Loads the validation engine.
+ *
+ * @returns The engine module
+ */
+export declare function loadEngine(): Promise<typeof import("./engine.js")>;

package/dist/runtime/validate/places.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reads validation rules stored on a schema.
+ *
+ * `schema()` does not call this. `okm check` does, and the engine does on
+ * the first validated call. A field with rules in two places is OKM1030.
+ */
+import type { ValidationModel } from "../../dialects/pg/model.js";
+import type { AnyTable } from "../../dialects/pg/table.js";
+/**
+ * Reports OKM1030 and a malformed `validate` section.
+ *
+ * A schema with no tables is left alone. The walk reads stored rules and
+ * does not run them.
+ *
+ * @param schema - A `schema()` result
+ */
+export declare function assertValidation(schema: object): void;
+/**
+ * Builds one table's validation model from the rules stored on it.
+ *
+ * Returns `undefined` when validation is off for the table. Throws OKM1030
+ * when a field is validated in two places, whether or not validation is on.
+ *
+ * @param schemaFlag - The schema's `validation` option, stored as given
+ * @param table - The table, with its column rules and `validate` section
+ * @returns The model, or `undefined` when this table does not validate
+ */
+export declare function validationGate(schemaFlag: unknown, table: AnyTable): ValidationModel | undefined;
+/**
+ * Reports whether a write on this table would run validation.
+ *
+ * True when the effective setting is on, or the table stores a `validate`
+ * section or an inline `.validate(...)`. A call that passes `{ validate: false }`
+ * would not. This does not run the rules and does not report OKM1030.
+ *
+ * @param schemaFlag - The schema `validation` option, stored as given
+ * @param table - The table, with its column rules and `validate` section
+ * @param options - Write options. `{ validate: false }` skips the call
+ * @returns Whether the write would validate
+ */
+export declare function writeWouldValidate(schemaFlag: unknown, table: AnyTable, options: object): boolean;

package/dist/runtime/validate/rules.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Rule objects `v` returns.
+ *
+ * The engine interprets `k`. This module does not import the engine. Each
+ * rule registers the client hook so a bundled app still has it when the
+ * module side effect is dropped.
+ */
+/** Trims a string. Other values are left as they are. */
+export type TrimRule = {
+    readonly k: "trim";
+};
+/** Lowercases a string. Other values are left as they are. */
+export type LowerRule = {
+    readonly k: "lower";
+};
+/** Rejects a string that is not an email. `key` is the issue message. */
+export type EmailRule = {
+    readonly k: "email";
+    readonly key: string;
+};
+/** Minimum string length or number. `key` is the issue message. */
+export type MinRule = {
+    readonly k: "min";
+    readonly n: number;
+    readonly key: string;
+};
+/** A caller predicate. `false` records `key` at `path`. */
+export type PredicateRule = {
+    readonly k: "rule";
+    readonly fn: (value: unknown) => boolean;
+    readonly path: string;
+    readonly key: string;
+};
+/** Runs the inner rule only on insert or only on update. */
+export type WhenRule = {
+    readonly k: "when";
+    readonly op: "insert" | "update";
+    readonly rule: unknown;
+};
+/** Following rules in the same list run only on this operation, until the next phase. */
+export type PhaseRule = {
+    readonly k: "phase";
+    readonly op: "insert" | "update";
+};
+/** One object `v` can return. */
+export type Rule = TrimRule | LowerRule | EmailRule | MinRule | PredicateRule | WhenRule | PhaseRule;
+/**
+ * Validation rules.
+ *
+ * Transforms (`trim`, `lowercase`) run before checks. `onInsert()` and
+ * `onUpdate()` with no argument scope the rules that follow them in the same
+ * list. Passed a rule, they scope that rule only.
+ */
+export declare const v: {
+    /**
+     * Removes leading and trailing whitespace from a string.
+     *
+     * @returns A transform rule
+     */
+    trim(): TrimRule;
+    /**
+     * Lowercases a string.
+     *
+     * @returns A transform rule
+     */
+    lowercase(): LowerRule;
+    /**
+     * Requires an email address.
+     *
+     * @param key - Issue message key
+     * @returns A check rule
+     */
+    email(key: string): EmailRule;
+    /**
+     * Requires a string at least `n` characters long, or a number at least `n`.
+     *
+     * @param n - Minimum length or value
+     * @param key - Issue message key
+     * @returns A check rule
+     */
+    min(n: number, key: string): MinRule;
+    /**
+     * Records `key` at `path` when `fn` returns false.
+     *
+     * On a field, `fn` receives the field value. In `$row`, it receives the row
+     * after field transforms.
+     *
+     * @param fn - Predicate. `true` accepts the value
+     * @param path - Issue path segment
+     * @param key - Issue message key
+     * @returns A check rule
+     */
+    rule<T>(fn: (value: T) => boolean, path: string, key: string): PredicateRule;
+    /**
+     * Limits a rule, or the rules that follow, to insert.
+     *
+     * @param rule - One rule. Omitted, the rules after this marker are limited
+     * @returns A phase marker or a wrapped rule
+     */
+    onInsert(rule?: unknown): PhaseRule | WhenRule;
+    /**
+     * Limits a rule, or the rules that follow, to update.
+     *
+     * @param rule - One rule. Omitted, the rules after this marker are limited
+     * @returns A phase marker or a wrapped rule
+     */
+    onUpdate(rule?: unknown): PhaseRule | WhenRule;
+};

package/dist/runtime/validate/surface.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Types `okmodel/validate` adds to a table handle.
+ *
+ * Nothing here exists at runtime. `index.ts` merges these members into
+ * `TableExtras` with a module augmentation, so a program that never imports
+ * `okmodel/validate` does not see them and does not pay for them.
+ */
+import type { ValidationIssue } from "../../contracts/error.js";
+import type { InputMark } from "../../contracts/rows.js";
+import type { QuerySchema } from "../../dialects/pg/model.js";
+import type { InsertOf, OptionalInsert, RequiredInsert, UpdateOf } from "../types.js";
+/**
+ * Reads one stored `validation` option: a boolean or `{ enabled, onRead, style }`.
+ *
+ * An object without `enabled` is on, as it is at runtime.
+ *
+ * @typeParam V - The option as the caller wrote it, or `undefined`
+ */
+type Enabled<V> = V extends true ? true : V extends {
+    readonly enabled: infer E;
+} ? E extends true ? true : false : V extends object ? true : false;
+/** The `validation` option a table's own `options` carry, or `never` when it sets none. */
+type TableOption<T> = T extends {
+    readonly options?: infer O;
+} ? O extends {
+    readonly validation: infer V;
+} ? V : never : never;
+/**
+ * The effective setting for one table: its own option, else the schema's.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam K - Table name
+ */
+export type ValidationOn<S extends QuerySchema, K extends keyof S["~byName"]> = Enabled<[
+    TableOption<S["~byName"][K]>
+] extends [never] ? S extends {
+    readonly "~validation": infer V;
+} ? V : undefined : TableOption<S["~byName"][K]>>;
+/** Insert shape plus {@link InputMark}. */
+type Marked<S extends QuerySchema, K extends keyof S["~byName"]> = InsertOf<S, K> & InputMark;
+/**
+ * One insert body, with optional columns left optional and the input mark.
+ *
+ * Guarded fields and the tenant key are already absent from the shape.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam K - Table name
+ */
+export type InputBody<S extends QuerySchema, K extends keyof S["~byName"]> = RequiredInsert<Marked<S, K>> & OptionalInsert<Marked<S, K>>;
+/** What `validate()` accepts: one body, or a list. */
+type Bodies<S extends QuerySchema, K extends keyof S["~byName"]> = InputBody<S, K> | readonly Marked<S, K>[];
+/**
+ * Members `insert` gains when this table validates.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam K - Table name
+ */
+export type ValidateInsert<S extends QuerySchema, K extends keyof S["~byName"]> = ValidationOn<S, K> extends true ? {
+    /**
+     * Checks one row or a list and returns it frozen.
+     *
+     * A later insert of that value skips these rules.
+     */
+    validate<const T extends Bodies<S, K>>(body: T): Promise<T>;
+    /** The same checks. Issues come back instead of OKM1200. */
+    check(body: unknown): Promise<readonly ValidationIssue[]>;
+    /** Validates only these fields. */
+    pick<const F extends readonly (keyof InsertOf<S, K> & string)[]>(...fields: F): {
+        validate(body: unknown): Promise<Pick<InsertOf<S, K>, F[number]> & InputMark>;
+        check(body: unknown): Promise<readonly ValidationIssue[]>;
+    };
+    /** Validates every field except these. */
+    omit<const F extends readonly (keyof InsertOf<S, K> & string)[]>(...fields: F): {
+        validate(body: unknown): Promise<Omit<InsertOf<S, K>, F[number]> & InputMark>;
+        check(body: unknown): Promise<readonly ValidationIssue[]>;
+    };
+    /** Standard Schema. Issues are returned. Other errors still throw. */
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: "okmodel";
+        validate(value: unknown): Promise<{
+            readonly value: unknown;
+        } | {
+            readonly issues: readonly ValidationIssue[];
+        }>;
+    };
+} : unknown;
+/** A patch: any subset of the update shape, plus {@link InputMark}. */
+type Patch<S extends QuerySchema, K extends keyof S["~byName"]> = Partial<UpdateOf<S, K>> & InputMark;
+/**
+ * Members `update` gains when this table validates.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam K - Table name
+ */
+export type ValidateUpdate<S extends QuerySchema, K extends keyof S["~byName"]> = ValidationOn<S, K> extends true ? {
+    /** Checks a patch. A `{ set }` body checks `set`. */
+    validate<const T extends Patch<S, K> | {
+        readonly set: Patch<S, K>;
+    }>(body: T): Promise<T>;
+} : unknown;
+export {};

package/dist/runtime/write.d.ts

@@ -4,8 +4,12 @@
  * Loaded on the first write. Conflict SQL loads only when `onConflict` is not
  * `"error"`. Chunked writes go through the internal transaction runner.
  */
-import type { DriverPool, Statement } from "../contracts/driver.js";
+import type { ExecuteOptions, ExecuteResult, Statement } from "../contracts/driver.js";
+import type { IdGenerators } from "../contracts/generator.js";
+import type { PresetUse } from "../dialects/pg/model.js";
 import type { QuerySchema } from "../dialects/pg/model.js";
+import { type ArchiveView, type CallScope } from "./plan.js";
+import { type RunHost } from "./tx.js";
 /** Statements in one insert stay under this many parameters. The protocol limit is 65535. */
 export declare const WRITE_PARAM_BUDGET = 2048;
 /** A write the caller asked for. */
@@ -14,11 +18,29 @@ export type WriteOp = "insert" | "update" | "delete";
 export type WriteMods = {
     readonly all?: string;
     readonly expect?: number;
+    readonly archive?: ArchiveView | undefined;
+    /** Presets chained on the handle. `planWrite` resolves them into `presets`. */
+    readonly uses?: PresetUse | undefined;
+    /** Filters the chained presets added. Joined after each `where` with AND. */
+    readonly presets?: readonly unknown[];
 };
 /** Pool and schema for one client. The client maps driver errors. */
-export type WriteHost = {
+export type WriteHost = RunHost & {
     readonly schema: QuerySchema;
-    readonly pool: DriverPool;
+    readonly generators?: IdGenerators | undefined;
+};
+/**
+ * A planned write: its statements, and what turns their results into the value.
+ *
+ * `batch` flattens the statements of many operations into one atomic unit and
+ * gives each operation back its own slice of the results.
+ */
+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";
+    finish(results: readonly ExecuteResult[]): unknown;
 };
 /**
  * Runs a write and decodes it.
@@ -29,9 +51,11 @@ export type WriteHost = {
  * @param input - Rows, or the update or delete target
  * @param options - Returning, conflict, expect, signal, timeout
  * @param mods - `.all` and `.expect`
+ * @param scope - Tenant scope of the client
+ * @param plan - Return the {@link PreparedWrite} without running it, for `batch`
  * @returns Rows, one row, or `{ count }`
  */
-export declare function executeWrite(host: WriteHost, op: WriteOp, table: string, input: unknown, options: object, mods: WriteMods): Promise<unknown>;
+export declare function executeWrite(host: WriteHost, op: WriteOp, table: string, input: unknown, options: object, mods: WriteMods, scope?: CallScope, plan?: true): Promise<unknown>;
 /**
  * Plans a write and does not run it.
  *
@@ -41,8 +65,9 @@ export declare function executeWrite(host: WriteHost, op: WriteOp, table: string
  * @param input - Rows, or the update or delete target
  * @param options - Returning, conflict, expect, signal, timeout
  * @param mods - `.all` and `.expect`
+ * @param generators - Built-in replacements. Omitted uses the functions stored on the columns
  * @returns The statements in order
  */
-export declare function explainWrite(schema: QuerySchema, op: WriteOp, table: string, input: unknown, options: object, mods: WriteMods): Promise<{
+export declare function explainWrite(schema: QuerySchema, op: WriteOp, table: string, input: unknown, options: object, mods: WriteMods, generators?: IdGenerators, scope?: CallScope): Promise<{
     readonly statements: readonly Statement[];
 }>;

package/dist/shared/{fgqgsb5z.js → 0qkxbm1f.js}

@@ -9,7 +9,7 @@ import {
   runCall,
   EMPTY_NOTICES,
   resultFrom
-} from "./xy79j5hq.js";
+} from "./9k6vetvf.js";
 
 // src/adapters/pg/pglite.ts
 import { PGlite } from "@electric-sql/pglite";
@@ -48,7 +48,7 @@ async function open3(config = {}) {
     return {
       execute: (text, params, options) => runCall(closed, options, (watch) => session.query(text, params, watch)),
       batch: (statements, options) => runCall(closed, options, async (watch) => {
-        const { runAtomicBatch } = await import("./dynq16vb.js");
+        const { runAtomicBatch } = await import("./b066g80h.js");
         return runAtomicBatch(session, statements, watch);
       }),
       async release() {

package/dist/shared/0v1g424p.js

@@ -0,0 +1,26 @@
+import {
+  OkmError2
+} from "./52szzakm.js";
+
+// src/dialects/pg/filter-parse.ts
+function parseQuery(allow, sort, query) {
+  if (typeof query !== "object" || query === null || Array.isArray(query)) {
+    throw new OkmError2("OKM1121", "filters parse expects an object of fields.");
+  }
+  const where = {};
+  let orderBy;
+  for (const key of Object.keys(query)) {
+    const value = query[key];
+    if (key === "sort" && typeof value === "string" && sort.includes(value)) {
+      orderBy = { [value]: "asc" };
+      continue;
+    }
+    if (allow[key]?.includes("eq") === true && (value === null || typeof value !== "object")) {
+      where[key] = value;
+    }
+  }
+  return orderBy === undefined ? { where } : { where, orderBy };
+}
+export {
+  parseQuery
+};