sumak 0.0.5 → 0.0.6

package/README.md

@@ -150,6 +150,19 @@ db.selectFrom("users").crossJoin("posts").compile(db.printer())
 .where(({ name }) =>
   name.like("%ali%"),
 )
+
+.where(({ name }) =>
+  name.notLike("%bob%"),
+)
+
+// Case-insensitive (PG)
+.where(({ name }) =>
+  name.ilike("%alice%"),
+)
+
+.where(({ email }) =>
+  email.notIlike("%spam%"),
+)
 ```
 
 ### Range & List
@@ -159,6 +172,15 @@ db.selectFrom("users").crossJoin("posts").compile(db.printer())
   age.between(18, 65),
 )
 
+.where(({ age }) =>
+  age.notBetween(18, 65),
+)
+
+// Order-independent (PG)
+.where(({ age }) =>
+  age.betweenSymmetric(65, 18),
+)
+
 .where(({ id }) =>
   id.in([1, 2, 3]),
 )
@@ -205,10 +227,24 @@ db.selectFrom("users").crossJoin("posts").compile(db.printer())
 )
 ```
 
+### Null-Safe Comparisons
+
+```ts
+// IS DISTINCT FROM — null-safe inequality
+.where(({ age }) =>
+  age.isDistinctFrom(null),
+)
+
+// IS NOT DISTINCT FROM — null-safe equality
+.where(({ age }) =>
+  age.isNotDistinctFrom(25),
+)
+```
+
 ### Aggregates
 
 ```ts
-import { count, countDistinct, sum, avg, min, max, coalesce } from "sumak"
+import { count, countDistinct, sumDistinct, avgDistinct, sum, avg, min, max, coalesce } from "sumak"
 
 db.selectFrom("users").selectExpr(count(), "total").compile(db.printer())
 
@@ -222,6 +258,50 @@ db.selectFrom("orders").selectExpr(avg(col.amount), "avgAmount").compile(db.prin
 db.selectFrom("orders")
   .selectExpr(coalesce(col.discount, val(0)), "safeDiscount")
   .compile(db.printer())
+
+// SUM(DISTINCT), AVG(DISTINCT)
+db.selectFrom("orders").selectExpr(sumDistinct(col.amount), "uniqueSum").compile(db.printer())
+db.selectFrom("orders").selectExpr(avgDistinct(col.amount), "uniqueAvg").compile(db.printer())
+
+// COALESCE with multiple fallbacks
+db.selectFrom("users")
+  .selectExpr(coalesce(col.nick, col.name, val("Anonymous")), "displayName")
+  .compile(db.printer())
+```
+
+### String & JSON Aggregates
+
+```ts
+import { stringAgg, arrayAgg, jsonAgg, jsonBuildObject } from "sumak"
+
+// STRING_AGG with ORDER BY
+db.selectFrom("users")
+  .selectExpr(stringAgg(col.name, ", ", [{ expr: col.name, direction: "ASC" }]), "names")
+  .compile(db.printer())
+// STRING_AGG("name", ', ' ORDER BY "name" ASC)
+
+// ARRAY_AGG
+db.selectFrom("users").selectExpr(arrayAgg(col.id), "ids").compile(db.printer())
+
+// JSON_AGG / JSON_BUILD_OBJECT
+db.selectFrom("users").selectExpr(jsonAgg(col.name), "namesJson").compile(db.printer())
+
+db.selectFrom("users")
+  .selectExpr(jsonBuildObject(["name", col.name], ["age", col.age]), "obj")
+  .compile(db.printer())
+```
+
+### Arithmetic
+
+```ts
+import { add, sub, mul, div, mod, neg } from "sumak"
+
+db.selectFrom("orders").selectExpr(mul(col.price, col.qty), "total").compile(db.printer())
+// ("price" * "qty") AS "total"
+
+db.selectFrom("orders")
+  .selectExpr(add(col.price, val(10)), "adjusted")
+  .compile(db.printer())
 ```
 
 ### EXISTS / NOT EXISTS
@@ -505,6 +585,28 @@ db.selectFrom("users")
 // WHERE ("age" > $1) AND ("active" = $2)
 ```
 
+## Reusable Query Fragments
+
+```ts
+// $call — pipe builder through a function
+const withPagination = (qb) => qb.limit(10).offset(20)
+const withActiveFilter = (qb) => qb.where(({ active }) => active.eq(true))
+
+db.selectFrom("users")
+  .select("id", "name")
+  .$call(withActiveFilter)
+  .$call(withPagination)
+  .compile(db.printer())
+
+// selectExprs — multiple aliased expressions at once
+db.selectFrom("users")
+  .selectExprs({
+    total: count(),
+    greeting: val("hello"),
+  })
+  .compile(db.printer())
+```
+
 ## INSERT Advanced
 
 ```ts
@@ -621,6 +723,58 @@ db.update("orders")
   .compile(db.printer())
 ```
 
+## Lateral JOIN
+
+```ts
+// INNER JOIN LATERAL — correlated subquery join
+const recentPosts = db
+  .selectFrom("posts")
+  .select("id", "title")
+  .where(({ userId }) => userId.eq(1))
+  .limit(3)
+
+db.selectFrom("users").innerJoinLateral(recentPosts, "rp", onExpr).compile(db.printer())
+// SELECT * FROM "users" INNER JOIN LATERAL (SELECT ...) AS "rp" ON ...
+
+// LEFT JOIN LATERAL
+db.selectFrom("users").leftJoinLateral(recentPosts, "rp", onExpr).compile(db.printer())
+```
+
+## Tuple Comparisons
+
+```ts
+import { tuple, val } from "sumak"
+
+// Row-value comparison: (id, age) = (1, 25)
+db.selectFrom("users")
+  .selectExpr(tuple(val(1), val(2), val(3)), "triple")
+  .compile(db.printer())
+// (1, 2, 3)
+```
+
+## SQL Template Literal
+
+```ts
+import { sql, val } from "sumak"
+
+// Tagged template with auto-parameterization
+sql`SELECT * FROM users WHERE name = ${"Alice"}`
+// params: ["Alice"]
+
+// Inline Expression values
+sql`SELECT * FROM users WHERE active = ${val(true)}`
+// → SELECT * FROM users WHERE active = TRUE
+
+// Helpers
+sql`SELECT ${sql.ref("id")} FROM ${sql.table("users", "public")}`
+// → SELECT "id" FROM "public"."users"
+
+// Use in selectExpr
+db.selectFrom("users")
+  .selectExpr(sql`CURRENT_DATE`, "today")
+  .compile(db.printer())
+```
+
 ## Aggregate FILTER (WHERE)
 
 ```ts

package/dist/ast/nodes.d.mts

@@ -6,7 +6,7 @@ export interface ExplainNode {
 	analyze?: boolean;
 	format?: "TEXT" | "JSON" | "YAML" | "XML";
 }
-export type ExpressionNode = ColumnRefNode | LiteralNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ParamNode | RawNode | SubqueryNode | BetweenNode | InNode | IsNullNode | CaseNode | CastNode | ExistsNode | StarNode | JsonAccessNode | ArrayExprNode | WindowFunctionNode | AliasedExprNode | FullTextSearchNode;
+export type ExpressionNode = ColumnRefNode | LiteralNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ParamNode | RawNode | SubqueryNode | BetweenNode | InNode | IsNullNode | CaseNode | CastNode | ExistsNode | StarNode | JsonAccessNode | ArrayExprNode | WindowFunctionNode | AliasedExprNode | FullTextSearchNode | TupleNode;
 export interface ColumnRefNode {
 	type: "column_ref";
 	table?: string;
@@ -35,6 +35,7 @@ export interface FunctionCallNode {
 	args: ExpressionNode[];
 	distinct?: boolean;
 	filter?: ExpressionNode;
+	orderBy?: OrderByNode[];
 	alias?: string;
 }
 export interface ParamNode {
@@ -58,6 +59,7 @@ export interface BetweenNode {
 	low: ExpressionNode;
 	high: ExpressionNode;
 	negated: boolean;
+	symmetric?: boolean;
 }
 export interface InNode {
 	type: "in";
@@ -102,6 +104,10 @@ export interface FullTextSearchNode {
 	language?: string;
 	alias?: string;
 }
+export interface TupleNode {
+	type: "tuple";
+	elements: ExpressionNode[];
+}
 export interface AliasedExprNode {
 	type: "aliased_expr";
 	expr: ExpressionNode;
@@ -137,6 +143,7 @@ export interface JoinNode {
 	joinType: JoinType;
 	table: TableRefNode | SubqueryNode;
 	on?: ExpressionNode;
+	lateral?: boolean;
 }
 export interface JsonAccessNode {
 	type: "json_access";
@@ -256,6 +263,8 @@ export interface UpdateNode {
 	from?: TableRefNode;
 	joins: JoinNode[];
 	ctes: CTENode[];
+	orderBy?: OrderByNode[];
+	limit?: ExpressionNode;
 }
 export interface DeleteNode {
 	type: "delete";
@@ -265,6 +274,8 @@ export interface DeleteNode {
 	ctes: CTENode[];
 	using?: TableRefNode;
 	joins: JoinNode[];
+	orderBy?: OrderByNode[];
+	limit?: ExpressionNode;
 }
 export interface MergeWhenMatched {
 	type: "matched";

package/dist/builder/delete.d.mts

@@ -11,6 +11,8 @@ export declare class DeleteBuilder {
 	join(type: JoinType, table: string | TableRefNode, on?: ExpressionNode): DeleteBuilder;
 	innerJoin(table: string | TableRefNode, on: ExpressionNode): DeleteBuilder;
 	leftJoin(table: string | TableRefNode, on: ExpressionNode): DeleteBuilder;
+	orderBy(expr: string | ExpressionNode, direction?: "ASC" | "DESC"): DeleteBuilder;
+	limit(n: ExpressionNode): DeleteBuilder;
 	returning(...exprs: ExpressionNode[]): DeleteBuilder;
 	with(name: string, query: SelectNode, recursive?: boolean): DeleteBuilder;
 	build(): DeleteNode;

package/dist/builder/delete.mjs

@@ -68,6 +68,25 @@ export class DeleteBuilder {
 	leftJoin(table, on) {
 		return this.join("LEFT", table, on);
 	}
+	orderBy(expr, direction = "ASC") {
+		const node = {
+			expr: typeof expr === "string" ? {
+				type: "column_ref",
+				column: expr
+			} : expr,
+			direction
+		};
+		return new DeleteBuilder({
+			...this.node,
+			orderBy: [...this.node.orderBy ?? [], node]
+		});
+	}
+	limit(n) {
+		return new DeleteBuilder({
+			...this.node,
+			limit: n
+		});
+	}
 	returning(...exprs) {
 		return new DeleteBuilder({
 			...this.node,

package/dist/builder/eb.d.mts

@@ -26,6 +26,12 @@ export declare class Col<T> {
 	lte(value: T): Expression<boolean>;
 	/** LIKE (string columns only) */
 	like(this: Col<string>, pattern: string): Expression<boolean>;
+	/** NOT LIKE */
+	notLike(this: Col<string>, pattern: string): Expression<boolean>;
+	/** ILIKE — case-insensitive LIKE (PG) */
+	ilike(this: Col<string>, pattern: string): Expression<boolean>;
+	/** NOT ILIKE (PG) */
+	notIlike(this: Col<string>, pattern: string): Expression<boolean>;
 	/** IN (value1, value2, ...) */
 	in(values: T[]): Expression<boolean>;
 	/** NOT IN */
@@ -36,8 +42,42 @@ export declare class Col<T> {
 	isNotNull(): Expression<boolean>;
 	/** BETWEEN low AND high */
 	between(low: T, high: T): Expression<boolean>;
+	/** NOT BETWEEN low AND high */
+	notBetween(low: T, high: T): Expression<boolean>;
+	/** BETWEEN SYMMETRIC low AND high (PG) — order-independent range check */
+	betweenSymmetric(low: T, high: T): Expression<boolean>;
+	/** IN (SELECT ...) — subquery */
+	inSubquery(query: SelectNode): Expression<boolean>;
+	/** NOT IN (SELECT ...) — subquery */
+	notInSubquery(query: SelectNode): Expression<boolean>;
+	/** = with Expression value */
+	eqExpr(value: Expression<T>): Expression<boolean>;
+	/** != with Expression value */
+	neqExpr(value: Expression<T>): Expression<boolean>;
+	/** > with Expression value */
+	gtExpr(value: Expression<T>): Expression<boolean>;
+	/** >= with Expression value */
+	gteExpr(value: Expression<T>): Expression<boolean>;
+	/** < with Expression value */
+	ltExpr(value: Expression<T>): Expression<boolean>;
+	/** <= with Expression value */
+	lteExpr(value: Expression<T>): Expression<boolean>;
+	/** IS DISTINCT FROM — null-safe inequality */
+	isDistinctFrom(value: T): Expression<boolean>;
+	/** IS NOT DISTINCT FROM — null-safe equality */
+	isNotDistinctFrom(value: T): Expression<boolean>;
 	/** Compare with another column: col1.eqCol(col2) */
 	eqCol(other: Col<T>): Expression<boolean>;
+	/** != another column */
+	neqCol(other: Col<T>): Expression<boolean>;
+	/** > another column */
+	gtCol(other: Col<T>): Expression<boolean>;
+	/** < another column */
+	ltCol(other: Col<T>): Expression<boolean>;
+	/** >= another column */
+	gteCol(other: Col<T>): Expression<boolean>;
+	/** <= another column */
+	lteCol(other: Col<T>): Expression<boolean>;
 	/** As raw Expression<T> for advanced use */
 	toExpr(): Expression<T>;
 }
@@ -69,12 +109,21 @@ export type WhereCallback<
 	DB,
 	TB extends keyof DB
 > = (cols: ColumnProxies<DB, TB>) => Expression<boolean>;
-/** AND two expressions */
-export declare function and(left: Expression<boolean>, right: Expression<boolean>): Expression<boolean>;
-/** OR two expressions */
-export declare function or(left: Expression<boolean>, right: Expression<boolean>): Expression<boolean>;
+/** AND expressions — variadic: and(a, b) or and(a, b, c, ...) */
+export declare function and(...exprs: Expression<boolean>[]): Expression<boolean>;
+/** OR expressions — variadic: or(a, b) or or(a, b, c, ...) */
+export declare function or(...exprs: Expression<boolean>[]): Expression<boolean>;
 /** Raw literal value as expression */
 export declare function val<T extends string | number | boolean | null>(value: T): Expression<T>;
+/**
+* Raw SQL expression — escape hatch for arbitrary SQL in expressions.
+*
+* ```ts
+* .where(() => rawExpr("age > 18"))
+* .selectExpr(rawExpr<number>("EXTRACT(YEAR FROM created_at)"), "year")
+* ```
+*/
+export declare function rawExpr<T = unknown>(sql: string, params?: unknown[]): Expression<T>;
 /** SQL function call */
 export declare function sqlFn(name: string, ...args: Expression<any>[]): Expression<any>;
 /** COUNT(*) */
@@ -83,16 +132,32 @@ export declare function count(): Expression<number>;
 export declare function countDistinct(expr: Expression<any>): Expression<number>;
 /** SUM(expr) */
 export declare function sum(expr: Expression<number>): Expression<number>;
+/** SUM(DISTINCT expr) */
+export declare function sumDistinct(expr: Expression<number>): Expression<number>;
 /** AVG(expr) */
 export declare function avg(expr: Expression<number>): Expression<number>;
+/** AVG(DISTINCT expr) */
+export declare function avgDistinct(expr: Expression<number>): Expression<number>;
 /** MIN(expr) */
 export declare function min<T>(expr: Expression<T>): Expression<T>;
 /** MAX(expr) */
 export declare function max<T>(expr: Expression<T>): Expression<T>;
-/** COALESCE(expr, fallback) */
-export declare function coalesce<T>(expr: Expression<T | null>, fallback: Expression<T>): Expression<T>;
+/** COALESCE(a, b, c, ...) — returns first non-null value */
+export declare function coalesce<T>(...args: Expression<T | null>[]): Expression<T>;
 /** NOT expr */
 export declare function not(expr: Expression<boolean>): Expression<boolean>;
+/** Add: a + b */
+export declare function add(a: Expression<number>, b: Expression<number>): Expression<number>;
+/** Subtract: a - b */
+export declare function sub(a: Expression<number>, b: Expression<number>): Expression<number>;
+/** Multiply: a * b */
+export declare function mul(a: Expression<number>, b: Expression<number>): Expression<number>;
+/** Divide: a / b */
+export declare function div(a: Expression<number>, b: Expression<number>): Expression<number>;
+/** Modulo: a % b */
+export declare function mod(a: Expression<number>, b: Expression<number>): Expression<number>;
+/** Unary minus: -expr */
+export declare function neg(expr: Expression<number>): Expression<number>;
 /** EXISTS (subquery) */
 export declare function exists(query: SelectNode): Expression<boolean>;
 /** NOT EXISTS (subquery) */
@@ -156,6 +221,7 @@ export declare class WindowBuilder {
 	orderBy(column: string, direction?: "ASC" | "DESC"): WindowBuilder;
 	rows(start: FrameBound, end?: FrameBound): WindowBuilder;
 	range(start: FrameBound, end?: FrameBound): WindowBuilder;
+	groups(start: FrameBound, end?: FrameBound): WindowBuilder;
 }
 /** ROW_NUMBER() — must be used with over() */
 export declare function rowNumber(): Expression<number>;
@@ -197,8 +263,44 @@ export declare function abs(expr: Expression<number>): Expression<number>;
 export declare function round(expr: Expression<number>, precision?: number): Expression<number>;
 /** CEIL(expr) */
 export declare function ceil(expr: Expression<number>): Expression<number>;
+/** JSON_AGG(expr) — aggregate rows into JSON array (PG) */
+export declare function jsonAgg<T>(expr: Expression<T>): Expression<T[]>;
+/** TO_JSON(expr) — convert value to JSON (PG) */
+export declare function toJson<T>(expr: Expression<T>): Expression<unknown>;
+/** JSON_BUILD_OBJECT(key, value, ...) — build JSON object (PG) */
+export declare function jsonBuildObject(...pairs: [string, Expression<any>][]): Expression<Record<string, unknown>>;
+/** @> (array contains) */
+export declare function arrayContains(arr: Expression<any>, values: Expression<any>): Expression<boolean>;
+/** <@ (array contained by) */
+export declare function arrayContainedBy(arr: Expression<any>, values: Expression<any>): Expression<boolean>;
+/** && (array overlaps) */
+export declare function arrayOverlaps(arr: Expression<any>, values: Expression<any>): Expression<boolean>;
 /** FLOOR(expr) */
 export declare function floor(expr: Expression<number>): Expression<number>;
+/** STRING_AGG(expr, delimiter) — aggregate strings with separator */
+export declare function stringAgg(expr: Expression<string>, delimiter: string, orderBy?: {
+	expr: Expression<any>;
+	direction?: "ASC" | "DESC";
+}[]): Expression<string>;
+/** ARRAY_AGG(expr) — aggregate values into array */
+export declare function arrayAgg<T>(expr: Expression<T>, orderBy?: {
+	expr: Expression<any>;
+	direction?: "ASC" | "DESC";
+}[]): Expression<T[]>;
+/** Attach ORDER BY to an existing aggregate expression. */
+export declare function aggOrderBy<T>(agg: Expression<T>, orderBy: {
+	expr: Expression<any>;
+	direction?: "ASC" | "DESC";
+}[]): Expression<T>;
+/**
+* Row-value tuple for comparisons.
+*
+* ```ts
+* // (a, b) = (1, 2)
+* tuple(cols.a.toExpr(), cols.b.toExpr())
+* ```
+*/
+export declare function tuple(...exprs: Expression<any>[]): Expression<any>;
 /**
 * Attach FILTER (WHERE ...) to an aggregate expression.
 *