@happyvertical/sql 0.105.11 → 0.106.0

package/README.md

@@ -636,6 +636,94 @@ semantics for `where` and `having`, and maps time buckets per adapter:
 PostgreSQL, DuckDB, and JSON use `date_trunc(...)`; SQLite uses portable
 `strftime(...)`/`date(...)` expressions.
 
+#### Joins, row expressions and filtered aggregates
+
+A spec can join tables, aggregate a computed value, and count or sum only the
+rows a predicate holds for. All three are structured data (never SQL text):
+identifiers are validated, strings and dates are bound, and an aggregate that
+takes an `expr` or `filter` must be `count`, `sum`, `avg`, `min` or `max`.
+Other parts of an `AggregateSpec` predate this and are not hardened for
+untrusted input: `fn` is free-form for a plain column, and `raw()` keys in
+`where`/`having` use a string prefix that JSON can forge. Validate specs built
+from untrusted input before passing them in.
+
+```typescript
+const aggregate = buildAggregate(
+  {
+    from: 'time_entries',
+    fromAlias: 'te',
+    joins: [
+      {
+        table: 'work_orders',
+        alias: 'wo',
+        type: 'left', // 'inner' (default) or 'left'
+        on: {
+          op: 'and',
+          operands: [
+            { op: 'eq', left: { col: 'te.work_order_id' }, right: { col: 'wo.id' } },
+            // Put the tenant equality in ON so ids that collide across tenants never match.
+            { op: 'eq', left: { col: 'te.tenant_id' }, right: { col: 'wo.tenant_id' } },
+          ],
+        },
+      },
+    ],
+    select: [
+      { column: 'wo.title', as: 'title' },
+      { column: 'wo.estimated_hours', as: 'estimated_hours' },
+      { fn: 'sum', column: 'te.hours', as: 'booked' },
+      // Filtered count: rows where the predicate is true (false and NULL are skipped).
+      {
+        fn: 'count',
+        filter: { op: 'gt', left: { col: 'te.hours' }, right: { value: 8 } },
+        as: 'long_days',
+      },
+      // A row expression, aggregated.
+      {
+        fn: 'avg',
+        expr: { op: 'secondsBetween', later: { col: 'te.ended_at' }, earlier: { col: 'te.started_at' } },
+        as: 'avg_seconds',
+      },
+    ],
+    where: { 'te.tenant_id': tenantId },
+  },
+  1,
+  'postgres',
+);
+```
+
+- **Joins.** `from` takes an optional `fromAlias`; each join has a `table`, a
+  unique `alias` (letters, digits, underscore) and a required `on` expression.
+  With joins, a table-qualified column must be `alias.column` where the alias
+  is `from`, `fromAlias` or a join alias; anything else is rejected. The
+  builder does not know what a tenant is: the caller puts the tenant condition
+  in `on` and in `where`.
+- **Expressions.** Operands are `{ col }`, `{ value }` or a node:
+  `add | sub | mul | div` (`div` is fractional and returns NULL for a zero
+  divisor), `secondsBetween` (timestamp difference in seconds),
+  `eq | ne | lt | lte | gt | gte` (`eq`/`ne` against a NULL literal compare with
+  `IS [NOT] NULL`), `and | or | not`, `isNull | isNotNull` and `coalesce`.
+  Numbers, booleans and null are inlined after validation; strings and dates
+  are bound as parameters. Expressions are limited to depth 24 and 1024 nodes per spec.
+- **Where an expression goes.** `{ expr, as }` in `select` is a grouping key
+  (grouped by its position, so a bound value is not repeated); `expr` on an
+  aggregate replaces `column`; `filter` on an aggregate restricts its rows
+  (rendered as `CASE WHEN`, the same on every dialect); `whereExpr` is a row
+  predicate ANDed with the whole of `where` (OR groups included). `having` and `orderBy` refer to any of them by
+  alias, as before.
+- **Parameters.** Values are numbered in build order (select, joins, `where`,
+  `whereExpr`, `having`, paging) and returned in that order. A parameter used
+  by a select expression is referenced again, with the same number, when
+  `having` names its alias; adapters that rewrite `$N` must resolve each
+  occurrence by number (the bundled ones do).
+- Date literals follow `buildWhere`: PostgreSQL binds them as `CAST($N AS
+  TIMESTAMPTZ)`; DuckDB and JSON bind them as `CAST($N AS
+  TIMESTAMP)`, which is read in the session time zone, so compare a
+  `TIMESTAMPTZ` column against a date there with the zone in mind.
+- Specs without these fields produce the SQL they always did, except that a
+  dotted column with no `as` (`t.region`, which used to alias to the invalid
+  `t.region`) now aliases to its last segment. Two select items that resolve to
+  the same alias are rejected.
+
 ### Schema Synchronization
 
 ```typescript

package/dist/aggregate-expression.d.ts

@@ -0,0 +1,100 @@
+import type { SqlAdapterType } from './shared/utils.js';
+/**
+ * Closed, structured expression nodes for {@link buildAggregate}.
+ *
+ * An expression is data, never SQL text: every node is checked against a fixed
+ * set of operators, column references are validated identifiers, and literals
+ * are either inlined after validation (finite numbers, booleans, null) or
+ * bound as parameters (strings, dates). There is no raw-SQL escape hatch.
+ */
+/** A scalar a node may hold. Strings and dates are bound; the rest are inlined. */
+export type AggregateLiteral = string | number | boolean | Date | null;
+export type AggregateArithmeticOp = 'add' | 'sub' | 'mul' | 'div';
+export type AggregateComparisonOp = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte';
+export type AggregateOperand = 
+/** A column, bare (`qty`) or qualified by a table alias (`wo.estimated_hours`). */
+{
+    col: string;
+}
+/** A literal value. */
+ | {
+    value: AggregateLiteral;
+} | AggregateExpression;
+export type AggregateExpression = 
+/**
+ * `left op right`. `div` yields a fractional result on every dialect (integer
+ * operands are not truncated) and NULL, not an error, for a zero divisor.
+ */
+{
+    op: AggregateArithmeticOp;
+    left: AggregateOperand;
+    right: AggregateOperand;
+}
+/**
+ * Seconds from `earlier` to `later`, both timestamps; fractional, NULL if
+ * either is NULL. Positive when `later` is after `earlier`.
+ */
+ | {
+    op: 'secondsBetween';
+    later: AggregateOperand;
+    earlier: AggregateOperand;
+}
+/**
+ * A comparison. `eq`/`ne` against a NULL literal compare with IS [NOT] NULL;
+ * any other comparison involving NULL is NULL (not true), as in SQL.
+ */
+ | {
+    op: AggregateComparisonOp;
+    left: AggregateOperand;
+    right: AggregateOperand;
+} | {
+    op: 'and' | 'or';
+    operands: AggregateOperand[];
+} | {
+    op: 'not';
+    operand: AggregateOperand;
+} | {
+    op: 'isNull' | 'isNotNull';
+    operand: AggregateOperand;
+}
+/** The first operand that is not NULL. */
+ | {
+    op: 'coalesce';
+    operands: AggregateOperand[];
+};
+/** A table joined to the aggregate's `from`. */
+export interface AggregateJoin {
+    /** The joined table. */
+    table: string;
+    /** Its alias in the query; referenced as `alias.column`. Unique, no dots. */
+    alias: string;
+    /** `inner` (default) or `left`. */
+    type?: 'inner' | 'left';
+    /**
+     * The join condition. Callers put a tenant equality here (for example
+     * `eq(a.tenant_id, b.tenant_id)`) so ids that collide across tenants never
+     * match; the builder does not know what a tenant is.
+     */
+    on: AggregateExpression;
+}
+/** Where an expression renders: its identifier checks and its parameter numbering. */
+export interface ExpressionContext {
+    adapterType: SqlAdapterType | undefined;
+    /** The parameter index the next bound value takes. Advanced as values are bound. */
+    nextIndex: number;
+    /** Values bound so far, in index order. */
+    values: unknown[];
+    /** Validates (and returns) an identifier; throws on anything unsafe. */
+    identifier: (identifier: string) => string;
+    /** Called with each column reference so the caller can check its table alias. */
+    onColumn?: (column: string) => void;
+    /** Nodes rendered so far across every expression of one build; capped at {@link MAX_NODES}. */
+    nodeCount?: number;
+}
+/**
+ * Render an expression node to SQL, binding its string and date literals into
+ * `ctx` as numbered parameters. Throws on any unknown operator, unsafe
+ * identifier, non-finite number, or an expression too large to be legitimate.
+ */
+export declare function renderAggregateExpression(node: AggregateOperand, ctx: ExpressionContext): string;
+//# sourceMappingURL=aggregate-expression.d.ts.map

package/dist/aggregate-expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-expression.d.ts","sourceRoot":"","sources":["../src/aggregate-expression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvE,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAE9E,MAAM,MAAM,gBAAgB;AAC1B,mFAAmF;AACjF;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE;AACjB,uBAAuB;GACrB;IAAE,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC3B,mBAAmB,CAAC;AAExB,MAAM,MAAM,mBAAmB;AAC7B;;;GAGG;AACD;IACE,EAAE,EAAE,qBAAqB,CAAC;IAC1B,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AACH;;;GAGG;GACD;IAAE,EAAE,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE;AAC9E;;;GAGG;GACD;IACE,EAAE,EAAE,qBAAqB,CAAC;IAC1B,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,gBAAgB,CAAC;CACzB,GACD;IAAE,EAAE,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAClD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE;AAC3D,0CAA0C;GACxC;IAAE,EAAE,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAErD,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,EAAE,EAAE,mBAAmB,CAAC;CACzB;AAqBD,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,cAAc,GAAG,SAAS,CAAC;IACxC,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,wEAAwE;IACxE,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,iFAAiF;IACjF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgKD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,iBAAiB,GACrB,MAAM,CAER"}

package/dist/aggregate.d.ts

@@ -1,3 +1,4 @@
+import { type AggregateJoin, type AggregateOperand } from './aggregate-expression.js';
 import type { WhereClause } from './shared/types.js';
 import { type SqlAdapterType } from './shared/utils.js';
 export type AggregateTimeBucketUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
@@ -5,9 +6,22 @@ export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max' | (strin
 export type AggregateSelectExpr = {
     column: string;
     as?: string;
+}
+/** A row expression used as a grouping key (a computed column of each row). */
+ | {
+    expr: AggregateOperand;
+    as: string;
 } | {
     fn: AggregateFunction;
     column?: string;
+    /** A row expression to aggregate in place of `column` (not both). */
+    expr?: AggregateOperand;
+    /**
+     * Aggregate only the rows this predicate holds for (a filtered count or
+     * sum). Rows where it is false or NULL are skipped. With `count` and no
+     * column or expression it counts the matching rows.
+     */
+    filter?: AggregateOperand;
     as: string;
     distinct?: boolean;
 } | {
@@ -17,8 +31,17 @@ export type AggregateSelectExpr = {
 };
 export interface AggregateSpec {
     from: string;
+    /** Alias for `from`, so its columns can be qualified (`o.total`) beside joined tables. */
+    fromAlias?: string;
+    /**
+     * Tables joined to `from`, in order. With joins, a column naming a table must
+     * be qualified by `from`, `fromAlias` or a join alias.
+     */
+    joins?: AggregateJoin[];
     select: AggregateSelectExpr[];
     where?: WhereClause;
+    /** A row predicate built from expression nodes, ANDed with `where`. */
+    whereExpr?: AggregateOperand;
     groupBy?: string[];
     having?: WhereClause;
     orderBy?: string | string[];

package/dist/aggregate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAIL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,uBAAuB,GAC/B,QAAQ,GACR,MAAM,GACN,KAAK,GACL,MAAM,GACN,OAAO,GACP,SAAS,GACT,MAAM,CAAC;AAEX,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B;IACE,EAAE,EAAE,iBAAiB,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GACD;IACE,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,GAAG,EAAE,CAAC;CACf;AA+BD,wBAAgB,UAAU,CACxB,WAAW,EAAE,cAAc,GAAG,SAAS,EACvC,IAAI,EAAE,uBAAuB,EAC7B,MAAM,EAAE,MAAM,GACb,MAAM,CA4BR;AAgHD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,UAAU,SAAI,EACd,WAAW,CAAC,EAAE,cAAc,GAC3B,oBAAoB,CA8EtB"}
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAGtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAIL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,uBAAuB,GAC/B,QAAQ,GACR,MAAM,GACN,KAAK,GACL,MAAM,GACN,OAAO,GACP,SAAS,GACT,MAAM,CAAC;AAEX,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE;AACjC,+EAA+E;GAC7E;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtC;IACE,EAAE,EAAE,iBAAiB,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GACD;IACE,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,GAAG,EAAE,CAAC;CACf;AAgCD,wBAAgB,UAAU,CACxB,WAAW,EAAE,cAAc,GAAG,SAAS,EACvC,IAAI,EAAE,uBAAuB,EAC7B,MAAM,EAAE,MAAM,GACb,MAAM,CA4BR;AA+PD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,UAAU,SAAI,EACd,WAAW,CAAC,EAAE,cAAc,GAC3B,oBAAoB,CAmItB"}

package/dist/chunks/{duckdb-D4x661Ux.js → duckdb-EvsYk7GK.js}

@@ -1,5 +1,5 @@
+import { a as NestedTransactionError, o as resolveSchemas, s as convertUniqueIndexesToInlineConstraints } from "./query-B6ATOWzc.js";
 import { c as wrapDatabaseError, n as buildWhere, o as resolveInsertColumns, r as formatDbError, t as DatabaseSchemaManager } from "./schema-manager-tfASrb_b.js";
-import { a as NestedTransactionError, o as resolveSchemas, s as convertUniqueIndexesToInlineConstraints } from "./query-DubG7aF0.js";
 import { _ as validateColumnNames, c as createTransactionLock, d as validateDatabaseCacheOptions, f as escapeQuotedIdentifier, g as validateColumnName, h as generateCreateIndexStatement, m as generateAddColumnStatement, p as escapeStringLiteral, v as validateIndexName, y as validateTableName } from "./postgres-dialect-DIy5f5YR.js";
 import { n as createDuckDBResourceCloser, r as throwWithDuckDBCleanup, t as serializeDuckDBStatements } from "./duckdb-statement-queue-BJ6-PQRr.js";
 import { t as redactDatabaseUrl } from "./redact-database-url-CfMDvSdy.js";
@@ -1093,4 +1093,4 @@ async function getDatabase(options = {}) {
 //#endregion
 export { getDatabase };
 
-//# sourceMappingURL=duckdb-D4x661Ux.js.map
+//# sourceMappingURL=duckdb-EvsYk7GK.js.map