uql-orm 0.100.2 → 0.100.3

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 (45) hide show
  1. package/README.md +8 -70
  2. package/dist/bunSql/bunSqlQuerierPool.js +3 -1
  3. package/dist/dialect/abstractSqlDialect.d.ts +27 -22
  4. package/dist/dialect/abstractSqlDialect.js +54 -59
  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/http/fetchHandler.d.ts +1 -1
  12. package/dist/http/fetchHandler.js +1 -1
  13. package/dist/mariadb/mariaDialect.d.ts +2 -2
  14. package/dist/mariadb/mariaDialect.js +1 -0
  15. package/dist/migrate/cli-config.d.ts +2 -4
  16. package/dist/migrate/cli-config.js +4 -4
  17. package/dist/mongodb/mongoDialect.js +9 -7
  18. package/dist/mssql/mssqlDialect.d.ts +2 -2
  19. package/dist/mssql/mssqlDialect.js +1 -0
  20. package/dist/pglite/pgliteQuerierPool.js +6 -12
  21. package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
  22. package/dist/postgres/abstractPgQuerierPool.js +0 -3
  23. package/dist/postgres/pgQuerier.d.ts +6 -0
  24. package/dist/postgres/pgQuerier.js +10 -0
  25. package/dist/postgres/pgWireTypes.d.ts +11 -7
  26. package/dist/postgres/pgWireTypes.js +47 -11
  27. package/dist/querier/abstractPoolQuerier.d.ts +2 -0
  28. package/dist/querier/abstractPoolQuerier.js +5 -1
  29. package/dist/querier/abstractQuerier.d.ts +1 -5
  30. package/dist/querier/abstractQuerier.js +18 -17
  31. package/dist/querier/abstractSqlQuerier.d.ts +3 -13
  32. package/dist/querier/abstractSqlQuerier.js +24 -84
  33. package/dist/querier/rowReader.d.ts +8 -0
  34. package/dist/querier/rowReader.js +88 -0
  35. package/dist/sqlite/sqliteDialect.d.ts +2 -2
  36. package/dist/sqlite/sqliteDialect.js +2 -1
  37. package/dist/util/dialect.util.d.ts +2 -11
  38. package/dist/util/dialect.util.js +8 -21
  39. package/dist/util/query.util.js +16 -8
  40. package/dist/util/sql.util.d.ts +0 -5
  41. package/dist/util/sql.util.js +0 -33
  42. package/dist/util/wideNumber.d.ts +4 -3
  43. package/dist/util/wideNumber.js +17 -6
  44. package/package.json +2 -3
  45. package/skills/uql-orm/SKILL.md +2 -2
@@ -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:
@@ -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;
@@ -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 `->`/`->>`
@@ -2,21 +2,19 @@ import type { Config } from '../type/index.js';
2
2
  import { UqlUsageError } from '../util/uqlError.js';
3
3
  /**
4
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
5
+ * no decorators, and Bun transforms them natively. uql bundles no transpiler, so the project's
6
6
  * loader reads the project's `tsconfig.json`. Registered for the process, never imported through: an
7
7
  * import of its own would load the config's `uql-orm` apart from the CLI's, whose objects the other misreads.
8
8
  */
9
9
  export declare function tsxApiFor(path: string, versions: {
10
10
  bun?: string;
11
- deno?: string;
12
11
  }): string | undefined;
13
12
  /**
14
13
  * 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.
14
+ * those, so only there does it point at a runtime that runs them: Bun or the project's tsx.
16
15
  */
17
16
  export declare function importFailure(path: string, cause: unknown, versions: {
18
17
  bun?: string;
19
- deno?: string;
20
18
  }, tsxApi: string | undefined): UqlUsageError;
21
19
  /** The config at `customPath`, or the first of {@link CONFIG_FILES} in the working directory; the CLI validates it. */
22
20
  export declare function loadConfig(customPath?: string): Promise<Config>;
@@ -5,12 +5,12 @@ import { pathToFileURL } from 'node:url';
5
5
  import { UqlUsageError } from '../util/uqlError.js';
6
6
  /**
7
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
8
+ * no decorators, and Bun transforms them natively. uql bundles no transpiler, so the project's
9
9
  * loader reads the project's `tsconfig.json`. Registered for the process, never imported through: an
10
10
  * import of its own would load the config's `uql-orm` apart from the CLI's, whose objects the other misreads.
11
11
  */
12
12
  export function tsxApiFor(path, versions) {
13
- if (!/\.[mc]?ts$/.test(path) || versions.bun || versions.deno) {
13
+ if (!/\.[mc]?ts$/.test(path) || versions.bun) {
14
14
  return undefined;
15
15
  }
16
16
  try {
@@ -36,11 +36,11 @@ async function importConfig(path) {
36
36
  }
37
37
  /**
38
38
  * 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.
39
+ * those, so only there does it point at a runtime that runs them: Bun or the project's tsx.
40
40
  */
41
41
  export function importFailure(path, cause, versions, tsxApi) {
42
42
  const message = cause instanceof Error ? cause.message : String(cause);
43
- const hint = tsxApi || versions.bun || versions.deno
43
+ const hint = tsxApi || versions.bun
44
44
  ? ''
45
45
  : '\nIf it reaches entity classes, their decorators need a runtime that transforms TypeScript, not ' +
46
46
  '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, targetKeyColumns, 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';
@@ -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
@@ -1,7 +1,7 @@
1
1
  import { assertSoleId, getMeta, idOf, namesKey, relationOf, soleIdOf } from '../entity/index.js';
2
2
  import { namesRows } from '../dialect/operators.js';
3
3
  import { parseQueryLock } from '../type/index.js';
4
- import { cascadesOnDelete, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, hasKeys, holdsForeignKey, getRelationRequestSummary, guardWrite, idOnlyQuery, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetKeyColumns, whereEach, whereIds, whereKeysIn, whereWith, withoutSoftDeleteFilter, } from '../util/index.js';
4
+ import { childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, forEachRequestedRelation, getKeys, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetKeyColumns, whereEach, whereIds, whereKeysIn, whereWith, withoutSoftDeleteFilter, cascadingRelations, holdsForeignKey, } from '../util/index.js';
5
5
  import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
6
6
  import { keysetRead } from './keyset.js';
7
7
  import { enrichError } from './queryError.js';
@@ -152,11 +152,12 @@ function pickFields(row, keys) {
152
152
  }
153
153
  /** Whether any payload writes a relation it cascades to, which makes the write several statements. */
154
154
  function writesRelations(meta, payloads) {
155
- return payloads.some((payload) => filterPersistableRelationKeys(meta, payload, 'persist').length > 0);
155
+ const keys = cascadingRelations(meta, 'persist');
156
+ return payloads.some((payload) => keys.some((key) => Object.hasOwn(payload, key)));
156
157
  }
157
- /** The relations a payload writes whose rows hold the parent's key: written after the parent, by its id. */
158
- function childRelationKeys(meta, payload) {
159
- return filterPersistableRelationKeys(meta, payload, 'persist').filter((relKey) => !holdsForeignKey(relationOf(meta, relKey)));
158
+ /** The relations a write cascades to whose rows hold the parent's key: written after the parent, by its id. */
159
+ function ownedRelations(meta) {
160
+ return cascadingRelations(meta, 'persist').filter((relKey) => !holdsForeignKey(relationOf(meta, relKey)));
160
161
  }
161
162
  /** A relation's value as the rows it lists: a to-many's list, a to-one's row, none for `null`. */
162
163
  function listedRows(value) {
@@ -174,11 +175,7 @@ const STREAM_HOLDS_QUERIER = 'a stream is reading on this querier: run the state
174
175
  /** Base class for all database queriers. */
175
176
  export class AbstractQuerier {
176
177
  extra;
177
- /**
178
- * Internal promise used to queue database operations.
179
- * This ensures that each operation is executed serially, preventing race conditions
180
- * and ensuring that the database connection is used safely across concurrent calls.
181
- */
178
+ /** The last task {@link serialize} queued, which the next one runs after. */
182
179
  taskQueue = Promise.resolve();
183
180
  /** The stream reading on the connection, from its first row asked for until its loop ends. */
184
181
  #stream;
@@ -204,9 +201,13 @@ export class AbstractQuerier {
204
201
  get connection() {
205
202
  return this;
206
203
  }
207
- /** The transaction the connection holds, which every querier on it reads. */
204
+ #connectionSlot;
205
+ /**
206
+ * The transaction the connection holds, which every querier on it reads: the querier's own where it owns
207
+ * its connection, and the shared session's otherwise, the one case the registry exists for.
208
+ */
208
209
  get #slot() {
209
- return slotOf(this.connection);
210
+ return (this.#connectionSlot ??= this.connection === this ? {} : slotOf(this.connection));
210
211
  }
211
212
  /** What every read is checked for before it runs, whichever backend runs it. */
212
213
  validateReadQuery(entity, q) {
@@ -463,7 +464,7 @@ export class AbstractQuerier {
463
464
  await this.writeHeldReferences(entity, [row]);
464
465
  fillOnFields(meta, [row], 'onUpdate');
465
466
  guardWrite(meta, [row], 'update');
466
- const relKeys = childRelationKeys(meta, row);
467
+ const relKeys = ownedRelations(meta).filter((key) => Object.hasOwn(row, key));
467
468
  const settles = !!relKeys.length || this.settlesWrite(entity, q);
468
469
  if (lockKey) {
469
470
  assertLockableUpdate(meta, q, settles);
@@ -639,7 +640,7 @@ export class AbstractQuerier {
639
640
  }
640
641
  async deleteRows(entity, q, opts) {
641
642
  const meta = getMeta(entity);
642
- const cascades = cascadesOnDelete(meta);
643
+ const cascades = cascadingRelations(meta, 'delete').length > 0;
643
644
  const watched = this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
644
645
  if (!watched && !cascades && !this.settlesWrite(entity, q)) {
645
646
  return this.internalDeleteMany(entity, q, opts);
@@ -726,7 +727,7 @@ export class AbstractQuerier {
726
727
  */
727
728
  async writeHeldReferences(entity, rows) {
728
729
  const meta = getMeta(entity);
729
- for (const relKey of filterPersistableRelationKeys(meta, meta.relations, 'persist')) {
730
+ for (const relKey of cascadingRelations(meta, 'persist')) {
730
731
  const relOpts = relationOf(meta, relKey);
731
732
  const holding = rows.filter((row) => row[relKey] !== undefined);
732
733
  if (!holdsForeignKey(relOpts) || !holding.length) {
@@ -748,7 +749,7 @@ export class AbstractQuerier {
748
749
  async insertChildren(entity, rows) {
749
750
  const meta = getMeta(entity);
750
751
  const [idKey] = meta.ids;
751
- for (const relKey of childRelationKeys(meta, meta.relations)) {
752
+ for (const relKey of ownedRelations(meta)) {
752
753
  const writes = rows.flatMap((row) => (row[relKey] == null ? [] : [{ id: row[idKey], value: row[relKey] }]));
753
754
  if (writes.length) {
754
755
  assertSoleId(meta, 'saving a relation');
@@ -829,7 +830,7 @@ export class AbstractQuerier {
829
830
  async deleteChildren(entity, ids, opts) {
830
831
  const meta = getMeta(entity);
831
832
  const soft = !!meta.softDelete && !opts?.hardDelete;
832
- for (const relKey of filterPersistableRelationKeys(meta, meta.relations, 'delete')) {
833
+ for (const relKey of cascadingRelations(meta, 'delete')) {
833
834
  const relOpts = relationOf(meta, relKey);
834
835
  const target = relOpts.through ? relOpts.through() : relOpts.entity();
835
836
  if (soft && !getMeta(target).softDelete) {
@@ -57,7 +57,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
57
57
  * so those count apart.
58
58
  */
59
59
  protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
60
+ /** The rows a read of `entity` matches, each as its statement reads it. */
60
61
  private selectRows;
62
+ /** The rows of a read the dialect builds, each as the terms it returns say. */
63
+ private readRows;
61
64
  /**
62
65
  * The one read not going through `all`, so it checks its budget and connects on its own; its values go as
63
66
  * the context holds them, each normalized as it was bound. The tuning is guarded as `selectRows` says.
@@ -69,19 +72,6 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
69
72
  * closes itself when the loop exits early.
70
73
  */
71
74
  protected internalStream(query: string, values?: unknown[]): AsyncIterable<RawRow>;
72
- /**
73
- * How each row of one statement becomes the entity's, for a read, a stream and a to-many alike: its dotted
74
- * columns nested as the first row names them, and its values decoded as `hydratableFields` says, resolved
75
- * once. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
76
- */
77
- private rowReader;
78
- /**
79
- * One row of {@link rowReader}. A related row arrives as its parent's statement read it: a to-one
80
- * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
81
- * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
82
- * Each is an object of its own, so the walk reaches none twice.
83
- */
84
- private hydrateFields;
85
75
  /**
86
76
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
87
77
  * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`