uql-orm 0.114.4 → 0.115.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.
Files changed (84) hide show
  1. package/dist/cockroachdb/cockroachDialect.d.ts +2 -0
  2. package/dist/cockroachdb/cockroachDialect.js +5 -0
  3. package/dist/d1/d1Querier.d.ts +2 -4
  4. package/dist/d1/d1Querier.js +0 -4
  5. package/dist/d1/d1SqliteDialect.js +1 -1
  6. package/dist/dialect/abstractDialect.d.ts +17 -8
  7. package/dist/dialect/abstractDialect.js +30 -16
  8. package/dist/dialect/abstractSqlDialect.d.ts +11 -2
  9. package/dist/dialect/abstractSqlDialect.js +17 -2
  10. package/dist/dialect/mysqlLikeSqlDialect.js +2 -0
  11. package/dist/dialect/operators.d.ts +2 -2
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -1
  13. package/dist/dialect/pgLikeSqlDialect.js +20 -0
  14. package/dist/entity/columnOptionsBuilder.d.ts +2 -1
  15. package/dist/entity/columnOptionsBuilder.js +3 -0
  16. package/dist/entity/metadata/definedFixture/author.d.ts +1 -1
  17. package/dist/entity/metadata/definedFixture/book.d.ts +2 -2
  18. package/dist/entity/metadata/definedFixture/folder.d.ts +1 -1
  19. package/dist/entity/metadata/definition.js +69 -30
  20. package/dist/http/api.d.ts +1 -1
  21. package/dist/http/wireQuery.js +1 -1
  22. package/dist/index.d.ts +2 -0
  23. package/dist/index.js +2 -0
  24. package/dist/migrate/ddl/tableDdl.d.ts +5 -0
  25. package/dist/migrate/ddl/tableDdl.js +9 -0
  26. package/dist/migrate/drift/driftDetector.js +2 -1
  27. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +3 -1
  28. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +7 -1
  29. package/dist/migrate/introspection/postgresIntrospector.d.ts +3 -1
  30. package/dist/migrate/introspection/postgresIntrospector.js +14 -1
  31. package/dist/migrate/introspection/tableSchemaAST.js +1 -0
  32. package/dist/migrate/policySql.d.ts +12 -0
  33. package/dist/migrate/policySql.js +74 -0
  34. package/dist/migrate/schemaChange.js +1 -0
  35. package/dist/migrate/schemaGenerator.d.ts +2 -0
  36. package/dist/migrate/schemaGenerator.js +37 -11
  37. package/dist/mongodb/mongoDialect.js +3 -1
  38. package/dist/mongodb/mongodbQuerier.d.ts +0 -2
  39. package/dist/mongodb/mongodbQuerier.js +0 -4
  40. package/dist/mssql/mssqlDialect.js +2 -0
  41. package/dist/neon/neonQuerier.d.ts +1 -2
  42. package/dist/nestjs/uqlContextInterceptor.d.ts +1 -1
  43. package/dist/nestjs/uqlContextInterceptor.js +1 -1
  44. package/dist/nestjs/uqlModule.d.ts +2 -2
  45. package/dist/nestjs/uqlModule.js +1 -1
  46. package/dist/querier/abstractQuerier.d.ts +31 -4
  47. package/dist/querier/abstractQuerier.js +120 -52
  48. package/dist/querier/abstractQuerierPool.js +2 -0
  49. package/dist/querier/abstractSqlQuerier.d.ts +16 -6
  50. package/dist/querier/abstractSqlQuerier.js +66 -6
  51. package/dist/querier/queryError.js +1 -0
  52. package/dist/schema/schemaAST.js +1 -0
  53. package/dist/schema/schemaASTBuilder.d.ts +3 -1
  54. package/dist/schema/schemaASTBuilder.js +1 -0
  55. package/dist/schema/schemaASTDiffer.js +4 -2
  56. package/dist/schema/types.d.ts +12 -4
  57. package/dist/sqlite/bindValues.d.ts +1 -1
  58. package/dist/sqlite/hranaQuerier.d.ts +2 -2
  59. package/dist/sqlite/sqliteDialect.js +2 -0
  60. package/dist/turso/tursoSessionQuerier.d.ts +2 -2
  61. package/dist/type/column.d.ts +10 -0
  62. package/dist/type/definedEntity.d.ts +9 -4
  63. package/dist/type/dialect.d.ts +13 -0
  64. package/dist/type/entity.d.ts +10 -0
  65. package/dist/type/index.d.ts +1 -0
  66. package/dist/type/index.js +1 -0
  67. package/dist/type/migration.d.ts +5 -1
  68. package/dist/type/policy.d.ts +91 -0
  69. package/dist/type/policy.js +1 -0
  70. package/dist/type/querier.d.ts +14 -0
  71. package/dist/type/querierPool.d.ts +2 -2
  72. package/dist/type/query.d.ts +18 -31
  73. package/dist/type/query.js +2 -0
  74. package/dist/util/contextRefs.d.ts +6 -0
  75. package/dist/util/contextRefs.js +5 -0
  76. package/dist/util/dialect.util.d.ts +10 -11
  77. package/dist/util/dialect.util.js +70 -56
  78. package/dist/util/fieldOption.util.js +1 -0
  79. package/dist/util/policy.util.d.ts +100 -0
  80. package/dist/util/policy.util.js +239 -0
  81. package/dist/util/uqlError.d.ts +2 -5
  82. package/dist/util/uqlError.js +2 -5
  83. package/package.json +1 -1
  84. package/skills/uql-orm/SKILL.md +23 -13
@@ -1,7 +1,7 @@
1
- import { AbstractSqlQuerier, type BoundStatement } from '../querier/index.js';
1
+ import { AbstractSqlQuerier } from '../querier/index.js';
2
2
  import { type SqliteBindValue } from '../sqlite/bindValues.js';
3
3
  import type { SqliteDialect } from '../sqlite/sqliteDialect.js';
4
- import type { ExtraOptions, RawRow } from '../type/index.js';
4
+ import type { BoundStatement, ExtraOptions, RawRow } from '../type/index.js';
5
5
  import type { SqlExecution } from '../util/sql.util.js';
6
6
  /** What a statement comes back with on a session: each row an array of its values, named by `columns`. */
7
7
  export type TursoResultSet = {
@@ -1,6 +1,7 @@
1
1
  import type { ForeignKeyAction } from '../schema/types.js';
2
2
  import type { TYPE_BOUNDS, VALUE_DECIDERS } from '../util/fieldOption.util.js';
3
3
  import type { ColumnType, DdlDefault, FamilyOf, FieldOptions, HasCompositeKey, IdValue, JsonColumnType, OnFieldCallback, StampEvent, TsTypeOf } from './entity.js';
4
+ import type { TenantKey } from './policy.js';
4
5
  import type { Wire } from './query.js';
5
6
  import type { QuerySql } from './querySql.js';
6
7
  import type { StandardSchemaV1 } from './standardSchema.js';
@@ -32,6 +33,8 @@ export type FilledOptions = {
32
33
  readonly onInsert: unknown;
33
34
  } | {
34
35
  readonly autoIncrement: true;
36
+ } | {
37
+ readonly tenant: string;
35
38
  };
36
39
  /** The `null` a column's row holds: none unless `nullable()` said so. */
37
40
  export type NullOf<O> = O extends {
@@ -98,6 +101,13 @@ export interface ColumnBuilder<in out O, in out V, F extends Family> extends Col
98
101
  softDelete(value?: OnFieldCallback<V>): With<O, V, {
99
102
  readonly softDelete: unknown;
100
103
  }, F>;
104
+ /**
105
+ * Makes it the row's tenant, read off `$context.tenantId` unless given another key: every statement is held to the
106
+ * context's tenant, and an insert leaving it out is given it.
107
+ */
108
+ tenant(...contextKey: TenantKey<V>): With<O, V, {
109
+ readonly tenant: string;
110
+ }, F>;
101
111
  unique(): With<O, V, {
102
112
  readonly unique: true;
103
113
  }, F>;
@@ -1,5 +1,6 @@
1
1
  import type { Column, ColumnOptionsOf, ColumnValueOf, FilledOptions, NullOf } from './column.js';
2
2
  import type { BrandNames, CheckSection, FilterSection, filledKey, HookContext, HookEvent, idKey, IdValue, IndexSection, IsUnion, KeyHolding, RefMap, RelationCardinality, RelationInverseOptions, RelationJoinOptions, RelationOwnerOptions, RelationRef, ToManyRefs, ToManyRelationKey, TriggerSection, versionKey } from './entity.js';
3
+ import type { PolicySection } from './policy.js';
3
4
  import type { EntityAccess, Wire } from './query.js';
4
5
  import type { QuerySql, RelationAggregate } from './querySql.js';
5
6
  import type { Type, AbstractType } from './utility.js';
@@ -162,6 +163,7 @@ type DefinedSections<Row, Key, Columns, B, Abstract> = {
162
163
  checks(checks: CheckSection<Columns>): DefinedEntity<Row, Key, Columns, B, Abstract>;
163
164
  triggers(triggers: TriggerSection<Columns>): DefinedEntity<Row, Key, Columns, B, Abstract>;
164
165
  filters(filters: FilterSection<Row>): DefinedEntity<Row, Key, Columns, B, Abstract>;
166
+ policies(policies: PolicySection<Row>): DefinedEntity<Row, Key, Columns, B, Abstract>;
165
167
  /** Functions each lifecycle event runs on the row, in order, given the querier writing it. */
166
168
  hooks(hooks: {
167
169
  readonly [E in HookEvent]?: readonly DefinedHook<Row>[];
@@ -172,10 +174,13 @@ type DefinedSections<Row, Key, Columns, B, Abstract> = {
172
174
  */
173
175
  relations<const R, const A extends AggregateThunks = {}>(relations: (rel: RelationBuilder<Columns>) => R, aggregates?: (refs: RefMap<Columns> & AggregateRefs<R> & ToManyRefs<B, Exclude<ToManyRelationKey<B>, keyof R>>) => A): RelatedEntity<Row & RelationRow<R> & AggregateRow<A>, Key, Columns, Abstract>;
174
176
  };
175
- /** A defined entity's class once its relations are in: its filters may follow, and read through them. */
176
- export type RelatedEntity<Row, Key, Columns, Abstract = false> = DefinedClass<Row, Key, Columns, Abstract> & {
177
- filters(filters: FilterSection<Row>): DefinedClass<Row, Key, Columns, Abstract>;
178
- };
177
+ /** The sections that read the row relations complete, so they may follow `relations`. */
178
+ type RowSection = 'filters' | 'policies';
179
+ /** A defined entity's class once its relations are in: its filters and policies may follow, and read through them. */
180
+ export type RelatedEntity<Row, Key, Columns, Abstract = false, Left extends RowSection = RowSection> = DefinedClass<Row, Key, Columns, Abstract> & Pick<{
181
+ filters(filters: FilterSection<Row>): RelatedEntity<Row, Key, Columns, Abstract, Exclude<Left, 'filters'>>;
182
+ policies(policies: PolicySection<Row>): RelatedEntity<Row, Key, Columns, Abstract, Exclude<Left, 'policies'>>;
183
+ }, Left>;
179
184
  /** A defined entity's class while its sections may still be declared. */
180
185
  export type DefinedEntity<Row, Key, Columns, B, Abstract = false> = DefinedClass<Row, Key, Columns, Abstract> & DefinedSections<Row, Key, Columns, B, Abstract>;
181
186
  /** The class `defineEntity` declares, to use as it is or to extend with behaviour; abstract for a base never a table. */
@@ -155,6 +155,19 @@ export interface DialectFeatures {
155
155
  * side of a value the nulls fall on.
156
156
  */
157
157
  readonly nullsSortLowest: boolean;
158
+ /**
159
+ * Whether the engine holds rows to an entity's policies itself, with `CREATE POLICY`, and whether a policy may read
160
+ * another table (CockroachDB's may not), or `false` where the querier alone holds them. See
161
+ * architecture/row-level-security.md.
162
+ */
163
+ readonly rowSecurity: {
164
+ readonly subqueries: boolean;
165
+ } | false;
166
+ /**
167
+ * Whether the querier opens a transaction of its own around a write split in steps. Where not, its steps land one by
168
+ * one, atomic only inside a transaction the caller opens (MongoDB), or none at all (D1).
169
+ */
170
+ readonly transactions: boolean;
158
171
  }
159
172
  /** How a dialect spells a row lock, once {@link DialectFeatures.rowLocks} says it has one. */
160
173
  export interface RowLockFeatures {
@@ -1,5 +1,6 @@
1
1
  import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
2
2
  import type { SqlDialectName } from './dialect.js';
3
+ import type { PolicyMeta, PolicySection } from './policy.js';
3
4
  import type { Querier } from './querier.js';
4
5
  import type { EntityAccess, FilterOptions, RelationQuery, Wire } from './query.js';
5
6
  import type { ColumnRef, JsonPathRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
@@ -321,6 +322,11 @@ export type FieldOptions<V = unknown> = {
321
322
  * stamps `new Date()`, anything else is the value or callback stamped, `softDelete: () => Date.now()`.
322
323
  */
323
324
  readonly softDelete?: true | OnFieldCallback<V>;
325
+ /**
326
+ * Makes the column the row's tenant, read off this context key (`tenantId` by default): every statement is held to
327
+ * the context's tenant, and an insert leaving it out is given it. See architecture/row-level-security.md.
328
+ */
329
+ readonly tenant?: string;
324
330
  /**
325
331
  * Makes the column an optimistic lock: an update matches the version its payload carries and writes
326
332
  * the next one, so a write against a row someone else moved on throws instead of overwriting it. The
@@ -762,6 +768,8 @@ export type EntityMeta<E> = {
762
768
  version?: FieldKey<E>;
763
769
  /** Named, default-on `$where` filters applied to every query unless bypassed. */
764
770
  filters?: Record<string, FilterOptions<E>>;
771
+ /** Row-level policies, in the order declared. See architecture/row-level-security.md. */
772
+ policies?: PolicyMeta<E>[];
765
773
  /** What a client may do over an API, see {@link Wire}; a subclass declaring none takes its base's. */
766
774
  wire?: Wire<EntityAccess>;
767
775
  fields: {
@@ -935,6 +943,8 @@ export type EntityOptions<E = unknown> = {
935
943
  /** What a client may do over an API: see {@link Wire}. */
936
944
  readonly wire?: Wire<EntityAccess>;
937
945
  readonly filters?: FilterSection<E>;
946
+ /** Row-level policies: see {@link PolicySection}. */
947
+ readonly policies?: PolicySection<E>;
938
948
  readonly indexes?: IndexSection<E>;
939
949
  /** Table-level `CHECK` constraints. See {@link CheckOptions}. */
940
950
  readonly checks?: CheckSection<E>;
@@ -11,6 +11,7 @@ export * from './query.js';
11
11
  export * from './queryAggregate.js';
12
12
  export * from './queryLock.js';
13
13
  export * from './querySql.js';
14
+ export * from './policy.js';
14
15
  export * from './definedEntity.js';
15
16
  export * from './queryWhere.js';
16
17
  export * from './universalQuerier.js';
@@ -11,6 +11,7 @@ export * from './query.js';
11
11
  export * from './queryAggregate.js';
12
12
  export * from './queryLock.js';
13
13
  export * from './querySql.js';
14
+ export * from './policy.js';
14
15
  export * from './definedEntity.js';
15
16
  export * from './queryWhere.js';
16
17
  export * from './universalQuerier.js';
@@ -1,7 +1,7 @@
1
1
  import type { AnyMigrationOperation } from '../migrate/builder/types.js';
2
2
  import type { SchemaAST } from '../schema/schemaAST.js';
3
3
  import type { DiffOptions } from '../schema/schemaASTDiffer.js';
4
- import type { CheckSchema, ColumnNode, ForeignKeyAction, IndexType, TableNode, TriggerSchema } from '../schema/types.js';
4
+ import type { CheckSchema, ColumnNode, ForeignKeyAction, IndexType, TableNode, PolicySchema, TriggerSchema } from '../schema/types.js';
5
5
  import type { Except, IndexEntry, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, AbstractType, VectorIndexOptions } from './index.js';
6
6
  /**
7
7
  * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
@@ -101,6 +101,8 @@ export interface TableSchema {
101
101
  readonly checks?: CheckSchema[];
102
102
  /** The triggers uql installed, each with the statements the engine would recreate it from. */
103
103
  readonly triggers?: TriggerSchema[];
104
+ /** The row-level policies uql installed, each with the statement the engine would recreate it from. */
105
+ readonly policies?: PolicySchema[];
104
106
  /** The statements the engine keeps for the table, where it keeps them: SQLite's `sqlite_master`. */
105
107
  readonly definition?: readonly StoredDefinition[];
106
108
  }
@@ -208,6 +210,8 @@ export interface SchemaDiff {
208
210
  * a column a trigger names, so a table whose columns change takes every trigger off and puts it back.
209
211
  */
210
212
  readonly triggers?: readonly Change<TriggerSchema>[];
213
+ /** The row-level policies installed or declared, none kept: a changed one is a new name. */
214
+ readonly policies?: readonly Change<PolicySchema>[];
211
215
  /** Columns renamed in place, `from` the database's name `to` the entity's, which the other changes already use. */
212
216
  readonly renamedColumns?: readonly Rename[];
213
217
  /**
@@ -0,0 +1,91 @@
1
+ import type { EntityAccess, UqlContext } from './query.js';
2
+ import type { QuerySql, SQL_VALUE_TYPE } from './querySql.js';
3
+ import type { QueryWhere } from './queryWhere.js';
4
+ /**
5
+ * A context key read where a policy's predicate takes a value, as data: `{ $context: 'tenantId' }`. Read off
6
+ * {@link $context}, which types it by {@link UqlContext}, so a key holding a string never meets a number column.
7
+ */
8
+ export type ContextRef<T = unknown> = unknown extends T ? ContextKeyRef : ContextKeyRef & {
9
+ readonly [SQL_VALUE_TYPE]?: NonNullable<T>;
10
+ };
11
+ /** A {@link ContextRef} whatever its value's type. */
12
+ export type ContextKeyRef = {
13
+ readonly $context: string;
14
+ };
15
+ /** The keys a declaration of {@link UqlContext} names, its index signature left out. */
16
+ type DeclaredContextKey = keyof {
17
+ [K in keyof UqlContext as string extends K ? never : number extends K ? never : K]: unknown;
18
+ };
19
+ /**
20
+ * A context key a policy may read: one {@link UqlContext} declares, so a misspelled key does not compile. Any string
21
+ * where the app declares none.
22
+ */
23
+ export type ContextKey = [DeclaredContextKey] extends [never] ? string : DeclaredContextKey & string;
24
+ /** The value context key `K` holds, `unknown` for one no declaration names. */
25
+ type ContextValue<K extends string> = K extends keyof UqlContext ? UqlContext[K] : unknown;
26
+ /**
27
+ * The context's keys as {@link ContextRef}s, each read as `$context.tenantId`: mapped over {@link UqlContext} itself, so
28
+ * a rename of a declared key reaches every read of it. Any key where the app declares none.
29
+ */
30
+ export type ContextRefs = string extends ContextKey ? {
31
+ readonly [key: string]: ContextRef;
32
+ } : {
33
+ readonly [K in keyof UqlContext as K extends ContextKey ? K : never]-?: ContextRef<UqlContext[K]>;
34
+ };
35
+ /**
36
+ * What `tenant()` takes: a column of value `V` reads its tenant off `$context.tenantId` unless given another key, which
37
+ * must hold such a value; required where `tenantId` holds none.
38
+ */
39
+ export type TenantKey<V> = string extends ContextKey ? [contextKey?: ContextRef<V>] : [ContextRef<ContextValue<'tenantId'>>] extends [ContextRef<V>] ? 'tenantId' extends ContextKey ? [contextKey?: ContextRef<V>] : [contextKey: ContextRef<V>] : [contextKey: ContextRef<V>];
40
+ /** What a policy's predicate interpolates where a query takes SQL: SQL itself, or a context key. */
41
+ export type PolicySql = QuerySql | ContextKeyRef;
42
+ /** A policy's predicate: a `$where` over the entity, its relations included, whose values may read the context. */
43
+ export type PolicyWhere<E> = QueryWhere<E, PolicySql>;
44
+ /**
45
+ * How a policy joins the others holding a statement: rows any `allow` reaches, and of them only those every `must`
46
+ * holds, Postgres's permissive and restrictive policies. An entity with policies and no `allow` for a statement
47
+ * reaches no row in it.
48
+ */
49
+ export type PolicyEffect = 'allow' | 'must';
50
+ /**
51
+ * The context a policy holds under, each key at its value or at one it lists: `{ role: ['admin', 'owner'] }`. Folded
52
+ * before the statement is written.
53
+ */
54
+ export type PolicyWhen = string extends ContextKey ? {
55
+ readonly [key: string]: unknown;
56
+ } : {
57
+ readonly [K in keyof UqlContext as K extends ContextKey ? K : never]?: UqlContext[K] | readonly UqlContext[K][];
58
+ };
59
+ /** What a policy states beyond its predicate. */
60
+ export type PolicyOptions<E> = {
61
+ /** The statements it holds, every one where unset. An update and a delete are held to the `read` ones too. */
62
+ readonly ops?: readonly EntityAccess[];
63
+ /** What a written row must hold, the predicate itself where unset: Postgres's `WITH CHECK`. */
64
+ readonly check?: PolicyWhere<E>;
65
+ readonly when?: PolicyWhen;
66
+ /** Names it in the database; derived from its effect and position where unset. */
67
+ readonly name?: string;
68
+ };
69
+ /** A policy as entity metadata keeps it, its effect and statements stated. */
70
+ export type PolicyMeta<E = object> = Omit<PolicyOptions<E>, 'ops'> & {
71
+ readonly effect: PolicyEffect;
72
+ readonly ops: readonly EntityAccess[];
73
+ readonly where: PolicyWhere<E>;
74
+ };
75
+ /**
76
+ * One policy as an entity declares it: its effect keyed to the rows it reaches, `{}` for all, beside its options.
77
+ * Data throughout, a context key read off {@link $context}: `{ must: { tenantId: $context.tenantId } }`.
78
+ */
79
+ export type Policy<E> = PolicyOptions<E> & ({
80
+ readonly allow: PolicyWhere<E>;
81
+ readonly must?: never;
82
+ } | {
83
+ readonly must: PolicyWhere<E>;
84
+ readonly allow?: never;
85
+ });
86
+ /**
87
+ * An entity's row-level policies, in order: `[{ must: { tenantId: $context.tenantId } }, { allow: { ownerId:
88
+ * $context.userId } }]`. See architecture/row-level-security.md.
89
+ */
90
+ export type PolicySection<E> = readonly Policy<E>[];
91
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -161,6 +161,18 @@ export type ListenerContext<E extends object = object> = {
161
161
  export type QuerierListener = {
162
162
  readonly [K in HookEvent]?: (ctx: ListenerContext) => Promise<void> | void;
163
163
  };
164
+ /** A statement as it is sent: its SQL and the values it binds. */
165
+ export type BoundStatement = {
166
+ readonly sql: string;
167
+ readonly values: unknown[];
168
+ };
169
+ /**
170
+ * Who holds statements to the entities' policies. `'app'`, the querier, on every engine. `'native'`, the database (the
171
+ * Postgres family): migrations install the policies, each transaction binds the context, and a role the database lets
172
+ * past them is refused under a context. `false`, nothing: a trusted pool, a job working across tenants, pointed at a
173
+ * role that bypasses row-level security. See architecture/row-level-security.md.
174
+ */
175
+ export type PolicyMode = 'app' | 'native' | false;
164
176
  export type ExtraOptions = {
165
177
  readonly logger?: LoggingOptions;
166
178
  /**
@@ -178,5 +190,7 @@ export type ExtraOptions = {
178
190
  */
179
191
  readonly schema?: string;
180
192
  readonly listeners?: readonly QuerierListener[];
193
+ /** Who holds this pool's statements to the entities' policies: see {@link PolicyMode}. `'app'` where unset. */
194
+ readonly policies?: PolicyMode;
181
195
  };
182
196
  export {};
@@ -5,7 +5,7 @@ import type { UniversalQuerier } from './universalQuerier.js';
5
5
  /** Options for a pool-level unit of work ({@link QuerierPool.withQuerier} / {@link QuerierPool.transaction}). */
6
6
  export interface PoolRunOptions {
7
7
  /**
8
- * {@link UqlContext} to run the callback under, so parameterized/`security` filters scope every
8
+ * {@link UqlContext} to run the callback under, so policies and parameterized filters scope every
9
9
  * query inside it. Same mechanism as `withContext`, scoped to this unit of work - ideal where no
10
10
  * ambient request context exists (background pipelines, queue consumers, webhooks) and the tenant
11
11
  * is known locally: `pool.withQuerier((q) => q.findMany(Invoice, {}), { context: { tenantId } })`.
@@ -50,7 +50,7 @@ export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDial
50
50
  */
51
51
  end(): Promise<void>;
52
52
  }
53
- /** A SQL pool, adding raw `all`/`run`, which no `security` filter scopes. */
53
+ /** A SQL pool, adding raw `all`/`run`, which no policy scopes but the database's own. */
54
54
  export interface SqlQuerierPool<Q extends SqlQuerier = SqlQuerier, D extends AbstractSqlDialect = AbstractSqlDialect> extends QuerierPool<Q, D>, Pick<SqlQuerier, 'all' | 'run'> {
55
55
  }
56
56
  /**
@@ -1,4 +1,5 @@
1
1
  import type { FieldKey, FieldKeyOf, JsonFieldPaths, MethodKey, RelationKey, RelationTarget, ToManyRelationKey, UpdateWrite, WrittenId } from './entity.js';
2
+ import type { PolicyWhere } from './policy.js';
2
3
  import type { QueryLock } from './queryLock.js';
3
4
  import type { QuerySql } from './querySql.js';
4
5
  import type { QueryWhere } from './queryWhere.js';
@@ -8,7 +9,7 @@ export type QueryOptions = {
8
9
  /**
9
10
  * Toggle named entity filters for this query. `false` disables all filters;
10
11
  * `{ softDelete: false }` disables one; `{ myFilter: true }` force-enables a `default: false` filter.
11
- * Security filters cannot be disabled here.
12
+ * Policies are no filters, and nothing here turns one off.
12
13
  */
13
14
  filters?: false | Record<string, boolean>;
14
15
  /**
@@ -23,13 +24,17 @@ export type QueryOptions = {
23
24
  */
24
25
  unfiltered?: boolean;
25
26
  };
27
+ /** Marks a statement as reading past the policies. A symbol, so no options a call or a client carries can name it. */
28
+ export declare const PAST_POLICIES: unique symbol;
26
29
  /**
27
30
  * What a statement runs with, on top of the options its caller passed. Kept apart from {@link QueryOptions}
28
31
  * because that one is public, the third argument of every querier method, and none of this is a caller's to set.
29
32
  */
30
33
  export type StatementOptions = QueryOptions & {
31
- /** What the statement does, which picks the `security` filters scoping it: a read by default. A write's reads take its own. */
32
- readonly access?: EntityAccess;
34
+ /** What the statement does, which picks the policies scoping it: a read by default. A write's reads take its own. */
35
+ readonly access?: ScopedAccess;
36
+ /** Reads past the policies: the querier's own read-back of what a policy check settled, or a pool not holding them. */
37
+ readonly [PAST_POLICIES]?: true;
33
38
  };
34
39
  /** What a statement is rendered with: an alias is the dialect's to choose and to spell. */
35
40
  export type QueryRenderOptions = StatementOptions & {
@@ -94,26 +99,24 @@ export type QueryPopulateRelationOptions<V, Sql = QuerySql> = IsMany<V> extends
94
99
  $required?: boolean;
95
100
  };
96
101
  /**
97
- * The per-request context parameterized filters read, set with `withContext(ctx, cb)`. An interface,
102
+ * The per-request context policies and parameterized filters read, set with `withContext(ctx, cb)`. An interface,
98
103
  * so its keys can be typed once: `declare module 'uql-orm' { interface UqlContext { tenantId: number } }`.
99
104
  */
100
105
  export interface UqlContext {
101
106
  [key: string]: unknown;
102
107
  }
103
108
  /**
104
- * A filter's `$where` fragment: a plain fragment, or a function of the ambient {@link UqlContext}.
105
- * Return `undefined` when the condition can't resolve (see {@link FilterOptions.onMissing}).
109
+ * A filter's `$where` fragment, whose values may read the context as a policy's do (`{ authorId: $context.userId }`),
110
+ * the filter skipped where the context lacks a key it reads; or a function of the ambient {@link UqlContext}, skipped
111
+ * where it answers `undefined`.
106
112
  */
107
- export type FilterWhere<E> = QueryWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);
108
- /**
109
- * What to do when a filter's condition returns `undefined`. `skip` omits it (convenience filters);
110
- * `throw` fails closed (the default for `security` filters).
111
- */
112
- export type FilterOnMissing = 'skip' | 'throw';
113
+ export type FilterWhere<E> = PolicyWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);
113
114
  /** What a field takes: reading it (select, filter, sort, distinct, aggregate) and writing it. */
114
115
  export type FieldAccess = 'read' | 'insert' | 'update';
115
116
  /** What a statement does to an entity's rows: a field's access, and deleting rows, which no field has a part in. */
116
117
  export type EntityAccess = FieldAccess | 'delete';
118
+ /** What a statement reading stored rows does, which the policies scope it by: an insert reads none. */
119
+ export type ScopedAccess = Exclude<EntityAccess, 'insert'>;
117
120
  /**
118
121
  * What a client may do to an entity, or one of its members, over an API: what it lists, nothing for `false`, and
119
122
  * everything where unset. Nothing is served by default: an entity reaches the wire only when an API's `include`
@@ -121,30 +124,14 @@ export type EntityAccess = FieldAccess | 'delete';
121
124
  */
122
125
  export type Wire<A extends EntityAccess = FieldAccess> = false | readonly A[];
123
126
  /**
124
- * Authoring shape for `@Entity({ filters })` and `defineEntity`'s `.filters()`.
127
+ * A convenience scope, `@Entity({ filters })` and `defineEntity`'s `.filters()`: switched off by name, and yielding
128
+ * to a `$where` on its own field. What must hold whatever a call asks is a policy: see {@link PolicySection}.
125
129
  */
126
130
  export type FilterOptions<E = unknown> = {
127
131
  readonly where: FilterWhere<E>;
128
132
  /** Applied to every query unless bypassed via `QueryOptions.filters`. Defaults to `true`. */
129
133
  readonly default?: boolean;
130
- } & ({
131
- readonly security?: false;
132
- /** What to do when {@link FilterOptions.where} returns `undefined`. Defaults to `skip`. */
133
- readonly onMissing?: FilterOnMissing;
134
- readonly ops?: never;
135
- } | {
136
- /**
137
- * Row-level-security filter: always applied (ignores `QueryOptions.filters` bypass) and
138
- * AND-merged so a client `$where` on the same field can't override it. It fails closed.
139
- */
140
- readonly security: true;
141
- readonly onMissing?: 'throw';
142
- /**
143
- * The statements it holds, every one by default: `['insert', 'update', 'delete']` lets anyone read a row
144
- * and only its author write it. An update or a delete reads the rows it changes, so read ones hold it too.
145
- */
146
- readonly ops?: readonly EntityAccess[];
147
- });
134
+ };
148
135
  /**
149
136
  * direction for the sort, and where nulls land in it.
150
137
  *
@@ -1,3 +1,5 @@
1
+ /** Marks a statement as reading past the policies. A symbol, so no options a call or a client carries can name it. */
2
+ export const PAST_POLICIES = Symbol('pastPolicies');
1
3
  /**
2
4
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
3
5
  * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
@@ -0,0 +1,6 @@
1
+ import type { ContextRefs } from '../type/index.js';
2
+ /**
3
+ * The context's keys as a policy reads them, each `{ $context: key }`, typed by `UqlContext`:
4
+ * `{ must: { tenantId: $context.tenantId } }`. A leaf module, so the root entry does not reach the metadata through it.
5
+ */
6
+ export declare const $context: ContextRefs;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * The context's keys as a policy reads them, each `{ $context: key }`, typed by `UqlContext`:
3
+ * `{ must: { tenantId: $context.tenantId } }`. A leaf module, so the root entry does not reach the metadata through it.
4
+ */
5
+ export const $context = new Proxy({}, { get: (_, key) => (typeof key === 'string' ? { $context: key } : undefined) });
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../schema/types.js';
2
- import { type AggregateCall, type CascadeType, type EntityAccess, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryUpsert, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type StatementOptions, type UpdatePayload, type VectorDistance } from '../type/index.js';
2
+ import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryUpsert, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type StatementOptions, type UpdatePayload, type VectorDistance } from '../type/index.js';
3
3
  import { type CallbackKey } from './field.util.js';
4
4
  /** The keys of `payload` a write persists as columns. */
5
5
  export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -127,22 +127,21 @@ export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
127
127
  */
128
128
  export declare function fieldUpdateOf(key: string, value: FieldUpdateOp): [keyof FieldUpdateOp, number | bigint | QuerySql];
129
129
  /**
130
- * `$where` with the entity's active filters merged in, against the ambient {@link UqlContext}. A convenience
131
- * filter yields to a `$where` on its key; a `security` one is always ANDed, from {@link securityConditions}.
130
+ * `$where` with the entity's active filters merged in, then ANDed with the rows its policies let the statement reach
131
+ * under the ambient {@link UqlContext}. A filter yields to a `$where` on its key; a policy yields to nothing.
132
132
  */
133
133
  export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWhere<E>, opts?: StatementOptions): QueryWhere<E>;
134
134
  /**
135
- * The condition of each `security` filter holding any of `accesses`, by name, resolved against the ambient context.
136
- * One resolving to `{}`, a trusted context's "no restriction", is left out. Reads AND these in; writes are held to them.
135
+ * Holds rows an insert or an update writes to the entity's policies under the ambient context, before the write: a
136
+ * field the check pins to one value is filled into an inserted row leaving it out, and refused where a row sets
137
+ * another. See architecture/row-level-security.md.
137
138
  */
138
- export declare function securityConditions<E>(meta: EntityMeta<E>, accesses: readonly EntityAccess[]): [name: string, condition: QueryWhere<E>][];
139
+ export declare function pinWrite<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, rows: readonly R[], write: 'insert' | 'update'): void;
139
140
  /**
140
- * Holds written rows to the `security` filters, as {@link applyFilters} holds reads: an inserted row gets
141
- * each field a condition names and it leaves out, and a row naming one must carry the condition's value.
142
- * A condition other than field equalities refuses the write, having nothing a row can be checked against.
143
- * See architecture/security-filter-writes.md.
141
+ * {@link pinWrite}, answering what the rows themselves cannot settle as the check the written rows must hold once
142
+ * written, which the querier reads back inside the write's transaction.
144
143
  */
145
- export declare function guardWrite<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, rows: readonly R[], write: 'insert' | 'update'): void;
144
+ export declare function guardWrite<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, rows: readonly R[], write: 'insert' | 'update'): QueryWhere<E> | undefined;
146
145
  /**
147
146
  * Parsed entry from a `$group` map - either a raw group key or an aggregate function call.
148
147
  */