@fabrika/db 0.6.0 → 0.8.0

package/src/orm-types.ts

@@ -3,7 +3,9 @@
 // may not call is an `Unavailable` tuple: calling it fails at the call, and the message names the fix.
 
 import type { Selectable, Updateable } from 'kysely'
+import type { RowRef } from './capability'
 import type { ConditionTuple } from './description'
+import type { FileReference } from './file-references'
 import type {
 	ActionOf,
 	ApplicationTableName,
@@ -37,7 +39,7 @@ type ModeOf<P, T> = PolicyOf<P, T> extends { readonly scope: infer S } ? S exten
 	: S extends { readonly child: string } ? 'child'
 	: S extends { readonly app: string } ? 'app'
 	: S extends { readonly reference: string } ? 'reference'
-	: 'inbox'
+	: never
 	: never
 
 /** The actions a table's `actions.appRead` or `actions.appCount` lists; `never` when it lists none. */
@@ -45,8 +47,6 @@ type AppActionsOf<P, T, F extends 'appRead' | 'appCount'> = PolicyOf<P, T> exten
 	{ readonly actions: { readonly [K in F]: readonly (infer A extends string)[] } } ? A
 	: never
 
-type ReadActionOf<P, T> = PolicyOf<P, T> extends { readonly scope: { readonly read: infer A extends string } } ? A : ActionOf<P, T, 'read'>
-
 /** Each column that declares its own read action, by column. */
 type ColumnReadsOf<P, T> = PolicyOf<P, T> extends { readonly columns: infer C } ? {
 		readonly [K in keyof C as C[K] extends { readonly read: string } ? K : never]: C[K] extends { readonly read: infer A extends string } ? A : never
@@ -74,7 +74,7 @@ type ColumnWriteAction<C> = { [K in keyof C]: C[K] extends { readonly write: inf
 
 /** One table, as every handle reads it. */
 export interface IndexedTable {
-	readonly mode: 'dimension' | 'child' | 'app' | 'reference' | 'inbox'
+	readonly mode: 'dimension' | 'child' | 'app' | 'reference'
 	/** The dimension a dimension table owns. */
 	readonly dimension: string
 	/** The dimension its rows are listed and inserted in: the container's, or a top-level table's own. */
@@ -101,6 +101,8 @@ export interface IndexedTable {
 	/** The dimensions whose `Within` lists the table: every dimension of its chain, and a top-level table's own. */
 	readonly reach: string
 	readonly versioned: boolean
+	/** A queue table: its rows are claimed and finished through `row.ref`. */
+	readonly queued: boolean
 }
 
 type IndexedTableOf<DB, P, T extends keyof P & keyof DB & string, V = unknown> = {
@@ -109,22 +111,23 @@ type IndexedTableOf<DB, P, T extends keyof P & keyof DB & string, V = unknown> =
 	readonly list: ListDimensionOf<P, T>
 	readonly parent: ParentOf<P, T>
 	readonly actions: {
-		readonly read: ReadActionOf<P, T>
+		readonly read: ActionOf<P, T, 'read'>
 		readonly insert: ActionOf<P, T, 'insert'>
 		readonly update: ActionOf<P, T, 'update'>
 		readonly delete: ActionOf<P, T, 'delete'>
 	}
 	readonly appRead: AppActionsOf<P, T, 'appRead'>
 	readonly appCount: AppActionsOf<P, T, 'appCount'>
-	readonly row: RowType<DB[T]>
+	readonly row: WithFiles<RowType<DB[T]>, FileColumnsOf<P, T>>
 	readonly reads: ColumnReadsOf<P, T>
-	readonly insert: InsertValues<DB, P, T>
-	readonly update: UpdateValues<DB, P, T>
-	readonly writes: UpdatesOf<DB, P, T>
+	readonly insert: WithFiles<InsertValues<DB, P, T>, FileColumnsOf<P, T>>
+	readonly update: WithFiles<UpdateValues<DB, P, T>, FileColumnsOf<P, T>>
+	readonly writes: { readonly [A in keyof UpdatesOf<DB, P, T>]: WithFiles<UpdatesOf<DB, P, T>[A], FileColumnsOf<P, T>> }
 	readonly chain: ChainColumns<P, T, V>
 	readonly refs: DimensionOf<P, T> | ChainDimensions<P, T, V>
 	readonly reach: ReachOf<P, T, V>
 	readonly versioned: PolicyOf<P, T> extends { readonly version: string } ? true : false
+	readonly queued: PolicyOf<P, T> extends { readonly queue: object } ? true : false
 }
 
 type OwnerTable<P, D> = { [K in keyof P]: P[K] extends { readonly scope: { readonly dimension: D } } ? K : never }[keyof P]
@@ -162,6 +165,13 @@ type ReachOf<P, T, V> = [ContainerOf<P, T>] extends [never] ? DimensionOf<P, T>
  */
 type RowType<R> = [R] extends [Selectable<R>] ? [Selectable<R>] extends [R] ? R : Selectable<R> : Selectable<R>
 
+/** The file columns of table `T`'s policy (`files: { <column>: '<kind>' }`). */
+type FileColumnsOf<P, T> = PolicyOf<P, T> extends { readonly files: infer F } ? keyof F & string : never
+
+/** A row or write of a table with file columns: each holds a file reference, `null` where the column is nullable. */
+type WithFiles<R, Files extends string> = [Files] extends [never] ? R
+	: { [K in keyof R]: K extends Files ? (null extends R[K] ? FileReference | null : FileReference) : R[K] }
+
 type ReferenceTableName<P> = { [K in keyof P]: P[K] extends { readonly scope: { readonly reference: string } } ? K : never }[keyof P] & string
 
 /**
@@ -225,6 +235,66 @@ export type Saved<E extends IndexedTable> = E['versioned'] extends true ? { read
 /** A versioned table's update and remove take `{ expectVersion }`; another table's take nothing. */
 export type VersionArguments<E extends IndexedTable> = E['versioned'] extends true ? [options: { readonly expectVersion: number }] : []
 
+/** The values an insert takes: the columns of the table's `insert` list. */
+type InsertValuesOf<E extends IndexedTable> = { [C in keyof E['insert']]: E['insert'][C] }
+
+/** `onConflict` of an insert: the columns of a unique index the migrations create, and what a conflict does. */
+export interface InsertConflict<E extends IndexedTable, M extends 'nothing' | 'update'> {
+	readonly onConflict: { readonly columns: readonly (keyof E['row'] & string)[]; readonly do: M }
+}
+
+/**
+ * An insert: with `onConflict`, a conflict of its columns writes nothing (`'nothing'`, which answers `{ inserted: false }`)
+ * or updates the conflicting row's update columns (`'update'`, which also needs the table's update action).
+ */
+export interface InsertMethod<E extends IndexedTable> {
+	(values: InsertValuesOf<E>, options: InsertConflict<E, 'nothing'>): Promise<(Saved<E> & { readonly inserted: true }) | { readonly inserted: false }>
+	(values: InsertValuesOf<E>, options: InsertConflict<E, 'update'>): Promise<Saved<E> & { readonly inserted: boolean }>
+	// Last, so `Parameters` and `ReturnType`, which read the last signature, read the plain insert.
+	(values: InsertValuesOf<E>): Promise<Saved<E>>
+}
+
+/** What a claim takes: how many rows to lease, at most `MAX_LIST_LIMIT`, and conditions on the columns its action reads. */
+export interface ClaimOptions<Row> {
+	readonly limit: number
+	readonly where?: readonly ConditionTuple<Row>[]
+}
+
+/** A claimed row: the columns of the claim's action, its new `version`, and `ref`, which `tx.db.on(ref)` finishes it through. */
+export type ClaimedRow<T extends string, E extends IndexedTable, A extends string> =
+	& RowFor<E, A>
+	& { readonly version: number; readonly ref: RowRef<T, A> }
+
+type ClaimRefusal<K extends DataKind> = K extends 'query' ? 'claim leases rows, so it runs only in a job'
+	: 'claim leases rows in a transaction of its own: a job calls it on ctx.db before ctx.transaction, never inside one or in a request'
+
+/** `claim` of a queue table, in a job, for a capability of its update action. */
+type Claim<T extends string, E extends IndexedTable, A extends string, K extends DataKind> = K extends 'job'
+	? E['queued'] extends true ? [A] extends [E['actions']['update']] ? (options: ClaimOptions<RowFor<E, A>>) => Promise<ClaimedRow<T, E, A>[]>
+		: Unavailable<`a claim of ${T} needs its update action '${E['actions']['update'] & string}', and this capability holds '${A}'`>
+	: Unavailable<`${T} is not a queue table: declare queue: { attempts, due } in its policy`>
+	: Unavailable<ClaimRefusal<K>>
+
+type JobWrite = Unavailable<'a job writes inside ctx.transaction((tx) => …): use tx.db there'>
+
+/**
+ * `tx.db.on(row.ref)`: one claimed row, finished in the job's transaction. `update` writes the claim action's columns and,
+ * with `done: true`, clears `due`; `remove` needs the table's delete action; `requeue` makes the row due again at `at`
+ * (now by default) with no attempts.
+ */
+export interface ClaimedRowHandle<T extends string, E extends IndexedTable, A extends string, K extends DataKind> {
+	readonly update: K extends 'mutation' ? (
+			values: { [C in keyof UpdateValuesOf<E, A>]: UpdateValuesOf<E, A>[C] },
+			options: { readonly expectVersion: number; readonly done?: boolean },
+		) => Promise<Saved<E>>
+		: JobWrite
+	readonly remove: K extends 'mutation' ? [A] extends [E['actions']['delete']] ? (options: { readonly expectVersion: number }) => Promise<void>
+		: [E['actions']['delete']] extends [never] ? Unavailable<`${T} allows no remove: its policy declares no delete action`>
+		: Unavailable<`remove of a claimed ${T} row needs its delete action '${E['actions']['delete'] & string}', and this row was claimed with '${A}'`>
+		: JobWrite
+	readonly requeue: K extends 'mutation' ? (options?: { readonly at?: Date | string }) => Promise<Saved<E>> : JobWrite
+}
+
 /** The actions table `E` names: its read, insert, update and delete actions, and each column's own write action. */
 type NamedActions<E extends IndexedTable> = (E['actions'][keyof E['actions']] | keyof E['writes']) & string
 
@@ -305,7 +375,7 @@ export interface TargetRow<T extends string, E extends IndexedTable, A extends s
  * by the scope's value.
  */
 export interface OwnerRow<T extends string, E extends IndexedTable, A extends string, K extends DataKind> {
-	readonly insert: Write<T, E, 'insert', A, K, (values: { [C in keyof E['insert']]: E['insert'][C] }) => Promise<Saved<E>>>
+	readonly insert: Write<T, E, 'insert', A, K, InsertMethod<E>>
 }
 
 /** A dimension no table owns has no row of its own; its subtree tables are still reachable. */
@@ -320,7 +390,7 @@ export interface UnownedTarget<D extends string> {
 export interface ChildRows<T extends string, E extends IndexedTable, A extends string, K extends DataKind> {
 	readonly list: Read<T, E, A, (options?: ListOptions<RowFor<E, A>>) => Promise<ListPage<RowFor<E, A>>>>
 	readonly get: Read<T, E, A, (key: string) => Promise<RowFor<E, A>>>
-	readonly insert: Write<T, E, 'insert', A, K, (values: { [C in keyof E['insert']]: E['insert'][C] }) => Promise<Saved<E>>>
+	readonly insert: Write<T, E, 'insert', A, K, InsertMethod<E>>
 	readonly update: Update<
 		T,
 		E,
@@ -334,7 +404,7 @@ export interface ChildRows<T extends string, E extends IndexedTable, A extends s
 /** A dimension table the target contains: listed in it, and inserted into it by a mutation of its insert action. */
 export interface ContainedRows<T extends string, E extends IndexedTable, A extends string, K extends DataKind> {
 	readonly list: Read<T, E, A, (options?: ListOptions<RowFor<E, A>>) => Promise<ListPage<RowFor<E, A>>>>
-	readonly insert: Write<T, E, 'insert', A, K, (values: { [C in keyof E['insert']]: E['insert'][C] }) => Promise<Saved<E>>>
+	readonly insert: Write<T, E, 'insert', A, K, InsertMethod<E>>
 }
 
 type SubtreeTables<Ix extends AnyDbIndex, D extends string, A extends string, K extends DataKind, F extends TargetForm> =
@@ -350,8 +420,9 @@ export type ScopeTarget<Ix extends AnyDbIndex, D extends string, A extends strin
 	& ([OwnerOf<Ix, D>] extends [never] ? UnownedTarget<D> : TargetRow<OwnerOf<Ix, D>, Ix['tables'][OwnerOf<Ix, D>], A, K, F>)
 	& SubtreeTables<Ix, D, A, K, F>
 
-/** A table listed in an `over` endpoint's dimension, read through its `Within`. */
-export interface WithinRows<T extends string, E extends IndexedTable, A extends string> {
+/** A table listed in an `over` endpoint's dimension, read through its `Within`; a job claims a queue table's rows through it. */
+export interface WithinRows<T extends string, E extends IndexedTable, A extends string, K extends DataKind> {
+	readonly claim: Claim<T, E, A, K>
 	readonly list: A extends E['actions']['read'] ? (options?: ListOptions<RowFor<E, A>>) => Promise<ListPage<RowFor<E, A>>>
 		: Unavailable<ListRefusal<T, E, A>>
 	readonly count: A extends E['actions']['read'] ? (options?: CountOptions<RowFor<E, A>>) => Promise<number> : Unavailable<ListRefusal<T, E, A>>
@@ -369,8 +440,8 @@ type ListRefusal<T extends string, E extends IndexedTable, A extends string> = `
  * `ctx.db.within` of an `over` endpoint: every table whose containment chain holds its dimension (tasks two levels
  * down through their stamped `org_id`), and a top-level table its own; child tables included.
  */
-export type WithinTables<Ix extends AnyDbIndex, D extends string, A extends string> = {
-	readonly [T in WithinIn<Ix, D>]: WithinRows<T, Ix['tables'][T], A>
+export type WithinTables<Ix extends AnyDbIndex, D extends string, A extends string, K extends DataKind> = {
+	readonly [T in WithinIn<Ix, D>]: WithinRows<T, Ix['tables'][T], A, K>
 }
 
 /** An application table under the capability of an `app` endpoint of action `A`, in a site of kind `K`. */
@@ -387,7 +458,9 @@ export interface ApplicationRows<T extends string, E extends IndexedTable, A ext
 	readonly getForUpdate: K extends 'mutation' ? Read<T, E, A, (key: string) => Promise<RowFor<E, A>>>
 		: K extends 'job' ? Unavailable<'a job writes inside ctx.transaction((tx) => …): use tx.db there'>
 		: Unavailable<'getForUpdate locks the row, so it runs only in a mutation: declare the endpoint with r.mutation'>
-	readonly insert: Write<T, E, 'insert', A, K, (values: { [C in keyof E['insert']]: E['insert'][C] }) => Promise<Saved<E>>>
+	/** Leases due rows of a queue table: a job's drain, before its transactions. */
+	readonly claim: Claim<T, E, A, K>
+	readonly insert: Write<T, E, 'insert', A, K, InsertMethod<E>>
 	readonly update: Update<
 		T,
 		E,
@@ -398,6 +471,59 @@ export interface ApplicationRows<T extends string, E extends IndexedTable, A ext
 	readonly remove: Write<T, E, 'delete', A, K, (key: string, ...version: VersionArguments<E>) => Promise<void>>
 }
 
+/**
+ * A public procedure's insert: it answers the new row's key (and version), which the data layer generated, and reads
+ * no column back; a conflict of `onConflict`'s columns writes nothing.
+ */
+export interface PublicInsertMethod<E extends IndexedTable> {
+	(values: InsertValuesOf<E>, options: InsertConflict<E, 'nothing'>): Promise<(Saved<E> & { readonly inserted: true }) | { readonly inserted: false }>
+	(values: InsertValuesOf<E>): Promise<Saved<E>>
+}
+
+type PublicRefusal<Op extends string> = Unavailable<`a public procedure does not ${Op} a row: it inserts, and reads under the table's read action`>
+
+/** A public procedure updates and removes only a versioned row, by an id a verified signed token of its request carries. */
+type PublicVersioned<T extends string, E extends IndexedTable, Member> = E['versioned'] extends true ? Member
+	: Unavailable<`a public procedure updates and removes only a versioned row: declare version in the policy of ${T}`>
+
+/**
+ * An application table of a public procedure of action `A`, in a site of kind `K`: read under its read action only,
+ * inserted with nothing read back, and updated or removed only by the id a verified signed token of the request carries,
+ * under `expectVersion`; never locked or claimed.
+ */
+export interface PublicApplicationRows<T extends string, E extends IndexedTable, A extends string, K extends DataKind> {
+	readonly list: ApplicationRows<T, E, A, K>['list']
+	readonly count: ApplicationRows<T, E, A, K>['count']
+	readonly aggregate: ApplicationRows<T, E, A, K>['aggregate']
+	readonly get: A extends E['actions']['read'] ? (key: string) => Promise<RowFor<E, A>> : Unavailable<ListRefusal<T, E, A>>
+	readonly getForUpdate: PublicRefusal<'lock'>
+	readonly claim: PublicRefusal<'claim'>
+	/** By the id a verified signed token of the request carries; answers only the new version. */
+	readonly update: PublicVersioned<
+		T,
+		E,
+		Update<
+			T,
+			E,
+			A,
+			K,
+			(
+				key: string,
+				values: { [C in keyof UpdateValuesOf<E, A>]: UpdateValuesOf<E, A>[C] },
+				options: { readonly expectVersion: number },
+			) => Promise<{ readonly version: number }>
+		>
+	>
+	/** By the id a verified signed token of the request carries. */
+	readonly remove: PublicVersioned<T, E, Write<T, E, 'delete', A, K, (key: string, options: { readonly expectVersion: number }) => Promise<void>>>
+	readonly insert: Write<T, E, 'insert', A, K, PublicInsertMethod<E>>
+}
+
+/** `ctx.db.app('<action>')` of a public procedure: the application tables only, each as `PublicApplicationRows`. */
+export type PublicApplicationTables<Ix extends AnyDbIndex, A extends string, K extends DataKind> = {
+	readonly [T in Ix['applications']]: PublicApplicationRows<T, Ix['tables'][T], A, K>
+}
+
 /**
  * A dimension or child table under an `app` endpoint of action `A`: every row read-only, with the columns `A` reads
  * (`RowFor`), or only how many rows match. A count-only action has no `aggregate`: a group or a minimum is a value.
@@ -477,30 +603,28 @@ export type UnscopedMode = 'read' | 'write'
 export type UnscopedDeclaration<Table extends string, Mode extends UnscopedMode> = { readonly [T in Table]?: Mode }
 
 /**
- * The tables of `U` whose mode may be `'write'` that no site writes: a reference table and a form's inbox. A union or
- * optional mode that admits `'write'` counts, because the declaration it types may hold it.
+ * The tables of `U` whose mode may be `'write'` that no site writes: a reference table. A union or optional mode that
+ * admits `'write'` counts, because the declaration it types may hold it.
  */
 type ReadOnlyWritten<Ix extends AnyDbIndex, U> = {
-	[T in keyof U & TableName<Ix>]: 'write' extends U[T] ? Ix['tables'][T]['mode'] extends 'reference' | 'inbox' ? T : never : never
+	[T in keyof U & TableName<Ix>]: 'write' extends U[T] ? Ix['tables'][T]['mode'] extends 'reference' ? T : never : never
 }[keyof U & TableName<Ix>]
 
-type ReadOnlyMessage<T extends string, Mode> = Mode extends 'reference'
-	? `${T} is a reference table, which no site writes: its rows come from a migration, so declare unscoped: { ${T}: 'read' }`
-	: `${T} is a form's inbox, which only its form writes: declare unscoped: { ${T}: 'read' }`
+type ReadOnlyMessage<T extends string> =
+	`${T} is a reference table, which no site writes: its rows come from a migration, so declare unscoped: { ${T}: 'read' }`
 
-/** An `unscoped` declaration's `'write'` of a read-only table, refused at its own line. */
+/** An `unscoped` declaration's `'write'` of a reference table, refused at its own line. */
 export type ReadOnlyUnscoped<Ix extends AnyDbIndex, U> = [ReadOnlyWritten<Ix, U>] extends [never] ? unknown
-	: { readonly [T in ReadOnlyWritten<Ix, U>]: Unavailable<ReadOnlyMessage<T, Ix['tables'][T]['mode']>> }
+	: { readonly [T in ReadOnlyWritten<Ix, U>]: Unavailable<ReadOnlyMessage<T>> }
 
-type KeylessMessage<T extends string, Mode> = Mode extends 'reference' ? `${T} is a reference table, which has no key: read it with list`
-	: `${T} is a form's inbox, which has no key: read it with list`
+type KeylessMessage<T extends string> = `${T} is a reference table, which has no key: read it with list`
 
 /** A table a site declared `unscoped`: its scope predicate is `true`, and `'read'` writes nothing. */
 export interface UnscopedRows<T extends string, E extends IndexedTable, M extends UnscopedMode, K extends DataKind> {
 	list(options?: ListOptions<TableRow<E>>): Promise<ListPage<TableRow<E>>>
 	count(options?: CountOptions<TableRow<E>>): Promise<number>
 	aggregate<const S extends AggregateSpec<TableRow<E>>>(spec: S): Promise<AggregateRow<TableRow<E>, S>[]>
-	readonly get: E['mode'] extends 'reference' | 'inbox' ? Unavailable<KeylessMessage<T, E['mode']>> : (key: string) => Promise<TableRow<E>>
+	readonly get: E['mode'] extends 'reference' ? Unavailable<KeylessMessage<T>> : (key: string) => Promise<TableRow<E>>
 	readonly insert: UnscopedWrite<T, M, K, 'insert', (values: { [C in keyof UnscopedInsert<E>]: UnscopedInsert<E>[C] }) => Promise<Saved<E>>>
 	readonly update: UnscopedWrite<
 		T,