okmodel 0.1.1 → 0.3.0

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

@@ -86,21 +86,23 @@ export declare function encodeTimeZone(value: TimeWithOffset, precision?: TimePr
 /**
  * Decodes a time with offset.
  *
- * @param wire - Time text plus an offset
- * @returns Time and offset
+ * @param wire - Time text plus an offset, `±HH` as Postgres sends it or `±HH:MM`
+ * @returns Time and offset, the offset as `±HH:MM`
  */
 export declare function decodeTimeZone(wire: string): TimeWithOffset;
 /**
  * Encodes a duration as an ISO-8601 duration.
  *
  * @param value - Duration
- * @returns ISO-8601 text Postgres accepts for interval
+ * @returns ISO-8601 text Postgres accepts for interval, with a sign on each field when negative
  */
 export declare function encodeDuration(value: Temporal.Duration): string;
 /**
- * Decodes an ISO-8601 duration.
+ * Decodes an interval as Postgres sends it: `1 year 2 mons 3 days 04:05:06.5`,
+ * `01:30:00`, or an ISO-8601 duration. A part may carry a sign. Parts of
+ * different signs (`1 day -01:00:00`) cannot be one `Temporal.Duration`.
  *
- * @param wire - Duration text
+ * @param wire - Interval text
  * @returns A duration
  */
 export declare function decodeDuration(wire: string): Temporal.Duration;
@@ -202,10 +204,10 @@ declare global {
         };
         readonly Duration: {
             /**
-             * @param item - ISO-8601 duration
+             * @param item - ISO-8601 duration, or numeric fields
              * @returns A duration
              */
-            from(item: string): Temporal.Duration;
+            from(item: string | Readonly<Record<string, number>>): Temporal.Duration;
         };
     };
 }

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

@@ -0,0 +1,103 @@
+/**
+ * The tenancy object `schema()` calls once.
+ *
+ * The methods live on the value `columnTenancy()` returns from `okmodel/tenancy`.
+ * This file only names them. An application that never imports that subpath
+ * does not load them.
+ */
+import type { ColumnBuilder, FlagTrue, PlainFlags } from "./column.js";
+import type { SchemaHookCtx } from "./model.js";
+import type { AnyTable } from "./table.js";
+/**
+ * A guarded uuid column, one per tenant table.
+ *
+ * Insert and update omit it. The client fills it from the scope.
+ */
+export type TenantFields<Key extends string> = {
+    readonly [K in Key]: ColumnBuilder<string, FlagTrue<PlainFlags, "guarded">>;
+};
+/** One tenant value, or a reason for leaving the scope. The value is not a cache key. */
+export type TenantCall = {
+    readonly value: string;
+} | {
+    readonly unscoped: string;
+};
+/** Text the scope predicate writes. The planner's sink has these methods. */
+export type TenancyText = {
+    text(value: string): void;
+    param(encoded: string): void;
+    mark(token: string): void;
+};
+/** `for()` and `unscoped()` plus the table names the root client keeps. */
+export type TenancyClient = {
+    readonly names: readonly string[];
+    readonly for?: (input: unknown) => unknown;
+    readonly unscoped?: (reason: string) => unknown;
+};
+/** One inspect rule the tenancy object recorded. */
+export type TenancyRule = {
+    readonly rule: string;
+    readonly contribution: string;
+    readonly provenance: string;
+    readonly source?: string;
+};
+/**
+ * Column tenancy passed to `schema({ tenancy })`.
+ *
+ * `columnTenancy()` from `okmodel/tenancy` builds it. `rewrite` runs once,
+ * before compile. The other methods are the planner and the client.
+ */
+export type ColumnTenancy = {
+    readonly key: string;
+    readonly type: "uuid";
+    readonly strategy: "column";
+    /** Tables with the tenant column, widened uniques, and composite references. */
+    rewrite(tables: readonly AnyTable[]): readonly AnyTable[];
+    /** The guarded uuid column, for emitted row types. */
+    column(): object;
+    predicate(input: {
+        readonly table: string;
+        readonly fieldSql: (field: string) => string | undefined;
+        readonly encode: ((value: unknown) => string) | undefined;
+        readonly alias: string;
+        readonly appended: boolean;
+        readonly scope: TenantCall | undefined;
+        readonly sink: TenancyText;
+    }): boolean;
+    guard(table: string, field: string, kind: "where" | "insert" | "update"): void;
+    stamp(table: string, rows: Record<string, unknown>[], scope: TenantCall | undefined): void;
+    client(input: {
+        readonly names: readonly string[];
+        readonly scoped: boolean;
+        readonly open: (scope: TenantCall) => unknown;
+    }): TenancyClient;
+    rules(table: string, source: string | undefined, scope: TenantCall | undefined): readonly TenancyRule[];
+    /**
+     * Attaches `for()` and `unscoped()` on the root client.
+     *
+     * The same hook archivable uses for its table methods.
+     *
+     * @param target - The client object
+     * @param ctx - Names, scope, and the table map
+     */
+    hook(target: Record<string, unknown>, ctx: SchemaHookCtx): void;
+    /**
+     * Treats a view that exposes the tenant key as tenant-scoped.
+     *
+     * The predicate then applies to reads of that view. A view that does not
+     * expose the key is refused earlier (OKM1820) unless it is `global`.
+     *
+     * @param name - Client name of the view
+     */
+    scopeView(name: string): void;
+    missing(table: string): never;
+};
+/**
+ * Reads `schema({ tenancy })`.
+ *
+ * Omitted stays `undefined`. Anything else must be `columnTenancy()`.
+ *
+ * @param value - The option the caller passed
+ * @returns The tenancy object, or `undefined`
+ */
+export declare function readTenancy(value: unknown): ColumnTenancy | undefined;

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

@@ -0,0 +1,21 @@
+/**
+ * Resolver and emitter of a `manyThrough` relation.
+ *
+ * The relation object carries both. `schema()` calls the resolver, and the
+ * planner calls the emitter with its own helpers, so a schema that has no
+ * `manyThrough` ships none of this. A join row or target in another tenant or
+ * archived never shows: the same planner predicates apply to both tables.
+ */
+import type { RelationScope } from "./relations.js";
+import type { RelationModel } from "./model.js";
+/**
+ * Resolves a `manyThrough` declaration against the schema's foreign keys.
+ *
+ * @param scope - What `schema()` knows
+ * @param table - Related table name
+ * @param through - Join table name
+ * @param from - Join table field that references the declaring table, when ambiguous
+ * @param to - Join table field that references the related table, when ambiguous
+ * @returns The resolved relation, carrying its emitter
+ */
+export declare function resolveThrough(scope: RelationScope, table: string, through: string, from: string | undefined, to: string | undefined): RelationModel;

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

@@ -0,0 +1,141 @@
+/**
+ * Trait values `schema()` applies.
+ *
+ * The timestamp columns and their clock live in `okmodel/traits`. This module
+ * only reads the object a schema passes in, so an application that never
+ * imports a trait does not load that code.
+ */
+/**
+ * Columns an archivable trait asks `schema()` to keep.
+ *
+ * `at` and `id` are field names. `cascade` names child tables archived and
+ * restored with the row. The trait's rewrite makes uniques partial and checks
+ * the cascade. Absent means the table is not archivable.
+ */
+export type ArchiveRequest = {
+    readonly at: string;
+    readonly id: string;
+    readonly cascade: readonly string[];
+};
+/**
+ * Columns `schema()` passes to {@link Trait.apply}.
+ *
+ * `columns` starts as the table's own fields. `apply` adds the trait's fields
+ * or throws OKM1012 when a name is already there. `archive` is set by
+ * `archivable()` and read once, after every trait has applied.
+ */
+export type TraitModel = {
+    columns: Record<string, object>;
+    archive?: ArchiveRequest;
+    /**
+     * Presets collected so far: the table's own first, then each trait's.
+     *
+     * Starts as the table's own object. A trait copies it before adding, so the
+     * author's object is never changed.
+     */
+    presets?: Readonly<Record<string, unknown>> | undefined;
+    /** Trait that added each preset. A name missing here is the table's own. */
+    presetFrom?: Record<string, string>;
+};
+/**
+ * The table `apply` is adding columns to.
+ */
+export type TraitContext = {
+    readonly table: string;
+};
+/**
+ * Columns and write rules a trait contributes.
+ *
+ * `fields` are real columns. `touch` columns are set to `now()` on update.
+ * `sealed` columns cannot be set from input, including `{ allow }`.
+ * A touched column is sealed. `apply` is the trait's own merge. `schema()`
+ * only calls it.
+ */
+export type Trait = {
+    readonly name: string;
+    readonly fields: Readonly<Record<string, object>>;
+    readonly touch?: readonly string[];
+    readonly sealed?: readonly string[];
+    /** Presets the trait adds to every table it applies to. */
+    readonly presets?: Readonly<Record<string, unknown>>;
+    /**
+     * Adds this trait's columns to one table.
+     *
+     * @param model - Columns collected so far
+     * @param ctx - Table name, for OKM1012
+     */
+    apply(model: TraitModel, ctx: TraitContext): void;
+};
+/**
+ * Field maps of every trait in a list, as one object.
+ *
+ * An empty list contributes no fields. The field types stay on the value
+ * `trait()` returned; this reads them back.
+ *
+ * @typeParam TTraits - Trait list
+ */
+export type FieldsOfList<TTraits> = TTraits extends readonly [] ? Record<never, never> : TTraits extends readonly (infer TItem)[] ? UnionToIntersection<TItem extends {
+    readonly fields: infer TFields;
+} ? TFields : Record<never, never>> : Record<never, never>;
+/**
+ * `{ "~archive": true }` when a trait list includes `archivable()`.
+ *
+ * An empty match contributes `unknown`, so a table without the trait does
+ * not gain the key.
+ *
+ * @typeParam TTraits - Trait list, or a single trait object
+ */
+export type HasArchive<TTraits> = [
+    Extract<TTraits extends readonly (infer TItem)[] ? TItem : TTraits, {
+        readonly "~archive": true;
+    }>
+] extends [never] ? unknown : {
+    readonly "~archive": true;
+};
+/** The `presets` maps of a trait list, as a union. Empty when no trait has any. */
+type TraitPresetUnion<TTraits> = TTraits extends readonly (infer TItem)[] ? TItem extends {
+    readonly presets: infer TPresets;
+} ? TPresets : never : never;
+/**
+ * `{ "~presets": ... }` when a trait list adds presets, joined into one map.
+ *
+ * Nothing is added otherwise, so a table without trait presets keeps its type.
+ *
+ * @typeParam TTraits - Trait list
+ */
+export type PresetsOfList<TTraits> = [TraitPresetUnion<TTraits>] extends [never] ? unknown : {
+    readonly "~presets": UnionToIntersection<TraitPresetUnion<TTraits>>;
+};
+type UnionToIntersection<TUnion> = (TUnion extends unknown ? (argument: TUnion) => void : never) extends (argument: infer TIntersection) => void ? TIntersection : never;
+/** A trait object before `trait()` attaches `apply`. */
+type CheckedTrait = {
+    readonly name: string;
+    readonly fields: Readonly<Record<string, object>>;
+    readonly touch?: readonly string[];
+    readonly sealed?: readonly string[];
+};
+/**
+ * Checks one trait object.
+ *
+ * `methods` and `requires` are part of the type and rejected until the
+ * prompt that implements them.
+ *
+ * @param value - One entry of a traits list
+ * @param where - `schema()` or the table name, for the error
+ * @returns The same object when it is a trait
+ */
+export declare function checkTrait(value: unknown, where: string): CheckedTrait;
+/**
+ * Trait field builders that apply to one table, in catalog order.
+ *
+ * `emitRowTypes` uses this. `schema()` has already rejected a conflict.
+ *
+ * @param schemaTraits - Traits stored on the built schema
+ * @param options - This table's `traits` and `omitDefaults`
+ * @returns Field name and builder pairs. Empty when the table has no traits
+ */
+export declare function contributedFields(schemaTraits: readonly Trait[] | undefined, options: {
+    readonly traits?: readonly Trait[];
+    readonly omitDefaults?: string;
+} | undefined): readonly (readonly [string, object])[];
+export {};

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

@@ -0,0 +1,30 @@
+/**
+ * Read model and client hook for a declared view.
+ *
+ * `schema()` calls `install` and the client calls `hook`. Neither path is
+ * imported by a featureless app. Writes are not copied onto the handle.
+ */
+import type { ColumnTenancy } from "../tenancy.js";
+import type { SchemaHook, TableModel } from "../model.js";
+import { type AnyTable } from "../table.js";
+/** What `schema()` passes when it binds a view. */
+export type ViewInstall = (model: {
+    [name: string]: TableModel;
+}, tenancy: ColumnTenancy | undefined, tables: readonly AnyTable[], casing: "snake" | undefined, scoped: Set<string>) => void;
+/**
+ * Client name, read model, and the hook that moves the handle under `views`.
+ *
+ * @param name - SQL name of the view
+ * @param columns - Declared output columns
+ * @param query - Author SQL
+ * @param tenancy - `global("reason")`, when the view opts out
+ * @returns Methods stored on the declaration
+ */
+export declare function viewClient(name: string, columns: readonly {
+    readonly name: string;
+    readonly type: string;
+}[], query: string, tenancy: unknown): {
+    readonly field: string;
+    readonly install: ViewInstall;
+    readonly hook: SchemaHook;
+};

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

@@ -0,0 +1,35 @@
+/**
+ * Column dependencies of a view, read from `pg_depend`.
+ *
+ * Postgres records them on the view's rewrite rule. The edge is column
+ * granularity when that column is a catalog object.
+ */
+import type { CatalogObject, Namespace, ObjectIdentity } from "../../../contracts/catalog/types.js";
+/**
+ * Reads a query cell as text.
+ *
+ * @param value - A driver cell
+ * @returns The string, or empty when the cell is not a scalar
+ */
+export declare function cellText(value: unknown): string;
+/**
+ * `pg_depend` rows for views and materialized views in one schema.
+ *
+ * `$1` is the concrete schema name. `refobjsubid > 0` keeps column edges.
+ */
+export declare const VIEW_DEPENDENCIES = "\n  select v.relname as view, t.relname as table, a.attname as column\n  from pg_depend d\n  join pg_rewrite r on r.oid = d.objid and d.classid = 'pg_rewrite'::regclass\n  join pg_class v on v.oid = r.ev_class\n  join pg_class t on t.oid = d.refobjid and d.refclassid = 'pg_class'::regclass\n  join pg_attribute a on a.attrelid = t.oid and a.attnum = d.refobjsubid\n  join pg_namespace n on n.oid = v.relnamespace\n  where n.nspname = $1\n    and v.relkind in ('v', 'm')\n    and d.refobjsubid > 0\n    and v.oid <> t.oid\n    and t.relkind in ('r', 'p', 'v', 'm')\n";
+/**
+ * Turns dependency rows into edges that exist in `objects`.
+ *
+ * A table column becomes a column edge. A view that is itself a catalog
+ * object becomes an object edge. Anything else is omitted: the catalog
+ * refuses an edge whose target is missing.
+ *
+ * @param rows - Rows from {@link VIEW_DEPENDENCIES}
+ * @param namespace - Logical namespace stored on the edges
+ * @param objects - Catalog the edges must point into
+ * @returns Edges keyed by view name
+ */
+export declare function viewDependencyEdges(rows: readonly Readonly<Record<string, unknown>>[], namespace: Namespace, objects: readonly CatalogObject[]): Map<string, ObjectIdentity[]>;
+/** Logical public namespace. Tests and the default schema use it. */
+export declare const PUBLIC: Namespace;

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

@@ -0,0 +1,114 @@
+/**
+ * `okmodel/view`.
+ *
+ * `view()` and `materializedView()` return objects that produce their own
+ * catalog records. `schema()` only asks each declared object for those records.
+ * DDL, diffing, and scratch verification stay out of this module's callers
+ * until a plan or a check loads them.
+ */
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+import type { SchemaHook } from "../model.js";
+import type { SqlText } from "../table.js";
+import { type ViewInstall } from "./client.js";
+/** One declared output column. `type` is the Postgres type name. */
+export type ViewColumnInput = {
+    readonly name: string;
+    readonly type: string;
+};
+/** Options for {@link view}. */
+export type ViewOptions = {
+    readonly columns: readonly ViewColumnInput[];
+    readonly query: SqlText | string;
+    /** Schema. The default is `public`. */
+    readonly schema?: string;
+    /**
+     * Opts the view out of tenancy.
+     *
+     * A view that reads a tenant table and does not expose the tenant key is
+     * OKM1820 unless this is `global("reason")`.
+     */
+    readonly tenancy?: unknown;
+};
+/**
+ * One declared view.
+ *
+ * `contribute` builds the catalog record. Column dependencies are filled
+ * from `pg_depend` by scratch verification, not at this call.
+ */
+export type ViewDeclaration = {
+    readonly name: string;
+    readonly schema: string;
+    /**
+     * Catalog record for this declaration.
+     *
+     * @param peers - The `schema({ views })` list
+     * @param built - Objects the schema has already staged
+     * @returns The view record
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+    /** Publishes the read model. `schema()` calls it. */
+    install: ViewInstall;
+    /** Moves the read handle under `db.views`. */
+    hook: SchemaHook;
+};
+/** One index owned by a materialized view. */
+export type MaterializedViewIndexInput = {
+    readonly name?: string;
+    readonly columns: readonly string[];
+    readonly unique?: boolean;
+};
+/** Options for {@link materializedView}. */
+export type MaterializedViewOptions = ViewOptions & {
+    readonly indexes?: readonly MaterializedViewIndexInput[];
+    /**
+     * Populate mode.
+     *
+     * `"concurrently"` plans `REFRESH MATERIALIZED VIEW CONCURRENTLY` and
+     * requires a unique index (OKM1822). Omitted still populates, without
+     * `CONCURRENTLY`.
+     */
+    readonly refresh?: "concurrently";
+};
+/**
+ * One declared materialized view.
+ *
+ * Identity is `(namespace, name)`. Indexes are separate catalog objects.
+ */
+export type MaterializedViewDeclaration = {
+    readonly name: string;
+    readonly schema: string;
+    /**
+     * Catalog records for this declaration.
+     *
+     * @param peers - The `schema({ views })` list
+     * @param built - Objects the schema has already staged
+     * @returns The materialized view and its indexes
+     */
+    contribute(peers: unknown, built: unknown): readonly CatalogObject[];
+    /** Publishes the read model. `schema()` calls it. */
+    install: ViewInstall;
+    /** Moves the read handle under `db.views`. */
+    hook: SchemaHook;
+};
+/**
+ * Declares a view as SQL with output columns.
+ *
+ * The query is stored as written. A scratch database reads `pg_depend` and
+ * `pg_get_viewdef` before a plan treats the body as canonical.
+ *
+ * @param name - View name
+ * @param options - Columns and query
+ * @returns The definition object `schema({ views })` stores
+ */
+export declare function view(name: string, options: ViewOptions): ViewDeclaration;
+/**
+ * Declares a materialized view.
+ *
+ * Creation is `WITH NO DATA`. Populate is a later plan step. `refresh:
+ * "concurrently"` without a unique index is OKM1822.
+ *
+ * @param name - Materialized view name
+ * @param options - Columns, query, indexes, and refresh mode
+ * @returns The definition object `schema({ views })` stores
+ */
+export declare function materializedView(name: string, options: MaterializedViewOptions): MaterializedViewDeclaration;