uql-orm 0.100.2 → 0.101.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 (50) hide show
  1. package/README.md +8 -70
  2. package/dist/bunSql/bunSqlQuerierPool.js +3 -1
  3. package/dist/dialect/abstractSqlDialect.d.ts +35 -23
  4. package/dist/dialect/abstractSqlDialect.js +90 -72
  5. package/dist/dialect/hydrateColumn.d.ts +4 -5
  6. package/dist/dialect/hydrateColumn.js +2 -8
  7. package/dist/dialect/mysqlLikeSqlDialect.d.ts +4 -4
  8. package/dist/dialect/mysqlLikeSqlDialect.js +7 -6
  9. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -2
  10. package/dist/dialect/pgLikeSqlDialect.js +11 -3
  11. package/dist/entity/metadata/definition.js +1 -1
  12. package/dist/http/fetchHandler.d.ts +1 -1
  13. package/dist/http/fetchHandler.js +1 -1
  14. package/dist/index.d.ts +2 -1
  15. package/dist/index.js +1 -1
  16. package/dist/mariadb/mariaDialect.d.ts +2 -2
  17. package/dist/mariadb/mariaDialect.js +1 -0
  18. package/dist/migrate/cli-config.d.ts +4 -7
  19. package/dist/migrate/cli-config.js +11 -9
  20. package/dist/mongodb/mongoDialect.js +11 -9
  21. package/dist/mssql/mssqlDialect.d.ts +2 -2
  22. package/dist/mssql/mssqlDialect.js +1 -0
  23. package/dist/pglite/pgliteQuerierPool.js +6 -12
  24. package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
  25. package/dist/postgres/abstractPgQuerierPool.js +0 -3
  26. package/dist/postgres/pgQuerier.d.ts +6 -0
  27. package/dist/postgres/pgQuerier.js +10 -0
  28. package/dist/postgres/pgWireTypes.d.ts +11 -7
  29. package/dist/postgres/pgWireTypes.js +47 -11
  30. package/dist/querier/abstractPoolQuerier.d.ts +2 -0
  31. package/dist/querier/abstractPoolQuerier.js +5 -1
  32. package/dist/querier/abstractQuerier.d.ts +5 -5
  33. package/dist/querier/abstractQuerier.js +59 -53
  34. package/dist/querier/abstractSqlQuerier.d.ts +3 -13
  35. package/dist/querier/abstractSqlQuerier.js +24 -84
  36. package/dist/querier/rowReader.d.ts +8 -0
  37. package/dist/querier/rowReader.js +88 -0
  38. package/dist/sqlite/sqliteDialect.d.ts +2 -2
  39. package/dist/sqlite/sqliteDialect.js +2 -1
  40. package/dist/util/dialect.util.d.ts +2 -11
  41. package/dist/util/dialect.util.js +8 -21
  42. package/dist/util/query.util.js +16 -8
  43. package/dist/util/relationQuery.util.d.ts +21 -12
  44. package/dist/util/relationQuery.util.js +30 -14
  45. package/dist/util/sql.util.d.ts +0 -5
  46. package/dist/util/sql.util.js +0 -33
  47. package/dist/util/wideNumber.d.ts +4 -3
  48. package/dist/util/wideNumber.js +17 -6
  49. package/package.json +3 -4
  50. package/skills/uql-orm/SKILL.md +4 -2
@@ -1,5 +1,5 @@
1
1
  import type { EntityMeta, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryTextSearchOptions, RowLockFeatures, SqlDialectFeatures, SqlDialectName, SqlValues, Type, UpdatePayload } from '../type/index.js';
2
- import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from './abstractSqlDialect.js';
2
+ import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from './abstractSqlDialect.js';
3
3
  import { type JsonSlot } from './jsonSql.js';
4
4
  /** Declared apart so MariaDB, which has no `FOR UPDATE OF`, can restate that one part of it. */
5
5
  export declare const MYSQL_ROW_LOCKS: RowLockFeatures;
@@ -52,9 +52,9 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
52
52
  * An ordered `GROUP_CONCAT` of each row's object, which reads as a JSON array: MySQL's `JSON_ARRAYAGG`
53
53
  * takes no `ORDER BY`, and as a window over the rows it rebuilds the array for every one of them.
54
54
  */
55
- protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
55
+ protected appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
56
56
  /** A read's statement, with the settings it needs applied to it alone. */
57
- find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
57
+ find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): readonly SelectTerm[];
58
58
  /** A `$distinct` read's count, which reads the relations the read does. */
59
59
  countDistinct<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
60
60
  private settled;
@@ -76,7 +76,7 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
76
76
  blob: (expr: string) => string;
77
77
  vector: (expr: string, field: import("../type/entity.js").FieldOptions) => string;
78
78
  };
79
- /** Bytes as the hex text `decodeColumn` reads back, whole. */
79
+ /** Bytes as the hex text `DECODERS.bytes` reads back, whole. */
80
80
  protected bytesAsText(expr: string): string;
81
81
  escape(value: unknown): string;
82
82
  /** A date as UTC text, which a `DATETIME` stores as is, where a driver would convert it to its own zone. */
@@ -139,13 +139,14 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
139
139
  * takes no `ORDER BY`, and as a window over the rows it rebuilds the array for every one of them.
140
140
  */
141
141
  appendRelationArray(ctx, rows) {
142
- const { from, pairs, order } = this.derivedRelation(ctx, rows);
142
+ const { terms, from, pairs, order } = this.derivedRelation(ctx, rows);
143
143
  const objects = `${this.jsonObject(pairs)}${order ? ` ORDER BY ${order}` : ''} SEPARATOR ','`;
144
144
  ctx.append(`(SELECT COALESCE(CONCAT('[', GROUP_CONCAT(${objects}), ']'), '[]') FROM ${from})`);
145
+ return terms;
145
146
  }
146
147
  /** A read's statement, with the settings it needs applied to it alone. */
147
148
  find(ctx, entity, q = {}, opts, totalAlias) {
148
- this.settled(ctx, entity, q, (statement) => super.find(statement, entity, q, opts, totalAlias));
149
+ return this.settled(ctx, entity, q, (statement) => super.find(statement, entity, q, opts, totalAlias));
149
150
  }
150
151
  /** A `$distinct` read's count, which reads the relations the read does. */
151
152
  countDistinct(ctx, entity, q, opts) {
@@ -154,12 +155,12 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
154
155
  settled(ctx, entity, q, build) {
155
156
  const settings = this.statementSettings(entity, q);
156
157
  if (!settings.length) {
157
- build(ctx);
158
- return;
158
+ return build(ctx);
159
159
  }
160
160
  const statement = ctx.createFragment();
161
- build(statement);
161
+ const built = build(statement);
162
162
  ctx.append(this.applySettings(statement.sql, settings));
163
+ return built;
163
164
  }
164
165
  /**
165
166
  * `name=value` for each variable a read's statement sets for itself alone. `GROUP_CONCAT`, and
@@ -181,7 +182,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
181
182
  blob: (expr) => this.bytesAsText(expr),
182
183
  vector: (expr, field) => this.selectFieldExpr(expr, field),
183
184
  };
184
- /** Bytes as the hex text `decodeColumn` reads back, whole. */
185
+ /** Bytes as the hex text `DECODERS.bytes` reads back, whole. */
185
186
  bytesAsText(expr) {
186
187
  return `CONCAT(${this.escape(BYTES_PREFIX)}, HEX(${expr}))`;
187
188
  }
@@ -2,7 +2,8 @@ import type { IndexType } from '../schema/types.js';
2
2
  import type { SqlDialectName, SqlValues } from '../type/index.js';
3
3
  import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
4
4
  import type { DialectOptions } from './abstractDialect.js';
5
- import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
5
+ import { AbstractSqlDialect, type RelationRows, type SelectTerm } from './abstractSqlDialect.js';
6
+ import { type HydrateKind } from './hydrateColumn.js';
6
7
  import { type JsonAccessMode, type JsonSlot } from './jsonSql.js';
7
8
  /** A Postgres-wire dialect's options: the base's, and how its driver binds a parameter. */
8
9
  export type PgLikeDialectOptions = DialectOptions & {
@@ -32,7 +33,12 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
32
33
  * builds it, so a wide row meets no argument limit. `json` has no equality, so under a parent's
33
34
  * `DISTINCT` the array is compared as `jsonb`.
34
35
  */
35
- protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
36
+ protected appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
37
+ /**
38
+ * Every Postgres-wire pool hands back a `BOOLEAN`, a date and an integer column decoded (an `INT8` by the
39
+ * pools' own wide-number rule); a `NUMERIC`, a float and anything crossing JSON still decode as the base says.
40
+ */
41
+ protected decodedAtWire(kind: HydrateKind, field: FieldOptions | undefined): boolean;
36
42
  /**
37
43
  * What JSON would round or cannot spell crosses it as text, for the field's own decode to read back:
38
44
  * a column declared numeric, whatever it decodes as, a vector, and bytes as hex.
@@ -1,9 +1,9 @@
1
1
  import { QueryRaw, } from '../type/index.js';
2
2
  import { bytesToHex } from '../util/bytes.js';
3
3
  import { fulltextConfig, fulltextIndexOver, hasVectorNear, textSearchFields } from '../util/dialect.util.js';
4
- import { jsonPathKeys } from '../util/field.util.js';
4
+ import { isIntegerColumn, jsonPathKeys } from '../util/field.util.js';
5
5
  import { escapePgSqlLiteral, PG_UTC } from '../util/sqlLiteral.js';
6
- import { ANSI_SQL_VALUES, AbstractSqlDialect } from './abstractSqlDialect.js';
6
+ import { ANSI_SQL_VALUES, AbstractSqlDialect, } from './abstractSqlDialect.js';
7
7
  import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
8
8
  import { BYTES_PREFIX } from './hydrateColumn.js';
9
9
  import { jsonSetTarget } from './jsonSql.js';
@@ -84,11 +84,19 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
84
84
  * `DISTINCT` the array is compared as `jsonb`.
85
85
  */
86
86
  appendRelationArray(ctx, rows) {
87
- const { from, pairs, order } = this.derivedRelation(ctx, rows);
87
+ const { terms, from, pairs, order } = this.derivedRelation(ctx, rows);
88
88
  const row = this.escapeId(RELATION_ROW_ALIAS, true);
89
89
  const columns = pairs.map(([, column]) => column).join(', ');
90
90
  const array = /*sql*/ `(SELECT COALESCE(JSON_AGG(${row}${order ? ` ORDER BY ${order}` : ''}), '[]'::json) FROM ${from} CROSS JOIN LATERAL (SELECT ${columns}) ${row})`;
91
91
  ctx.append(rows.distinct ? `${array}::jsonb` : array);
92
+ return terms;
93
+ }
94
+ /**
95
+ * Every Postgres-wire pool hands back a `BOOLEAN`, a date and an integer column decoded (an `INT8` by the
96
+ * pools' own wide-number rule); a `NUMERIC`, a float and anything crossing JSON still decode as the base says.
97
+ */
98
+ decodedAtWire(kind, field) {
99
+ return kind === 'boolean' || kind === 'date' || (kind === 'number' && !!field && isIntegerColumn(field));
92
100
  }
93
101
  /**
94
102
  * What JSON would round or cannot spell crosses it as text, for the field's own decode to read back:
@@ -260,7 +260,7 @@ export function assertSoleId(meta, what) {
260
260
  return;
261
261
  }
262
262
  throw new UqlUsageError(ids.length
263
- ? `'${meta.entity.name}' has a composite primary key (${ids.join(', ')}), which ${what} does not support yet.`
263
+ ? `'${meta.entity.name}' has a composite primary key (${ids.join(', ')}), which ${what} does not support.`
264
264
  : // An entity registered with `@Field` but no `@Entity` never ran the check in `defineEntity`.
265
265
  `'${meta.entity.name}' has no primary key, which ${what} needs.`);
266
266
  }
@@ -8,6 +8,6 @@ export type FetchHandlerOptions = RequestHandlerOptions<Request> & {
8
8
  /**
9
9
  * Web-standard adapter over {@link createRequestHandler}: mount the returned
10
10
  * `(request: Request) => Promise<Response>` in any fetch-native runtime
11
- * (Hono, Next.js route handlers, Bun.serve, Deno.serve, Cloudflare Workers, SvelteKit).
11
+ * (Hono, Next.js route handlers, Bun.serve, Cloudflare Workers, SvelteKit).
12
12
  */
13
13
  export declare function createFetchHandler(opts: FetchHandlerOptions): (request: Request) => Promise<Response>;
@@ -4,7 +4,7 @@ import { createRequestHandler } from './handler.js';
4
4
  /**
5
5
  * Web-standard adapter over {@link createRequestHandler}: mount the returned
6
6
  * `(request: Request) => Promise<Response>` in any fetch-native runtime
7
- * (Hono, Next.js route handlers, Bun.serve, Deno.serve, Cloudflare Workers, SvelteKit).
7
+ * (Hono, Next.js route handlers, Bun.serve, Cloudflare Workers, SvelteKit).
8
8
  */
9
9
  export function createFetchHandler(opts) {
10
10
  const { basePath = '', ...handlerOpts } = opts;
package/dist/index.d.ts CHANGED
@@ -4,7 +4,8 @@ export * from './entity/decorator/members.js';
4
4
  export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, defineTrigger, getMeta, idOf, removeEntity, } from './entity/metadata/definition.js';
5
5
  export * from './namingStrategy/index.js';
6
6
  export { type QueryError, queryErrorKind } from './querier/queryError.js';
7
- export * from './type/index.js';
7
+ export type * from './type/index.js';
8
+ export { idKey, isSqlQuerier, versionKey } from './type/index.js';
8
9
  export { withDeleted } from './util/filters.util.js';
9
10
  export type { HookContext } from './util/hook.util.js';
10
11
  export { DefaultLogger } from './util/logger.js';
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ export * from './entity/decorator/members.js';
4
4
  export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, defineTrigger, getMeta, idOf, removeEntity, } from './entity/metadata/definition.js';
5
5
  export * from './namingStrategy/index.js';
6
6
  export { queryErrorKind } from './querier/queryError.js';
7
- export * from './type/index.js';
7
+ export { idKey, isSqlQuerier, versionKey } from './type/index.js';
8
8
  export { withDeleted } from './util/filters.util.js';
9
9
  export { DefaultLogger } from './util/logger.js';
10
10
  export { currentDate, currentTime, currentTimestamp, raw, refs, uuid, uuidv7 } from './util/raw.js';
@@ -1,4 +1,4 @@
1
- import { type RelationRows } from '../dialect/abstractSqlDialect.js';
1
+ import { type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
2
  import { type JsonAccessMode } from '../dialect/jsonSql.js';
3
3
  import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
4
4
  import type { FieldOptions, Query, QueryContext, SqlDialectFeatures, SqlValues, Type, VectorDistance, VectorMetric } from '../type/index.js';
@@ -17,7 +17,7 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
17
17
  * A derived table here reads no column of the statement around it, so the aggregate reads the
18
18
  * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
19
19
  */
20
- protected appendRelationArray(ctx: QueryContext, { entity, query, alias, joins }: RelationRows): void;
20
+ protected appendRelationArray(ctx: QueryContext, { entity, query, alias, joins }: RelationRows): readonly SelectTerm[];
21
21
  /**
22
22
  * `JSON_EXTRACT` for the value and `JSON_VALUE` for its text, which every version has: MySQL's `->`/`->>`
23
23
  * arrive only in 13.1.
@@ -38,6 +38,7 @@ export class MariaDialect extends MysqlLikeSqlDialect {
38
38
  const object = this.jsonObject(terms.map((term) => [relationTermKey(term), term.sql]));
39
39
  const rows = `${query.$distinct ? 'DISTINCT ' : ''}${object}${order}${page}`;
40
40
  ctx.append(`COALESCE((SELECT JSON_ARRAYAGG(${rows}) FROM ${this.tableRef(meta, alias).ref}${from}), JSON_ARRAY())`);
41
+ return terms;
41
42
  }
42
43
  /**
43
44
  * `JSON_EXTRACT` for the value and `JSON_VALUE` for its text, which every version has: MySQL's `->`/`->>`
@@ -1,22 +1,19 @@
1
1
  import type { Config } from '../type/index.js';
2
2
  import { UqlUsageError } from '../util/uqlError.js';
3
3
  /**
4
- * The project's own `tsx/esm/api` where Node must load a TypeScript config: Node's type stripping runs
5
- * no decorators, and Bun and Deno transform them natively. uql bundles no transpiler, so the project's
6
- * loader reads the project's `tsconfig.json`. Registered for the process, never imported through: an
7
- * import of its own would load the config's `uql-orm` apart from the CLI's, whose objects the other misreads.
4
+ * The ESM build of the project's own tsx API, where Node must load a TypeScript config: its type stripping
5
+ * runs no decorators. Registered, never imported through, so the config shares the CLI's `uql-orm`. Read off
6
+ * the export map, as `require.resolve` picks the CommonJS build, whose `register` fails on Node 22.
8
7
  */
9
8
  export declare function tsxApiFor(path: string, versions: {
10
9
  bun?: string;
11
- deno?: string;
12
10
  }): string | undefined;
13
11
  /**
14
12
  * Why `path` failed to import. Only plain Node, which strips types without running decorators, can fail on
15
- * those, so only there does it point at a runtime that runs them: Bun, Deno, or the project's tsx.
13
+ * those, so only there does it point at a runtime that runs them: Bun or the project's tsx.
16
14
  */
17
15
  export declare function importFailure(path: string, cause: unknown, versions: {
18
16
  bun?: string;
19
- deno?: string;
20
17
  }, tsxApi: string | undefined): UqlUsageError;
21
18
  /** The config at `customPath`, or the first of {@link CONFIG_FILES} in the working directory; the CLI validates it. */
22
19
  export declare function loadConfig(customPath?: string): Promise<Config>;
@@ -1,20 +1,22 @@
1
1
  import { stat } from 'node:fs/promises';
2
2
  import { createRequire } from 'node:module';
3
- import { resolve } from 'node:path';
3
+ import { dirname, join, resolve } from 'node:path';
4
4
  import { pathToFileURL } from 'node:url';
5
5
  import { UqlUsageError } from '../util/uqlError.js';
6
6
  /**
7
- * The project's own `tsx/esm/api` where Node must load a TypeScript config: Node's type stripping runs
8
- * no decorators, and Bun and Deno transform them natively. uql bundles no transpiler, so the project's
9
- * loader reads the project's `tsconfig.json`. Registered for the process, never imported through: an
10
- * import of its own would load the config's `uql-orm` apart from the CLI's, whose objects the other misreads.
7
+ * The ESM build of the project's own tsx API, where Node must load a TypeScript config: its type stripping
8
+ * runs no decorators. Registered, never imported through, so the config shares the CLI's `uql-orm`. Read off
9
+ * the export map, as `require.resolve` picks the CommonJS build, whose `register` fails on Node 22.
11
10
  */
12
11
  export function tsxApiFor(path, versions) {
13
- if (!/\.[mc]?ts$/.test(path) || versions.bun || versions.deno) {
12
+ if (!/\.[mc]?ts$/.test(path) || versions.bun) {
14
13
  return undefined;
15
14
  }
16
15
  try {
17
- return createRequire(path).resolve('tsx/esm/api');
16
+ const require = createRequire(path);
17
+ const manifest = require.resolve('tsx/package.json');
18
+ const { exports } = require(manifest);
19
+ return join(dirname(manifest), exports['./esm/api'].import.default);
18
20
  }
19
21
  catch {
20
22
  return undefined;
@@ -36,11 +38,11 @@ async function importConfig(path) {
36
38
  }
37
39
  /**
38
40
  * Why `path` failed to import. Only plain Node, which strips types without running decorators, can fail on
39
- * those, so only there does it point at a runtime that runs them: Bun, Deno, or the project's tsx.
41
+ * those, so only there does it point at a runtime that runs them: Bun or the project's tsx.
40
42
  */
41
43
  export function importFailure(path, cause, versions, tsxApi) {
42
44
  const message = cause instanceof Error ? cause.message : String(cause);
43
- const hint = tsxApi || versions.bun || versions.deno
45
+ const hint = tsxApi || versions.bun
44
46
  ? ''
45
47
  : '\nIf it reaches entity classes, their decorators need a runtime that transforms TypeScript, not ' +
46
48
  'just one that strips its types. Run the CLI with `bun`, or install tsx (`npm i -D tsx`), which the ' +
@@ -6,7 +6,7 @@ import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTe
6
6
  import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
7
7
  import { COUNT_RESULT_KEY } from '../type/query.js';
8
8
  import { QueryRaw } from '../type/queryRaw.js';
9
- import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, holdsForeignKey, jsonKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetKeyColumns, textSortOf, vectorDistanceOf, } from '../util/index.js';
9
+ import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, definedEntries, getKeys, holdsForeignKey, jsonKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, vectorDistanceOf, } from '../util/index.js';
10
10
  import { UqlUsageError } from '../util/uqlError.js';
11
11
  import { decodeBigIntsExcept } from '../util/wideNumber.js';
12
12
  import { textLanguage } from './textLanguage.js';
@@ -303,13 +303,13 @@ export class MongoDialect extends AbstractDialect {
303
303
  assertSoleId(meta, 'MongoDB');
304
304
  assertSoleId(relMeta, 'MongoDB');
305
305
  const [parentJoin] = parentJoins(relOpts, meta.ids.length);
306
- const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
306
+ const [{ column: targetColumn }] = targetJoins(relOpts, meta.ids.length);
307
307
  const scope = this.renderFilter(through, this.scopedWhere(throughMeta, {}));
308
308
  return {
309
309
  lookup: {
310
310
  from: this.resolveTableName(throughMeta),
311
311
  localField: ID_KEY,
312
- foreignField: this.columnOf(throughMeta, parentJoin.joined),
312
+ foreignField: this.columnOf(throughMeta, parentJoin.column),
313
313
  },
314
314
  scope: hasKeys(scope) ? [{ $match: scope }] : [],
315
315
  target: this.columnOf(throughMeta, targetColumn),
@@ -939,12 +939,14 @@ export class MongoDialect extends AbstractDialect {
939
939
  // A 64-bit integer, which the pool reads as a `bigint`: kept for a `BigInt` field, and elsewhere the
940
940
  // number it is where exact and its exact text past 2^53, as every SQL driver decodes one.
941
941
  decodeBigIntsExcept(res, (key) => meta.fields[key]?.type === BigInt);
942
- const relKeys = getKeys(meta.relations).filter((key) => res[key]);
943
- for (const relKey of relKeys) {
944
- const relMeta = getMeta(relationOf(meta, relKey).entity());
945
- res[relKey] = Array.isArray(res[relKey])
946
- ? this.normalizeIds(relMeta, res[relKey])
947
- : this.normalizeId(relMeta, res[relKey]);
942
+ for (const [relKey, relation] of definedEntries(meta.relations)) {
943
+ const value = res[relKey];
944
+ if (value) {
945
+ const relMeta = getMeta(relation.entity());
946
+ res[relKey] = Array.isArray(value)
947
+ ? this.normalizeIds(relMeta, value)
948
+ : this.normalizeId(relMeta, value);
949
+ }
948
950
  }
949
951
  return res;
950
952
  }
@@ -1,4 +1,4 @@
1
- import { type RelationRows } from '../dialect/abstractSqlDialect.js';
1
+ import { type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
2
  import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
4
4
  import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric } from '../type/index.js';
@@ -58,7 +58,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
58
58
  * null out, which is what unflattening a row with a joined column does, so a row with none keeps its
59
59
  * nulls. `JSON_QUERY` keeps the array JSON inside a parent's own `FOR JSON`.
60
60
  */
61
- protected appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
61
+ protected appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
62
62
  /**
63
63
  * What JSON would round or misread crosses it as text: a number exactly, style 3 keeping a float's
64
64
  * 17 digits, bytes as hex, and a date in UTC with its offset, which is how `tedious` reads one.
@@ -167,6 +167,7 @@ export class MsSqlDialect extends MergeSqlDialect {
167
167
  const { terms } = this.read(rowsCtx, rows.entity, rows.query, { alias: rows.alias, json: true }, rows.joins);
168
168
  const nulls = terms.some((term) => relationTermKey(term).includes('.')) ? '' : ', INCLUDE_NULL_VALUES';
169
169
  ctx.append(`JSON_QUERY(COALESCE((${rowsCtx.sql} FOR JSON PATH${nulls}), '[]'))`);
170
+ return terms;
170
171
  }
171
172
  /**
172
173
  * What JSON would round or misread crosses it as text: a number exactly, style 3 keeping a float's
@@ -1,7 +1,6 @@
1
1
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
2
+ import { PG_DECODERS } from '../postgres/pgWireTypes.js';
2
3
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
3
- import { decodeDate } from '../util/date.js';
4
- import { decodeWideNumber } from '../util/wideNumber.js';
5
4
  import { PgliteDialect } from './pgliteDialect.js';
6
5
  import { PgliteQuerier } from './pgliteQuerier.js';
7
6
  /**
@@ -18,18 +17,13 @@ export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
18
17
  this.opts = opts;
19
18
  }
20
19
  async openDb() {
21
- const { PGlite, types } = await import('@electric-sql/pglite');
22
- // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53, and a zoneless
23
- // TIMESTAMP or a DATE as UTC, as every pool reads one; a caller's own `parsers` still win. The declared
24
- // return type is what checks {@link PgliteDatabase} against the real driver, so no cast is needed below it.
20
+ const { PGlite } = await import('@electric-sql/pglite');
21
+ // Every Postgres-wire pool's decoders, which PGlite applies to an array's elements too; a caller's own
22
+ // `parsers` still win. The declared return type is what checks {@link PgliteDatabase} against the real
23
+ // driver, so no cast is needed below it.
25
24
  return PGlite.create(this.dataDir, {
26
25
  ...this.opts,
27
- parsers: {
28
- [types.INT8]: decodeWideNumber,
29
- [types.TIMESTAMP]: decodeDate,
30
- [types.DATE]: decodeDate,
31
- ...this.opts?.parsers,
32
- },
26
+ parsers: { ...Object.fromEntries(PG_DECODERS), ...this.opts?.parsers },
33
27
  });
34
28
  }
35
29
  buildQuerier(db) {
@@ -6,7 +6,6 @@ export interface PgAnyPool<C extends PgAnyClient> {
6
6
  connect: () => Promise<C>;
7
7
  end: () => Promise<void>;
8
8
  on(event: 'error', listener: (err: Error) => void): unknown;
9
- on(event: 'connect', listener: (client: C) => void): unknown;
10
9
  }
11
10
  /** A Postgres-wire pool of {@link PgQuerier}s, attaching the error handler that keeps a dropped connection from crashing the process. */
12
11
  export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<PgQuerier<C>, D> {
@@ -8,9 +8,6 @@ export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
8
8
  super(dialect, extra);
9
9
  this.pool = pool;
10
10
  attachPoolErrorHandler(pool, 'Idle Postgres pool client encountered an error', extra?.logger);
11
- // A client the server drops while a querier holds it emits `error` with no statement to report it to,
12
- // which unheard ends the process. The next statement on it fails instead, and the pool evicts it.
13
- pool.on('connect', (client) => client.on('error', () => { }));
14
11
  }
15
12
  async getQuerier() {
16
13
  return new PgQuerier(() => this.pool.connect(), this.dialect, this.extra);
@@ -7,6 +7,7 @@ export interface PgAnyClient {
7
7
  }>;
8
8
  query(stream: object): AsyncIterable<RawRow>;
9
9
  on(event: 'error', listener: (err: Error) => void): unknown;
10
+ removeListener(event: 'error', listener: (err: Error) => void): unknown;
10
11
  /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
11
12
  release(discard?: boolean): void | Promise<void>;
12
13
  }
@@ -15,6 +16,11 @@ export interface PgAnyClient {
15
16
  * Neon's serverless driver. Generic over the client alone - the dialect is whichever the pool built.
16
17
  */
17
18
  export declare class PgQuerier<C extends PgAnyClient = PgAnyClient> extends AbstractPoolQuerier<C> {
19
+ /**
20
+ * A client the server drops while held emits `error` with no statement to report it to, which unheard ends
21
+ * the process: the querier hears it while it holds the client, `pg-pool` while it idles, never both at once.
22
+ */
23
+ protected acquired(conn: C): C;
18
24
  internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
19
25
  internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
20
26
  internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
@@ -1,9 +1,18 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
+ const ignoreError = () => { };
2
3
  /**
3
4
  * Querier for every client with node-postgres' API: `pg` itself, for Postgres and CockroachDB, and
4
5
  * Neon's serverless driver. Generic over the client alone - the dialect is whichever the pool built.
5
6
  */
6
7
  export class PgQuerier extends AbstractPoolQuerier {
8
+ /**
9
+ * A client the server drops while held emits `error` with no statement to report it to, which unheard ends
10
+ * the process: the querier hears it while it holds the client, `pg-pool` while it idles, never both at once.
11
+ */
12
+ acquired(conn) {
13
+ conn.on('error', ignoreError);
14
+ return conn;
15
+ }
7
16
  async internalAll(query, values) {
8
17
  const res = await this.getConn().query(query, values);
9
18
  return res.rows;
@@ -17,6 +26,7 @@ export class PgQuerier extends AbstractPoolQuerier {
17
26
  yield* this.getConn().query(new QueryStream(query, values));
18
27
  }
19
28
  async releaseConn(conn, discard) {
29
+ conn.removeListener('error', ignoreError);
20
30
  await conn.release(discard);
21
31
  }
22
32
  }
@@ -1,19 +1,23 @@
1
1
  import type { CustomTypesConfig } from 'pg';
2
2
  /**
3
- * The shape every pg-family driver exposes as `types`: `pg`'s own, and `@neondatabase/serverless`'s
3
+ * The registry every pg-family driver exposes as `types`: `pg`'s own, and `@neondatabase/serverless`'s
4
4
  * reimplementation of it. Taken as a parameter rather than imported, because `uql-orm/neon` must not
5
5
  * pull `pg` into an edge bundle that has no such peer installed - the same reason
6
6
  * `abstractPgQuerierPool.ts` keeps its `pg` imports type-only.
7
7
  */
8
8
  type PgTypes = {
9
- readonly builtins: Readonly<Record<string, number>>;
10
- getTypeParser(oid: number, format?: 'text' | 'binary'): (value: string) => unknown;
9
+ getTypeParser(oid: number, format?: 'text' | 'binary'): Decode;
11
10
  };
11
+ type Decode = (text: string) => unknown;
12
12
  /**
13
- * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
14
- * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
15
- * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
16
- * never a global parser, and a caller's own `types` win.
13
+ * The types every Postgres-wire pool decodes itself: an `INT8` by `decodeWideNumber`, since `type: Number`
14
+ * maps to BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's
15
+ * zone. `NUMERIC` is left to hydration, which knows the field.
16
+ */
17
+ export declare const PG_DECODERS: ReadonlyMap<number, Decode>;
18
+ /**
19
+ * {@link PG_DECODERS} as `pg`'s text-format parsers, an array decoding each element as its scalar does.
20
+ * At the wire, which every result crosses; per pool, never a global parser, and a caller's own `types` win.
17
21
  */
18
22
  export declare function wireTypes(types: PgTypes): CustomTypesConfig;
19
23
  export {};
@@ -1,20 +1,56 @@
1
1
  import { decodeDate } from '../util/date.js';
2
2
  import { decodeWideNumber } from '../util/wideNumber.js';
3
+ /** Postgres' fixed OIDs: each type decoded here beside its array, and `TEXT[]`, whose parser splits any array literal. */
4
+ const OID = {
5
+ INT8: 20,
6
+ INT8_ARRAY: 1016,
7
+ TIMESTAMP: 1114,
8
+ TIMESTAMP_ARRAY: 1115,
9
+ DATE: 1082,
10
+ DATE_ARRAY: 1182,
11
+ NUMERIC: 1700,
12
+ NUMERIC_ARRAY: 1231,
13
+ TEXT_ARRAY: 1009,
14
+ };
3
15
  /**
4
- * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
5
- * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
6
- * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
7
- * never a global parser, and a caller's own `types` win.
16
+ * The types every Postgres-wire pool decodes itself: an `INT8` by `decodeWideNumber`, since `type: Number`
17
+ * maps to BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's
18
+ * zone. `NUMERIC` is left to hydration, which knows the field.
19
+ */
20
+ export const PG_DECODERS = new Map([
21
+ [OID.INT8, decodeWideNumber],
22
+ [OID.TIMESTAMP, decodeDate],
23
+ [OID.DATE, decodeDate],
24
+ ]);
25
+ /**
26
+ * Each array `pg` decodes apart from its element's rule, to its element's OID: the three above, and a
27
+ * `NUMERIC[]`, which `pg` reads as floats where its scalar stays exact text.
28
+ */
29
+ const ELEMENT_OIDS = new Map([
30
+ [OID.INT8_ARRAY, OID.INT8],
31
+ [OID.TIMESTAMP_ARRAY, OID.TIMESTAMP],
32
+ [OID.DATE_ARRAY, OID.DATE],
33
+ [OID.NUMERIC_ARRAY, OID.NUMERIC],
34
+ ]);
35
+ /**
36
+ * {@link PG_DECODERS} as `pg`'s text-format parsers, an array decoding each element as its scalar does.
37
+ * At the wire, which every result crosses; per pool, never a global parser, and a caller's own `types` win.
8
38
  */
9
39
  export function wireTypes(types) {
10
- // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
11
- const decoders = new Map([
12
- [types.builtins['INT8'], decodeWideNumber],
13
- [types.builtins['FLOAT8'], Number],
14
- [types.builtins['TIMESTAMP'], decodeDate],
15
- [types.builtins['DATE'], decodeDate],
16
- ]);
40
+ const splitArray = types.getTypeParser(OID.TEXT_ARRAY, 'text');
41
+ const decoders = new Map(PG_DECODERS);
42
+ for (const [arrayOid, oid] of ELEMENT_OIDS) {
43
+ const decode = PG_DECODERS.get(oid) ?? types.getTypeParser(oid, 'text');
44
+ decoders.set(arrayOid, (text) => decodeElements(splitArray(text), decode));
45
+ }
17
46
  return {
47
+ // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
18
48
  getTypeParser: (oid, format) => (format === 'text' && decoders.get(oid)) || types.getTypeParser(oid, format),
19
49
  };
20
50
  }
51
+ function decodeElements(value, decode) {
52
+ if (typeof value === 'string') {
53
+ return decode(value);
54
+ }
55
+ return Array.isArray(value) ? value.map((element) => decodeElements(element, decode)) : value;
56
+ }
@@ -8,6 +8,8 @@ export declare abstract class AbstractPoolQuerier<C> extends AbstractSqlQuerier
8
8
  protected getConn(): C;
9
9
  constructor(connect: () => Promise<C>, dialect: AbstractSqlDialect, extra?: ExtraOptions | undefined);
10
10
  protected lazyConnect(): Promise<void>;
11
+ /** A connection as this querier takes it from its pool, before its first statement: see {@link releaseConn}. */
12
+ protected acquired(conn: C): C;
11
13
  internalRelease(discard: boolean): Promise<void>;
12
14
  protected abstract releaseConn(conn: C, discard: boolean): Promise<void>;
13
15
  }
@@ -15,7 +15,11 @@ export class AbstractPoolQuerier extends AbstractSqlQuerier {
15
15
  }
16
16
  async lazyConnect() {
17
17
  await super.lazyConnect();
18
- this.conn ??= await this.connect();
18
+ this.conn ??= this.acquired(await this.connect());
19
+ }
20
+ /** A connection as this querier takes it from its pool, before its first statement: see {@link releaseConn}. */
21
+ acquired(conn) {
22
+ return conn;
19
23
  }
20
24
  async internalRelease(discard) {
21
25
  const conn = this.conn;
@@ -6,11 +6,7 @@ import { type TransactionScope } from './transaction.js';
6
6
  export declare abstract class AbstractQuerier implements Querier {
7
7
  #private;
8
8
  readonly extra?: ExtraOptions | undefined;
9
- /**
10
- * Internal promise used to queue database operations.
11
- * This ensures that each operation is executed serially, preventing race conditions
12
- * and ensuring that the database connection is used safely across concurrent calls.
13
- */
9
+ /** The last task {@link serialize} queued, which the next one runs after. */
14
10
  private taskQueue;
15
11
  /**
16
12
  * A querier is one unit of work, so releasing ends it. Checked where each backend reaches for its
@@ -210,6 +206,10 @@ export declare abstract class AbstractQuerier implements Querier {
210
206
  * keeping what each does not write, and the parent's other children (a junction's other links) go.
211
207
  */
212
208
  private replaceChildren;
209
+ /** A many-to-many's links: the targets are saved, the parent's links to any other go, and the missing ones are added. */
210
+ private replaceLinks;
211
+ /** The rows a parent owns: those it does not list go, and the listed ones are saved pointing at it. */
212
+ private replaceOwned;
213
213
  /** Writes each parent's children: rows pointed at their parent, or targets linked through the junction. */
214
214
  private saveChildren;
215
215
  /**