sumak 0.0.4 → 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,13 +227,30 @@ 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, 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())
 
+db.selectFrom("users").selectExpr(countDistinct(col.dept), "uniqueDepts").compile(db.printer())
+// SELECT COUNT(DISTINCT "dept") AS "uniqueDepts" FROM "users"
+
 db.selectFrom("orders").selectExpr(sum(col.amount), "totalAmount").compile(db.printer())
 
 db.selectFrom("orders").selectExpr(avg(col.amount), "avgAmount").compile(db.printer())
@@ -219,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
@@ -292,6 +375,122 @@ db.selectFrom("users")
   .compile(db.printer())
 ```
 
+## Window Functions
+
+```ts
+import { over, rowNumber, rank, denseRank, lag, lead, ntile, count, sum } from "sumak"
+
+// ROW_NUMBER() OVER (PARTITION BY dept ORDER BY salary DESC)
+db.selectFrom("employees")
+  .selectExpr(
+    over(rowNumber(), (w) => w.partitionBy("dept").orderBy("salary", "DESC")),
+    "rn",
+  )
+  .compile(db.printer())
+
+// RANK() OVER (ORDER BY score DESC)
+db.selectFrom("students")
+  .selectExpr(
+    over(rank(), (w) => w.orderBy("score", "DESC")),
+    "rnk",
+  )
+  .compile(db.printer())
+
+// Running total with frame
+db.selectFrom("orders")
+  .selectExpr(
+    over(sum(col.amount), (w) =>
+      w
+        .partitionBy("userId")
+        .orderBy("createdAt")
+        .rows({ type: "unbounded_preceding" }, { type: "current_row" }),
+    ),
+    "runningTotal",
+  )
+  .compile(db.printer())
+
+// LAG / LEAD
+db.selectFrom("prices")
+  .selectExpr(
+    over(lag(col.price, 1), (w) => w.orderBy("date")),
+    "prevPrice",
+  )
+  .compile(db.printer())
+
+// NTILE(4)
+db.selectFrom("employees")
+  .selectExpr(
+    over(ntile(4), (w) => w.orderBy("salary", "DESC")),
+    "quartile",
+  )
+  .compile(db.printer())
+```
+
+## SQL Functions
+
+### String Functions
+
+```ts
+import { upper, lower, concat, substring, trim, length } from "sumak"
+
+db.selectFrom("users").selectExpr(upper(col.name), "upperName").compile(db.printer())
+// SELECT UPPER("name") AS "upperName" FROM "users"
+
+db.selectFrom("users").selectExpr(lower(col.email), "lowerEmail").compile(db.printer())
+
+db.selectFrom("users")
+  .selectExpr(concat(col.firstName, val(" "), col.lastName), "fullName")
+  .compile(db.printer())
+
+db.selectFrom("users")
+  .selectExpr(substring(col.name, 1, 3), "prefix")
+  .compile(db.printer())
+
+db.selectFrom("users").selectExpr(trim(col.name), "trimmed").compile(db.printer())
+
+db.selectFrom("users").selectExpr(length(col.name), "nameLen").compile(db.printer())
+```
+
+### Numeric Functions
+
+```ts
+import { abs, round, ceil, floor } from "sumak"
+
+db.selectFrom("orders").selectExpr(abs(col.balance), "absBalance").compile(db.printer())
+
+db.selectFrom("orders").selectExpr(round(col.price, 2), "rounded").compile(db.printer())
+
+db.selectFrom("orders").selectExpr(ceil(col.amount), "ceiling").compile(db.printer())
+
+db.selectFrom("orders").selectExpr(floor(col.amount), "floored").compile(db.printer())
+```
+
+### Conditional Functions
+
+```ts
+import { nullif, greatest, least } from "sumak"
+
+db.selectFrom("users")
+  .selectExpr(nullif(col.age, val(0)), "ageOrNull")
+  .compile(db.printer())
+
+db.selectFrom("products")
+  .selectExpr(greatest(col.price, col.minPrice), "effectivePrice")
+  .compile(db.printer())
+
+db.selectFrom("products")
+  .selectExpr(least(col.price, col.maxPrice), "cappedPrice")
+  .compile(db.printer())
+```
+
+### Date/Time Functions
+
+```ts
+import { now, currentTimestamp } from "sumak"
+
+db.selectFrom("users").selectExpr(now(), "currentTime").compile(db.printer())
+```
+
 ## Set Operations
 
 ```ts
@@ -311,11 +510,13 @@ active.union(premium).compile(db.printer())
 // UNION ALL
 active.unionAll(premium).compile(db.printer())
 
-// INTERSECT
+// INTERSECT / INTERSECT ALL
 active.intersect(premium).compile(db.printer())
+active.intersectAll(premium).compile(db.printer())
 
-// EXCEPT
+// EXCEPT / EXCEPT ALL
 active.except(premium).compile(db.printer())
+active.exceptAll(premium).compile(db.printer())
 ```
 
 ## CTEs (WITH)
@@ -362,20 +563,95 @@ db.update("users")
 // UPDATE "users" SET "name" = $1 FROM "posts" WHERE ("id" = $2)
 ```
 
+## Conditional Query Building
+
+```ts
+const withFilter = true
+const withOrder = false
+
+db.selectFrom("users")
+  .select("id", "name")
+  .$if(withFilter, (qb) => qb.where(({ age }) => age.gt(18)))
+  .$if(withOrder, (qb) => qb.orderBy("name"))
+  .compile(db.printer())
+// WHERE applied, ORDER BY skipped
+
+// Multiple .where() calls are AND'd together
+db.selectFrom("users")
+  .select("id")
+  .where(({ age }) => age.gt(18))
+  .where(({ active }) => active.eq(true))
+  .compile(db.printer())
+// 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
+// INSERT ... SELECT
+const selectQuery = db.selectFrom("users").select("name", "age").build()
+db.insertInto("archive").fromSelect(selectQuery).compile(db.printer())
+
+// INSERT ... DEFAULT VALUES
+db.insertInto("users").defaultValues().compile(db.printer())
+
+// SQLite: INSERT OR IGNORE / INSERT OR REPLACE
+db.insertInto("users").values({ name: "Alice" }).orIgnore().compile(db.printer())
+// INSERT OR IGNORE INTO "users" ...
+
+db.insertInto("users").values({ name: "Alice" }).orReplace().compile(db.printer())
+// INSERT OR REPLACE INTO "users" ...
+```
+
 ## ON CONFLICT
 
 ```ts
-// DO NOTHING
+// DO NOTHING (by columns)
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
   .onConflictDoNothing("email")
   .compile(db.printer())
 
-// DO UPDATE
+// DO UPDATE (by columns)
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
   .onConflictDoUpdate(["email"], [{ column: "name", value: val("Alice") }])
   .compile(db.printer())
+
+// DO NOTHING (by constraint name)
+db.insertInto("users")
+  .values({ name: "Alice", email: "a@b.com" })
+  .onConflictConstraintDoNothing("users_email_key")
+  .compile(db.printer())
+// ON CONFLICT ON CONSTRAINT "users_email_key" DO NOTHING
+
+// MySQL: ON DUPLICATE KEY UPDATE
+db.insertInto("users")
+  .values({ name: "Alice" })
+  .onDuplicateKeyUpdate([{ column: "name", value: val("Alice") }])
+  .compile(db.printer())
 ```
 
 ## MERGE (SQL:2003)
@@ -395,6 +671,134 @@ db.mergeInto("users", "staging", "s", ({ target, source }) => target.id.eqCol(so
   .compile(db.printer())
 ```
 
+## Row Locking
+
+```ts
+// FOR UPDATE
+db.selectFrom("users").select("id").forUpdate().compile(db.printer())
+
+// FOR SHARE
+db.selectFrom("users").select("id").forShare().compile(db.printer())
+
+// FOR NO KEY UPDATE / FOR KEY SHARE (PG)
+db.selectFrom("users").select("id").forNoKeyUpdate().compile(db.printer())
+db.selectFrom("users").select("id").forKeyShare().compile(db.printer())
+
+// SKIP LOCKED / NOWAIT
+db.selectFrom("users").select("id").forUpdate().skipLocked().compile(db.printer())
+db.selectFrom("users").select("id").forUpdate().noWait().compile(db.printer())
+```
+
+## DISTINCT ON (PG)
+
+```ts
+db.selectFrom("users")
+  .selectAll()
+  .distinctOn("dept")
+  .orderBy("dept")
+  .orderBy("salary", "DESC")
+  .compile(db.printer())
+// SELECT DISTINCT ON ("dept") * FROM "users" ORDER BY "dept" ASC, "salary" DESC
+```
+
+## DELETE USING / JOIN in UPDATE & DELETE
+
+```ts
+// PG: DELETE ... USING
+db.deleteFrom("orders")
+  .using("users")
+  .where(eq(col("orders.user_id"), col("users.id")))
+  .compile(db.printer())
+
+// MySQL: DELETE with JOIN
+db.deleteFrom("orders")
+  .innerJoin("users", eq(col("user_id", "orders"), col("id", "users")))
+  .where(eq(col("name", "users"), lit("Alice")))
+  .compile(db.printer())
+
+// MySQL: UPDATE with JOIN
+db.update("orders")
+  .set({ total: 0 })
+  .innerJoin("users", eq(col("user_id", "orders"), col("id", "users")))
+  .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
+import { filter, count, sum } from "sumak"
+
+// COUNT(*) FILTER (WHERE active = true)
+db.selectFrom("users").selectExpr(filter(count(), activeExpr), "activeCount").compile(db.printer())
+```
+
+## EXPLAIN
+
+```ts
+// EXPLAIN
+db.selectFrom("users").select("id").explain().compile(db.printer())
+// EXPLAIN SELECT "id" FROM "users"
+
+// EXPLAIN ANALYZE
+db.selectFrom("users").select("id").explain({ analyze: true }).compile(db.printer())
+
+// EXPLAIN with format
+db.selectFrom("users").select("id").explain({ format: "JSON" }).compile(db.printer())
+// EXPLAIN (FORMAT JSON) SELECT "id" FROM "users"
+```
+
 ## Full-Text Search
 
 Dialect-aware FTS — same API, different SQL per dialect:

package/dist/ast/expression.d.mts

@@ -0,0 +1,26 @@
+import type { BetweenNode, BinaryOpNode, CastNode, ColumnRefNode, ExistsNode, ExpressionNode, FunctionCallNode, InNode, IsNullNode, LiteralNode, ParamNode, RawNode, SelectNode, StarNode, SubqueryNode, UnaryOpNode } from "./nodes.mjs";
+export declare function col(column: string, table?: string): ColumnRefNode;
+export declare function colAs(column: string, alias: string, table?: string): ColumnRefNode;
+export declare function lit(value: string | number | boolean | null): LiteralNode;
+export declare function star(table?: string): StarNode;
+export declare function param(index: number, value: unknown): ParamNode;
+export declare function raw(sql: string, params?: unknown[]): RawNode;
+export declare function subquery(query: SelectNode, alias?: string): SubqueryNode;
+export declare function fn(name: string, args: ExpressionNode[], alias?: string): FunctionCallNode;
+export declare function binOp(op: string, left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function unaryOp(op: string, operand: ExpressionNode, position?: "prefix" | "postfix"): UnaryOpNode;
+export declare function and(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function or(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function eq(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function neq(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function gt(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function gte(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function lt(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function lte(left: ExpressionNode, right: ExpressionNode): BinaryOpNode;
+export declare function like(expr: ExpressionNode, pattern: ExpressionNode): BinaryOpNode;
+export declare function between(expr: ExpressionNode, low: ExpressionNode, high: ExpressionNode, negated?: boolean): BetweenNode;
+export declare function inList(expr: ExpressionNode, values: ExpressionNode[] | SelectNode, negated?: boolean): InNode;
+export declare function isNull(expr: ExpressionNode, negated?: boolean): IsNullNode;
+export declare function cast(expr: ExpressionNode, dataType: string): CastNode;
+export declare function exists(query: SelectNode, negated?: boolean): ExistsNode;
+export declare function not(operand: ExpressionNode): UnaryOpNode;

package/dist/ast/expression.mjs

@@ -0,0 +1,140 @@
+export function col(column, table) {
+	return {
+		type: "column_ref",
+		column,
+		table
+	};
+}
+export function colAs(column, alias, table) {
+	return {
+		type: "column_ref",
+		column,
+		table,
+		alias
+	};
+}
+export function lit(value) {
+	return {
+		type: "literal",
+		value
+	};
+}
+export function star(table) {
+	return {
+		type: "star",
+		table
+	};
+}
+export function param(index, value) {
+	return {
+		type: "param",
+		index,
+		value
+	};
+}
+export function raw(sql, params = []) {
+	return {
+		type: "raw",
+		sql,
+		params
+	};
+}
+export function subquery(query, alias) {
+	return {
+		type: "subquery",
+		query,
+		alias
+	};
+}
+export function fn(name, args, alias) {
+	return {
+		type: "function_call",
+		name,
+		args,
+		alias
+	};
+}
+export function binOp(op, left, right) {
+	return {
+		type: "binary_op",
+		op,
+		left,
+		right
+	};
+}
+export function unaryOp(op, operand, position = "prefix") {
+	return {
+		type: "unary_op",
+		op,
+		operand,
+		position
+	};
+}
+export function and(left, right) {
+	return binOp("AND", left, right);
+}
+export function or(left, right) {
+	return binOp("OR", left, right);
+}
+export function eq(left, right) {
+	return binOp("=", left, right);
+}
+export function neq(left, right) {
+	return binOp("!=", left, right);
+}
+export function gt(left, right) {
+	return binOp(">", left, right);
+}
+export function gte(left, right) {
+	return binOp(">=", left, right);
+}
+export function lt(left, right) {
+	return binOp("<", left, right);
+}
+export function lte(left, right) {
+	return binOp("<=", left, right);
+}
+export function like(expr, pattern) {
+	return binOp("LIKE", expr, pattern);
+}
+export function between(expr, low, high, negated = false) {
+	return {
+		type: "between",
+		expr,
+		low,
+		high,
+		negated
+	};
+}
+export function inList(expr, values, negated = false) {
+	return {
+		type: "in",
+		expr,
+		values,
+		negated
+	};
+}
+export function isNull(expr, negated = false) {
+	return {
+		type: "is_null",
+		expr,
+		negated
+	};
+}
+export function cast(expr, dataType) {
+	return {
+		type: "cast",
+		expr,
+		dataType
+	};
+}
+export function exists(query, negated = false) {
+	return {
+		type: "exists",
+		query,
+		negated
+	};
+}
+export function not(operand) {
+	return unaryOp("NOT", operand);
+}