uql-orm 0.100.2 → 0.101.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +8 -70
  2. package/dist/bunSql/bunSqlQuerierPool.js +3 -1
  3. package/dist/dialect/abstractSqlDialect.d.ts +35 -23
  4. package/dist/dialect/abstractSqlDialect.js +90 -72
  5. package/dist/dialect/hydrateColumn.d.ts +4 -5
  6. package/dist/dialect/hydrateColumn.js +2 -8
  7. package/dist/dialect/mysqlLikeSqlDialect.d.ts +4 -4
  8. package/dist/dialect/mysqlLikeSqlDialect.js +7 -6
  9. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -2
  10. package/dist/dialect/pgLikeSqlDialect.js +11 -3
  11. package/dist/entity/metadata/definition.js +1 -1
  12. package/dist/http/fetchHandler.d.ts +1 -1
  13. package/dist/http/fetchHandler.js +1 -1
  14. package/dist/index.d.ts +2 -1
  15. package/dist/index.js +1 -1
  16. package/dist/mariadb/mariaDialect.d.ts +2 -2
  17. package/dist/mariadb/mariaDialect.js +1 -0
  18. package/dist/migrate/cli-config.d.ts +4 -7
  19. package/dist/migrate/cli-config.js +11 -9
  20. package/dist/mongodb/mongoDialect.js +11 -9
  21. package/dist/mssql/mssqlDialect.d.ts +2 -2
  22. package/dist/mssql/mssqlDialect.js +1 -0
  23. package/dist/pglite/pgliteQuerierPool.js +6 -12
  24. package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
  25. package/dist/postgres/abstractPgQuerierPool.js +0 -3
  26. package/dist/postgres/pgQuerier.d.ts +6 -0
  27. package/dist/postgres/pgQuerier.js +10 -0
  28. package/dist/postgres/pgWireTypes.d.ts +11 -7
  29. package/dist/postgres/pgWireTypes.js +47 -11
  30. package/dist/querier/abstractPoolQuerier.d.ts +2 -0
  31. package/dist/querier/abstractPoolQuerier.js +5 -1
  32. package/dist/querier/abstractQuerier.d.ts +5 -5
  33. package/dist/querier/abstractQuerier.js +59 -53
  34. package/dist/querier/abstractSqlQuerier.d.ts +3 -13
  35. package/dist/querier/abstractSqlQuerier.js +24 -84
  36. package/dist/querier/rowReader.d.ts +8 -0
  37. package/dist/querier/rowReader.js +88 -0
  38. package/dist/sqlite/sqliteDialect.d.ts +2 -2
  39. package/dist/sqlite/sqliteDialect.js +2 -1
  40. package/dist/util/dialect.util.d.ts +2 -11
  41. package/dist/util/dialect.util.js +8 -21
  42. package/dist/util/query.util.js +16 -8
  43. package/dist/util/relationQuery.util.d.ts +21 -12
  44. package/dist/util/relationQuery.util.js +30 -14
  45. package/dist/util/sql.util.d.ts +0 -5
  46. package/dist/util/sql.util.js +0 -33
  47. package/dist/util/wideNumber.d.ts +4 -3
  48. package/dist/util/wideNumber.js +17 -6
  49. package/package.json +3 -4
  50. package/skills/uql-orm/SKILL.md +4 -2
@@ -65,28 +65,36 @@ export function assertWhere(meta, where) {
65
65
  * as no condition at all: `{ email: maybeEmail }` reading any row. `what` names the map in the error.
66
66
  */
67
67
  export function assertNoUndefined(map, what) {
68
- const path = undefinedPath(map, []);
68
+ const path = undefinedPath(map);
69
69
  if (path) {
70
70
  throw new UqlUsageError(`${what} holds undefined at '${path.join('.')}': leave the key out not to filter by it, or name null`);
71
71
  }
72
72
  }
73
- /** The path to the first `undefined` in a plain object or array, read depth first. */
74
- function undefinedPath(value, path) {
73
+ /**
74
+ * The path to the first `undefined` in a plain object or array, read depth first. Built on the way back out,
75
+ * so a filter holding none, which is every one that runs, allocates nothing.
76
+ */
77
+ function undefinedPath(value) {
75
78
  if (value === undefined) {
76
- return path;
79
+ return [];
77
80
  }
78
- if (!Array.isArray(value) && !isPlainObject(value)) {
81
+ if (!isWalkable(value)) {
79
82
  return undefined;
80
83
  }
81
- for (const [key, item] of Object.entries(value)) {
82
- const found = undefinedPath(item, [...path, key]);
84
+ for (const key in value) {
85
+ const found = undefinedPath(value[key]);
83
86
  if (found) {
87
+ found.unshift(key);
84
88
  return found;
85
89
  }
86
90
  }
87
91
  return undefined;
88
92
  }
89
- function isPlainObject(value) {
93
+ /** An array or a plain object: what a filter nests, and not a `Date`, a `raw` or a driver's value. */
94
+ function isWalkable(value) {
95
+ if (Array.isArray(value)) {
96
+ return true;
97
+ }
90
98
  if (!isRecord(value)) {
91
99
  return false;
92
100
  }
@@ -11,24 +11,33 @@ export type RelationRequestSummary<E> = {
11
11
  export declare function isToManyRelation(relation: Pick<RelationMeta, 'cardinality'>): boolean;
12
12
  /** Whether the entity declaring the relation holds its foreign key: an owning to-one. */
13
13
  export declare function holdsForeignKey(relation: Pick<RelationMeta, 'cardinality' | 'mappedBy'>): boolean;
14
- /** One column of a parent's key, paired with the column matching it on the table being joined. */
15
- export type ParentJoin = {
16
- readonly parent: string;
17
- readonly joined: string;
14
+ /** A key column of the entity a relation starts from or reaches, paired with the column holding it on the table joined. */
15
+ export type KeyJoin = {
16
+ readonly key: string;
17
+ readonly column: string;
18
18
  };
19
19
  /**
20
- * How a relation joins its parent, one pair per key: `parent` a column of the parent's table, `joined` the
20
+ * How a relation joins its parent, one pair per key: `key` a column of the parent's table, `column` the
21
21
  * matching one on the table the relation reads, a junction's or the child's.
22
22
  */
23
- export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | 'through'>, parentKeyCount: number): ParentJoin[];
24
- /** The junction columns holding the target's key, after the parent's `parentKeyCount` ones. */
25
- export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): string[];
23
+ export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | 'through'>, parentKeyCount: number): KeyJoin[];
24
+ /** The same pairs for the target's key: `key` a key column of the target, `column` the junction column holding it. */
25
+ export declare function targetJoins(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): KeyJoin[];
26
26
  /**
27
- * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
28
- * column a single key contributes, an OR of whole key maps for several - lists of each column apart
29
- * would pair values no parent has, and a delete would take a child of a parent that survives.
27
+ * The columns that make a row belong to the key `id` names, one per pair: a sole key's `id` is its value, a
28
+ * composite's the map of every column.
30
29
  */
31
- export declare function childrenOf(joins: readonly ParentJoin[], parentIds: readonly unknown[]): Record<string, unknown>;
30
+ export declare function pointAt(joins: readonly KeyJoin[], id: unknown): Record<string, unknown>;
31
+ /** A key's own columns, each paired with itself: the joins of a table to the rows that name it by its own key. */
32
+ export declare function keyJoins(keys: readonly string[]): KeyJoin[];
33
+ /**
34
+ * The `$where` naming exactly the rows the keys `ids` identify: an `IN` over the one column a single key
35
+ * contributes, an OR of whole key maps for several - lists of each column apart would pair values no key
36
+ * has, and a delete would take a row of a key that survives.
37
+ */
38
+ export declare function childrenOf(joins: readonly KeyJoin[], ids: readonly unknown[]): Record<string, unknown>;
39
+ /** The `$where` naming the rows {@link childrenOf} does not: `NOT IN` over one column, a `$nor` of whole keys for several. */
40
+ export declare function childrenExcept(joins: readonly KeyJoin[], ids: readonly unknown[]): Record<string, unknown>;
32
41
  /**
33
42
  * What a joined relation cannot carry, and why. A to-many is loaded by a query of its own, which is
34
43
  * what gives these four a meaning there; a to-one is one row of the parent's, so every backend used
@@ -19,34 +19,50 @@ export function holdsForeignKey(relation) {
19
19
  return !relation.mappedBy && !isToManyRelation(relation);
20
20
  }
21
21
  /**
22
- * How a relation joins its parent, one pair per key: `parent` a column of the parent's table, `joined` the
22
+ * How a relation joins its parent, one pair per key: `key` a column of the parent's table, `column` the
23
23
  * matching one on the table the relation reads, a junction's or the child's.
24
24
  */
25
25
  export function parentJoins(relOpts, parentKeyCount) {
26
26
  if (!relOpts.through) {
27
- return relOpts.references.map(({ local, foreign }) => ({ parent: local, joined: foreign }));
27
+ return relOpts.references.map(({ local, foreign }) => ({ key: local, column: foreign }));
28
28
  }
29
29
  // A junction's pairs are the parent's followed by the target's, and how many the parent has is
30
30
  // something its caller already knows - so the boundary is passed rather than stored on a relation.
31
- return relOpts.references.slice(0, parentKeyCount).map(({ local, foreign }) => ({ parent: foreign, joined: local }));
31
+ return relOpts.references.slice(0, parentKeyCount).map(({ local, foreign }) => ({ key: foreign, column: local }));
32
32
  }
33
- /** The junction columns holding the target's key, after the parent's `parentKeyCount` ones. */
34
- export function targetKeyColumns(relOpts, parentKeyCount) {
35
- return relOpts.references.slice(parentKeyCount).map(({ local }) => local);
33
+ /** The same pairs for the target's key: `key` a key column of the target, `column` the junction column holding it. */
34
+ export function targetJoins(relOpts, parentKeyCount) {
35
+ return relOpts.references.slice(parentKeyCount).map(({ local, foreign }) => ({ key: foreign, column: local }));
36
36
  }
37
37
  /**
38
- * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
39
- * column a single key contributes, an OR of whole key maps for several - lists of each column apart
40
- * would pair values no parent has, and a delete would take a child of a parent that survives.
38
+ * The columns that make a row belong to the key `id` names, one per pair: a sole key's `id` is its value, a
39
+ * composite's the map of every column.
41
40
  */
42
- export function childrenOf(joins, parentIds) {
41
+ export function pointAt(joins, id) {
43
42
  const [first] = joins;
44
43
  if (joins.length === 1) {
45
- return { [first.joined]: parentIds };
44
+ return { [first.column]: id };
46
45
  }
47
- return {
48
- $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, read(id, parent)]))),
49
- };
46
+ return Object.fromEntries(joins.map(({ key, column }) => [column, read(id, key)]));
47
+ }
48
+ /** A key's own columns, each paired with itself: the joins of a table to the rows that name it by its own key. */
49
+ export function keyJoins(keys) {
50
+ return keys.map((key) => ({ key, column: key }));
51
+ }
52
+ /**
53
+ * The `$where` naming exactly the rows the keys `ids` identify: an `IN` over the one column a single key
54
+ * contributes, an OR of whole key maps for several - lists of each column apart would pair values no key
55
+ * has, and a delete would take a row of a key that survives.
56
+ */
57
+ export function childrenOf(joins, ids) {
58
+ return joins.length === 1 ? { [joins[0].column]: ids } : { $or: alternatives(joins, ids) };
59
+ }
60
+ /** The `$where` naming the rows {@link childrenOf} does not: `NOT IN` over one column, a `$nor` of whole keys for several. */
61
+ export function childrenExcept(joins, ids) {
62
+ return joins.length === 1 ? { [joins[0].column]: { $nin: ids } } : { $nor: alternatives(joins, ids) };
63
+ }
64
+ function alternatives(joins, ids) {
65
+ return ids.map((id) => pointAt(joins, id));
50
66
  }
51
67
  function read(row, key) {
52
68
  return row[key];
@@ -1,10 +1,5 @@
1
1
  import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
2
2
  import type { PrimaryKey } from '../type/utility.js';
3
- /** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
4
- export declare function unflatObject<T extends object>(row: RawRow, attrsPaths: Record<string, string[]>): T;
5
- export declare function obtainAttrsPaths<T extends object>(row: T): {
6
- [k: string]: string[];
7
- };
8
3
  /**
9
4
  * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
10
5
  * table's key, its statement operand and its escaped form cannot spell it differently. Never the
@@ -1,38 +1,5 @@
1
1
  import { OWNED_PREFIX } from '../dialect/aliases.js';
2
- import { hasKeys, isRecord } from './object.util.js';
3
2
  import { fnv1a } from './string.util.js';
4
- /** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
5
- export function unflatObject(row, attrsPaths) {
6
- if (!hasKeys(attrsPaths)) {
7
- return row;
8
- }
9
- const dto = {};
10
- for (const col in row) {
11
- const attrPath = attrsPaths[col];
12
- if (attrPath) {
13
- let target = dto;
14
- for (let i = 0; i < attrPath.length - 1; i++) {
15
- const seg = attrPath[i];
16
- const next = target[seg];
17
- target = isRecord(next) ? next : (target[seg] = {});
18
- }
19
- target[attrPath[attrPath.length - 1]] = row[col];
20
- }
21
- else {
22
- dto[col] = row[col];
23
- }
24
- }
25
- return dto;
26
- }
27
- export function obtainAttrsPaths(row) {
28
- const paths = {};
29
- for (const col in row) {
30
- if (col.includes('.')) {
31
- paths[col] = col.split('.');
32
- }
33
- }
34
- return paths;
35
- }
36
3
  /**
37
4
  * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
38
5
  * table's key, its statement operand and its escaped form cannot spell it differently. Never the
@@ -7,9 +7,10 @@ import type { RawRow } from '../type/index.js';
7
7
  */
8
8
  export declare function decodeWideNumber(value: string | bigint): number | string;
9
9
  /**
10
- * {@link decodeWideNumber} over every `bigint` cell of a row, for the drivers that hand a BIGINT back as
11
- * one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In place: the row is the driver's fresh
12
- * object, and a copy per row cost more than the decode it carried. One argument, so it maps rows as is.
10
+ * {@link decodeWideNumber} over every `bigint` cell of a row, an array's elements included, for the
11
+ * drivers that hand a BIGINT back as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
12
+ * place: the row is the driver's fresh object, and a copy per row cost more than the decode it carried.
13
+ * One argument, so it maps rows as is.
13
14
  */
14
15
  export declare function decodeBigInts(row: RawRow): RawRow;
15
16
  /** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
@@ -9,9 +9,10 @@ export function decodeWideNumber(value) {
9
9
  return Math.abs(decoded) <= Number.MAX_SAFE_INTEGER ? decoded : String(value);
10
10
  }
11
11
  /**
12
- * {@link decodeWideNumber} over every `bigint` cell of a row, for the drivers that hand a BIGINT back as
13
- * one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In place: the row is the driver's fresh
14
- * object, and a copy per row cost more than the decode it carried. One argument, so it maps rows as is.
12
+ * {@link decodeWideNumber} over every `bigint` cell of a row, an array's elements included, for the
13
+ * drivers that hand a BIGINT back as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
14
+ * place: the row is the driver's fresh object, and a copy per row cost more than the decode it carried.
15
+ * One argument, so it maps rows as is.
15
16
  */
16
17
  export function decodeBigInts(row) {
17
18
  return decodeBigIntsExcept(row, () => false);
@@ -19,10 +20,20 @@ export function decodeBigInts(row) {
19
20
  /** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
20
21
  export function decodeBigIntsExcept(row, exact) {
21
22
  for (const key in row) {
22
- const value = row[key];
23
- if (typeof value === 'bigint' && !exact(key)) {
24
- row[key] = decodeWideNumber(value);
23
+ if (!exact(key)) {
24
+ row[key] = decodeBigIntsIn(row[key]);
25
25
  }
26
26
  }
27
27
  return row;
28
28
  }
29
+ function decodeBigIntsIn(value) {
30
+ if (typeof value === 'bigint') {
31
+ return decodeWideNumber(value);
32
+ }
33
+ if (Array.isArray(value)) {
34
+ value.forEach((element, index) => {
35
+ value[index] = decodeBigIntsIn(element);
36
+ });
37
+ }
38
+ return value;
39
+ }
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "uql-orm",
3
3
  "homepage": "https://uql-orm.dev",
4
- "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, 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.",
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.100.2",
6
+ "version": "0.101.0",
7
7
  "type": "module",
8
8
  "engines": {
9
- "node": ">=24"
9
+ "node": ">=22.18"
10
10
  },
11
11
  "sideEffects": false,
12
12
  "main": "./dist/index.js",
@@ -196,7 +196,6 @@
196
196
  "d1",
197
197
  "cloudflare",
198
198
  "bun",
199
- "deno",
200
199
  "node",
201
200
  "nodejs",
202
201
  "edge",
@@ -20,7 +20,9 @@ The full docs are Markdown at https://uql-orm.dev/llms.txt, one page per URL. Re
20
20
  npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client, ...
21
21
  ```
22
22
 
23
- ESM only. Node 24+, Bun, Deno or an edge runtime, TypeScript 5.7+. Decorators are the TC39 standard: never enable `experimentalDecorators` or `emitDecoratorMetadata`, never import `reflect-metadata`. In `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is a dated one (`es2022`+), not `esnext`.
23
+ ESM only (a CommonJS app loads it through `require(esm)`). Node 22.18+, Bun or an edge runtime, TypeScript 5.7+.
24
+
25
+ UQL's decorators are the TC39 standard: for them, never enable `experimentalDecorators` or `emitDecoratorMetadata`, never import `reflect-metadata`; in `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is a dated one (`es2022`+), not `esnext`. A project already on legacy decorators (NestJS, Angular) keeps its `tsconfig.json` as it is and defines entities with `defineEntity` instead: one config cannot compile both decorator specs. NestJS: https://uql-orm.dev/nestjs.md
24
26
 
25
27
  Node's type stripping runs no decorators: on Node, add `tsx` (`npm i -D tsx`), which `uql-migrate` imports `uql.config.ts` through. Next.js compiles TC39 decorators only through a `babel.config.json` with `@babel/plugin-proposal-decorators` at `version: '2023-11'`. A bundle that minifies class names (Next's server build, or any bundler's `minify`) needs `@Entity({ name: 'todo' })`: a table name is the class name otherwise.
26
28
 
@@ -118,7 +120,7 @@ const users = await pool.findMany(User, {
118
120
  - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0, so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. On SQL the step may be a ref or `raw` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set`, `$unset`, `$push`, `$pull`.
119
121
  - `$lock: true` locks the rows a read returns (`{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and refuse it.
120
122
  - `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security` - so catch by kind rather than by a driver's code or an `instanceof`. Every error UQL raises itself is a `UqlError`.
121
- - ``pool.all`SELECT ... WHERE id = ${id}` `` runs a `SELECT` and ``pool.run`...` `` a write: both are tags, each interpolated value bound: a scalar, `null` or a list of them, never `undefined` or a plain object (bind `JSON.stringify(doc)`). `raw` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `raw.join(fragments, ' AND ')` joins them. `raw.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `raw` is a tag, so ``raw(`...`)`` does not compile. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
123
+ - ``pool.all`SELECT ... WHERE id = ${id}` `` runs a `SELECT` and ``pool.run`...` `` a write, one statement per call: both are tags, each interpolated value bound: a scalar, `null` or a list of them, never `undefined` or a plain object (bind `JSON.stringify(doc)`). `raw` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `raw.join(fragments, ' AND ')` joins them. `raw.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `raw` is a tag, so ``raw(`...`)`` does not compile. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
122
124
 
123
125
  ## Connections and transactions
124
126