sumak 0.0.9 → 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
@@ -1012,6 +1017,136 @@ 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
@@ -1217,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.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -1237,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)        │
 └─────────────────────────────────────────────────────────────────┘
@@ -1249,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
 
@@ -1258,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/index.d.mts

@@ -60,4 +60,11 @@ export { DropTableBuilder, DropIndexBuilder, DropViewBuilder, TruncateTableBuild
 export { DDLPrinter } from "./printer/ddl.mjs";
 export { SchemaBuilder } from "./sumak.mjs";
 export type { AlterColumnSet, AlterTableAction, AlterTableNode, CheckConstraintNode, ColumnDefinitionNode, CreateIndexNode, CreateTableNode, CreateViewNode, DDLNode, DropIndexNode, DropTableNode, DropViewNode, ForeignKeyAction, ForeignKeyConstraintNode, PrimaryKeyConstraintNode, TableConstraintNode, TruncateTableNode, UniqueConstraintNode } from "./ast/ddl-nodes.mjs";
+export { normalizeExpression, normalizeQuery, toCNF, fromCNF } from "./normalize/index.mjs";
+export type { CNF, NormalizeOptions } from "./normalize/index.mjs";
+export { optimize, createRule, predicatePushdown, subqueryFlattening, removeWhereTrue, BUILTIN_RULES } from "./optimize/index.mjs";
+export type { RewriteRule, OptimizeOptions } from "./optimize/index.mjs";
+export { placeholder, compileQuery, collectPlaceholders, isPlaceholder } from "./builder/compiled.mjs";
+export type { CompiledQueryFn, PlaceholderMarker } from "./builder/compiled.mjs";
+export { JsonOptic, JsonExpr, jsonCol, jsonExpr } from "./builder/json-optics.mjs";
 export { EmptyQueryError, InvalidExpressionError, SumakError, UnsupportedDialectFeatureError } from "./errors.mjs";

package/dist/index.mjs

@@ -58,4 +58,12 @@ export { DropTableBuilder, DropIndexBuilder, DropViewBuilder, TruncateTableBuild
 export { DDLPrinter } from "./printer/ddl.mjs";
 export { SchemaBuilder } from "./sumak.mjs";
 
+export { normalizeExpression, normalizeQuery, toCNF, fromCNF } from "./normalize/index.mjs";
+
+export { optimize, createRule, predicatePushdown, subqueryFlattening, removeWhereTrue, BUILTIN_RULES } from "./optimize/index.mjs";
+
+export { placeholder, compileQuery, collectPlaceholders, isPlaceholder } from "./builder/compiled.mjs";
+
+export { JsonOptic, JsonExpr, jsonCol, jsonExpr } from "./builder/json-optics.mjs";
+
 export { EmptyQueryError, InvalidExpressionError, SumakError, UnsupportedDialectFeatureError } from "./errors.mjs";

package/dist/normalize/expression.d.mts

@@ -0,0 +1,26 @@
+import type { ExpressionNode } from "../ast/nodes.mjs";
+import type { CNF, NormalizeOptions } from "./types.mjs";
+/**
+* Normalize an expression node using NbE (Normalization by Evaluation).
+*
+* Pipeline: Expression → evaluate (semantic domain) → reify (canonical AST)
+*
+* Transformations:
+* - Flatten nested AND/OR
+* - Remove duplicate predicates
+* - Simplify tautologies: `x AND true → x`, `x OR false → x`
+* - Simplify contradictions: `x AND false → false`, `x OR true → true`
+* - Fold constants: `1 + 2 → 3`
+* - Simplify negation: `NOT NOT x → x`, `NOT true → false`
+* - Normalize comparison direction: `1 = x → x = 1` (literal always on right)
+*/
+export declare function normalizeExpression(expr: ExpressionNode, opts?: NormalizeOptions): ExpressionNode;
+/**
+* Convert a WHERE expression to Conjunctive Normal Form.
+* Top-level AND, inner OR.
+*/
+export declare function toCNF(expr: ExpressionNode): CNF;
+/**
+* Reify a CNF back to an ExpressionNode.
+*/
+export declare function fromCNF(cnf: CNF): ExpressionNode | undefined;