@maestro-js/sql 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,311 @@
+# @maestro-js/sql
+
+Composable SQL query builders for constructing parameterized WHERE clauses and Common Table Expressions (CTEs). Standalone utility package with no runtime dependencies on other maestro packages.
+
+## Quick Setup
+
+```ts
+import { Sql } from '@maestro-js/sql'
+
+// Dynamic WHERE clause
+const where = Sql.where()
+where.and('status = ?', ['active'])
+where.and('price > ?', [50])
+await Db.select(`SELECT * FROM products WHERE ${where.query}`, where.parameters)
+
+// CTE wrapping a Db service
+const withTotals = Sql.cte({
+  orderTotals: { subquery: '(SELECT userId, SUM(amount) as total FROM orders GROUP BY userId)', params: [] }
+}, Db)
+await withTotals.select('SELECT * FROM orderTotals WHERE total > ?', [500])
+```
+
+## WHERE Clause Builder
+
+Build parameterized SQL WHERE clauses incrementally with `Sql.where()`. Conditions are appended via `and()` and `or()`. If no conditions are added, `query` returns `'TRUE'`.
+
+### Basic Conditions
+
+```ts
+const where = Sql.where()
+where.and('status = ?', ['active'])
+where.and('created_at > ?', ['2024-01-01'])
+// where.query       => 'status = ? AND created_at > ?'
+// where.parameters  => ['active', '2024-01-01']
+```
+
+### Mixed AND/OR
+
+```ts
+const where = Sql.where()
+where.and('a = ?', [1])
+where.or('b = ?', [2])
+where.and('c = ?', [3])
+// where.query       => 'a = ? OR b = ? AND c = ?'
+// where.parameters  => [1, 2, 3]
+```
+
+### Nested Groups (Parenthesized Sub-Conditions)
+
+Pass a callback to `and()` or `or()` to create parenthesized groups using a sub-builder:
+
+```ts
+const where = Sql.where()
+where.and('status = ?', ['active'])
+where.and(sub => {
+  sub.or('role = ?', ['admin'])
+  sub.or('role = ?', ['editor'])
+})
+// where.query       => 'status = ? AND (role = ? OR role = ?)'
+// where.parameters  => ['active', 'admin', 'editor']
+```
+
+### Deeply Nested Groups
+
+```ts
+const where = Sql.where()
+where.and('a = ?', [1])
+where.or(qb => {
+  qb.and('b = ?', [2])
+  qb.or(iqb => {
+    iqb.and('c = ?', [3])
+    iqb.and('d = ?', [4])
+  })
+})
+// where.query       => 'a = ? OR (b = ? OR (c = ? AND d = ?))'
+// where.parameters  => [1, 2, 3, 4]
+```
+
+### IN Clauses
+
+```ts
+const where = Sql.where()
+where.and('id IN (?)', [[1, 2, 3]])
+// where.query       => 'id IN (?)'
+// where.parameters  => [[1, 2, 3]]
+```
+
+### Cloning
+
+Pass an existing builder to `Sql.where()` to clone it. The clone is independent of the original:
+
+```ts
+const original = Sql.where()
+original.and('a = ?', [1])
+
+const clone = Sql.where(original)
+clone.and('b = ?', [2])
+
+// original.query => 'a = ?'
+// clone.query    => 'a = ? AND b = ?'
+```
+
+### Empty Sub-Builder
+
+If a callback adds no conditions, the group is silently skipped:
+
+```ts
+const where = Sql.where()
+where.and('a = ?', [1])
+where.and(sub => {
+  // no conditions added
+})
+// where.query => 'a = ?'
+```
+
+## CTE Builder (Common Table Expressions)
+
+Wrap a Db service with `Sql.cte()` so every query method auto-prepends the `WITH` clause and merges CTE parameters before the query parameters.
+
+### Basic CTE
+
+```ts
+const withStats = Sql.cte({
+  userStats: {
+    subquery: '(SELECT userId, COUNT(*) as total FROM orders GROUP BY userId)',
+    params: []
+  }
+}, Db)
+
+const results = await withStats.select('SELECT * FROM userStats WHERE total > ?', [10])
+// Executes: WITH userStats AS (SELECT userId, COUNT(*) ...) SELECT * FROM userStats WHERE total > ?
+// Parameters: [10]
+```
+
+### Multiple CTEs
+
+```ts
+const builder = Sql.cte({
+  activeUsers: {
+    subquery: '(SELECT * FROM users WHERE active = ?)',
+    params: [true]
+  },
+  recentOrders: {
+    subquery: '(SELECT * FROM orders WHERE created_at > ?)',
+    params: ['2024-01-01']
+  }
+}, Db)
+
+await builder.select('SELECT * FROM activeUsers JOIN recentOrders ON activeUsers.id = recentOrders.userId')
+// WITH activeUsers AS (...), recentOrders AS (...) SELECT ...
+// Parameters: [true, '2024-01-01']
+```
+
+### Recursive CTEs
+
+Set `recursive: true` on any expression to trigger `WITH RECURSIVE`:
+
+```ts
+const builder = Sql.cte({
+  hierarchy: {
+    subquery: '(SELECT id, parentId, name FROM categories WHERE parentId IS NULL UNION ALL SELECT c.id, c.parentId, c.name FROM categories c JOIN hierarchy h ON c.parentId = h.id)',
+    params: [],
+    recursive: true
+  }
+}, Db)
+// WITH RECURSIVE hierarchy AS (...)
+```
+
+### Dynamic Parameters
+
+Pass a function for `params` to resolve values at query time:
+
+```ts
+const builder = Sql.cte({
+  filtered: {
+    subquery: '(SELECT * FROM items WHERE tenant_id = ?)',
+    params: () => [getCurrentTenantId()]
+  }
+}, Db)
+```
+
+### Re-Wrapping with fromDbService
+
+Use `fromDbService()` to apply the same CTEs to a different Db service (e.g., inside a transaction):
+
+```ts
+const cteBuilder = Sql.cte({ ... }, Db)
+const txResult = await Db.transaction(async () => {
+  const txCte = cteBuilder.fromDbService(TxDb)
+  return txCte.select('SELECT * FROM ...')
+})
+```
+
+### Wrapped Methods
+
+The CTE builder exposes all standard Db methods: `select`, `selectIterable`, `insert`, `update`, `delete`, `statement`, `scalar`, `format`, `transaction`.
+
+## API Reference
+
+### Sql.where(existing?)
+
+Create a new WhereClauseBuilder. Pass an existing builder to clone it.
+
+```ts
+function WhereClauseBuilder(existing?: WhereClauseBuilder): WhereClauseBuilder
+```
+
+**WhereClauseBuilder interface:**
+
+| Member       | Type                                                   | Description                                              |
+|--------------|--------------------------------------------------------|----------------------------------------------------------|
+| `and()`      | `(condition: string \| Callback, params?: any[]) => void` | Append condition with AND, or parenthesized group via callback |
+| `or()`       | `(condition: string \| Callback, params?: any[]) => void` | Append condition with OR, or parenthesized group via callback  |
+| `query`      | `string` (readonly getter)                             | Assembled clause string, or `'TRUE'` if empty            |
+| `parameters` | `any[]` (readonly getter)                              | Parameter array matching `?` placeholders in query       |
+
+### Sql.cte(expressions, db)
+
+Create a CTE builder wrapping a Db service.
+
+```ts
+function CommonTableExpressionBuilder(
+  commonTableExpressions: CommonTableExpressionSet,
+  db: CteDbService
+): CteDbService & { fromDbService(db: CteDbService): CteDbService }
+```
+
+**CommonTableExpressionSet:**
+
+```ts
+interface CommonTableExpressionSet {
+  [name: string]: {
+    subquery: string                    // CTE body wrapped in parentheses
+    params?: any[] | (() => any[])      // Static array or dynamic resolver
+    recursive?: boolean                 // Triggers WITH RECURSIVE
+  }
+}
+```
+
+### Type Exports
+
+Access types through the `Sql` namespace:
+
+```ts
+Sql.cte.Expression     // CommonTableExpressionConfig
+Sql.cte.ExpressionSet  // CommonTableExpressionSet
+Sql.cte.DbService      // CteDbService
+Sql.where.Builder      // WhereClauseBuilder
+Sql.where.Callback     // WhereClauseCallback
+```
+
+`Sql.commonTableExpression` is an alias for `Sql.cte` (both the function and its namespace types).
+
+## Important: Avoid Table Name Aliases
+
+When writing SQL queries with these builders, avoid table name aliases when possible. Write full table names for clarity:
+
+```ts
+// Preferred
+where.and('users.status = ?', ['active'])
+await builder.select('SELECT users.id, orders.total FROM users JOIN orders ON users.id = orders.userId')
+
+// Avoid
+where.and('u.status = ?', ['active'])
+await builder.select('SELECT u.id, o.total FROM users u JOIN orders o ON u.id = o.userId')
+```
+
+## Testing
+
+```bash
+# Run tests
+pnpm --filter @maestro-js/sql test
+
+# Single test file
+cd packages/sql && npx beartest ./tests/where-clause.test.ts
+
+# Typecheck
+pnpm --filter @maestro-js/sql typecheck
+```
+
+Tests use `beartest-js` with `expect` for assertions. Test file location: `packages/sql/tests/where-clause.test.ts`.
+
+## Cross-Package Integration
+
+- **No runtime dependencies** on other maestro packages
+- **Works with @maestro-js/db**: SQL builders produce `{ query, parameters }` pairs for Db to execute. The CTE builder wraps a Db service (or any object matching `CteDbService`) to auto-prepend WITH clauses.
+- **@maestro-js/db is a devDependency** only, used for the `CteDbService` type interface
+
+### Typical Usage with Db
+
+```ts
+import { Sql } from '@maestro-js/sql'
+import { Db } from '@maestro-js/db'
+
+// WHERE builder feeds into Db.select
+const where = Sql.where()
+where.and('active = ?', [true])
+if (minPrice) where.and('price >= ?', [minPrice])
+if (category) where.and('category = ?', [category])
+
+const products = await Db.select(`SELECT * FROM products WHERE ${where.query}`, where.parameters)
+
+// CTE builder wraps Db directly
+const withMetrics = Sql.cte({
+  dailySales: {
+    subquery: '(SELECT DATE(created_at) as day, SUM(amount) as total FROM orders GROUP BY DATE(created_at))',
+    params: []
+  }
+}, Db)
+const trends = await withMetrics.select('SELECT * FROM dailySales WHERE total > ?', [1000])
+```

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+/** Map of CTE names to their subquery, parameters, and recursive flag */
+interface CommonTableExpressionSet {
+    [name: string]: {
+        /** The CTE body, wrapped in parentheses (e.g. `'(SELECT * FROM users WHERE active = ?)'`) */
+        subquery: string;
+        /** Parameters for the subquery placeholders — pass a function for dynamic resolution */
+        params?: any[] | (() => any[]);
+        /** Marks this CTE as recursive — triggers `WITH RECURSIVE` for the entire statement */
+        recursive?: boolean;
+    };
+}
+/** Merged configuration for a single CTE after parameter resolution */
+interface CommonTableExpressionConfig {
+    subquery: string;
+    params?: any[];
+    recursive?: boolean;
+}
+/**
+ * Db service interface that CTE builders accept and return.
+ *
+ * Mirrors the core Db service methods. The CTE builder wraps each method to
+ * automatically prepend the `WITH` clause and merge CTE parameters before
+ * the query parameters.
+ *
+ * @example
+ * ```ts
+ * const withTotals = Sql.cte({
+ *   orderTotals: { subquery: '(SELECT userId, SUM(amount) as total FROM orders GROUP BY userId)', params: [] }
+ * }, Db)
+ * await withTotals.select('SELECT * FROM orderTotals WHERE total > ?', [500])
+ * ```
+ */
+interface CteDbService {
+    /** Executes a SELECT query, returning an array of typed rows */
+    select<T = Record<string, unknown>>(query: string, parameters?: any[]): Promise<T[]>;
+    /** Executes a SELECT query, returning an async iterable for streaming results */
+    selectIterable<T = Record<string, unknown>>(query: string, parameters?: any[]): any;
+    /** Executes an INSERT query, returning affected row count and insert ID */
+    insert(query: string, parameters?: any[]): Promise<{
+        affectedRows: number;
+        insertId: number;
+    }>;
+    /** Executes an UPDATE query, returning affected and changed row counts */
+    update(query: string, parameters?: any[]): Promise<{
+        affectedRows: number;
+        changedRows: number;
+    }>;
+    /** Executes a DELETE query, returning affected row count */
+    delete(query: string, parameters?: any[]): Promise<{
+        affectedRows: number;
+    }>;
+    /** Executes an arbitrary SQL statement */
+    statement<T = unknown>(query: string, parameters?: any[]): Promise<T>;
+    /** Executes a query and returns a single scalar value, or `null` */
+    scalar<T = unknown>(query: string, parameters?: any[]): Promise<T | null>;
+    /** Executes the callback within a database transaction */
+    transaction: <T>(callback: () => Promise<T>) => Promise<T>;
+    /** Formats a query with interpolated parameters for debugging */
+    format: (query: string, params?: any[]) => string;
+}
+/**
+ * Creates a CTE builder that wraps a Db service with Common Table Expressions.
+ *
+ * Every query method on the returned object automatically prepends the `WITH`
+ * clause and merges CTE parameters before the query parameters. Use
+ * `fromDbService()` to re-wrap a different Db service with the same CTEs.
+ *
+ * @example
+ * ```ts
+ * const withStats = Sql.cte({
+ *   userStats: { subquery: '(SELECT userId, COUNT(*) as total FROM orders GROUP BY userId)', params: [] }
+ * }, Db)
+ * const results = await withStats.select('SELECT * FROM userStats WHERE total > ?', [10])
+ * ```
+ */
+declare function CommonTableExpressionBuilder(commonTableExpressions: CommonTableExpressionSet, db: CteDbService): {
+    fromDbService: (db: CteDbService) => CteDbService;
+    select: <T = Record<string, unknown>>(query: string, parameters?: any[]) => Promise<T[]>;
+    selectIterable: <T = Record<string, unknown>>(query: string, parameters?: any[]) => any;
+    insert: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+        insertId: number;
+    }>;
+    update: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+        changedRows: number;
+    }>;
+    delete: (query: string, parameters?: any[]) => Promise<{
+        affectedRows: number;
+    }>;
+    statement: <T = unknown>(query: string, parameters?: any[]) => Promise<T>;
+    scalar: <T = unknown>(query: string, parameters?: any[]) => Promise<T | null>;
+    format: (query: string, params?: any[]) => string;
+    transaction: <T>(callback: () => Promise<T>) => Promise<T>;
+};
+
+/** Callback that receives a sub-builder for creating parenthesized condition groups */
+type WhereClauseCallback = (builder: WhereClauseBuilder) => void;
+/**
+ * Mutable builder for constructing parameterized SQL WHERE clauses.
+ *
+ * Conditions are appended incrementally with {@link and} and {@link or}. Pass a
+ * callback to either method to wrap conditions in parentheses. Read {@link query}
+ * and {@link parameters} to get the assembled clause and its matching parameter array.
+ *
+ * @example
+ * ```ts
+ * const where = Sql.where()
+ * where.and('status = ?', ['active'])
+ * where.and(sub => {
+ *   sub.or('role = ?', ['admin'])
+ *   sub.or('role = ?', ['editor'])
+ * })
+ * where.query       // 'status = ? AND (role = ? OR role = ?)'
+ * where.parameters  // ['active', 'admin', 'editor']
+ * ```
+ */
+interface WhereClauseBuilder {
+    /** Appends a condition joined by `AND`, or a parenthesized group when given a callback */
+    and(condition: string | WhereClauseCallback, params?: any[]): void;
+    /** Appends a condition joined by `OR`, or a parenthesized group when given a callback */
+    or(condition: string | WhereClauseCallback, params?: any[]): void;
+    /** Returns the assembled WHERE clause string, or `'TRUE'` if no conditions were added */
+    readonly query: string;
+    /** Returns the parameter array matching the `?` placeholders in {@link query} */
+    readonly parameters: any[];
+}
+/**
+ * Creates a new WHERE clause builder for constructing parameterized SQL conditions.
+ *
+ * @example
+ * ```ts
+ * const builder = WhereClauseBuilder()
+ * builder.and('a = ?', [1])
+ * builder.and('b IN (?)', [[2, 3]])
+ * builder.or(qb => {
+ *    qb.and('c = ?', [4])
+ *    qb.or('d = ?', [5])
+ * })
+ * // a = ? AND b IN (?) OR (c = ? OR d = ?)
+ * // params: [1, [2, 3], 4, 5]
+ * ```
+ */
+declare function WhereClauseBuilder(existing?: WhereClauseBuilder): WhereClauseBuilder;
+
+/**
+ * Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions.
+ * Use `Sql.where()` for parameterized filters and `Sql.cte()` to wrap a Db service with CTEs.
+ */
+declare const Sql: {
+    cte: typeof CommonTableExpressionBuilder;
+    commonTableExpression: typeof CommonTableExpressionBuilder;
+    where: typeof WhereClauseBuilder;
+};
+/**
+ * Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions.
+ *
+ * The WHERE builder produces `{ query, parameters }` pairs for safe, incremental filter
+ * construction. The CTE builder wraps a Db service so every query method automatically
+ * prepends `WITH` expressions and merges parameters.
+ *
+ * @example
+ * ```ts
+ * // Dynamic WHERE clause
+ * const where = Sql.where()
+ * where.and('status = ?', ['active'])
+ * where.and('price > ?', [50])
+ * await Db.select(`SELECT * FROM products WHERE ${where.query}`, where.parameters)
+ *
+ * // CTE wrapping a Db service
+ * const withTotals = Sql.cte({
+ *   orderTotals: { subquery: '(SELECT userId, SUM(amount) as total FROM orders GROUP BY userId)', params: [] }
+ * }, Db)
+ * await withTotals.select('SELECT * FROM orderTotals WHERE total > ?', [500])
+ * ```
+ */
+declare namespace Sql {
+    namespace cte {
+        /** Configuration for a single CTE — subquery, parameters, and optional recursive flag */
+        type Expression = CommonTableExpressionConfig;
+        /** Map of CTE names to their configurations */
+        type ExpressionSet = CommonTableExpressionSet;
+        /** Db service interface that CTE builders accept and return */
+        type DbService = CteDbService;
+    }
+    /** Alias for {@link cte} — same types under the full name `commonTableExpression` */
+    namespace commonTableExpression {
+        /** Configuration for a single CTE — subquery, parameters, and optional recursive flag */
+        type Expression = CommonTableExpressionConfig;
+        /** Map of CTE names to their configurations */
+        type ExpressionSet = CommonTableExpressionSet;
+        /** Db service interface that CTE builders accept and return */
+        type DbService = CteDbService;
+    }
+    namespace where {
+        /** Mutable builder with `and()`, `or()`, `query`, and `parameters` for constructing WHERE clauses */
+        type Builder = WhereClauseBuilder;
+        /** Callback that receives a sub-builder for creating parenthesized condition groups */
+        type Callback = WhereClauseCallback;
+    }
+}
+
+export { Sql };

package/dist/index.js

@@ -0,0 +1,115 @@
+// src/cte.ts
+function mergeExpressions(commonTableExpressions) {
+  const queries = Object.entries(commonTableExpressions).map(([name, cte]) => {
+    const params2 = typeof cte.params === "function" ? cte.params() : cte.params;
+    return { statement: `${name} AS ${cte.subquery}`, params: params2 ?? [], recursive: cte.recursive };
+  });
+  const params = queries.flatMap((q) => q.params);
+  const subquery = `WITH ${queries.some((q) => q.recursive) ? "RECURSIVE " : ""}${queries.map((q) => q.statement).join(", ")}`;
+  return { params, subquery };
+}
+function CommonTableExpressionBuilder(commonTableExpressions, db) {
+  const cte = mergeExpressions(commonTableExpressions);
+  function getQueryAndParams(query, params = []) {
+    const q = `${cte.subquery} ${query}`;
+    const p = [...cte.params ?? [], ...params];
+    return [q, p];
+  }
+  function fromDbService(db2) {
+    return {
+      transaction: db2.transaction,
+      format(query, params) {
+        return db2.format(...getQueryAndParams(query, params));
+      },
+      select(query, params) {
+        return db2.select(...getQueryAndParams(query, params));
+      },
+      selectIterable(query, params) {
+        return db2.selectIterable(...getQueryAndParams(query, params));
+      },
+      insert(query, params) {
+        return db2.insert(...getQueryAndParams(query, params));
+      },
+      update(query, params) {
+        return db2.update(...getQueryAndParams(query, params));
+      },
+      delete(query, params) {
+        return db2.delete(...getQueryAndParams(query, params));
+      },
+      statement(query, params) {
+        return db2.statement(...getQueryAndParams(query, params));
+      },
+      scalar(query, params) {
+        return db2.scalar(...getQueryAndParams(query, params));
+      }
+    };
+  }
+  const facade = fromDbService(db);
+  return {
+    fromDbService,
+    select: facade.select,
+    selectIterable: facade.selectIterable,
+    insert: facade.insert,
+    update: facade.update,
+    delete: facade.delete,
+    statement: facade.statement,
+    scalar: facade.scalar,
+    format: facade.format,
+    transaction: facade.transaction
+  };
+}
+
+// src/where-clause.ts
+function WhereClauseBuilder(existing) {
+  let clause = existing?.query === "TRUE" ? void 0 : existing?.query;
+  const params = [...existing?.parameters || []];
+  function add(glue, condition, newParams = []) {
+    let conditionClause;
+    let conditionParams;
+    if (typeof condition === "function") {
+      const subBuilder = WhereClauseBuilder();
+      condition(subBuilder);
+      const subQuery = subBuilder.query;
+      if (subQuery === "TRUE") {
+        return;
+      }
+      conditionClause = `(${subQuery})`;
+      conditionParams = subBuilder.parameters;
+    } else {
+      conditionClause = condition;
+      conditionParams = newParams;
+    }
+    if (!clause) {
+      clause = conditionClause;
+    } else {
+      clause = `${clause} ${glue} ${conditionClause}`;
+    }
+    params.push(...conditionParams);
+  }
+  function and(condition, params2 = []) {
+    add("AND", condition, params2);
+  }
+  function or(condition, params2 = []) {
+    add("OR", condition, params2);
+  }
+  return {
+    and,
+    or,
+    get query() {
+      return clause || "TRUE";
+    },
+    get parameters() {
+      return params.length > 0 ? params : [];
+    }
+  };
+}
+
+// src/index.ts
+var Sql = {
+  cte: CommonTableExpressionBuilder,
+  commonTableExpression: CommonTableExpressionBuilder,
+  where: WhereClauseBuilder
+};
+export {
+  Sql
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@maestro-js/sql",
+  "description": "Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions (CTEs). Use when working with @maestro-js/sql, building dynamic SQL filters, constructing parameterized WHERE clauses, wrapping Db services with CTEs, or generating safe parameterized SQL fragments. Key capabilities: WhereClauseBuilder for incremental AND/OR conditions with nested sub-groups, CommonTableExpressionBuilder for wrapping a Db service so all queries auto-prepend WITH clauses, cloning builders, recursive CTEs, and dynamic parameter resolution.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@maestro-js/db": "1.0.0-alpha.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}