uql-orm 0.102.7 → 0.103.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cockroachdb/crdbQuerierPool.d.ts +2 -2
- package/dist/context/context.d.ts +0 -6
- package/dist/context/context.js +1 -7
- package/dist/d1/d1QuerierPool.d.ts +0 -1
- package/dist/d1/d1QuerierPool.js +0 -1
- package/dist/dialect/abstractSqlDialect.d.ts +2 -2
- package/dist/dialect/abstractSqlDialect.js +4 -4
- package/dist/mssql/mssqlDialect.js +2 -2
- package/dist/neon/neonQuerier.d.ts +10 -10
- package/dist/neon/neonQuerier.js +5 -10
- package/dist/neon/neonQuerierPool.d.ts +9 -9
- package/dist/neon/neonQuerierPool.js +36 -12
- package/dist/postgres/abstractPgQuerierPool.d.ts +6 -6
- package/dist/postgres/pgQuerier.d.ts +5 -5
- package/dist/postgres/pgQuerier.js +2 -2
- package/dist/postgres/pgQuerierPool.d.ts +2 -2
- package/dist/querier/abstractQuerierPool.d.ts +2 -4
- package/dist/querier/abstractQuerierPool.js +2 -0
- package/dist/querier/abstractSqlQuerier.d.ts +9 -7
- package/dist/querier/abstractSqlQuerier.js +24 -20
- package/dist/querier/transaction.js +1 -1
- package/dist/turso/tursoQuerierPool.d.ts +0 -2
- package/dist/turso/tursoQuerierPool.js +0 -2
- package/dist/util/asyncScope.d.ts +11 -0
- package/dist/util/asyncScope.js +29 -0
- package/dist/util/sql.util.d.ts +4 -2
- package/dist/util/sql.util.js +4 -2
- package/package.json +4 -7
- package/skills/uql-orm/SKILL.md +57 -43
- package/dist/context/context.browser.d.ts +0 -12
- package/dist/context/context.browser.js +0 -33
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
import { Pool, type
|
|
1
|
+
import { Pool, type PoolConfig } from 'pg';
|
|
2
2
|
import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
|
|
3
3
|
import type { ExtraOptions } from '../type/index.js';
|
|
4
4
|
import { CockroachDialect } from './cockroachDialect.js';
|
|
5
5
|
/**
|
|
6
6
|
* QuerierPool for CockroachDB using the `pg` driver Pool.
|
|
7
7
|
*/
|
|
8
|
-
export declare class CrdbQuerierPool extends AbstractPgQuerierPool<
|
|
8
|
+
export declare class CrdbQuerierPool extends AbstractPgQuerierPool<CockroachDialect> {
|
|
9
9
|
readonly pool: Pool;
|
|
10
10
|
constructor(opts: PoolConfig, extra?: ExtraOptions);
|
|
11
11
|
}
|
|
@@ -1,12 +1,6 @@
|
|
|
1
1
|
import type { UqlContext } from '../type/index.js';
|
|
2
|
-
/** A value held for the active async flow, across `await`s: the browser build keeps it for synchronous callbacks only. */
|
|
3
|
-
export declare function asyncScope<T>(): {
|
|
4
|
-
run<R>(value: T, callback: () => R): R;
|
|
5
|
-
get(): T | undefined;
|
|
6
|
-
};
|
|
7
2
|
/**
|
|
8
3
|
* Runs `callback` with a {@link UqlContext} parameterized filters read, across `await`s and transactions.
|
|
9
|
-
* The browser build keeps the API without `node:async_hooks`.
|
|
10
4
|
* @example `await withContext({ tenantId }, () => querier.findMany(Invoice, {}))`
|
|
11
5
|
*/
|
|
12
6
|
export declare function withContext<T>(context: UqlContext, callback: () => T): T;
|
package/dist/context/context.js
CHANGED
|
@@ -1,14 +1,8 @@
|
|
|
1
|
-
import {
|
|
2
|
-
/** A value held for the active async flow, across `await`s: the browser build keeps it for synchronous callbacks only. */
|
|
3
|
-
export function asyncScope() {
|
|
4
|
-
const storage = new AsyncLocalStorage();
|
|
5
|
-
return { run: (value, callback) => storage.run(value, callback), get: () => storage.getStore() };
|
|
6
|
-
}
|
|
1
|
+
import { asyncScope } from '../util/asyncScope.js';
|
|
7
2
|
/** Holds the current {@link UqlContext} for the active async flow (per request/transaction). */
|
|
8
3
|
const contextScope = asyncScope();
|
|
9
4
|
/**
|
|
10
5
|
* Runs `callback` with a {@link UqlContext} parameterized filters read, across `await`s and transactions.
|
|
11
|
-
* The browser build keeps the API without `node:async_hooks`.
|
|
12
6
|
* @example `await withContext({ tenantId }, () => querier.findMany(Invoice, {}))`
|
|
13
7
|
*/
|
|
14
8
|
export function withContext(context, callback) {
|
package/dist/d1/d1QuerierPool.js
CHANGED
|
@@ -160,7 +160,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
160
160
|
*/
|
|
161
161
|
normalizeValue(value: unknown): unknown;
|
|
162
162
|
placeholder(_index: number): string;
|
|
163
|
-
/** `RETURNING <id column
|
|
163
|
+
/** `RETURNING <id column>` as {@link RETURNED_ID}, or nothing on a composite key, whose every column the payload already names. */
|
|
164
164
|
returningId<E>(meta: EntityMeta<E>): string;
|
|
165
165
|
/**
|
|
166
166
|
* ` RETURNING` the fields `keys` names, after an `UPDATE` or `DELETE` this context holds, projected and read as
|
|
@@ -169,7 +169,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
|
|
|
169
169
|
returning<E>(ctx: QueryContext, entity: Type<E>, keys: readonly FieldKey<E>[]): readonly SelectTerm[];
|
|
170
170
|
/** What the returned row is read off, for an engine that names it: SQL Server's `INSERTED.`. */
|
|
171
171
|
protected readonly returnedRowPrefix: string;
|
|
172
|
-
/** `<id column> AS
|
|
172
|
+
/** `<id column> AS` {@link RETURNED_ID} on its own, for a statement composing a `RETURNING` list of several items. */
|
|
173
173
|
protected returningIdExpression<E>(meta: EntityMeta<E>): string;
|
|
174
174
|
search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: ReadOptions, joins?: QueryJoins, order?: readonly SortRef[]): void;
|
|
175
175
|
/**
|
|
@@ -3,7 +3,7 @@ import { soleId, valueFieldOf } from '../entity/metadata/definition.js';
|
|
|
3
3
|
import { COUNT_RESULT_KEY, parseQueryLock, QuerySql, RAW_ALIAS, } from '../type/index.js';
|
|
4
4
|
import { utcTimestamp } from '../util/date.js';
|
|
5
5
|
import { ancestorPaths, isExactDecimal, isInlinedExpression, jsonPathKeys } from '../util/field.util.js';
|
|
6
|
-
import { isAutoIncrement, isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, deletionOf, hasKeys, idOnlyQuery, keySet, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, foldJson, writesKeys, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, columnRef, throwUnknownAggregateColumn, upsertAssigned, } from '../util/index.js';
|
|
6
|
+
import { isAutoIncrement, RETURNED_ID, isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, deletionOf, hasKeys, idOnlyQuery, keySet, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, foldJson, writesKeys, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, columnRef, throwUnknownAggregateColumn, upsertAssigned, } from '../util/index.js';
|
|
7
7
|
import { cachedIn, isJsonScalar } from '../util/object.util.js';
|
|
8
8
|
import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
|
|
9
9
|
import { kindOf, UqlUsageError } from '../util/uqlError.js';
|
|
@@ -207,7 +207,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
207
207
|
placeholder(_index) {
|
|
208
208
|
return '?';
|
|
209
209
|
}
|
|
210
|
-
/** `RETURNING <id column
|
|
210
|
+
/** `RETURNING <id column>` as {@link RETURNED_ID}, or nothing on a composite key, whose every column the payload already names. */
|
|
211
211
|
returningId(meta) {
|
|
212
212
|
const expression = this.returningIdExpression(meta);
|
|
213
213
|
return expression ? `RETURNING ${expression}` : '';
|
|
@@ -223,11 +223,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
|
|
|
223
223
|
}
|
|
224
224
|
/** What the returned row is read off, for an engine that names it: SQL Server's `INSERTED.`. */
|
|
225
225
|
returnedRowPrefix = '';
|
|
226
|
-
/** `<id column> AS
|
|
226
|
+
/** `<id column> AS` {@link RETURNED_ID} on its own, for a statement composing a `RETURNING` list of several items. */
|
|
227
227
|
returningIdExpression(meta) {
|
|
228
228
|
const [idKey] = meta.ids;
|
|
229
229
|
return meta.ids.length === 1
|
|
230
|
-
? `${this.returnedRowPrefix}${this.escapedColumnName(meta, idKey)} ${this.escapeId(
|
|
230
|
+
? `${this.returnedRowPrefix}${this.escapedColumnName(meta, idKey)} ${this.escapeId(RETURNED_ID)}`
|
|
231
231
|
: '';
|
|
232
232
|
}
|
|
233
233
|
search(ctx, entity, q = {}, opts = {}, joins = NO_JOINS, order) {
|
|
@@ -10,7 +10,7 @@ import { QuerySql } from '../type/index.js';
|
|
|
10
10
|
import { parseQueryLock } from '../type/index.js';
|
|
11
11
|
import { bytesToHex } from '../util/bytes.js';
|
|
12
12
|
import { isAutoIncrement, isExactDecimal, jsonPathKeys } from '../util/field.util.js';
|
|
13
|
-
import { assertNonNegativeInteger, isOperatorMap } from '../util/index.js';
|
|
13
|
+
import { assertNonNegativeInteger, isOperatorMap, RETURNED_ID } from '../util/index.js';
|
|
14
14
|
import { escapeSingleQuotes } from '../util/sqlLiteral.js';
|
|
15
15
|
import { UqlUsageError } from '../util/uqlError.js';
|
|
16
16
|
/** What SQL Server has. */
|
|
@@ -206,7 +206,7 @@ export class MsSqlDialect extends MergeSqlDialect {
|
|
|
206
206
|
*/
|
|
207
207
|
writeRows(ctx, meta, payload, write) {
|
|
208
208
|
const id = soleId(meta);
|
|
209
|
-
const column = this.escapeId(
|
|
209
|
+
const column = this.escapeId(RETURNED_ID);
|
|
210
210
|
const identity = this.identityInsertTarget(meta, payload);
|
|
211
211
|
if (id) {
|
|
212
212
|
ctx.append(`DECLARE ${OUTPUT_TABLE} TABLE (${column} ${canonicalToSql(resolveColumnCanonicalType(id.field), this)}); `);
|
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
import
|
|
2
|
-
import { PgQuerier } from '../postgres/pgQuerier.js';
|
|
1
|
+
import { type PgAnyClient, PgQuerier } from '../postgres/pgQuerier.js';
|
|
3
2
|
import type { BoundStatement } from '../querier/index.js';
|
|
4
3
|
import type { ExtraOptions, TransactionOptions } from '../type/index.js';
|
|
5
4
|
import type { SqlExecution } from '../util/sql.util.js';
|
|
6
5
|
import type { NeonDialect } from './neonDialect.js';
|
|
7
|
-
/** Neon
|
|
8
|
-
export type NeonHttp =
|
|
6
|
+
/** Neon over HTTP, what a statement goes through outside a session: one statement, or a list as one transaction. */
|
|
7
|
+
export type NeonHttp = {
|
|
8
|
+
query(sql: string, values?: unknown[]): Promise<SqlExecution>;
|
|
9
|
+
transaction(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
|
|
10
|
+
};
|
|
9
11
|
/**
|
|
10
12
|
* Querier for Neon, over HTTP first: a statement is one request, and a list one request running it as a
|
|
11
|
-
* transaction. A WebSocket session,
|
|
12
|
-
*
|
|
13
|
-
* `types` itself, since `neon()` ignores them, so a row decodes as it does over the session.
|
|
13
|
+
* transaction. A WebSocket session, opened for what one request cannot hold (a transaction a callback runs in, a
|
|
14
|
+
* stream's loop), serves the querier until it is released.
|
|
14
15
|
*/
|
|
15
|
-
export declare class NeonQuerier extends PgQuerier
|
|
16
|
+
export declare class NeonQuerier extends PgQuerier {
|
|
16
17
|
private readonly http;
|
|
17
|
-
|
|
18
|
-
constructor(http: NeonHttp, types: CustomTypesConfig, connect: () => Promise<PoolClient>, dialect: NeonDialect, extra?: ExtraOptions);
|
|
18
|
+
constructor(http: NeonHttp, connect: () => Promise<PgAnyClient>, dialect: NeonDialect, extra?: ExtraOptions);
|
|
19
19
|
/** Connects nothing: a statement goes over HTTP until a session holds the connection. */
|
|
20
20
|
protected lazyConnect(): Promise<void>;
|
|
21
21
|
protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
|
package/dist/neon/neonQuerier.js
CHANGED
|
@@ -1,18 +1,14 @@
|
|
|
1
|
-
import { pgExecution } from '../postgres/pgExecution.js';
|
|
2
1
|
import { PgQuerier } from '../postgres/pgQuerier.js';
|
|
3
2
|
/**
|
|
4
3
|
* Querier for Neon, over HTTP first: a statement is one request, and a list one request running it as a
|
|
5
|
-
* transaction. A WebSocket session,
|
|
6
|
-
*
|
|
7
|
-
* `types` itself, since `neon()` ignores them, so a row decodes as it does over the session.
|
|
4
|
+
* transaction. A WebSocket session, opened for what one request cannot hold (a transaction a callback runs in, a
|
|
5
|
+
* stream's loop), serves the querier until it is released.
|
|
8
6
|
*/
|
|
9
7
|
export class NeonQuerier extends PgQuerier {
|
|
10
8
|
http;
|
|
11
|
-
|
|
12
|
-
constructor(http, types, connect, dialect, extra) {
|
|
9
|
+
constructor(http, connect, dialect, extra) {
|
|
13
10
|
super(connect, dialect, extra);
|
|
14
11
|
this.http = http;
|
|
15
|
-
this.types = types;
|
|
16
12
|
}
|
|
17
13
|
/** Connects nothing: a statement goes over HTTP until a session holds the connection. */
|
|
18
14
|
async lazyConnect() {
|
|
@@ -22,7 +18,7 @@ export class NeonQuerier extends PgQuerier {
|
|
|
22
18
|
if (this.conn) {
|
|
23
19
|
return super.execute(sql, values);
|
|
24
20
|
}
|
|
25
|
-
return
|
|
21
|
+
return this.http.query(sql, values);
|
|
26
22
|
}
|
|
27
23
|
/** A list as one HTTP transaction, all or none; inside an open transaction, in turn on its session, which it joins. */
|
|
28
24
|
async executeBatch(statements) {
|
|
@@ -33,8 +29,7 @@ export class NeonQuerier extends PgQuerier {
|
|
|
33
29
|
}
|
|
34
30
|
return results;
|
|
35
31
|
}
|
|
36
|
-
|
|
37
|
-
return results.map(pgExecution);
|
|
32
|
+
return this.http.transaction(statements);
|
|
38
33
|
}
|
|
39
34
|
async openTransaction(opts) {
|
|
40
35
|
await super.lazyConnect();
|
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
|
|
1
|
+
import { type ClientConfig } from '@neondatabase/serverless';
|
|
3
2
|
import { PgQuerier } from '../postgres/pgQuerier.js';
|
|
3
|
+
import { AbstractSqlQuerierPool } from '../querier/index.js';
|
|
4
4
|
import type { ExtraOptions } from '../type/index.js';
|
|
5
5
|
import { NeonDialect } from './neonDialect.js';
|
|
6
6
|
import { NeonQuerier } from './neonQuerier.js';
|
|
7
7
|
/**
|
|
8
|
-
* Pool for Neon
|
|
9
|
-
*
|
|
10
|
-
* is the session's.
|
|
8
|
+
* Pool for Neon that holds no connection: its queriers send statements and lists over HTTP, and open a WebSocket
|
|
9
|
+
* session of their own only for a transaction or a stream, which their release ends. So one pool serves every
|
|
10
|
+
* request of an edge isolate. A migration runs on a session throughout, since its lock is the session's.
|
|
11
|
+
* [The design](../../../../architecture/split-writes.md).
|
|
11
12
|
*/
|
|
12
|
-
export declare class NeonQuerierPool extends
|
|
13
|
+
export declare class NeonQuerierPool extends AbstractSqlQuerierPool<PgQuerier, NeonDialect> {
|
|
13
14
|
#private;
|
|
14
|
-
|
|
15
|
-
constructor(opts: PoolConfig, extra?: ExtraOptions);
|
|
15
|
+
constructor(opts: ClientConfig, extra?: ExtraOptions);
|
|
16
16
|
getQuerier(): Promise<NeonQuerier>;
|
|
17
|
-
getMigrationQuerier(): Promise<PgQuerier
|
|
17
|
+
getMigrationQuerier(): Promise<PgQuerier>;
|
|
18
18
|
}
|
|
@@ -1,30 +1,54 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Client, neon, types } from '@neondatabase/serverless';
|
|
2
2
|
import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
|
|
3
|
-
import {
|
|
3
|
+
import { pgExecution } from '../postgres/pgExecution.js';
|
|
4
4
|
import { PgQuerier } from '../postgres/pgQuerier.js';
|
|
5
5
|
import { wireTypes } from '../postgres/pgWireTypes.js';
|
|
6
|
+
import { AbstractSqlQuerierPool } from '../querier/index.js';
|
|
6
7
|
import { NeonDialect } from './neonDialect.js';
|
|
7
8
|
import { NeonQuerier } from './neonQuerier.js';
|
|
9
|
+
const ignoreError = () => { };
|
|
8
10
|
/**
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* is the session's. [The design](../../../../architecture/split-writes.md).
|
|
11
|
+
* A WebSocket session of one querier's own, ended where a pooled client would be handed back. A socket error while
|
|
12
|
+
* it closes is heard and dropped, as `pg-pool` hears one on a client it holds, rather than reaching no listener.
|
|
12
13
|
*/
|
|
13
|
-
|
|
14
|
+
class NeonSession extends Client {
|
|
15
|
+
release() {
|
|
16
|
+
this.on('error', ignoreError);
|
|
17
|
+
return this.end();
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Pool for Neon that holds no connection: its queriers send statements and lists over HTTP, and open a WebSocket
|
|
22
|
+
* session of their own only for a transaction or a stream, which their release ends. So one pool serves every
|
|
23
|
+
* request of an edge isolate. A migration runs on a session throughout, since its lock is the session's.
|
|
24
|
+
* [The design](../../../../architecture/split-writes.md).
|
|
25
|
+
*/
|
|
26
|
+
export class NeonQuerierPool extends AbstractSqlQuerierPool {
|
|
14
27
|
#http;
|
|
15
|
-
#
|
|
28
|
+
#config;
|
|
16
29
|
constructor(opts, extra) {
|
|
30
|
+
super(new NeonDialect(dialectOptionsFrom(extra)), extra);
|
|
17
31
|
// Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
|
|
18
32
|
const wire = opts.types ?? wireTypes(types);
|
|
19
|
-
|
|
33
|
+
this.#config = { ...opts, types: wire };
|
|
20
34
|
const { connectionString, host, port, user, password, database } = opts;
|
|
21
|
-
|
|
22
|
-
|
|
35
|
+
const http = neon({ connectionString, host, port, user, password, database, fullResults: true });
|
|
36
|
+
// Each query passes the wire types itself, since `neon()` ignores them, so a row decodes as over a session.
|
|
37
|
+
const query = (sql, values) => http.query(sql, values, { types: wire });
|
|
38
|
+
this.#http = {
|
|
39
|
+
query: async (sql, values) => pgExecution(await query(sql, values)),
|
|
40
|
+
transaction: async (statements) => (await http.transaction(statements.map(({ sql, values }) => query(sql, values)))).map(pgExecution),
|
|
41
|
+
};
|
|
23
42
|
}
|
|
24
43
|
async getQuerier() {
|
|
25
|
-
return new NeonQuerier(this.#http,
|
|
44
|
+
return new NeonQuerier(this.#http, () => this.#session(), this.dialect, this.extra);
|
|
26
45
|
}
|
|
27
46
|
async getMigrationQuerier() {
|
|
28
|
-
return new PgQuerier(() => this
|
|
47
|
+
return new PgQuerier(() => this.#session(), this.dialect, this.extra);
|
|
48
|
+
}
|
|
49
|
+
async #session() {
|
|
50
|
+
const session = new NeonSession(this.#config);
|
|
51
|
+
await session.connect();
|
|
52
|
+
return session;
|
|
29
53
|
}
|
|
30
54
|
}
|
|
@@ -2,15 +2,15 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
|
|
|
2
2
|
import { AbstractSqlQuerierPool } from '../querier/index.js';
|
|
3
3
|
import type { ExtraOptions } from '../type/index.js';
|
|
4
4
|
import { type PgAnyClient, PgQuerier } from './pgQuerier.js';
|
|
5
|
-
export interface PgAnyPool
|
|
6
|
-
connect: () => Promise<
|
|
5
|
+
export interface PgAnyPool {
|
|
6
|
+
connect: () => Promise<PgAnyClient>;
|
|
7
7
|
end: () => Promise<void>;
|
|
8
8
|
on(event: 'error', listener: (err: Error) => void): unknown;
|
|
9
9
|
}
|
|
10
10
|
/** A Postgres-wire pool of {@link PgQuerier}s, attaching the error handler that keeps a dropped connection from crashing the process. */
|
|
11
|
-
export declare abstract class AbstractPgQuerierPool<
|
|
12
|
-
readonly pool: PgAnyPool
|
|
13
|
-
constructor(dialect: D, pool: PgAnyPool
|
|
14
|
-
getQuerier(): Promise<PgQuerier
|
|
11
|
+
export declare abstract class AbstractPgQuerierPool<D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<PgQuerier, D> {
|
|
12
|
+
readonly pool: PgAnyPool;
|
|
13
|
+
constructor(dialect: D, pool: PgAnyPool, extra?: ExtraOptions);
|
|
14
|
+
getQuerier(): Promise<PgQuerier>;
|
|
15
15
|
end(): Promise<void>;
|
|
16
16
|
}
|
|
@@ -11,15 +11,15 @@ export interface PgAnyClient {
|
|
|
11
11
|
}
|
|
12
12
|
/**
|
|
13
13
|
* Querier for every client with node-postgres' API: `pg` itself, for Postgres and CockroachDB, and
|
|
14
|
-
* Neon's serverless driver
|
|
14
|
+
* Neon's serverless driver; the dialect is whichever the pool built.
|
|
15
15
|
*/
|
|
16
|
-
export declare class PgQuerier
|
|
16
|
+
export declare class PgQuerier extends AbstractPoolQuerier<PgAnyClient> {
|
|
17
17
|
/**
|
|
18
18
|
* A client the server drops while held emits `error` with no statement to report it to, which unheard ends
|
|
19
|
-
* the process: the querier hears it while it holds the client,
|
|
19
|
+
* the process: the querier hears it while it holds the client, and what it hands the client back to after it.
|
|
20
20
|
*/
|
|
21
|
-
protected acquired(conn:
|
|
21
|
+
protected acquired(conn: PgAnyClient): PgAnyClient;
|
|
22
22
|
protected execute(sql: string, values?: unknown[]): Promise<import("../util/sql.util.js").SqlExecution>;
|
|
23
23
|
internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
|
|
24
|
-
protected releaseConn(conn:
|
|
24
|
+
protected releaseConn(conn: PgAnyClient, discard: boolean): Promise<void>;
|
|
25
25
|
}
|
|
@@ -3,12 +3,12 @@ import { pgExecution } from './pgExecution.js';
|
|
|
3
3
|
const ignoreError = () => { };
|
|
4
4
|
/**
|
|
5
5
|
* Querier for every client with node-postgres' API: `pg` itself, for Postgres and CockroachDB, and
|
|
6
|
-
* Neon's serverless driver
|
|
6
|
+
* Neon's serverless driver; the dialect is whichever the pool built.
|
|
7
7
|
*/
|
|
8
8
|
export class PgQuerier extends AbstractPoolQuerier {
|
|
9
9
|
/**
|
|
10
10
|
* A client the server drops while held emits `error` with no statement to report it to, which unheard ends
|
|
11
|
-
* the process: the querier hears it while it holds the client,
|
|
11
|
+
* the process: the querier hears it while it holds the client, and what it hands the client back to after it.
|
|
12
12
|
*/
|
|
13
13
|
acquired(conn) {
|
|
14
14
|
conn.on('error', ignoreError);
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { Pool, type
|
|
1
|
+
import { Pool, type PoolConfig } from 'pg';
|
|
2
2
|
import type { ExtraOptions } from '../type/index.js';
|
|
3
3
|
import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
|
|
4
4
|
import { PostgresDialect } from './postgresDialect.js';
|
|
5
|
-
export declare class PgQuerierPool extends AbstractPgQuerierPool<
|
|
5
|
+
export declare class PgQuerierPool extends AbstractPgQuerierPool<PostgresDialect> {
|
|
6
6
|
readonly pool: Pool;
|
|
7
7
|
constructor(opts: PoolConfig, extra?: ExtraOptions);
|
|
8
8
|
}
|
|
@@ -50,8 +50,6 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
|
|
|
50
50
|
readonly deleteMany: UniversalQuerier['deleteMany'];
|
|
51
51
|
readonly restoreOneById: UniversalQuerier['restoreOneById'];
|
|
52
52
|
readonly restoreMany: UniversalQuerier['restoreMany'];
|
|
53
|
-
/**
|
|
54
|
-
|
|
55
|
-
*/
|
|
56
|
-
abstract end(): Promise<void>;
|
|
53
|
+
/** Closes what the pool holds: nothing where each querier closes its own connection, or there is none to close. */
|
|
54
|
+
end(): Promise<void>;
|
|
57
55
|
}
|
|
@@ -142,4 +142,6 @@ export class AbstractQuerierPool {
|
|
|
142
142
|
deleteMany = (...args) => this.withQuerier((querier) => querier.deleteMany(...args));
|
|
143
143
|
restoreOneById = (...args) => this.withQuerier((querier) => querier.restoreOneById(...args));
|
|
144
144
|
restoreMany = (...args) => this.withQuerier((querier) => querier.restoreMany(...args));
|
|
145
|
+
/** Closes what the pool holds: nothing where each querier closes its own connection, or there is none to close. */
|
|
146
|
+
async end() { }
|
|
145
147
|
}
|
|
@@ -55,12 +55,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
|
|
|
55
55
|
private rowsOf;
|
|
56
56
|
/** What the write `build` writes reports. */
|
|
57
57
|
private changesOf;
|
|
58
|
-
/**
|
|
59
|
-
* The `SET`s tuning an ANN index for the query, leading its read, refused where they would apply to nothing: a
|
|
60
|
-
* `SET LOCAL` outside a transaction. None for a query with no vector search, or on a field with no ANN index,
|
|
61
|
-
* which then demands no transaction either.
|
|
62
|
-
*/
|
|
58
|
+
/** The `SET`s tuning an ANN index for the query, leading its read: none without a vector search or an ANN index. */
|
|
63
59
|
private vectorTuning;
|
|
60
|
+
/** Whether `tuning` applies only inside a transaction, as a `SET LOCAL` does: a read opens one, or joins the open one. */
|
|
61
|
+
private tunedInTransaction;
|
|
64
62
|
protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
|
|
65
63
|
/** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
|
|
66
64
|
private countUnpaged;
|
|
@@ -70,13 +68,17 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
|
|
|
70
68
|
* so those count apart.
|
|
71
69
|
*/
|
|
72
70
|
protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
|
|
73
|
-
/**
|
|
71
|
+
/**
|
|
72
|
+
* The rows a read of `entity` matches, each as its statement reads it, the vector search's tuning leading it, in a
|
|
73
|
+
* transaction of its own where the tuning needs one and none is open.
|
|
74
|
+
*/
|
|
74
75
|
private selectRows;
|
|
75
76
|
/** The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. */
|
|
76
77
|
private readRows;
|
|
77
78
|
/**
|
|
78
79
|
* The one read not going through `runStatements`: it holds the connection for its loop, so it checks its budget
|
|
79
|
-
* and connects on its own, its values going as the context holds them, each normalized as it was bound.
|
|
80
|
+
* and connects on its own, its values going as the context holds them, each normalized as it was bound. Tuning
|
|
81
|
+
* that needs a transaction is refused outside one, which would otherwise stay open for the whole loop.
|
|
80
82
|
*/
|
|
81
83
|
protected internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<Awaited<E>, void, unknown>;
|
|
82
84
|
/**
|
|
@@ -153,20 +153,16 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
153
153
|
const [result] = await this.runStatements([this.bound(build)]);
|
|
154
154
|
return this.updateResultOf(result);
|
|
155
155
|
}
|
|
156
|
-
/**
|
|
157
|
-
* The `SET`s tuning an ANN index for the query, leading its read, refused where they would apply to nothing: a
|
|
158
|
-
* `SET LOCAL` outside a transaction. None for a query with no vector search, or on a field with no ANN index,
|
|
159
|
-
* which then demands no transaction either.
|
|
160
|
-
*/
|
|
156
|
+
/** The `SET`s tuning an ANN index for the query, leading its read: none without a vector search or an ANN index. */
|
|
161
157
|
vectorTuning(entity, q) {
|
|
162
158
|
if (q.$candidates === undefined) {
|
|
163
159
|
return [];
|
|
164
160
|
}
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
return
|
|
161
|
+
return this.dialect.vectorTuningStatements(getMeta(entity), q).map((sql) => ({ sql, values: [] }));
|
|
162
|
+
}
|
|
163
|
+
/** Whether `tuning` applies only inside a transaction, as a `SET LOCAL` does: a read opens one, or joins the open one. */
|
|
164
|
+
tunedInTransaction(tuning) {
|
|
165
|
+
return tuning.length > 0 && this.dialect.features.vectorTuningNeedsTransaction;
|
|
170
166
|
}
|
|
171
167
|
async internalFindMany(entity, q, opts) {
|
|
172
168
|
return this.selectRows(entity, q, opts);
|
|
@@ -194,29 +190,37 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
194
190
|
}
|
|
195
191
|
return [rows, total];
|
|
196
192
|
}
|
|
197
|
-
/**
|
|
193
|
+
/**
|
|
194
|
+
* The rows a read of `entity` matches, each as its statement reads it, the vector search's tuning leading it, in a
|
|
195
|
+
* transaction of its own where the tuning needs one and none is open.
|
|
196
|
+
*/
|
|
198
197
|
selectRows(entity, q, opts, totalAlias) {
|
|
199
198
|
const tuning = this.vectorTuning(entity, q);
|
|
200
|
-
|
|
199
|
+
const build = (ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias);
|
|
200
|
+
return this.readRows(build, tuning, this.tunedInTransaction(tuning));
|
|
201
201
|
}
|
|
202
202
|
/** The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. */
|
|
203
|
-
async readRows(build, leading = []) {
|
|
203
|
+
async readRows(build, leading = [], atomic = false) {
|
|
204
204
|
let terms = [];
|
|
205
205
|
const statement = this.bound((ctx) => {
|
|
206
206
|
terms = build(ctx);
|
|
207
207
|
});
|
|
208
|
-
const results = await this.runStatements([...leading, statement]);
|
|
208
|
+
const results = await this.runStatements([...leading, statement], atomic);
|
|
209
209
|
return results[leading.length].rows.map(rowReader(terms));
|
|
210
210
|
}
|
|
211
211
|
/**
|
|
212
212
|
* The one read not going through `runStatements`: it holds the connection for its loop, so it checks its budget
|
|
213
|
-
* and connects on its own, its values going as the context holds them, each normalized as it was bound.
|
|
213
|
+
* and connects on its own, its values going as the context holds them, each normalized as it was bound. Tuning
|
|
214
|
+
* that needs a transaction is refused outside one, which would otherwise stay open for the whole loop.
|
|
214
215
|
*/
|
|
215
216
|
async *internalFindManyStream(entity, q, opts) {
|
|
217
|
+
const tuning = this.vectorTuning(entity, q);
|
|
218
|
+
if (this.tunedInTransaction(tuning) && !this.scopeHere()) {
|
|
219
|
+
throw new UqlUsageError(`a streamed $candidates needs an open transaction on ${this.dialect.engineName}; run the stream inside pool.transaction(...)`);
|
|
220
|
+
}
|
|
216
221
|
const ctx = this.dialect.createContext();
|
|
217
222
|
const read = rowReader(this.dialect.find(ctx, entity, q, opts));
|
|
218
223
|
this.assertBindBudget(ctx.values);
|
|
219
|
-
const tuning = this.vectorTuning(entity, q);
|
|
220
224
|
await this.lazyConnect();
|
|
221
225
|
for (const { sql } of tuning) {
|
|
222
226
|
await this.timed(sql, undefined, () => this.execute(sql));
|
|
@@ -288,7 +292,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
288
292
|
results.forEach((result, at) => {
|
|
289
293
|
const { indexes, idsReliable } = statements[at];
|
|
290
294
|
if (idsReliable) {
|
|
291
|
-
const { ids
|
|
295
|
+
const { ids } = this.updateResultOf(result);
|
|
292
296
|
indexes.forEach((index, position) => {
|
|
293
297
|
rows[index][idKey] ??= ids[position];
|
|
294
298
|
});
|
|
@@ -296,7 +300,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
296
300
|
});
|
|
297
301
|
}
|
|
298
302
|
async internalUpdateMany(entity, q, payload, opts) {
|
|
299
|
-
const { changes
|
|
303
|
+
const { changes } = await this.changesOf((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
|
|
300
304
|
return changes;
|
|
301
305
|
}
|
|
302
306
|
/** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
|
|
@@ -354,12 +358,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
354
358
|
/** The ids an upsert reports of its rows: its `RETURNING` rows' in order, or its one row's in the header. */
|
|
355
359
|
reportedIds(result) {
|
|
356
360
|
if (result.rows.length) {
|
|
357
|
-
return this.updateResultOf(result).ids
|
|
361
|
+
return this.updateResultOf(result).ids;
|
|
358
362
|
}
|
|
359
363
|
return result.id ? [result.id] : [];
|
|
360
364
|
}
|
|
361
365
|
async internalDeleteMany(entity, q, opts) {
|
|
362
|
-
const { changes
|
|
366
|
+
const { changes } = await this.changesOf((ctx) => this.dialect.delete(ctx, entity, q, opts));
|
|
363
367
|
return changes;
|
|
364
368
|
}
|
|
365
369
|
async openTransaction(opts) {
|
|
@@ -13,6 +13,4 @@ export declare class TursoQuerierPool extends AbstractSqlQuerierPool<TursoSessio
|
|
|
13
13
|
private readonly conf;
|
|
14
14
|
constructor(conf: TursoConfig, extra?: ExtraOptions);
|
|
15
15
|
getQuerier(): Promise<TursoSessionQuerier>;
|
|
16
|
-
/** Nothing to close: every querier closes its own session. */
|
|
17
|
-
end(): Promise<void>;
|
|
18
16
|
}
|
|
@@ -16,6 +16,4 @@ export class TursoQuerierPool extends AbstractSqlQuerierPool {
|
|
|
16
16
|
const { Session } = await import('@tursodatabase/serverless');
|
|
17
17
|
return new TursoSessionQuerier(new Session(this.conf), this.dialect, this.extra);
|
|
18
18
|
}
|
|
19
|
-
/** Nothing to close: every querier closes its own session. */
|
|
20
|
-
async end() { }
|
|
21
19
|
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** A value held for a flow: set for the length of a callback, read anywhere inside it. */
|
|
2
|
+
type Scope<T> = {
|
|
3
|
+
run<R>(value: T, callback: () => R): R;
|
|
4
|
+
get(): T | undefined;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* A value held for the active async flow, across `await`s; in a browser, for a synchronous callback only, which
|
|
8
|
+
* is all it needs there, where filters never resolve.
|
|
9
|
+
*/
|
|
10
|
+
export declare function asyncScope<T>(): Scope<T>;
|
|
11
|
+
export {};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The runtime's `AsyncLocalStorage`, read when the module loads rather than imported, so no bundler sees a Node
|
|
3
|
+
* builtin: Node, Bun, Deno and Workers (`nodejs_compat`) have it, a browser does not.
|
|
4
|
+
*/
|
|
5
|
+
const RUNTIME_STORAGE = globalThis.process?.getBuiltinModule?.('node:async_hooks').AsyncLocalStorage;
|
|
6
|
+
/**
|
|
7
|
+
* A value held for the active async flow, across `await`s; in a browser, for a synchronous callback only, which
|
|
8
|
+
* is all it needs there, where filters never resolve.
|
|
9
|
+
*/
|
|
10
|
+
export function asyncScope() {
|
|
11
|
+
if (RUNTIME_STORAGE) {
|
|
12
|
+
const store = new RUNTIME_STORAGE();
|
|
13
|
+
return { run: (value, callback) => store.run(value, callback), get: () => store.getStore() };
|
|
14
|
+
}
|
|
15
|
+
let current;
|
|
16
|
+
return {
|
|
17
|
+
run: (value, callback) => {
|
|
18
|
+
const previous = current;
|
|
19
|
+
current = value;
|
|
20
|
+
try {
|
|
21
|
+
return callback();
|
|
22
|
+
}
|
|
23
|
+
finally {
|
|
24
|
+
current = previous;
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
get: () => current,
|
|
28
|
+
};
|
|
29
|
+
}
|
package/dist/util/sql.util.d.ts
CHANGED
|
@@ -54,6 +54,8 @@ export type SqlExecution = {
|
|
|
54
54
|
readonly changes?: number | null;
|
|
55
55
|
readonly id?: PrimaryKey;
|
|
56
56
|
};
|
|
57
|
+
/** The column a `RETURNING` reports ids under: uql's own statements alias the key to it, and a raw `run()` names it so. */
|
|
58
|
+
export declare const RETURNED_ID = "id";
|
|
57
59
|
/** A statement's result, and how its dialect reports inserted ids, to build a {@link QueryUpdateResult} from. */
|
|
58
60
|
export type BuildUpdateResultPayload = SqlExecution & {
|
|
59
61
|
readonly insertIdSource?: InsertIdSource;
|
|
@@ -65,10 +67,10 @@ export type BuildUpdateResultPayload = SqlExecution & {
|
|
|
65
67
|
};
|
|
66
68
|
/**
|
|
67
69
|
* A driver's result as a {@link QueryUpdateResult}: a statement returning rows counts them, which a driver's own
|
|
68
|
-
* count is not always (Hrana answers 0); `RETURNING` rows name their id
|
|
70
|
+
* count is not always (Hrana answers 0); `RETURNING` rows name their id {@link RETURNED_ID}; a MySQL header's first id is extended
|
|
69
71
|
* by the increment, which holds only where auto-increment allocation is contiguous (`innodb_autoinc_lock_mode` 0, 1).
|
|
70
72
|
*/
|
|
71
|
-
export declare function buildUpdateResult(payload: BuildUpdateResultPayload): QueryUpdateResult
|
|
73
|
+
export declare function buildUpdateResult(payload: BuildUpdateResultPayload): Required<QueryUpdateResult>;
|
|
72
74
|
/**
|
|
73
75
|
* Checks if a value is of a primary key type (string, number, or bigint).
|
|
74
76
|
*/
|
package/dist/util/sql.util.js
CHANGED
|
@@ -112,9 +112,11 @@ export function escapeSqlId(val, escapeIdChar = '`', forbidQualified, addDot) {
|
|
|
112
112
|
: `${escapeIdChar}${val.replaceAll(escapeIdChar, escapeIdChar + escapeIdChar)}${escapeIdChar}`;
|
|
113
113
|
return addDot ? `${escaped}.` : escaped;
|
|
114
114
|
}
|
|
115
|
+
/** The column a `RETURNING` reports ids under: uql's own statements alias the key to it, and a raw `run()` names it so. */
|
|
116
|
+
export const RETURNED_ID = 'id';
|
|
115
117
|
/**
|
|
116
118
|
* A driver's result as a {@link QueryUpdateResult}: a statement returning rows counts them, which a driver's own
|
|
117
|
-
* count is not always (Hrana answers 0); `RETURNING` rows name their id
|
|
119
|
+
* count is not always (Hrana answers 0); `RETURNING` rows name their id {@link RETURNED_ID}; a MySQL header's first id is extended
|
|
118
120
|
* by the increment, which holds only where auto-increment allocation is contiguous (`innodb_autoinc_lock_mode` 0, 1).
|
|
119
121
|
*/
|
|
120
122
|
export function buildUpdateResult(payload) {
|
|
@@ -125,7 +127,7 @@ export function buildUpdateResult(payload) {
|
|
|
125
127
|
// counts the rows (false for a MySQL upsert batch, whose querier reads ids back instead). `0` means none.
|
|
126
128
|
let ids = [];
|
|
127
129
|
if (rows.length) {
|
|
128
|
-
ids = rows.map((r) => r[
|
|
130
|
+
ids = rows.map((r) => r[RETURNED_ID]);
|
|
129
131
|
}
|
|
130
132
|
else if (insertIdSource !== 'returning' && isPrimaryKey(id) && id) {
|
|
131
133
|
if (typeof id === 'string') {
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"homepage": "https://uql-orm.dev",
|
|
4
4
|
"description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"version": "0.
|
|
6
|
+
"version": "0.103.1",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=22.18"
|
|
@@ -11,9 +11,6 @@
|
|
|
11
11
|
"sideEffects": false,
|
|
12
12
|
"main": "./dist/index.js",
|
|
13
13
|
"types": "./dist/index.d.ts",
|
|
14
|
-
"browser": {
|
|
15
|
-
"./dist/context/context.js": "./dist/context/context.browser.js"
|
|
16
|
-
},
|
|
17
14
|
"bin": {
|
|
18
15
|
"uql-migrate": "./dist/migrate/bin.js"
|
|
19
16
|
},
|
|
@@ -126,8 +123,8 @@
|
|
|
126
123
|
}
|
|
127
124
|
},
|
|
128
125
|
"devDependencies": {
|
|
129
|
-
"@electric-sql/pglite": "0.5.
|
|
130
|
-
"@electric-sql/pglite-pgvector": "0.0.
|
|
126
|
+
"@electric-sql/pglite": "0.5.11",
|
|
127
|
+
"@electric-sql/pglite-pgvector": "0.0.12",
|
|
131
128
|
"@libsql/client": "^0.18.0",
|
|
132
129
|
"@neondatabase/serverless": "^1.2.0",
|
|
133
130
|
"@nestjs/common": "^12.2.0",
|
|
@@ -144,7 +141,7 @@
|
|
|
144
141
|
"express": "^5.3.0",
|
|
145
142
|
"mariadb": "^3.5.4",
|
|
146
143
|
"mongodb": "^7.7.0",
|
|
147
|
-
"mssql": "^12.7.
|
|
144
|
+
"mssql": "^12.7.11",
|
|
148
145
|
"mysql2": "^3.24.6",
|
|
149
146
|
"pg": "^8.23.1",
|
|
150
147
|
"pg-query-stream": "^4.17.1",
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -12,7 +12,7 @@ description: >
|
|
|
12
12
|
|
|
13
13
|
Entities are classes. A query is a JSON object checked key by key against the entity, and it runs the same on every supported database. There is no schema file, no generated client and no query builder.
|
|
14
14
|
|
|
15
|
-
Full docs are Markdown: the index at https://uql-orm.dev/llms.txt, and each page at its URL plus `.md`. Read the page for the task before guessing an option.
|
|
15
|
+
Full docs are Markdown: the index at https://uql-orm.dev/llms.txt, and each page at its URL plus `.md`. Read the page for the task before guessing an option.
|
|
16
16
|
|
|
17
17
|
## Setup
|
|
18
18
|
|
|
@@ -20,11 +20,11 @@ Full docs are Markdown: the index at https://uql-orm.dev/llms.txt, and each page
|
|
|
20
20
|
npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client, ...
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
ESM only
|
|
23
|
+
ESM only. Needs Node 22.18+, Bun or an edge runtime, and TypeScript 5.7+.
|
|
24
24
|
|
|
25
|
-
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`.
|
|
25
|
+
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`. A project on legacy decorators (NestJS, Angular) keeps its config and defines entities with `defineEntity`: https://uql-orm.dev/entities/imperative.md
|
|
26
26
|
|
|
27
|
-
Node
|
|
27
|
+
Node runs no decorators natively yet, so add `tsx` there (`npm i -D tsx`); `uql-migrate` loads `uql.config.ts` through it. A bundler that minifies class names needs `@Entity({ name: 'todo' })`, since the table name defaults to the class name.
|
|
28
28
|
|
|
29
29
|
```ts
|
|
30
30
|
// uql.config.ts
|
|
@@ -72,22 +72,19 @@ export class Post {
|
|
|
72
72
|
}
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. The base needs no `@Entity()` unless it is a table.
|
|
76
|
-
- Every `@Field` states its `type`: `String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`. A foreign key takes `references` and inherits the target's type. A
|
|
77
|
-
- A column is nullable unless it says `nullable: false`. Its property must admit `null
|
|
78
|
-
-
|
|
79
|
-
- Declare a `nullable: false` column with `!` (`email!: string`). Declare `?` for anything an insert may omit: nullable, `onInsert`, `defaultValue`, `eager: false`, `computed` fields, and relations. A single-column key and a `version` are filled by uql.
|
|
75
|
+
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. The base needs no `@Entity()` unless it is a table.
|
|
76
|
+
- Every `@Field` states its `type`: `String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`. A foreign key takes `references` and inherits the target's type. A JSON column of no fixed shape is a bare `Json`.
|
|
77
|
+
- A column is nullable unless it says `nullable: false`. Its property must admit `null` (`title?: string | null`).
|
|
78
|
+
- Declare a `nullable: false` column with `!` (`email!: string`). Declare `?` for anything an insert may omit: nullable, `onInsert`, `defaultValue`, `eager: false`, computed fields and relations. uql fills a single-column key and a `version`.
|
|
80
79
|
- `defaultValue` is a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included.
|
|
81
|
-
- `
|
|
82
|
-
- An engine's own column type is a `sql` constant: ``columnType: sql`tsvector` ``.
|
|
80
|
+
- `Date` is an instant, stored in UTC to the millisecond on every engine. `'decimal'` is exact text (`price?: string | null`). `type: Number` with `precision`/`scale` opts into a rounding JS number.
|
|
83
81
|
- Members are named by callbacks, never strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
|
|
84
|
-
- `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity.
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status],
|
|
90
|
-
- `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
|
|
82
|
+
- `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity. `cascade: true` writes related rows in the same transaction; an update replaces a to-many's rows.
|
|
83
|
+
- **MongoDB:** a key declared `Number` and left to the database is refused, since MongoDB only generates ObjectIds. Declare the key a `String`, or give it an `onInsert` generator.
|
|
84
|
+
- Optimistic lock: `@Field({ type: Number, version: true })` with `[versionKey]?: 'version'` on the class. An update must carry the version it read. A stale one throws `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409).
|
|
85
|
+
- Computed fields are `readonly` and read in any query that names them. As SQL over the row ``(u) => sql`${u.first} || ' ' || ${u.last}` ``, or as a relation aggregate: `@Field({ computed: (user) => user.resources.count() })`. `stored: true` makes a generated column.
|
|
86
|
+
- Partial index: `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })`. Write the predicate as a query, not `sql`.
|
|
87
|
+
- Triggers run in the database: `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], run })`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. A trigger's writes skip uql's fills and entity filters. MongoDB has no triggers: https://uql-orm.dev/entities/triggers.md
|
|
91
88
|
|
|
92
89
|
## Queries
|
|
93
90
|
|
|
@@ -109,22 +106,47 @@ const users = await pool.findMany(User, {
|
|
|
109
106
|
- Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyPage`, `findManyStream`, `count`, `exists`, `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`, `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first, or the query's `$entity`. Signatures: https://uql-orm.dev/querying/methods.md
|
|
110
107
|
- Results are narrowed to what the query selected and populated. Reading an unselected field is a compile error. Name a shape with `QueryFindResult<User, 'id' | 'email'>`.
|
|
111
108
|
- `$populate` loads relations in the same statement. Nothing is lazy: an unpopulated relation is absent.
|
|
112
|
-
- In code generic over its entity, `{ [key]: 'asc' }` widens to an index signature. Take the member as a selector, `since: (keys: KeyMap<E>) => K`, read it with `keyOf(since)`, and sort with `sortOf<E>([[key, 'asc']])`. A selector follows a rename; a string key does not. `$where` and writes by a constant have no such builder: take a callback the caller writes against its own entity, `(state) => ({ state })`.
|
|
113
109
|
- `$sort` takes `'asc'`/`1` or `'desc'`/`-1`, plus `'ascNullsLast'`, `'ascNullsFirst'`, `'descNullsFirst'`, `'descNullsLast'`, which behave the same on every engine. Unqualified, each engine keeps its own null order.
|
|
114
110
|
- `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`, `$isNotNull`. Combine with `$and`, `$or`, `$not`, `$nor`. `$regex` is case-sensitive unless the pattern opens with `(?i)`.
|
|
115
111
|
- An `undefined` anywhere in `$where` throws. Leave the key out to skip the filter (`...(email && { email })`), or name `null`.
|
|
116
|
-
- NULL compares as the engine does: on SQL, `$ne`, `$nin`, `$not` and `$nor` drop NULL rows, where MongoDB keeps them. To keep them, name NULL: `{ $or: [{ col: { $ne: 'a' } }, { col: null }] }`.
|
|
117
|
-
-
|
|
118
|
-
- `
|
|
119
|
-
-
|
|
120
|
-
- Writes take `{ returning: { id: true } }` as their last argument and resolve to those rows, read back in the same transaction. Without it, inserts and upserts resolve to ids, and updates and deletes to a count. An update or delete writes exactly the rows it reports. One that reads its rows first holds them, so a racing writer waits for the commit. SQLite and MongoDB have no row locks and fail the racing writer with a retryable error instead.
|
|
121
|
-
- A query is plain data, so it can be sent from a browser to `uql-orm/http`. Its handler serves only the entities its required `include` names.
|
|
112
|
+
- NULL compares as the engine does: on SQL, `$ne`, `$nin`, `$not` and `$nor` drop NULL rows, where MongoDB keeps them. To keep them, name NULL: `{ $or: [{ col: { $ne: 'a' } }, { col: null }] }`.
|
|
113
|
+
- `findManyPage(User, { $sort: { createdAt: -1, id: 1 }, $limit: 20, $after })` pages by cursor, so page 1,000 costs what page 1 does. It returns `{ items, startCursor, endCursor, hasNextPage, hasPrevPage }`. `$sort` must end in the key or a unique `nullable: false` field, and takes no `$skip`.
|
|
114
|
+
- `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update payload with operators. Without `update`, a conflicting row takes the payload but keeps its own key. Resolves to the row's id.
|
|
115
|
+
- Writes take `{ returning: { id: true } }` as their last argument and resolve to those rows. Without it, inserts and upserts resolve to ids, and updates and deletes to a count.
|
|
122
116
|
- `updateMany` and `deleteMany` that name no rows throw: no `$where` holding a value, and no `$limit`. Pass `{ unfiltered: true }` to mean the whole table.
|
|
123
|
-
- Updates use operators
|
|
124
|
-
- JSON fields take `$pull`, `$set`, `$push`, `$addToSet`, then `$unset`, applied in that order on one value. `$set` and `$unset` take keys or dotted paths and create parents: `settings: { $set: { 'billing.plan': 'pro' } }`.
|
|
117
|
+
- Updates use operators: `{ stock: { $inc: -1 } }` or `$mul`, with NULL counted as 0. Put a guard in `$where` (`stock: { $gte: 1 }`) to make a decrement race-safe.
|
|
118
|
+
- JSON fields take `$pull`, `$set`, `$push`, `$addToSet`, then `$unset`, applied in that order on one value. `$set` and `$unset` take keys or dotted paths and create parents: `settings: { $set: { 'billing.plan': 'pro' } }`.
|
|
125
119
|
- `$lock: true` locks the rows a read returns, and `{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds. It needs an open transaction. SQLite, libSQL, Turso, D1 and MongoDB have no row lock and refuse it.
|
|
126
|
-
- `queryErrorKind(err)` names a failure the same on every engine: `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security`. Catch by kind, not by driver code.
|
|
127
|
-
- Raw SQL: ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar, `null` or a list, never `undefined` or a plain object
|
|
120
|
+
- `queryErrorKind(err)` names a failure the same on every engine: `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security`. Catch by kind, not by driver code.
|
|
121
|
+
- Raw SQL: ``pool.all`SELECT ... WHERE id = ${id}` `` for a `SELECT`, ``pool.run`...` `` for a write. Interpolated values bind: a scalar, `null` or a list, never `undefined` or a plain object. `sql` builds a fragment, and `sql.join(fragments, ' AND ')` joins them. `sql.text(s)` runs trusted SQL held in a string. Never build it from user input.
|
|
122
|
+
|
|
123
|
+
## Aggregates
|
|
124
|
+
|
|
125
|
+
Compute in SQL, not in code. Loading rows to dedupe, count or sum them in JavaScript costs a round trip and every row.
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
import { Post } from './entities.js';
|
|
129
|
+
import { pool } from './uql.config.js';
|
|
130
|
+
|
|
131
|
+
// Distinct values: a $group with no $select returns each once.
|
|
132
|
+
const titles = await pool.aggregate(Post, {
|
|
133
|
+
$group: { title: true },
|
|
134
|
+
$sort: { title: 1 },
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
// Tallies per group, in one statement.
|
|
138
|
+
const counts = await pool.aggregate(Post, {
|
|
139
|
+
$group: { authorId: true },
|
|
140
|
+
$select: { distinctTitles: { $countDistinct: { title: true } } },
|
|
141
|
+
});
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- `$select` takes `$count` (`'*'` or a field), `$countDistinct`, `$sum`, `$avg`, `$min` and `$max`. Over no rows a count is `0` and the others are `null`.
|
|
145
|
+
- `$where` on the query filters rows before grouping. An operator's own `$where` filters only the rows that operator reads, which pivots rows into columns in one query: `{ $count: '*', $where: { published: true } }`.
|
|
146
|
+
- `$having` and `$sort` name a grouped column or a `$select` alias, never a field that is not grouped.
|
|
147
|
+
- A `$group` key can reach a to-one relation's field: `{ orderId: { transaction: { orderId: true } } }`. A to-many cannot be grouped, since it multiplies the rows.
|
|
148
|
+
- A per-row count belongs on the entity as a `computed` field, not as an aggregate per request. Counts for a read's rows: `$count: { posts: true }`.
|
|
149
|
+
- Details: https://uql-orm.dev/querying/aggregate.md
|
|
128
150
|
|
|
129
151
|
## Connections and transactions
|
|
130
152
|
|
|
@@ -137,33 +159,25 @@ await pool.transaction(async (querier) => {
|
|
|
137
159
|
});
|
|
138
160
|
```
|
|
139
161
|
|
|
140
|
-
The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A
|
|
162
|
+
The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A nested `transaction()` is a savepoint; MongoDB refuses it. For a transaction that opens in one place and ends in another, use `beginTransaction`, `commitTransaction` and `rollbackTransaction`. `querier.onCommit(fn)` runs `fn` after the outermost commit and never on rollback: use it for mail and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
141
163
|
|
|
142
|
-
A
|
|
143
|
-
|
|
144
|
-
A `findManyStream` holds its querier until the loop ends, and other statements on it are refused meanwhile. Inside the loop, run them on another connection. Inside a transaction, or on SQLite and PGlite (one shared connection), run them after the loop. That includes an `@AfterLoad` querying through its `querier` on a streamed row. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server, 32,767 on Neon) is refused: split a long `$in`.
|
|
164
|
+
A `findManyStream` holds its querier until the loop ends, and other statements on it are refused meanwhile. Run them after the loop, or on another connection.
|
|
145
165
|
|
|
146
166
|
## Migrations
|
|
147
167
|
|
|
148
168
|
`npx uql-migrate` reads `uql.config.ts` (`bun --bun uql-migrate` on Bun):
|
|
149
169
|
|
|
150
170
|
- `sync`: applies what the entities imply. Development only.
|
|
151
|
-
- `generate:entities`: writes the diff as a migration file to review. A renamed column is a drop and an add, unless a naming strategy maps it
|
|
152
|
-
- `up` and `down`: each migration runs in its own transaction, under a lock so concurrent instances run it once. From code, `await new Migrator(pool, { migrationsPath }).up()` before the app starts.
|
|
171
|
+
- `generate:entities`: writes the diff as a migration file to review. A renamed column is a drop and an add, unless a naming strategy maps it or you write `renameColumn(table, from, to)`. It refuses a required column with no default on a table that holds rows.
|
|
172
|
+
- `up` and `down`: each migration runs in its own transaction, under a lock so concurrent instances run it once. From code, `await new Migrator(pool, { migrationsPath }).up()` before the app starts.
|
|
153
173
|
- `generate:from-db`: writes entity classes from an existing database.
|
|
154
|
-
- `drift:check`: fails when the database no longer matches
|
|
155
|
-
- `sync --dry-run`: prints only SQL on stdout, for a migration file another tool applies
|
|
156
|
-
|
|
157
|
-
In a migration, ``querier.run /*sql*/ `CREATE TABLE ...` `` marks the SQL: the comment is what es6-string-html highlights.
|
|
158
|
-
|
|
159
|
-
Checks, enums and triggers are part of the diff. uql owns the `_uql_`-prefixed checks and triggers and never touches another. On MongoDB, checks and enums are the collection's validator, which uql owns whole: a check fails a document that lacks the field it compares.
|
|
174
|
+
- `drift:check`: fails when the database no longer matches the entities.
|
|
175
|
+
- `sync --dry-run`: prints only SQL on stdout, for a migration file another tool applies.
|
|
160
176
|
|
|
161
177
|
## Where to read more
|
|
162
178
|
|
|
163
179
|
- Operators and per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
|
|
164
180
|
- Relations and deep `$populate`: https://uql-orm.dev/querying/relations.md
|
|
165
181
|
- Computed fields and stamps: https://uql-orm.dev/entities/computed-fields.md
|
|
166
|
-
- Triggers: https://uql-orm.dev/entities/triggers.md
|
|
167
182
|
- Coming from Prisma, Drizzle, TypeORM, MikroORM or Mongoose: https://uql-orm.dev/switching-to-uql.md
|
|
168
|
-
- Moving data off MongoDB: https://uql-orm.dev/mongodb.md#moving-to-sql
|
|
169
183
|
- Breaking changes by version: https://uql-orm.dev/upgrade-guide.md
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
import type { UqlContext } from '../type/index.js';
|
|
2
|
-
/** A value held for a synchronous callback. See `context.ts` for the server behavior. */
|
|
3
|
-
export declare function asyncScope<T>(): {
|
|
4
|
-
run<R>(value: T, callback: () => R): R;
|
|
5
|
-
get(): T | undefined;
|
|
6
|
-
};
|
|
7
|
-
/** Runs `callback` with an ambient {@link UqlContext}. See `context.ts` for the server behavior. */
|
|
8
|
-
export declare function withContext<T>(context: UqlContext, callback: () => T): T;
|
|
9
|
-
/** The ambient context set by the nearest enclosing {@link withContext}, or `undefined`. */
|
|
10
|
-
export declare function getContext(): UqlContext | undefined;
|
|
11
|
-
/** Captures the current context and returns a runner that re-establishes it later. See `context.ts`. */
|
|
12
|
-
export declare function captureContext(): <T>(callback: () => T) => T;
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
// The browser's `context.ts`, without `node:async_hooks`. Filters never resolve in a browser, so this
|
|
2
|
-
// only keeps the API; it does not carry a value across `await`s.
|
|
3
|
-
/** A value held for a synchronous callback. See `context.ts` for the server behavior. */
|
|
4
|
-
export function asyncScope() {
|
|
5
|
-
let current;
|
|
6
|
-
return {
|
|
7
|
-
run: (value, callback) => {
|
|
8
|
-
const previous = current;
|
|
9
|
-
current = value;
|
|
10
|
-
try {
|
|
11
|
-
return callback();
|
|
12
|
-
}
|
|
13
|
-
finally {
|
|
14
|
-
current = previous;
|
|
15
|
-
}
|
|
16
|
-
},
|
|
17
|
-
get: () => current,
|
|
18
|
-
};
|
|
19
|
-
}
|
|
20
|
-
const contextScope = asyncScope();
|
|
21
|
-
/** Runs `callback` with an ambient {@link UqlContext}. See `context.ts` for the server behavior. */
|
|
22
|
-
export function withContext(context, callback) {
|
|
23
|
-
return contextScope.run(context, callback);
|
|
24
|
-
}
|
|
25
|
-
/** The ambient context set by the nearest enclosing {@link withContext}, or `undefined`. */
|
|
26
|
-
export function getContext() {
|
|
27
|
-
return contextScope.get();
|
|
28
|
-
}
|
|
29
|
-
/** Captures the current context and returns a runner that re-establishes it later. See `context.ts`. */
|
|
30
|
-
export function captureContext() {
|
|
31
|
-
const context = getContext();
|
|
32
|
-
return (callback) => (context ? withContext(context, callback) : callback());
|
|
33
|
-
}
|