@fabrika/db 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/db",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -61,8 +61,8 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "^0.4.0",
-		"@fabrika/platform-node": "^0.4.0",
+		"@fabrika/auth-core": "^0.4.1",
+		"@fabrika/platform-node": "^0.4.1",
 		"kysely": "0.29.6",
 		"kysely-postgres-js": "5.0.1",
 		"zod": "^3.25.76"

package/src/orm-types.ts

@@ -561,8 +561,13 @@ type RefFragment<Ix extends AnyDbIndex, D extends string, A extends string> = {
 		: never
 }[TableName<Ix>]
 
-/** What a `Within` writes on a `'write'` site: the target of an UPDATE or DELETE whose action it holds. */
-type WithinWrites<E extends IndexedTable, M extends 'read' | 'write'> = M extends 'write' ? E['actions']['update'] | E['actions']['delete'] : never
+/**
+ * What a `Within` writes on a `'write'` site: the target of an UPDATE or DELETE whose action it holds, a column's own
+ * write action included (the statement's SET is checked against its columns at run time).
+ */
+type WithinWrites<E extends IndexedTable, M extends 'read' | 'write'> = M extends 'write'
+	? E['actions']['update'] | E['actions']['delete'] | (keyof E['writes'] & string)
+	: never
 
 /** The tables a fragment of a `Within` of `D` and `A` reaches: those it lists by their read action, or writes on `M`. */
 type WithinFragment<Ix extends AnyDbIndex, D extends string, A extends string, M extends 'read' | 'write'> = {

package/src/orm.ts

@@ -125,11 +125,11 @@ export function dataAccess(parts: DataLayerParts): DataAccess {
 			sqlTag(
 				site,
 				parts.runtime().database.schema,
-				(capability, table, use) => {
+				(capability, table, use, assigned) => {
 					if (!hasOwn(parts.models, table)) {
 						throw new QueryRefusedError('unknown_table', `ctx.sql.scope: ${table} is not a table of src/db/tables.ts`)
 					}
-					return scopeTerms(parts.contextOf(table), capability, use)
+					return scopeTerms(parts.contextOf(table), capability, use, assigned)
 				},
 				(table) => {
 					if (modelOf(parts.models, table)?.scope.mode === 'reference') {

package/src/sql.ts

@@ -46,9 +46,10 @@ export type ScopeUse = 'read' | 'update' | 'delete'
 
 /**
  * The scope of `capability` on `table` for `use`, as the data layer predicates its handles; throws when it does not
- * reach it for that use.
+ * reach it for that use. `assigned` is the columns an UPDATE's SET names (none when the SET cannot be read with
+ * certainty), and `undefined` before a statement is known.
  */
-export type ScopeOf = (capability: unknown, table: string, use: ScopeUse) => ScopeTerms
+export type ScopeOf = (capability: unknown, table: string, use: ScopeUse, assigned?: readonly string[]) => ScopeTerms
 
 /** The operation a write statement performs on one of its targets. */
 export type WriteOperation = 'insert' | 'update' | 'delete'
@@ -392,11 +393,13 @@ interface Target {
 	readonly operation: WriteOperation
 }
 
-/** The relation an UPDATE or DELETE writes: its table, under its alias (the table's name without one). */
+/** The relation an UPDATE or DELETE writes: its table, under its alias (the table's name without one), and what it sets. */
 interface Written {
 	readonly table: string
 	readonly alias: string
 	readonly operation: 'update' | 'delete'
+	/** The columns an UPDATE's SET assigns; none for a DELETE. */
+	readonly assigned: readonly string[]
 }
 
 /** What a statement writes, and for each interpolation, in order, the UPDATE or DELETE of the query block it stands in. */
@@ -466,22 +469,140 @@ function statementWrites(tokens: readonly SqlToken[]): StatementWrites {
 			}
 		} else if (word === 'DELETE' && next === 'FROM') {
 			const target = targetAt(tokens, index + 2)
-			enter(target === undefined ? undefined : { ...target, operation: 'delete' })
+			enter(target === undefined ? undefined : { ...target, operation: 'delete', assigned: [] })
 			if (target !== undefined) targets.push({ table: target.table, operation: 'delete' })
 		} else if (word === 'UPDATE') {
 			const before = upperWord(tokens[index - 1])
 			if (before === 'FOR' || before === 'KEY') continue
 			const target = before === 'DO' ? inserts.get(depth) : targetAt(tokens, index + 1)
-			enter(target === undefined ? undefined : { ...target, operation: 'update' })
+			enter(target === undefined ? undefined : { ...target, operation: 'update', assigned: assignedColumns(tokens, index + 1) })
 			if (target !== undefined) targets.push({ table: target.table, operation: 'update' })
 		}
 	}
 	return { targets, blocks }
 }
 
+/** Words that end an UPDATE's SET list at its own depth, outside a CASE; `IS [NOT] DISTINCT FROM` does not. */
+const SET_ENDS: ReadonlySet<string> = new Set(['FROM', 'WHERE', 'RETURNING'])
+
+/**
+ * The columns the SET of the UPDATE whose target starts at `from` assigns: `a = …` and `(a, b) = …` items, a column's
+ * subfield or subscript by the column. A SET it cannot read to its end with certainty assigns no column it can name,
+ * which refuses a column's own write action: an item that is not a name, an unmatched bracket, a CASE without END.
+ */
+function assignedColumns(tokens: readonly SqlToken[], from: number): readonly string[] {
+	const set = setKeyword(tokens, from)
+	if (set === undefined) return []
+	const columns: string[] = []
+	let index = set + 1
+	for (;;) {
+		const item = assignmentTarget(tokens, index)
+		const end = item === undefined ? undefined : expressionEnd(tokens, item.equals + 1)
+		if (item === undefined || end === undefined) return []
+		columns.push(...item.columns)
+		if (!isPunct(tokens[end], ',')) return columns
+		index = end + 1
+	}
+}
+
+/**
+ * The index of what ends the assigned expression that starts at `index`: the `,` before the next item, or the end of the
+ * SET list (`FROM`, `WHERE`, `RETURNING`, the `)` around the statement, `;`, the end of the text). A clause word inside
+ * brackets or a CASE, and the `FROM` of `IS [NOT] DISTINCT FROM`, belong to the expression. `undefined` when a bracket
+ * or a CASE does not close before the end.
+ */
+function expressionEnd(tokens: readonly SqlToken[], index: number): number | undefined {
+	let depth = 0
+	let cases = 0
+	for (let position = index; position < tokens.length; position++) {
+		const token = tokens[position]
+		const word = upperWord(token)
+		if (isPunct(token, '(') || isPunct(token, '[')) {
+			depth++
+		} else if (isPunct(token, ')') || isPunct(token, ']')) {
+			if (--depth < 0) return cases === 0 && isPunct(token, ')') ? position : undefined
+		} else if (depth > 0) {
+			continue
+		} else if (word === 'CASE') {
+			cases++
+		} else if (word === 'END') {
+			if (--cases < 0) return undefined
+		} else if (isPunct(token, ',') || isPunct(token, ';')) {
+			return cases === 0 ? position : undefined
+		} else if (cases === 0 && word !== undefined && SET_ENDS.has(word) && !distinctFrom(tokens, position)) {
+			return position
+		}
+	}
+	return depth === 0 && cases === 0 ? tokens.length : undefined
+}
+
+/** The index of the SET of the UPDATE whose target starts at `from`, at the UPDATE's depth. */
+function setKeyword(tokens: readonly SqlToken[], from: number): number | undefined {
+	let depth = 0
+	for (let index = from; index < tokens.length; index++) {
+		const token = tokens[index]
+		const word = upperWord(token)
+		if (depth === 0 && word === 'SET') return index
+		if (isPunct(token, '(')) depth++
+		if (isPunct(token, ')') && --depth < 0) return undefined
+		if (depth === 0 && word !== undefined && SET_ENDS.has(word)) return undefined
+	}
+	return undefined
+}
+
+/** Whether the `FROM` at `index` ends `IS [NOT] DISTINCT FROM`, a comparison, not a clause. */
+function distinctFrom(tokens: readonly SqlToken[], index: number): boolean {
+	if (upperWord(tokens[index]) !== 'FROM' || upperWord(tokens[index - 1]) !== 'DISTINCT') return false
+	const before = upperWord(tokens[index - 2])
+	return before === 'IS' || (before === 'NOT' && upperWord(tokens[index - 3]) === 'IS')
+}
+
+/**
+ * The columns one SET item at `index` assigns and the index of its `=`: a name with any `.field` and `[…]` after it,
+ * or a parenthesized list of them. `undefined` when the item has no such form.
+ */
+function assignmentTarget(tokens: readonly SqlToken[], index: number): { readonly columns: readonly string[]; readonly equals: number } | undefined {
+	if (!isPunct(tokens[index], '(')) {
+		const name = nameText(tokens[index])
+		if (name === undefined) return undefined
+		const equals = afterIndirection(tokens, index + 1)
+		return equals !== undefined && isPunct(tokens[equals], '=') ? { columns: [name], equals } : undefined
+	}
+	const columns: string[] = []
+	let position = index
+	do {
+		const name = nameText(tokens[position + 1])
+		const next = name === undefined ? undefined : afterIndirection(tokens, position + 2)
+		if (name === undefined || next === undefined) return undefined
+		columns.push(name)
+		position = next
+	} while (isPunct(tokens[position], ','))
+	return isPunct(tokens[position], ')') && isPunct(tokens[position + 1], '=') ? { columns, equals: position + 1 } : undefined
+}
+
+/** The index past a column's `.field` and `[…]` subscripts from `index`, or `undefined` when a bracket never closes. */
+function afterIndirection(tokens: readonly SqlToken[], index: number): number | undefined {
+	let position = index
+	for (;;) {
+		if (isPunct(tokens[position], '.') && nameText(tokens[position + 1]) !== undefined) {
+			position += 2
+		} else if (isPunct(tokens[position], '[')) {
+			let depth = 0
+			for (; position < tokens.length; position++) {
+				if (isPunct(tokens[position], '[')) depth++
+				if (isPunct(tokens[position], ']') && --depth === 0) break
+			}
+			if (position >= tokens.length) return undefined
+			position++
+		} else {
+			return position
+		}
+	}
+}
+
 /** What a fragment on `table` under `alias` is to its block: the relation its UPDATE or DELETE writes, or else read. */
-function fragmentUse(written: Written | undefined, table: string, alias: string): ScopeUse {
-	return written !== undefined && written.table === table && written.alias === alias ? written.operation : 'read'
+function fragmentUse(written: Written | undefined, table: string, alias: string): Written | undefined {
+	return written !== undefined && written.table === table && written.alias === alias ? written : undefined
 }
 
 /** Words that open the clause a scope may stand in. */
@@ -640,7 +761,10 @@ function expandScopes(
 		if (fragment.site !== site) {
 			refuse('sql_scope', 'a ctx.sql.scope(…) of another invocation or site is refused; build it with this ctx.sql')
 		}
-		const terms = termsOf(fragment.capability, fragment.table, fragmentUse(writes.blocks[index], fragment.table, fragment.alias))
+		const written = fragmentUse(writes.blocks[index], fragment.table, fragment.alias)
+		const terms = written === undefined
+			? termsOf(fragment.capability, fragment.table, 'read')
+			: termsOf(fragment.capability, fragment.table, written.operation, written.assigned)
 		const rendered = scopeFragment(terms, fragment.alias)
 		expanded[expanded.length - 1] += rendered.parts[0] ?? ''
 		for (let position = 0; position < rendered.values.length; position++) {

package/src/store.ts

@@ -90,6 +90,7 @@ import {
 	type TableModels,
 	tableModels,
 	type Tables,
+	updatableBy,
 	updateActions,
 	type UpdateValues,
 	type VersionArguments,
@@ -340,9 +341,11 @@ export function reachPredicate(context: TableContext, capability: unknown): Oper
 
 /**
  * A fragment on an UPDATE or DELETE target: the capability's action is that operation's, and an application table is
- * written by an `app` capability only, a dimension or child table never by one.
+ * written by an `app` capability only, a dimension or child table never by one. An UPDATE may instead hold a column's
+ * own write action when every column it assigns declares that action (`updatingRef`'s rule); `assigned` is
+ * `undefined` before the statement is known, and then any such action is taken.
  */
-function checkWriteTarget(context: TableContext, grant: CapabilityGrant, use: 'update' | 'delete'): void {
+function checkWriteTarget(context: TableContext, grant: CapabilityGrant, use: 'update' | 'delete', assigned: readonly string[] | undefined): void {
 	const model = context.model
 	const statement = `${use === 'update' ? 'UPDATE' : 'DELETE'} of ${model.name}`
 	if (grant.kind === 'app' && model.scope.mode !== 'app') {
@@ -352,11 +355,39 @@ function checkWriteTarget(context: TableContext, grant: CapabilityGrant, use: 'u
 		throw new CapabilityError('table_kind', `a scoped site writes no application table: ${statement} needs the capability of an app endpoint`)
 	}
 	const action = model.actions[use]
-	if (action === undefined) {
+	if (grant.action === action) {
+		return
+	}
+	const columnWrites: string[] = []
+	const updates = use === 'update' ? updateActions(model) : []
+	for (let index = 0; index < updates.length; index++) {
+		const write = updates[index]
+		if (write !== undefined && write !== action) columnWrites[columnWrites.length] = write
+	}
+	if (action === undefined && columnWrites.length === 0) {
 		throw new CapabilityError('undeclared_operation', `${statement}: its policy declares no ${use} action`)
 	}
-	if (grant.action !== action) {
-		throw new CapabilityError('wrong_action', `${statement} needs its ${use} action ${action}; the capability holds ${grant.action}`)
+	if (!columnWrites.includes(grant.action)) {
+		const needs = action === undefined ? [] : [`its ${use} action ${action}`]
+		if (columnWrites.length > 0) needs[needs.length] = `a column's own write action (${columnWrites.join(', ')})`
+		throw new CapabilityError('wrong_action', `${statement} needs ${needs.join(' or ')}; the capability holds ${grant.action}`)
+	}
+	if (assigned === undefined) {
+		return
+	}
+	const written = updatableBy(model, grant.action)
+	const outside: string[] = assigned.length === 0 ? ['no column it can name'] : []
+	for (let index = 0; index < assigned.length; index++) {
+		const column = assigned[index]
+		if (column !== undefined && !inSet(written, column)) outside[outside.length] = column
+	}
+	if (outside.length > 0) {
+		throw new CapabilityError(
+			'wrong_action',
+			`${statement} assigns ${
+				outside.join(', ')
+			}, which ${grant.action} does not write: a column's own write action scopes an UPDATE of its columns only`,
+		)
 	}
 }
 
@@ -369,11 +400,11 @@ function checkWriteTarget(context: TableContext, grant: CapabilityGrant, use: 'u
  * and every link of the chain it carries; a `Within` matches like `ctx.db.within` (its values, each container grant on
  * its own column, or every row for `all`); an `app` capability, and a scoped read of an application table, every row.
  */
-export function scopeTerms(context: TableContext, capability: unknown, use: ScopeUse): ScopeTerms {
+export function scopeTerms(context: TableContext, capability: unknown, use: ScopeUse, assigned?: readonly string[]): ScopeTerms {
 	const grant = runtimeOf(context.connection).capabilities.resolve(capability)
 	const model = context.model
 	if (use !== 'read') {
-		checkWriteTarget(context, grant, use)
+		checkWriteTarget(context, grant, use, assigned)
 	}
 	if (grant.kind === 'app') {
 		if (use === 'read') {