sumak 0.0.8 → 0.0.10

package/README.md

@@ -41,6 +41,9 @@
 - [Schema Builder (DDL)](#schema-builder-ddl)
 - [Full-Text Search](#full-text-search)
 - [Temporal Tables](#temporal-tables-sql2011)
+- [JSON Optics](#json-optics)
+- [Compiled Queries](#compiled-queries)
+- [Query Optimization](#query-optimization)
 - [Plugins](#plugins)
 - [Hooks](#hooks)
 - [Dialects](#dialects)
@@ -428,6 +431,8 @@ db.selectFrom("users")
   .toSQL()
 ```
 
+> For composable, type-tracked JSON navigation, see [JSON Optics](#json-optics).
+
 ### PostgreSQL Array Operators
 
 ```ts
@@ -689,6 +694,38 @@ Available: `clearWhere()`, `clearOrderBy()`, `clearLimit()`, `clearOffset()`, `c
 
 ---
 
+## Cursor Pagination
+
+```ts
+// Forward pagination (after cursor)
+db.selectFrom("users")
+  .select("id", "name")
+  .cursorPaginate({ column: "id", after: 42, pageSize: 20 })
+  .toSQL()
+// SELECT "id", "name" FROM "users" WHERE ("id" > $1) ORDER BY "id" ASC LIMIT 21
+// params: [42] — pageSize + 1 for hasNextPage detection
+
+// Backward pagination (before cursor)
+db.selectFrom("users")
+  .select("id", "name")
+  .cursorPaginate({ column: "id", before: 100, pageSize: 20 })
+  .toSQL()
+// WHERE ("id" < $1) ORDER BY "id" DESC LIMIT 21
+
+// First page (no cursor)
+db.selectFrom("users").select("id", "name").cursorPaginate({ column: "id", pageSize: 20 }).toSQL()
+// LIMIT 21
+
+// With existing WHERE — ANDs together
+db.selectFrom("users")
+  .select("id", "name")
+  .where(({ active }) => active.eq(true))
+  .cursorPaginate({ column: "id", after: lastId, pageSize: 20 })
+  .toSQL()
+```
+
+---
+
 ## Raw SQL
 
 ### `sql` tagged template
@@ -980,16 +1017,277 @@ Modes: `as_of`, `from_to`, `between`, `contained_in`, `all`.
 
 ---
 
+## JSON Optics
+
+Composable, type-tracked JSON column navigation. Each `.at()` step tracks the type at that level.
+
+```ts
+import { jsonCol } from "sumak"
+
+// Navigate into JSON: -> (returns JSON)
+db.selectFrom("users")
+  .selectExprs(jsonCol("data").at("address").at("city").asText().as("city"))
+  .toSQL()
+// SELECT "data"->'address'->>'city' AS "city" FROM "users"
+
+// Text extraction: ->> (returns text)
+db.selectFrom("users").selectExprs(jsonCol("meta").text("name").as("metaName")).toSQL()
+// SELECT "meta"->>'name' AS "metaName" FROM "users"
+
+// PG path operators: #> and #>>
+jsonCol("data").atPath("address.city") // #>  (returns JSON)
+jsonCol("data").textPath("address.city") // #>> (returns text)
+
+// With table prefix
+jsonCol("data", "users").at("settings").asText()
+```
+
+Type-safe with generics:
+
+```ts
+interface UserProfile {
+  address: { city: string; zip: string }
+  preferences: { theme: string }
+}
+
+// Type narrows at each level
+jsonCol<UserProfile>("profile")
+  .at("address") // JsonOptic<{ city: string; zip: string }>
+  .at("city") // JsonOptic<string>
+  .asText() // JsonExpr<string>
+```
+
+---
+
+## Compiled Queries
+
+Pre-bake SQL at setup time. At runtime, only fill parameters — zero AST traversal.
+
+```ts
+import { placeholder, compileQuery } from "sumak"
+
+// Define query with named placeholders
+const findUser = compileQuery<{ userId: number }>(
+  db
+    .selectFrom("users")
+    .select("id", "name")
+    .where(({ id }) => id.eq(placeholder("userId")))
+    .build(),
+  db.printer(),
+)
+
+// Runtime — same SQL string, different params:
+findUser({ userId: 42 })
+// → { sql: 'SELECT "id", "name" FROM "users" WHERE "id" = $1', params: [42] }
+
+findUser({ userId: 99 })
+// → { sql: 'SELECT "id", "name" FROM "users" WHERE "id" = $1', params: [99] }
+
+// Inspect the pre-baked SQL
+findUser.sql // 'SELECT "id", "name" FROM "users" WHERE "id" = $1'
+```
+
+---
+
+## Query Optimization
+
+sumak automatically normalizes and optimizes queries through two new pipeline layers.
+
+### Normalization (NbE)
+
+Enabled by default. Reduces expressions to canonical form:
+
+- **Flatten AND/OR:** `(a AND (b AND c))` → `(a AND b AND c)`
+- **Deduplicate:** `a = 1 AND b = 2 AND a = 1` → `a = 1 AND b = 2`
+- **Simplify tautologies:** `x AND true` → `x`, `x OR false` → `x`
+- **Constant folding:** `1 + 2` → `3`
+- **Double negation:** `NOT NOT x` → `x`
+- **Comparison normalization:** `1 = x` → `x = 1`
+
+### Optimization (Rewrite Rules)
+
+Built-in rules applied after normalization:
+
+- **Predicate pushdown:** Moves WHERE conditions into JOIN ON when they reference a single table
+- **Subquery flattening:** `SELECT * FROM (SELECT * FROM t)` → `SELECT * FROM t`
+- **WHERE true removal:** Cleans up `WHERE true` left by plugins
+
+### Configuration
+
+```ts
+// Default: both enabled
+const db = sumak({ dialect: pgDialect(), tables: { ... } })
+
+// Disable normalization
+const db = sumak({ dialect: pgDialect(), normalize: false, tables: { ... } })
+
+// Disable optimization
+const db = sumak({ dialect: pgDialect(), optimizeQueries: false, tables: { ... } })
+```
+
+### Custom Rewrite Rules
+
+```ts
+import { createRule } from "sumak"
+
+const defaultLimit = createRule({
+  name: "default-limit",
+  match: (node) => node.type === "select" && !node.limit,
+  apply: (node) => ({ ...node, limit: { type: "literal", value: 1000 } }),
+})
+
+const db = sumak({
+  dialect: pgDialect(),
+  rules: [defaultLimit],
+  tables: { ... },
+})
+```
+
+Rules are applied bottom-up until a fixpoint (no more changes). Max 10 iterations by default.
+
+---
+
 ## Plugins
 
+### WithSchemaPlugin
+
+```ts
+const db = sumak({
+  plugins: [new WithSchemaPlugin("public")],
+  ...
+})
+// SELECT * FROM "public"."users"
+```
+
+### SoftDeletePlugin
+
+```ts
+// Mode "convert" (default) — DELETE becomes UPDATE SET deleted_at = NOW()
+const db = sumak({
+  plugins: [new SoftDeletePlugin({ tables: ["users"], mode: "convert" })],
+  ...
+})
+
+db.deleteFrom("users").where(({ id }) => id.eq(1)).toSQL()
+// UPDATE "users" SET "deleted_at" = NOW() WHERE ("id" = $1) AND ("deleted_at" IS NULL)
+
+// Mode "filter" — just adds WHERE deleted_at IS NULL (no DELETE conversion)
+new SoftDeletePlugin({ tables: ["users"], mode: "filter" })
+```
+
+### AuditTimestampPlugin
+
+```ts
+// Auto-inject created_at/updated_at timestamps
+const db = sumak({
+  plugins: [new AuditTimestampPlugin({ tables: ["users"] })],
+  ...
+})
+
+db.insertInto("users").values({ name: "Alice" }).toSQL()
+// INSERT INTO "users" ("name", "created_at", "updated_at") VALUES ($1, NOW(), NOW())
+
+db.update("users").set({ name: "Bob" }).where(({ id }) => id.eq(1)).toSQL()
+// UPDATE "users" SET "name" = $1, "updated_at" = NOW() WHERE ...
+```
+
+### MultiTenantPlugin
+
+```ts
+// Auto-inject tenant_id on all queries
+// Use a callback for per-request tenant resolution:
+const db = sumak({
+  plugins: [
+    new MultiTenantPlugin({
+      tables: ["users", "posts"],
+      tenantId: () => getCurrentTenantId(),  // called per query
+    }),
+  ],
+  ...
+})
+
+db.selectFrom("users").select("id").toSQL()
+// SELECT "id" FROM "users" WHERE ("tenant_id" = $1)
+
+db.insertInto("users").values({ name: "Alice" }).toSQL()
+// INSERT INTO "users" ("name", "tenant_id") VALUES ($1, $2)
+```
+
+### QueryLimitPlugin
+
+```ts
+// Auto-inject LIMIT on unbounded SELECTs
+const db = sumak({
+  plugins: [new QueryLimitPlugin({ maxRows: 1000 })],
+  ...
+})
+
+db.selectFrom("users").select("id").toSQL()
+// SELECT "id" FROM "users" LIMIT 1000
+
+db.selectFrom("users").select("id").limit(5).toSQL()
+// SELECT "id" FROM "users" LIMIT 5  — explicit limit preserved
+```
+
+### CamelCasePlugin
+
 ```ts
-import { WithSchemaPlugin, SoftDeletePlugin, CamelCasePlugin } from "sumak"
+// Transform snake_case result columns to camelCase
+const db = sumak({
+  plugins: [new CamelCasePlugin()],
+  ...
+})
+```
+
+### OptimisticLockPlugin
 
+```ts
+// Auto-inject WHERE version = N and SET version = version + 1 on UPDATE
+// Use a callback for per-row version:
+let rowVersion = 3
+const db = sumak({
+  plugins: [
+    new OptimisticLockPlugin({
+      tables: ["users"],
+      currentVersion: () => rowVersion,  // called per query
+    }),
+  ],
+  ...
+})
+
+rowVersion = fetchedRow.version  // set before each update
+db.update("users").set({ name: "Bob" }).where(({ id }) => id.eq(1)).toSQL()
+// UPDATE "users" SET "name" = $1, "version" = ("version" + 1)
+//   WHERE ("id" = $2) AND ("version" = $3)
+```
+
+### DataMaskingPlugin
+
+```ts
+// Mask sensitive data in query results
+const plugin = new DataMaskingPlugin({
+  rules: [
+    { column: "email", mask: "email" },    // "alice@example.com" → "al***@example.com"
+    { column: "phone", mask: "phone" },    // "+1234567890" → "***7890"
+    { column: "name", mask: "partial" },   // "John Doe" → "Jo***"
+    { column: "ssn", mask: (v) => `***-**-${String(v).slice(-4)}` },  // custom
+  ],
+})
+
+const db = sumak({ plugins: [plugin], ... })
+```
+
+### Combining Plugins
+
+```ts
 const db = sumak({
   dialect: pgDialect(),
   plugins: [
-    new WithSchemaPlugin("public"),      // auto "public"."users"
-    new SoftDeletePlugin({ tables: ["users"] }), // auto WHERE deleted_at IS NULL
+    new WithSchemaPlugin("public"),
+    new SoftDeletePlugin({ tables: ["users"] }),
+    new AuditTimestampPlugin({ tables: ["users", "posts"] }),
+    new MultiTenantPlugin({ tables: ["users", "posts"], tenantId: () => currentTenantId }),
+    new QueryLimitPlugin({ maxRows: 5000 }),
   ],
   tables: { ... },
 })
@@ -1054,7 +1352,7 @@ import { serial, text } from "sumak/schema"
 
 ## Architecture
 
-sumak uses a 5-layer pipeline. Your code never touches SQL strings — everything flows through an AST.
+sumak uses a 7-layer pipeline. Your code never touches SQL strings — everything flows through an AST.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -1074,7 +1372,15 @@ sumak uses a 5-layer pipeline. Your code never touches SQL strings — everythin
 │     Plugin.transformNode() → Hook "query:before"                │
 │     → AST rewriting, tenant isolation, soft delete, logging     │
 ├─────────────────────────────────────────────────────────────────┤
-│  5. PRINTER                                                     │
+│  5. NORMALIZE (NbE)                                             │
+│     Predicate simplification, constant folding, deduplication   │
+│     → Canonical form via Normalization by Evaluation            │
+├─────────────────────────────────────────────────────────────────┤
+│  6. OPTIMIZE (Rewrite Rules)                                    │
+│     Predicate pushdown, subquery flattening, user rules         │
+│     → Declarative rules applied to fixpoint                     │
+├─────────────────────────────────────────────────────────────────┤
+│  7. PRINTER                                                     │
 │     .toSQL() → { sql: "SELECT ...", params: [...] }             │
 │     → Dialect-specific: PG ($1), MySQL (?), MSSQL (@p0)        │
 └─────────────────────────────────────────────────────────────────┘
@@ -1086,6 +1392,8 @@ The query is never a string until the very last step. This means:
 
 - **Plugins can rewrite queries** — add WHERE clauses, prefix schemas, transform joins
 - **Hooks can inspect/modify** — logging, tracing, tenant isolation
+- **Normalize simplifies** — duplicate predicates, tautologies, constant expressions
+- **Optimize rewrites** — predicate pushdown, subquery flattening, custom rules
 - **Printers are swappable** — same AST, different SQL per dialect
 - **No SQL injection** — values are always parameterized
 
@@ -1095,6 +1403,8 @@ The query is never a string until the very last step. This means:
 - **Immutable builders** — every method returns a new instance
 - **Proxy-based column access** — `({ age }) => age.gt(18)` with full type safety
 - **Phantom types** — `Expression<T>` carries type info with zero runtime cost
+- **NbE normalization** — expressions reduced to canonical form before printing
+- **Compiled queries** — pre-bake SQL at setup, zero AST walk at runtime
 
 ---
 

package/dist/builder/json-optics.d.mts

@@ -0,0 +1,106 @@
+import type { ExpressionNode } from "../ast/nodes.mjs";
+import type { Expression } from "../ast/typed-expression.mjs";
+/**
+* JSON optics — composable, type-tracked JSON column navigation.
+*
+* Each `.at()` step creates a new optic that tracks the type at that level.
+* The final expression is a chain of JSON access operators.
+*
+* ```ts
+* // Type-tracked navigation:
+* jsonCol<UserProfile>("profile")
+*   .at("address")              // JsonOptic<Address>
+*   .at("city")                 // JsonOptic<string>
+*   .asText()                   // Expression<string>
+*
+* // Use in SELECT:
+* db.selectFrom("users")
+*   .selectExprs(jsonCol("data").at("name").asText().as("name"))
+* ```
+*
+* **Dialect-aware operators:**
+* - `.at("key")` → `->` (returns JSON)
+* - `.asText()` → `->>` (returns text)
+* - `.atPath("a.b.c")` → `#>` (PG path operator)
+* - `.asTextPath("a.b.c")` → `#>>` (PG text path operator)
+*/
+export declare class JsonOptic<T = unknown> {
+	readonly _type: T;
+	constructor(node: ExpressionNode);
+	/**
+	* Navigate into a JSON object key. Returns JSON type.
+	*
+	* ```ts
+	* jsonCol("data").at("address") // → data->'address'
+	* ```
+	*/
+	at<K extends string>(key: K): JsonOptic<T extends Record<K, infer V> ? V : unknown>;
+	/**
+	* Navigate into a JSON object key and extract as text.
+	*
+	* ```ts
+	* jsonCol("data").text("name") // → data->>'name' (returns string)
+	* ```
+	*/
+	text<K extends string>(key: K): JsonExpr<string>;
+	/**
+	* Navigate by PG JSON path operator `#>`.
+	*
+	* ```ts
+	* jsonCol("data").atPath("address.city") // → data#>'{address,city}'
+	* ```
+	*/
+	atPath(path: string): JsonOptic<unknown>;
+	/**
+	* Navigate by PG JSON text path operator `#>>`.
+	*
+	* ```ts
+	* jsonCol("data").textPath("address.city") // → data#>>'{address,city}'
+	* ```
+	*/
+	textPath(path: string): JsonExpr<string>;
+	/**
+	* Cast current JSON value to text (`->>`).
+	*/
+	asText(): JsonExpr<string>;
+	/**
+	* Get the underlying expression node.
+	*/
+	toExpression(): Expression<T>;
+}
+/**
+* A JSON expression that can be aliased and used in SELECT/WHERE.
+* This is the "leaf" of the optics chain.
+*/
+export declare class JsonExpr<T> {
+	readonly _type: T;
+	constructor(node: ExpressionNode);
+	/**
+	* Alias this expression for use in SELECT.
+	*
+	* ```ts
+	* jsonCol("data").text("name").as("userName")
+	* ```
+	*/
+	as(alias: string): Expression<T>;
+	/**
+	* Get the underlying expression node.
+	*/
+	toExpression(): Expression<T>;
+}
+/**
+* Create a JSON optic from a column name.
+*
+* ```ts
+* const profileCity = jsonCol<UserProfile>("profile").at("address").at("city").asText()
+* ```
+*/
+export declare function jsonCol<T = unknown>(column: string, table?: string): JsonOptic<T>;
+/**
+* Create a JSON optic from an existing expression.
+*
+* ```ts
+* const optic = jsonExpr<Config>(someExpression).at("settings")
+* ```
+*/
+export declare function jsonExpr<T = unknown>(expr: Expression<any>): JsonOptic<T>;

package/dist/builder/json-optics.mjs

@@ -0,0 +1,110 @@
+
+export class JsonOptic {
+	
+	_node;
+	constructor(node) {
+		this._node = node;
+	}
+	
+	at(key) {
+		const node = {
+			type: "json_access",
+			expr: this._node,
+			path: key,
+			operator: "->"
+		};
+		return new JsonOptic(node);
+	}
+	
+	text(key) {
+		const node = {
+			type: "json_access",
+			expr: this._node,
+			path: key,
+			operator: "->>"
+		};
+		return new JsonExpr(node);
+	}
+	
+	atPath(path) {
+		const node = {
+			type: "json_access",
+			expr: this._node,
+			path,
+			operator: "#>"
+		};
+		return new JsonOptic(node);
+	}
+	
+	textPath(path) {
+		const node = {
+			type: "json_access",
+			expr: this._node,
+			path,
+			operator: "#>>"
+		};
+		return new JsonExpr(node);
+	}
+	
+	asText() {
+		
+		if (this._node.type === "json_access") {
+			const ja = this._node;
+			if (ja.operator === "->") {
+				return new JsonExpr({
+					...ja,
+					operator: "->>"
+				});
+			}
+		}
+		
+		return new JsonExpr({
+			type: "cast",
+			expr: this._node,
+			dataType: "text"
+		});
+	}
+	
+	toExpression() {
+		return this._node;
+	}
+}
+
+export class JsonExpr {
+	
+	_node;
+	constructor(node) {
+		this._node = node;
+	}
+	
+	as(alias) {
+		if (this._node.type === "json_access") {
+			return {
+				...this._node,
+				alias
+			};
+		}
+		return {
+			type: "aliased_expr",
+			expr: this._node,
+			alias
+		};
+	}
+	
+	toExpression() {
+		return this._node;
+	}
+}
+
+export function jsonCol(column, table) {
+	const node = {
+		type: "column_ref",
+		column,
+		table
+	};
+	return new JsonOptic(node);
+}
+
+export function jsonExpr(expr) {
+	return new JsonOptic(expr._node ?? expr);
+}

package/dist/builder/typed-delete.mjs

@@ -8,6 +8,8 @@ export class TypedDeleteBuilder {
 	_builder;
 	
 	_printer;
+	
+	_compile;
 	constructor(table) {
 		this._builder = new DeleteBuilder().from(table);
 	}
@@ -16,6 +18,7 @@ export class TypedDeleteBuilder {
 		const t = new TypedDeleteBuilder("");
 		t._builder = builder;
 		t._printer = this._printer;
+		t._compile = this._compile;
 		return t;
 	}
 	
@@ -77,6 +80,7 @@ export class TypedDeleteBuilder {
 	}
 	
 	toSQL() {
+		if (this._compile) return this._compile(this.build());
 		if (!this._printer) {
 			throw new Error("toSQL() requires a printer. Use db.deleteFrom() or pass a printer to compile().");
 		}

package/dist/builder/typed-insert.d.mts

@@ -73,7 +73,7 @@ export declare class TypedInsertBuilder<
 	$if(condition: boolean, fn: (qb: TypedInsertBuilder<DB, TB>) => TypedInsertBuilder<DB, TB>): TypedInsertBuilder<DB, TB>;
 	build(): InsertNode;
 	compile(printer: Printer): CompiledQuery;
-	/** Compile to SQL using the dialect's printer. */
+	/** Compile to SQL using the full pipeline. */
 	toSQL(): CompiledQuery;
 	/** EXPLAIN this query. */
 	explain(options?: {

package/dist/builder/typed-insert.mjs

@@ -8,6 +8,8 @@ export class TypedInsertBuilder {
 	_builder;
 	
 	_printer;
+	
+	_compile;
 	constructor(table) {
 		this._builder = new InsertBuilder().into(table);
 	}
@@ -16,6 +18,7 @@ export class TypedInsertBuilder {
 		const t = new TypedInsertBuilder("");
 		t._builder = builder;
 		t._printer = this._printer;
+		t._compile = this._compile;
 		return t;
 	}
 	
@@ -153,6 +156,7 @@ export class TypedInsertBuilder {
 	}
 	
 	toSQL() {
+		if (this._compile) return this._compile(this.build());
 		if (!this._printer) {
 			throw new Error("toSQL() requires a printer. Use db.insertInto() or pass a printer to compile().");
 		}

package/dist/builder/typed-select.d.mts

@@ -19,7 +19,7 @@ export declare class TypedSelectBuilder<
 > {
 	private _table;
 	private _printer?;
-	constructor(builder: SelectBuilder, table?: string, printer?: Printer);
+	constructor(builder: SelectBuilder, table?: string, printer?: Printer, compile?: (node: import("../ast/nodes.ts").ASTNode) => CompiledQuery);
 	/** Select specific columns. Narrows O. */
 	select<K extends keyof O & string>(...cols: K[]): TypedSelectBuilder<DB, TB, Pick<O, K>>;
 	/** Select all columns. */
@@ -165,6 +165,25 @@ export declare class TypedSelectBuilder<
 	$call<R>(fn: (qb: TypedSelectBuilder<DB, TB, O>) => R): R;
 	/** Conditionally apply a transformation. */
 	$if<O2>(condition: boolean, fn: (qb: TypedSelectBuilder<DB, TB, O>) => TypedSelectBuilder<DB, TB, O2>): TypedSelectBuilder<DB, TB, O | O2>;
+	/**
+	* Cursor-based (keyset) pagination.
+	*
+	* Adds WHERE column > cursor (ASC) or column < cursor (DESC),
+	* ORDER BY column, and LIMIT pageSize + 1 (for hasNextPage detection).
+	*
+	* ```ts
+	* db.selectFrom("users")
+	*   .select("id", "name")
+	*   .cursorPaginate({ column: "id", after: 42, pageSize: 20 })
+	*   .toSQL()
+	* ```
+	*/
+	cursorPaginate(options: {
+		column: keyof O & string;
+		after?: unknown;
+		before?: unknown;
+		pageSize: number;
+	}): TypedSelectBuilder<DB, TB, O>;
 	/** Build the AST node. */
 	build(): SelectNode;
 	/** Compile to SQL with explicit printer. */