@fabrika/db 0.9.0-dev.1 → 0.9.0-dev.3

package/types/src/file-columns.d.ts

@@ -0,0 +1,37 @@
+import { type Session } from './database';
+import type { Primitive } from './description';
+import type { TableModel } from './policy';
+/** Where a site's file references belong, and what claiming a pending one needs. */
+export interface FileBinding {
+    /** The work a reference of this site belongs to: one request, or one job attempt. */
+    readonly holder: object;
+    /** The id a pending file must carry to be claimed here: the request (or attempt) that staged it. */
+    readonly request: string;
+    /** How long a pending file may wait for its first reference. */
+    readonly graceMs: number;
+    /** Whether files of `kind` wait for a clean scan: a claimed one is `quarantined` until then. */
+    scans(kind: string): boolean;
+}
+/**
+ * Puts a file reference in each file column of `rows`, read with `action` in `session`: one statement loads every
+ * file's metadata. Without a binding (a store's own runner) the columns keep their ids.
+ */
+export declare function answerFiles<R>(model: TableModel, binding: FileBinding | undefined, session: Session, rows: R[], action: string): Promise<R[]>;
+/**
+ * A write's value for a file column: `null`, or the id of a file reference of the column's kind. A string id, a copied
+ * object or a reference of another kind is refused; whether the site holds it is checked where the write runs.
+ */
+export declare function fileValue(model: TableModel, column: string, value: unknown): string | null;
+/**
+ * The top-level scope a row of `model` lies in, from the values it is written with: `<dimension>:<value>`, or `null` for
+ * an application table, which sets no scope.
+ */
+export declare function rowScope(model: TableModel, values: ReadonlyMap<string, Primitive | null>): string | null | undefined;
+/** The top-level scope of the row whose key is `key`, read in `session`: what an update's file references are stamped with. */
+export declare function storedRowScope(model: TableModel, session: Session, key: string, keyValue: string): Promise<string | null>;
+/**
+ * The file references of a write, in `session` (its transaction), after its statement: each file is locked `for share`
+ * while its state is checked, a pending one this request staged within the grace is claimed, and the first reference
+ * from a dimensional table stamps its scope; a reference from another top-level scope is refused.
+ */
+export declare function referenceFiles(model: TableModel, binding: FileBinding | undefined, session: Session, values: ReadonlyMap<string, Primitive | null>, scope: () => Promise<string | null>): Promise<void>;

package/types/src/file-references.d.ts

@@ -0,0 +1,27 @@
+import type { StoredFileMeta, StoredFileStatus } from './stored-files';
+/** What a handler sees of a stored file: its metadata, never its object. */
+export interface FileReference {
+    readonly id: string;
+    readonly name: string | null;
+    readonly type: string;
+    readonly size: number;
+    readonly status: StoredFileStatus;
+}
+/** Whose a reference is, and what it lets that work do. */
+export interface FileHolding {
+    readonly id: string;
+    readonly kind: string;
+    /** The work that holds it: one request, or one job attempt. */
+    readonly holder: object;
+    /** Read under an action that reads the file (or received, or put): it may be written into a column, served and opened. */
+    readonly readable: boolean;
+}
+/**
+ * A reference to a file for `holder`; only `@fabrika/db` and the framework mint one. A `readable` one also lets its
+ * holder write the file into a column, serve it and open it, through any reference to the same file.
+ */
+export declare function fileReference(meta: StoredFileMeta, holder: object, readable: boolean): FileReference;
+/** What a reference holds, or `undefined` for any other value: a structural copy, a string id or a forged object. */
+export declare function fileHoldingOf(value: unknown): FileHolding | undefined;
+/** Whether `holder` received, put, or read under a read action the file `id`. */
+export declare function holdsFile(holder: object, id: string): boolean;

package/types/src/framework-tables.d.ts

@@ -0,0 +1,59 @@
+import { type Session } from './database';
+import type { DataLayerRuntime } from './store';
+/** One webhook binding: the scope value it reaches, the provider account it accepts, and its signing secret. */
+export interface WebhookBinding {
+    readonly id: string;
+    /** The webhook mount's name. */
+    readonly webhook: string;
+    readonly scope: {
+        readonly type: string;
+        readonly value: string;
+    };
+    /** The provider account: for GitHub, `installation:<id>` or `repository:<id>`, which a delivery must name. */
+    readonly account: string;
+    readonly secret: string;
+}
+export interface NewWebhookBinding extends WebhookBinding {
+    readonly createdBy: string;
+    readonly createdAt: number;
+}
+export interface WebhookTables {
+    /** Records a binding, in `using` when given: the transaction of the procedure that binds. */
+    createBinding(binding: NewWebhookBinding, using?: Session): Promise<void>;
+    /** The binding `id` of `webhook`, or `null`. */
+    binding(webhook: string, id: string): Promise<WebhookBinding | null>;
+    /**
+     * Replaces the secret of the binding when it belongs to `webhook` and `scope`, in `using` when given: a provider that
+     * issues its own signing secret shows it only after the binding's URL is registered. `false` when there was none.
+     */
+    replaceSecret(webhook: string, id: string, scope: {
+        readonly type: string;
+        readonly value: string;
+    }, secret: string, using?: Session): Promise<boolean>;
+    /** Removes the binding when it belongs to `webhook` and `scope`, in `using` when given; `false` when there was none. */
+    removeBinding(webhook: string, id: string, scope: {
+        readonly type: string;
+        readonly value: string;
+    }, using?: Session): Promise<boolean>;
+    /**
+     * Claims a delivery key for `leaseMs`: `null` when the binding completed it within the retention window, or another
+     * copy holds an unexpired claim. A claim whose lease expired is taken over. Keys of the binding older than
+     * `retainedSince` are dropped first, so the table stays bounded.
+     */
+    claimDelivery(bindingId: string, deliveryKey: string, now: number, leaseMs: number, retainedSince: number): Promise<DeliveryClaim | null>;
+    /**
+     * Completes a claimed delivery in `using`, the transaction its handler wrote in, so the work and the completion
+     * commit together; `false` when another copy took the claim over meanwhile, and that transaction must not commit.
+     * Without `using` (a handler with no transaction) it completes on its own.
+     */
+    completeDelivery(claim: DeliveryClaim, using?: Session): Promise<boolean>;
+    /** Gives a claim back after its handler failed, so the provider's redelivery runs it again at once. */
+    releaseDelivery(claim: DeliveryClaim): Promise<void>;
+}
+/** One copy's claim on a delivery: its lease end fences the completion against a copy that took the claim over. */
+export interface DeliveryClaim {
+    readonly bindingId: string;
+    readonly key: string;
+    readonly leaseUntil: number;
+}
+export declare function webhookTables(runtime: () => DataLayerRuntime): WebhookTables;

package/types/src/framework.d.ts

@@ -0,0 +1,32 @@
+import type { DataAccess } from './orm';
+import { type FrameworkTables, type Locator } from './registry';
+import type { DataLayerRuntime } from './store';
+export type { Admissions } from './admissions';
+export type { LeaseFence } from './capability';
+export type { InvocationTransaction, Session } from './database';
+export { CAPABILITY_ERRORS, CapabilityError, type CapabilityErrorReason, LeaseLostError, QUERY_REFUSALS, type QueryRefusal, QueryRefusedError, } from './errors';
+export type { FileBinding } from './file-columns';
+export { type FileHolding, fileHoldingOf, type FileReference, fileReference, holdsFile } from './file-references';
+export type { DeliveryClaim, NewWebhookBinding, WebhookBinding, WebhookTables } from './framework-tables';
+export type { JobLeases, JobLeaseState, JobOutcome, OverdueClaim } from './job-leases';
+export type { DataAccess, DataHandles, DataSite } from './orm';
+export type { FrameworkTables, Locator } from './registry';
+export type { SqlMode, SqlSite, SqlTag, SqlValue } from './sql';
+export type { FileColumnRef, QuarantinedStoredFile, ServedFile, StagedFile, StoredFileMeta, StoredFiles, StoredFileStatus } from './stored-files';
+/** Whether `value` is an object `scoped(tables)` created, rather than a look-alike with the same fields. */
+export declare function isScopedDatabase(value: unknown): boolean;
+/**
+ * Connects the layer `scoped(tables)` created to `runtime`, once, and answers its locator, which nothing else can
+ * reach. Throws for any other value and for a layer that is already connected.
+ */
+export declare function bindScopedDatabase(value: unknown, runtime: DataLayerRuntime): Locator;
+/**
+ * The framework's own writes over the layer `scoped(tables)` created: the webhook tables, the job leases and the
+ * admission counters. Each operation needs the layer bound first. Throws for any other value.
+ */
+export declare function frameworkTablesOf(value: unknown): FrameworkTables;
+/**
+ * The mini-ORM of the layer `scoped(tables)` created: the invocation transactions and the `ctx.db` handles the
+ * framework builds per site. Each operation needs the layer bound first. Throws for any other value.
+ */
+export declare function dataAccessOf(value: unknown): DataAccess;

package/types/src/guard.d.ts

@@ -0,0 +1,23 @@
+import type { OperationNode } from 'kysely';
+export type RootKind = 'SelectQueryNode' | 'InsertQueryNode' | 'UpdateQueryNode' | 'DeleteQueryNode';
+export interface ForeignKeyPair {
+    readonly childColumn: string;
+    readonly parentColumn: string;
+}
+export interface GuardContext {
+    readonly root: RootKind;
+    readonly table: string;
+    /** The children a select may join, each with the composite foreign key its ON must equal. */
+    readonly joins: Readonly<Record<string, readonly ForeignKeyPair[]>>;
+    /** The scope predicate; it must be the WHERE itself or its top-level right conjunct. Absent for an insert only. */
+    readonly scope: OperationNode | undefined;
+    /**
+     * A select that locks its rows: `share` is the layer's check of a mutation's destination, `update` a mutation's
+     * `getForUpdate` of its own target, `claim` a queue claim's `for update skip locked`. No other lock is admitted.
+     */
+    readonly lock?: 'share' | 'update' | 'claim';
+    /** An insert that does nothing on a conflict of its listed columns: `on conflict (columns) do nothing`, and no other. */
+    readonly onConflict?: 'nothing';
+}
+/** Refuses any operation tree outside the allowlist. Runs on the final tree, immediately before it is compiled. */
+export declare function assertAllowedTree(root: OperationNode, context: GuardContext): void;

package/types/src/identifier.d.ts

@@ -0,0 +1,4 @@
+/** `^[a-z_][a-z0-9_]*$`, at most 63 characters (Postgres truncates longer names). */
+export declare function isPlainIdentifier(value: unknown): value is string;
+/** A plain identifier, or two joined by one dot (`note_comments.body`, the alias of a joined column). */
+export declare function isPlainAlias(value: unknown): value is string;

package/types/src/index.d.ts

@@ -0,0 +1,10 @@
+export type { AppCapability, AppGrant, CapabilityAuthority, CapabilityGrant, ContainerGrant, LeaseFence, Ref, RefGrant, RowGrant, RowRef, Within, WithinGrant, } from './capability';
+export { MAX_WITHIN_VALUES } from './capability';
+export { applicationSchema, Database, type PostgresOptions } from './database';
+export type { AllowedOperator, ComparisonOperator, ConditionTuple, ListOperator, NoColumns, NullOperator, PatternOperator, Primitive, ScopedSelect, } from './description';
+export { CAPABILITY_ERRORS, CapabilityError, type CapabilityErrorReason, DatabaseError, LeaseLostError, PolicyError, QUERY_REFUSALS, type QueryRefusal, QueryRefusedError, } from './errors';
+export type { AnyDbIndex, ChildRows, ContainedRows, CountOptions, DataKind, DbIndex, IndexedTable, ListOptions, ListPage, NoUnscoped, OrderTerm, OwnerRow, ReadOnlyUnscoped, ReferenceRows, ReferenceTables, RowFor, Saved, ScopeTarget, TargetForm, TargetRow, Unavailable, UnownedTarget, UnscopedDeclaration, UnscopedInsert, UnscopedMode, UnscopedRows, UnscopedTables, VersionArguments, WithinRows, WithinTables, } from './orm-types';
+export { type ChildPolicy, type ChildScope, type ColumnList, defineTables, type DimensionPolicy, type DimensionScope, type InsertValues, isTables, readTables, type RecordActions, type ReferencePolicy, type ReferenceScope, type RowOf, type TableActions, type TableInsert, Tables, type TableUpdate, type UpdateValues, type VersionColumn, type VocabularyTables, } from './policy';
+export { type AggregateRow, type AggregateSpec, type ChildListScope, type DataLayer, type DataLayerRuntime, scoped, type ScopedDatabase, } from './store';
+export { type TablePolicies, tablePolicies } from './tables';
+export type { ColumnTypes, DefineVocabularyPolicies, NormalizedPolicies, TableVocabulary, TypedColumnList, VocabularyAction, VocabularyChildScope, VocabularyContainer, VocabularyContainerOf, VocabularyDimension, VocabularyDimensionScope, VocabularyPolicyMap, VocabularyTablePolicy, } from './vocabulary-tables';

package/types/src/job-leases.d.ts

@@ -0,0 +1,84 @@
+import type { LeaseFence } from './capability';
+import { type Session } from './database';
+import type { DataLayerRuntime } from './store';
+export type JobOutcome = 'succeeded' | 'failed';
+export interface JobLeaseState {
+    readonly generation: number;
+    /** The attempt holding the lease, or `null` when it is free. */
+    readonly holder: string | null;
+    readonly expiresAt: Date;
+    /** The holding attempt's deadline: no write of it commits after this. */
+    readonly attemptDeadline: Date;
+    /** When the job was first seen in this schema: the baseline of a job that never succeeded. */
+    readonly firstSeenAt: Date;
+    readonly lastStartedAt: Date | null;
+    readonly lastFinishedAt: Date | null;
+    readonly lastStatus: JobOutcome | null;
+    readonly lastSucceededAt: Date | null;
+    readonly lastDurationMs: number | null;
+    readonly lastMissedReportedAt: Date | null;
+}
+/** A job overdue by twice its period, claimed for one report. */
+export interface OverdueClaim {
+    readonly lastSucceededAt: Date | null;
+    readonly firstSeenAt: Date;
+}
+export interface JobLeases {
+    /** The database's clock. */
+    now(): Promise<Date>;
+    /** Records that the job exists (its first-seen time), once; later calls change nothing. */
+    register(job: string): Promise<void>;
+    /**
+     * Frees a lease whose holder never finished before it expired (the run crashed) and records the run as failed.
+     * `true` for the one caller that freed it.
+     */
+    reapCrashed(job: string): Promise<boolean>;
+    /**
+     * A free lease for `holder`, under a new generation, for `leaseMs`; its attempt may write for `attemptMs`. `null`
+     * while another run holds it.
+     */
+    acquire(job: string, holder: string, attemptMs: number, leaseMs: number): Promise<LeaseFence | null>;
+    /**
+     * `acquire` of a registered job that never waits for a lock: `null` at once while another run holds the lease or an
+     * attempt's transaction holds its row. A kick takes the lease only this way, on a connection requests share.
+     */
+    tryAcquire(job: string, holder: string, attemptMs: number, leaseMs: number): Promise<LeaseFence | null>;
+    /**
+     * Hands a live lease to the next attempt under a new generation, so no write of the previous attempt commits from
+     * now on. `null` when `fence` no longer holds it.
+     */
+    renew(fence: LeaseFence, holder: string, attemptMs: number, leaseMs: number): Promise<LeaseFence | null>;
+    /** Frees the lease and records the run's outcome and duration; `false` when `fence` no longer held it. */
+    finish(fence: LeaseFence, outcome: JobOutcome): Promise<boolean>;
+    /** Records that a kick arrived: the run that started before it runs the job once more. Never waits on the lease. */
+    markPending(job: string): Promise<void>;
+    /**
+     * Clears the flag `markPending` set; `true` for the one caller that cleared it. A run clears it when it starts (it
+     * covers every kick before it) and again after it succeeded, when `true` means one more run.
+     */
+    takePending(job: string): Promise<boolean>;
+    /**
+     * Claims one report of a job that has not succeeded within twice `periodMs`, at most once per period: only the
+     * caller that gets the claim reports.
+     */
+    claimOverdue(job: string, periodMs: number): Promise<OverdueClaim | null>;
+    /**
+     * Refuses every further write of the attempt `fence` names and cancels the statements it still has running; the
+     * runner calls it when the attempt ends.
+     */
+    cancelInFlight(fence: LeaseFence): Promise<void>;
+    state(job: string): Promise<JobLeaseState | null>;
+}
+/**
+ * The database's clock inside `session`'s transaction: a queue claim compares and moves `due` by it, so no process
+ * clock decides when a row is due.
+ */
+export declare function databaseNow(session: Session): Promise<Date>;
+/**
+ * Runs `work` in a mutation's transaction under `fence`. Before it: the attempt still holds its lease, the lease row
+ * stays locked `for share` until the commit (a takeover or a renewal waits), and every statement is bounded by the
+ * attempt's remaining time. After it, just before the commit: the attempt still holds the lease within its deadline.
+ * Otherwise the transaction rolls back with `LeaseLostError`; so does a statement the deadline or the runner cancelled.
+ */
+export declare function fencedTransaction<T>(session: Session, fence: LeaseFence, work: (transaction: Session) => Promise<T>): Promise<T>;
+export declare function jobLeases(runtime: () => DataLayerRuntime): JobLeases;

package/types/src/links.d.ts

@@ -0,0 +1,13 @@
+import type { OperationNode } from 'kysely';
+import type { RefGrant } from './capability';
+import type { Container } from './policy';
+export interface LinkValue {
+    readonly link: Container;
+    readonly value: string;
+}
+/**
+ * The column values a Ref addresses over `links`: the first link takes the Ref's id, every other link a value
+ * from its chain. A chain entry no link covers cannot be enforced, so it is refused rather than ignored.
+ */
+export declare function linkValues(table: string, links: readonly Container[], grant: RefGrant): readonly LinkValue[];
+export declare function linksPredicate(table: string, values: readonly LinkValue[]): OperationNode;

package/types/src/migrations.d.ts

@@ -0,0 +1,25 @@
+/** Migration identity of the framework's tables in every application schema: bundle `fabrika`, same ledger. */
+export declare const FRAMEWORK_MIGRATION_BUNDLE = "fabrika";
+export declare const WEBHOOK_BINDINGS_TABLE = "fabrika_webhook_bindings";
+export declare const WEBHOOK_DELIVERIES_TABLE = "fabrika_webhook_deliveries";
+export declare const JOB_LEASES_TABLE = "fabrika_job_leases";
+export declare const JOB_KICKS_TABLE = "fabrika_job_kicks";
+export declare const FORM_ADMISSIONS_TABLE = "fabrika_form_admissions";
+export declare const FORM_CHALLENGES_TABLE = "fabrika_form_challenges";
+export declare const FORM_FILES_TABLE = "fabrika_form_files";
+export declare const FORM_BYTES_TABLE = "fabrika_form_bytes";
+export declare const FILES_TABLE = "fabrika_files";
+export declare const FILE_DELETIONS_TABLE = "fabrika_file_deletions";
+/** The function an application's last adoption migration calls with the name of a file collection it adopted. */
+export declare const FILES_RELEASE_FUNCTION = "fabrika_files_release";
+/**
+ * The function an adoption migration calls right before it reads a collection's table: it copies the rows an older
+ * instance wrote since 0008 ran, so each one it adopts has its `fabrika_files` row. Idempotent.
+ */
+export declare const FILES_COPY_FUNCTION = "fabrika_files_copy_legacy";
+export interface FrameworkMigration {
+    /** Ordered by name; an applied one is immutable, like an application's. */
+    readonly name: string;
+    readonly sql: string;
+}
+export declare const FRAMEWORK_MIGRATIONS: readonly FrameworkMigration[];

package/types/src/nodes.d.ts

@@ -0,0 +1,62 @@
+import { type DeleteQueryNode, type InsertQueryNode, type OperationNode, ReferenceNode, ReturningNode, type SelectQueryNode, type UpdateQueryNode, WhereNode } from 'kysely';
+import { type NameSet } from './builtins';
+import type { Condition, Primitive, SelectState } from './description';
+export declare function column(table: string, name: string): ReferenceNode;
+export declare function equals(table: string, name: string, value: Primitive): OperationNode;
+export declare function allOf(nodes: readonly OperationNode[]): OperationNode;
+/** One node, or the OR of several in a parenthesis: inside an AND, `a and b or c` would read as `(a and b) or c`. */
+export declare function anyOf(nodes: readonly OperationNode[]): OperationNode;
+export declare function inList(table: string, name: string, values: readonly string[]): OperationNode;
+/** The scope of a `Within` that is not limited to scope values. */
+export declare function everything(): OperationNode;
+/** LIKE treats `\` as its escape character by default, so the text matches literally. */
+export declare function containsPattern(text: string): string;
+/**
+ * The caller's conditions go inside an explicit parenthesis and the scope is the top-level right conjunct, so
+ * `x or true` cannot escape it. The guard checks this shape.
+ */
+export declare function scopedWhere(conditions: OperationNode | undefined, scope: OperationNode): WhereNode;
+/** `returning key as id[, version as version]`: a mutation's acknowledgement, never row data. */
+export declare function acknowledgement(table: string, key: string, version: string | undefined): ReturningNode;
+/** `after` is a keyset page's position, ANDed to the caller's conditions inside their parenthesis. */
+export declare function selectNode(state: SelectState, visible: readonly string[], scope: OperationNode, after?: OperationNode, days?: NameSet): SelectQueryNode;
+export interface AggregateColumns {
+    readonly groupBy: readonly string[];
+    readonly count: boolean;
+    readonly sum: readonly string[];
+    readonly min: readonly string[];
+    readonly max: readonly string[];
+}
+export declare function aggregateNode(table: string, columns: AggregateColumns, conditions: readonly Condition[], scope: OperationNode, days?: NameSet): SelectQueryNode;
+/** `conflict` names the columns of a unique index the insert does nothing on: `on conflict (<columns>) do nothing`. */
+export declare function insertNode(table: string, values: ReadonlyMap<string, Primitive | null>, answer: ReturningNode, conflict?: readonly string[]): InsertQueryNode;
+export declare function updateNode(table: string, values: ReadonlyMap<string, Primitive | null>, bump: string | undefined, where: WhereNode, answer: ReturningNode): UpdateQueryNode;
+export declare function deleteNode(table: string, where: WhereNode, key: string): DeleteQueryNode;
+/** `select key from table where (conditions) and scope limit 1`: does the scoped object exist? */
+export declare function existsNode(table: string, key: string, scope: OperationNode, conditions?: OperationNode): SelectQueryNode;
+/** `select key as id, version as version from table where (conditions) and scope limit 1`: an update that sets nothing. */
+export declare function acknowledgementNode(table: string, key: string, version: string | undefined, where: WhereNode): SelectQueryNode;
+/** `select columns from table where scope limit 1`: the containment columns of one object, for the framework's locator. */
+export declare function locateNode(table: string, columns: readonly string[], scope: OperationNode): SelectQueryNode;
+/**
+ * The same check, locked: `for share` keeps the row from moving until the transaction that checked it ends, `for
+ * update` also keeps every other writer and locker of it waiting.
+ */
+export declare function lockNode(table: string, key: string, scope: OperationNode, lock?: 'share' | 'update'): SelectQueryNode;
+/** The alias a keyset page's position column is selected under; a column name holds no dot, so none collides. */
+export declare function cursorAlias(index: number): string;
+/** `select …, cast(<column> as text) as "keyset.c<n>"`: each order column's exact value, which a Date would round. */
+export declare function withCursorColumns(node: SelectQueryNode, table: string, columns: readonly string[]): SelectQueryNode;
+/**
+ * A queue claim's lease: `select <columns> from table where (<conditions> and (<due> is not null and <due> <= $now and
+ * <attempts> < $max)) and scope order by <due>, <key> limit $n for update skip locked`. A row another claim holds is
+ * skipped, never waited for.
+ */
+export declare function claimNode(state: SelectState, columns: readonly string[], due: {
+    readonly due: string;
+    readonly attempts: string;
+    readonly now: Date;
+    readonly maxAttempts: number;
+}, scope: OperationNode, days: NameSet): SelectQueryNode;
+/** `select <columns> from table where scope for update`: a mutation's precondition read of its own target. */
+export declare function lockedSelectNode(table: string, columns: readonly string[], scope: OperationNode, days?: NameSet): SelectQueryNode;