@atscript/db-sql-tools 0.1.148 → 0.1.150

package/dist/index.cjs

@@ -80,6 +80,14 @@ const EMPTY_OR = {
 	sql: "0=1",
 	params: []
 };
+/** ORs predicate parts (parenthesized when several); no parts matches nothing. */
+function orFragment(parts, params) {
+	if (parts.length === 0) return EMPTY_OR;
+	return {
+		sql: parts.length === 1 ? parts[0] : `(${parts.join(" OR ")})`,
+		params
+	};
+}
 //#endregion
 //#region src/arith.ts
 /**
@@ -220,6 +228,7 @@ function createFilterVisitor(dialect, options) {
 					params: []
 				};
 				case "$regex": return dialect.regex(col, value);
+				case _atscript_db.INTEGER_REGEX_OP: return dialect.regex(dialect.integerText ? dialect.integerText(col) : `CAST(${col} AS TEXT)`, value);
 				default: throw new Error(`Unsupported filter operator: ${String(op)}`);
 			}
 		},
@@ -1114,7 +1123,10 @@ function fillReplacePayload(data, columns, versionColumn) {
 *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
 *   `versionColumn` is set, regardless of whether `expectedVersion` is
 *   supplied. If the version column doesn't auto-increment on every write,
-*   OCC silently degrades to no protection.
+*   OCC silently degrades to no protection. A caller that must not bump (a
+*   version-exempt patch, `TDbUpdateOptions.keepVersion`) passes
+*   `versionColumn: undefined`, which also drops the CAS predicate — callers
+*   never combine that with `expectedVersion`.
 * - `expectedVersion` — when supplied, the builder appends
 *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
 *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
@@ -1482,6 +1494,7 @@ exports.jsonDollarPath = jsonDollarPath;
 exports.mapQueryErrors = mapQueryErrors;
 exports.normalizeGeoPointValue = normalizeGeoPointValue;
 exports.numericOutOfRangeError = numericOutOfRangeError;
+exports.orFragment = orFragment;
 exports.orderKeySql = orderKeySql;
 exports.parseRegexString = parseRegexString;
 exports.queryNodeToSql = queryNodeToSql;

package/dist/index.d.cts

@@ -25,6 +25,13 @@ interface SqlDialect {
   toParam(value: unknown): unknown;
   /** Handle $regex filter */
   regex(quotedCol: string, value: unknown): TSqlFragment;
+  /**
+   * The canonical decimal text of an integer column (`29461277`, `-12` — no
+   * `.0`, no exponent), as an SQL expression over the quoted column. Backs
+   * `$regex` on integer fields. Defaults to `CAST(<col> AS TEXT)`.
+   * @since 0.1.150
+   */
+  integerText?(quotedExpr: string): string;
   /**
    * Handle `$geoWithin` filter — circle search on a `db.geoPoint` column.
    * The circle is pre-validated by the core layer (`center` is a `[lng, lat]`
@@ -174,6 +181,8 @@ declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean):
 declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
+/** ORs predicate parts (parenthesized when several); no parts matches nothing. */
+declare function orFragment(parts: string[], params: unknown[]): TSqlFragment;
 //#endregion
 //#region src/arith.d.ts
 /** Why {@link renderArith} cannot render an expression. */
@@ -489,7 +498,10 @@ declare function fillReplacePayload(data: Record<string, unknown>, columns: read
  *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
  *   `versionColumn` is set, regardless of whether `expectedVersion` is
  *   supplied. If the version column doesn't auto-increment on every write,
- *   OCC silently degrades to no protection.
+ *   OCC silently degrades to no protection. A caller that must not bump (a
+ *   version-exempt patch, `TDbUpdateOptions.keepVersion`) passes
+ *   `versionColumn: undefined`, which also drops the CAS predicate — callers
+ *   never combine that with `expectedVersion`.
  * - `expectedVersion` — when supplied, the builder appends
  *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
  *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
@@ -626,4 +638,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/dist/index.d.mts

@@ -25,6 +25,13 @@ interface SqlDialect {
   toParam(value: unknown): unknown;
   /** Handle $regex filter */
   regex(quotedCol: string, value: unknown): TSqlFragment;
+  /**
+   * The canonical decimal text of an integer column (`29461277`, `-12` — no
+   * `.0`, no exponent), as an SQL expression over the quoted column. Backs
+   * `$regex` on integer fields. Defaults to `CAST(<col> AS TEXT)`.
+   * @since 0.1.150
+   */
+  integerText?(quotedExpr: string): string;
   /**
    * Handle `$geoWithin` filter — circle search on a `db.geoPoint` column.
    * The circle is pre-validated by the core layer (`center` is a `[lng, lat]`
@@ -174,6 +181,8 @@ declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean):
 declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
+/** ORs predicate parts (parenthesized when several); no parts matches nothing. */
+declare function orFragment(parts: string[], params: unknown[]): TSqlFragment;
 //#endregion
 //#region src/arith.d.ts
 /** Why {@link renderArith} cannot render an expression. */
@@ -489,7 +498,10 @@ declare function fillReplacePayload(data: Record<string, unknown>, columns: read
  *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
  *   `versionColumn` is set, regardless of whether `expectedVersion` is
  *   supplied. If the version column doesn't auto-increment on every write,
- *   OCC silently degrades to no protection.
+ *   OCC silently degrades to no protection. A caller that must not bump (a
+ *   version-exempt patch, `TDbUpdateOptions.keepVersion`) passes
+ *   `versionColumn: undefined`, which also drops the CAS predicate — callers
+ *   never combine that with `expectedVersion`.
  * - `expectedVersion` — when supplied, the builder appends
  *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
  *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
@@ -626,4 +638,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { DbError, aggregateExpressionsNotSupported, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter } from "@atscript/db";
+import { DbError, INTEGER_REGEX_OP, aggregateExpressionsNotSupported, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter } from "@atscript/db";
 import { BUCKET_UNITS, TIME_ZONE_NAME_RE, WEEK_STARTS, walkFilter } from "@uniqu/core";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 //#region src/dialect.ts
@@ -79,6 +79,14 @@ const EMPTY_OR = {
 	sql: "0=1",
 	params: []
 };
+/** ORs predicate parts (parenthesized when several); no parts matches nothing. */
+function orFragment(parts, params) {
+	if (parts.length === 0) return EMPTY_OR;
+	return {
+		sql: parts.length === 1 ? parts[0] : `(${parts.join(" OR ")})`,
+		params
+	};
+}
 //#endregion
 //#region src/arith.ts
 /**
@@ -219,6 +227,7 @@ function createFilterVisitor(dialect, options) {
 					params: []
 				};
 				case "$regex": return dialect.regex(col, value);
+				case INTEGER_REGEX_OP: return dialect.regex(dialect.integerText ? dialect.integerText(col) : `CAST(${col} AS TEXT)`, value);
 				default: throw new Error(`Unsupported filter operator: ${String(op)}`);
 			}
 		},
@@ -1113,7 +1122,10 @@ function fillReplacePayload(data, columns, versionColumn) {
 *   `<col> = <col> + 1` to the SET list. The bump is **mandatory** whenever
 *   `versionColumn` is set, regardless of whether `expectedVersion` is
 *   supplied. If the version column doesn't auto-increment on every write,
-*   OCC silently degrades to no protection.
+*   OCC silently degrades to no protection. A caller that must not bump (a
+*   version-exempt patch, `TDbUpdateOptions.keepVersion`) passes
+*   `versionColumn: undefined`, which also drops the CAS predicate — callers
+*   never combine that with `expectedVersion`.
 * - `expectedVersion` — when supplied, the builder appends
 *   `AND <col> = ?` to the WHERE clause and pushes the value. Requires
 *   `versionColumn` (CAS targets that column); supplying `expectedVersion`
@@ -1442,4 +1454,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.148",
+  "version": "0.1.150",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -38,11 +38,11 @@
   },
   "devDependencies": {
     "@uniqu/core": "^0.1.13",
-    "unplugin-atscript": "^0.1.100"
+    "unplugin-atscript": "^0.1.101"
   },
   "peerDependencies": {
     "@uniqu/core": "^0.1.13",
-    "@atscript/db": "^0.1.148"
+    "@atscript/db": "^0.1.150"
   },
   "scripts": {
     "build": "vp pack",