uql-orm 0.115.4 → 0.116.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,6 +6,8 @@ export declare class CockroachDialect extends PgLikeSqlDialect {
6
6
  readonly dialectName = "cockroachdb";
7
7
  /** Bare: a policy takes no subquery here. */
8
8
  contextRead(key: string, type: string): string;
9
+ /** No `row_security_active` here: whether the role writing reads past row-level security, as the check asks. */
10
+ rowSecurityApplies(): string;
9
11
  /**
10
12
  * pgvector's but `l1`: `<+>` and `vector_l1_ops` answer "unimplemented: operator class ... is not
11
13
  * supported" (verified live on v26.2), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
@@ -8,6 +8,10 @@ export class CockroachDialect extends PgLikeSqlDialect {
8
8
  contextRead(key, type) {
9
9
  return this.settingRead(key, type);
10
10
  }
11
+ /** No `row_security_active` here: whether the role writing reads past row-level security, as the check asks. */
12
+ rowSecurityApplies() {
13
+ return `NOT ${this.bypassesRowSecurity('current_user')}`;
14
+ }
11
15
  /**
12
16
  * pgvector's but `l1`: `<+>` and `vector_l1_ops` answer "unimplemented: operator class ... is not
13
17
  * supported" (verified live on v26.2), tracked at https://github.com/cockroachdb/cockroach/issues/147839.
@@ -562,10 +562,13 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
562
562
  /** ` ON CONFLICT (keys) DO UPDATE SET ... WHERE ...`, or `DO NOTHING` with nothing to assign. */
563
563
  private onConflict;
564
564
  /**
565
- * The statement failing a trigger's write with `message`, a quoted literal: SQL/PSM's `SIGNAL`, which the
566
- * MySQL family speaks. `rows` are what a set-based engine's body reads, where it fails only if there are any.
565
+ * The statement failing a trigger's write with `message`, a quoted literal, under `sqlState` where one is named:
566
+ * SQL/PSM's `SIGNAL`, which the MySQL family speaks. `rows` are what a set-based engine's body reads, where it fails
567
+ * only if there are any.
567
568
  */
568
- protected refusal(message: string, _rows?: TriggerRows): string;
569
+ protected refusal(message: string, _rows?: TriggerRows, sqlState?: string): string;
570
+ /** What answers, in a trigger on `meta`'s table, whether row-level security holds the role writing it. */
571
+ rowSecurityApplies(_meta: EntityMeta<object>): string;
569
572
  /** What a trigger's update assigns: the values it names, and the `onUpdate` fills a trigger can write, a value or SQL. */
570
573
  private triggerUpdateEntries;
571
574
  /** The values a write names, refusing one the entity has no column for. */
@@ -1468,7 +1468,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1468
1468
  */
1469
1469
  triggerWrite(ctx, write, rows) {
1470
1470
  if (write.kind === 'refuse') {
1471
- ctx.append(this.refusal(this.escape(write.message), rows));
1471
+ ctx.append(this.refusal(this.escape(write.message), rows, write.sqlState));
1472
1472
  return;
1473
1473
  }
1474
1474
  const meta = getMeta(write.entity);
@@ -1554,11 +1554,16 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1554
1554
  return ` ON CONFLICT (${keys}) ${assignments ? update : 'DO NOTHING'}`;
1555
1555
  }
1556
1556
  /**
1557
- * The statement failing a trigger's write with `message`, a quoted literal: SQL/PSM's `SIGNAL`, which the
1558
- * MySQL family speaks. `rows` are what a set-based engine's body reads, where it fails only if there are any.
1557
+ * The statement failing a trigger's write with `message`, a quoted literal, under `sqlState` where one is named:
1558
+ * SQL/PSM's `SIGNAL`, which the MySQL family speaks. `rows` are what a set-based engine's body reads, where it fails
1559
+ * only if there are any.
1559
1560
  */
1560
- refusal(message, _rows) {
1561
- return `SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = ${message};`;
1561
+ refusal(message, _rows, sqlState = '45000') {
1562
+ return `SIGNAL SQLSTATE '${sqlState}' SET MESSAGE_TEXT = ${message};`;
1563
+ }
1564
+ /** What answers, in a trigger on `meta`'s table, whether row-level security holds the role writing it. */
1565
+ rowSecurityApplies(_meta) {
1566
+ throw new UqlUsageError(`${this.engineName} holds no row to a policy itself`);
1562
1567
  }
1563
1568
  /** What a trigger's update assigns: the values it names, and the `onUpdate` fills a trigger can write, a value or SQL. */
1564
1569
  triggerUpdateEntries(meta, values) {
@@ -1,6 +1,6 @@
1
1
  import type { IndexType } from '../schema/types.js';
2
2
  import type { BoundStatement, SqlDialectName, SqlValues } from '../type/index.js';
3
- import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
3
+ import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type TriggerRows, type VectorDistance, type VectorMetric } from '../type/index.js';
4
4
  import type { DialectOptions } from './abstractDialect.js';
5
5
  import { AbstractSqlDialect, type RelationRows, type SelectTerm } from './abstractSqlDialect.js';
6
6
  import { type HydrateKind } from './hydrateColumn.js';
@@ -34,8 +34,12 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
34
34
  protected settingRead(key: string, type: string): string;
35
35
  /** Where the pool binds roles, an unnamed one is the connection's own, which unbinding one goes back to. */
36
36
  rowSecurityBypassQuery(role?: string): string;
37
+ /** Whether role `name`, as SQL, reads past row-level security: a superuser, or one granted `BYPASSRLS`. */
38
+ protected bypassesRowSecurity(name: string): string;
37
39
  /** `USING MESSAGE`, so the text is taken as it is rather than as a format reading each `%`. */
38
- protected refusal(message: string): string;
40
+ protected refusal(message: string, _rows?: TriggerRows, sqlState?: string): string;
41
+ /** `row_security_active`, false for a superuser, a role bypassing it, and an owner of a table not forced. */
42
+ rowSecurityApplies(meta: EntityMeta<object>): string;
39
43
  readonly escapeIdChar = "\"";
40
44
  readonly autoIncrementSuffix: string;
41
45
  /**
@@ -93,11 +93,19 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
93
93
  /** Where the pool binds roles, an unnamed one is the connection's own, which unbinding one goes back to. */
94
94
  rowSecurityBypassQuery(role) {
95
95
  const name = role === undefined ? (this.policies.role ? 'session_user' : this.currentRole) : this.escape(role);
96
- return `SELECT EXISTS (SELECT FROM pg_roles WHERE rolname = ${name} AND (rolsuper OR rolbypassrls)) AS bypasses`;
96
+ return `SELECT ${this.bypassesRowSecurity(name)} AS bypasses`;
97
+ }
98
+ /** Whether role `name`, as SQL, reads past row-level security: a superuser, or one granted `BYPASSRLS`. */
99
+ bypassesRowSecurity(name) {
100
+ return `EXISTS (SELECT FROM pg_roles WHERE rolname = ${name} AND (rolsuper OR rolbypassrls))`;
97
101
  }
98
102
  /** `USING MESSAGE`, so the text is taken as it is rather than as a format reading each `%`. */
99
- refusal(message) {
100
- return `RAISE EXCEPTION USING MESSAGE = ${message};`;
103
+ refusal(message, _rows, sqlState) {
104
+ return `RAISE EXCEPTION USING ${sqlState ? `ERRCODE = '${sqlState}', ` : ''}MESSAGE = ${message};`;
105
+ }
106
+ /** `row_security_active`, false for a superuser, a role bypassing it, and an owner of a table not forced. */
107
+ rowSecurityApplies(meta) {
108
+ return `row_security_active(${this.escape(this.escapedTableName(meta))})`;
101
109
  }
102
110
  escapeIdChar = '"';
103
111
  // Shared default for both dialects. CockroachDB docs flag sequential PKs as a hotspotting risk
@@ -1,7 +1,7 @@
1
- import { COLUMN_OPTIONS, REF_KEY, RelationAggregate, SECTION_ENTRY, SOFT_DELETE_FILTER, } from '../../type/index.js';
1
+ import { COLUMN_OPTIONS, REF_KEY, RelationAggregate, SECTION_ENTRY, SOFT_DELETE_FILTER, QuerySql, } from '../../type/index.js';
2
2
  import { aggregateField, defaultReadKeys, fieldKeys, isInlinedExpression } from '../../util/field.util.js';
3
- import { fieldOptionConflict, findVectorIndex, valueTypesOf, hasKeys, holdsForeignKey, isCascadable, isToManyRelation, indexRefs, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, isRecord, whereWith, } from '../../util/index.js';
4
- import { contextKeys, EVERY_ROW_POLICY, POLICY_CONTEXT_KEY, POLICY_OPS, policyMeta, TENANT_POLICY, tenantPolicy, } from '../../util/policy.util.js';
3
+ import { fieldOptionConflict, findVectorIndex, valueTypesOf, hasKeys, holdsForeignKey, isCascadable, isToManyRelation, indexRefs, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, isRecord, isPlainObject, whereWith, aggregateOf, } from '../../util/index.js';
4
+ import { contextKeys, EVERY_ROW_POLICY, POLICY_CONTEXT_KEY, POLICY_OPS, pairsRows, POLICY_SIDES, policyMeta, TENANT_POLICY, tenantPolicy, isRowSide, sidesOf, transitionsOf, } from '../../util/policy.util.js';
5
5
  import { UqlUsageError } from '../../util/uqlError.js';
6
6
  import { ownRegistrations } from '../decorator/bag.js';
7
7
  /**
@@ -122,9 +122,76 @@ function addFilter(meta, name, opts) {
122
122
  }
123
123
  (meta.filters ??= {})[name] = opts;
124
124
  }
125
+ /** What a policy states: anything else is refused, never ignored, since an ignored condition reaches more rows. */
126
+ const POLICY_KEYS = { allow: true, must: true, ops: true, when: true, name: true };
127
+ /**
128
+ * Refuses a policy's rows read where none can be: a side none of its statements has; one inside a relation or another
129
+ * side; and a pair of both rows anywhere but a `must` holding updates alone.
130
+ */
131
+ function assertSides(meta, policy) {
132
+ const { entity } = meta;
133
+ for (const side of sidesOf(policy.where)) {
134
+ if (!policy.ops.some((op) => POLICY_SIDES[op][side])) {
135
+ const verb = side === '$old' ? 'finds' : 'writes';
136
+ throw new UqlUsageError(`'${entity.name}' has a policy holding ${policy.ops.join(', ')} that reads '${side}', a row none of them ${verb}`);
137
+ }
138
+ }
139
+ const buried = buriedSide(meta, policy.where);
140
+ if (buried) {
141
+ throw new UqlUsageError(`'${entity.name}' has a policy reading '${buried}' inside a relation or another row: state it at the predicate's root`);
142
+ }
143
+ const transitions = transitionsOf(policy.where);
144
+ if (!transitions.length) {
145
+ return;
146
+ }
147
+ if (policy.effect !== 'must' || !policy.ops.every(pairsRows)) {
148
+ throw new UqlUsageError(`'${entity.name}' has a policy pairing the row as found with the row as written: only a must holding updates alone may`);
149
+ }
150
+ if (readsBeyondRow(meta, transitions)) {
151
+ throw new UqlUsageError(`'${entity.name}' has a policy pairing both rows through a relation or SQL: a transition reads the entity's own fields`);
152
+ }
153
+ }
154
+ /** A side `where` reads inside a relation's predicate or another side's, where none is read. */
155
+ function buriedSide(meta, where, buried = false) {
156
+ if (Array.isArray(where)) {
157
+ return where.map((item) => buriedSide(meta, item, buried)).find(Boolean);
158
+ }
159
+ if (!isPlainObject(where)) {
160
+ return undefined;
161
+ }
162
+ for (const [key, value] of Object.entries(where)) {
163
+ if (isRowSide(key) && buried) {
164
+ return key;
165
+ }
166
+ const deeper = buried || isRowSide(key) || key in meta.relations;
167
+ const found = buriedSide(meta, value, deeper);
168
+ if (found) {
169
+ return found;
170
+ }
171
+ }
172
+ return undefined;
173
+ }
174
+ /**
175
+ * Whether `where` reads past the row at any depth: a relation of `meta` by its key or an aggregate, or SQL, which names
176
+ * no row.
177
+ */
178
+ function readsBeyondRow(meta, where) {
179
+ if (where instanceof QuerySql) {
180
+ return true;
181
+ }
182
+ if (Array.isArray(where)) {
183
+ return where.some((item) => readsBeyondRow(meta, item));
184
+ }
185
+ return (isPlainObject(where) &&
186
+ Object.entries(where).some(([key, value]) => key in meta.relations || aggregateOf(meta.fields[key]) !== undefined || readsBeyondRow(meta, value)));
187
+ }
125
188
  /** Registers a policy, refusing one stating no single effect, a name taken and a statement no policy holds. */
126
189
  function addPolicy(meta, declared) {
127
190
  const { entity } = meta;
191
+ const stray = Object.keys(declared).find((key) => !Object.hasOwn(POLICY_KEYS, key));
192
+ if (stray !== undefined) {
193
+ throw new UqlUsageError(`'${entity.name}' has a policy stating '${stray}': a policy states allow or must, with ops, when and name`);
194
+ }
128
195
  const policy = policyMeta(declared);
129
196
  if (!policy || (declared.allow !== undefined && declared.must !== undefined)) {
130
197
  throw new UqlUsageError(`'${entity.name}' has a policy stating none or both of allow and must: state one`);
@@ -133,11 +200,12 @@ function addPolicy(meta, declared) {
133
200
  if (unknown !== undefined || !policy.ops.length) {
134
201
  throw new UqlUsageError(`'${entity.name}' has a policy holding '${String(unknown ?? 'no statement')}': name read, insert, update or delete`);
135
202
  }
203
+ assertSides(meta, policy);
136
204
  if (policy.name === TENANT_POLICY || policy.name === EVERY_ROW_POLICY) {
137
205
  throw new UqlUsageError(`'${entity.name}' policy name '${policy.name}' is reserved for the policies uql derives`);
138
206
  }
139
207
  assertUnnamed(meta, 'policy', meta.policies, policy.name);
140
- const misnamed = [...contextKeys([policy.where, policy.check]), ...Object.keys(policy.when ?? {})].find((key) => !POLICY_CONTEXT_KEY.test(key));
208
+ const misnamed = [...contextKeys(policy.where), ...Object.keys(policy.when ?? {})].find((key) => !POLICY_CONTEXT_KEY.test(key));
141
209
  if (misnamed !== undefined) {
142
210
  throw new UqlUsageError(`'${entity.name}' has a policy reading context key '${misnamed}': name keys as identifiers`);
143
211
  }
@@ -1,11 +1,17 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { PolicySchema } from '../schema/types.js';
3
- import { type EntityMeta, type FieldMeta } from '../type/index.js';
3
+ import { type EntityMeta, type EntityTriggerMeta, type FieldMeta } from '../type/index.js';
4
4
  /**
5
5
  * The policies a native pool's database holds `meta` to, each named for its table and label and ending in a hash of
6
6
  * its own SQL, as a trigger is: one `FOR ALL` where it holds every statement, else one per statement. See
7
7
  * architecture/row-level-security.md.
8
8
  */
9
9
  export declare function renderPolicies(dialect: AbstractSqlDialect, meta: EntityMeta<object>, columnType: (field: FieldMeta) => string): PolicySchema[];
10
+ /**
11
+ * The triggers holding a native pool's database to `meta`'s transitions, which no policy can, as no `WITH CHECK` sees
12
+ * the row as found: before each update, a row moving where none lets it is refused as `42501`, wherever row-level
13
+ * security holds the role writing it. In the body, since Postgres takes no subquery in a trigger's `WHEN`.
14
+ */
15
+ export declare function policyTriggers(dialect: AbstractSqlDialect, meta: EntityMeta<object>, columnType: (field: FieldMeta) => string): EntityTriggerMeta<object>[];
10
16
  /** What removes a policy from `table`, a name qualified where its schema is. */
11
17
  export declare function dropPolicy(dialect: AbstractSqlDialect, table: string, name: string): string;
@@ -1,9 +1,12 @@
1
1
  import { readsRelations } from '../dialect/abstractDialect.js';
2
2
  import { QuerySql, } from '../type/index.js';
3
3
  import { entityName } from '../util/object.util.js';
4
- import { asWhere, bindContext, POLICY_OPS, policiesOf } from '../util/policy.util.js';
4
+ import { asWhere, bindContext, boundTransitions, POLICY_OPS, movesRefused, POLICY_SIDES, policiesOf, project, } from '../util/policy.util.js';
5
+ import { sql } from '../util/sql.js';
5
6
  import { ownedName } from '../util/sql.util.js';
7
+ import { written } from '../util/triggerWrite.js';
6
8
  import { UqlUsageError } from '../util/uqlError.js';
9
+ import { rowNames, sidedSql } from './triggerSql.js';
7
10
  /** The command each statement a policy holds is, as `CREATE POLICY ... FOR` names it. */
8
11
  const COMMANDS = {
9
12
  read: 'SELECT',
@@ -22,15 +25,9 @@ export function renderPolicies(dialect, meta, columnType) {
22
25
  }
23
26
  const table = dialect.resolveTableAlias(meta);
24
27
  const target = dialect.escapedTableName(meta);
25
- const read = (ref, field) => {
26
- if (!field) {
27
- throw new UqlUsageError(`a policy of '${entityName(meta)}' compares context key '${ref.$context}' with no field`);
28
- }
29
- const sql = dialect.contextRead(ref.$context, columnType(field));
30
- return new QuerySql(() => sql);
31
- };
28
+ const read = contextReader(dialect, meta, columnType);
32
29
  return policiesOf(meta.policies).flatMap((policy, position) => {
33
- const label = policy.name ?? `${policy.effect}_${position}`;
30
+ const label = policyLabel(policy, position);
34
31
  const predicate = (where) => {
35
32
  const bound = asWhere(meta, bindContext(meta, where, read));
36
33
  const { rowSecurity } = dialect.features;
@@ -44,8 +41,10 @@ export function renderPolicies(dialect, meta, columnType) {
44
41
  ? [['ALL', undefined]]
45
42
  : policy.ops.map((op) => [COMMANDS[op], op]);
46
43
  return commands.map(([command, op]) => {
47
- const using = command === 'INSERT' ? undefined : predicate(policy.where);
48
- const check = writes(command) ? predicate(policy.check ?? policy.where) : undefined;
44
+ // `ALL` reads both rows, as an update does.
45
+ const sides = POLICY_SIDES[op ?? 'update'];
46
+ const using = sides.$old && predicate(project(policy.where, '$old'));
47
+ const check = sides.$new && predicate(project(policy.where, '$new'));
49
48
  const create = (name) => [
50
49
  `CREATE POLICY ${dialect.escapeId(name)} ON ${target} AS ${policy.effect === 'allow' ? 'PERMISSIVE' : 'RESTRICTIVE'} FOR ${command} TO PUBLIC`,
51
50
  ...(using === undefined ? [] : [`USING (${using})`]),
@@ -56,9 +55,46 @@ export function renderPolicies(dialect, meta, columnType) {
56
55
  });
57
56
  });
58
57
  }
59
- /** Whether `command` writes rows, which `WITH CHECK` holds. */
60
- function writes(command) {
61
- return command === 'ALL' || command === 'INSERT' || command === 'UPDATE';
58
+ /**
59
+ * The triggers holding a native pool's database to `meta`'s transitions, which no policy can, as no `WITH CHECK` sees
60
+ * the row as found: before each update, a row moving where none lets it is refused as `42501`, wherever row-level
61
+ * security holds the role writing it. In the body, since Postgres takes no subquery in a trigger's `WHEN`.
62
+ */
63
+ export function policyTriggers(dialect, meta, columnType) {
64
+ if (!dialect.policies.database || !meta.policies?.length) {
65
+ return [];
66
+ }
67
+ const read = contextReader(dialect, meta, columnType);
68
+ const names = rowNames(dialect);
69
+ const refusal = written({
70
+ kind: 'refuse',
71
+ message: movesRefused(entityName(meta)),
72
+ sqlState: '42501',
73
+ });
74
+ return policiesOf(meta.policies).flatMap((policy, position) => {
75
+ const moves = boundTransitions(meta, policy, read);
76
+ if (!moves.length) {
77
+ return [];
78
+ }
79
+ const held = moves.map((bound) => sidedSql(dialect, meta, asWhere(meta, bound), names)).join(' AND ');
80
+ const condition = [dialect.rowSecurityApplies(meta), ...whenSql(dialect, policy.when), `(${held}) IS NOT TRUE`];
81
+ const body = sql `IF ${sql.text(condition.join(' AND '))} THEN\n${refusal}\nEND IF;`;
82
+ return [{ on: 'beforeUpdate', name: `${policyLabel(policy, position)}_update`, run: () => body }];
83
+ });
84
+ }
85
+ /** A policy's label within its entity: its name, else its effect and position. */
86
+ function policyLabel(policy, position) {
87
+ return policy.name ?? `${policy.effect}_${position}`;
88
+ }
89
+ /** Each context key a policy reads, as the database reads it off the transaction, typed as the field it meets. */
90
+ function contextReader(dialect, meta, columnType) {
91
+ return (ref, field) => {
92
+ if (!field) {
93
+ throw new UqlUsageError(`a policy of '${entityName(meta)}' compares context key '${ref.$context}' with no field`);
94
+ }
95
+ const read = dialect.contextRead(ref.$context, columnType(field));
96
+ return new QuerySql(() => read);
97
+ };
62
98
  }
63
99
  /** What removes a policy from `table`, a name qualified where its schema is. */
64
100
  export function dropPolicy(dialect, table, name) {
@@ -16,7 +16,7 @@ import { rebuildTable } from './ddl/tableRebuild.js';
16
16
  import { columnForeignKey, columnIndex, bareColumn, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
17
17
  import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
18
18
  import { assertIndexPredicate } from './indexPredicate.js';
19
- import { dropPolicy, renderPolicies } from './policySql.js';
19
+ import { dropPolicy, policyTriggers, renderPolicies } from './policySql.js';
20
20
  import { added, alterations, dropped, needsRebuild, newlyRequired, nonEmpty, sides } from './schemaChange.js';
21
21
  import { dropTrigger, dropTriggerBody, namesAny, renderTrigger, stampTriggers } from './triggerSql.js';
22
22
  /** The SQL schema generator, one for every SQL engine, its spellings taken from the dialect and its DDL classes. */
@@ -58,6 +58,7 @@ export class SqlSchemaGenerator {
58
58
  */
59
59
  buildAST(entities) {
60
60
  const { dialect } = this;
61
+ const columnType = (field) => canonicalToSql(resolveColumnCanonicalType(field), dialect);
61
62
  return buildSchemaAST(entities, {
62
63
  // The alias, not `resolveTableName`: a node holds its schema apart, so a name derived from it is one identifier.
63
64
  resolveTableName: (meta) => dialect.resolveTableAlias(meta),
@@ -69,9 +70,9 @@ export class SqlSchemaGenerator {
69
70
  return dialect.compileDdl(where, entity);
70
71
  },
71
72
  defaultForeignKeyAction: this.defaultForeignKeyAction,
72
- renderTriggers: (meta) => [...(meta.triggers ?? []), ...stampTriggers(this.dialect, meta)].map((trigger, i) => renderTrigger(this.dialect, meta, trigger, i)),
73
- renderPolicies: (meta) => renderPolicies(this.dialect, meta, (field) => canonicalToSql(resolveColumnCanonicalType(field), this.dialect)),
74
- textScoreIndexes: this.dialect.features.textScoreIndexes,
73
+ renderTriggers: (meta) => [...(meta.triggers ?? []), ...stampTriggers(dialect, meta), ...policyTriggers(dialect, meta, columnType)].map((trigger, i) => renderTrigger(dialect, meta, trigger, i)),
74
+ renderPolicies: (meta) => renderPolicies(dialect, meta, columnType),
75
+ textScoreIndexes: dialect.features.textScoreIndexes,
75
76
  vectorIndexRequiresNotNull: this.features.vectorIndexRequiresNotNull,
76
77
  });
77
78
  }
@@ -1,6 +1,6 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { TriggerSchema } from '../schema/types.js';
3
- import type { EntityMeta, EntityTriggerMeta } from '../type/index.js';
3
+ import { type EntityMeta, type EntityTriggerMeta, type RowSide, type PolicyWhere, type TriggerMetaWhere, type TriggerRowName } from '../type/index.js';
4
4
  /**
5
5
  * One trigger for `dialect`, named for its table and label and ending in a hash of its own SQL. That hash
6
6
  * is the whole of change detection: a trigger is in place exactly when its name is installed, and an
@@ -14,6 +14,16 @@ export declare function renderTrigger<E>(dialect: AbstractSqlDialect, meta: Enti
14
14
  export declare function dropTrigger(dialect: AbstractSqlDialect, table: string, name: string): string[];
15
15
  /** What dropping a trigger or its table leaves behind: on the Postgres family, the function holding its body. */
16
16
  export declare function dropTriggerBody(dialect: AbstractSqlDialect, schema: string | undefined, name: string): string[];
17
+ /** What the engine calls the rows it hands a trigger: records on a row-based engine, tables on a set-based one. */
18
+ export declare function rowNames(dialect: AbstractSqlDialect): RowNames;
19
+ /** Keyed as `where` names the rows, so a predicate reads its own row's name directly. */
20
+ type RowNames = Readonly<Record<RowSide, TriggerRowName>>;
21
+ /**
22
+ * A predicate over a trigger's rows as SQL: `$old` reads the row as found, `$new` the row as written, and a condition
23
+ * beside neither holds both. Each row's SQL is an `operand` wherever another term sits beside it, bracketing itself
24
+ * if compound, as `$where` does.
25
+ */
26
+ export declare function sidedSql<E>(dialect: AbstractSqlDialect, meta: EntityMeta<E>, where: PolicyWhere<E> | TriggerMetaWhere<E>, names: RowNames, operand?: boolean): string;
17
27
  /**
18
28
  * The triggers a stamp needs: one per event it names, each assigning the field's expression to its
19
29
  * column. Generated rather than authored, so unlike an authored body it renders on every engine from
@@ -22,3 +32,4 @@ export declare function dropTriggerBody(dialect: AbstractSqlDialect, schema: str
22
32
  export declare function stampTriggers<E extends object>(dialect: AbstractSqlDialect, meta: EntityMeta<E>): EntityTriggerMeta<E>[];
23
33
  /** Whether `statement` names any of `columns` as a whole identifier, quoted or not, in any case. */
24
34
  export declare function namesAny(statement: string, columns: readonly string[]): boolean;
35
+ export {};
@@ -1,6 +1,8 @@
1
- import { TriggerWriteSql } from '../type/index.js';
1
+ import { groupClauses, isGroupOp } from '../dialect/operators.js';
2
+ import { QuerySql, TriggerWriteSql, } from '../type/index.js';
2
3
  import { stampEvents } from '../util/field.util.js';
3
4
  import { definedEntries } from '../util/object.util.js';
5
+ import { isRowSide } from '../util/policy.util.js';
4
6
  import { sql, refs, rowRefs } from '../util/sql.js';
5
7
  import { ownedName, splitQualifiedName } from '../util/sql.util.js';
6
8
  import { escapeRegExp } from '../util/string.util.js';
@@ -130,10 +132,10 @@ function triggerBody(dialect, meta, trigger, before) {
130
132
  */
131
133
  function triggerFilter(dialect, meta, trigger, rows, names) {
132
134
  const moved = movedColumns(dialect, meta, trigger.of ?? [], names);
133
- return [
134
- ...(moved ? [moved] : []),
135
- ...(trigger.where ? condition(dialect, meta, trigger.where, rows, names, Boolean(moved)) : []),
136
- ].join(' AND ');
135
+ // A set-based engine ANDs the filter into each write the body runs, so it is an operand there.
136
+ const operand = Boolean(moved) || dialect.features.triggers.fires === 'eachStatement';
137
+ const where = trigger.where && condition(dialect, meta, trigger.where, rows, names, operand);
138
+ return [moved, where].filter(Boolean).join(' AND ');
137
139
  }
138
140
  /** The PL/pgSQL function holding a body. `OR REPLACE`, since a dropped table leaves its function behind. */
139
141
  function plpgsqlFunction(id, block) {
@@ -141,26 +143,49 @@ function plpgsqlFunction(id, block) {
141
143
  return `CREATE OR REPLACE FUNCTION ${id}() RETURNS trigger AS ${quote}\n${block} ${quote} LANGUAGE plpgsql`;
142
144
  }
143
145
  /** What the engine calls the rows it hands a trigger: records on a row-based engine, tables on a set-based one. */
144
- function rowNames(dialect) {
146
+ export function rowNames(dialect) {
145
147
  return dialect.features.triggers.fires === 'eachStatement'
146
148
  ? { $new: 'inserted', $old: 'deleted' }
147
149
  : { $new: 'NEW', $old: 'OLD' };
148
150
  }
149
151
  /**
150
- * The `where` filter as the terms an `AND` joins. A callback writes its own off the rows; a predicate
151
- * renders a term per row it names, spelled verbatim because `NEW` is a record the engine declares. Each
152
- * is an `operand` wherever another term sits beside it, bracketing itself if compound, as `$where` does.
152
+ * The `where` filter as SQL: a callback's own off the rows, or a predicate's, see {@link sidedSql}. An `operand`
153
+ * wherever another term sits beside it.
153
154
  */
154
155
  function condition(dialect, meta, where, rows, names, operand) {
155
156
  if (typeof where === 'function') {
156
157
  const sql = dialect.compileDdl(where(...rows), meta.entity);
157
- return [operand ? `(${sql})` : sql];
158
+ return operand ? `(${sql})` : sql;
158
159
  }
159
- const predicates = definedEntries(where);
160
- return predicates.map(([row, predicate]) => dialect.compileDdl(predicate, meta.entity, {
161
- escapedPrefix: `${names[row]}.`,
162
- operand: operand || predicates.length > 1,
163
- }));
160
+ return sidedSql(dialect, meta, where, names, operand);
161
+ }
162
+ /**
163
+ * A predicate over a trigger's rows as SQL: `$old` reads the row as found, `$new` the row as written, and a condition
164
+ * beside neither holds both. Each row's SQL is an `operand` wherever another term sits beside it, bracketing itself
165
+ * if compound, as `$where` does.
166
+ */
167
+ export function sidedSql(dialect, meta, where, names, operand = false) {
168
+ const parts = sidedParts(dialect, meta, where, names, operand);
169
+ // Alone, its one term brackets itself as an operand; beside others, each term already did.
170
+ return dialect.compileDdl({ $and: parts }, meta.entity, { operand: operand && parts.length === 1 });
171
+ }
172
+ /** The terms of `where`, each row it reads replaced by SQL off that row, see {@link sidedSql}. */
173
+ function sidedParts(dialect, meta, where, names, operand) {
174
+ const entries = Object.entries(where).filter(([, value]) => value !== undefined);
175
+ const onRow = (row, side, beside) => new QuerySql(() => dialect.compileDdl(row, meta.entity, { escapedPrefix: `${names[side]}.`, operand: operand || beside }));
176
+ return entries.map(([key, value]) => {
177
+ if (isGroupOp(key)) {
178
+ const clauses = groupClauses(key, value).map((clause) => ({
179
+ $and: sidedParts(dialect, meta, clause, names, true),
180
+ }));
181
+ return { [key]: clauses };
182
+ }
183
+ if (isRowSide(key)) {
184
+ return onRow(value, key, entries.length > 1);
185
+ }
186
+ const leaf = { [key]: value };
187
+ return { $and: [onRow(leaf, '$old', true), onRow(leaf, '$new', true)] };
188
+ });
164
189
  }
165
190
  /**
166
191
  * The triggers a stamp needs: one per event it names, each assigning the field's expression to its
@@ -152,23 +152,33 @@ export declare abstract class AbstractQuerier implements Querier {
152
152
  */
153
153
  private insertRows;
154
154
  /**
155
- * {@link guardWrite} under a pool holding writes to the policies, answering how the write of `rows` runs: alone, or
156
- * with the rows it wrote read back against the check they could not settle, in a transaction undoing it where one
157
- * does not hold. Where the database holds the policies the rows still get their pinned fields and an early refusal,
158
- * and nothing is read back. A checked write is refused where this querier holds no transaction to undo it in.
155
+ * How a statement doing `write` to `rows` runs where this pool reads rows to hold it to the check {@link guardWrite}
156
+ * answers and, for an update, to the transitions: alone where neither applies; else in a transaction reading each
157
+ * found row before the write, refusing one no transition lets go unwritten, then each written row after it against
158
+ * the check and what its transitions leave. A write read around is refused where no transaction undoes it.
159
159
  */
160
160
  private guarded;
161
+ /** The transitions this pool holds an update of `meta` to under the context: none where the database holds them. */
162
+ private heldTransitions;
161
163
  /**
162
- * {@link guardWrite} where this pool reads written rows back, answering the check to read them against; else
163
- * {@link pinUpserted}'s pinning alone, where it guards writes at all.
164
+ * What each row `found` names owes `transitions` once written, by its {@link rowKey}: each reads the row as found
165
+ * first, and one that lets it go nowhere refuses the write before it runs. Rows holding alike owe alike.
166
+ */
167
+ private transitionsOwed;
168
+ /** The {@link rowKey}s of the rows among `ids` holding `where` as they are stored. */
169
+ private idsHolding;
170
+ /**
171
+ * {@link guardWrite} where this pool guards writes: it pins and refuses `rows`, answering the check left to read
172
+ * them back against.
164
173
  */
165
174
  private guardRows;
166
- /** {@link pinWrite} where this pool guards writes: an upsert's branches check what they write, or its database does. */
167
- private pinUpserted;
168
175
  /** Whether {@link atomically} undoes every step of a write that fails partway: a transaction holds them. */
169
176
  private undoesSteps;
170
- /** Refuses, undoing the write, where any row `ids` names does not hold `check` once written. */
171
- private holdToCheck;
177
+ /**
178
+ * Refuses, undoing the write, where any row `ids` names does not hold `check` and what `owed` holds it to once
179
+ * written: one count per distinct predicate.
180
+ */
181
+ private holdWritten;
172
182
  /** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
173
183
  protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
174
184
  updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affected']>;
@@ -304,7 +314,10 @@ export declare abstract class AbstractQuerier implements Querier {
304
314
  deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affectedMany']>;
305
315
  /** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
306
316
  private deleteWhere;
307
- /** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
317
+ /**
318
+ * Whether an update is its one statement over `q`: no version to lock, relation to write, page to settle first, or
319
+ * transition to read its rows as found for.
320
+ */
308
321
  private updatesByFilter;
309
322
  /** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
310
323
  private deletesByFilter;