uql-orm 0.104.1 → 0.105.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/README.md +24 -10
- package/dist/browser/querier/httpQuerier.d.ts +3 -3
- package/dist/browser/type/clientQuerier.d.ts +1 -1
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +9 -9
- package/dist/cockroachdb/cockroachDialect.d.ts +2 -2
- package/dist/dialect/abstractDialect.d.ts +3 -3
- package/dist/dialect/abstractSqlDialect.d.ts +39 -37
- package/dist/dialect/abstractSqlDialect.js +35 -32
- package/dist/dialect/aliases.d.ts +2 -0
- package/dist/dialect/aliases.js +2 -0
- package/dist/dialect/jsonSql.js +2 -2
- package/dist/dialect/mergeSqlDialect.d.ts +2 -2
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +7 -7
- package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
- package/dist/dialect/operators.js +2 -4
- package/dist/dialect/queryJoins.d.ts +4 -2
- package/dist/dialect/vectorSqlDialect.d.ts +1 -1
- package/dist/dialect/vectorSqlDialect.js +1 -1
- package/dist/entity/column.d.ts +3 -0
- package/dist/entity/column.js +3 -0
- package/dist/entity/columnOptionsBuilder.d.ts +54 -0
- package/dist/entity/columnOptionsBuilder.js +108 -0
- package/dist/entity/decorator/bag.d.ts +5 -5
- package/dist/entity/decorator/entity.d.ts +3 -20
- package/dist/entity/decorator/entity.js +3 -37
- package/dist/entity/decorator/members.d.ts +46 -76
- package/dist/entity/decorator/members.js +18 -7
- package/dist/entity/index.d.ts +2 -1
- package/dist/entity/index.js +2 -1
- package/dist/entity/metadata/definition.d.ts +15 -26
- package/dist/entity/metadata/definition.js +344 -148
- package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
- package/dist/entity/metadata/schemaFixture/animal.js +7 -0
- package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
- package/dist/entity/metadata/schemaFixture/author.js +25 -0
- package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
- package/dist/entity/metadata/schemaFixture/book.js +23 -0
- package/dist/http/contract.d.ts +2 -2
- package/dist/http/handler.d.ts +2 -2
- package/dist/http/query.js +12 -13
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -1
- package/dist/mariadb/mariaDialect.d.ts +2 -2
- package/dist/mariadb/mariaDialect.js +1 -1
- package/dist/mariadb/mariadbQuerier.js +1 -3
- package/dist/migrate/builder/columnBuilder.d.ts +20 -68
- package/dist/migrate/builder/columnBuilder.js +104 -110
- package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
- package/dist/migrate/builder/migrationBuilder.js +7 -6
- package/dist/migrate/builder/tableBuilder.d.ts +3 -55
- package/dist/migrate/builder/tableBuilder.js +88 -204
- package/dist/migrate/builder/types.d.ts +52 -151
- package/dist/migrate/builder/types.js +0 -6
- package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
- package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
- package/dist/migrate/codegen/entityTypes.d.ts +2 -2
- package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
- package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
- package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
- package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
- package/dist/migrate/ddl/defaultSql.js +7 -6
- package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
- package/dist/migrate/ddl/indexCapabilities.js +26 -13
- package/dist/migrate/ddl/indexDdl.d.ts +13 -13
- package/dist/migrate/ddl/indexDdl.js +33 -30
- package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
- package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
- package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
- package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
- package/dist/migrate/drift/driftDetector.js +2 -2
- package/dist/migrate/generator/definitionToNode.d.ts +8 -2
- package/dist/migrate/generator/definitionToNode.js +4 -5
- package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
- package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
- package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
- package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
- package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
- package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
- package/dist/migrate/introspection/postgresIntrospector.js +3 -4
- package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
- package/dist/migrate/introspection/tableSchemaAST.js +5 -1
- package/dist/migrate/migrator.d.ts +2 -2
- package/dist/migrate/schemaChange.d.ts +3 -3
- package/dist/migrate/schemaChange.js +3 -2
- package/dist/migrate/schemaGenerator.d.ts +5 -5
- package/dist/migrate/schemaGenerator.js +1 -1
- package/dist/migrate/storage/databaseStorage.js +4 -4
- package/dist/mongodb/mongoDialect.d.ts +41 -44
- package/dist/mongodb/mongoDialect.js +118 -32
- package/dist/mongodb/mongoIntrospector.d.ts +3 -1
- package/dist/mongodb/mongoIntrospector.js +11 -5
- package/dist/mongodb/mongoSchemaGenerator.d.ts +4 -4
- package/dist/mongodb/mongoSchemaGenerator.js +35 -27
- package/dist/mongodb/mongodbQuerier.d.ts +1 -11
- package/dist/mongodb/mongodbQuerier.js +9 -43
- package/dist/mssql/mssqlDialect.d.ts +4 -4
- package/dist/postgres/postgresDialect.d.ts +2 -2
- package/dist/querier/abstractQuerier.d.ts +0 -1
- package/dist/querier/abstractQuerier.js +1 -20
- package/dist/querier/abstractSqlQuerier.d.ts +1 -1
- package/dist/querier/keyset.js +3 -3
- package/dist/schema/declaredColumn.d.ts +11 -0
- package/dist/schema/declaredColumn.js +21 -0
- package/dist/schema/indexColumns.d.ts +0 -3
- package/dist/schema/indexColumns.js +11 -7
- package/dist/schema/indexDifferences.d.ts +10 -5
- package/dist/schema/indexDifferences.js +42 -28
- package/dist/schema/schemaASTBuilder.d.ts +4 -4
- package/dist/schema/schemaASTBuilder.js +28 -36
- package/dist/schema/schemaASTDiffer.js +8 -4
- package/dist/schema/sqlExpression.d.ts +21 -17
- package/dist/schema/sqlExpression.js +11 -23
- package/dist/type/column.d.ts +328 -0
- package/dist/type/column.js +2 -0
- package/dist/type/config.d.ts +3 -3
- package/dist/type/dialect.d.ts +15 -14
- package/dist/type/dialect.js +1 -0
- package/dist/type/entity.d.ts +292 -281
- package/dist/type/entity.js +6 -1
- package/dist/type/index.d.ts +2 -0
- package/dist/type/index.js +2 -0
- package/dist/type/migration.d.ts +11 -11
- package/dist/type/querier.d.ts +2 -2
- package/dist/type/query.d.ts +44 -40
- package/dist/type/query.js +2 -3
- package/dist/type/queryAggregate.d.ts +22 -12
- package/dist/type/querySql.d.ts +22 -6
- package/dist/type/querySql.js +27 -9
- package/dist/type/schemaEntity.d.ts +194 -0
- package/dist/type/schemaEntity.js +1 -0
- package/dist/type/utility.d.ts +4 -7
- package/dist/type/vector.d.ts +1 -1
- package/dist/util/ddlExpression.util.d.ts +12 -13
- package/dist/util/ddlExpression.util.js +12 -21
- package/dist/util/dialect.util.d.ts +11 -5
- package/dist/util/dialect.util.js +31 -37
- package/dist/util/field.util.d.ts +10 -9
- package/dist/util/field.util.js +14 -10
- package/dist/util/fieldOption.util.d.ts +11 -95
- package/dist/util/fieldOption.util.js +49 -16
- package/dist/util/hook.util.d.ts +3 -15
- package/dist/util/hook.util.js +3 -16
- package/dist/util/index.d.ts +1 -0
- package/dist/util/index.js +1 -0
- package/dist/util/indexEntry.util.d.ts +45 -0
- package/dist/util/indexEntry.util.js +138 -0
- package/dist/util/relationQuery.util.d.ts +0 -1
- package/dist/util/relationQuery.util.js +0 -5
- package/dist/util/sql.d.ts +13 -10
- package/dist/util/sql.js +34 -16
- package/dist/util/sql.util.d.ts +4 -5
- package/dist/util/sql.util.js +7 -16
- package/dist/util/string.util.d.ts +2 -0
- package/dist/util/string.util.js +4 -0
- package/dist/util/triggerWrite.d.ts +5 -5
- package/dist/util/uqlError.d.ts +1 -1
- package/dist/util/uqlError.js +1 -1
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +76 -25
- package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
|
@@ -1,104 +1,20 @@
|
|
|
1
|
-
import { type
|
|
2
|
-
/**
|
|
3
|
-
|
|
4
|
-
* Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
|
|
5
|
-
* discipline `INDEX_FEATURE_LABELS` uses for index features.
|
|
6
|
-
*/
|
|
7
|
-
declare const FIELD_OPTION_FAMILY: {
|
|
8
|
-
readonly name: '*';
|
|
9
|
-
readonly isId: '*';
|
|
10
|
-
readonly type: '*';
|
|
11
|
-
readonly dimensions: 'vector';
|
|
12
|
-
readonly distance: 'vector';
|
|
13
|
-
readonly references: '*';
|
|
14
|
-
readonly onDelete: '*';
|
|
15
|
-
readonly enum: '*';
|
|
16
|
-
readonly computed: '*';
|
|
17
|
-
readonly stored: '*';
|
|
18
|
-
readonly updatable: '*';
|
|
19
|
-
readonly eager: '*';
|
|
20
|
-
readonly onInsert: '*';
|
|
21
|
-
readonly onUpdate: '*';
|
|
22
|
-
readonly softDelete: '*';
|
|
23
|
-
readonly version: 'numeric';
|
|
24
|
-
readonly columnType: '*';
|
|
25
|
-
readonly length: 'string';
|
|
26
|
-
readonly precision: readonly ["numeric", "date"];
|
|
27
|
-
readonly scale: 'numeric';
|
|
28
|
-
readonly nullable: '*';
|
|
29
|
-
readonly unique: '*';
|
|
30
|
-
readonly defaultValue: '*';
|
|
31
|
-
readonly autoIncrement: 'numeric';
|
|
32
|
-
readonly index: '*';
|
|
33
|
-
readonly comment: '*';
|
|
34
|
-
};
|
|
35
|
-
/**
|
|
36
|
-
* The only options an inlined computed field reaches: it is skipped in DDL and dropped from every insert and
|
|
37
|
-
* update, so the whole persistence half of the options above is dead on one. Stated as what survives
|
|
38
|
-
* rather than on each option that dies, because it is one fact rather than nineteen - and because an
|
|
39
|
-
* option added without a thought then lands on the safe side of it.
|
|
40
|
-
*/
|
|
41
|
-
declare const INLINE_READS: readonly ["type", "computed", "stored", "enum", "eager", "distance"];
|
|
42
|
-
type InlineRead = (typeof INLINE_READS)[number];
|
|
43
|
-
/**
|
|
44
|
-
* What a column the *database* writes cannot use. A stored computed column is a real column - it has
|
|
45
|
-
* DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
|
|
46
|
-
* `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
|
|
47
|
-
*/
|
|
48
|
-
declare const GENERATED_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "version"];
|
|
49
|
-
type GeneratedWrite = (typeof GENERATED_WRITES)[number];
|
|
50
|
-
/**
|
|
51
|
-
* What an optimistic lock cannot use: the querier writes the column on every update and matches the
|
|
52
|
-
* value the payload carried, so anything else deciding it would be fighting that, and the three that
|
|
53
|
-
* would make it another kind of column entirely. Its `nullable: false` and `DEFAULT 0` are implied.
|
|
54
|
-
*/
|
|
55
|
-
declare const VERSION_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "computed", "stored", "isId"];
|
|
56
|
-
type VersionWrite = (typeof VERSION_WRITES)[number];
|
|
1
|
+
import { type FieldOptions } from '../type/index.js';
|
|
2
|
+
/** Every option that decides what a column holds, or whether it is written at all. */
|
|
3
|
+
export declare const VALUE_DECIDERS: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement"];
|
|
57
4
|
/**
|
|
58
5
|
* What bounds a type: stated separately where uql spells the type, and part of the text where the
|
|
59
6
|
* engine's own is written out, which renders verbatim and leaves these unread.
|
|
60
7
|
*/
|
|
61
|
-
declare const TYPE_BOUNDS: readonly ["length", "precision", "scale", "dimensions"];
|
|
62
|
-
type TypeBound = (typeof TYPE_BOUNDS)[number];
|
|
8
|
+
export declare const TYPE_BOUNDS: readonly ["length", "precision", "scale", "dimensions"];
|
|
63
9
|
/**
|
|
64
10
|
* The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
|
|
65
|
-
* where every option applies. The runtime half of the decorators' check, so
|
|
66
|
-
*
|
|
11
|
+
* where every option applies. The runtime half of the decorators' check, so plain JavaScript reaches
|
|
12
|
+
* the same answer.
|
|
67
13
|
*/
|
|
68
14
|
export declare function fieldOptionConflict(opts: FieldOptions): string | undefined;
|
|
69
|
-
/**
|
|
70
|
-
type
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
} ? FamilyOf<T> : ColumnFamily;
|
|
75
|
-
/** What the field's own values leave unread, matching {@link deadOn} line for line. */
|
|
76
|
-
type DeadOptions<O> = (O extends {
|
|
77
|
-
readonly stored: true | readonly StampEvent[];
|
|
78
|
-
} ? GeneratedWrite : O extends {
|
|
79
|
-
readonly computed: QuerySql;
|
|
80
|
-
} ? Exclude<keyof FieldOptions, InlineRead> : never) | (O extends {
|
|
81
|
-
readonly isId: true;
|
|
82
|
-
readonly nullable: true;
|
|
83
|
-
} ? 'nullable' : never) | (O extends {
|
|
84
|
-
readonly updatable: false;
|
|
85
|
-
} ? 'onUpdate' : never) | (O extends {
|
|
86
|
-
readonly columnType: QuerySql;
|
|
87
|
-
} ? TypeBound : never) | (O extends {
|
|
88
|
-
readonly version: true;
|
|
89
|
-
} ? VersionWrite : never) | (O extends {
|
|
90
|
-
readonly version: true;
|
|
91
|
-
readonly nullable: true;
|
|
92
|
-
} ? 'nullable' : never);
|
|
93
|
-
type Given<O> = Extract<keyof O, keyof FieldOptions>;
|
|
94
|
-
/** The families option `K` applies to, `'*'` for every one. */
|
|
95
|
-
type OptionFamilies<K extends keyof FieldOptions> = (typeof FIELD_OPTION_FAMILY)[K] extends readonly (infer F)[] ? F : (typeof FIELD_OPTION_FAMILY)[K];
|
|
96
|
-
type Offending<O> = {
|
|
97
|
-
[K in Given<O>]: [Extract<OptionFamilies<K>, OptionsFamily<O> | '*'>] extends [never] ? K : K extends DeadOptions<O> ? K : never;
|
|
98
|
-
}[Given<O>];
|
|
99
|
-
/**
|
|
100
|
-
* Every option `O` states but cannot use, mapped to `never`, so one that would be ignored does not compile.
|
|
101
|
-
* `@Id` states `{ nullable?: false }` itself, since `O` has to stay naked to be inferred.
|
|
102
|
-
*/
|
|
103
|
-
export type RejectIncompatible<O> = [Offending<O>] extends [never] ? unknown : Record<Offending<O> & string, never>;
|
|
15
|
+
/** What `typeof` answers on a value of `T`, where a column's values are checked: a date, a document or bytes are not. */
|
|
16
|
+
type ValueTypeOf<T> = T extends string ? 'string' : T extends number ? 'number' : T extends bigint ? 'bigint' : T extends boolean ? 'boolean' : never;
|
|
17
|
+
type ValueType = ValueTypeOf<string | number | bigint | boolean>;
|
|
18
|
+
/** What `typeof` a value answers on a column of `type`, as `TsTypeOf` types it; nothing where none is checked. */
|
|
19
|
+
export declare function valueTypesOf(type: FieldOptions['type']): readonly ValueType[] | undefined;
|
|
104
20
|
export {};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { QuerySql } from '../type/index.js';
|
|
2
|
-
import { fieldFamily, isInlinedExpression } from './field.util.js';
|
|
1
|
+
import { QuerySql, } from '../type/index.js';
|
|
2
|
+
import { columnFamily, fieldFamily, isInlinedExpression } from './field.util.js';
|
|
3
3
|
import { getKeys } from './object.util.js';
|
|
4
4
|
import { constantSql } from './sql.js';
|
|
5
5
|
/**
|
|
@@ -16,6 +16,7 @@ const FIELD_OPTION_FAMILY = {
|
|
|
16
16
|
references: '*',
|
|
17
17
|
onDelete: '*',
|
|
18
18
|
enum: '*',
|
|
19
|
+
shape: 'json',
|
|
19
20
|
computed: '*',
|
|
20
21
|
stored: '*',
|
|
21
22
|
updatable: '*',
|
|
@@ -49,9 +50,10 @@ const INLINE_READS = [
|
|
|
49
50
|
'enum',
|
|
50
51
|
'eager',
|
|
51
52
|
'distance',
|
|
53
|
+
'nullable',
|
|
52
54
|
];
|
|
53
55
|
/** Every option that decides what a column holds, or whether it is written at all. */
|
|
54
|
-
const VALUE_DECIDERS = [
|
|
56
|
+
export const VALUE_DECIDERS = [
|
|
55
57
|
'updatable',
|
|
56
58
|
'onInsert',
|
|
57
59
|
'onUpdate',
|
|
@@ -68,43 +70,41 @@ const GENERATED_WRITES = [...VALUE_DECIDERS, 'version'];
|
|
|
68
70
|
/**
|
|
69
71
|
* What an optimistic lock cannot use: the querier writes the column on every update and matches the
|
|
70
72
|
* value the payload carried, so anything else deciding it would be fighting that, and the three that
|
|
71
|
-
* would make it another kind of column entirely. Its `
|
|
73
|
+
* would make it another kind of column entirely. Its `DEFAULT 0` is implied.
|
|
72
74
|
*/
|
|
73
75
|
const VERSION_WRITES = [...VALUE_DECIDERS, 'computed', 'stored', 'isId'];
|
|
74
76
|
/**
|
|
75
77
|
* What bounds a type: stated separately where uql spells the type, and part of the text where the
|
|
76
78
|
* engine's own is written out, which renders verbatim and leaves these unread.
|
|
77
79
|
*/
|
|
78
|
-
const TYPE_BOUNDS = [
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
return key === 'nullable' && opts.nullable === true;
|
|
85
|
-
}
|
|
80
|
+
export const TYPE_BOUNDS = [
|
|
81
|
+
'length',
|
|
82
|
+
'precision',
|
|
83
|
+
'scale',
|
|
84
|
+
'dimensions',
|
|
85
|
+
];
|
|
86
86
|
/** Whatever leaves `key` unread, named for the message, or `undefined` where the field reads it. */
|
|
87
87
|
function deadOn(opts, key) {
|
|
88
88
|
if (isInlinedExpression(opts) && !INLINE_READS.some((read) => read === key))
|
|
89
89
|
return 'an inlined computed field';
|
|
90
90
|
if (opts.stored && GENERATED_WRITES.some((write) => write === key))
|
|
91
91
|
return 'a column the database writes';
|
|
92
|
-
if (opts.isId === true &&
|
|
92
|
+
if (opts.isId === true && key === 'nullable')
|
|
93
93
|
return 'a primary key';
|
|
94
94
|
if (opts.updatable === false && key === 'onUpdate')
|
|
95
95
|
return "a field declared 'updatable: false'";
|
|
96
96
|
if (opts.columnType instanceof QuerySql && TYPE_BOUNDS.some((bound) => bound === key)) {
|
|
97
97
|
return 'a column type written out as SQL, which carries its own bounds';
|
|
98
98
|
}
|
|
99
|
-
if (opts.version === true && (VERSION_WRITES.some((write) => write === key) ||
|
|
99
|
+
if (opts.version === true && (VERSION_WRITES.some((write) => write === key) || key === 'nullable')) {
|
|
100
100
|
return 'a version field';
|
|
101
101
|
}
|
|
102
102
|
return undefined;
|
|
103
103
|
}
|
|
104
104
|
/**
|
|
105
105
|
* The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
|
|
106
|
-
* where every option applies. The runtime half of the decorators' check, so
|
|
107
|
-
*
|
|
106
|
+
* where every option applies. The runtime half of the decorators' check, so plain JavaScript reaches
|
|
107
|
+
* the same answer.
|
|
108
108
|
*/
|
|
109
109
|
export function fieldOptionConflict(opts) {
|
|
110
110
|
// Caught here rather than where the type is resolved, which is a migration on most engines and a
|
|
@@ -112,6 +112,10 @@ export function fieldOptionConflict(opts) {
|
|
|
112
112
|
if (opts.columnType instanceof QuerySql && constantSql(opts.columnType) === undefined) {
|
|
113
113
|
return "cannot use 'columnType': a `sql` one names a constant type, so it can bind no value and read no column";
|
|
114
114
|
}
|
|
115
|
+
const stray = enumStray(opts);
|
|
116
|
+
if (stray) {
|
|
117
|
+
return stray;
|
|
118
|
+
}
|
|
115
119
|
const family = fieldFamily(opts);
|
|
116
120
|
// Walked in table order, not in the order the field happened to be written, so a field with two
|
|
117
121
|
// conflicts always reports the same one. An option no rule knows is a typo, which `@Field`'s own check
|
|
@@ -130,3 +134,32 @@ export function fieldOptionConflict(opts) {
|
|
|
130
134
|
}
|
|
131
135
|
return undefined;
|
|
132
136
|
}
|
|
137
|
+
/** The values each family holds. A family left out is not checked. */
|
|
138
|
+
const VALUE_TYPES_OF_FAMILY = {
|
|
139
|
+
string: { string: true },
|
|
140
|
+
numeric: { number: true, bigint: true },
|
|
141
|
+
boolean: { boolean: true },
|
|
142
|
+
};
|
|
143
|
+
/** Where a type's family does not decide its values: a constructor holds one kind, and `time` and an exact decimal read as text. */
|
|
144
|
+
const VALUE_TYPES_OF_TYPE = new Map([
|
|
145
|
+
[Number, { number: true }],
|
|
146
|
+
[BigInt, { bigint: true }],
|
|
147
|
+
['time', { string: true }],
|
|
148
|
+
['decimal', { string: true }],
|
|
149
|
+
['numeric', { string: true }],
|
|
150
|
+
]);
|
|
151
|
+
/** What `typeof` a value answers on a column of `type`, as `TsTypeOf` types it; nothing where none is checked. */
|
|
152
|
+
export function valueTypesOf(type) {
|
|
153
|
+
const family = columnFamily(type);
|
|
154
|
+
const held = VALUE_TYPES_OF_TYPE.get(type) ?? (family && VALUE_TYPES_OF_FAMILY[family]);
|
|
155
|
+
return held && getKeys(held);
|
|
156
|
+
}
|
|
157
|
+
/** An `enum` member its `type` cannot hold, which the row would still type as that member. */
|
|
158
|
+
function enumStray(opts) {
|
|
159
|
+
const types = valueTypesOf(opts.type);
|
|
160
|
+
const stray = types && opts.enum?.find((member) => !types.some((type) => type === typeof member));
|
|
161
|
+
if (!types || stray === undefined)
|
|
162
|
+
return undefined;
|
|
163
|
+
const shown = typeof stray === 'string' ? `'${stray}'` : String(stray);
|
|
164
|
+
return `cannot use 'enum': its member ${shown} is no ${types.join(' or ')}, which its type holds`;
|
|
165
|
+
}
|
package/dist/util/hook.util.d.ts
CHANGED
|
@@ -1,15 +1,3 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
/**
|
|
3
|
-
|
|
4
|
-
* must wait until that transaction commits.
|
|
5
|
-
*/
|
|
6
|
-
export type HookContext = {
|
|
7
|
-
readonly querier: Querier;
|
|
8
|
-
readonly onCommit: Querier['onCommit'];
|
|
9
|
-
};
|
|
10
|
-
/**
|
|
11
|
-
* Run all registered hooks for the given event on each payload.
|
|
12
|
-
* Hooks are invoked with `this` bound to the payload via `call`,
|
|
13
|
-
* so mutations go directly to the original object.
|
|
14
|
-
*/
|
|
15
|
-
export declare function runHooks<E extends object>(entity: Type<E>, event: HookEvent, payloads: readonly E[], ctx: HookContext): Promise<void>;
|
|
1
|
+
import type { HookContext, HookEvent, AbstractType } from '../type/index.js';
|
|
2
|
+
/** Runs each hook registered for `event` on each payload, in order, awaiting each: a hook mutates the payload itself. */
|
|
3
|
+
export declare function runHooks<E extends object>(entity: AbstractType<E>, event: HookEvent, payloads: readonly E[], ctx: HookContext): Promise<void>;
|
package/dist/util/hook.util.js
CHANGED
|
@@ -1,26 +1,13 @@
|
|
|
1
1
|
import { getMeta } from '../entity/index.js';
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* Run all registered hooks for the given event on each payload.
|
|
5
|
-
* Hooks are invoked with `this` bound to the payload via `call`,
|
|
6
|
-
* so mutations go directly to the original object.
|
|
7
|
-
*/
|
|
2
|
+
/** Runs each hook registered for `event` on each payload, in order, awaiting each: a hook mutates the payload itself. */
|
|
8
3
|
export async function runHooks(entity, event, payloads, ctx) {
|
|
9
4
|
const meta = getMeta(entity);
|
|
10
5
|
const registrations = meta.hooks?.[event];
|
|
11
6
|
if (!registrations?.length)
|
|
12
7
|
return;
|
|
13
|
-
// A prototype is typed `any`, so what is read off it is typed here, where it enters.
|
|
14
|
-
const prototype = entity.prototype;
|
|
15
8
|
for (const payload of payloads) {
|
|
16
|
-
for (const
|
|
17
|
-
|
|
18
|
-
if (typeof method !== 'function') {
|
|
19
|
-
throw new UqlUsageError(`'${entity.name}' runs '${methodName}' on ${event}, but has no such method`);
|
|
20
|
-
}
|
|
21
|
-
const result = method.call(payload, ctx);
|
|
22
|
-
if (result instanceof Promise)
|
|
23
|
-
await result;
|
|
9
|
+
for (const hook of registrations) {
|
|
10
|
+
await hook.run(payload, ctx);
|
|
24
11
|
}
|
|
25
12
|
}
|
|
26
13
|
}
|
package/dist/util/index.d.ts
CHANGED
|
@@ -5,6 +5,7 @@ export * from './fieldOption.util.js';
|
|
|
5
5
|
export * from './filters.util.js';
|
|
6
6
|
export * from './hook.util.js';
|
|
7
7
|
export * from './ddlExpression.util.js';
|
|
8
|
+
export * from './indexEntry.util.js';
|
|
8
9
|
export * from './logger.js';
|
|
9
10
|
export * from './object.util.js';
|
|
10
11
|
export * from './sql.js';
|
package/dist/util/index.js
CHANGED
|
@@ -5,6 +5,7 @@ export * from './fieldOption.util.js';
|
|
|
5
5
|
export * from './filters.util.js';
|
|
6
6
|
export * from './hook.util.js';
|
|
7
7
|
export * from './ddlExpression.util.js';
|
|
8
|
+
export * from './indexEntry.util.js';
|
|
8
9
|
export * from './logger.js';
|
|
9
10
|
export * from './object.util.js';
|
|
10
11
|
export * from './sql.js';
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { type EntityIndexColumnInput, type FieldType, type IndexColumnInput, type IndexEntry, type IndexEntryModifiers, type IndexValueType, QuerySql } from '../type/index.js';
|
|
2
|
+
/**
|
|
3
|
+
* Reduces an index entry, authored or the migration builder's, to the one form metadata keeps: a column read
|
|
4
|
+
* off the refs as its key, a JSON path as its column and dotted path, any other `sql` as its expression.
|
|
5
|
+
*/
|
|
6
|
+
export declare function normalizeIndexColumn(entry: IndexColumnInput | EntityIndexColumnInput): IndexEntry;
|
|
7
|
+
/** An index entry as the schema holds it, its expression rendered to text by `render`. */
|
|
8
|
+
export declare function renderIndexColumn(entry: IndexEntry, render: (statement: QuerySql) => string): IndexEntry<string>;
|
|
9
|
+
/** An entry over a column as stored. */
|
|
10
|
+
export type StoredEntry<Sql> = IndexEntry<Sql> & {
|
|
11
|
+
readonly column: string;
|
|
12
|
+
};
|
|
13
|
+
/** Whether every entry is a column as stored. */
|
|
14
|
+
export declare function isStored<Sql>(entries: readonly IndexEntry<Sql>[]): entries is readonly StoredEntry<Sql>[];
|
|
15
|
+
/** Each entry's column as stored, or `undefined` where any entry is not one. */
|
|
16
|
+
export declare function storedColumns(entries: readonly IndexEntry<unknown>[]): string[] | undefined;
|
|
17
|
+
/** The column an entry keys whole, with no prefix; a JSON path or an expression keys none. */
|
|
18
|
+
export declare function wholeColumn(entry: IndexEntry<unknown>): string | undefined;
|
|
19
|
+
/** The column an entry reads, as stored or as the document a JSON path reads into; an expression reads none. */
|
|
20
|
+
export declare function entryColumn(entry: IndexEntry<unknown>): string | undefined;
|
|
21
|
+
/** The columns `entries` read, a JSON path's included. */
|
|
22
|
+
export declare function entryColumns(entries: readonly IndexEntry<unknown>[]): string[];
|
|
23
|
+
/** What an entry keys: its column, then the keys of a JSON path inside it, if any; an expression keys none. */
|
|
24
|
+
export declare function entryKeys(entry: IndexEntry<unknown>): string[] | undefined;
|
|
25
|
+
/**
|
|
26
|
+
* What an entry adds to a derived index name: its column and its path's keys (`kind_theme`), or `expr<at>` for
|
|
27
|
+
* an expression, which has none. The one rule both naming an index and recognising a name read.
|
|
28
|
+
*/
|
|
29
|
+
export declare function indexEntryNamePart(entry: IndexEntry<unknown>, at: number): string;
|
|
30
|
+
/** How an entry keys, without what it keys: its order, nulls, operator class and weight. */
|
|
31
|
+
export declare function entryModifiers<Sql>(entry: IndexEntry<Sql>): IndexEntryModifiers;
|
|
32
|
+
/** `entry` with the column it reads, as stored or as the document a JSON path reads into, renamed by `rename`. */
|
|
33
|
+
export declare function renamedEntry<Sql>(entry: IndexEntry<Sql>, rename: (column: string) => string): IndexEntry<Sql>;
|
|
34
|
+
/** How an index reads a JSON column: the value at `path` as `type`, or with `elements`, each element of the array there. */
|
|
35
|
+
export type JsonIndexRead = {
|
|
36
|
+
readonly column: string;
|
|
37
|
+
readonly path: string;
|
|
38
|
+
readonly type: FieldType;
|
|
39
|
+
readonly elements: boolean;
|
|
40
|
+
readonly charLength?: number;
|
|
41
|
+
};
|
|
42
|
+
/** The JSON read an entry indexes, `undefined` for a column or an expression; a path says nothing to be read as text. */
|
|
43
|
+
export declare function jsonIndexRead(entry: IndexEntry<unknown>): JsonIndexRead | undefined;
|
|
44
|
+
/** Whether an index reads each element of an array, `[type]`, rather than one value. */
|
|
45
|
+
export declare function isElementsType(type: IndexValueType | undefined): type is readonly [FieldType];
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { ColumnRef, JSON_PATH, JsonPathRef, QuerySql, REF_KEY, } from '../type/index.js';
|
|
2
|
+
import { jsonPathKeys } from './field.util.js';
|
|
3
|
+
import { UqlUsageError } from './uqlError.js';
|
|
4
|
+
/**
|
|
5
|
+
* Every key an index entry takes. Checked at run time because TypeScript never checks a callback's returned
|
|
6
|
+
* literal for excess properties, so a misspelt option would otherwise build an index without it.
|
|
7
|
+
*/
|
|
8
|
+
const INDEX_ENTRY_KEYS = {
|
|
9
|
+
column: true,
|
|
10
|
+
json: true,
|
|
11
|
+
path: true,
|
|
12
|
+
type: true,
|
|
13
|
+
expression: true,
|
|
14
|
+
prefixLength: true,
|
|
15
|
+
charLength: true,
|
|
16
|
+
order: true,
|
|
17
|
+
nulls: true,
|
|
18
|
+
opsClass: true,
|
|
19
|
+
weight: true,
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* Reduces an index entry, authored or the migration builder's, to the one form metadata keeps: a column read
|
|
23
|
+
* off the refs as its key, a JSON path as its column and dotted path, any other `sql` as its expression.
|
|
24
|
+
*/
|
|
25
|
+
export function normalizeIndexColumn(entry) {
|
|
26
|
+
if (typeof entry === 'string' || entry instanceof QuerySql || entry instanceof JsonPathRef) {
|
|
27
|
+
return entryTarget(entry);
|
|
28
|
+
}
|
|
29
|
+
const unknown = Object.keys(entry).find((key) => !Object.hasOwn(INDEX_ENTRY_KEYS, key));
|
|
30
|
+
if (unknown) {
|
|
31
|
+
throw new UqlUsageError(`an index entry has no option '${unknown}'`);
|
|
32
|
+
}
|
|
33
|
+
if (entry.column === undefined && entry.json === undefined && entry.expression === undefined) {
|
|
34
|
+
throw new UqlUsageError('an index entry names no column or expression');
|
|
35
|
+
}
|
|
36
|
+
if (entry.column === undefined) {
|
|
37
|
+
return entry;
|
|
38
|
+
}
|
|
39
|
+
if (typeof entry.column === 'string') {
|
|
40
|
+
refuseLength('charLength', entry.charLength, 'a stored column');
|
|
41
|
+
return entry;
|
|
42
|
+
}
|
|
43
|
+
const { column, type, prefixLength, charLength, ...modifiers } = entry;
|
|
44
|
+
const target = entryTarget(column);
|
|
45
|
+
if (target.column !== undefined && type === undefined) {
|
|
46
|
+
refuseLength('charLength', charLength, 'a stored column');
|
|
47
|
+
return { ...modifiers, column: target.column, ...(prefixLength !== undefined && { prefixLength }) };
|
|
48
|
+
}
|
|
49
|
+
if (target.expression !== undefined) {
|
|
50
|
+
refuseLength('prefixLength', prefixLength, 'an expression');
|
|
51
|
+
refuseLength('charLength', charLength, 'an expression');
|
|
52
|
+
return { ...modifiers, expression: target.expression };
|
|
53
|
+
}
|
|
54
|
+
refuseLength('prefixLength', prefixLength, 'a JSON path');
|
|
55
|
+
return {
|
|
56
|
+
...modifiers,
|
|
57
|
+
json: target.json ?? target.column,
|
|
58
|
+
...(target.path !== undefined && { path: target.path }),
|
|
59
|
+
...(type !== undefined && { type }),
|
|
60
|
+
...(charLength !== undefined && { charLength }),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
function entryTarget(target) {
|
|
64
|
+
if (typeof target === 'string') {
|
|
65
|
+
return { column: target };
|
|
66
|
+
}
|
|
67
|
+
if (target instanceof JsonPathRef) {
|
|
68
|
+
return { json: target[REF_KEY], path: target[JSON_PATH] };
|
|
69
|
+
}
|
|
70
|
+
return target instanceof ColumnRef ? { column: target[REF_KEY] } : { expression: target };
|
|
71
|
+
}
|
|
72
|
+
/** Refuses a length an entry's target does not take, which only a column's ref and other `sql` leave to run time. */
|
|
73
|
+
function refuseLength(option, length, target) {
|
|
74
|
+
if (length !== undefined) {
|
|
75
|
+
throw new UqlUsageError(`an index entry over ${target} takes no ${option}`);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
/** An index entry as the schema holds it, its expression rendered to text by `render`. */
|
|
79
|
+
export function renderIndexColumn(entry, render) {
|
|
80
|
+
return entry.expression === undefined ? entry : { ...entry, expression: render(entry.expression) };
|
|
81
|
+
}
|
|
82
|
+
/** Whether every entry is a column as stored. */
|
|
83
|
+
export function isStored(entries) {
|
|
84
|
+
return entries.every((entry) => entry.column !== undefined);
|
|
85
|
+
}
|
|
86
|
+
/** Each entry's column as stored, or `undefined` where any entry is not one. */
|
|
87
|
+
export function storedColumns(entries) {
|
|
88
|
+
return isStored(entries) ? entries.map((entry) => entry.column) : undefined;
|
|
89
|
+
}
|
|
90
|
+
/** The column an entry keys whole, with no prefix; a JSON path or an expression keys none. */
|
|
91
|
+
export function wholeColumn(entry) {
|
|
92
|
+
return entry.prefixLength === undefined ? entry.column : undefined;
|
|
93
|
+
}
|
|
94
|
+
/** The column an entry reads, as stored or as the document a JSON path reads into; an expression reads none. */
|
|
95
|
+
export function entryColumn(entry) {
|
|
96
|
+
return entry.column ?? entry.json;
|
|
97
|
+
}
|
|
98
|
+
/** The columns `entries` read, a JSON path's included. */
|
|
99
|
+
export function entryColumns(entries) {
|
|
100
|
+
return entries.flatMap((entry) => entryColumn(entry) ?? []);
|
|
101
|
+
}
|
|
102
|
+
/** What an entry keys: its column, then the keys of a JSON path inside it, if any; an expression keys none. */
|
|
103
|
+
export function entryKeys(entry) {
|
|
104
|
+
const column = entryColumn(entry);
|
|
105
|
+
return column === undefined ? undefined : [column, ...(entry.path ? jsonPathKeys(entry.path) : [])];
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* What an entry adds to a derived index name: its column and its path's keys (`kind_theme`), or `expr<at>` for
|
|
109
|
+
* an expression, which has none. The one rule both naming an index and recognising a name read.
|
|
110
|
+
*/
|
|
111
|
+
export function indexEntryNamePart(entry, at) {
|
|
112
|
+
return entryKeys(entry)?.join('_') ?? `expr${at}`;
|
|
113
|
+
}
|
|
114
|
+
/** How an entry keys, without what it keys: its order, nulls, operator class and weight. */
|
|
115
|
+
export function entryModifiers(entry) {
|
|
116
|
+
const { column: _column, json: _json, path: _path, type: _type, expression: _expression, prefixLength: _prefixLength, charLength: _charLength, ...modifiers } = entry;
|
|
117
|
+
return modifiers;
|
|
118
|
+
}
|
|
119
|
+
/** `entry` with the column it reads, as stored or as the document a JSON path reads into, renamed by `rename`. */
|
|
120
|
+
export function renamedEntry(entry, rename) {
|
|
121
|
+
if (entry.column !== undefined) {
|
|
122
|
+
return { ...entry, column: rename(entry.column) };
|
|
123
|
+
}
|
|
124
|
+
return entry.json === undefined ? entry : { ...entry, json: rename(entry.json) };
|
|
125
|
+
}
|
|
126
|
+
/** The JSON read an entry indexes, `undefined` for a column or an expression; a path says nothing to be read as text. */
|
|
127
|
+
export function jsonIndexRead(entry) {
|
|
128
|
+
if (entry.json === undefined) {
|
|
129
|
+
return undefined;
|
|
130
|
+
}
|
|
131
|
+
const { json: column, path = '', type = String, charLength } = entry;
|
|
132
|
+
const elements = isElementsType(type);
|
|
133
|
+
return { column, path, type: elements ? type[0] : type, elements, charLength };
|
|
134
|
+
}
|
|
135
|
+
/** Whether an index reads each element of an array, `[type]`, rather than one value. */
|
|
136
|
+
export function isElementsType(type) {
|
|
137
|
+
return Array.isArray(type);
|
|
138
|
+
}
|
|
@@ -68,5 +68,4 @@ export type ParsedRelationQuery<E extends object = object> = {
|
|
|
68
68
|
export declare function parseRelationQueryValue<E extends object = object>(value: unknown): ParsedRelationQuery<E>;
|
|
69
69
|
/** Parses the relation payload for `relKey` */
|
|
70
70
|
export declare function parseRelationAtKey<E>(relKey: RelationKey<E>, populate?: QueryPopulate<E>): ParsedRelationQuery;
|
|
71
|
-
export declare function forEachRequestedRelation<E extends object>(meta: EntityMeta<E>, populate: QueryPopulate<E> | undefined, fn: (relKey: RelationKey<E>, rawValue: unknown) => void): void;
|
|
72
71
|
export {};
|
|
@@ -182,11 +182,6 @@ export function parseRelationQueryValue(value) {
|
|
|
182
182
|
export function parseRelationAtKey(relKey, populate) {
|
|
183
183
|
return parseRelationQueryValue(populate?.[relKey]);
|
|
184
184
|
}
|
|
185
|
-
export function forEachRequestedRelation(meta, populate, fn) {
|
|
186
|
-
for (const relKey of getRelationRequestSummary(meta, populate).requestedKeys) {
|
|
187
|
-
fn(relKey, populate?.[relKey]);
|
|
188
|
-
}
|
|
189
|
-
}
|
|
190
185
|
function isBooleanLikeValue(value) {
|
|
191
186
|
return value === true || value === false || value === 0 || value === 1;
|
|
192
187
|
}
|
package/dist/util/sql.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ColumnRef, type
|
|
1
|
+
import { ColumnRef, type IndexRefMap, QuerySql, type QuerySqlFn, type ComputedRefs, type RefMap, type RelationRef, type SqlArg, type SqlStatement, type SqlValueName, type TriggerRowName, type AbstractType } from '../type/index.js';
|
|
2
2
|
/**
|
|
3
3
|
* Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `sql` renders
|
|
4
4
|
* in place: `sql`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
|
|
@@ -34,30 +34,33 @@ export declare const uuidv7: QuerySql;
|
|
|
34
34
|
export declare const SQL_VALUES: Readonly<Record<SqlValueName, QuerySql>>;
|
|
35
35
|
/**
|
|
36
36
|
* The fields of `entity` as {@link ColumnRef}s, each rendering inside `sql` as its column: named the way
|
|
37
|
-
* the dialect names it, so the naming strategy and
|
|
37
|
+
* the dialect names it, so the naming strategy and `.name()` apply, and qualified by the alias
|
|
38
38
|
* in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
|
|
39
39
|
*/
|
|
40
|
-
export declare function refs<E>(entity:
|
|
40
|
+
export declare function refs<E>(entity: AbstractType<E>): RefMap<E>;
|
|
41
41
|
/**
|
|
42
|
-
* The refs a definition's callbacks read:
|
|
42
|
+
* The refs a definition's callbacks read: a check's, a computed field's, a predicate's. A member decorator
|
|
43
43
|
* sees no class, so these name no entity and resolve against the one rendering them.
|
|
44
44
|
*/
|
|
45
45
|
export declare function memberRefs<E>(): ComputedRefs<E>;
|
|
46
|
-
/**
|
|
47
|
-
export declare function
|
|
48
|
-
/**
|
|
49
|
-
|
|
46
|
+
/** Each to-many as a schema's aggregates read it, by key: the same refs {@link memberRefs} gives a decorated entity. */
|
|
47
|
+
export declare function relationRefs(): Readonly<Record<string, RelationRef<object>>>;
|
|
48
|
+
/**
|
|
49
|
+
* The refs an index's callbacks read: each field's column, a JSON one also read into along its paths,
|
|
50
|
+
* `(user) => [user.settings.theme]`. Named for no entity, as {@link memberRefs} are.
|
|
51
|
+
*/
|
|
52
|
+
export declare function indexRefs<E>(): IndexRefMap<E>;
|
|
50
53
|
/**
|
|
51
54
|
* The fields of `entity` as the row a trigger body reads them off, qualified by the side it names:
|
|
52
55
|
* `NEW."col"` against the incoming row, `OLD."col"` against the outgoing one. Bound to the entity, as
|
|
53
56
|
* {@link refs} are, so each names its own column wherever it renders, a write to another table included.
|
|
54
57
|
* Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
|
|
55
58
|
*/
|
|
56
|
-
export declare function rowRefs<E>(entity:
|
|
59
|
+
export declare function rowRefs<E>(entity: AbstractType<E>, qualifier: TriggerRowName): RefMap<E>;
|
|
57
60
|
/**
|
|
58
61
|
* One field as SQL, against its own entity or, read off a definition, the entity rendering it. A
|
|
59
62
|
* `qualifier` names the row it reads from, `NEW` or `OLD`, instead of the alias in scope.
|
|
60
63
|
*/
|
|
61
|
-
export declare function columnRef(entity:
|
|
64
|
+
export declare function columnRef(entity: AbstractType<unknown> | undefined, key: string, qualifier?: string): ColumnRef;
|
|
62
65
|
/** @deprecated Renamed to {@link sql}, the tag editors recognise for SQL highlighting. */
|
|
63
66
|
export declare const raw: typeof sql;
|