@atscript/db-sql-tools 0.1.38

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Artem Maltsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,428 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __uniqu_core = __toESM(require("@uniqu/core"));
+const __atscript_db_agg = __toESM(require("@atscript/db/agg"));
+
+//#region packages/db-sql-tools/src/dialect.ts
+function finalizeParams(dialect, fragment) {
+	if (!dialect.paramPlaceholder) return fragment;
+	let idx = 0;
+	const sql = fragment.sql.replace(/\?/g, () => dialect.paramPlaceholder(++idx));
+	return {
+		sql,
+		params: fragment.params
+	};
+}
+const EMPTY_AND = {
+	sql: "1=1",
+	params: []
+};
+const EMPTY_OR = {
+	sql: "0=1",
+	params: []
+};
+
+//#endregion
+//#region packages/db-sql-tools/src/filter-builder.ts
+function createFilterVisitor(dialect) {
+	return {
+		comparison(field, op, value) {
+			const col = dialect.quoteIdentifier(field);
+			const v = dialect.toParam(value);
+			switch (op) {
+				case "$eq": {
+					if (v === null) return {
+						sql: `${col} IS NULL`,
+						params: []
+					};
+					return {
+						sql: `${col} = ?`,
+						params: [v]
+					};
+				}
+				case "$ne": {
+					if (v === null) return {
+						sql: `${col} IS NOT NULL`,
+						params: []
+					};
+					return {
+						sql: `${col} != ?`,
+						params: [v]
+					};
+				}
+				case "$gt": return {
+					sql: `${col} > ?`,
+					params: [v]
+				};
+				case "$gte": return {
+					sql: `${col} >= ?`,
+					params: [v]
+				};
+				case "$lt": return {
+					sql: `${col} < ?`,
+					params: [v]
+				};
+				case "$lte": return {
+					sql: `${col} <= ?`,
+					params: [v]
+				};
+				case "$in": {
+					const arr = value.map((x) => dialect.toParam(x));
+					if (arr.length === 0) return EMPTY_OR;
+					const placeholders = arr.map(() => "?").join(", ");
+					return {
+						sql: `${col} IN (${placeholders})`,
+						params: arr
+					};
+				}
+				case "$nin": {
+					const arr = value.map((x) => dialect.toParam(x));
+					if (arr.length === 0) return EMPTY_AND;
+					const placeholders = arr.map(() => "?").join(", ");
+					return {
+						sql: `${col} NOT IN (${placeholders})`,
+						params: arr
+					};
+				}
+				case "$exists": return value ? {
+					sql: `${col} IS NOT NULL`,
+					params: []
+				} : {
+					sql: `${col} IS NULL`,
+					params: []
+				};
+				case "$regex": return dialect.regex(col, value);
+				default: throw new Error(`Unsupported filter operator: ${op}`);
+			}
+		},
+		and(children) {
+			if (children.length === 0) return EMPTY_AND;
+			return {
+				sql: children.map((c) => c.sql).join(" AND "),
+				params: children.flatMap((c) => c.params)
+			};
+		},
+		or(children) {
+			if (children.length === 0) return EMPTY_OR;
+			return {
+				sql: `(${children.map((c) => c.sql).join(" OR ")})`,
+				params: children.flatMap((c) => c.params)
+			};
+		},
+		not(child) {
+			return {
+				sql: `NOT (${child.sql})`,
+				params: child.params
+			};
+		}
+	};
+}
+const visitorCache = new WeakMap();
+function getVisitor(dialect) {
+	let visitor = visitorCache.get(dialect);
+	if (!visitor) {
+		visitor = createFilterVisitor(dialect);
+		visitorCache.set(dialect, visitor);
+	}
+	return visitor;
+}
+function buildWhere(dialect, filter) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
+	return (0, __uniqu_core.walkFilter)(filter, getVisitor(dialect)) ?? EMPTY_AND;
+}
+
+//#endregion
+//#region packages/db-sql-tools/src/common.ts
+function sqlStringLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function toSqlValue(value) {
+	if (value === undefined) return null;
+	if (value === null) return null;
+	if (typeof value === "object") return JSON.stringify(value);
+	if (typeof value === "boolean") return value ? 1 : 0;
+	return value;
+}
+function refActionToSql(action) {
+	switch (action) {
+		case "cascade": return "CASCADE";
+		case "restrict": return "RESTRICT";
+		case "setNull": return "SET NULL";
+		case "setDefault": return "SET DEFAULT";
+		default: return "NO ACTION";
+	}
+}
+function defaultValueForType(designType) {
+	switch (designType) {
+		case "number":
+		case "integer": return "0";
+		case "boolean": return "0";
+		case "decimal": return "'0'";
+		default: return "''";
+	}
+}
+function defaultValueToSqlLiteral(designType, value) {
+	switch (designType) {
+		case "boolean": return value === "true" || value === "1" ? "1" : "0";
+		case "number":
+		case "integer":
+		case "decimal": {
+			const n = Number(value);
+			return Number.isFinite(n) ? String(n) : "0";
+		}
+		default: return sqlStringLiteral(value);
+	}
+}
+const queryOpToSql = {
+	$eq: "=",
+	$ne: "!=",
+	$gt: ">",
+	$gte: ">=",
+	$lt: "<",
+	$lte: "<="
+};
+function queryNodeToSql(node, resolveFieldRef) {
+	if ("$and" in node) {
+		const children = node.$and;
+		return children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
+	}
+	if ("$or" in node) {
+		const children = node.$or;
+		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+	}
+	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef)})`;
+	const comp = node;
+	const leftSql = resolveFieldRef(comp.left);
+	const sqlOp = queryOpToSql[comp.op] || "=";
+	if (comp.right && typeof comp.right === "object" && "field" in comp.right) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
+	if (comp.right === null || comp.right === undefined) return comp.op === "$ne" ? `${leftSql} IS NOT NULL` : `${leftSql} IS NULL`;
+	if (typeof comp.right === "string") return `${leftSql} ${sqlOp} '${comp.right.replace(/'/g, "''")}'`;
+	return `${leftSql} ${sqlOp} ${comp.right}`;
+}
+
+//#endregion
+//#region packages/db-sql-tools/src/agg.ts
+const AGG_FN_SQL = {
+	sum: "SUM",
+	avg: "AVG",
+	count: "COUNT",
+	min: "MIN",
+	max: "MAX"
+};
+function buildAggExpr(dialect, expr) {
+	const fn = AGG_FN_SQL[expr.$fn] ?? expr.$fn.toUpperCase();
+	const alias = dialect.quoteIdentifier((0, __atscript_db_agg.resolveAlias)(expr));
+	const field = expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field);
+	return `${fn}(${field}) AS ${alias}`;
+}
+function buildAggregateSelect(dialect, table, where, controls) {
+	const selectParts = [];
+	const plainFields = controls.$select?.asArray;
+	if (plainFields) for (const f of plainFields) selectParts.push(dialect.quoteIdentifier(f));
+	const aggregates = controls.$select?.aggregates;
+	if (aggregates) for (const expr of aggregates) selectParts.push(buildAggExpr(dialect, expr));
+	const cols = selectParts.length > 0 ? selectParts.join(", ") : "*";
+	let sql = `SELECT ${cols} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const params = [...where.params];
+	const groupBy = controls.$groupBy;
+	if (groupBy?.length) {
+		const groupCols = groupBy.map((f) => dialect.quoteIdentifier(f)).join(", ");
+		sql += ` GROUP BY ${groupCols}`;
+	}
+	if (controls.$having) {
+		const havingFragment = buildWhere(dialect, controls.$having);
+		if (havingFragment.sql !== EMPTY_AND.sql) {
+			sql += ` HAVING ${havingFragment.sql}`;
+			params.push(...havingFragment.params);
+		}
+	}
+	if (controls.$sort) {
+		const orderParts = [];
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
+	}
+	if (controls.$limit !== undefined) {
+		sql += ` LIMIT ?`;
+		params.push(controls.$limit);
+	}
+	if (controls.$skip !== undefined) {
+		if (controls.$limit === undefined) sql += ` LIMIT ${dialect.unlimitedLimit}`;
+		sql += ` OFFSET ?`;
+		params.push(controls.$skip);
+	}
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+function buildAggregateCount(dialect, table, where, controls) {
+	const groupFields = controls.$groupBy;
+	if (!groupFields?.length) {
+		const sql$1 = `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+		return finalizeParams(dialect, {
+			sql: sql$1,
+			params: where.params
+		});
+	}
+	const groupCols = groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ");
+	const sql = `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM (SELECT 1 FROM ${dialect.quoteTable(table)} WHERE ${where.sql} GROUP BY ${groupCols}) AS ${dialect.quoteIdentifier("_groups")}`;
+	return finalizeParams(dialect, {
+		sql,
+		params: where.params
+	});
+}
+
+//#endregion
+//#region packages/db-sql-tools/src/sql-builder.ts
+function buildInsert(dialect, table, data) {
+	const keys = Object.keys(data);
+	const cols = keys.map((k) => dialect.quoteIdentifier(k)).join(", ");
+	const placeholders = keys.map(() => "?").join(", ");
+	return finalizeParams(dialect, {
+		sql: `INSERT INTO ${dialect.quoteTable(table)} (${cols}) VALUES (${placeholders})`,
+		params: keys.map((k) => dialect.toValue(data[k]))
+	});
+}
+function buildSelect(dialect, table, where, controls) {
+	const cols = buildProjection(dialect, controls?.$select);
+	let sql = `SELECT ${cols} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const params = [...where.params];
+	if (controls?.$sort) {
+		const orderParts = [];
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
+	}
+	if (controls?.$limit !== undefined) {
+		sql += ` LIMIT ?`;
+		params.push(controls.$limit);
+	}
+	if (controls?.$skip !== undefined) {
+		if (controls.$limit === undefined) sql += ` LIMIT ${dialect.unlimitedLimit}`;
+		sql += ` OFFSET ?`;
+		params.push(controls.$skip);
+	}
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+function buildUpdate(dialect, table, data, where, limit) {
+	const setClauses = [];
+	const params = [];
+	for (const [key, value] of Object.entries(data)) {
+		setClauses.push(`${dialect.quoteIdentifier(key)} = ?`);
+		params.push(dialect.toValue(value));
+	}
+	let sql = `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${where.sql}`;
+	if (limit !== undefined) sql += ` LIMIT ${limit}`;
+	return finalizeParams(dialect, {
+		sql,
+		params: [...params, ...where.params]
+	});
+}
+function buildDelete(dialect, table, where, limit) {
+	let sql = `DELETE FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	if (limit !== undefined) sql += ` LIMIT ${limit}`;
+	return finalizeParams(dialect, {
+		sql,
+		params: where.params
+	});
+}
+function buildProjection(dialect, select) {
+	const fields = select?.asArray;
+	if (!fields) return "*";
+	let sql = "";
+	for (let i = 0; i < fields.length; i++) {
+		if (i > 0) sql += ", ";
+		sql += dialect.quoteIdentifier(fields[i]);
+	}
+	return sql || "*";
+}
+/** Builds the SQL expression for a single aggregate column. */ function buildAggColExpr(dialect, c) {
+	const fn = AGG_FN_SQL[c.aggFn] ?? c.aggFn.toUpperCase();
+	const arg = c.aggField === "*" ? "*" : `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`;
+	return `${fn}(${arg})`;
+}
+function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+	const selectCols = columns.map((c) => {
+		if (c.aggFn) return `${buildAggColExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
+		return `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
+	}).join(", ");
+	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
+	for (const join of plan.joins) {
+		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		sql += ` JOIN ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
+	}
+	if (plan.filter) {
+		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
+		sql += ` WHERE ${whereClause}`;
+	}
+	const hasAggregates = columns.some((c) => c.aggFn);
+	if (hasAggregates) {
+		const dimensionCols = columns.filter((c) => !c.aggFn);
+		if (dimensionCols.length > 0) {
+			const groupByCols = dimensionCols.map((c) => `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`).join(", ");
+			sql += ` GROUP BY ${groupByCols}`;
+		}
+		if (plan.having) {
+			const columnMap = new Map();
+			for (const c of columns) columnMap.set(c.viewColumn, c);
+			const havingResolver = (ref) => {
+				if (!ref.type) {
+					const col = columnMap.get(ref.field);
+					if (col?.aggFn) return buildAggColExpr(dialect, col);
+					if (col) return `${dialect.quoteIdentifier(col.sourceTable)}.${dialect.quoteIdentifier(col.sourceColumn)}`;
+				}
+				return resolveFieldRef(ref);
+			};
+			const havingClause = queryNodeToSql(plan.having, havingResolver);
+			sql += ` HAVING ${havingClause}`;
+		}
+	}
+	return sql;
+}
+
+//#endregion
+exports.AGG_FN_SQL = AGG_FN_SQL
+exports.EMPTY_AND = EMPTY_AND
+exports.EMPTY_OR = EMPTY_OR
+exports.buildAggregateCount = buildAggregateCount
+exports.buildAggregateSelect = buildAggregateSelect
+exports.buildCreateView = buildCreateView
+exports.buildDelete = buildDelete
+exports.buildInsert = buildInsert
+exports.buildProjection = buildProjection
+exports.buildSelect = buildSelect
+exports.buildUpdate = buildUpdate
+exports.buildWhere = buildWhere
+exports.createFilterVisitor = createFilterVisitor
+exports.defaultValueForType = defaultValueForType
+exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral
+exports.finalizeParams = finalizeParams
+exports.queryNodeToSql = queryNodeToSql
+exports.queryOpToSql = queryOpToSql
+exports.refActionToSql = refActionToSql
+exports.sqlStringLiteral = sqlStringLiteral
+exports.toSqlValue = toSqlValue

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { FilterExpr, FilterVisitor } from '@uniqu/core';
+import { TViewPlan, TViewColumnMapping, AtscriptQueryFieldRef, UniquSelect, DbControls, AtscriptQueryNode, TDbReferentialAction } from '@atscript/db';
+
+interface TSqlFragment {
+    sql: string;
+    params: unknown[];
+}
+interface SqlDialect {
+    /** Quotes a column/table name */
+    quoteIdentifier(name: string): string;
+    /** Quotes a possibly schema-qualified table name */
+    quoteTable(name: string): string;
+    /** SQL literal for unlimited LIMIT (SQLite: '-1', MySQL: '18446744073709551615') */
+    unlimitedLimit: string;
+    /** Convert JS value to SQL-bindable param for DML */
+    toValue(value: unknown): unknown;
+    /** Convert JS value to SQL-bindable param for filters (lighter) */
+    toParam(value: unknown): unknown;
+    /** Handle $regex filter */
+    regex(quotedCol: string, value: unknown): TSqlFragment;
+    /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
+    createViewPrefix: string;
+    /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
+    paramPlaceholder?: (index: number) => string;
+}
+/**
+ * Replaces positional `?` placeholders with dialect-specific numbered placeholders
+ * (e.g. `$1, $2, ...` for PostgreSQL). No-op when `dialect.paramPlaceholder` is not set.
+ */
+declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TSqlFragment;
+declare const EMPTY_AND: TSqlFragment;
+declare const EMPTY_OR: TSqlFragment;
+
+/**
+ * Creates a dialect-specific filter visitor for `walkFilter`.
+ */
+declare function createFilterVisitor(dialect: SqlDialect): FilterVisitor<TSqlFragment>;
+/**
+ * Translates a filter expression into a parameterized SQL WHERE clause.
+ */
+declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragment;
+
+/**
+ * Builds an INSERT statement.
+ */
+declare function buildInsert(dialect: SqlDialect, table: string, data: Record<string, unknown>): TSqlFragment;
+/**
+ * Builds a SELECT statement with optional sort, limit, offset, projection.
+ */
+declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+ */
+declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<string, unknown>, where: TSqlFragment, limit?: number): TSqlFragment;
+/**
+ * Builds a DELETE ... WHERE statement with optional LIMIT.
+ */
+declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number): TSqlFragment;
+/**
+ * Builds a column projection (SELECT clause fields).
+ */
+declare function buildProjection(dialect: SqlDialect, select?: UniquSelect): string;
+/**
+ * Builds a CREATE VIEW statement from a view plan and column mappings.
+ */
+declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+
+/** Formats a string value as a SQL literal with single-quote escaping. */
+declare function sqlStringLiteral(value: string): string;
+/** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
+declare function toSqlValue(value: unknown): unknown;
+declare function refActionToSql(action: TDbReferentialAction): string;
+/** Returns a safe SQL DEFAULT literal for a given design type. */
+declare function defaultValueForType(designType: string): string;
+/**
+ * Converts a stored default value string to a SQL DEFAULT literal,
+ * respecting the field's designType. Booleans become 0/1, numbers stay unquoted,
+ * strings are single-quote-escaped.
+ */
+declare function defaultValueToSqlLiteral(designType: string, value: string): string;
+declare const queryOpToSql: Record<string, string>;
+/**
+ * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
+ */
+declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+
+declare const AGG_FN_SQL: Record<string, string>;
+/**
+ * Builds a SELECT ... GROUP BY statement with aggregate functions.
+ */
+declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
+/**
+ * Builds a COUNT query for the number of distinct groups.
+ * Returns `{ count: N }` when executed.
+ */
+declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
+
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, finalizeParams, queryNodeToSql, queryOpToSql, refActionToSql, sqlStringLiteral, toSqlValue };
+export type { SqlDialect, TSqlFragment };

package/dist/index.mjs

@@ -0,0 +1,384 @@
+import { walkFilter } from "@uniqu/core";
+import { resolveAlias } from "@atscript/db/agg";
+
+//#region packages/db-sql-tools/src/dialect.ts
+function finalizeParams(dialect, fragment) {
+	if (!dialect.paramPlaceholder) return fragment;
+	let idx = 0;
+	const sql = fragment.sql.replace(/\?/g, () => dialect.paramPlaceholder(++idx));
+	return {
+		sql,
+		params: fragment.params
+	};
+}
+const EMPTY_AND = {
+	sql: "1=1",
+	params: []
+};
+const EMPTY_OR = {
+	sql: "0=1",
+	params: []
+};
+
+//#endregion
+//#region packages/db-sql-tools/src/filter-builder.ts
+function createFilterVisitor(dialect) {
+	return {
+		comparison(field, op, value) {
+			const col = dialect.quoteIdentifier(field);
+			const v = dialect.toParam(value);
+			switch (op) {
+				case "$eq": {
+					if (v === null) return {
+						sql: `${col} IS NULL`,
+						params: []
+					};
+					return {
+						sql: `${col} = ?`,
+						params: [v]
+					};
+				}
+				case "$ne": {
+					if (v === null) return {
+						sql: `${col} IS NOT NULL`,
+						params: []
+					};
+					return {
+						sql: `${col} != ?`,
+						params: [v]
+					};
+				}
+				case "$gt": return {
+					sql: `${col} > ?`,
+					params: [v]
+				};
+				case "$gte": return {
+					sql: `${col} >= ?`,
+					params: [v]
+				};
+				case "$lt": return {
+					sql: `${col} < ?`,
+					params: [v]
+				};
+				case "$lte": return {
+					sql: `${col} <= ?`,
+					params: [v]
+				};
+				case "$in": {
+					const arr = value.map((x) => dialect.toParam(x));
+					if (arr.length === 0) return EMPTY_OR;
+					const placeholders = arr.map(() => "?").join(", ");
+					return {
+						sql: `${col} IN (${placeholders})`,
+						params: arr
+					};
+				}
+				case "$nin": {
+					const arr = value.map((x) => dialect.toParam(x));
+					if (arr.length === 0) return EMPTY_AND;
+					const placeholders = arr.map(() => "?").join(", ");
+					return {
+						sql: `${col} NOT IN (${placeholders})`,
+						params: arr
+					};
+				}
+				case "$exists": return value ? {
+					sql: `${col} IS NOT NULL`,
+					params: []
+				} : {
+					sql: `${col} IS NULL`,
+					params: []
+				};
+				case "$regex": return dialect.regex(col, value);
+				default: throw new Error(`Unsupported filter operator: ${op}`);
+			}
+		},
+		and(children) {
+			if (children.length === 0) return EMPTY_AND;
+			return {
+				sql: children.map((c) => c.sql).join(" AND "),
+				params: children.flatMap((c) => c.params)
+			};
+		},
+		or(children) {
+			if (children.length === 0) return EMPTY_OR;
+			return {
+				sql: `(${children.map((c) => c.sql).join(" OR ")})`,
+				params: children.flatMap((c) => c.params)
+			};
+		},
+		not(child) {
+			return {
+				sql: `NOT (${child.sql})`,
+				params: child.params
+			};
+		}
+	};
+}
+const visitorCache = new WeakMap();
+function getVisitor(dialect) {
+	let visitor = visitorCache.get(dialect);
+	if (!visitor) {
+		visitor = createFilterVisitor(dialect);
+		visitorCache.set(dialect, visitor);
+	}
+	return visitor;
+}
+function buildWhere(dialect, filter) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
+	return walkFilter(filter, getVisitor(dialect)) ?? EMPTY_AND;
+}
+
+//#endregion
+//#region packages/db-sql-tools/src/common.ts
+function sqlStringLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function toSqlValue(value) {
+	if (value === undefined) return null;
+	if (value === null) return null;
+	if (typeof value === "object") return JSON.stringify(value);
+	if (typeof value === "boolean") return value ? 1 : 0;
+	return value;
+}
+function refActionToSql(action) {
+	switch (action) {
+		case "cascade": return "CASCADE";
+		case "restrict": return "RESTRICT";
+		case "setNull": return "SET NULL";
+		case "setDefault": return "SET DEFAULT";
+		default: return "NO ACTION";
+	}
+}
+function defaultValueForType(designType) {
+	switch (designType) {
+		case "number":
+		case "integer": return "0";
+		case "boolean": return "0";
+		case "decimal": return "'0'";
+		default: return "''";
+	}
+}
+function defaultValueToSqlLiteral(designType, value) {
+	switch (designType) {
+		case "boolean": return value === "true" || value === "1" ? "1" : "0";
+		case "number":
+		case "integer":
+		case "decimal": {
+			const n = Number(value);
+			return Number.isFinite(n) ? String(n) : "0";
+		}
+		default: return sqlStringLiteral(value);
+	}
+}
+const queryOpToSql = {
+	$eq: "=",
+	$ne: "!=",
+	$gt: ">",
+	$gte: ">=",
+	$lt: "<",
+	$lte: "<="
+};
+function queryNodeToSql(node, resolveFieldRef) {
+	if ("$and" in node) {
+		const children = node.$and;
+		return children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
+	}
+	if ("$or" in node) {
+		const children = node.$or;
+		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+	}
+	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef)})`;
+	const comp = node;
+	const leftSql = resolveFieldRef(comp.left);
+	const sqlOp = queryOpToSql[comp.op] || "=";
+	if (comp.right && typeof comp.right === "object" && "field" in comp.right) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
+	if (comp.right === null || comp.right === undefined) return comp.op === "$ne" ? `${leftSql} IS NOT NULL` : `${leftSql} IS NULL`;
+	if (typeof comp.right === "string") return `${leftSql} ${sqlOp} '${comp.right.replace(/'/g, "''")}'`;
+	return `${leftSql} ${sqlOp} ${comp.right}`;
+}
+
+//#endregion
+//#region packages/db-sql-tools/src/agg.ts
+const AGG_FN_SQL = {
+	sum: "SUM",
+	avg: "AVG",
+	count: "COUNT",
+	min: "MIN",
+	max: "MAX"
+};
+function buildAggExpr(dialect, expr) {
+	const fn = AGG_FN_SQL[expr.$fn] ?? expr.$fn.toUpperCase();
+	const alias = dialect.quoteIdentifier(resolveAlias(expr));
+	const field = expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field);
+	return `${fn}(${field}) AS ${alias}`;
+}
+function buildAggregateSelect(dialect, table, where, controls) {
+	const selectParts = [];
+	const plainFields = controls.$select?.asArray;
+	if (plainFields) for (const f of plainFields) selectParts.push(dialect.quoteIdentifier(f));
+	const aggregates = controls.$select?.aggregates;
+	if (aggregates) for (const expr of aggregates) selectParts.push(buildAggExpr(dialect, expr));
+	const cols = selectParts.length > 0 ? selectParts.join(", ") : "*";
+	let sql = `SELECT ${cols} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const params = [...where.params];
+	const groupBy = controls.$groupBy;
+	if (groupBy?.length) {
+		const groupCols = groupBy.map((f) => dialect.quoteIdentifier(f)).join(", ");
+		sql += ` GROUP BY ${groupCols}`;
+	}
+	if (controls.$having) {
+		const havingFragment = buildWhere(dialect, controls.$having);
+		if (havingFragment.sql !== EMPTY_AND.sql) {
+			sql += ` HAVING ${havingFragment.sql}`;
+			params.push(...havingFragment.params);
+		}
+	}
+	if (controls.$sort) {
+		const orderParts = [];
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
+	}
+	if (controls.$limit !== undefined) {
+		sql += ` LIMIT ?`;
+		params.push(controls.$limit);
+	}
+	if (controls.$skip !== undefined) {
+		if (controls.$limit === undefined) sql += ` LIMIT ${dialect.unlimitedLimit}`;
+		sql += ` OFFSET ?`;
+		params.push(controls.$skip);
+	}
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+function buildAggregateCount(dialect, table, where, controls) {
+	const groupFields = controls.$groupBy;
+	if (!groupFields?.length) {
+		const sql$1 = `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+		return finalizeParams(dialect, {
+			sql: sql$1,
+			params: where.params
+		});
+	}
+	const groupCols = groupFields.map((f) => dialect.quoteIdentifier(f)).join(", ");
+	const sql = `SELECT COUNT(*) AS ${dialect.quoteIdentifier("count")} FROM (SELECT 1 FROM ${dialect.quoteTable(table)} WHERE ${where.sql} GROUP BY ${groupCols}) AS ${dialect.quoteIdentifier("_groups")}`;
+	return finalizeParams(dialect, {
+		sql,
+		params: where.params
+	});
+}
+
+//#endregion
+//#region packages/db-sql-tools/src/sql-builder.ts
+function buildInsert(dialect, table, data) {
+	const keys = Object.keys(data);
+	const cols = keys.map((k) => dialect.quoteIdentifier(k)).join(", ");
+	const placeholders = keys.map(() => "?").join(", ");
+	return finalizeParams(dialect, {
+		sql: `INSERT INTO ${dialect.quoteTable(table)} (${cols}) VALUES (${placeholders})`,
+		params: keys.map((k) => dialect.toValue(data[k]))
+	});
+}
+function buildSelect(dialect, table, where, controls) {
+	const cols = buildProjection(dialect, controls?.$select);
+	let sql = `SELECT ${cols} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const params = [...where.params];
+	if (controls?.$sort) {
+		const orderParts = [];
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
+	}
+	if (controls?.$limit !== undefined) {
+		sql += ` LIMIT ?`;
+		params.push(controls.$limit);
+	}
+	if (controls?.$skip !== undefined) {
+		if (controls.$limit === undefined) sql += ` LIMIT ${dialect.unlimitedLimit}`;
+		sql += ` OFFSET ?`;
+		params.push(controls.$skip);
+	}
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+function buildUpdate(dialect, table, data, where, limit) {
+	const setClauses = [];
+	const params = [];
+	for (const [key, value] of Object.entries(data)) {
+		setClauses.push(`${dialect.quoteIdentifier(key)} = ?`);
+		params.push(dialect.toValue(value));
+	}
+	let sql = `UPDATE ${dialect.quoteTable(table)} SET ${setClauses.join(", ")} WHERE ${where.sql}`;
+	if (limit !== undefined) sql += ` LIMIT ${limit}`;
+	return finalizeParams(dialect, {
+		sql,
+		params: [...params, ...where.params]
+	});
+}
+function buildDelete(dialect, table, where, limit) {
+	let sql = `DELETE FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	if (limit !== undefined) sql += ` LIMIT ${limit}`;
+	return finalizeParams(dialect, {
+		sql,
+		params: where.params
+	});
+}
+function buildProjection(dialect, select) {
+	const fields = select?.asArray;
+	if (!fields) return "*";
+	let sql = "";
+	for (let i = 0; i < fields.length; i++) {
+		if (i > 0) sql += ", ";
+		sql += dialect.quoteIdentifier(fields[i]);
+	}
+	return sql || "*";
+}
+/** Builds the SQL expression for a single aggregate column. */ function buildAggColExpr(dialect, c) {
+	const fn = AGG_FN_SQL[c.aggFn] ?? c.aggFn.toUpperCase();
+	const arg = c.aggField === "*" ? "*" : `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`;
+	return `${fn}(${arg})`;
+}
+function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+	const selectCols = columns.map((c) => {
+		if (c.aggFn) return `${buildAggColExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
+		return `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
+	}).join(", ");
+	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
+	for (const join of plan.joins) {
+		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		sql += ` JOIN ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
+	}
+	if (plan.filter) {
+		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
+		sql += ` WHERE ${whereClause}`;
+	}
+	const hasAggregates = columns.some((c) => c.aggFn);
+	if (hasAggregates) {
+		const dimensionCols = columns.filter((c) => !c.aggFn);
+		if (dimensionCols.length > 0) {
+			const groupByCols = dimensionCols.map((c) => `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`).join(", ");
+			sql += ` GROUP BY ${groupByCols}`;
+		}
+		if (plan.having) {
+			const columnMap = new Map();
+			for (const c of columns) columnMap.set(c.viewColumn, c);
+			const havingResolver = (ref) => {
+				if (!ref.type) {
+					const col = columnMap.get(ref.field);
+					if (col?.aggFn) return buildAggColExpr(dialect, col);
+					if (col) return `${dialect.quoteIdentifier(col.sourceTable)}.${dialect.quoteIdentifier(col.sourceColumn)}`;
+				}
+				return resolveFieldRef(ref);
+			};
+			const havingClause = queryNodeToSql(plan.having, havingResolver);
+			sql += ` HAVING ${havingClause}`;
+		}
+	}
+	return sql;
+}
+
+//#endregion
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildInsert, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, finalizeParams, queryNodeToSql, queryOpToSql, refActionToSql, sqlStringLiteral, toSqlValue };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@atscript/db-sql-tools",
+  "version": "0.1.38",
+  "description": "Shared SQL builder utilities for @atscript database adapters.",
+  "keywords": [
+    "atscript",
+    "database",
+    "sql"
+  ],
+  "homepage": "https://github.com/moostjs/atscript/tree/main/packages/db-sql-tools#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/atscript/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/atscript.git",
+    "directory": "packages/db-sql-tools"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "@uniqu/core": "^0.1.2",
+    "@atscript/db": "^0.1.38"
+  },
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "test": "vitest"
+  }
+}