uql-orm 0.115.5 → 0.116.1

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
@@ -18,7 +18,7 @@ export declare class NeonQuerier extends PgQuerier {
18
18
  /** Connects nothing: a statement goes over HTTP until a session holds the connection. */
19
19
  protected lazyConnect(): Promise<void>;
20
20
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
21
- /** A list as one HTTP transaction, all or none; inside an open transaction, in turn on its session, which it joins. */
21
+ /** A list as one HTTP transaction, all or none; inside an open transaction, pipelined on its session, which it joins. */
22
22
  protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
23
23
  protected openTransaction(opts?: TransactionOptions): Promise<void>;
24
24
  internalStream(query: string, values?: unknown[]): AsyncGenerator<import("../type/utility.js").RawRow, void, any>;
@@ -20,16 +20,9 @@ export class NeonQuerier extends PgQuerier {
20
20
  }
21
21
  return this.http.query(sql, values);
22
22
  }
23
- /** A list as one HTTP transaction, all or none; inside an open transaction, in turn on its session, which it joins. */
24
- async executeBatch(statements) {
25
- if (this.hasOpenTransaction) {
26
- const results = [];
27
- for (const { sql, values } of statements) {
28
- results.push(await super.execute(sql, values));
29
- }
30
- return results;
31
- }
32
- return this.http.transaction(statements);
23
+ /** A list as one HTTP transaction, all or none; inside an open transaction, pipelined on its session, which it joins. */
24
+ executeBatch(statements) {
25
+ return this.hasOpenTransaction ? super.executeBatch(statements) : this.http.transaction(statements);
33
26
  }
34
27
  async openTransaction(opts) {
35
28
  await super.lazyConnect();
@@ -0,0 +1,33 @@
1
+ import type { BoundStatement } from '../type/index.js';
2
+ import type { PgResult } from './pgExecution.js';
3
+ /** What a pipeline writes to besides the statements its `Query` writes: the `Sync` closing the request. */
4
+ type PgConnection = {
5
+ sync(): void;
6
+ };
7
+ /** What decodes a column, as node-postgres reads its wire types off a client: `client.getTypeParser`. */
8
+ export type PgTypes = {
9
+ getTypeParser(oid: number, format?: 'text' | 'binary'): unknown;
10
+ };
11
+ /** node-postgres' `Query`, as a pipeline extends it: the one the client runs, so it reads the client's protocol. */
12
+ interface PgQuery {
13
+ text: string;
14
+ values?: readonly unknown[];
15
+ submit(connection: object): unknown;
16
+ requiresPreparation(): boolean;
17
+ prepare(connection: PgConnection): void;
18
+ handleCommandComplete(msg: unknown, connection: PgConnection): void;
19
+ handleError(error: Error, connection: PgConnection): void;
20
+ }
21
+ /** A client running statements, `pg`'s or a fork's, which names its `Query` on its class. */
22
+ export type PgPipelineClient = PgTypes & {
23
+ query(text: string, values?: unknown[]): Promise<PgResult>;
24
+ query(query: PgQuery): unknown;
25
+ };
26
+ /**
27
+ * Runs `statements` on `client` in one round trip: each one's Parse, Bind and Execute, then a single `Sync`, so the
28
+ * server answers them in order and fails the list at its first error, skipping the rest. A client whose `Query` cannot
29
+ * be pipelined, as pg-native's, runs them in turn. The error names the statement that failed as `statementIndex`,
30
+ * counted from the first after the `leading` ones the caller added.
31
+ */
32
+ export declare function pipelined(client: PgPipelineClient, statements: readonly BoundStatement[], leading?: number): Promise<PgResult[]>;
33
+ export {};
@@ -0,0 +1,82 @@
1
+ import { cachedIn, noop } from '../util/object.util.js';
2
+ const PIPELINES = new WeakMap();
3
+ /**
4
+ * Runs `statements` on `client` in one round trip: each one's Parse, Bind and Execute, then a single `Sync`, so the
5
+ * server answers them in order and fails the list at its first error, skipping the rest. A client whose `Query` cannot
6
+ * be pipelined, as pg-native's, runs them in turn. The error names the statement that failed as `statementIndex`,
7
+ * counted from the first after the `leading` ones the caller added.
8
+ */
9
+ export function pipelined(client, statements, leading = 0) {
10
+ const Query = Reflect.get(client.constructor, 'Query');
11
+ if (!pipelines(Query)) {
12
+ return inTurn(client, statements, leading);
13
+ }
14
+ const Pipeline = cachedIn(PIPELINES, Query, () => pipelineOf(Query));
15
+ return new Promise((resolve, reject) => {
16
+ client.query(new Pipeline(statements, client, leading, (error, results) => error ? reject(error) : resolve([results].flat())));
17
+ });
18
+ }
19
+ /** Whether `value` is a `Query` writing its statement's protocol itself, as `pg`'s does, which a pipeline extends. */
20
+ function pipelines(value) {
21
+ return typeof value === 'function' && typeof value.prototype?.prepare === 'function';
22
+ }
23
+ /** `statements` one round trip each, the error naming its statement as {@link pipelined}'s does. */
24
+ async function inTurn(client, statements, leading) {
25
+ const results = [];
26
+ for (const [at, { sql, values }] of statements.entries()) {
27
+ const result = await client.query(sql, [...values]).catch((error) => {
28
+ throw Object.assign(error, { statementIndex: at - leading });
29
+ });
30
+ results.push(result);
31
+ }
32
+ return results;
33
+ }
34
+ /**
35
+ * The pipeline over `Query`: it writes each statement as `Query` does, holding back each one's `Sync` but the last.
36
+ * Earlier than `pg` 8.5 a failed list crashes the client, hence the peer floor. `pg` 8.23's public `pipeline` option
37
+ * does not fit yet: it is set per client, and refuses the cursors a stream reads.
38
+ */
39
+ function pipelineOf(Query) {
40
+ return class Pipeline extends Query {
41
+ #statements;
42
+ #leading;
43
+ /** The statements the server finished, which is the position of one it fails. */
44
+ #completed = 0;
45
+ /** The statement being written, which is the one failing where its values cannot be. */
46
+ #writing;
47
+ #failed = false;
48
+ /** `types`, the client's own, so every statement's rows decode as one run alone would, on a fork too. */
49
+ constructor(statements, types, leading, callback) {
50
+ super({ text: statements[0].sql, callback, types });
51
+ this.#statements = statements;
52
+ this.#leading = leading;
53
+ }
54
+ requiresPreparation() {
55
+ return true;
56
+ }
57
+ prepare(connection) {
58
+ // `Query` closes each statement it writes with a `Sync`, which would commit it alone: the list sends one, last.
59
+ const held = Object.create(connection, { sync: { value: noop } });
60
+ for (const [at, { sql, values }] of this.#statements.entries()) {
61
+ this.#writing = at;
62
+ this.text = sql;
63
+ this.values = values;
64
+ super.prepare(held);
65
+ if (this.#failed) {
66
+ break;
67
+ }
68
+ }
69
+ this.#writing = undefined;
70
+ connection.sync();
71
+ }
72
+ handleCommandComplete(msg, connection) {
73
+ this.#completed++;
74
+ super.handleCommandComplete(msg, connection);
75
+ }
76
+ handleError(error, connection) {
77
+ this.#failed = true;
78
+ const statementIndex = (this.#writing ?? this.#completed) - this.#leading;
79
+ super.handleError(Object.assign(error, { statementIndex }), connection);
80
+ }
81
+ };
82
+ }