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.
- package/dist/cockroachdb/cockroachDialect.d.ts +2 -0
- package/dist/cockroachdb/cockroachDialect.js +5 -0
- package/dist/d1/d1Querier.d.ts +2 -4
- package/dist/d1/d1Querier.js +0 -4
- package/dist/d1/d1SqliteDialect.js +1 -1
- package/dist/dialect/abstractDialect.d.ts +17 -8
- package/dist/dialect/abstractDialect.js +30 -16
- package/dist/dialect/abstractSqlDialect.d.ts +11 -2
- package/dist/dialect/abstractSqlDialect.js +17 -2
- package/dist/dialect/mysqlLikeSqlDialect.js +2 -0
- package/dist/dialect/operators.d.ts +2 -2
- package/dist/dialect/pgLikeSqlDialect.d.ts +8 -1
- package/dist/dialect/pgLikeSqlDialect.js +20 -0
- package/dist/entity/columnOptionsBuilder.d.ts +2 -1
- package/dist/entity/columnOptionsBuilder.js +3 -0
- package/dist/entity/metadata/definedFixture/author.d.ts +1 -1
- package/dist/entity/metadata/definedFixture/book.d.ts +2 -2
- package/dist/entity/metadata/definedFixture/folder.d.ts +1 -1
- package/dist/entity/metadata/definition.js +69 -30
- package/dist/http/api.d.ts +1 -1
- package/dist/http/wireQuery.js +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/migrate/ddl/tableDdl.d.ts +5 -0
- package/dist/migrate/ddl/tableDdl.js +9 -0
- package/dist/migrate/drift/driftDetector.js +2 -1
- package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +3 -1
- package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +7 -1
- package/dist/migrate/introspection/postgresIntrospector.d.ts +3 -1
- package/dist/migrate/introspection/postgresIntrospector.js +14 -1
- package/dist/migrate/introspection/tableSchemaAST.js +1 -0
- package/dist/migrate/policySql.d.ts +12 -0
- package/dist/migrate/policySql.js +74 -0
- package/dist/migrate/schemaChange.js +1 -0
- package/dist/migrate/schemaGenerator.d.ts +2 -0
- package/dist/migrate/schemaGenerator.js +37 -11
- package/dist/mongodb/mongoDialect.js +3 -1
- package/dist/mongodb/mongodbQuerier.d.ts +0 -2
- package/dist/mongodb/mongodbQuerier.js +0 -4
- package/dist/mssql/mssqlDialect.js +2 -0
- package/dist/neon/neonQuerier.d.ts +1 -2
- package/dist/nestjs/uqlContextInterceptor.d.ts +1 -1
- package/dist/nestjs/uqlContextInterceptor.js +1 -1
- package/dist/nestjs/uqlModule.d.ts +2 -2
- package/dist/nestjs/uqlModule.js +1 -1
- package/dist/querier/abstractQuerier.d.ts +31 -4
- package/dist/querier/abstractQuerier.js +120 -52
- package/dist/querier/abstractQuerierPool.js +2 -0
- package/dist/querier/abstractSqlQuerier.d.ts +16 -6
- package/dist/querier/abstractSqlQuerier.js +66 -6
- package/dist/querier/queryError.js +1 -0
- package/dist/schema/schemaAST.js +1 -0
- package/dist/schema/schemaASTBuilder.d.ts +3 -1
- package/dist/schema/schemaASTBuilder.js +1 -0
- package/dist/schema/schemaASTDiffer.js +4 -2
- package/dist/schema/types.d.ts +12 -4
- package/dist/sqlite/bindValues.d.ts +1 -1
- package/dist/sqlite/hranaQuerier.d.ts +2 -2
- package/dist/sqlite/sqliteDialect.js +2 -0
- package/dist/turso/tursoSessionQuerier.d.ts +2 -2
- package/dist/type/column.d.ts +10 -0
- package/dist/type/definedEntity.d.ts +9 -4
- package/dist/type/dialect.d.ts +13 -0
- package/dist/type/entity.d.ts +10 -0
- package/dist/type/index.d.ts +1 -0
- package/dist/type/index.js +1 -0
- package/dist/type/migration.d.ts +5 -1
- package/dist/type/policy.d.ts +91 -0
- package/dist/type/policy.js +1 -0
- package/dist/type/querier.d.ts +14 -0
- package/dist/type/querierPool.d.ts +2 -2
- package/dist/type/query.d.ts +18 -31
- package/dist/type/query.js +2 -0
- package/dist/util/contextRefs.d.ts +6 -0
- package/dist/util/contextRefs.js +5 -0
- package/dist/util/dialect.util.d.ts +10 -11
- package/dist/util/dialect.util.js +70 -56
- package/dist/util/fieldOption.util.js +1 -0
- package/dist/util/policy.util.d.ts +100 -0
- package/dist/util/policy.util.js +239 -0
- package/dist/util/uqlError.d.ts +2 -5
- package/dist/util/uqlError.js +2 -5
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +23 -13
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { AbstractSqlQuerier
|
|
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 = {
|
package/dist/type/column.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
176
|
-
|
|
177
|
-
|
|
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. */
|
package/dist/type/dialect.d.ts
CHANGED
|
@@ -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 {
|
package/dist/type/entity.d.ts
CHANGED
|
@@ -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>;
|
package/dist/type/index.d.ts
CHANGED
|
@@ -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';
|
package/dist/type/index.js
CHANGED
|
@@ -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';
|
package/dist/type/migration.d.ts
CHANGED
|
@@ -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 {};
|
package/dist/type/querier.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
/**
|
package/dist/type/query.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
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
|
|
32
|
-
readonly access?:
|
|
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
|
|
105
|
-
*
|
|
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> =
|
|
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
|
-
*
|
|
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
|
*
|
package/dist/type/query.js
CHANGED
|
@@ -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
|
|
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,
|
|
131
|
-
* filter yields to a `$where` on its key; a
|
|
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
|
-
*
|
|
136
|
-
*
|
|
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
|
|
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
|
-
*
|
|
141
|
-
*
|
|
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'):
|
|
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
|
*/
|