uql-orm 0.109.2 → 0.111.0

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 (56) hide show
  1. package/README.md +3 -3
  2. package/dist/bunSql/bunSqlQuerier.d.ts +2 -5
  3. package/dist/d1/d1Querier.d.ts +1 -2
  4. package/dist/d1/d1Querier.js +0 -2
  5. package/dist/dialect/abstractSqlDialect.js +2 -2
  6. package/dist/dialect/aliases.d.ts +2 -0
  7. package/dist/dialect/aliases.js +2 -0
  8. package/dist/entity/columnOptionsBuilder.d.ts +1 -2
  9. package/dist/entity/columnOptionsBuilder.js +2 -5
  10. package/dist/entity/decorator/members.d.ts +37 -11
  11. package/dist/entity/decorator/members.js +0 -5
  12. package/dist/entity/metadata/definedFixture/animal.d.ts +4 -0
  13. package/dist/entity/metadata/definedFixture/animal.js +1 -1
  14. package/dist/entity/metadata/definedFixture/author.d.ts +4 -0
  15. package/dist/entity/metadata/definedFixture/author.js +1 -1
  16. package/dist/entity/metadata/definedFixture/book.d.ts +5 -0
  17. package/dist/entity/metadata/definedFixture/book.js +1 -1
  18. package/dist/entity/metadata/definition.d.ts +0 -2
  19. package/dist/entity/metadata/definition.js +4 -9
  20. package/dist/mariadb/mariadbQuerier.d.ts +2 -4
  21. package/dist/migrate/builder/columnBuilder.js +2 -2
  22. package/dist/migrate/codegen/entityCodeGenerator.js +1 -1
  23. package/dist/migrate/codegen/fieldOptionsSource.js +2 -13
  24. package/dist/migrate/schemaGenerator.d.ts +2 -2
  25. package/dist/migrate/schemaGenerator.js +9 -5
  26. package/dist/mongodb/mongodbQuerier.d.ts +1 -2
  27. package/dist/mongodb/mongodbQuerier.js +0 -2
  28. package/dist/mssql/mssqlQuerier.d.ts +2 -4
  29. package/dist/mysql/mysql2Querier.d.ts +2 -10
  30. package/dist/pglite/pgliteQuerier.d.ts +4 -7
  31. package/dist/pglite/pgliteQuerier.js +0 -2
  32. package/dist/postgres/pgQuerier.d.ts +2 -1
  33. package/dist/querier/abstractPoolQuerier.d.ts +1 -2
  34. package/dist/querier/abstractPoolQuerier.js +0 -2
  35. package/dist/querier/abstractSqlQuerier.d.ts +8 -2
  36. package/dist/querier/abstractSqlQuerier.js +29 -4
  37. package/dist/schema/canonicalType.d.ts +3 -3
  38. package/dist/schema/canonicalType.js +9 -4
  39. package/dist/schema/declaredColumn.d.ts +2 -4
  40. package/dist/schema/declaredColumn.js +4 -5
  41. package/dist/schema/schemaASTBuilder.js +1 -2
  42. package/dist/sqlite/hranaQuerier.d.ts +1 -2
  43. package/dist/sqlite/hranaQuerier.js +0 -2
  44. package/dist/sqlite/sqliteQuerier.d.ts +3 -9
  45. package/dist/sqlite/sqliteQuerier.js +0 -2
  46. package/dist/turso/tursoSessionQuerier.d.ts +1 -2
  47. package/dist/turso/tursoSessionQuerier.js +0 -2
  48. package/dist/type/column.d.ts +41 -73
  49. package/dist/type/definedEntity.d.ts +1 -1
  50. package/dist/type/entity.d.ts +19 -14
  51. package/dist/type/querierPool.d.ts +1 -1
  52. package/dist/type/utility.d.ts +4 -2
  53. package/dist/util/field.util.d.ts +1 -7
  54. package/dist/util/field.util.js +2 -12
  55. package/package.json +5 -5
  56. package/skills/uql-orm/SKILL.md +7 -7
@@ -1,5 +1,6 @@
1
1
  import { AbstractSqlQuerier } from '../querier/index.js';
2
- import type { ExtraOptions, RawRow } from '../type/index.js';
2
+ import type { ExtraOptions } from '../type/index.js';
3
+ import type { SqlExecution } from '../util/sql.util.js';
3
4
  import type { PgliteDialect } from './pgliteDialect.js';
4
5
  /** The two methods uql uses of `@electric-sql/pglite`, stated so its published types do not depend on a pre-1.0 package. */
5
6
  export type PgliteDatabase = {
@@ -17,16 +18,12 @@ export type PgliteDatabase = {
17
18
  */
18
19
  export declare class PgliteQuerier extends AbstractSqlQuerier {
19
20
  readonly db: PgliteDatabase;
20
- readonly extra?: ExtraOptions | undefined;
21
- constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions | undefined);
21
+ constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions);
22
22
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
23
23
  protected get connection(): object;
24
24
  /**
25
25
  * `affectedRows`, not `rowCount`: PGlite derives the former from the command tag of a write only, where the
26
26
  * latter also counts a `SELECT`'s rows and is absent altogether from a DDL tag.
27
27
  */
28
- protected execute(sql: string, values?: unknown[]): Promise<{
29
- rows: RawRow[];
30
- changes: number | undefined;
31
- }>;
28
+ protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
32
29
  }
@@ -7,11 +7,9 @@ import { AbstractSqlQuerier } from '../querier/index.js';
7
7
  */
8
8
  export class PgliteQuerier extends AbstractSqlQuerier {
9
9
  db;
10
- extra;
11
10
  constructor(db, dialect, extra) {
12
11
  super(dialect, extra);
13
12
  this.db = db;
14
- this.extra = extra;
15
13
  }
16
14
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
17
15
  get connection() {
@@ -1,5 +1,6 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
2
  import type { RawRow } from '../type/index.js';
3
+ import type { SqlExecution } from '../util/sql.util.js';
3
4
  import { type PgResult } from './pgExecution.js';
4
5
  export interface PgAnyClient {
5
6
  query(text: string, values?: unknown[]): Promise<PgResult>;
@@ -19,7 +20,7 @@ export declare class PgQuerier extends AbstractPoolQuerier<PgAnyClient> {
19
20
  * the process: the querier hears it while it holds the client, and what it hands the client back to after it.
20
21
  */
21
22
  protected acquired(conn: PgAnyClient): PgAnyClient;
22
- protected execute(sql: string, values?: unknown[]): Promise<import("../util/sql.util.js").SqlExecution>;
23
+ protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
23
24
  internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
24
25
  protected releaseConn(conn: PgAnyClient, discard: boolean): Promise<void>;
25
26
  }
@@ -3,10 +3,9 @@ import type { ExtraOptions } from '../type/index.js';
3
3
  import { AbstractSqlQuerier } from './abstractSqlQuerier.js';
4
4
  export declare abstract class AbstractPoolQuerier<C> extends AbstractSqlQuerier {
5
5
  protected readonly connect: () => Promise<C>;
6
- readonly extra?: ExtraOptions | undefined;
7
6
  protected conn: C | undefined;
8
7
  protected getConn(): C;
9
- constructor(connect: () => Promise<C>, dialect: AbstractSqlDialect, extra?: ExtraOptions | undefined);
8
+ constructor(connect: () => Promise<C>, dialect: AbstractSqlDialect, extra?: ExtraOptions);
10
9
  protected lazyConnect(): Promise<void>;
11
10
  /** A connection as this querier takes it from its pool, before its first statement: see {@link releaseConn}. */
12
11
  protected acquired(conn: C): C;
@@ -1,7 +1,6 @@
1
1
  import { AbstractSqlQuerier } from './abstractSqlQuerier.js';
2
2
  export class AbstractPoolQuerier extends AbstractSqlQuerier {
3
3
  connect;
4
- extra;
5
4
  conn;
6
5
  getConn() {
7
6
  if (!this.conn)
@@ -11,7 +10,6 @@ export class AbstractPoolQuerier extends AbstractSqlQuerier {
11
10
  constructor(connect, dialect, extra) {
12
11
  super(dialect, extra);
13
12
  this.connect = connect;
14
- this.extra = extra;
15
13
  }
16
14
  async lazyConnect() {
17
15
  await super.lazyConnect();
@@ -10,9 +10,8 @@ export type BoundStatement = {
10
10
  export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
11
11
  #private;
12
12
  readonly dialect: AbstractSqlDialect;
13
- readonly extra?: ExtraOptions | undefined;
14
13
  hasOpenTransaction: boolean;
15
- constructor(dialect: AbstractSqlDialect, extra?: ExtraOptions | undefined);
14
+ constructor(dialect: AbstractSqlDialect, extra?: ExtraOptions);
16
15
  /** Runs one statement on the driver: what it read, how many rows it changed, and any id its header reports. */
17
16
  protected abstract execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
18
17
  /** What a write reports: the rows it changed, and their ids, inferred from a header's first id where the dialect reads them so. */
@@ -104,6 +103,13 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
104
103
  estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
105
104
  protected internalAggregate<E extends object>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): Promise<RawRow[]>;
106
105
  internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
106
+ /**
107
+ * Writes a defaulted key onto each row naming none, where the engine reports only a key it generates: the row then
108
+ * names its key, the value the column would have taken, SQL evaluated first.
109
+ */
110
+ private fillDefaultedKeys;
111
+ /** What SQL evaluates to on its own, `count` times, each as a column's default would: one statement, a value a row. */
112
+ private evaluated;
107
113
  /**
108
114
  * The statements an insert of `rows` takes, as the indexes of the rows each writes. Grouped by whether a row names
109
115
  * its key, as the two carry different columns: a budget taken over their union would under-fill the statement
@@ -1,8 +1,9 @@
1
- import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
1
+ import { AGGREGATE_VALUE_ALIAS, KEY_DEFAULT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
2
  import { getMeta } from '../entity/index.js';
3
3
  import { generatesKey, idOf, namesEvery, namesKey, soleId } from '../entity/metadata/definition.js';
4
+ import { QuerySql } from '../type/querySql.js';
4
5
  import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, upsertKeepsOwnKey, getKeys, rowKey, } from '../util/index.js';
5
- import { statementOf } from '../util/sql.js';
6
+ import { sql, statementOf } from '../util/sql.js';
6
7
  import { UqlUsageError } from '../util/uqlError.js';
7
8
  import { AbstractQuerier } from './abstractQuerier.js';
8
9
  import { streamViaCursor } from './cursorStream.js';
@@ -64,14 +65,12 @@ function inPayloadOrder(meta, rows, reported) {
64
65
  }
65
66
  export class AbstractSqlQuerier extends AbstractQuerier {
66
67
  dialect;
67
- extra;
68
68
  hasOpenTransaction = false;
69
69
  /** Cached `auto_increment_increment` stride; see {@link loadInsertIdIncrement}. */
70
70
  #insertIdIncrement;
71
71
  constructor(dialect, extra) {
72
72
  super(extra);
73
73
  this.dialect = dialect;
74
- this.extra = extra;
75
74
  }
76
75
  /** What a write reports: the rows it changed, and their ids, inferred from a header's first id where the dialect reads them so. */
77
76
  updateResultOf(result) {
@@ -286,6 +285,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
286
285
  const [idKey] = meta.ids;
287
286
  const sole = soleId(meta);
288
287
  const generatedKey = generatesKey(meta);
288
+ await this.fillDefaultedKeys(meta, rows);
289
289
  // Only a statement whose every row left its key to the database needs its ids, which a supplied one would void
290
290
  // in a header: a `RETURNING` reports them all, a header only a generated key's.
291
291
  const statements = this.insertChunks(meta, rows).map((indexes) => ({
@@ -318,6 +318,31 @@ export class AbstractSqlQuerier extends AbstractQuerier {
318
318
  }
319
319
  });
320
320
  }
321
+ /**
322
+ * Writes a defaulted key onto each row naming none, where the engine reports only a key it generates: the row then
323
+ * names its key, the value the column would have taken, SQL evaluated first.
324
+ */
325
+ async fillDefaultedKeys(meta, rows) {
326
+ const sole = soleId(meta);
327
+ if (sole?.field.defaultValue === undefined || this.dialect.insertIdSource === 'returning') {
328
+ return;
329
+ }
330
+ const unnamed = rows.filter((row) => !namesKey(meta, row));
331
+ if (!unnamed.length) {
332
+ return;
333
+ }
334
+ const value = sole.field.defaultValue;
335
+ const keys = value instanceof QuerySql ? await this.evaluated(value, unnamed.length) : unnamed.map(() => value);
336
+ unnamed.forEach((row, at) => {
337
+ row[sole.key] = keys[at];
338
+ });
339
+ }
340
+ /** What SQL evaluates to on its own, `count` times, each as a column's default would: one statement, a value a row. */
341
+ async evaluated(value, count) {
342
+ const select = sql `SELECT ${value} AS ${sql.id(KEY_DEFAULT_ALIAS)}`;
343
+ const rows = await this.rowsOf(sql.join(new Array(count).fill(select), ' UNION ALL '));
344
+ return rows.map((row) => row[KEY_DEFAULT_ALIAS]);
345
+ }
321
346
  /**
322
347
  * The statements an insert of `rows` takes, as the indexes of the rows each writes. Grouped by whether a row names
323
348
  * its key, as the two carry different columns: a budget taken over their union would under-fill the statement
@@ -19,9 +19,9 @@ type TypeBounds = {
19
19
  * `TINYINT(1)` means boolean on MySQL.
20
20
  */
21
21
  export declare function sqlToCanonical(sqlType: string, reported?: TypeBounds): CanonicalType;
22
- /**
23
- * Convert a canonical type to a SQL type string for a specific dialect instance.
24
- */
22
+ /** {@link canonicalToSql} for a key the database does not generate, which an engine may spell apart from one it does. */
23
+ export declare function suppliedKeySql(type: CanonicalType, dialect: AbstractDialect): string;
24
+ /** Convert a canonical type to a SQL type string for a specific dialect instance. */
25
25
  export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDialect): string;
26
26
  /**
27
27
  * Convert a canonical type to a TypeScript type string.
@@ -203,7 +203,7 @@ const ENGINE_TYPES = {
203
203
  timestampPrecision: 0,
204
204
  },
205
205
  // SQLite uses affinity, so no size variants. `F32_BLOB` is libSQL's vector type; elsewhere just a name of BLOB affinity.
206
- sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB') },
206
+ sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB'), suppliedIntegerKey: 'INT' },
207
207
  // 2025 and up; below that the server refuses the type rather than storing it as text.
208
208
  mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES, timestampPrecision: 7 },
209
209
  mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
@@ -277,9 +277,14 @@ function declaredSqlType(options) {
277
277
  }
278
278
  return columnType ?? (typeof type === 'string' ? type : undefined);
279
279
  }
280
- /**
281
- * Convert a canonical type to a SQL type string for a specific dialect instance.
282
- */
280
+ /** {@link canonicalToSql} for a key the database does not generate, which an engine may spell apart from one it does. */
281
+ export function suppliedKeySql(type, dialect) {
282
+ const { suppliedIntegerKey } = ENGINE_TYPES[dialect.dialectName];
283
+ return suppliedIntegerKey && type.category === 'integer' && !type.raw
284
+ ? suppliedIntegerKey
285
+ : canonicalToSql(type, dialect);
286
+ }
287
+ /** Convert a canonical type to a SQL type string for a specific dialect instance. */
283
288
  export function canonicalToSql(type, dialect) {
284
289
  if (type.raw)
285
290
  return type.raw;
@@ -1,11 +1,9 @@
1
1
  import type { Except, FieldMeta, QuerySql } from '../type/index.js';
2
2
  import type { ColumnNode } from './types.js';
3
3
  /**
4
- * The column a field's options declare, whether an entity's table or a migration holds it: `soleKey` says whether it
5
- * is its table's whole and own key, which a numeric one auto-increments as, and `compile` renders its SQL.
4
+ * The column a field's options declare, whether an entity's table or a migration holds it: `compile` renders its SQL.
6
5
  */
7
- export declare function declaredColumn(field: FieldMeta, { name, soleKey, compile, }: {
6
+ export declare function declaredColumn(field: FieldMeta, { name, compile }: {
8
7
  readonly name: string;
9
- readonly soleKey: boolean;
10
8
  readonly compile: (sql: QuerySql) => string;
11
9
  }): Except<ColumnNode, 'table'>;
@@ -1,18 +1,17 @@
1
- import { declaresNotNull, fieldFamily, isAutoIncrement } from '../util/field.util.js';
1
+ import { declaresNotNull, fieldFamily } from '../util/field.util.js';
2
2
  import { resolveColumnCanonicalType } from './canonicalType.js';
3
3
  import { schemaDefault } from './sqlExpression.js';
4
4
  /**
5
- * The column a field's options declare, whether an entity's table or a migration holds it: `soleKey` says whether it
6
- * is its table's whole and own key, which a numeric one auto-increments as, and `compile` renders its SQL.
5
+ * The column a field's options declare, whether an entity's table or a migration holds it: `compile` renders its SQL.
7
6
  */
8
- export function declaredColumn(field, { name, soleKey, compile, }) {
7
+ export function declaredColumn(field, { name, compile }) {
9
8
  return {
10
9
  name,
11
10
  type: resolveColumnCanonicalType(field),
12
11
  nullable: !declaresNotNull(field),
13
12
  defaultValue: schemaDefault(field.defaultValue, compile, fieldFamily(field) === 'json'),
14
13
  isPrimaryKey: field.isId === true,
15
- isAutoIncrement: isAutoIncrement(field, soleKey),
14
+ isAutoIncrement: field.autoIncrement === true,
16
15
  isUnique: field.unique ?? false,
17
16
  // A stamp is filled by a trigger, so it is a column like any other; only `stored: true` generates.
18
17
  generatedAs: field.stored === true && field.computed ? compile(field.computed) : undefined,
@@ -1,4 +1,4 @@
1
- import { fieldOf, foreignKeysOf, getMeta, ownsSoleKey } from '../entity/metadata/definition.js';
1
+ import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
2
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 } from '../util/field.util.js';
@@ -50,7 +50,6 @@ function addTableFromEntity(ctx, meta) {
50
50
  const column = {
51
51
  ...declaredColumn(field, {
52
52
  name: columnName,
53
- soleKey: ownsSoleKey(meta, key),
54
53
  compile: (sql) => ctx.compileDdl(sql, meta.entity),
55
54
  }),
56
55
  ...(notNull.has(key) && { nullable: false }),
@@ -45,10 +45,9 @@ export type HranaQuerierConnectionOptions = {
45
45
  */
46
46
  export declare class HranaQuerier extends AbstractSqlQuerier {
47
47
  readonly client: HranaClient;
48
- readonly extra?: ExtraOptions | undefined;
49
48
  private tx?;
50
49
  private readonly closeClientOnRelease;
51
- constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions | undefined, connection?: HranaQuerierConnectionOptions);
50
+ constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions, connection?: HranaQuerierConnectionOptions);
52
51
  /** Runs on the open transaction's handle when there is one. */
53
52
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
54
53
  /** A list as one request: the client's `batch`, all or none; inside an open transaction, its own, which joins it. */
@@ -9,13 +9,11 @@ import { sqliteStatements, toBindValues } from './bindValues.js';
9
9
  */
10
10
  export class HranaQuerier extends AbstractSqlQuerier {
11
11
  client;
12
- extra;
13
12
  tx;
14
13
  closeClientOnRelease;
15
14
  constructor(client, dialect, extra, connection) {
16
15
  super(dialect, extra);
17
16
  this.client = client;
18
- this.extra = extra;
19
17
  this.closeClientOnRelease = connection?.closeClientOnRelease ?? false;
20
18
  }
21
19
  /** Runs on the open transaction's handle when there is one. */
@@ -1,5 +1,6 @@
1
1
  import { AbstractSqlQuerier } from '../querier/index.js';
2
2
  import type { ExtraOptions, RawRow } from '../type/index.js';
3
+ import type { SqlExecution } from '../util/sql.util.js';
3
4
  import { type SqliteBindValue } from './bindValues.js';
4
5
  import type { SqliteDialect } from './sqliteDialect.js';
5
6
  /**
@@ -32,18 +33,11 @@ export type SqliteDatabase = {
32
33
  */
33
34
  export declare class SqliteQuerier extends AbstractSqlQuerier {
34
35
  readonly db: SqliteDatabase;
35
- readonly extra?: ExtraOptions | undefined;
36
- constructor(db: SqliteDatabase, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
36
+ constructor(db: SqliteDatabase, dialect: SqliteDialect, extra?: ExtraOptions);
37
37
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
38
38
  protected get connection(): object;
39
39
  /** `reader` picks the call: `run()` would discard the rows of a statement that reads, RETURNING included. */
40
- protected execute(sql: string, values?: unknown[]): Promise<{
41
- rows: RawRow[];
42
- changes?: undefined;
43
- } | {
44
- rows: never[];
45
- changes: number;
46
- }>;
40
+ protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
47
41
  /** Row by row, as the driver steps the statement. */
48
42
  internalStream(sql: string, values?: unknown[]): AsyncGenerator<RawRow, void, unknown>;
49
43
  }
@@ -8,11 +8,9 @@ import { toBindValues } from './bindValues.js';
8
8
  */
9
9
  export class SqliteQuerier extends AbstractSqlQuerier {
10
10
  db;
11
- extra;
12
11
  constructor(db, dialect, extra) {
13
12
  super(dialect, extra);
14
13
  this.db = db;
15
- this.extra = extra;
16
14
  }
17
15
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
18
16
  get connection() {
@@ -49,8 +49,7 @@ export type TursoSession = {
49
49
  /** A Turso Cloud querier on a stream of its own, which holds its transaction and which `release` closes. */
50
50
  export declare class TursoSessionQuerier extends AbstractSqlQuerier {
51
51
  readonly session: TursoSession;
52
- readonly extra?: ExtraOptions | undefined;
53
- constructor(session: TursoSession, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
52
+ constructor(session: TursoSession, dialect: SqliteDialect, extra?: ExtraOptions);
54
53
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
55
54
  /**
56
55
  * A list as one request, all or none: its own `BEGIN IMMEDIATE` and `COMMIT` in it, or, inside an open
@@ -4,11 +4,9 @@ import { decodeBigInts } from '../util/wideNumber.js';
4
4
  /** A Turso Cloud querier on a stream of its own, which holds its transaction and which `release` closes. */
5
5
  export class TursoSessionQuerier extends AbstractSqlQuerier {
6
6
  session;
7
- extra;
8
7
  constructor(session, dialect, extra) {
9
8
  super(dialect, extra);
10
9
  this.session = session;
11
- this.extra = extra;
12
10
  }
13
11
  async execute(sql, values) {
14
12
  return executionOf(await this.session.execute(sql, toBindValues(values), true));
@@ -1,10 +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 { ReferencedKey } from './definedEntity.js';
4
- import type { BlobColumnType, BooleanColumnType, ColumnType, DateColumnType, DdlDefault, JsonColumnType, NumericColumnType, StringColumnType, VectorColumnType, FieldOptions, HasCompositeKey, IdValue, JoinKind, OnFieldCallback, StampEvent } from './entity.js';
3
+ import type { ColumnType, DdlDefault, FamilyOf, FieldOptions, HasCompositeKey, IdValue, JsonColumnType, OnFieldCallback, StampEvent, TsTypeOf } from './entity.js';
5
4
  import type { QuerySql } from './querySql.js';
6
5
  import type { StandardSchemaV1 } from './standardSchema.js';
7
- import type { Type, Json, AbstractType } from './utility.js';
6
+ import type { Type, Json, JsonDocument, JsonScalar, AbstractType } from './utility.js';
8
7
  import type { VectorDistance } from './vector.js';
9
8
  /** Where a column builder holds its options, so every string key of a builder is a method. */
10
9
  export declare const COLUMN_OPTIONS: unique symbol;
@@ -75,7 +74,7 @@ export interface ColumnBuilder<in out O, in out V, F extends Family> extends Col
75
74
  readonly nullable: true;
76
75
  }, F>;
77
76
  /** Makes it the primary key, or a column of a composite one. */
78
- id(this: Lacking<'nullable'>): With<O, V, {
77
+ id(this: Lacking<'nullable' | 'autoIncrement'>): With<O, V, {
79
78
  readonly isId: true;
80
79
  }, F>;
81
80
  /** The column's DDL default: a value, or SQL the database evaluates per row (`currentTimestamp`, `sql`). */
@@ -123,8 +122,8 @@ export interface ColumnBuilder<in out O, in out V, F extends Family> extends Col
123
122
  columnType(this: Lacking<TypeBound>, type: QuerySql): With<O, V, {
124
123
  readonly columnType: QuerySql;
125
124
  }, F>;
126
- /** A foreign key to `entity`'s key, which the column has to hold the kind of: `f.number().references(() => User)`. */
127
- references<C extends Type<object>>(entity: () => C & HoldsKey<C, V>): With<O, V, {
125
+ /** A foreign key to `entity`'s key, which `@Field` holds its property to: `f.number().references(() => User)`. */
126
+ references<C extends Type<object>>(entity: () => C): With<O, V, {
128
127
  readonly references: () => C;
129
128
  }, F>;
130
129
  /** The foreign key's delete action. */
@@ -133,8 +132,6 @@ export interface ColumnBuilder<in out O, in out V, F extends Family> extends Col
133
132
  }>, action: ForeignKeyAction): With<O, V, {
134
133
  readonly onDelete: ForeignKeyAction;
135
134
  }, F>;
136
- /** Narrows the value a row holds, a branded id or a literal union: `f.uuid().narrow<UserId>()`. */
137
- narrow<T extends V>(): Builders<O, T>[F];
138
135
  /**
139
136
  * A column the database computes from `expression`, read in each query naming it; `stored()` keeps it. A relation
140
137
  * aggregate is no column's SQL: it is read on each query, so `@Computed` or `aggregates` declares one.
@@ -153,13 +150,11 @@ export interface NumericColumn<in out O, in out V> extends ColumnBuilder<O, V, '
153
150
  scale(this: TypeNotSql, digits: number): NumericColumn<O & {
154
151
  readonly scale: number;
155
152
  }, V>;
156
- /** Has the database generate the value, which a numeric sole key does unless `autoIncrement(false)` says otherwise. */
157
- autoIncrement(): NumericColumn<O & {
153
+ /** Makes it the primary key, which the database generates. A key the caller supplies is `.id()`. */
154
+ autoIncrement(this: Lacking<'nullable' | 'isId'>): NumericColumn<O & {
155
+ readonly isId: true;
158
156
  readonly autoIncrement: true;
159
157
  }, V>;
160
- autoIncrement(generated: false): NumericColumn<O & {
161
- readonly autoIncrement: false;
162
- }, V>;
163
158
  }
164
159
  export interface StringColumn<in out O, in out V> extends ColumnBuilder<O, V, 'string'> {
165
160
  length(this: TypeNotSql, length: number): StringColumn<O & {
@@ -200,24 +195,18 @@ export interface VersionColumn<in out O, in out V> extends Column<O, V> {
200
195
  readonly comment: string;
201
196
  }, V>;
202
197
  }
203
- /** Refuses a target whose key is another kind of value than the column holds, which no join matches. */
204
- type HoldsKey<C, V> = [JoinKind<NonNullable<ReferencedKey<C>>>] extends [JoinKind<V>] ? unknown : {
205
- readonly __columnMustHoldReferencedKey: ReferencedKey<C>;
206
- };
207
- /** The column types holding an exact decimal, read as its text: a JS number would round it. */
208
- type DecimalType = 'decimal' | 'numeric';
209
198
  /** A JSON column of `T`, typed by the payload its schema validates to, or any document with none. */
210
199
  type JsonColumn<T extends 'json' | 'jsonb'> = {
211
- (): ColumnBuilder<{
200
+ <P extends JsonScalar | object = JsonDocument>(): ColumnBuilder<{
212
201
  readonly type: T;
213
- }, Json, 'json'>;
202
+ }, Json<P>, 'json'>;
214
203
  <S extends StandardSchemaV1>(schema: S): ColumnBuilder<{
215
204
  readonly type: T;
216
205
  readonly schema: S;
217
206
  }, JsonOutput<PayloadOf<S['~standard']['types']>>, 'json'>;
218
207
  };
219
208
  /** 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;
209
+ type JsonOutput<O> = O extends JsonScalar | object | null ? Json<O> : Json;
221
210
  /** The output a schema's `types` states, `unknown` where it states none: `never` would type the column as nothing. */
222
211
  type PayloadOf<T> = NonNullable<T> extends infer N ? [N] extends [never] ? unknown : N extends {
223
212
  readonly output: infer O;
@@ -226,42 +215,51 @@ type PayloadOf<T> = NonNullable<T> extends infer N ? [N] extends [never] ? unkno
226
215
  type ReferenceValue<C> = C extends AbstractType<infer E> ? HasCompositeKey<E> extends true ? {
227
216
  readonly __compositeKeyNeedsAColumnPerKey: true;
228
217
  } : NonNullable<IdValue<E>> : never;
229
- /** The builders, one per value a column holds; `column` takes any SQL type, its family deciding what it offers. */
218
+ /** The builder of a SQL type, its value what the type reads as: a family alone does not say, `time` and a decimal being text. */
219
+ type ColumnOf<T extends ColumnType> = [FamilyOf<T>] extends [never] ? ColumnBuilder<{
220
+ readonly type: ColumnType;
221
+ }, unknown, 'any'> : Builders<{
222
+ readonly type: T;
223
+ }, T extends JsonColumnType ? Json : TsTypeOf<T>>[FamilyOf<T>];
224
+ /**
225
+ * The builders, one per value a column holds; `column` takes any SQL type, its family deciding what it offers. A
226
+ * scalar's or a document's type argument narrows what a row holds, a brand or a payload: `f.uuid<UserId>()`.
227
+ */
230
228
  export type ColumnFactory = {
231
- string(): StringColumn<{
229
+ string<V extends string = string>(): StringColumn<{
232
230
  readonly type: StringConstructor;
233
- }, string>;
234
- text(): StringColumn<{
231
+ }, V>;
232
+ text<V extends string = string>(): StringColumn<{
235
233
  readonly type: 'text';
236
- }, string>;
237
- uuid(): StringColumn<{
234
+ }, V>;
235
+ uuid<V extends string = string>(): StringColumn<{
238
236
  readonly type: 'uuid';
239
- }, string>;
240
- number(): NumericColumn<{
237
+ }, V>;
238
+ number<V extends number = number>(): NumericColumn<{
241
239
  readonly type: NumberConstructor;
242
- }, number>;
243
- bigint(): NumericColumn<{
240
+ }, V>;
241
+ bigint<V extends bigint = bigint>(): NumericColumn<{
244
242
  readonly type: BigIntConstructor;
245
- }, bigint>;
243
+ }, V>;
246
244
  /** An exact decimal, read as its text: a JS number would round it. `f.number().precision()` opts in to that. */
247
- decimal(): NumericColumn<{
245
+ decimal<V extends string = string>(): NumericColumn<{
248
246
  readonly type: 'decimal';
249
- }, string>;
250
- decimal(precision: number): NumericColumn<{
247
+ }, V>;
248
+ decimal<V extends string = string>(precision: number): NumericColumn<{
251
249
  readonly type: 'decimal';
252
250
  readonly precision: number;
253
- }, string>;
254
- decimal(precision: number, scale: number): NumericColumn<{
251
+ }, V>;
252
+ decimal<V extends string = string>(precision: number, scale: number): NumericColumn<{
255
253
  readonly type: 'decimal';
256
254
  readonly precision: number;
257
255
  readonly scale: number;
258
- }, string>;
256
+ }, V>;
259
257
  boolean(): ColumnBuilder<{
260
258
  readonly type: BooleanConstructor;
261
259
  }, boolean, 'boolean'>;
262
- date(): DateColumn<{
260
+ date<V extends Date = Date>(): DateColumn<{
263
261
  readonly type: DateConstructor;
264
- }, Date>;
262
+ }, V>;
265
263
  json: JsonColumn<'json'>;
266
264
  jsonb: JsonColumn<'jsonb'>;
267
265
  vector(dimensions: number): VectorColumn<{
@@ -289,38 +287,8 @@ export type ColumnFactory = {
289
287
  readonly type: BigIntConstructor;
290
288
  readonly version: true;
291
289
  }, bigint>;
292
- /** A column of SQL type `type`, offering what its family takes. */
293
- column(type: DecimalType): NumericColumn<{
294
- readonly type: DecimalType;
295
- }, string>;
296
- column(type: Exclude<NumericColumnType, DecimalType>): NumericColumn<{
297
- readonly type: NumericColumnType;
298
- }, number | bigint>;
299
- column(type: StringColumnType): StringColumn<{
300
- readonly type: StringColumnType;
301
- }, string>;
302
- column(type: 'time'): DateColumn<{
303
- readonly type: 'time';
304
- }, string>;
305
- column(type: Exclude<DateColumnType, 'time'>): DateColumn<{
306
- readonly type: DateColumnType;
307
- }, Date>;
308
- column(type: VectorColumnType): VectorColumn<{
309
- readonly type: VectorColumnType;
310
- }, readonly number[]>;
311
- column(type: BooleanColumnType): ColumnBuilder<{
312
- readonly type: BooleanColumnType;
313
- }, boolean, 'boolean'>;
314
- column(type: JsonColumnType): ColumnBuilder<{
315
- readonly type: JsonColumnType;
316
- }, Json, 'json'>;
317
- column(type: BlobColumnType): ColumnBuilder<{
318
- readonly type: BlobColumnType;
319
- }, Uint8Array, 'blob'>;
320
- /** A column whose type is data, as an entity defined at run time declares one. */
321
- column(type: ColumnType): ColumnBuilder<{
322
- readonly type: ColumnType;
323
- }, unknown, 'any'>;
290
+ /** A column of SQL type `type`, offering what its family takes, or what any does where its type is data. */
291
+ column<T extends ColumnType>(type: T): ColumnOf<T>;
324
292
  /** A foreign key to `entity`'s key, its column typed as that key is. */
325
293
  references<C extends Type<object>>(entity: () => C): ColumnBuilder<{
326
294
  readonly references: () => C;
@@ -100,7 +100,7 @@ type IdKeyOf<F> = FlagKeys<F, Column<{
100
100
  type VersionKeyOf<F> = FlagKeys<F, Column<{
101
101
  readonly version: true;
102
102
  }>>;
103
- type FilledKeyOf<F> = Exclude<FlagKeys<F, Column<FilledOptions>>, IdKeyOf<F>>;
103
+ type FilledKeyOf<F> = FlagKeys<F, Column<FilledOptions>>;
104
104
  /** The relation constructors a defined entity's `relations` receives, typed by the columns of the entity declaring them. */
105
105
  export type RelationBuilder<O> = {
106
106
  oneToOne<T extends object, K = IdValue<T>, Columns = T>(target: Type<T> & DefinedShape<K, Columns>, opts: RelationOwnerOptions<T, O, DefinedJoins<T, O, K, Columns>> | RelationInverseOptions<T, DefinedJoins<T, O, K, Columns>>): DefinedRelation<T, '11'>;