uql-orm 0.101.1 → 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 (88) 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/query.d.ts +1 -1
  18. package/dist/http/query.js +4 -4
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/migrate/builder/tableBuilder.js +1 -1
  22. package/dist/migrate/builder/types.d.ts +2 -2
  23. package/dist/migrate/codegen/entityCodeGenerator.js +1 -1
  24. package/dist/migrate/codegen/fieldOptionsSource.js +5 -5
  25. package/dist/migrate/codegen/indexDecoratorSource.d.ts +2 -2
  26. package/dist/migrate/codegen/indexDecoratorSource.js +5 -5
  27. package/dist/migrate/codegen/sourceLiteral.d.ts +2 -2
  28. package/dist/migrate/codegen/sourceLiteral.js +3 -3
  29. package/dist/migrate/ddl/defaultSql.js +1 -1
  30. package/dist/migrate/generator/definitionToNode.d.ts +3 -3
  31. package/dist/migrate/indexPredicate.d.ts +1 -1
  32. package/dist/migrate/indexPredicate.js +5 -5
  33. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +8 -8
  34. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +3 -3
  35. package/dist/migrate/introspection/mssqlIntrospector.d.ts +5 -5
  36. package/dist/migrate/introspection/mssqlIntrospector.js +10 -10
  37. package/dist/migrate/introspection/mysqlIntrospector.d.ts +5 -5
  38. package/dist/migrate/introspection/mysqlIntrospector.js +13 -13
  39. package/dist/migrate/introspection/postgresIntrospector.d.ts +13 -13
  40. package/dist/migrate/introspection/postgresIntrospector.js +21 -21
  41. package/dist/migrate/introspection/sqliteIntrospector.d.ts +4 -4
  42. package/dist/migrate/introspection/sqliteIntrospector.js +6 -6
  43. package/dist/migrate/migrationLock.d.ts +3 -3
  44. package/dist/migrate/migrationLock.js +7 -7
  45. package/dist/migrate/migrationTarget.js +2 -2
  46. package/dist/migrate/migrator.js +2 -2
  47. package/dist/migrate/schemaGenerator.d.ts +1 -1
  48. package/dist/migrate/schemaGenerator.js +1 -1
  49. package/dist/migrate/storage/databaseStorage.d.ts +3 -3
  50. package/dist/migrate/storage/databaseStorage.js +4 -4
  51. package/dist/migrate/triggerSql.js +7 -7
  52. package/dist/mongodb/mongoDialect.js +4 -4
  53. package/dist/mongodb/mongoSchemaGenerator.js +3 -3
  54. package/dist/mssql/mssqlDialect.js +3 -3
  55. package/dist/querier/abstractSqlQuerier.js +1 -1
  56. package/dist/schema/canonicalType.d.ts +1 -1
  57. package/dist/schema/canonicalType.js +6 -6
  58. package/dist/schema/sqlExpression.d.ts +4 -4
  59. package/dist/schema/sqlExpression.js +5 -5
  60. package/dist/sqlite/sqliteDialect.js +2 -2
  61. package/dist/type/dialect.d.ts +3 -3
  62. package/dist/type/entity.d.ts +39 -39
  63. package/dist/type/index.d.ts +1 -1
  64. package/dist/type/index.js +1 -1
  65. package/dist/type/migration.d.ts +1 -1
  66. package/dist/type/querier.d.ts +5 -5
  67. package/dist/type/query.d.ts +32 -32
  68. package/dist/type/queryAggregate.d.ts +2 -2
  69. package/dist/type/{queryRaw.d.ts → querySql.d.ts} +33 -33
  70. package/dist/type/{queryRaw.js → querySql.js} +17 -17
  71. package/dist/type/queryWhere.d.ts +22 -22
  72. package/dist/type/universalQuerier.d.ts +12 -12
  73. package/dist/type/wire.d.ts +4 -4
  74. package/dist/util/ddlExpression.util.d.ts +4 -4
  75. package/dist/util/ddlExpression.util.js +7 -7
  76. package/dist/util/dialect.util.d.ts +7 -7
  77. package/dist/util/dialect.util.js +4 -4
  78. package/dist/util/fieldOption.util.d.ts +3 -3
  79. package/dist/util/fieldOption.util.js +5 -5
  80. package/dist/util/index.d.ts +1 -1
  81. package/dist/util/index.js +1 -1
  82. package/dist/util/query.util.js +1 -1
  83. package/dist/util/{raw.d.ts → sql.d.ts} +22 -20
  84. package/dist/util/{raw.js → sql.js} +28 -26
  85. package/dist/util/triggerWrite.d.ts +7 -7
  86. package/dist/util/triggerWrite.js +2 -2
  87. package/package.json +1 -1
  88. package/skills/uql-orm/SKILL.md +7 -7
@@ -1,8 +1,8 @@
1
1
  import { fieldOf, getMeta, relationOf } from '../entity/index.js';
2
- import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, } from '../type/index.js';
2
+ import { COUNT_RESULT_KEY, parseQueryLock, QuerySql, RAW_ALIAS, } from '../type/index.js';
3
3
  import { utcTimestamp } from '../util/date.js';
4
4
  import { isExactDecimal, isInlinedExpression, jsonKey, jsonPathKeys } from '../util/field.util.js';
5
- import { isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
5
+ import { isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
6
6
  import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
7
7
  import { kindOf, UqlUsageError } from '../util/uqlError.js';
8
8
  import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
@@ -28,12 +28,12 @@ function projectedKeys(meta, select, exclude, json) {
28
28
  : normalizeScalarFieldSelection(meta, select, exclude);
29
29
  return selected.length || !json ? selected : normalizeScalarFieldSelection(meta);
30
30
  }
31
- /** An item of a `$select` list, which only `raw()` fills: anything else arrived from an untyped client. */
31
+ /** An item of a `$select` list, which only `sql()` fills: anything else arrived from an untyped client. */
32
32
  function selectRaw(item) {
33
- if (item instanceof QueryRaw) {
33
+ if (item instanceof QuerySql) {
34
34
  return item;
35
35
  }
36
- throw new UqlUsageError(`a $select list takes raw() expressions only, not a ${kindOf(item)}: name fields in its map form, { field: true }`);
36
+ throw new UqlUsageError(`a $select list takes sql() expressions only, not a ${kindOf(item)}: name fields in its map form, { field: true }`);
37
37
  }
38
38
  /** `value`, where there is one; a `UqlUsageError` saying `refusal` where there is none. */
39
39
  function orRefuse(value, refusal) {
@@ -150,10 +150,10 @@ export class AbstractSqlDialect extends VectorSqlDialect {
150
150
  createContext(options = {}) {
151
151
  return new SqlQueryContext(this, [], undefined, options.inlineValues);
152
152
  }
153
- /** A statement as it is sent: the SQL `build` writes, or a `raw` renders, and the values it binds. */
153
+ /** A statement as it is sent: the SQL `build` writes, or a `sql` renders, and the values it binds. */
154
154
  compile(build) {
155
155
  const ctx = this.createContext();
156
- if (build instanceof QueryRaw) {
156
+ if (build instanceof QuerySql) {
157
157
  this.getRawValue(ctx, { value: build });
158
158
  }
159
159
  else {
@@ -170,7 +170,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
170
170
  build(fragmentCtx);
171
171
  return fragmentCtx.sql;
172
172
  }
173
- /** A `raw()` rendered in place, an operand or a projected term: bound, the driver would get the object. */
173
+ /** A `sql()` rendered in place, an operand or a projected term: bound, the driver would get the object. */
174
174
  rawFragment(ctx, value, prefix, entity) {
175
175
  return this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, { value, prefix, entity }));
176
176
  }
@@ -184,7 +184,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
184
184
  .filter((part) => part !== '');
185
185
  }
186
186
  addValue(ctx, value) {
187
- if (value instanceof QueryRaw) {
187
+ if (value instanceof QuerySql) {
188
188
  return this.rawFragment(ctx, value);
189
189
  }
190
190
  if (ctx.inlineValues) {
@@ -265,7 +265,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
265
265
  });
266
266
  return [{ sql: `${this.escapeId(opts.prefix, true, true)}*`, bare: true, kinds }];
267
267
  }
268
- return keys.map((key) => key instanceof QueryRaw
268
+ return keys.map((key) => key instanceof QuerySql
269
269
  ? { sql: this.rawFragment(ctx, key, opts.prefix), key: key[RAW_ALIAS] }
270
270
  : this.fieldTerm(ctx, meta, key, opts));
271
271
  }
@@ -521,7 +521,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
521
521
  }
522
522
  compare(ctx, entity, key, val, opts = {}) {
523
523
  const meta = getMeta(entity);
524
- if (val instanceof QueryRaw) {
524
+ if (val instanceof QuerySql) {
525
525
  if (key === '$exists' || key === '$nexists') {
526
526
  ctx.append(key === '$exists' ? 'EXISTS (' : 'NOT EXISTS (');
527
527
  // The read's alias: the enclosing statement declares one, and Postgres forbids reaching past
@@ -579,7 +579,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
579
579
  const childOperand = items.length > 1 || negate || opts.operand;
580
580
  const parts = this.renderOperands(ctx, items, (fragmentCtx, entry) => {
581
581
  // The same scope as the group, so every render option carries over: a trigger's `NEW.` included.
582
- if (entry instanceof QueryRaw) {
582
+ if (entry instanceof QuerySql) {
583
583
  this.getRawValue(fragmentCtx, { ...opts, value: entry });
584
584
  }
585
585
  else {
@@ -831,7 +831,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
831
831
  * dialects use this - PostgreSQL binds JSON through {@link PgLikeSqlDialect.jsonScalarParam} instead.
832
832
  */
833
833
  jsonScalarParam(ctx, value) {
834
- if (value instanceof QueryRaw) {
834
+ if (value instanceof QuerySql) {
835
835
  return this.rawFragment(ctx, value);
836
836
  }
837
837
  return this.jsonCast(this.addValue(ctx, JSON.stringify(value)));
@@ -934,7 +934,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
934
934
  }
935
935
  /**
936
936
  * The `ORDER BY` operands for one key: a JSON path's in each of {@link jsonSortModes}. A key that is
937
- * not a field of `meta` - a `raw()` projection, a `$select` alias - is an output alias, which is never
937
+ * not a field of `meta` - a `sql()` projection, a `$select` alias - is an output alias, which is never
938
938
  * table-qualified and needs no resolving.
939
939
  */
940
940
  sortColumns(ctx, meta, key, prefix) {
@@ -1024,7 +1024,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1024
1024
  count(ctx, entity, q, opts) {
1025
1025
  const { $where, $skip, $limit } = q;
1026
1026
  if ($skip === undefined && $limit === undefined) {
1027
- this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(AGGREGATE_VALUE_ALIAS)] });
1027
+ this.select(ctx, entity, { $select: [sql `COUNT(*)`.as(AGGREGATE_VALUE_ALIAS)] });
1028
1028
  this.search(ctx, entity, { $where }, opts);
1029
1029
  return;
1030
1030
  }
@@ -1364,7 +1364,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1364
1364
  else if (isFieldUpdateOp(value)) {
1365
1365
  const [op, operand] = fieldUpdateOf(key, value);
1366
1366
  ctx.append(`${escapedCol} = COALESCE(${current}, 0) ${SQL_ARITHMETIC[op]} `);
1367
- if (operand instanceof QueryRaw) {
1367
+ if (operand instanceof QuerySql) {
1368
1368
  ctx.append('(');
1369
1369
  this.getRawValue(ctx, { value: operand, escapedPrefix: qualifier });
1370
1370
  ctx.append(')');
@@ -1373,7 +1373,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1373
1373
  ctx.addValue(operand);
1374
1374
  }
1375
1375
  }
1376
- else if (value instanceof QueryRaw) {
1376
+ else if (value instanceof QuerySql) {
1377
1377
  ctx.append(`${escapedCol} = `);
1378
1378
  this.getRawValue(ctx, { value, escapedPrefix: qualifier });
1379
1379
  }
@@ -1438,7 +1438,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1438
1438
  ctx.append(` FROM ${rows.from}`);
1439
1439
  }
1440
1440
  const narrowed = rows?.where;
1441
- const where = narrowed ? { $and: [write.where, raw(() => narrowed)] } : write.where;
1441
+ const where = narrowed ? { $and: [write.where, sql(() => narrowed)] } : write.where;
1442
1442
  // Qualified by the table: on a set-based engine `inserted` holds the same column names.
1443
1443
  this.renderWhere(ctx, write.entity, where, { escapedPrefix: `${table}.` });
1444
1444
  ctx.append(';');
@@ -1526,7 +1526,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1526
1526
  /** `key`'s column of the row being inserted, as SQL an assignment takes. */
1527
1527
  incoming(meta, key) {
1528
1528
  const column = this.escapedColumnName(meta, key);
1529
- return raw(() => this.upsertIncoming(column));
1529
+ return sql(() => this.upsertIncoming(column));
1530
1530
  }
1531
1531
  /**
1532
1532
  * What a conflicting row takes: `update` where given, else the incoming row less the conflict paths, and what
@@ -1658,7 +1658,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1658
1658
  }
1659
1659
  /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
1660
1660
  writePersistableValue(ctx, kind, field, value) {
1661
- if (value instanceof QueryRaw) {
1661
+ if (value instanceof QuerySql) {
1662
1662
  this.getRawValue(ctx, { value });
1663
1663
  return;
1664
1664
  }
@@ -1744,7 +1744,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1744
1744
  }
1745
1745
  compileDdl(sql, entity, { rows, escapedPrefix, operand } = {}) {
1746
1746
  const ctx = this.createContext({ inlineValues: true });
1747
- if (sql instanceof QueryRaw) {
1747
+ if (sql instanceof QuerySql) {
1748
1748
  sql.render({ ctx, dialect: this, prefix: '', escapedPrefix: escapedPrefix ?? '', entity, rows });
1749
1749
  }
1750
1750
  else if (entity) {
@@ -1898,11 +1898,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1898
1898
  appendRelationPage(ctx, meta, rel, aggregate, parent) {
1899
1899
  const entity = rel.entity();
1900
1900
  const alias = ctx.claimAlias(aggregate.relation, parent);
1901
- const correlation = raw(({ ctx: pageCtx }) => this.appendCorrelation(pageCtx, meta, rel, parent, alias));
1901
+ const correlation = sql(({ ctx: pageCtx }) => this.appendCorrelation(pageCtx, meta, rel, parent, alias));
1902
1902
  const { where: $where, page } = aggregate;
1903
1903
  // `1` where nothing is aggregated: a tally counts the rows the page holds, whatever they carry.
1904
1904
  const { field } = aggregate;
1905
- const read = field ? refs(entity)[field] : raw `1`;
1905
+ const read = field ? refs(entity)[field] : sql `1`;
1906
1906
  const query = {
1907
1907
  ...page,
1908
1908
  $select: [read.as(AGGREGATE_VALUE_ALIAS)],
@@ -1963,7 +1963,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1963
1963
  const relMeta = getMeta(entity);
1964
1964
  this.assertDistinctSort(relMeta, relKey, query);
1965
1965
  const alias = ctx.claimAlias(relKey, parent);
1966
- const correlation = raw(({ ctx: rowsCtx }) => this.appendCorrelation(rowsCtx, meta, relation, parent, alias));
1966
+ const correlation = sql(({ ctx: rowsCtx }) => this.appendCorrelation(rowsCtx, meta, relation, parent, alias));
1967
1967
  const rows = { ...query, $where: whereAnd(query.$where, [correlation]) };
1968
1968
  const joins = resolveQueryJoins(relMeta, rows, (path) => ctx.claimAlias(path));
1969
1969
  return this.appendRelationArray(ctx, { entity, query: rows, alias, joins, distinct });
@@ -1,4 +1,4 @@
1
- import { QueryRaw, VECTOR_QUERY_KEYS, } from '../type/index.js';
1
+ import { QuerySql, VECTOR_QUERY_KEYS, } from '../type/index.js';
2
2
  import { isOperatorMap } from '../util/dialect.util.js';
3
3
  import { hasKeys, isWhereMap, someKey } from '../util/object.util.js';
4
4
  import { kindOf, UqlUsageError } from '../util/uqlError.js';
@@ -34,7 +34,7 @@ export function groupClauses(key, val) {
34
34
  export function namesRows(where) {
35
35
  return (where !== undefined &&
36
36
  someKey(where, (key) => isGroupOp(key)
37
- ? groupClauses(key, where[key]).some((clause) => clause instanceof QueryRaw || namesRows(clause))
37
+ ? groupClauses(key, where[key]).some((clause) => clause instanceof QuerySql || namesRows(clause))
38
38
  : !(isWhereMap(where[key]) && !hasKeys(where[key]))));
39
39
  }
40
40
  /**
@@ -127,7 +127,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
127
127
  */
128
128
  protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
129
129
  /**
130
- * The plain values merge as one bound object; a `raw()` one is an SQL expression rather than JSON,
130
+ * The plain values merge as one bound object; a `sql()` one is an SQL expression rather than JSON,
131
131
  * so it merges through `JSONB_BUILD_OBJECT` and is evaluated in place - stringified with the rest,
132
132
  * it would land as `{}`.
133
133
  */
@@ -1,4 +1,4 @@
1
- import { QueryRaw, } from '../type/index.js';
1
+ import { QuerySql, } from '../type/index.js';
2
2
  import { bytesToHex } from '../util/bytes.js';
3
3
  import { fulltextConfig, fulltextIndexOver, hasVectorNear, textSearchFields } from '../util/dialect.util.js';
4
4
  import { isIntegerColumn, jsonPathKeys } from '../util/field.util.js';
@@ -285,14 +285,14 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
285
285
  return `JSONB_SET(${expr}, '{"${key}"}', ${pulled}, false)`;
286
286
  }
287
287
  /**
288
- * The plain values merge as one bound object; a `raw()` one is an SQL expression rather than JSON,
288
+ * The plain values merge as one bound object; a `sql()` one is an SQL expression rather than JSON,
289
289
  * so it merges through `JSONB_BUILD_OBJECT` and is evaluated in place - stringified with the rest,
290
290
  * it would land as `{}`.
291
291
  */
292
292
  jsonSet(ctx, expr, set, field) {
293
293
  const entries = Object.entries(set);
294
- const merged = this.jsonVal(ctx, Object.fromEntries(entries.filter(([, value]) => !(value instanceof QueryRaw))));
295
- const raws = entries.flatMap(([key, value]) => value instanceof QueryRaw ? [` || JSONB_BUILD_OBJECT('${key}', ${this.rawFragment(ctx, value)})`] : []);
294
+ const merged = this.jsonVal(ctx, Object.fromEntries(entries.filter(([, value]) => !(value instanceof QuerySql))));
295
+ const raws = entries.flatMap(([key, value]) => value instanceof QuerySql ? [` || JSONB_BUILD_OBJECT('${key}', ${this.rawFragment(ctx, value)})`] : []);
296
296
  return `${jsonSetTarget(expr, field, `'{}'::jsonb`)} || ${merged}${raws.join('')}`;
297
297
  }
298
298
  /** The only fragment that references `expr` twice - safe here because placeholders are numbered. */
@@ -313,7 +313,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
313
313
  * Helper to add a JSON value to context with appropriate stringification and cast.
314
314
  */
315
315
  jsonVal(ctx, value, type = 'jsonb') {
316
- if (value instanceof QueryRaw)
316
+ if (value instanceof QuerySql)
317
317
  return this.rawFragment(ctx, value);
318
318
  if (value == null)
319
319
  return `${this.addValue(ctx, null)}::${type}`;
@@ -8,7 +8,7 @@ export declare class SqlQueryContext implements QueryContext {
8
8
  private readonly params;
9
9
  private readonly tableAliases;
10
10
  /**
11
- * `params` and `statement` are a fragment's parent's, so a value numbers against the whole statement and
11
+ * `params` and `sql` are a fragment's parent's, so a value numbers against the whole statement and
12
12
  * an alias is unique across it; a fragment inlines values where its statement does.
13
13
  */
14
14
  constructor(dialect: SqlQueryDialect, params?: unknown[], statement?: SqlQueryContext | undefined, inlineValues?: boolean);
@@ -7,7 +7,7 @@ export class SqlQueryContext {
7
7
  params;
8
8
  tableAliases = new Set();
9
9
  /**
10
- * `params` and `statement` are a fragment's parent's, so a value numbers against the whole statement and
10
+ * `params` and `sql` are a fragment's parent's, so a value numbers against the whole statement and
11
11
  * an alias is unique across it; a fragment inlines values where its statement does.
12
12
  */
13
13
  constructor(dialect, params = [], statement, inlineValues = false) {
@@ -75,7 +75,7 @@ export class VectorSqlDialect extends AbstractDialect {
75
75
  */
76
76
  appendVectorDistance(ctx, meta, key, search, prefix) {
77
77
  if (this.vectorMetrics.size === 0) {
78
- throw new UqlUsageError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
78
+ throw new UqlUsageError(`${this.dialectName} does not support vector similarity search. Use sql() for vector queries.`);
79
79
  }
80
80
  const { colName, distance, field } = this.resolveVectorDistance(meta, key, search);
81
81
  const metric = this.vectorMetrics.get(distance);
@@ -13,11 +13,11 @@ export declare function Filter<E, N extends string>(name: FilterName<N>, opts: F
13
13
  /**
14
14
  * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
15
15
  * does not compile and a rename reaches every column. Stacks, so several may sit above one class.
16
- * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
16
+ * @example `@Index((user) => [user.lastName, sql`lower(${user.email})`], { unique: true })`
17
17
  */
18
18
  export declare function Index<E>(columns: (refs: RefMap<E>) => readonly EntityIndexColumnInput<E>[], options?: EntityIndexOptions<E>): (entity: Type<E>) => void;
19
19
  /**
20
20
  * Declares triggers the database runs, in the order written. Stacks, so several may sit above one class.
21
- * @example ``@Trigger({ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => raw`...` })``
21
+ * @example ``@Trigger({ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => sql`...` })``
22
22
  */
23
23
  export declare function Trigger<E>(...triggers: readonly TriggerOptions<E>[]): (entity: Type<E>) => void;
@@ -25,7 +25,7 @@ export function Filter(name, opts) {
25
25
  /**
26
26
  * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
27
27
  * does not compile and a rename reaches every column. Stacks, so several may sit above one class.
28
- * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
28
+ * @example `@Index((user) => [user.lastName, sql`lower(${user.email})`], { unique: true })`
29
29
  */
30
30
  export function Index(columns, options = {}) {
31
31
  return (entity) => {
@@ -34,7 +34,7 @@ export function Index(columns, options = {}) {
34
34
  }
35
35
  /**
36
36
  * Declares triggers the database runs, in the order written. Stacks, so several may sit above one class.
37
- * @example ``@Trigger({ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => raw`...` })``
37
+ * @example ``@Trigger({ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => sql`...` })``
38
38
  */
39
39
  export function Trigger(...triggers) {
40
40
  return (entity) => {
@@ -19,7 +19,7 @@ export declare function parseQueryParams<E = unknown>(params?: unknown): WireQue
19
19
  export declare function stringifyQuery(query?: Record<string, unknown>): string;
20
20
  /**
21
21
  * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server
22
- * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not
22
+ * build a statement around the remains. A `sql` fragment renders SQL against a dialect the client does not
23
23
  * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it
24
24
  * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,
25
25
  * hits where the client's types already refuse a fragment.
@@ -1,8 +1,8 @@
1
1
  // the clause table itself, not the barrel: this module is in the browser bundle's graph
2
2
  import { QUERY_CLAUSES } from '../type/query.js';
3
- // the brand alone, not the class: importing `QueryRaw` for an `instanceof` kept it, and `ColumnRef`
3
+ // the brand alone, not the class: importing `QuerySql` for an `instanceof` kept it, and `ColumnRef`
4
4
  // with it, in the browser bundle, which is on a size budget
5
- import { RAW_VALUE } from '../type/queryRaw.js';
5
+ import { SQL_FN } from '../type/querySql.js';
6
6
  // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
7
7
  import { getKeys, isRecord, isWhereMap } from '../util/object.util.js';
8
8
  // the error class alone, from its own leaf module: `queryError.ts` carries every driver's code map
@@ -98,7 +98,7 @@ export function stringifyQuery(query) {
98
98
  }
99
99
  /**
100
100
  * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server
101
- * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not
101
+ * build a statement around the remains. A `sql` fragment renders SQL against a dialect the client does not
102
102
  * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it
103
103
  * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,
104
104
  * hits where the client's types already refuse a fragment.
@@ -108,7 +108,7 @@ export function wireJson(value) {
108
108
  if (typeof held !== 'object' || held === null) {
109
109
  return held;
110
110
  }
111
- if (RAW_VALUE in held) {
111
+ if (SQL_FN in held) {
112
112
  throw new UqlUsageError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
113
113
  }
114
114
  // A blob is a field value, so no type parameter reaches it: this is the only place it is caught.
package/dist/index.d.ts CHANGED
@@ -9,6 +9,6 @@ export { idKey, isSqlQuerier, versionKey } from './type/index.js';
9
9
  export { withDeleted } from './util/filters.util.js';
10
10
  export type { HookContext } from './util/hook.util.js';
11
11
  export { DefaultLogger } from './util/logger.js';
12
- export { currentDate, currentTime, currentTimestamp, raw, refs, uuid, uuidv7 } from './util/raw.js';
12
+ export { currentDate, currentTime, currentTimestamp, raw, refs, sql, uuid, uuidv7 } from './util/sql.js';
13
13
  export { deleteFrom, insertInto, refuse, updateTable, upsertInto } from './util/triggerWrite.js';
14
14
  export { type QueryErrorKind, UqlError, UqlOptimisticLockError, UqlSecurityError, UqlUsageError, } from './util/uqlError.js';
package/dist/index.js CHANGED
@@ -7,6 +7,6 @@ export { queryErrorKind } from './querier/queryError.js';
7
7
  export { idKey, isSqlQuerier, versionKey } from './type/index.js';
8
8
  export { withDeleted } from './util/filters.util.js';
9
9
  export { DefaultLogger } from './util/logger.js';
10
- export { currentDate, currentTime, currentTimestamp, raw, refs, uuid, uuidv7 } from './util/raw.js';
10
+ export { currentDate, currentTime, currentTimestamp, raw, refs, sql, uuid, uuidv7 } from './util/sql.js';
11
11
  export { deleteFrom, insertInto, refuse, updateTable, upsertInto } from './util/triggerWrite.js';
12
12
  export { UqlError, UqlOptimisticLockError, UqlSecurityError, UqlUsageError, } from './util/uqlError.js';
@@ -4,7 +4,7 @@
4
4
  * Fluent API for defining tables in migrations.
5
5
  */
6
6
  import { DATE_PRECISION } from '../../util/date.js';
7
- import { currentTimestamp } from '../../util/raw.js';
7
+ import { currentTimestamp } from '../../util/sql.js';
8
8
  import { columnForeignKey, columnIndex, indexDefinition } from '../generator/definitionToNode.js';
9
9
  import { ColumnDefinitionBuilder } from './columnBuilder.js';
10
10
  /** Normalizes `table.index` options, where a bare string is the index name. */
@@ -5,7 +5,7 @@
5
5
  * Enables type-safe migrations without raw SQL.
6
6
  */
7
7
  import type { ColumnNode, EnumValues, ForeignKeyAction } from '../../schema/types.js';
8
- import type { EntityIndexColumn, Except, IndexColumnInput, IndexOptions, IndexSchema, QueryRaw } from '../../type/index.js';
8
+ import type { EntityIndexColumn, Except, IndexColumnInput, IndexOptions, IndexSchema, QuerySql } from '../../type/index.js';
9
9
  import type { ForeignKeySchema } from '../../type/migration.js';
10
10
  /**
11
11
  * Foreign key reference options.
@@ -92,7 +92,7 @@ export interface FullColumnDefinition extends ColumnDefinition {
92
92
  */
93
93
  export type IndexDefinition = Except<IndexSchema, 'entries' | 'where'> & {
94
94
  readonly entries: readonly EntityIndexColumn[];
95
- readonly where?: QueryRaw;
95
+ readonly where?: QuerySql;
96
96
  };
97
97
  /**
98
98
  * Complete table definition.
@@ -94,7 +94,7 @@ export class EntityCodeGenerator {
94
94
  uqlImports.add('Index');
95
95
  }
96
96
  if (declared.some(indexNeedsRaw)) {
97
- uqlImports.add('raw');
97
+ uqlImports.add('sql');
98
98
  }
99
99
  }
100
100
  return [
@@ -2,7 +2,7 @@ import { canonicalToColumnType, isVectorCategory } from '../../schema/canonicalT
2
2
  import { SqlExpression } from '../../schema/sqlExpression.js';
3
3
  import { DATE_PRECISION } from '../../util/date.js';
4
4
  import { isAutoIncrement } from '../../util/field.util.js';
5
- import { quoted, rawTag } from './sourceLiteral.js';
5
+ import { quoted, sqlTag } from './sourceLiteral.js';
6
6
  /** What each field of a {@link ColumnNode} contributes to `@Field({ ... })`, in emit order; `satisfies` makes a new field answer. */
7
7
  const OPTION_SOURCE = {
8
8
  // Without this the entity maps to a column named after the property, which for anything the
@@ -24,7 +24,7 @@ const OPTION_SOURCE = {
24
24
  nullable: (col) => (col.nullable || col.isPrimaryKey ? [] : ['nullable: false']),
25
25
  isUnique: (col) => (col.isUnique ? ['unique: true'] : []),
26
26
  defaultValue: (col) => col.defaultValue === undefined ? [] : [`defaultValue: ${defaultValueSource(col.defaultValue)}`],
27
- generatedAs: (col) => (col.generatedAs ? [`computed: ${rawTag(col.generatedAs)}`, 'stored: true'] : []),
27
+ generatedAs: (col) => (col.generatedAs ? [`computed: ${sqlTag(col.generatedAs)}`, 'stored: true'] : []),
28
28
  comment: (col) => (col.comment ? [`comment: ${quoted(col.comment)}`] : []),
29
29
  // A key is `@Id`, which says it on its own, and generates where `isAutoIncrement` says, which only a
30
30
  // column the database treats otherwise contradicts.
@@ -51,7 +51,7 @@ export function buildFieldOptionsSource(col, propertyName, indexName) {
51
51
  /** The uql imports the field's decorator needs besides `Field`, as {@link indexNeedsRaw} tells for an index. */
52
52
  export function fieldImports(col) {
53
53
  const sql = SqlExpression.isExpression(col.defaultValue) ? [sqlDefaultSource(col.defaultValue).name] : [];
54
- return [...(col.generatedAs === undefined ? [] : ['raw']), ...sql];
54
+ return [...(col.generatedAs === undefined ? [] : ['sql']), ...sql];
55
55
  }
56
56
  /** A default value as source code: SQL the way an entity declares it, a string single-quoted and escaped. */
57
57
  function defaultValueSource(value) {
@@ -62,8 +62,8 @@ function defaultValueSource(value) {
62
62
  }
63
63
  /**
64
64
  * A SQL default as an entity declares it, with the name to import for it: the value uql exports by its own
65
- * name (`currentTimestamp`), and `raw` for any other SQL, as introspection reads it back.
65
+ * name (`currentTimestamp`), and `sql` for any other SQL, as introspection reads it back.
66
66
  */
67
67
  function sqlDefaultSource({ kind, sql }) {
68
- return sql === undefined ? { name: kind, source: kind } : { name: 'raw', source: rawTag(sql) };
68
+ return sql === undefined ? { name: kind, source: kind } : { name: 'sql', source: sqlTag(sql) };
69
69
  }
@@ -8,9 +8,9 @@ import type { IndexNode } from '../../schema/types.js';
8
8
  export declare function isPlainFieldIndex(index: IndexNode): boolean;
9
9
  /**
10
10
  * One `@Index((user) => [...])` as source, for an index no `@Field` can express, its columns read off the
11
- * refs `param` names. Emits `raw` for an expression entry, so callers import `raw` when
11
+ * refs `param` names. Emits `sql` for an expression entry, so callers import `sql` when
12
12
  * {@link indexNeedsRaw} holds.
13
13
  */
14
14
  export declare function buildIndexDecoratorSource(index: IndexNode, propertyName: (column: string) => string, param: string): string;
15
- /** Whether emitting this index needs `raw` imported alongside `Index`. */
15
+ /** Whether emitting this index needs `sql` imported alongside `Index`. */
16
16
  export declare function indexNeedsRaw(index: IndexNode): boolean;
@@ -1,6 +1,6 @@
1
1
  import { isVectorIndexType } from '../../type/index.js';
2
2
  import { fulltextConfig } from '../../util/dialect.util.js';
3
- import { memberSource, quoted, rawTag } from './sourceLiteral.js';
3
+ import { memberSource, quoted, sqlTag } from './sourceLiteral.js';
4
4
  /**
5
5
  * The options each field of an index entry writes into `@Index`, in emit order; `satisfies` forces every new
6
6
  * field to be listed. Defaults are skipped: Postgres reports each entry in full (`order: 'asc', nulls: 'last'`
@@ -34,7 +34,7 @@ const INDEX_OPTION_SOURCE = {
34
34
  const config = fulltextConfig(index);
35
35
  return index.type === 'fulltext' && config !== fulltextConfig({}) ? [`config: ${quoted(config)}`] : [];
36
36
  },
37
- where: (index) => (index.where ? [`where: ${rawTag(index.where)}`] : []),
37
+ where: (index) => (index.where ? [`where: ${sqlTag(index.where)}`] : []),
38
38
  include: (index, { param, propertyName }) => {
39
39
  const included = index.include?.map((column) => memberSource(param, propertyName(column))) ?? [];
40
40
  return included.length ? [`include: (${param}) => [${included.join(', ')}]`] : [];
@@ -80,7 +80,7 @@ export function isPlainFieldIndex(index) {
80
80
  }
81
81
  /**
82
82
  * One `@Index((user) => [...])` as source, for an index no `@Field` can express, its columns read off the
83
- * refs `param` names. Emits `raw` for an expression entry, so callers import `raw` when
83
+ * refs `param` names. Emits `sql` for an expression entry, so callers import `sql` when
84
84
  * {@link indexNeedsRaw} holds.
85
85
  */
86
86
  export function buildIndexDecoratorSource(index, propertyName, param) {
@@ -89,12 +89,12 @@ export function buildIndexDecoratorSource(index, propertyName, param) {
89
89
  const options = Object.values(INDEX_OPTION_SOURCE).flatMap((source) => source?.(index, context) ?? []);
90
90
  return `@Index((${param}) => [${entries}]${options.length > 0 ? `, { ${options.join(', ')} }` : ''})`;
91
91
  }
92
- /** Whether emitting this index needs `raw` imported alongside `Index`. */
92
+ /** Whether emitting this index needs `sql` imported alongside `Index`. */
93
93
  export function indexNeedsRaw(index) {
94
94
  return Boolean(index.where) || index.entries.some((entry) => entry.expression);
95
95
  }
96
96
  function indexEntrySource(entry, { param, propertyName }) {
97
- const column = entry.expression ? rawTag(entry.column) : memberSource(param, propertyName(entry.column));
97
+ const column = entry.expression ? sqlTag(entry.column) : memberSource(param, propertyName(entry.column));
98
98
  const modifiers = entryModifiers(entry);
99
99
  return modifiers.length === 0 ? column : `{ column: ${column}, ${modifiers.join(', ')} }`;
100
100
  }
@@ -14,5 +14,5 @@ export declare function memberSource(param: string, property: string): string;
14
14
  * need none, which keeps multi-line SQL readable in the generated file.
15
15
  */
16
16
  export declare function templateOf(sql: string): string;
17
- /** SQL as a `raw` tagged template. */
18
- export declare function rawTag(sql: string): string;
17
+ /** SQL as a `sql` tagged template. */
18
+ export declare function sqlTag(sql: string): string;
@@ -22,7 +22,7 @@ export function memberSource(param, property) {
22
22
  export function templateOf(sql) {
23
23
  return `\`${sql.replace(/[\\`]|\$\{/g, (char) => `\\${char}`)}\``;
24
24
  }
25
- /** SQL as a `raw` tagged template. */
26
- export function rawTag(sql) {
27
- return `raw${templateOf(sql)}`;
25
+ /** SQL as a `sql` tagged template. */
26
+ export function sqlTag(sql) {
27
+ return `sql${templateOf(sql)}`;
28
28
  }
@@ -101,7 +101,7 @@ function expressionSql({ kind, sql }, dialect, columnType) {
101
101
  const precision = columnType === undefined ? undefined : preciseTypes.exec(columnType)?.[1];
102
102
  return precision ? `CURRENT_TIMESTAMP(${precision})` : 'CURRENT_TIMESTAMP';
103
103
  }
104
- const spelled = kind === 'raw' ? undefined : dialect.sqlValues[kind];
104
+ const spelled = kind === 'sql' ? undefined : dialect.sqlValues[kind];
105
105
  if (spelled === undefined) {
106
106
  throw new UqlUsageError(`${dialect.dialectName} has no ${kind}; write it as raw SQL this engine accepts`);
107
107
  }
@@ -1,14 +1,14 @@
1
1
  import type { TableNode } from '../../schema/types.js';
2
2
  import type { IndexColumnInput, IndexOptions } from '../../type/entity.js';
3
3
  import type { ForeignKeySchema, IndexSchema } from '../../type/migration.js';
4
- import type { QueryRaw } from '../../type/queryRaw.js';
4
+ import type { QuerySql } from '../../type/querySql.js';
5
5
  import type { ColumnDefinition, FullColumnDefinition, IndexDefinition, TableDefinition } from '../builder/types.js';
6
6
  /**
7
7
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
8
8
  * `createTable` and an entity reach `generateCreateTableFromNode` in the same shape, its SQL rendered by
9
9
  * `render`. Free functions and not generator methods: the dialect reaches them only through `render`.
10
10
  */
11
- export declare function tableDefinitionToNode(def: TableDefinition, render: (sql: QueryRaw) => string): TableNode;
11
+ export declare function tableDefinitionToNode(def: TableDefinition, render: (sql: QuerySql) => string): TableNode;
12
12
  /** A builder's column without its `index`, `foreignKey` and `enum`, which are lifted onto the table. */
13
13
  export declare function bareColumn({ index: _index, foreignKey: _foreignKey, enum: _enum, ...column }: FullColumnDefinition): ColumnDefinition;
14
14
  /**
@@ -25,6 +25,6 @@ export declare function columnIndex(tableName: string, col: FullColumnDefinition
25
25
  */
26
26
  export declare function indexDefinition(tableName: string, columns: readonly IndexColumnInput[], { name, unique, ...options }?: IndexOptions, uniqueName?: boolean): IndexDefinition;
27
27
  /** An index the builder recorded, its SQL rendered by `render` into the text the schema holds. */
28
- export declare function renderIndexDefinition(index: IndexDefinition, render: (sql: QueryRaw) => string): IndexSchema;
28
+ export declare function renderIndexDefinition(index: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
29
29
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
30
30
  export declare function columnForeignKey(col: FullColumnDefinition): ForeignKeySchema | undefined;
@@ -1,7 +1,7 @@
1
1
  import type { DialectName, EntityWhereMeta } from '../type/index.js';
2
2
  /**
3
3
  * Refuses a partial index's predicate reaching past what the engine takes, before it compiles to what
4
- * only the server would reject, naming the operator as its author wrote it. A `raw` one is left to the server.
4
+ * only the server would reject, naming the operator as its author wrote it. A `sql` one is left to the server.
5
5
  */
6
6
  export declare function assertIndexPredicate<E>(where: EntityWhereMeta<E>, dialectName: DialectName, indexName: string): void;
7
7
  /** What refusing any part of a partial index's predicate reports. */
@@ -1,4 +1,4 @@
1
- import { QueryRaw } from '../type/queryRaw.js';
1
+ import { QuerySql } from '../type/querySql.js';
2
2
  import { isOperatorObject } from '../util/object.util.js';
3
3
  import { UqlUsageError } from '../util/uqlError.js';
4
4
  /**
@@ -20,11 +20,11 @@ const PREDICATE_GRAMMARS = {
20
20
  };
21
21
  /**
22
22
  * Refuses a partial index's predicate reaching past what the engine takes, before it compiles to what
23
- * only the server would reject, naming the operator as its author wrote it. A `raw` one is left to the server.
23
+ * only the server would reject, naming the operator as its author wrote it. A `sql` one is left to the server.
24
24
  */
25
25
  export function assertIndexPredicate(where, dialectName, indexName) {
26
26
  const grammar = PREDICATE_GRAMMARS[dialectName];
27
- const refused = grammar && !(where instanceof QueryRaw) ? refusedOperator(where, grammar) : undefined;
27
+ const refused = grammar && !(where instanceof QuerySql) ? refusedOperator(where, grammar) : undefined;
28
28
  if (refused) {
29
29
  throw refusedIndexPredicate(dialectName, refused, indexName);
30
30
  }
@@ -33,7 +33,7 @@ export function assertIndexPredicate(where, dialectName, indexName) {
33
33
  export function refusedIndexPredicate(dialectName, part, indexName) {
34
34
  return new UqlUsageError(`${dialectName} does not support ${part} in a partial index predicate (index "${indexName}")`);
35
35
  }
36
- /** The first part of `where` outside `grammar`, depth-first; a `raw` clause is left alone. */
36
+ /** The first part of `where` outside `grammar`, depth-first; a `sql` clause is left alone. */
37
37
  function refusedOperator(where, grammar) {
38
38
  return Object.entries(where)
39
39
  .map(([key, value]) => {
@@ -46,7 +46,7 @@ function refusedOperator(where, grammar) {
46
46
  if (!grammar.rootOps.has(key)) {
47
47
  return key;
48
48
  }
49
- const clauses = Array.isArray(value) ? value.filter((clause) => !(clause instanceof QueryRaw)) : [];
49
+ const clauses = Array.isArray(value) ? value.filter((clause) => !(clause instanceof QuerySql)) : [];
50
50
  return clauses.map((clause) => refusedOperator(clause, grammar)).find(Boolean);
51
51
  })
52
52
  .find(Boolean);