@atscript/db-sqlite 0.1.131 → 0.1.133

package/README.md

@@ -39,7 +39,7 @@ await users.insertOne({ name: "John", email: "john@example.com" });
 
 ## Features
 
-- Swappable driver via `TSqliteDriver` interface (5 methods)
+- Swappable driver via `TSqliteDriver` interface (5 methods, plus the optional `registerFunction` hook calendar-bucket grouping needs)
 - Built-in `BetterSqlite3Driver` for immediate use (with optional `{ vector: true }` and `loadExtensions` hooks)
 - MongoDB-style filter translation to parameterized SQL (no injection risk)
 - Automatic schema management from `@db.*` annotations

package/dist/index.cjs

@@ -3,6 +3,7 @@ let _atscript_db = require("@atscript/db");
 let node_module = require("node:module");
 let _atscript_db_agg = require("@atscript/db/agg");
 let _atscript_db_sql_tools = require("@atscript/db-sql-tools");
+let _uniqu_core = require("@uniqu/core");
 let node_async_hooks = require("node:async_hooks");
 //#region src/better-sqlite3-driver.ts
 /**
@@ -74,11 +75,93 @@ var BetterSqlite3Driver = class {
 	exec(sql) {
 		this.db.exec(sql);
 	}
+	registerFunction(name, fn, opts) {
+		this.db.function(name, { deterministic: opts?.deterministic ?? false }, fn);
+	}
 	close() {
 		this.db.close();
 	}
 };
 //#endregion
+//#region src/calendar-bucket.ts
+/**
+* Name of the scalar SQL function the adapter registers on its driver:
+* `atscript_bucket(value, unit, tz, weekStart)` → TEXT `'YYYY-MM-DD'` or NULL.
+*/
+const SQLITE_BUCKET_FN = "atscript_bucket";
+/**
+* Prepared kernels by `unit|tz|weekStart`. Bounded by construction: the
+* arguments are the literals `sqliteCalendarBucket` inlines — closed unit /
+* week-start sets and validated IANA zones — and an invalid combination
+* throws before it is stored.
+*/
+const bucketers = /* @__PURE__ */ new Map();
+/** The last arguments and their kernel — a query calls the UDF with one combination per row. */
+let last;
+function cachedBucketer(unit, tz, weekStart) {
+	if (last && last.unit === unit && last.tz === tz && last.weekStart === weekStart) return last.fn;
+	const u = String(unit);
+	const z = String(tz);
+	const w = String(weekStart);
+	const key = `${u}|${z}|${w}`;
+	let fn = bucketers.get(key);
+	if (!fn) {
+		fn = (0, _uniqu_core.bucketer)(u, z, w);
+		bucketers.set(key, fn);
+	}
+	last = {
+		unit,
+		tz,
+		weekStart,
+		fn
+	};
+	return fn;
+}
+/**
+* Body of the `atscript_bucket` UDF: the `@uniqu/core` calendar kernel — the
+* same definition the in-memory adapter groups with. INTEGER / REAL values
+* arrive as `number` (or `bigint` in better-sqlite3's safe-integer mode);
+* NULL and any other storage class (TEXT, BLOB) label as NULL, as does an
+* instant outside the supported range. The kernel is prepared once per
+* (unit, zone, week start), not per row.
+*
+* Four declared parameters on purpose: SQLite drivers take a UDF's arity from
+* `fn.length`.
+*/
+function atscriptBucketUdf(value, unit, tz, weekStart) {
+	if (typeof value !== "number" && typeof value !== "bigint") return null;
+	return cachedBucketer(unit, tz, weekStart)(value);
+}
+/** Drivers the UDF is registered on. */
+const registered = /* @__PURE__ */ new WeakSet();
+/**
+* Registers {@link SQLITE_BUCKET_FN} on `driver` once — every table adapter
+* of a space shares one driver — and reports whether the driver has the UDF.
+* A driver without {@link TSqliteDriver.registerFunction} cannot run calendar
+* buckets (the adapter then advertises no bucket units → `BUCKET_NOT_SUPPORTED`).
+* A failing `registerFunction` propagates: it is a broken driver, not a
+* missing capability.
+*/
+function registerBucketFunction(driver) {
+	if (typeof driver.registerFunction !== "function") return false;
+	if (!registered.has(driver)) {
+		driver.registerFunction(SQLITE_BUCKET_FN, atscriptBucketUdf, { deterministic: true });
+		registered.add(driver);
+	}
+	return true;
+}
+/**
+* The SQLite dialect's calendar-bucket expression:
+* `atscript_bucket("col", 'week', 'Europe/Berlin', 'sun')`. Parameter-free —
+* the shared builder asserts the unit and week start against their closed
+* sets, and the zone passes {@link sqlTimeZoneLiteral}'s charset — so SELECT,
+* GROUP BY and HAVING render identical text. Deterministic, so SQLite treats
+* repeated calls as one expression.
+*/
+function sqliteCalendarBucket(quotedCol, b) {
+	return `${SQLITE_BUCKET_FN}(${quotedCol}, '${b.unit}', ${(0, _atscript_db_sql_tools.sqlTimeZoneLiteral)(b.tz)}, '${b.weekStart}')`;
+}
+//#endregion
 //#region src/sql-builder.ts
 function esc(name) {
 	return name.replace(/"/g, "\"\"");
@@ -189,6 +272,7 @@ const sqliteDialect = {
 			params: [...dist.params, circle.radius]
 		};
 	},
+	calendarBucket: sqliteCalendarBucket,
 	createViewPrefix: "CREATE VIEW IF NOT EXISTS"
 };
 /**
@@ -579,6 +663,14 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 	supportsNativeValueDefaults() {
 		return true;
 	}
+	/**
+	* Every calendar-bucket unit when the driver could register the
+	* `atscript_bucket` UDF (at construction — see {@link registerBucketFunction}),
+	* none otherwise (`BUCKET_NOT_SUPPORTED`, a clean 400).
+	*/
+	calendarBucketUnits() {
+		return this._hasBucketFn ? _atscript_db.ALL_BUCKET_UNITS : super.calendarBucketUnits();
+	}
 	/** Whether the SQLite connection has the sqlite-vec extension loaded. */
 	_supportsVector;
 	/** Whether SQLite math functions (radians/asin/...) are available — geo search. */
@@ -592,12 +684,15 @@ var SqliteAdapter = class SqliteAdapter extends _atscript_db.BaseDbAdapter {
 	/** Per-driver transaction gate (shared by every adapter over this driver). */
 	_gate;
 	_txOptions;
+	/** Whether the driver has the calendar-bucket UDF — fixed at construction, when it is registered. */
+	_hasBucketFn;
 	constructor(driver, options) {
 		super();
 		this.driver = driver;
 		this._gate = getSqliteTxGate(driver);
 		this._txOptions = { ...options };
 		this.driver.exec("PRAGMA foreign_keys = ON");
+		this._hasBucketFn = registerBucketFunction(driver);
 	}
 	onFieldScanned(field, _type, metadata) {
 		const vectorMeta = metadata.get("db.search.vector");

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
+import { BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
@@ -47,6 +47,21 @@ interface TSqliteDriver {
    * Close the database connection.
    */
   close(): void;
+  /**
+   * Registers a scalar SQL function (a user-defined function) on the
+   * connection. Optional: the adapter registers `atscript_bucket` through it
+   * for calendar-bucket grouping, and a driver without it advertises no
+   * calendar-bucket units (`BUCKET_NOT_SUPPORTED`). The function's arity is
+   * `fn.length`; `deterministic` marks it pure, which lets SQLite use it in
+   * GROUP BY / indexes and fold repeated calls.
+   *
+   * better-sqlite3: `db.function(name, { deterministic }, fn)`;
+   * node:sqlite: `DatabaseSync#function(name, { deterministic }, fn)` (Node ≥ 22.13).
+   * Since 0.1.132.
+   */
+  registerFunction?(name: string, fn: (...args: any[]) => unknown, opts?: {
+    deterministic?: boolean;
+  }): void;
   /**
    * Whether a vector search extension (e.g., `sqlite-vec`) is loaded.
    * Consumers gate vec0 virtual tables and KNN queries on this flag.
@@ -103,6 +118,9 @@ declare class BetterSqlite3Driver implements TSqliteDriver {
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
   exec(sql: string): void;
+  registerFunction(name: string, fn: (...args: any[]) => unknown, opts?: {
+    deterministic?: boolean;
+  }): void;
   close(): void;
 }
 //#endregion
@@ -243,6 +261,12 @@ declare function getSqliteTxGate(driver: TSqliteDriver): SqliteTxGate;
 declare class SqliteAdapter extends BaseDbAdapter {
   protected readonly driver: TSqliteDriver;
   supportsNativeValueDefaults(): boolean;
+  /**
+   * Every calendar-bucket unit when the driver could register the
+   * `atscript_bucket` UDF (at construction — see {@link registerBucketFunction}),
+   * none otherwise (`BUCKET_NOT_SUPPORTED`, a clean 400).
+   */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Whether the SQLite connection has the sqlite-vec extension loaded. */
   private _supportsVector;
   /** Whether SQLite math functions (radians/asin/...) are available — geo search. */
@@ -256,6 +280,8 @@ declare class SqliteAdapter extends BaseDbAdapter {
   /** Per-driver transaction gate (shared by every adapter over this driver). */
   private readonly _gate;
   private readonly _txOptions;
+  /** Whether the driver has the calendar-bucket UDF — fixed at construction, when it is registered. */
+  private readonly _hasBucketFn;
   constructor(driver: TSqliteDriver, options?: SqliteAdapterOptions);
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   formatValue(field: TDbFieldMeta): TValueFormatterPair | undefined;

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
+import { BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
-import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
+import { TMetadataMap } from "@atscript/typescript/utils";
 
 //#region src/types.d.ts
 /**
@@ -47,6 +47,21 @@ interface TSqliteDriver {
    * Close the database connection.
    */
   close(): void;
+  /**
+   * Registers a scalar SQL function (a user-defined function) on the
+   * connection. Optional: the adapter registers `atscript_bucket` through it
+   * for calendar-bucket grouping, and a driver without it advertises no
+   * calendar-bucket units (`BUCKET_NOT_SUPPORTED`). The function's arity is
+   * `fn.length`; `deterministic` marks it pure, which lets SQLite use it in
+   * GROUP BY / indexes and fold repeated calls.
+   *
+   * better-sqlite3: `db.function(name, { deterministic }, fn)`;
+   * node:sqlite: `DatabaseSync#function(name, { deterministic }, fn)` (Node ≥ 22.13).
+   * Since 0.1.132.
+   */
+  registerFunction?(name: string, fn: (...args: any[]) => unknown, opts?: {
+    deterministic?: boolean;
+  }): void;
   /**
    * Whether a vector search extension (e.g., `sqlite-vec`) is loaded.
    * Consumers gate vec0 virtual tables and KNN queries on this flag.
@@ -103,6 +118,9 @@ declare class BetterSqlite3Driver implements TSqliteDriver {
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
   exec(sql: string): void;
+  registerFunction(name: string, fn: (...args: any[]) => unknown, opts?: {
+    deterministic?: boolean;
+  }): void;
   close(): void;
 }
 //#endregion
@@ -243,6 +261,12 @@ declare function getSqliteTxGate(driver: TSqliteDriver): SqliteTxGate;
 declare class SqliteAdapter extends BaseDbAdapter {
   protected readonly driver: TSqliteDriver;
   supportsNativeValueDefaults(): boolean;
+  /**
+   * Every calendar-bucket unit when the driver could register the
+   * `atscript_bucket` UDF (at construction — see {@link registerBucketFunction}),
+   * none otherwise (`BUCKET_NOT_SUPPORTED`, a clean 400).
+   */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Whether the SQLite connection has the sqlite-vec extension loaded. */
   private _supportsVector;
   /** Whether SQLite math functions (radians/asin/...) are available — geo search. */
@@ -256,6 +280,8 @@ declare class SqliteAdapter extends BaseDbAdapter {
   /** Per-driver transaction gate (shared by every adapter over this driver). */
   private readonly _gate;
   private readonly _txOptions;
+  /** Whether the driver has the calendar-bucket UDF — fixed at construction, when it is registered. */
+  private readonly _hasBucketFn;
   constructor(driver: TSqliteDriver, options?: SqliteAdapterOptions);
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   formatValue(field: TDbFieldMeta): TValueFormatterPair | undefined;

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import { createRequire } from "node:module";
-import { BaseDbAdapter, DbError, DbSpace } from "@atscript/db";
+import { ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { EMPTY_AND, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, geoWindowFromControls, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, toSqlValue } from "@atscript/db-sql-tools";
+import { EMPTY_AND, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, geoWindowFromControls, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, toSqlValue } from "@atscript/db-sql-tools";
+import { bucketer } from "@uniqu/core";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/better-sqlite3-driver.ts
 /**
@@ -73,11 +74,93 @@ var BetterSqlite3Driver = class {
 	exec(sql) {
 		this.db.exec(sql);
 	}
+	registerFunction(name, fn, opts) {
+		this.db.function(name, { deterministic: opts?.deterministic ?? false }, fn);
+	}
 	close() {
 		this.db.close();
 	}
 };
 //#endregion
+//#region src/calendar-bucket.ts
+/**
+* Name of the scalar SQL function the adapter registers on its driver:
+* `atscript_bucket(value, unit, tz, weekStart)` → TEXT `'YYYY-MM-DD'` or NULL.
+*/
+const SQLITE_BUCKET_FN = "atscript_bucket";
+/**
+* Prepared kernels by `unit|tz|weekStart`. Bounded by construction: the
+* arguments are the literals `sqliteCalendarBucket` inlines — closed unit /
+* week-start sets and validated IANA zones — and an invalid combination
+* throws before it is stored.
+*/
+const bucketers = /* @__PURE__ */ new Map();
+/** The last arguments and their kernel — a query calls the UDF with one combination per row. */
+let last;
+function cachedBucketer(unit, tz, weekStart) {
+	if (last && last.unit === unit && last.tz === tz && last.weekStart === weekStart) return last.fn;
+	const u = String(unit);
+	const z = String(tz);
+	const w = String(weekStart);
+	const key = `${u}|${z}|${w}`;
+	let fn = bucketers.get(key);
+	if (!fn) {
+		fn = bucketer(u, z, w);
+		bucketers.set(key, fn);
+	}
+	last = {
+		unit,
+		tz,
+		weekStart,
+		fn
+	};
+	return fn;
+}
+/**
+* Body of the `atscript_bucket` UDF: the `@uniqu/core` calendar kernel — the
+* same definition the in-memory adapter groups with. INTEGER / REAL values
+* arrive as `number` (or `bigint` in better-sqlite3's safe-integer mode);
+* NULL and any other storage class (TEXT, BLOB) label as NULL, as does an
+* instant outside the supported range. The kernel is prepared once per
+* (unit, zone, week start), not per row.
+*
+* Four declared parameters on purpose: SQLite drivers take a UDF's arity from
+* `fn.length`.
+*/
+function atscriptBucketUdf(value, unit, tz, weekStart) {
+	if (typeof value !== "number" && typeof value !== "bigint") return null;
+	return cachedBucketer(unit, tz, weekStart)(value);
+}
+/** Drivers the UDF is registered on. */
+const registered = /* @__PURE__ */ new WeakSet();
+/**
+* Registers {@link SQLITE_BUCKET_FN} on `driver` once — every table adapter
+* of a space shares one driver — and reports whether the driver has the UDF.
+* A driver without {@link TSqliteDriver.registerFunction} cannot run calendar
+* buckets (the adapter then advertises no bucket units → `BUCKET_NOT_SUPPORTED`).
+* A failing `registerFunction` propagates: it is a broken driver, not a
+* missing capability.
+*/
+function registerBucketFunction(driver) {
+	if (typeof driver.registerFunction !== "function") return false;
+	if (!registered.has(driver)) {
+		driver.registerFunction(SQLITE_BUCKET_FN, atscriptBucketUdf, { deterministic: true });
+		registered.add(driver);
+	}
+	return true;
+}
+/**
+* The SQLite dialect's calendar-bucket expression:
+* `atscript_bucket("col", 'week', 'Europe/Berlin', 'sun')`. Parameter-free —
+* the shared builder asserts the unit and week start against their closed
+* sets, and the zone passes {@link sqlTimeZoneLiteral}'s charset — so SELECT,
+* GROUP BY and HAVING render identical text. Deterministic, so SQLite treats
+* repeated calls as one expression.
+*/
+function sqliteCalendarBucket(quotedCol, b) {
+	return `${SQLITE_BUCKET_FN}(${quotedCol}, '${b.unit}', ${sqlTimeZoneLiteral(b.tz)}, '${b.weekStart}')`;
+}
+//#endregion
 //#region src/sql-builder.ts
 function esc(name) {
 	return name.replace(/"/g, "\"\"");
@@ -188,6 +271,7 @@ const sqliteDialect = {
 			params: [...dist.params, circle.radius]
 		};
 	},
+	calendarBucket: sqliteCalendarBucket,
 	createViewPrefix: "CREATE VIEW IF NOT EXISTS"
 };
 /**
@@ -578,6 +662,14 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	supportsNativeValueDefaults() {
 		return true;
 	}
+	/**
+	* Every calendar-bucket unit when the driver could register the
+	* `atscript_bucket` UDF (at construction — see {@link registerBucketFunction}),
+	* none otherwise (`BUCKET_NOT_SUPPORTED`, a clean 400).
+	*/
+	calendarBucketUnits() {
+		return this._hasBucketFn ? ALL_BUCKET_UNITS : super.calendarBucketUnits();
+	}
 	/** Whether the SQLite connection has the sqlite-vec extension loaded. */
 	_supportsVector;
 	/** Whether SQLite math functions (radians/asin/...) are available — geo search. */
@@ -591,12 +683,15 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	/** Per-driver transaction gate (shared by every adapter over this driver). */
 	_gate;
 	_txOptions;
+	/** Whether the driver has the calendar-bucket UDF — fixed at construction, when it is registered. */
+	_hasBucketFn;
 	constructor(driver, options) {
 		super();
 		this.driver = driver;
 		this._gate = getSqliteTxGate(driver);
 		this._txOptions = { ...options };
 		this.driver.exec("PRAGMA foreign_keys = ON");
+		this._hasBucketFn = registerBucketFunction(driver);
 	}
 	onFieldScanned(field, _type, metadata) {
 		const vectorMeta = metadata.get("db.search.vector");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sqlite",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "SQLite adapter for @atscript/db with swappable driver support.",
   "keywords": [
     "atscript",
@@ -39,7 +39,7 @@
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
     "@types/better-sqlite3": "^7.6.13",
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.10",
     "better-sqlite3": "^12.6.2",
     "sqlite-vec": "^0.1.9",
     "unplugin-atscript": "^0.1.92"
@@ -47,10 +47,10 @@
   "peerDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.10",
     "better-sqlite3": ">=11.0.0",
-    "@atscript/db": "^0.1.131",
-    "@atscript/db-sql-tools": "^0.1.131"
+    "@atscript/db": "^0.1.133",
+    "@atscript/db-sql-tools": "^0.1.133"
   },
   "peerDependenciesMeta": {
     "better-sqlite3": {