effect-qb 0.13.0 → 0.15.0

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[];