uql-orm 0.105.1 → 0.106.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 (36) hide show
  1. package/dist/browser/uql-browser.min.js.map +1 -1
  2. package/dist/entity/columnOptionsBuilder.d.ts +3 -3
  3. package/dist/entity/columnOptionsBuilder.js +3 -5
  4. package/dist/entity/decorator/members.d.ts +1 -1
  5. package/dist/entity/metadata/definition.d.ts +5 -3
  6. package/dist/entity/metadata/definition.js +67 -84
  7. package/dist/entity/metadata/schemaFixture/animal.d.ts +17 -5
  8. package/dist/entity/metadata/schemaFixture/author.d.ts +10 -10
  9. package/dist/entity/metadata/schemaFixture/author.js +3 -3
  10. package/dist/entity/metadata/schemaFixture/book.d.ts +20 -20
  11. package/dist/migrate/builder/types.d.ts +5 -7
  12. package/dist/migrate/cli.js +13 -13
  13. package/dist/migrate/generator/definitionToNode.d.ts +1 -1
  14. package/dist/migrate/generator/definitionToNode.js +4 -8
  15. package/dist/mongodb/mongoIntrospector.d.ts +1 -1
  16. package/dist/mongodb/mongoSchemaGenerator.js +4 -7
  17. package/dist/pglite/pgliteQuerierPool.d.ts +2 -2
  18. package/dist/schema/schemaASTBuilder.js +6 -12
  19. package/dist/sqlite/localSqliteQuerierPool.d.ts +3 -2
  20. package/dist/type/column.d.ts +21 -20
  21. package/dist/type/entity.d.ts +51 -64
  22. package/dist/type/index.d.ts +1 -0
  23. package/dist/type/index.js +1 -0
  24. package/dist/type/query.d.ts +1 -1
  25. package/dist/type/schemaEntity.d.ts +42 -45
  26. package/dist/type/standardSchema.d.ts +28 -0
  27. package/dist/type/standardSchema.js +1 -0
  28. package/dist/type/utility.d.ts +21 -32
  29. package/dist/type/vector.d.ts +4 -4
  30. package/dist/util/ddlExpression.util.d.ts +6 -6
  31. package/dist/util/ddlExpression.util.js +11 -5
  32. package/dist/util/fieldOption.util.js +1 -1
  33. package/dist/util/sql.d.ts +1 -3
  34. package/dist/util/sql.js +0 -4
  35. package/package.json +1 -1
  36. package/skills/uql-orm/SKILL.md +25 -10
@@ -18,8 +18,8 @@ export const Author = defineEntity({
18
18
  },
19
19
  ],
20
20
  })
21
- .relations((rel) => ({ books: () => rel.oneToMany(Book, { mappedBy: (book) => book.author }) }), (rel) => ({
22
- bookCount: () => rel.books.count(),
23
- topStock: () => rel.books.max((book) => book.stock),
21
+ .relations((rel) => ({ books: () => rel.oneToMany(Book, { mappedBy: (book) => book.author }) }), (author) => ({
22
+ bookCount: () => author.books.count(),
23
+ topStock: () => author.books.max((book) => book.stock),
24
24
  }));
25
25
  export const label = (author) => `${author.name} (${author.books?.length ?? 0})`;
@@ -30,9 +30,9 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
30
30
  readonly authorId: import("../../../index.js").NumericColumn<{
31
31
  readonly type: NumberConstructor;
32
32
  }, number>;
33
- }> & {
34
- readonly shout?: string | null | undefined;
35
- } & import("../../../index.js").RelationRow<{
33
+ }, object> & {
34
+ readonly shout: string | null;
35
+ } & {} & import("../../../index.js").RelationRow<{
36
36
  readonly author: () => import("../../../index.js").SchemaRelation<object & {
37
37
  id: number;
38
38
  name: string;
@@ -58,7 +58,7 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
58
58
  } & {
59
59
  readonly defaultValue: unknown;
60
60
  }, Date>;
61
- }> & import("../../../index.js").RelationRow<{
61
+ }, object> & import("../../../index.js").RelationRow<{
62
62
  readonly books: () => import("../../../index.js").SchemaRelation<object & {
63
63
  id: number;
64
64
  title: string;
@@ -91,9 +91,9 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
91
91
  readonly authorId: import("../../../index.js").NumericColumn<{
92
92
  readonly type: NumberConstructor;
93
93
  }, number>;
94
- }> & {
95
- readonly shout?: string | null | undefined;
96
- } & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").AggregateRow<{}>, "1m", {
94
+ }, object> & {
95
+ readonly shout: string | null;
96
+ } & {} & import("../../../index.js").RelationRow</*elided*/ any> & import("../../../index.js").DerivedRow<{}>, "1m", {
97
97
  id: number;
98
98
  title: string;
99
99
  stock: number;
@@ -101,9 +101,9 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
101
101
  version: number;
102
102
  authorId: number;
103
103
  } & {} & {
104
- readonly shout?: string | null | undefined;
105
- }>;
106
- }> & import("../../../index.js").AggregateRow<{
104
+ readonly shout: string | null;
105
+ } & {}>;
106
+ }> & import("../../../index.js").DerivedRow<{
107
107
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
108
108
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
109
109
  }>, "m1", object & {
@@ -131,7 +131,7 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
131
131
  } & {
132
132
  readonly defaultValue: unknown;
133
133
  }, Date>;
134
- }> & import("../../../index.js").RelationRow<{
134
+ }, object> & import("../../../index.js").RelationRow<{
135
135
  readonly books: () => import("../../../index.js").SchemaRelation<object & {
136
136
  id: number;
137
137
  title: string;
@@ -164,9 +164,9 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
164
164
  readonly authorId: import("../../../index.js").NumericColumn<{
165
165
  readonly type: NumberConstructor;
166
166
  }, number>;
167
- }> & {
168
- readonly shout?: string | null | undefined;
169
- } & import("../../../index.js").RelationRow<any> & import("../../../index.js").AggregateRow<{}>, "1m", {
167
+ }, object> & {
168
+ readonly shout: string | null;
169
+ } & {} & import("../../../index.js").RelationRow<any> & import("../../../index.js").DerivedRow<{}>, "1m", {
170
170
  id: number;
171
171
  title: string;
172
172
  stock: number;
@@ -174,13 +174,13 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
174
174
  version: number;
175
175
  authorId: number;
176
176
  } & {} & {
177
- readonly shout?: string | null | undefined;
178
- }>;
179
- }> & import("../../../index.js").AggregateRow<{
177
+ readonly shout: string | null;
178
+ } & {}>;
179
+ }> & import("../../../index.js").DerivedRow<{
180
180
  readonly bookCount: () => import("../../../index.js").RelationAggregate<number>;
181
181
  readonly topStock: () => import("../../../index.js").RelationAggregate<number | null>;
182
182
  }>>;
183
- }> & import("../../../index.js").AggregateRow<{}>, number, {
183
+ }> & import("../../../index.js").DerivedRow<{}>, number, {
184
184
  id: number;
185
185
  title: string;
186
186
  stock: number;
@@ -188,5 +188,5 @@ export declare const Book: import("../../../index.js").SchemaClass<object & {
188
188
  version: number;
189
189
  authorId: number;
190
190
  } & {} & {
191
- readonly shout?: string | null | undefined;
192
- }, false>;
191
+ readonly shout: string | null;
192
+ } & {}, false>;
@@ -1,5 +1,5 @@
1
1
  import type { ColumnNode, EnumValues, ForeignKeyAction } from '../../schema/types.js';
2
- import type { IndexEntry, Except, FieldOptions, IndexColumnInput, IndexOptions, IndexSchema, QuerySql } from '../../type/index.js';
2
+ import type { IndexEntry, Except, FieldOptions, IndexColumnInput, IndexOptions } from '../../type/index.js';
3
3
  import type { ForeignKeySchema } from '../../type/migration.js';
4
4
  export type ColumnDefinition = Except<ColumnNode, 'table'>;
5
5
  /**
@@ -20,14 +20,12 @@ export interface FullColumnDefinition extends ColumnDefinition {
20
20
  index?: string | boolean;
21
21
  }
22
22
  /**
23
- * An index as the builder records it, with the entries and options an entity's `indexes` entry takes: its SQL kept as `raw`
24
- * until a generator renders it for the engine the migration runs on.
23
+ * An index as the builder records it: its options as declared, its SQL kept as `raw` until a generator renders it for
24
+ * the engine the migration runs on, and an unnamed one named then, from its predicate as written.
25
25
  */
26
- export type IndexDefinition = Except<IndexSchema, 'name' | 'entries' | 'where'> & {
27
- /** As declared; an unnamed index is named when it is rendered, from its predicate as written. */
28
- readonly name?: string;
26
+ export type IndexDefinition = IndexOptions & {
29
27
  readonly entries: readonly IndexEntry[];
30
- readonly where?: QuerySql;
28
+ readonly unique: boolean;
31
29
  /** Whether an unnamed index takes the `_uk` kind. Only `table.unique` sets it: earlier migrations installed `_uk` there, so `index` keeps `_idx`. */
32
30
  readonly uniqueName?: boolean;
33
31
  };
@@ -230,9 +230,9 @@ function printDriftGroup(title, drifts, icon, showSuggestion) {
230
230
  }
231
231
  function printHelp() {
232
232
  console.log(`
233
- uql-orm/migrate - Database migration tool for uql ORM
233
+ uql-migrate - Database migration tool for uql ORM
234
234
 
235
- Usage: uql-orm/migrate <command> [options]
235
+ Usage: uql-migrate <command> [options]
236
236
 
237
237
  Commands:
238
238
  up Run all pending migrations
@@ -282,16 +282,16 @@ Configuration:
282
282
  };
283
283
 
284
284
  Examples:
285
- uql-orm/migrate up
286
- uql-orm/migrate up --step 1
287
- uql-orm/migrate down
288
- uql-orm/migrate down --step 3
289
- uql-orm/migrate status
290
- uql-orm/migrate generate add_users_table
291
- uql-orm/migrate generate:entities initial_schema
292
- uql-orm/migrate generate:from-db --output ./src/entities
293
- uql-orm/migrate sync --dry-run
294
- uql-orm/migrate sync --pull
295
- uql-orm/migrate drift:check
285
+ uql-migrate up
286
+ uql-migrate up --step 1
287
+ uql-migrate down
288
+ uql-migrate down --step 3
289
+ uql-migrate status
290
+ uql-migrate generate add_users_table
291
+ uql-migrate generate:entities initial_schema
292
+ uql-migrate generate:from-db --output ./src/entities
293
+ uql-migrate sync --dry-run
294
+ uql-migrate sync --pull
295
+ uql-migrate drift:check
296
296
  `);
297
297
  }
@@ -34,6 +34,6 @@ export declare function indexDefinition(columns: readonly IndexColumnInput[], {
34
34
  * An index the builder recorded, its SQL rendered by `render` into the text the schema holds, and named
35
35
  * from that text the way an entity's is.
36
36
  */
37
- export declare function renderIndexDefinition(table: string, { uniqueName, ...index }: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
37
+ export declare function renderIndexDefinition(table: string, { uniqueName, where, ...index }: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
38
38
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
39
39
  export declare function columnForeignKey(col: FullColumnDefinition): ForeignKeySchema | undefined;
@@ -1,6 +1,6 @@
1
1
  import { createTableNode, keyOfColumns } from '../../schema/schemaAST.js';
2
- import { namedIndex, enumCheck } from '../../util/ddlExpression.util.js';
3
- import { normalizeIndexColumn, renderIndexColumn } from '../../util/indexEntry.util.js';
2
+ import { enumCheck, renderIndex } from '../../util/ddlExpression.util.js';
3
+ import { normalizeIndexColumn } from '../../util/indexEntry.util.js';
4
4
  import { derivedIndexName, splitQualifiedName } from '../../util/sql.util.js';
5
5
  /**
6
6
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
@@ -61,12 +61,8 @@ export function indexDefinition(columns, { name, unique = false, ...options } =
61
61
  * An index the builder recorded, its SQL rendered by `render` into the text the schema holds, and named
62
62
  * from that text the way an entity's is.
63
63
  */
64
- export function renderIndexDefinition(table, { uniqueName, ...index }, render) {
65
- return {
66
- ...index,
67
- ...namedIndex(index.name, table, index.entries, () => index.where && render(index.where), uniqueName),
68
- entries: index.entries.map((entry) => renderIndexColumn(entry, render)),
69
- };
64
+ export function renderIndexDefinition(table, { uniqueName, where, ...index }, render) {
65
+ return renderIndex(table, index, render, () => where && render(where), uniqueName);
70
66
  }
71
67
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
72
68
  export function columnForeignKey(col) {
@@ -15,4 +15,4 @@ export declare class MongoSchemaIntrospector implements SchemaIntrospector {
15
15
  private withDb;
16
16
  }
17
17
  /** A key as the entity declares it: the field, then the path inside it, so the two compare and name alike. */
18
- export declare function documentEntry(key: string): IndexEntry<string>;
18
+ export declare function documentEntry(key: string): IndexEntry<never>;
@@ -8,7 +8,7 @@ import { sides } from '../migrate/schemaChange.js';
8
8
  import { indexChanges } from '../schema/indexDifferences.js';
9
9
  import { QuerySql, } from '../type/index.js';
10
10
  import { indexDistance, unsupportedVectorMetric } from '../type/vector.js';
11
- import { declaredIndexes, namedIndex } from '../util/ddlExpression.util.js';
11
+ import { declaredIndexes, renderIndex } from '../util/ddlExpression.util.js';
12
12
  import { findVectorIndex, fulltextConfig, fulltextWeights, indexedDistance } from '../util/dialect.util.js';
13
13
  import { entryKeys, entryModifiers, renamedEntry } from '../util/indexEntry.util.js';
14
14
  import { definedEntries, hasKeys } from '../util/object.util.js';
@@ -67,13 +67,10 @@ export class MongoSchemaGenerator extends MongoDialect {
67
67
  const [first] = declared;
68
68
  const vectorKey = options.type === 'vectorSearch' && typeof first?.column === 'string' ? first.column : undefined;
69
69
  const vector = vectorKey === undefined ? undefined : meta.fields[vectorKey];
70
- const named = namedIndex(options.name, collectionName, entries, (label) => where && this.indexFilter(where, meta.entity, label));
70
+ const index = renderIndex(collectionName, { ...options, entries }, refuseSql, (label) => where && this.indexFilter(where, meta.entity, label));
71
71
  return {
72
- ...options,
73
- ...named,
74
- name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : named.name,
75
- entries,
76
- unique: options.unique ?? false,
72
+ ...index,
73
+ name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : index.name,
77
74
  distance: vectorKey === undefined
78
75
  ? options.distance
79
76
  : indexedDistance(meta, vectorKey, findVectorIndex(meta, vectorKey)),
@@ -1,10 +1,10 @@
1
1
  import type { PGliteOptions } from '@electric-sql/pglite';
2
2
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
3
- import type { ExtraOptions } from '../type/index.js';
3
+ import type { Except, ExtraOptions } from '../type/index.js';
4
4
  import { PgliteDialect } from './pgliteDialect.js';
5
5
  import { type PgliteDatabase, PgliteQuerier } from './pgliteQuerier.js';
6
6
  /** PGlite's own options but `dataDir`, the pool's first argument; `extensions: { vector }` enables pgvector. Type-only. */
7
- export type PglitePoolOptions = Omit<PGliteOptions, 'dataDir'>;
7
+ export type PglitePoolOptions = Except<PGliteOptions, 'dataDir'>;
8
8
  /**
9
9
  * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
10
10
  * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
@@ -1,8 +1,8 @@
1
1
  import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
2
- import { declaredIndexes, namedIndex, enumCheck, ownedCheck } from '../util/ddlExpression.util.js';
2
+ import { declaredIndexes, enumCheck, ownedCheck, renderIndex } from '../util/ddlExpression.util.js';
3
3
  import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
4
4
  import { isInlinedExpression, isSoleIdField } from '../util/field.util.js';
5
- import { entryColumn, entryColumns, renamedEntry, renderIndexColumn } from '../util/indexEntry.util.js';
5
+ import { entryColumn, entryColumns, renamedEntry } from '../util/indexEntry.util.js';
6
6
  import { definedEntries, entityName } from '../util/object.util.js';
7
7
  import { derivedForeignKeyName, derivedIndexName } from '../util/sql.util.js';
8
8
  import { UqlUsageError } from '../util/uqlError.js';
@@ -176,16 +176,10 @@ function addCompositeIndex(ctx, table, meta, { entries, include, where, ...optio
176
176
  });
177
177
  if (!resolved.length)
178
178
  return;
179
- const named = namedIndex(options.name, table.name, resolved, (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
180
- ctx.ast.addIndex({
181
- ...options,
182
- ...named,
183
- table,
184
- entries: resolved.map((entry) => renderIndexColumn(entry, (sql) => ctx.compileDdl(sql, meta.entity))),
185
- // An `include` column is named like any other, so a custom naming has to reach it too.
186
- include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column),
187
- unique: options.unique ?? false,
188
- });
179
+ const index = renderIndex(table.name,
180
+ // An `include` column is named like any other, so a custom naming has to reach it too.
181
+ { ...options, entries: resolved, include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column) }, (sql) => ctx.compileDdl(sql, meta.entity), (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
182
+ ctx.ast.addIndex({ ...index, table });
189
183
  if (ctx.textScoreIndexes) {
190
184
  addTextScoreIndexes(ctx, table, options.type, resolved);
191
185
  }
@@ -1,4 +1,5 @@
1
1
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
2
+ import type { Except, Merge } from '../type/index.js';
2
3
  import type { SqliteDialect } from './sqliteDialect.js';
3
4
  import { type SqliteDatabase, type SqlitePreparedStatement, SqliteQuerier } from './sqliteQuerier.js';
4
5
  /** What every local SQLite pool accepts on top of its driver's own options. */
@@ -27,9 +28,9 @@ export type LocalSqliteDatabase = {
27
28
  * A `node:sqlite` or `bun:sqlite` handle as a {@link LocalSqliteDatabase}. Neither says whether a statement
28
29
  * reads, so `reads` does: taken by `run()`, a RETURNING statement's rows would be lost, and its ids with them.
29
30
  */
30
- export declare function adaptSqlite<S extends Omit<SqlitePreparedStatement, 'reader'>>(db: Omit<LocalSqliteDatabase, 'prepare'> & {
31
+ export declare function adaptSqlite<S extends Except<SqlitePreparedStatement, 'reader'>>(db: Merge<LocalSqliteDatabase, {
31
32
  prepare(sql: string): S;
32
- }, reads: (stmt: S) => boolean): LocalSqliteDatabase;
33
+ }>, reads: (stmt: S) => boolean): LocalSqliteDatabase;
33
34
  /**
34
35
  * `db` extended past SQLite's own: each loadable extension installed, which `node:sqlite` refuses unless
35
36
  * opened to allow them, and `REGEXP` defined as libSQL builds it in, which SQLite leaves to the application.
@@ -1,8 +1,9 @@
1
1
  import type { ForeignKeyAction } from '../schema/types.js';
2
2
  import type { TYPE_BOUNDS, VALUE_DECIDERS } from '../util/fieldOption.util.js';
3
- import type { BlobColumnType, BooleanColumnType, ColumnType, DateColumnType, DdlDefault, JsonColumnType, NumericColumnType, StringColumnType, VectorColumnType, FieldOptions, HasCompositeKey, IdValue, JsonShape, OnFieldCallback, ShapeValue, StampEvent } from './entity.js';
3
+ import type { BlobColumnType, BooleanColumnType, ColumnType, DateColumnType, DdlDefault, JsonColumnType, NumericColumnType, StringColumnType, VectorColumnType, FieldOptions, HasCompositeKey, IdValue, JoinKind, OnFieldCallback, StampEvent } from './entity.js';
4
4
  import type { QuerySql } from './querySql.js';
5
5
  import type { ReferencedKey } from './schemaEntity.js';
6
+ import type { StandardSchemaV1 } from './standardSchema.js';
6
7
  import type { Type, Json, AbstractType } from './utility.js';
7
8
  import type { VectorDistance } from './vector.js';
8
9
  /** Where a column builder holds its options, so every string key of a builder is a method. */
@@ -199,16 +200,28 @@ export interface VersionColumn<in out O, in out V> extends Column<O, V> {
199
200
  readonly comment: string;
200
201
  }, V>;
201
202
  }
202
- /** A key's kind as a join compares it: a number and a bigint both integers, so a BIGINT column holds either key. */
203
- type ValueKind<T> = T extends number | bigint ? number | bigint : T;
204
203
  /** Refuses a target whose key is another kind of value than the column holds, which no join matches. */
205
- type HoldsKey<C, V> = [ValueKind<NonNullable<ReferencedKey<C>>>] extends [ValueKind<V>] ? unknown : {
204
+ type HoldsKey<C, V> = [JoinKind<NonNullable<ReferencedKey<C>>>] extends [JoinKind<V>] ? unknown : {
206
205
  readonly __columnMustHoldReferencedKey: ReferencedKey<C>;
207
206
  };
208
207
  /** The column types holding an exact decimal, read as its text: a JS number would round it. */
209
208
  type DecimalType = 'decimal' | 'numeric';
210
- /** What a JSON column holds: its shape's payload, or any document. */
211
- type JsonValue<S> = [S] extends [never] ? Json : ShapeValue<S> extends infer P extends object | string | number | boolean ? Json<P> : Json;
209
+ /** A JSON column of `T`, typed by the payload its schema validates to, or any document with none. */
210
+ type JsonColumn<T extends 'json' | 'jsonb'> = {
211
+ (): ColumnBuilder<{
212
+ readonly type: T;
213
+ }, Json, 'json'>;
214
+ <S extends StandardSchemaV1>(schema: S): ColumnBuilder<{
215
+ readonly type: T;
216
+ readonly schema: S;
217
+ }, JsonOutput<PayloadOf<S['~standard']['types']>>, 'json'>;
218
+ };
219
+ /** A schema's output as a JSON column holds it: a document, or the primitive a payload may be. */
220
+ type JsonOutput<O> = O extends object | string | number | boolean | null ? Json<O> : Json;
221
+ /** The output a schema's `types` states, `unknown` where it states none: `never` would type the column as nothing. */
222
+ type PayloadOf<T> = NonNullable<T> extends infer N ? [N] extends [never] ? unknown : N extends {
223
+ readonly output: infer O;
224
+ } ? O : unknown : never;
212
225
  /** The key a column referencing `C` holds, or a named complaint for a composite one, which no one column holds. */
213
226
  type ReferenceValue<C> = C extends AbstractType<infer E> ? HasCompositeKey<E> extends true ? {
214
227
  readonly __compositeKeyNeedsAColumnPerKey: true;
@@ -249,20 +262,8 @@ export type ColumnFactory = {
249
262
  date(): DateColumn<{
250
263
  readonly type: DateConstructor;
251
264
  }, Date>;
252
- json(): ColumnBuilder<{
253
- readonly type: 'json';
254
- }, Json, 'json'>;
255
- json<const S extends JsonShape>(shape: S): ColumnBuilder<{
256
- readonly type: 'json';
257
- readonly shape: S;
258
- }, JsonValue<S>, 'json'>;
259
- jsonb(): ColumnBuilder<{
260
- readonly type: 'jsonb';
261
- }, Json, 'json'>;
262
- jsonb<const S extends JsonShape>(shape: S): ColumnBuilder<{
263
- readonly type: 'jsonb';
264
- readonly shape: S;
265
- }, JsonValue<S>, 'json'>;
265
+ json: JsonColumn<'json'>;
266
+ jsonb: JsonColumn<'jsonb'>;
266
267
  vector(dimensions: number): VectorColumn<{
267
268
  readonly type: 'vector';
268
269
  readonly dimensions: number;
@@ -4,7 +4,8 @@ import type { Querier } from './querier.js';
4
4
  import type { FilterOptions, RelationQuery } from './query.js';
5
5
  import type { ColumnRef, JsonPathRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
6
6
  import type { QueryWhere } from './queryWhere.js';
7
- import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
7
+ import type { StandardSchemaV1 } from './standardSchema.js';
8
+ import type { AtLeastOne, ExactlyOne, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
8
9
  import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
9
10
  /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
10
11
  export declare const idKey: unique symbol;
@@ -16,11 +17,9 @@ export declare const idKey: unique symbol;
16
17
  export declare const versionKey: unique symbol;
17
18
  /** Brands the fields an insert may leave out, which a default fills, `[filledKey]?: 'units' | 'createdAt'`; each stays present on every read. */
18
19
  export declare const filledKey: unique symbol;
19
- type EntityBrand = typeof idKey | typeof versionKey | typeof filledKey;
20
+ export type EntityBrand = typeof idKey | typeof versionKey | typeof filledKey;
20
21
  /** The names an entity's brand `B` lists, `never` where it declares none. */
21
- type BrandNames<E, B extends EntityBrand> = E extends {
22
- readonly [K in B]?: infer N;
23
- } ? N : never;
22
+ export type BrandNames<E, B extends EntityBrand> = B extends keyof E ? NonNullable<E[B]> : never;
24
23
  /**
25
24
  * A brand naming a key that is no field, which each reader would drop silently: refused where an entity
26
25
  * registers, `@Entity()`, by a member the class lacks that names the typo. A class with no
@@ -258,24 +257,6 @@ type TimeColumnType = 'time';
258
257
  /** A numeric column holding an exact decimal, read as its text: a JS number would round it. */
259
258
  type DecimalColumnType = 'decimal' | 'numeric';
260
259
  export type JsonColumnType = ColumnTypeOf<'json'>;
261
- /**
262
- * A JSON column's payload described as data, in a field's vocabulary: a value's type (`String`), an object of
263
- * shapes, a key ending in `?` for an optional member, and `[shape]` for an array of it.
264
- * @example `{ theme: String, 'nickname?': String, tags: [String], billing: { plan: String } }`
265
- */
266
- export type JsonShape = JsonLeaf | readonly [JsonShape] | {
267
- readonly [key: string]: JsonShape;
268
- };
269
- /** The values a JSON document holds at a leaf. */
270
- type JsonLeaf = StringConstructor | NumberConstructor | BooleanConstructor;
271
- /** The payload a {@link JsonShape} describes. */
272
- export type ShapeValue<S> = S extends readonly [infer E] ? ShapeValue<E>[] : S extends JsonLeaf ? TsTypeOf<S> : [Extract<keyof S, `${string}?`>] extends [never] ? {
273
- -readonly [K in keyof S]: ShapeValue<S[K]>;
274
- } : {
275
- -readonly [K in keyof S as K extends `${string}?` ? never : K]: ShapeValue<S[K]>;
276
- } & {
277
- -readonly [K in keyof S as K extends `${infer N}?` ? N : never]?: ShapeValue<S[K]>;
278
- };
279
260
  export type BlobColumnType = ColumnTypeOf<'blob'>;
280
261
  export type BooleanColumnType = ColumnTypeOf<'boolean'>;
281
262
  export type VectorColumnType = ColumnTypeOf<'vector'>;
@@ -309,8 +290,8 @@ export type FieldOptions<V = unknown> = {
309
290
  readonly onDelete?: ForeignKeyAction;
310
291
  /** The values the column accepts, `f.enum(['draft', 'paid'])`: a `CHECK (col IN (...))` on every SQL engine. */
311
292
  readonly enum?: EnumValues;
312
- /** A JSON column's payload, which a schema entity's row reads it as: `shape: { theme: String, tags: [String] }`. */
313
- readonly shape?: JsonShape;
293
+ /** A JSON column's payload as a Standard Schema, `f.json(schema)`, typed by its output and never read at run time. */
294
+ readonly schema?: StandardSchemaV1;
314
295
  /**
315
296
  * An expression the database computes, never written: spliced into each read, or with `stored` a generated
316
297
  * column, `.as(sql`${user.first} || ' ' || ${user.last}`)`. A relation aggregate, `user.resources.count()`,
@@ -414,11 +395,11 @@ type RelationActions = {
414
395
  readonly onUpdate?: ForeignKeyAction;
415
396
  };
416
397
  /** The one column of `O` that can be a foreign key to `E`: a field holding `E`'s key, which has to be a single one. */
417
- type ForeignKey<O, E> = HasCompositeKey<E> extends true ? never : FieldKeyHolding<O, IdValue<E>>;
398
+ type ForeignKey<O, E> = HasCompositeKey<E> extends true ? never : KeyHolding<O, IdValue<E>>;
418
399
  /** One pair of join columns, each a field read off its entity's key map, the local one holding the foreign's value. */
419
400
  export type RelationReference<O, E> = {
420
401
  readonly [F in keyof E]-?: {
421
- readonly local: FieldKeyHolding<O, E[F]>;
402
+ readonly local: KeyHolding<O, E[F]>;
422
403
  readonly foreign: F;
423
404
  };
424
405
  }[FieldKey<E>];
@@ -426,22 +407,24 @@ export type RelationReference<O, E> = {
426
407
  export type FieldKeyOf<E, T> = {
427
408
  readonly [K in FieldKey<E>]-?: [NonNullable<E[K]>] extends [T] ? K : never;
428
409
  }[FieldKey<E>];
429
- /** The fields of `O` that can hold any value `V` takes. */
430
- type FieldKeyHolding<O, V> = {
431
- readonly [K in keyof O]-?: [NonNullable<V>] extends [NonNullable<O[K]>] ? K : never;
410
+ /** A value's kind as a join compares it: a number and a bigint are one kind, which BIGINT widens. */
411
+ export type JoinKind<T> = T extends number | bigint ? number : T;
412
+ /** The fields of `O` that can hold a key of `V`'s kind, compared as a join compares it at run time. */
413
+ export type KeyHolding<O, V> = [V] extends [never] ? never : {
414
+ readonly [K in keyof O]-?: [JoinKind<NonNullable<V>>] extends [JoinKind<NonNullable<O[K]>>] ? K : never;
432
415
  }[FieldKey<O>];
433
416
  /** A relation once `getMeta` resolved it: `references` settled into pairs and `mappedBy` a name. */
434
- export type RelationMeta = Omit<RelationRegistration, 'references'> & {
417
+ export type RelationMeta = Merge<RelationRegistration, {
435
418
  references: RelationReferences;
436
- };
419
+ }>;
437
420
  /**
438
421
  * A relation as the registry takes it: `mappedBy` and `references` read down to names, `references` a
439
422
  * single column until `getMeta` pairs it with the target's key.
440
423
  */
441
- export type RelationRegistration = Omit<RelationOptions<object>, 'mappedBy' | 'references'> & {
424
+ export type RelationRegistration = Merge<RelationOptions<object>, {
442
425
  mappedBy?: string;
443
426
  references?: RelationReferences | string;
444
- };
427
+ }>;
445
428
  /**
446
429
  * What a relation's join callbacks answer, `E` its target and `O` the entity declaring it: one foreign key, pairs of
447
430
  * columns, or the target's member mapping it. Each form states its own: a decorated class checks each member's
@@ -594,21 +577,21 @@ export type HookFunction = {
594
577
  * cosine; a `fulltext` one may name the text-search `config` it parses with; and any other index neither.
595
578
  */
596
579
  export type IndexTypeOptions = {
597
- type: VectorIndexType;
598
- distance: VectorDistance;
599
- config?: never;
580
+ readonly type: VectorIndexType;
581
+ readonly distance: VectorDistance;
582
+ readonly config?: never;
600
583
  } | {
601
- type: 'vectorSearch';
602
- distance?: VectorDistance;
603
- config?: never;
584
+ readonly type: 'vectorSearch';
585
+ readonly distance?: VectorDistance;
586
+ readonly config?: never;
604
587
  } | {
605
- type: 'fulltext';
606
- distance?: never;
607
- config?: string;
588
+ readonly type: 'fulltext';
589
+ readonly distance?: never;
590
+ readonly config?: string;
608
591
  } | {
609
- type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
610
- distance?: never;
611
- config?: never;
592
+ readonly type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
593
+ readonly distance?: never;
594
+ readonly config?: never;
612
595
  };
613
596
  /** What an index entry carries besides what it indexes, at every layer. */
614
597
  export type IndexEntryModifiers = {
@@ -726,19 +709,25 @@ type IndexEntryTarget = (ColumnLengths & {
726
709
  * @example `{ columns: (user) => [user.settings.theme, { column: user.settings.rating, type: Number }] }`
727
710
  */
728
711
  export type EntityIndexColumnInput = QuerySql | JsonPathRef<string> | JsonPathRef<UntypedJson> | (IndexEntryModifiers & IndexEntryTarget);
712
+ /**
713
+ * What an index states the same at every layer. Each layer adds its own `include` and `where` beside it, so nothing
714
+ * maps over `IndexTypeOptions`' arms: `type` and `distance` stay a discriminated pair at no instantiation cost.
715
+ */
716
+ export type IndexKnobs = {
717
+ /** Custom index name */
718
+ readonly name?: string;
719
+ /** Whether index is unique; omit or `false` for a non-unique index (default). */
720
+ readonly unique?: boolean;
721
+ } & VectorIndexOptions & IndexTypeOptions;
729
722
  /** An index as metadata keeps it. */
730
723
  export type EntityIndexMeta<E = object> = {
731
724
  /** The indexed entries, in order. */
732
- entries: readonly IndexEntry[];
733
- /** Custom index name */
734
- name?: string;
735
- /** Whether index is unique; omit or `false` for a non-unique index (default). */
736
- unique?: boolean;
737
- /** Partial index predicate, compiled when the schema is built. */
738
- where?: EntityWhereMeta<E>;
725
+ readonly entries: readonly IndexEntry[];
739
726
  /** Columns stored in the index beyond its key, so a query reading only these needs no row. Postgres-wire only. */
740
- include?: readonly string[];
741
- } & VectorIndexOptions & IndexTypeOptions;
727
+ readonly include?: readonly string[];
728
+ /** Partial index predicate, compiled when the schema is built. */
729
+ readonly where?: EntityWhereMeta<E>;
730
+ } & IndexKnobs;
742
731
  export type EntityMeta<E> = {
743
732
  readonly entity: AbstractType<E>;
744
733
  /** The table, which is the class's own name where the entity named none - see {@link derivedName}. */
@@ -870,11 +859,11 @@ export type TriggerOptions<E = unknown> = {
870
859
  * A trigger as entity metadata keeps it: the column callback resolved to keys, and a body widened to
871
860
  * take both rows, which the renderer passes whatever the event, each body reading only its own.
872
861
  */
873
- export type EntityTriggerMeta<E = object> = Except<TriggerOptions<E>, 'of' | 'where' | 'run'> & {
862
+ export type EntityTriggerMeta<E = object> = Merge<TriggerOptions<E>, {
874
863
  readonly of?: readonly string[];
875
864
  readonly where?: TriggerPredicate<E, TriggerUpdateEvent> | TriggerMetaBody<E>;
876
865
  readonly run: TriggerMetaBody<E> | Readonly<Partial<Record<SqlDialectName, TriggerMetaBody<E>>>>;
877
- };
866
+ }>;
878
867
  /**
879
868
  * A body as the renderer calls it, with both rows whatever the event. Bivariant,
880
869
  * so a body typing the row its event lacks as `never` is still held here.
@@ -929,17 +918,15 @@ export type EntityOptions<E = unknown> = {
929
918
  /** Triggers the database runs, in the order written. See {@link TriggerOptions}. */
930
919
  readonly triggers?: TriggerSection<E>;
931
920
  };
932
- /**
933
- * Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it,
934
- * and through {@link EntityIndexOptions} an entity's `indexes`. `Except` (not plain `Omit`) keeps
935
- * `type`/`distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
936
- */
937
- export type IndexOptions = Except<EntityIndexMeta, 'entries' | 'where'> & {
921
+ /** Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it. */
922
+ export type IndexOptions = IndexKnobs & {
923
+ /** Columns stored in the index beyond its key, so a query reading only these needs no row. Postgres-wire only. */
924
+ readonly include?: readonly string[];
938
925
  /** Partial-index predicate, as `sql` with no interpolation: the migration builder has no entity to compile one against. */
939
926
  readonly where?: QuerySql;
940
927
  };
941
928
  /** {@link IndexOptions} on an entity, `include` and `where` read off the section's refs as its columns are. */
942
- export type EntityIndexOptions<E> = Except<IndexOptions, 'include' | 'where'> & {
929
+ export type EntityIndexOptions<E> = IndexKnobs & {
943
930
  readonly include?: readonly ColumnRef<FieldKey<E>>[];
944
931
  /**
945
932
  * Partial-index predicate, written as the predicate the query passes: a planner matches the two by
@@ -14,6 +14,7 @@ export * from './querySql.js';
14
14
  export * from './schemaEntity.js';
15
15
  export * from './queryWhere.js';
16
16
  export * from './universalQuerier.js';
17
+ export * from './standardSchema.js';
17
18
  export * from './utility.js';
18
19
  export * from './vector.js';
19
20
  export * from './wire.js';
@@ -14,6 +14,7 @@ export * from './querySql.js';
14
14
  export * from './schemaEntity.js';
15
15
  export * from './queryWhere.js';
16
16
  export * from './universalQuerier.js';
17
+ export * from './standardSchema.js';
17
18
  export * from './utility.js';
18
19
  export * from './vector.js';
19
20
  export * from './wire.js';
@@ -450,7 +450,7 @@ type MaybeFields<E, M> = [MaybeKeys<M>] extends [never] ? unknown : Partial<Pick
450
450
  /** The entity, less the relations {@link RelatedRows} fills in, so none comes back as declared. */
451
451
  type WholeRow<E, Q> = Q extends {
452
452
  readonly $populate: infer M;
453
- } ? Omit<E, keyof M & keyof E> & MethodMask<E> : DataRow<E>;
453
+ } ? Except<E, keyof M & keyof E> & MethodMask<E> : DataRow<E>;
454
454
  /** The populated relations, and the `_count` a query asked for. */
455
455
  type RelatedRows<E, Q> = Q extends {
456
456
  readonly $populate: infer M;