uql-orm 0.101.0 → 0.101.2

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 (104) hide show
  1. package/README.md +1 -1
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +6 -6
  4. package/dist/d1/d1SqliteDialect.d.ts +1 -1
  5. package/dist/d1/d1SqliteDialect.js +1 -1
  6. package/dist/dialect/abstractDialect.js +2 -2
  7. package/dist/dialect/abstractSqlDialect.d.ts +10 -10
  8. package/dist/dialect/abstractSqlDialect.js +24 -24
  9. package/dist/dialect/operators.js +2 -2
  10. package/dist/dialect/pgLikeSqlDialect.d.ts +1 -1
  11. package/dist/dialect/pgLikeSqlDialect.js +5 -5
  12. package/dist/dialect/queryContext.d.ts +1 -1
  13. package/dist/dialect/queryContext.js +1 -1
  14. package/dist/dialect/vectorSqlDialect.js +1 -1
  15. package/dist/entity/decorator/entity.d.ts +2 -2
  16. package/dist/entity/decorator/entity.js +2 -2
  17. package/dist/http/index.d.ts +2 -2
  18. package/dist/http/index.js +1 -2
  19. package/dist/http/query.d.ts +1 -1
  20. package/dist/http/query.js +4 -4
  21. package/dist/index.d.ts +1 -1
  22. package/dist/index.js +1 -1
  23. package/dist/libsql/index.d.ts +1 -1
  24. package/dist/libsql/index.js +1 -1
  25. package/dist/migrate/builder/tableBuilder.js +1 -1
  26. package/dist/migrate/builder/types.d.ts +2 -2
  27. package/dist/migrate/codegen/entityCodeGenerator.js +1 -1
  28. package/dist/migrate/codegen/fieldOptionsSource.js +5 -5
  29. package/dist/migrate/codegen/indexDecoratorSource.d.ts +2 -2
  30. package/dist/migrate/codegen/indexDecoratorSource.js +5 -5
  31. package/dist/migrate/codegen/sourceLiteral.d.ts +2 -2
  32. package/dist/migrate/codegen/sourceLiteral.js +3 -3
  33. package/dist/migrate/ddl/defaultSql.js +1 -1
  34. package/dist/migrate/generator/definitionToNode.d.ts +3 -3
  35. package/dist/migrate/index.d.ts +8 -11
  36. package/dist/migrate/index.js +7 -17
  37. package/dist/migrate/indexPredicate.d.ts +1 -1
  38. package/dist/migrate/indexPredicate.js +5 -5
  39. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +8 -8
  40. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +3 -3
  41. package/dist/migrate/introspection/mssqlIntrospector.d.ts +5 -5
  42. package/dist/migrate/introspection/mssqlIntrospector.js +10 -10
  43. package/dist/migrate/introspection/mysqlIntrospector.d.ts +5 -5
  44. package/dist/migrate/introspection/mysqlIntrospector.js +13 -13
  45. package/dist/migrate/introspection/postgresIntrospector.d.ts +13 -13
  46. package/dist/migrate/introspection/postgresIntrospector.js +21 -21
  47. package/dist/migrate/introspection/sqliteIntrospector.d.ts +4 -4
  48. package/dist/migrate/introspection/sqliteIntrospector.js +6 -6
  49. package/dist/migrate/migrationLock.d.ts +3 -3
  50. package/dist/migrate/migrationLock.js +7 -7
  51. package/dist/migrate/migrationTarget.js +2 -2
  52. package/dist/migrate/migrator.js +2 -2
  53. package/dist/migrate/schemaGenerator.d.ts +1 -1
  54. package/dist/migrate/schemaGenerator.js +1 -1
  55. package/dist/migrate/storage/databaseStorage.d.ts +3 -3
  56. package/dist/migrate/storage/databaseStorage.js +4 -4
  57. package/dist/migrate/triggerSql.js +7 -7
  58. package/dist/mongodb/index.d.ts +1 -1
  59. package/dist/mongodb/index.js +1 -1
  60. package/dist/mongodb/mongoDialect.js +4 -4
  61. package/dist/mongodb/mongoSchemaGenerator.js +3 -3
  62. package/dist/mongodb/mongodbQuerier.d.ts +3 -2
  63. package/dist/mssql/mssqlDialect.js +3 -3
  64. package/dist/postgres/index.d.ts +1 -1
  65. package/dist/postgres/index.js +1 -1
  66. package/dist/querier/abstractQuerier.d.ts +10 -3
  67. package/dist/querier/abstractQuerier.js +12 -12
  68. package/dist/querier/abstractSqlQuerier.d.ts +3 -3
  69. package/dist/querier/abstractSqlQuerier.js +3 -3
  70. package/dist/schema/canonicalType.d.ts +1 -1
  71. package/dist/schema/canonicalType.js +6 -6
  72. package/dist/schema/sqlExpression.d.ts +4 -4
  73. package/dist/schema/sqlExpression.js +5 -5
  74. package/dist/sqlite/index.d.ts +1 -1
  75. package/dist/sqlite/index.js +1 -1
  76. package/dist/sqlite/sqliteDialect.js +2 -2
  77. package/dist/type/dialect.d.ts +3 -3
  78. package/dist/type/entity.d.ts +39 -39
  79. package/dist/type/index.d.ts +1 -1
  80. package/dist/type/index.js +1 -1
  81. package/dist/type/migration.d.ts +1 -1
  82. package/dist/type/querier.d.ts +5 -5
  83. package/dist/type/query.d.ts +32 -32
  84. package/dist/type/queryAggregate.d.ts +2 -2
  85. package/dist/type/{queryRaw.d.ts → querySql.d.ts} +33 -33
  86. package/dist/type/{queryRaw.js → querySql.js} +17 -17
  87. package/dist/type/queryWhere.d.ts +22 -22
  88. package/dist/type/universalQuerier.d.ts +12 -12
  89. package/dist/type/wire.d.ts +4 -4
  90. package/dist/util/ddlExpression.util.d.ts +4 -4
  91. package/dist/util/ddlExpression.util.js +7 -7
  92. package/dist/util/dialect.util.d.ts +7 -7
  93. package/dist/util/dialect.util.js +4 -4
  94. package/dist/util/fieldOption.util.d.ts +3 -3
  95. package/dist/util/fieldOption.util.js +5 -5
  96. package/dist/util/index.d.ts +1 -1
  97. package/dist/util/index.js +1 -1
  98. package/dist/util/query.util.js +1 -1
  99. package/dist/util/{raw.d.ts → sql.d.ts} +22 -20
  100. package/dist/util/{raw.js → sql.js} +28 -26
  101. package/dist/util/triggerWrite.d.ts +7 -7
  102. package/dist/util/triggerWrite.js +2 -2
  103. package/package.json +1 -1
  104. package/skills/uql-orm/SKILL.md +7 -7
@@ -1,7 +1,7 @@
1
- import { QueryRaw } from '../type/index.js';
1
+ import { QuerySql } from '../type/index.js';
2
2
  import { fieldFamily, isInlinedExpression } from './field.util.js';
3
3
  import { getKeys } from './object.util.js';
4
- import { constantSql } from './raw.js';
4
+ import { constantSql } from './sql.js';
5
5
  /**
6
6
  * The column families each field option means anything on, or `'*'` where it applies to every column.
7
7
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
@@ -93,7 +93,7 @@ function deadOn(opts, key) {
93
93
  return 'a primary key';
94
94
  if (opts.updatable === false && key === 'onUpdate')
95
95
  return "a field declared 'updatable: false'";
96
- if (opts.columnType instanceof QueryRaw && TYPE_BOUNDS.some((bound) => bound === key)) {
96
+ if (opts.columnType instanceof QuerySql && TYPE_BOUNDS.some((bound) => bound === key)) {
97
97
  return 'a column type written out as SQL, which carries its own bounds';
98
98
  }
99
99
  if (opts.version === true && (VERSION_WRITES.some((write) => write === key) || contradictsNotNull(opts, key))) {
@@ -109,8 +109,8 @@ function deadOn(opts, key) {
109
109
  export function fieldOptionConflict(opts) {
110
110
  // Caught here rather than where the type is resolved, which is a migration on most engines and a
111
111
  // query on SQL Server, and which knows no field to name.
112
- if (opts.columnType instanceof QueryRaw && constantSql(opts.columnType) === undefined) {
113
- return "cannot use 'columnType': a `raw` one names a constant type, so it can bind no value and read no column";
112
+ if (opts.columnType instanceof QuerySql && constantSql(opts.columnType) === undefined) {
113
+ return "cannot use 'columnType': a `sql` one names a constant type, so it can bind no value and read no column";
114
114
  }
115
115
  const family = fieldFamily(opts);
116
116
  // Walked in table order, not in the order the field happened to be written, so a field with two
@@ -7,7 +7,7 @@ export * from './hook.util.js';
7
7
  export * from './ddlExpression.util.js';
8
8
  export * from './logger.js';
9
9
  export * from './object.util.js';
10
- export * from './raw.js';
10
+ export * from './sql.js';
11
11
  export { deleteFrom, insertInto, refuse, updateTable, upsertInto } from './triggerWrite.js';
12
12
  export * from './rowKey.util.js';
13
13
  export * from './relationQuery.util.js';
@@ -7,7 +7,7 @@ export * from './hook.util.js';
7
7
  export * from './ddlExpression.util.js';
8
8
  export * from './logger.js';
9
9
  export * from './object.util.js';
10
- export * from './raw.js';
10
+ export * from './sql.js';
11
11
  export { deleteFrom, insertInto, refuse, updateTable, upsertInto } from './triggerWrite.js';
12
12
  export * from './rowKey.util.js';
13
13
  export * from './relationQuery.util.js';
@@ -90,7 +90,7 @@ function undefinedPath(value) {
90
90
  }
91
91
  return undefined;
92
92
  }
93
- /** An array or a plain object: what a filter nests, and not a `Date`, a `raw` or a driver's value. */
93
+ /** An array or a plain object: what a filter nests, and not a `Date`, a `sql` or a driver's value. */
94
94
  function isWalkable(value) {
95
95
  if (Array.isArray(value)) {
96
96
  return true;
@@ -1,39 +1,39 @@
1
- import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type RawValue, type SqlStatement, type SqlValueName, type TriggerRowName, type Type } from '../type/index.js';
1
+ import { type EntitySql, type EntityWhere, type EntityWhereMeta, QuerySql, type QuerySqlFn, type ComputedRefs, type RefMap, type SqlArg, type SqlStatement, type SqlValueName, type TriggerRowName, type Type } from '../type/index.js';
2
2
  /**
3
- * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
4
- * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
3
+ * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `sql` renders
4
+ * in place: `sql`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
5
5
  * never build one from user input. See the Raw SQL guide.
6
6
  */
7
- export declare function raw(strings: TemplateStringsArray, ...values: readonly RawValue[]): QueryRaw;
8
- export declare namespace raw {
9
- var join: (parts: readonly QueryRaw[], separator?: string) => QueryRaw;
10
- var text: (sql: string) => QueryRaw;
7
+ export declare function sql(strings: TemplateStringsArray, ...values: readonly SqlArg[]): QuerySql;
8
+ export declare namespace sql {
9
+ var join: (parts: readonly QuerySql[], separator?: string) => QuerySql;
10
+ var text: (statement: string) => QuerySql;
11
11
  }
12
- export declare function raw(value: QueryRawFn): QueryRaw;
13
- /** The statement `all` or `run` was handed: a tagged template's, or a `raw` built apart. */
14
- export declare function statementOf([sql, ...values]: SqlStatement): QueryRaw;
12
+ export declare function sql(value: QuerySqlFn): QuerySql;
13
+ /** The statement `all` or `run` was handed: a tagged template's, or a `sql` built apart. */
14
+ export declare function statementOf([statement, ...values]: SqlStatement): QuerySql;
15
15
  /**
16
- * The SQL of a `raw` that names a constant, for a DDL clause with no dialect to render against and
16
+ * The SQL of a `sql` that names a constant, for a DDL clause with no dialect to render against and
17
17
  * nowhere to bind a value; `undefined` where it interpolates and so needs one.
18
18
  */
19
- export declare function constantSql(value: QueryRaw): string | undefined;
19
+ export declare function constantSql(value: QuerySql): string | undefined;
20
20
  /**
21
21
  * The database's clock in UTC to the millisecond, the form uql reads a timestamp back in exactly. Use it for
22
22
  * a `defaultValue`, a stamp, an `onUpdate` or a `$where`, in entities and migrations alike.
23
23
  */
24
- export declare const currentTimestamp: QueryRaw;
24
+ export declare const currentTimestamp: QuerySql;
25
25
  /** Today on the database's clock; on SQLite, the text a bound `Date` at midnight is. */
26
- export declare const currentDate: QueryRaw;
26
+ export declare const currentDate: QuerySql;
27
27
  /** The time of day on the database's clock. */
28
- export declare const currentTime: QueryRaw;
28
+ export declare const currentTime: QuerySql;
29
29
  /** A UUID the database generates: a version 4, or a version 1 on MySQL and MariaDB. SQLite has none. */
30
- export declare const uuid: QueryRaw;
30
+ export declare const uuid: QuerySql;
31
31
  /** A time-ordered version 7 UUID, which indexes better as a key. Postgres 18+ and MariaDB 11.7+ only. */
32
- export declare const uuidv7: QueryRaw;
32
+ export declare const uuidv7: QuerySql;
33
33
  /** Each value above by its name, the name a migration or `generate:from-db` writes it under. */
34
- export declare const SQL_VALUES: Readonly<Record<SqlValueName, QueryRaw>>;
34
+ export declare const SQL_VALUES: Readonly<Record<SqlValueName, QuerySql>>;
35
35
  /**
36
- * The fields of `entity` as {@link ColumnRef}s, each rendering inside `raw` as its column: named the way
36
+ * The fields of `entity` as {@link ColumnRef}s, each rendering inside `sql` as its column: named the way
37
37
  * the dialect names it, so the naming strategy and `@Field({ name })` apply, and qualified by the alias
38
38
  * in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
39
39
  */
@@ -44,7 +44,7 @@ export declare function refs<E>(entity: Type<E>): RefMap<E>;
44
44
  */
45
45
  export declare function memberRefs<E>(): ComputedRefs<E>;
46
46
  /** SQL a definition writes, a callback's refs read off {@link memberRefs}. */
47
- export declare function entitySql<E>(sql: EntitySql<E>): QueryRaw;
47
+ export declare function entitySql<E>(statement: EntitySql<E>): QuerySql;
48
48
  /** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */
49
49
  export declare function entityWhere<E>(where: EntityWhere<E>): EntityWhereMeta<E>;
50
50
  /**
@@ -54,3 +54,5 @@ export declare function entityWhere<E>(where: EntityWhere<E>): EntityWhereMeta<E
54
54
  * Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
55
55
  */
56
56
  export declare function rowRefs<E>(entity: Type<E>, qualifier: TriggerRowName): RefMap<E>;
57
+ /** @deprecated Renamed to {@link sql}, the tag editors recognise for SQL highlighting. */
58
+ export declare const raw: typeof sql;
@@ -1,25 +1,25 @@
1
1
  import { getMeta } from '../entity/metadata/definition.js';
2
- import { ColumnRef, QueryRaw, RAW_TEXT, RelationAggregate, TriggerWriteRaw, } from '../type/index.js';
2
+ import { ColumnRef, QuerySql, SQL_TEXT, RelationAggregate, TriggerWriteSql, } from '../type/index.js';
3
3
  import { aggregateOf, isInlinedExpression } from './field.util.js';
4
4
  import { entityName, hasKeys } from './object.util.js';
5
5
  import { UqlUsageError } from './uqlError.js';
6
- export function raw(source, ...values) {
6
+ export function sql(source, ...values) {
7
7
  if (!isTemplateStrings(source)) {
8
- return new QueryRaw(source);
8
+ return new QuerySql(source);
9
9
  }
10
10
  if (!values.length) {
11
- return raw.text(source[0]);
11
+ return sql.text(source[0]);
12
12
  }
13
13
  if (values.some((value) => value === undefined)) {
14
- throw new UqlUsageError('a raw template interpolated undefined, which binds nothing: leave it out, or write null');
14
+ throw new UqlUsageError('an sql template interpolated undefined, which binds nothing: leave it out, or write null');
15
15
  }
16
16
  // Writes joined by whitespace alone are still only writes, so a set-based trigger narrows each one.
17
- const writes = values.every((value) => value instanceof TriggerWriteRaw) && source.every((part) => !part.trim());
18
- return new (writes ? TriggerWriteRaw : QueryRaw)((opts) => {
17
+ const writes = values.every((value) => value instanceof TriggerWriteSql) && source.every((part) => !part.trim());
18
+ return new (writes ? TriggerWriteSql : QuerySql)((opts) => {
19
19
  const { ctx } = opts;
20
20
  ctx.append(source[0]);
21
21
  values.forEach((value, i) => {
22
- if (value instanceof QueryRaw) {
22
+ if (value instanceof QuerySql) {
23
23
  value.render(opts);
24
24
  }
25
25
  else {
@@ -29,9 +29,9 @@ export function raw(source, ...values) {
29
29
  });
30
30
  });
31
31
  }
32
- /** `parts` one after another, `separator` between each, every part binding its own values: `raw.join(conditions, ' AND ')`. */
33
- raw.join = function join(parts, separator = ', ') {
34
- return new QueryRaw((opts) => {
32
+ /** `parts` one after another, `separator` between each, every part binding its own values: `sql.join(conditions, ' AND ')`. */
33
+ sql.join = function join(parts, separator = ', ') {
34
+ return new QuerySql((opts) => {
35
35
  parts.forEach((part, index) => {
36
36
  if (index) {
37
37
  opts.ctx.append(separator);
@@ -41,28 +41,28 @@ raw.join = function join(parts, separator = ', ') {
41
41
  });
42
42
  };
43
43
  /** SQL held in a string, run as written, binding nothing: for trusted text only, never built from user input. */
44
- raw.text = function text(sql) {
45
- return new QueryRaw(() => sql, { text: sql });
44
+ sql.text = function text(statement) {
45
+ return new QuerySql(() => statement, { text: statement });
46
46
  };
47
- /** The statement `all` or `run` was handed: a tagged template's, or a `raw` built apart. */
48
- export function statementOf([sql, ...values]) {
49
- return sql instanceof QueryRaw ? sql : raw(sql, ...values);
47
+ /** The statement `all` or `run` was handed: a tagged template's, or a `sql` built apart. */
48
+ export function statementOf([statement, ...values]) {
49
+ return statement instanceof QuerySql ? statement : sql(statement, ...values);
50
50
  }
51
51
  /**
52
- * The SQL of a `raw` that names a constant, for a DDL clause with no dialect to render against and
52
+ * The SQL of a `sql` that names a constant, for a DDL clause with no dialect to render against and
53
53
  * nowhere to bind a value; `undefined` where it interpolates and so needs one.
54
54
  */
55
55
  export function constantSql(value) {
56
- return value[RAW_TEXT];
56
+ return value[SQL_TEXT];
57
57
  }
58
58
  /** A value the database computes, in each engine's SQL; one an engine has no function for throws. */
59
59
  function sqlValue(name) {
60
- return raw(({ dialect }) => {
61
- const sql = dialect.sqlValues[name];
62
- if (sql === undefined) {
60
+ return sql(({ dialect }) => {
61
+ const statement = dialect.sqlValues[name];
62
+ if (statement === undefined) {
63
63
  throw new UqlUsageError(`${dialect.dialectName} has no ${name}; write it as raw SQL this engine accepts`);
64
64
  }
65
- return sql;
65
+ return statement;
66
66
  });
67
67
  }
68
68
  /**
@@ -87,7 +87,7 @@ export const SQL_VALUES = {
87
87
  uuidv7,
88
88
  };
89
89
  /**
90
- * The fields of `entity` as {@link ColumnRef}s, each rendering inside `raw` as its column: named the way
90
+ * The fields of `entity` as {@link ColumnRef}s, each rendering inside `sql` as its column: named the way
91
91
  * the dialect names it, so the naming strategy and `@Field({ name })` apply, and qualified by the alias
92
92
  * in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
93
93
  */
@@ -103,8 +103,8 @@ export function memberRefs() {
103
103
  return MEMBER_REFS;
104
104
  }
105
105
  /** SQL a definition writes, a callback's refs read off {@link memberRefs}. */
106
- export function entitySql(sql) {
107
- return sql instanceof QueryRaw ? sql : sql(memberRefs());
106
+ export function entitySql(statement) {
107
+ return statement instanceof QuerySql ? statement : statement(memberRefs());
108
108
  }
109
109
  /** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */
110
110
  export function entityWhere(where) {
@@ -185,7 +185,9 @@ function renderColumn(meta, key, opts, qualifier) {
185
185
  }
186
186
  scope.ctx.append(scope.escapedPrefix + scope.dialect.escapeId(scope.dialect.columnOf(meta, key), true));
187
187
  }
188
- /** A tag call passes the frozen strings array, which carries its own `raw` counterpart. */
188
+ /** @deprecated Renamed to {@link sql}, the tag editors recognise for SQL highlighting. */
189
+ export const raw = sql;
190
+ /** A tag call passes the frozen strings array, which carries its own `sql` counterpart. */
189
191
  function isTemplateStrings(value) {
190
192
  return Array.isArray(value) && Array.isArray(Reflect.get(value, 'raw'));
191
193
  }
@@ -1,27 +1,27 @@
1
- import { type EntityPredicate, type QueryConflictPaths, type QueryRaw, type TriggerWrite, type Type, type UpdatePayload, type WritableKey, type WriteRow } from '../type/index.js';
1
+ import { type EntityPredicate, type QueryConflictPaths, type QuerySql, type TriggerWrite, type Type, type UpdatePayload, type WritableKey, type WriteRow } from '../type/index.js';
2
2
  /**
3
3
  * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
4
4
  * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
5
5
  * set-based trigger included, where it inserts one row for each the statement touched.
6
6
  */
7
- export declare function insertInto<E extends object>(entity: Type<E>, row: WriteRow<E>): QueryRaw;
7
+ export declare function insertInto<E extends object>(entity: Type<E>, row: WriteRow<E>): QuerySql;
8
8
  /**
9
9
  * A row inserted by a trigger's body, or what its conflict paths find taking `update` instead, as `upsertOne`
10
10
  * does: `upsertInto(Tally, { postId: true }, { postId: newRow.id, count: 1 }, { count: { $inc: 1 } })`.
11
11
  */
12
- export declare function upsertInto<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, row: WriteRow<E>, update?: UpdatePayload<E, QueryRaw, WritableKey<E>, never>): QueryRaw;
12
+ export declare function upsertInto<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, row: WriteRow<E>, update?: UpdatePayload<E, QuerySql, WritableKey<E>, never>): QuerySql;
13
13
  /** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
14
14
  export declare function updateTable<E extends object>(entity: Type<E>, q: {
15
15
  readonly $where: EntityPredicate<E>;
16
- }, set: UpdatePayload<E, QueryRaw, WritableKey<E>, never>): QueryRaw;
16
+ }, set: UpdatePayload<E, QuerySql, WritableKey<E>, never>): QuerySql;
17
17
  /** The rows `q.$where` names deleted by a trigger's body, outright: a soft delete is an `updateTable`. */
18
18
  export declare function deleteFrom<E extends object>(entity: Type<E>, q: {
19
19
  readonly $where: EntityPredicate<E>;
20
- }): QueryRaw;
20
+ }): QuerySql;
21
21
  /**
22
22
  * Fails the write that fired the trigger, with `message` as the error: a table kept append-only refuses its
23
23
  * updates and deletes, and a `where` narrows it to the rows a rule forbids.
24
24
  */
25
- export declare function refuse(message: string): QueryRaw;
25
+ export declare function refuse(message: string): QuerySql;
26
26
  /** A write in a trigger's body, as every helper here and a stamp render one. */
27
- export declare function written(write: TriggerWrite): QueryRaw;
27
+ export declare function written(write: TriggerWrite): QuerySql;
@@ -1,4 +1,4 @@
1
- import { TriggerWriteRaw, } from '../type/index.js';
1
+ import { TriggerWriteSql, } from '../type/index.js';
2
2
  /**
3
3
  * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
4
4
  * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
@@ -31,5 +31,5 @@ export function refuse(message) {
31
31
  }
32
32
  /** A write in a trigger's body, as every helper here and a stamp render one. */
33
33
  export function written(write) {
34
- return new TriggerWriteRaw(({ ctx, dialect, rows }) => dialect.triggerWrite(ctx, write, rows));
34
+ return new TriggerWriteSql(({ ctx, dialect, rows }) => dialect.triggerWrite(ctx, write, rows));
35
35
  }
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.101.0",
6
+ "version": "0.101.2",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -75,16 +75,16 @@ export class Post {
75
75
  - Every `@Field` states its `type`: `String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`. A foreign key takes `references` instead and inherits the target key's type. A `Date` is an instant, stored in UTC to the millisecond on every engine; `precision` sets other fractional digits. A `'decimal'` is exact text (`price?: string | null`); `type: Number` with `precision`/`scale` opts in to a rounding JS number. A JSON column of no fixed shape is a bare `Json`.
76
76
  - A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
77
77
  - Declare a `nullable: false` column `!` (`email!: string`): reads have it and inserts must name it, except a single-column key and a `version`, which uql fills. Declare `?` whatever an insert may leave out: a nullable, `onInsert`, `defaultValue`, `eager: false` or `computed` field, and relations.
78
- - An engine's own column type is a `raw` constant, ``columnType: raw`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
79
- - `defaultValue` is a value of the field's type (a JSON column's document, `[]` or `{}`), or SQL the database evaluates per row: one of `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``raw`...` ``. A string is always text, `'CURRENT_TIMESTAMP'` included. The migration builder takes the same.
78
+ - An engine's own column type is a `sql` constant, ``columnType: sql`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
79
+ - `defaultValue` is a value of the field's type (a JSON column's document, `[]` or `{}`), or SQL the database evaluates per row: one of `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A string is always text, `'CURRENT_TIMESTAMP'` included. The migration builder takes the same.
80
80
  - `currentTimestamp` is the database clock, UTC to the millisecond on every engine, where a raw `CURRENT_TIMESTAMP` is not on SQLite, MySQL or SQL Server. Use it for a default, a stamp, `onUpdate` or `$where`.
81
81
  - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
82
82
  - `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names its junction entity.
83
83
  - `cascade: true` makes writes reach a relation's rows, in one transaction. A to-one holding the key takes `'persist'` only: its target is written first, and `{ id }` links an existing one. An update replaces a to-many's rows and a many-to-many's links: the listed ones are saved or kept, the rest removed.
84
- - `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })` states a partial index's filter as the predicate the query passes, never as `raw`: a planner matches the two by shape, so `raw` that means the same thing leaves the index unused.
84
+ - `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })` states a partial index's filter as the predicate the query passes, never as `sql`: a planner matches the two by shape, so `sql` that means the same thing leaves the index unused.
85
85
  - `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, is an optimistic lock: an update must carry the version it read (a compile error otherwise), and one against a row someone else moved on throws `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409). Its updates name one row by its id; save and upsert are refused.
86
- - `@Field({ computed })` is a value the database produces, on a `readonly` property: SQL over the row, ``(u) => raw`${u.first} || ' ' || ${u.last}` ``, or a relation aggregate, `(order) => order.items.count()`. `stored: true` makes the SQL a generated column; `stored: ['insert', 'update']` makes it a stamp, which a trigger writes on those events whoever writes the row (`computed: currentTimestamp`), where `onUpdate` covers only uql's own writes.
87
- - `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires. `run(newRow, oldRow)` returns the body, written with `insertInto`, `upsertInto` (as `upsertOne` takes it), `updateTable`, `deleteFrom` and `refuse(message)` (fails the write), which are typed by the entity written and render on every engine; `deferred: true` fires an after trigger at commit, on Postgres only; anything else is `raw` SQL over the rows, per engine where they differ. A trigger's writes skip uql's fills and entity filters, soft delete included. MongoDB has none. Details, SQL Server's per-statement shape included: https://uql-orm.dev/entities/triggers.md
86
+ - `@Field({ computed })` is a value the database produces, on a `readonly` property: SQL over the row, ``(u) => sql`${u.first} || ' ' || ${u.last}` ``, or a relation aggregate, `(order) => order.items.count()`. `stored: true` makes the SQL a generated column; `stored: ['insert', 'update']` makes it a stamp, which a trigger writes on those events whoever writes the row (`computed: currentTimestamp`), where `onUpdate` covers only uql's own writes.
87
+ - `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires. `run(newRow, oldRow)` returns the body, written with `insertInto`, `upsertInto` (as `upsertOne` takes it), `updateTable`, `deleteFrom` and `refuse(message)` (fails the write), which are typed by the entity written and render on every engine; `deferred: true` fires an after trigger at commit, on Postgres only; anything else is `sql` SQL over the rows, per engine where they differ. A trigger's writes skip uql's fills and entity filters, soft delete included. MongoDB has none. Details, SQL Server's per-statement shape included: https://uql-orm.dev/entities/triggers.md
88
88
  - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
89
89
 
90
90
  ## Queries
@@ -117,10 +117,10 @@ const users = await pool.findMany(User, {
117
117
  - `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update's payload with its operators (`{ uses: { $inc: 1 } }`), instead of `row`; a new one inserts `row`. An empty `{}` leaves a conflicting row as it is: insert if absent. Cascaded relations write on either branch, a found row's replaced, as `updateMany` does. It resolves to the row's id.
118
118
  - Every write takes `{ returning: { id: true, createdAt: true } }` as its last argument and then resolves to those rows (an update or delete by id: the row or `undefined`), read back in the same transaction; without it, inserts, saves and upserts resolve to ids, updates and deletes to a count.
119
119
  - `updateMany` and `deleteMany` naming no rows - no `$where` holding a value (an empty group holds none), no `$limit` - throw; `{ unfiltered: true }` means the whole table.
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`.
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 `sql` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set`, `$unset`, `$push`, `$pull`.
121
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.
122
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`.
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.
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)`). `sql` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `sql.join(fragments, ' AND ')` joins them. `sql.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `sql` is a tag, so ``sql(`...`)`` does not compile. `raw` is its deprecated former name. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
124
124
 
125
125
  ## Connections and transactions
126
126