okmodel 0.1.1 → 0.3.0

package/dist/dialects/pg/fn/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `okmodel/fn`.
+ *
+ * `fn()` and `trigger()` return objects that produce their own catalog
+ * records. `schema()` only asks each declared object for those records.
+ */
+import type { CatalogObject, FunctionLanguage, FunctionSecurity, FunctionVolatility, TriggerEvent, TriggerLevel, TriggerTiming } from "../../../contracts/catalog/types.js";
+import type { AnyTable, SqlText } from "../table.js";
+/** One argument of {@link fn}. */
+export type FunctionArgumentInput = {
+    readonly name: string;
+    readonly type: string;
+};
+/**
+ * A table, or one column of a table.
+ *
+ * A table is an object dependency. `{ table, column }` is a column dependency.
+ * `column` is the SQL name.
+ */
+export type DependsOn = AnyTable | {
+    readonly table: AnyTable;
+    readonly column: string;
+};
+/** Options for {@link fn}. */
+export type FunctionOptions = {
+    readonly arguments?: readonly FunctionArgumentInput[];
+    readonly returns: string;
+    readonly language: FunctionLanguage;
+    readonly volatility?: FunctionVolatility;
+    readonly security?: FunctionSecurity;
+    /** Required when `security` is `"definer"` (OKM1823). */
+    readonly searchPath?: string;
+    readonly body: SqlText | string;
+    /**
+     * Tables and columns the body uses.
+     *
+     * Required for plpgsql (OKM1824). Omitted for `LANGUAGE sql` that begins
+     * with `BEGIN ATOMIC`; those edges are read from `pg_depend`.
+     */
+    readonly dependsOn?: readonly DependsOn[];
+    /** Schema. The default is `public`. */
+    readonly schema?: string;
+};
+/**
+ * One declared function.
+ *
+ * `contribute` builds the catalog record. Overloads differ by argument types.
+ */
+export type Routine = {
+    readonly name: string;
+    readonly schema: string;
+    readonly argTypes: readonly string[];
+    /**
+     * Catalog record for this declaration.
+     *
+     * @param peers - The `schema({ functions })` list
+     * @param built - Objects the schema has already staged
+     * @returns The function record
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+};
+/** Options for {@link trigger}. */
+export type TriggerOptions = {
+    readonly on: AnyTable;
+    readonly timing: TriggerTiming;
+    readonly events: readonly TriggerEvent[];
+    readonly level: TriggerLevel;
+    /** `UPDATE OF` columns. SQL names. Each one is a column dependency. */
+    readonly updateOf?: readonly string[];
+    readonly when?: SqlText | string;
+    readonly calls: Routine;
+};
+/**
+ * One declared trigger.
+ *
+ * Identity is `(table, name)`.
+ */
+export type TriggerDeclaration = {
+    readonly name: string;
+    /**
+     * Catalog record for this declaration.
+     *
+     * @param peers - The `schema({ triggers })` list
+     * @param built - Objects the schema has already staged
+     * @returns The trigger record
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+};
+/**
+ * Declares a function.
+ *
+ * plpgsql without `dependsOn` is OKM1824. `security: "definer"` without
+ * `searchPath` is OKM1823.
+ *
+ * @param name - Function name
+ * @param options - Signature, language, body, and dependencies
+ * @returns The definition object `schema({ functions })` stores
+ */
+export declare function fn(name: string, options: FunctionOptions): Routine;
+/**
+ * Declares a trigger.
+ *
+ * @param name - Trigger name, unique on its table
+ * @param options - Table, timing, events, and the function it calls
+ * @returns The definition object `schema({ triggers })` stores
+ */
+export declare function trigger(name: string, options: TriggerOptions): TriggerDeclaration;

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

@@ -0,0 +1,175 @@
+import {
+  functionObject,
+  triggerObject
+} from "../../../shared/9x25fxhc.js";
+import {
+  staticNamespace2
+} from "../../../shared/t4tbsy9h.js";
+import {
+  OkmError2
+} from "../../../shared/52szzakm.js";
+
+// src/dialects/pg/fn/index.ts
+function fn(name, options) {
+  const language = options.language;
+  const body = bodyText(options.body);
+  const atomic = language === "sql" && /^\s*begin\s+atomic\b/i.test(body);
+  if (language === "plpgsql" && options.dependsOn === undefined) {
+    throw new OkmError2("OKM1824", `Function ${name} is plpgsql and has no dependsOn. Postgres does not record dependencies inside the body.`, {
+      fix: {
+        summary: "List dependsOn. LANGUAGE sql with BEGIN ATOMIC is inferred and does not need the list."
+      }
+    });
+  }
+  if (options.security === "definer" && (options.searchPath === undefined || options.searchPath.trim().length === 0)) {
+    throw new OkmError2("OKM1823", `Function ${name} is security definer and has no search_path.`, {
+      fix: { summary: "Set search_path on the function to the schemas it is allowed to see." }
+    });
+  }
+  const argTypes = (options.arguments ?? []).map((argument) => argument.type);
+  const schema = options.schema ?? "public";
+  return {
+    name,
+    schema,
+    argTypes,
+    contribute(peers, built) {
+      assertPeers(peers, "functions");
+      const namespace = staticNamespace2(schema);
+      const provenance = { origin: "file", name };
+      return [
+        functionObject({
+          namespace,
+          name,
+          ...options.arguments !== undefined ? { arguments: options.arguments } : {},
+          returns: options.returns,
+          language,
+          ...options.volatility !== undefined ? { volatility: options.volatility } : {},
+          ...options.security !== undefined ? { security: options.security } : {},
+          ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
+          body,
+          ...atomic ? { atomic: true } : {},
+          provenance,
+          dependencies: dependencyEdges(options.dependsOn, built)
+        })
+      ];
+    }
+  };
+}
+function trigger(name, options) {
+  return {
+    name,
+    contribute(peers, built) {
+      assertPeers(peers, "triggers");
+      const parent = tableRef(options.on, built);
+      const namespace = staticNamespace2(options.calls.schema);
+      const calls = {
+        namespace,
+        name: options.calls.name,
+        argTypes: options.calls.argTypes
+      };
+      if (!hasIdentity(built, { kind: "function", ...calls })) {
+        throw new OkmError2("OKM1020", `Trigger ${name} calls ${options.calls.name}, which is not in the catalog.`, { fix: { summary: "List the function in schema({ functions }) before the trigger." } });
+      }
+      for (const column of options.updateOf ?? []) {
+        if (!hasIdentity(built, { kind: "column", parent, name: column })) {
+          throw new OkmError2("OKM1020", `Trigger ${name} names column ${column}, which ${parent.name} does not have.`, { fix: { summary: "Name a column of the table the trigger is on." } });
+        }
+      }
+      return [
+        triggerObject({
+          parent,
+          name,
+          timing: options.timing,
+          events: options.events,
+          level: options.level,
+          calls,
+          ...options.updateOf !== undefined ? { updateOf: options.updateOf } : {},
+          ...options.when !== undefined ? { when: bodyText(options.when) } : {},
+          provenance: { origin: "file", name }
+        })
+      ];
+    }
+  };
+}
+function bodyText(body) {
+  return typeof body === "string" ? body : body.text;
+}
+function assertPeers(peers, option) {
+  if (!Array.isArray(peers)) {
+    throw new OkmError2("OKM1020", `schema({ ${option} }) must be a list.`, {
+      fix: { summary: `Pass an array to schema({ ${option} }).` }
+    });
+  }
+}
+function dependencyEdges(dependsOn, built) {
+  if (dependsOn === undefined)
+    return [];
+  return dependsOn.map((item) => {
+    if ("column" in item && "table" in item) {
+      const parent = tableRef(item.table, built);
+      const edge = { kind: "column", parent, name: item.column };
+      if (!hasIdentity(built, edge)) {
+        throw new OkmError2("OKM1020", `dependsOn names column ${item.column}, which ${parent.name} does not have.`, { fix: { summary: "Name a column of a table in this schema." } });
+      }
+      return edge;
+    }
+    const parent = tableRef(item, built);
+    return { kind: "table", namespace: parent.namespace, name: parent.name };
+  });
+}
+function tableRef(table, built) {
+  if (!Array.isArray(built)) {
+    throw new OkmError2("OKM1020", `Table ${table.name} is not in the catalog.`, {
+      fix: { summary: "List the table in schema({ tables })." }
+    });
+  }
+  for (const object of built) {
+    if (!isRecord(object) || object.kind !== "table")
+      continue;
+    const identity = object.identity;
+    const provenance = object.provenance;
+    if (!isRecord(identity) || !isRecord(provenance))
+      continue;
+    if (provenance.origin === "file" && provenance.name === table.name && typeof identity.name === "string") {
+      const namespace = identity.namespace;
+      if (isRecord(namespace) && namespace.form === "static" && typeof namespace.name === "string") {
+        return { namespace: staticNamespace2(namespace.name), name: identity.name };
+      }
+    }
+  }
+  throw new OkmError2("OKM1020", `Table ${table.name} is not in the catalog.`, {
+    fix: { summary: "List the table in schema({ tables })." }
+  });
+}
+function hasIdentity(built, identity) {
+  if (!Array.isArray(built))
+    return false;
+  for (const object of built) {
+    if (!isRecord(object) || !isRecord(object.identity))
+      continue;
+    if (same(object.identity, identity))
+      return true;
+  }
+  return false;
+}
+function same(left, right) {
+  if (left.kind !== right.kind)
+    return false;
+  if (right.kind === "function") {
+    return left.name === right.name && JSON.stringify(left.argTypes) === JSON.stringify(right.argTypes);
+  }
+  if (right.kind === "column") {
+    const parent = left.parent;
+    return left.name === right.name && isRecord(parent) && parent.name === right.parent.name;
+  }
+  if (right.kind === "table")
+    return left.name === right.name;
+  return false;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  fn,
+  trigger
+};

package/dist/dialects/pg/fn/touch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The trigger and function `timestamps({ enforce: "trigger" })` contributes.
+ *
+ * One function per updated-column SQL name. One trigger per table. Provenance
+ * is the timestamps trait. The body writes `new.<column> = now()`.
+ */
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+/**
+ * Catalog records for tables that carry the timestamps trait.
+ *
+ * @param built - Objects already staged, including columns
+ * @returns The function and one trigger per table, or nothing when no table opted in
+ */
+export declare function timestampRecords(built: unknown): readonly CatalogObject[];

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

@@ -6,13 +6,14 @@
  */
 export { schema, type BuiltSchema, type SchemaCodecs, type SchemaInput, type SchemaRequires, } from "./schema.js";
 export { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type Table, type TableOptions, } from "./table.js";
+export type { PresetQuery } from "./preset.js";
 export { custom } from "./custom.js";
 export { ColumnBuilder } from "./column.js";
 export type { ArrayOf, ColumnFlags, ColumnInsert, ColumnInsertOf, ColumnRow, ColumnRowOf, ColumnUpdate, ColumnUpdateOf, FlagTrue, IdFlags, IdentityFlags, PlainFlags, ReferenceModifier, ReferenceOptions, SqlForm, ValidateModifier, WithGenerated, } from "./column.js";
 export { bigint, identity, integer, smallint, type BigintAs, type BigintValue } from "./integer.js";
 export { double, numeric, real, type NumericAs, type NumericValue } from "./decimal.js";
 export { boolean, bytea } from "./bool.js";
-export { json, jsonb, jsonReplacer } from "./json.js";
+export { jsonb, jsonReplacer } from "./json.js";
 export { id, uuid } from "./keys.js";
 export { char, citext, text, varchar } from "./text.js";
 export { date, interval, time, timestamp, timestamptz, timetz } from "./time.js";
@@ -23,7 +24,10 @@ export { line, point, type Line, type Point } from "./geometry.js";
 export { ltree, tsvector } from "./search.js";
 export { domain, enumColumn as enum } from "./enum.js";
 export { t } from "./namespace.js";
+export * as arr from "./ops/arr-ns.js";
+export * as json from "./ops/json-ns.js";
 export { between } from "./ops/between.js";
+export { containedBy } from "./ops/containedBy.js";
 export { contains } from "./ops/contains.js";
 export { endsWith } from "./ops/endsWith.js";
 export { eq } from "./ops/eq.js";
@@ -32,14 +36,19 @@ export { gt } from "./ops/gt.js";
 export { inc } from "./ops/inc.js";
 export { gte } from "./ops/gte.js";
 export { has } from "./ops/has.js";
+export { hasAnyKey } from "./ops/hasAnyKey.js";
+export { hasKey } from "./ops/hasKey.js";
 export { ilike } from "./ops/ilike.js";
 export { inList } from "./ops/inList.js";
 export { like } from "./ops/like.js";
+export { matches } from "./ops/matches.js";
 export { lt } from "./ops/lt.js";
 export { lte } from "./ops/lte.js";
 export { none } from "./ops/none.js";
 export { not } from "./ops/not.js";
 export { notIn } from "./ops/notIn.js";
 export { or } from "./ops/or.js";
+export { overlaps } from "./ops/overlaps.js";
+export { path } from "./ops/path.js";
 export { startsWith } from "./ops/startsWith.js";
-export { many, one, type ManyRelation, type OneRelation, type RelationCall } from "./relations.js";
+export { many, manyThrough, one, type ManyRelation, type ManyThroughRelation, type OneRelation, type RelationCall, } from "./relations.js";