effect-qb 0.14.0 → 0.15.0

package/src/internal/{predicate-normalize.ts → predicate/normalize.ts}

@@ -1,8 +1,8 @@
-import type * as Expression from "./expression.js"
-import type * as ExpressionAst from "./expression-ast.js"
-import type { ColumnKeyOfExpression, ValueKey } from "./predicate-key.js"
-import type { AllFormula, AnyFormula, AtomFormula, FalseFormula, NotFormula, PredicateFormula, TrueFormula } from "./predicate-formula.js"
-import type { EqColumnAtom, EqLiteralAtom, NeqLiteralAtom, NonNullAtom, NullAtom, UnknownAtom } from "./predicate-atom.js"
+import type * as Expression from "../scalar.js"
+import type * as ExpressionAst from "../expression-ast.js"
+import type { ColumnKeyOfExpression, ValueKey } from "./key.js"
+import type { AllFormula, AnyFormula, AtomFormula, FalseFormula, NotFormula, PredicateFormula, TrueFormula } from "./formula.js"
+import type { EqColumnAtom, EqLiteralAtom, NeqLiteralAtom, NonNullAtom, NullAtom, UnknownAtom } from "./atom.js"
 
 type AstOf<Value extends Expression.Any> = Value extends {
   readonly [ExpressionAst.TypeId]: infer Ast extends ExpressionAst.Any
@@ -16,8 +16,8 @@ type True = TrueFormula
 type False = FalseFormula
 
 type UnknownTag<Tag extends string> = AtomFormula<UnknownAtom<Tag>>
-type AtomOf<Atom extends import("./predicate-atom.js").PredicateAtom> = AtomFormula<Atom>
-type FactOf<Atom extends import("./predicate-atom.js").PredicateAtom> = AtomFormula<Atom>
+type AtomOf<Atom extends import("./atom.js").PredicateAtom> = AtomFormula<Atom>
+type FactOf<Atom extends import("./atom.js").PredicateAtom> = AtomFormula<Atom>
 
 type NonNullFactsOfExpression<Value extends Expression.Any> =
   [ColumnKeyOfExpression<Value>] extends [never]
@@ -31,7 +31,7 @@ type CombineFacts<
   ? Right
   : [Right] extends [never]
     ? Left
-    : import("./predicate-formula.js").NormalizeBooleanConstants<AllFormula<[Left, Right]>>
+    : import("./formula.js").NormalizeBooleanConstants<AllFormula<[Left, Right]>>
 
 type FactsOfExpressions<Values extends readonly Expression.Any[]> =
   Values extends readonly [
@@ -77,7 +77,7 @@ type FormulaOfEq<
             ? False
             : AtomOf<EqLiteralAtom<ColumnKeyOfExpression<Left>, ValueKey<RightLiteral>>>
         : UnknownTag<"eq:unsupported">
-      : AtomOf<import("./predicate-atom.js").EqColumnAtom<ColumnKeyOfExpression<Left>, ColumnKeyOfExpression<Right>>>
+      : AtomOf<import("./atom.js").EqColumnAtom<ColumnKeyOfExpression<Left>, ColumnKeyOfExpression<Right>>>
 
 type FormulaOfNeq<
   Left extends Expression.Any,
@@ -149,11 +149,11 @@ type FormulaOfIsNotDistinctFrom<
 
 type OrFormulas<
   Items extends readonly PredicateFormula[]
-> = import("./predicate-formula.js").NormalizeBooleanConstants<AnyFormula<Items>>
+> = import("./formula.js").NormalizeBooleanConstants<AnyFormula<Items>>
 
 type AndFormulas<
   Items extends readonly PredicateFormula[]
-> = import("./predicate-formula.js").NormalizeBooleanConstants<AllFormula<Items>>
+> = import("./formula.js").NormalizeBooleanConstants<AllFormula<Items>>
 
 type FormulaTupleOf<
   Values extends readonly Expression.Any[]
@@ -163,11 +163,11 @@ type FormulaTupleOf<
 
 type AllFormulaOfValues<
   Values extends readonly Expression.Any[]
-> = import("./predicate-formula.js").NormalizeBooleanConstants<AllFormula<FormulaTupleOf<Values>>>
+> = import("./formula.js").NormalizeBooleanConstants<AllFormula<FormulaTupleOf<Values>>>
 
 type AnyFormulaOfValues<
   Values extends readonly Expression.Any[]
-> = import("./predicate-formula.js").NormalizeBooleanConstants<AnyFormula<FormulaTupleOf<Values>>>
+> = import("./formula.js").NormalizeBooleanConstants<AnyFormula<FormulaTupleOf<Values>>>
 
 type FormulaOfInValues<
   Left extends Expression.Any,
@@ -202,10 +202,10 @@ type FormulaOfVariadic<
       ? Values extends readonly [infer Left extends Expression.Any, ...infer Tail extends readonly Expression.Any[]]
         ? OrFormulas<FormulaOfInValues<Left, Tail>>
         : False
-      : Kind extends "notIn"
-        ? Values extends readonly [infer Left extends Expression.Any, ...infer Tail extends readonly Expression.Any[]]
-          ? AndFormulas<FormulaOfNotInValues<Left, Tail>>
-          : True
+  : Kind extends "notIn"
+    ? Values extends readonly [infer Left extends Expression.Any, ...infer Tail extends readonly Expression.Any[]]
+      ? CombineFacts<NonNullFactsOfExpression<Left>, AndFormulas<FormulaOfNotInValues<Left, Tail>>>
+      : True
         : Kind extends "between"
           ? FactsOfExpressions<Values> extends infer Facts extends PredicateFormula
             ? [Facts] extends [never]
@@ -226,7 +226,7 @@ type FormulaOfUnary<
       ? UnknownTag<"isNotNull:unsupported">
       : AtomOf<NonNullAtom<ColumnKeyOfExpression<Inner>>>
     : Kind extends "not"
-      ? import("./predicate-formula.js").Not<FormulaOfExpression<Inner>>
+      ? import("./formula.js").Not<FormulaOfExpression<Inner>>
       : UnknownTag<`unary:${Kind}`>
 
 type FormulaOfBinary<
@@ -242,7 +242,7 @@ type FormulaOfBinary<
       : Kind extends "isNotDistinctFrom"
         ? FormulaOfIsNotDistinctFrom<Left, Right>
         : Kind extends "isDistinctFrom"
-          ? import("./predicate-formula.js").Not<FormulaOfIsNotDistinctFrom<Left, Right>>
+          ? import("./formula.js").Not<FormulaOfIsNotDistinctFrom<Left, Right>>
           : CombineFacts<NonNullFactsOfExpression<Left>, NonNullFactsOfExpression<Right>>
 
 type FormulaOfAst<

package/src/internal/predicate/runtime.d.ts

@@ -0,0 +1,31 @@
+import * as Expression from "../scalar.js";
+import type { PredicateAtom } from "./atom.js";
+import type { AtomFormula, FalseFormula, PredicateFormula, TrueFormula } from "./formula.js";
+export interface RuntimeContext {
+    readonly nonNullKeys: ReadonlySet<string>;
+    readonly nullKeys: ReadonlySet<string>;
+    readonly eqLiterals: ReadonlyMap<string, string>;
+    readonly neqLiterals: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly sourceNames: ReadonlySet<string>;
+    readonly contradiction: boolean;
+    readonly unknown: boolean;
+}
+export declare const trueFormula: () => TrueFormula;
+export declare const falseFormula: () => FalseFormula;
+export declare const atomFormula: <Atom extends PredicateAtom>(atom: Atom) => AtomFormula<Atom>;
+export declare const allFormula: (items: readonly PredicateFormula[]) => PredicateFormula;
+export declare const anyFormula: (items: readonly PredicateFormula[]) => PredicateFormula;
+export declare const notFormula: (item: PredicateFormula) => PredicateFormula;
+export declare const andFormula: (left: PredicateFormula, right: PredicateFormula) => PredicateFormula;
+export declare const orFormula: (left: PredicateFormula, right: PredicateFormula) => PredicateFormula;
+export declare const analyzeFormula: (formula: PredicateFormula) => RuntimeContext;
+export declare const normalizeFormula: (formula: PredicateFormula) => PredicateFormula;
+export declare const formulaOfExpression: (value: Expression.Any) => PredicateFormula;
+export declare const formulaOfPredicate: (value: boolean | Expression.Any) => PredicateFormula;
+export declare const assumeFormulaTrue: (assumptions: PredicateFormula, formula: PredicateFormula) => PredicateFormula;
+export declare const assumeFormulaFalse: (assumptions: PredicateFormula, formula: PredicateFormula) => PredicateFormula;
+export declare const contradictsFormula: (assumptions: PredicateFormula, formula: PredicateFormula) => boolean;
+export declare const impliesFormula: (assumptions: PredicateFormula, formula: PredicateFormula) => boolean;
+export declare const guaranteedNonNullKeys: (assumptions: PredicateFormula) => ReadonlySet<string>;
+export declare const guaranteedNullKeys: (assumptions: PredicateFormula) => ReadonlySet<string>;
+export declare const guaranteedSourceNames: (assumptions: PredicateFormula) => ReadonlySet<string>;

package/src/internal/{predicate-runtime.ts → predicate/runtime.ts}

@@ -1,6 +1,6 @@
-import * as Expression from "./expression.js"
-import * as ExpressionAst from "./expression-ast.js"
-import type { PredicateAtom } from "./predicate-atom.js"
+import * as Expression from "../scalar.js"
+import * as ExpressionAst from "../expression-ast.js"
+import type { PredicateAtom } from "./atom.js"
 import type {
   EqColumnAtom,
   EqLiteralAtom,
@@ -8,7 +8,7 @@ import type {
   NonNullAtom,
   NullAtom,
   UnknownAtom
-} from "./predicate-atom.js"
+} from "./atom.js"
 import type {
   AllFormula,
   AnyFormula,
@@ -17,7 +17,7 @@ import type {
   NotFormula,
   PredicateFormula,
   TrueFormula
-} from "./predicate-formula.js"
+} from "./formula.js"
 
 export interface RuntimeContext {
   readonly nonNullKeys: ReadonlySet<string>
@@ -622,7 +622,10 @@ export const formulaOfExpression = (value: Expression.Any): PredicateFormula =>
       const [left, ...rest] = ast.values
       return left === undefined
         ? trueFormula()
-        : allFormula(rest.map((value: Expression.Any) => formulaOfNeq(left, value)))
+        : combineFacts(
+            nonNullFactsOfExpression(left),
+            allFormula(rest.map((value: Expression.Any) => formulaOfNeq(left, value)))
+          )
     }
     case "between":
       return combineFacts(

package/src/internal/projection-alias.d.ts

@@ -0,0 +1,13 @@
+/** Symbol used to attach explicit projection-alias metadata to an expression. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/**
+ * Projection-alias metadata carried by a runtime expression wrapper.
+ *
+ * This is intentionally orthogonal to the scalar expression AST. Aliasing does
+ * not change SQL semantics; it only changes how a selected expression is named
+ * in the rendered `SELECT ... AS ...` list.
+ */
+export interface State<Alias extends string = string> {
+    readonly alias: Alias;
+}

package/src/internal/projections.d.ts

@@ -0,0 +1,31 @@
+import * as Expression from "./scalar.js";
+/**
+ * Flat projection metadata shared by renderers and executors.
+ *
+ * `path` identifies where a value should be decoded in the nested result row,
+ * while `alias` is the flat SQL column alias used by the rendered query.
+ */
+export interface Projection {
+    readonly path: readonly string[];
+    readonly alias: string;
+}
+/** Selection leaf paired with its resolved projection alias. */
+export interface FlattenedProjection {
+    readonly path: readonly string[];
+    readonly expression: Expression.Any;
+    readonly alias: string;
+}
+/**
+ * Flattens a nested selection object into leaf expressions with decode paths
+ * and resolved SQL aliases.
+ */
+export declare const flattenSelection: (selection: Record<string, unknown>, path?: readonly string[]) => readonly FlattenedProjection[];
+/**
+ * Validates the flattened projection set shared by renderer and executor code.
+ *
+ * This rejects:
+ * - duplicate SQL aliases
+ * - duplicate decode paths
+ * - conflicting prefix paths like `profile` and `profile.id`
+ */
+export declare const validateProjections: (projections: readonly Projection[]) => void;

package/src/internal/projections.ts

@@ -1,4 +1,4 @@
-import * as Expression from "./expression.js"
+import * as Expression from "./scalar.js"
 import * as ProjectionAlias from "./projection-alias.js"
 
 /**

package/src/internal/query-ast.d.ts

@@ -0,0 +1,217 @@
+import type * as Expression from "./scalar.js";
+/** Symbol used to attach query-clause AST metadata to query-plan values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/** Statement kinds supported by the current query AST. */
+export type QueryStatement = "select" | "set" | "insert" | "update" | "delete" | "truncate" | "merge" | "transaction" | "commit" | "rollback" | "savepoint" | "rollbackTo" | "releaseSavepoint" | "createTable" | "createIndex" | "dropIndex" | "alterTable" | "dropTable";
+/** Base `FROM` clause recorded by the query AST. */
+export interface FromClause<TableName extends string = string> {
+    readonly kind: "from";
+    readonly tableName: TableName;
+    readonly baseTableName: string;
+    readonly source: unknown;
+}
+/** Boolean predicate recorded in a `WHERE` clause. */
+export interface WhereClause<Predicate extends Expression.Any = Expression.Any> {
+    readonly kind: "where";
+    readonly predicate: Predicate;
+}
+/** Boolean predicate recorded in a `HAVING` clause. */
+export interface HavingClause<Predicate extends Expression.Any = Expression.Any> {
+    readonly kind: "having";
+    readonly predicate: Predicate;
+}
+/** Assignment recorded in a mutation statement. */
+export interface AssignmentClause<Value extends Expression.Any = Expression.Any> {
+    readonly tableName?: string;
+    readonly columnName: string;
+    readonly value: Value;
+}
+/** One row in a multi-row `values (...)` insert source. */
+export interface InsertValuesRowClause<Values extends readonly AssignmentClause[] = readonly AssignmentClause[]> {
+    readonly values: Values;
+}
+/** Additional insert source kinds beyond a single literal row. */
+export type InsertSourceClause = {
+    readonly kind: "values";
+    readonly columns: readonly [string, ...string[]];
+    readonly rows: readonly [InsertValuesRowClause, ...InsertValuesRowClause[]];
+} | {
+    readonly kind: "query";
+    readonly columns: readonly [string, ...string[]];
+    readonly query: unknown;
+} | {
+    readonly kind: "unnest";
+    readonly columns: readonly [string, ...string[]];
+    readonly values: readonly {
+        readonly columnName: string;
+        readonly values: readonly unknown[];
+    }[];
+};
+/** One branch inside a `merge` statement. */
+export type MergeMatchedClause<Predicate extends Expression.Any | undefined = Expression.Any | undefined> = {
+    readonly kind: "update";
+    readonly values: readonly AssignmentClause[];
+    readonly predicate?: Predicate;
+} | {
+    readonly kind: "delete";
+    readonly predicate?: Predicate;
+};
+/** Insert branch inside a `merge` statement. */
+export interface MergeNotMatchedClause<Predicate extends Expression.Any | undefined = Expression.Any | undefined> {
+    readonly kind: "insert";
+    readonly values: readonly AssignmentClause[];
+    readonly predicate?: Predicate;
+}
+/** Payload recorded by a `merge` statement. */
+export interface MergeClause<On extends Expression.Any = Expression.Any, Predicate extends Expression.Any | undefined = Expression.Any | undefined> {
+    readonly kind: "merge";
+    readonly on: On;
+    readonly whenMatched?: MergeMatchedClause<Predicate>;
+    readonly whenNotMatched?: MergeNotMatchedClause<Predicate>;
+}
+/** DDL payload recorded by schema-manipulation statements. */
+export type DdlClause = {
+    readonly kind: "createTable";
+    readonly ifNotExists: boolean;
+} | {
+    readonly kind: "dropTable";
+    readonly ifExists: boolean;
+} | {
+    readonly kind: "createIndex";
+    readonly name: string;
+    readonly columns: readonly [string, ...string[]];
+    readonly unique: boolean;
+    readonly ifNotExists: boolean;
+} | {
+    readonly kind: "dropIndex";
+    readonly name: string;
+    readonly ifExists: boolean;
+};
+/** Truncate payload recorded by a truncate statement. */
+export interface TruncateClause {
+    readonly kind: "truncate";
+    readonly restartIdentity: boolean;
+    readonly cascade: boolean;
+}
+/** Transaction-control payload recorded by transactional statements. */
+export type TransactionClause = {
+    readonly kind: "transaction";
+    readonly isolationLevel?: "read committed" | "repeatable read" | "serializable";
+    readonly readOnly?: boolean;
+} | {
+    readonly kind: "commit";
+} | {
+    readonly kind: "rollback";
+} | {
+    readonly kind: "savepoint";
+    readonly name: string;
+} | {
+    readonly kind: "rollbackTo";
+    readonly name: string;
+} | {
+    readonly kind: "releaseSavepoint";
+    readonly name: string;
+} | {
+    readonly kind: "dropTable";
+    readonly ifExists: boolean;
+} | {
+    readonly kind: "createIndex";
+    readonly name: string;
+    readonly columns: readonly [string, ...string[]];
+    readonly unique: boolean;
+    readonly ifNotExists: boolean;
+} | {
+    readonly kind: "dropIndex";
+    readonly name: string;
+    readonly ifExists: boolean;
+};
+/** Locking mode attached to a select statement. */
+export interface LockClause {
+    readonly kind: "lock";
+    readonly mode: "update" | "share" | "lowPriority" | "ignore" | "quick";
+    readonly nowait?: boolean;
+    readonly skipLocked?: boolean;
+}
+/** Conflict target attached to a Postgres insert statement. */
+export type ConflictTargetClause = {
+    readonly kind: "columns";
+    readonly columns: readonly [string, ...string[]];
+    readonly where?: Expression.Any;
+} | {
+    readonly kind: "constraint";
+    readonly name: string;
+};
+/** Conflict clause attached to an insert statement. */
+export interface ConflictClause {
+    readonly kind: "conflict";
+    readonly target?: ConflictTargetClause;
+    readonly action: "doNothing" | "doUpdate";
+    readonly values?: readonly AssignmentClause[];
+    readonly where?: Expression.Any;
+}
+/** Join kinds supported by the current query layer. */
+export type JoinKind = "inner" | "left" | "right" | "full" | "cross";
+/** Join clause recorded by the query AST. */
+export interface JoinClause<TableName extends string = string, Kind extends JoinKind = JoinKind, On extends Expression.Any | undefined = Expression.Any | undefined> {
+    readonly kind: Kind;
+    readonly tableName: TableName;
+    readonly baseTableName: string;
+    readonly source: unknown;
+    readonly on?: On;
+}
+/** Sort direction recorded by an `ORDER BY` clause. */
+export type OrderDirection = "asc" | "desc";
+/** Ordering clause recorded by the query AST. */
+export interface OrderByClause<Value extends Expression.Any = Expression.Any> {
+    readonly kind: "orderBy";
+    readonly value: Value;
+    readonly direction: OrderDirection;
+}
+/** Set-operator kinds supported by compound queries. */
+export type SetOperatorKind = "union" | "intersect" | "except";
+/** Compound-query clause recorded by the query AST. */
+export interface SetOperationClause {
+    readonly kind: SetOperatorKind;
+    readonly all?: boolean;
+    readonly query: unknown;
+}
+/**
+ * Internal query AST stored alongside public `Plan` metadata.
+ *
+ * The public plan state tracks selection, required sources, available sources,
+ * and dialect. This AST captures the clause ordering needed to eventually
+ * render or optimize a SQL query.
+ */
+export interface Ast<Selection = unknown, Grouped extends string = never, Statement extends QueryStatement = "select"> {
+    readonly kind: Statement;
+    readonly select: Selection;
+    readonly distinct?: boolean;
+    readonly distinctOn?: readonly Expression.Any[];
+    readonly setBase?: unknown;
+    readonly recursive?: boolean;
+    readonly from?: FromClause;
+    readonly fromSources?: readonly FromClause[];
+    readonly into?: FromClause;
+    readonly target?: FromClause;
+    readonly targets?: readonly FromClause[];
+    readonly using?: FromClause;
+    readonly values?: readonly AssignmentClause[];
+    readonly insertSource?: InsertSourceClause;
+    readonly set?: readonly AssignmentClause[];
+    readonly ddl?: DdlClause;
+    readonly truncate?: TruncateClause;
+    readonly merge?: MergeClause;
+    readonly transaction?: TransactionClause;
+    readonly lock?: LockClause;
+    readonly conflict?: ConflictClause;
+    readonly where: readonly WhereClause[];
+    readonly having: readonly HavingClause[];
+    readonly joins: readonly JoinClause[];
+    readonly groupBy: readonly Expression.Any[];
+    readonly orderBy: readonly OrderByClause[];
+    readonly limit?: Expression.Any;
+    readonly offset?: Expression.Any;
+    readonly setOperations?: readonly SetOperationClause[];
+    readonly groupedSources?: Grouped;
+}

package/src/internal/query-ast.ts

@@ -1,4 +1,4 @@
-import type * as Expression from "./expression.js"
+import type * as Expression from "./scalar.js"
 
 /** Symbol used to attach query-clause AST metadata to query-plan values. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/QueryAst")

package/src/internal/query-requirements.d.ts

@@ -0,0 +1,20 @@
+/** Query capabilities directly modeled by the current plan AST. */
+export type QueryCapability = "read" | "write" | "ddl" | "transaction" | "locking";
+/**
+ * Capability or query-mode requirement associated with a dialect error.
+ *
+ * Not every requirement is currently expressible by query plans. The extra
+ * vocabulary exists so dialect maps can stay stable as the plan surface grows.
+ */
+export type QueryRequirement = QueryCapability | "ddl" | "transaction" | "locking";
+/** Runtime capability list for the current read-only query plans. */
+export declare const read_query_capabilities: readonly ["read"];
+/** Type-level union of two capability sets. */
+export type MergeCapabilities<Left extends QueryCapability, Right extends QueryCapability> = Left | Right;
+/** Type-level union of capability sets across a readonly tuple. */
+export type MergeCapabilityTuple<Values extends readonly QueryCapability[], Current extends QueryCapability = never> = Values extends readonly [
+    infer Head extends QueryCapability,
+    ...infer Tail extends readonly QueryCapability[]
+] ? MergeCapabilityTuple<Tail, Current | Head> : Current;
+/** Dedupes and normalizes capability lists at runtime. */
+export declare const union_query_capabilities: (...values: readonly (readonly QueryCapability[])[]) => readonly QueryCapability[];