effect-qb 0.14.0 → 0.16.0

package/src/internal/renderer.ts

@@ -1,6 +1,6 @@
 import * as Query from "./query.js"
+import type * as Expression from "./scalar.js"
 import { type Projection, validateProjections } from "./projections.js"
-import { renderPostgresPlan } from "./postgres-renderer.js"
 
 /** Symbol used to attach rendered-query phantom row metadata. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Renderer")
@@ -22,6 +22,7 @@ export interface RenderedQuery<Row, Dialect extends string = string> {
   readonly params: readonly unknown[]
   readonly dialect: Dialect
   readonly projections: readonly Projection[]
+  readonly valueMappings?: Expression.DriverValueMappings
   readonly [TypeId]: {
     readonly row: Row
     readonly dialect: Dialect
@@ -41,53 +42,45 @@ export type RowOf<Value extends RenderedQuery<any, any>> = Value[typeof TypeId][
  */
 export interface Renderer<Dialect extends string = string> {
   readonly dialect: Dialect
-  render<PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+  render<PlanValue extends Query.Plan.Any>(
     plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
   ): RenderedQuery<any, Dialect>
 }
 
-type CustomRender<Dialect extends string> = <PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+type CustomRender<Dialect extends string> = <PlanValue extends Query.Plan.Any>(
   plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
 ) => {
   readonly sql: string
   readonly params?: readonly unknown[]
   readonly projections?: readonly Projection[]
+  readonly valueMappings?: Expression.DriverValueMappings
 }
 
 /**
- * Constructs a renderer from a dialect and optional implementation callback.
- *
- * When no callback is provided, the library supplies a built-in renderer for
- * `"postgres"` that consumes the query AST directly and produces SQL text plus
- * parameter values.
+ * Constructs a renderer from a dialect and implementation callback.
  */
-export function make(dialect: "postgres"): Renderer<"postgres">
 export function make<Dialect extends string>(
   dialect: Dialect,
   render: CustomRender<Dialect>
 ): Renderer<Dialect>
 export function make<Dialect extends string>(
   dialect: Dialect,
-  render?: CustomRender<Dialect>
+  render: CustomRender<Dialect>
 ): Renderer<Dialect> {
-  const implementation = render ?? ((dialect === "postgres"
-    ? renderPostgresPlan
-    : undefined) as CustomRender<Dialect> | undefined)
-
-  if (!implementation) {
-    throw new Error(`No built-in renderer for dialect: ${dialect}`)
+  if (typeof render !== "function") {
+    throw new Error(`Renderer.make requires an explicit render implementation for dialect: ${dialect}`)
   }
-
   return {
     dialect,
     render(plan) {
-      const rendered = implementation(plan)
+      const rendered = render(plan)
       const projections = rendered.projections ?? []
       validateProjections(projections)
       return {
         sql: rendered.sql,
         params: rendered.params ?? [],
         projections,
+        valueMappings: rendered.valueMappings,
         dialect,
         [TypeId]: {
           row: undefined as any,
@@ -97,6 +90,3 @@ export function make<Dialect extends string>(
     }
   } as Renderer<Dialect>
 }
-
-/** Built-in Postgres renderer backed by the current query AST. */
-export const postgres = make("postgres")

package/src/internal/row-set.d.ts

@@ -0,0 +1,53 @@
+import type { Pipeable } from "effect/Pipeable";
+import type { PredicateFormula } from "./predicate/formula.js";
+/** Symbol used to attach logical-plan metadata to runtime values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/**
+ * Source availability mode within a query scope.
+ *
+ * `required` means the source is guaranteed to produce a row at this point in
+ * the plan. `optional` means the source may be absent, such as the nullable
+ * side of a left join.
+ */
+export type SourceMode = "required" | "optional";
+/** Source made available to a plan. */
+export interface Source<Name extends string = string, Mode extends SourceMode = SourceMode, PresentFormula extends PredicateFormula = PredicateFormula, PresenceWitness extends string = never> {
+    readonly name: Name;
+    readonly mode: Mode;
+    readonly baseName?: string;
+    readonly _presentFormula?: PresentFormula;
+    readonly _presenceWitnesses?: readonly PresenceWitness[];
+}
+export type AnySource = Source<string, SourceMode, PredicateFormula, string>;
+/**
+ * Canonical static metadata stored on a plan.
+ *
+ * `required` tracks sources that the selection references but which are not yet
+ * in scope. `available` tracks sources already in scope for subsequent query
+ * operations.
+ */
+export interface State<Columns, Required, Available extends Record<string, AnySource>, Dialect extends string> {
+    readonly selection: Columns;
+    readonly required: Required;
+    readonly available: Available;
+    readonly dialect: Dialect;
+}
+/**
+ * A composable logical row set.
+ *
+ * Tables implement this interface as already-complete plans. Future query
+ * builders such as `select()` and `from()` should produce and transform values
+ * with this same structure.
+ */
+export interface RowSet<Columns, Required = never, Available extends Record<string, AnySource> = {}, Dialect extends string = never> extends Pipeable {
+    readonly [TypeId]: State<Columns, Required, Available, Dialect>;
+}
+/** Convenience alias for any plan-like value. */
+export type Any = RowSet<any, any, Record<string, AnySource>, string>;
+/** Extracts a row set's columns shape. */
+export type ColumnsOf<Value extends Any> = Value[typeof TypeId]["selection"];
+/** Extracts a plan's selection shape. */
+export type SelectionOf<Value extends Any> = ColumnsOf<Value>;
+/** Extracts a plan's effective dialect. */
+export type DialectOf<Value extends Any> = Value[typeof TypeId]["dialect"];

package/src/internal/{plan.ts → row-set.ts}

@@ -1,5 +1,5 @@
 import type { Pipeable } from "effect/Pipeable"
-import type { PredicateFormula } from "./predicate-formula.js"
+import type { PredicateFormula } from "./predicate/formula.js"
 
 /** Symbol used to attach logical-plan metadata to runtime values. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Plan")
@@ -39,36 +39,38 @@ export type AnySource = Source<string, SourceMode, PredicateFormula, string>
  * operations.
  */
 export interface State<
-  Selection,
+  Columns,
   Required,
   Available extends Record<string, AnySource>,
   Dialect extends string
 > {
-  readonly selection: Selection
+  readonly selection: Columns
   readonly required: Required
   readonly available: Available
   readonly dialect: Dialect
 }
 
 /**
- * A composable logical query plan.
+ * A composable logical row set.
  *
  * Tables implement this interface as already-complete plans. Future query
  * builders such as `select()` and `from()` should produce and transform values
  * with this same structure.
  */
-export interface Plan<
-  Selection,
+export interface RowSet<
+  Columns,
   Required = never,
   Available extends Record<string, AnySource> = {},
   Dialect extends string = never
 > extends Pipeable {
-  readonly [TypeId]: State<Selection, Required, Available, Dialect>
+  readonly [TypeId]: State<Columns, Required, Available, Dialect>
 }
 
 /** Convenience alias for any plan-like value. */
-export type Any = Plan<any, any, Record<string, AnySource>, string>
+export type Any = RowSet<any, any, Record<string, AnySource>, string>
+/** Extracts a row set's columns shape. */
+export type ColumnsOf<Value extends Any> = Value[typeof TypeId]["selection"]
 /** Extracts a plan's selection shape. */
-export type SelectionOf<Value extends Any> = Value[typeof TypeId]["selection"]
+export type SelectionOf<Value extends Any> = ColumnsOf<Value>
 /** Extracts a plan's effective dialect. */
 export type DialectOf<Value extends Any> = Value[typeof TypeId]["dialect"]

package/src/internal/runtime/driver-value-mapping.ts

@@ -0,0 +1,186 @@
+import * as Schema from "effect/Schema"
+
+import type * as Expression from "../scalar.js"
+import { normalizeDbValue } from "./normalize.js"
+
+export type DriverValueMapping = Expression.DriverValueMapping
+export type DriverValueMappings = Expression.DriverValueMappings
+
+export interface DriverValueContext {
+  readonly dialect?: string
+  readonly dbType?: Expression.DbType.Any
+  readonly runtimeSchema?: Schema.Schema.Any
+  readonly driverValueMapping?: DriverValueMapping
+  readonly valueMappings?: DriverValueMappings
+}
+
+type MappingKey =
+  | "fromDriver"
+  | "toDriver"
+  | "selectSql"
+  | "jsonSelectSql"
+
+const runtimeTagOfDbType = (
+  dbType: Expression.DbType.Any | undefined
+): string | undefined => {
+  if (dbType === undefined) {
+    return undefined
+  }
+  if ("base" in dbType) {
+    return runtimeTagOfDbType(dbType.base)
+  }
+  if ("element" in dbType) {
+    return "array"
+  }
+  if ("fields" in dbType) {
+    return "record"
+  }
+  if ("variant" in dbType && dbType.variant === "json") {
+    return "json"
+  }
+  if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
+    return "string"
+  }
+  return dbType.runtime
+}
+
+const familyOfDbType = (
+  dbType: Expression.DbType.Any | undefined
+): string | undefined => {
+  if (dbType === undefined) {
+    return undefined
+  }
+  if ("base" in dbType) {
+    return familyOfDbType(dbType.base)
+  }
+  return dbType.family
+}
+
+const mappingCandidates = (
+  context: DriverValueContext
+): readonly (DriverValueMapping | undefined)[] => {
+  const dbType = context.dbType
+  const runtimeTag = runtimeTagOfDbType(dbType)
+  const family = familyOfDbType(dbType)
+  return [
+    context.driverValueMapping,
+    dbType?.driverValueMapping,
+    dbType === undefined ? undefined : context.valueMappings?.[dbType.kind],
+    family === undefined ? undefined : context.valueMappings?.[family],
+    runtimeTag === undefined ? undefined : context.valueMappings?.[runtimeTag]
+  ]
+}
+
+const findMapping = <Key extends MappingKey>(
+  context: DriverValueContext,
+  key: Key
+): NonNullable<DriverValueMapping[Key]> | undefined => {
+  for (const candidate of mappingCandidates(context)) {
+    const value = candidate?.[key]
+    if (value !== undefined) {
+      return value as NonNullable<DriverValueMapping[Key]>
+    }
+  }
+  return undefined
+}
+
+const encodeWithSchema = (
+  schema: Schema.Schema.Any | undefined,
+  value: unknown
+): { readonly value: unknown; readonly encoded: boolean } => {
+  if (schema === undefined) {
+    return { value, encoded: false }
+  }
+  if (!(Schema.is(schema) as (value: unknown) => boolean)(value)) {
+    return { value, encoded: false }
+  }
+  return {
+    value: (Schema.encodeUnknownSync as any)(schema)(value),
+    encoded: true
+  }
+}
+
+export const toDriverValue = (
+  value: unknown,
+  context: DriverValueContext
+): unknown => {
+  if (value === null) {
+    return null
+  }
+  const dbType = context.dbType
+  const encoded = encodeWithSchema(context.runtimeSchema, value)
+  let current = encoded.value
+  const custom = findMapping(context, "toDriver")
+  if (custom !== undefined && dbType !== undefined) {
+    return custom(current, dbType)
+  }
+  return dbType === undefined || !encoded.encoded
+    ? current
+    : normalizeDbValue(dbType, current)
+}
+
+export const fromDriverValue = (
+  value: unknown,
+  context: DriverValueContext
+): unknown => {
+  if (value === null) {
+    return null
+  }
+  const dbType = context.dbType
+  const custom = findMapping(context, "fromDriver")
+  if (custom !== undefined && dbType !== undefined) {
+    return custom(value, dbType)
+  }
+  return dbType === undefined
+    ? value
+    : normalizeDbValue(dbType, value)
+}
+
+const textCast = (sql: string): string => `(${sql})::text`
+
+const postgresJsonSql = (
+  sql: string,
+  dbType: Expression.DbType.Any
+): string => {
+  const runtimeTag = runtimeTagOfDbType(dbType)
+  switch (runtimeTag) {
+    case "bigintString":
+    case "decimalString":
+    case "localDate":
+    case "localTime":
+    case "offsetTime":
+    case "localDateTime":
+    case "instant":
+    case "year":
+      return textCast(sql)
+    case "bytes":
+      return `encode(${sql}, 'base64')`
+    default:
+      return sql
+  }
+}
+
+export const renderSelectSql = (
+  sql: string,
+  context: DriverValueContext
+): string => {
+  const dbType = context.dbType
+  const custom = findMapping(context, "selectSql")
+  return custom !== undefined && dbType !== undefined
+    ? custom(sql, dbType)
+    : sql
+}
+
+export const renderJsonSelectSql = (
+  sql: string,
+  context: DriverValueContext
+): string => {
+  const dbType = context.dbType
+  const custom = findMapping(context, "jsonSelectSql")
+  if (custom !== undefined && dbType !== undefined) {
+    return custom(sql, dbType)
+  }
+  return context.dialect === "postgres" && dbType !== undefined
+    ? postgresJsonSql(sql, dbType)
+    : sql
+}

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

@@ -1,22 +1,5 @@
-import type * as Expression from "./expression.js"
-import { mysqlDatatypeKinds } from "../mysql/datatypes/spec.js"
-import { postgresDatatypeKinds } from "../postgres/datatypes/spec.js"
-import type { RuntimeTag } from "./datatypes/shape.js"
-
-const stripParameterizedKind = (kind: string): string => {
-  const openParen = kind.indexOf("(")
-  return openParen === -1 ? kind : kind.slice(0, openParen)
-}
-
-const stripArrayKind = (kind: string): string => {
-  let current = kind
-  while (current.endsWith("[]")) {
-    current = current.slice(0, -2)
-  }
-  return current
-}
-
-const baseKind = (kind: string): string => stripArrayKind(stripParameterizedKind(kind))
+import type * as Expression from "../scalar.js"
+import type { RuntimeTag } from "../datatypes/shape.js"
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
@@ -39,17 +22,9 @@ const formatLocalDateTime = (value: Date): string => {
 }
 
 const runtimeTagOfBaseDbType = (
-  dialect: string,
-  kind: string
+  dbType: Expression.DbType.Base<string, string>
 ): RuntimeTag | undefined => {
-  const normalizedKind = baseKind(kind)
-  if (dialect === "postgres") {
-    return postgresDatatypeKinds[normalizedKind as keyof typeof postgresDatatypeKinds]?.runtime
-  }
-  if (dialect === "mysql") {
-    return mysqlDatatypeKinds[normalizedKind as keyof typeof mysqlDatatypeKinds]?.runtime
-  }
-  return undefined
+  return dbType.runtime
 }
 
 const expectString = (value: unknown, label: string): string => {
@@ -225,7 +200,10 @@ const normalizeBytes = (value: unknown): Uint8Array => {
   if (value instanceof Uint8Array) {
     return new Uint8Array(value)
   }
-  if (typeof Buffer !== "undefined" && value instanceof Buffer) {
+  const BufferConstructor = (globalThis as {
+    readonly Buffer?: abstract new (...args: never[]) => Uint8Array
+  }).Buffer
+  if (BufferConstructor !== undefined && value instanceof BufferConstructor) {
     return new Uint8Array(value)
   }
   throw new Error("Expected a byte array value")
@@ -298,7 +276,7 @@ export const normalizeDbValue = (
   if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
     return expectString(value, "text")
   }
-  switch (runtimeTagOfBaseDbType(dbType.dialect, dbType.kind)) {
+  switch (runtimeTagOfBaseDbType(dbType)) {
     case "string":
       return expectString(value, "text")
     case "number":

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

@@ -1,19 +1,19 @@
 import * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
 
-import * as Expression from "./expression.js"
-import * as ExpressionAst from "./expression-ast.js"
-import * as Query from "./query.js"
-import * as JsonPath from "./json/path.js"
-import type { PredicateFormula } from "./predicate-formula.js"
+import * as Expression from "../scalar.js"
+import * as ExpressionAst from "../expression-ast.js"
+import * as Query from "../query.js"
+import * as JsonPath from "../json/path.js"
+import type { PredicateFormula } from "../predicate/formula.js"
 import {
   assumeFormulaFalse,
   assumeFormulaTrue,
   contradictsFormula,
   formulaOfExpression as formulaOfExpressionRuntime,
   impliesFormula
-} from "./predicate-runtime.js"
-import { flattenSelection } from "./projections.js"
+} from "../predicate/runtime.js"
+import { flattenSelection } from "../projections.js"
 import {
   BigIntStringSchema,
   DecimalStringSchema,
@@ -24,10 +24,8 @@ import {
   LocalTimeStringSchema,
   OffsetTimeStringSchema,
   YearStringSchema
-} from "./runtime-value.js"
-import { mysqlDatatypeKinds } from "../mysql/datatypes/spec.js"
-import { postgresDatatypeKinds } from "../postgres/datatypes/spec.js"
-import type { RuntimeTag } from "./datatypes/shape.js"
+} from "./value.js"
+import type { RuntimeTag } from "../datatypes/shape.js"
 
 export type RuntimeSchema = Schema.Schema<any, any, any>
 
@@ -37,21 +35,6 @@ type SchemaContext = {
 
 const schemaCache = new WeakMap<Expression.Any, RuntimeSchema | undefined>()
 
-const stripParameterizedKind = (kind: string): string => {
-  const openParen = kind.indexOf("(")
-  return openParen === -1 ? kind : kind.slice(0, openParen)
-}
-
-const stripArrayKind = (kind: string): string => {
-  let current = kind
-  while (current.endsWith("[]")) {
-    current = current.slice(0, -2)
-  }
-  return current
-}
-
-const baseKind = (kind: string): string => stripArrayKind(stripParameterizedKind(kind))
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
@@ -98,17 +81,9 @@ const runtimeSchemaForTag = (tag: RuntimeTag): RuntimeSchema | undefined => {
 }
 
 const runtimeTagOfBaseDbType = (
-  dialect: string,
-  kind: string
+  dbType: Expression.DbType.Base<string, string>
 ): RuntimeTag | undefined => {
-  const normalizedKind = baseKind(kind)
-  if (dialect === "postgres") {
-    return postgresDatatypeKinds[normalizedKind as keyof typeof postgresDatatypeKinds]?.runtime
-  }
-  if (dialect === "mysql") {
-    return mysqlDatatypeKinds[normalizedKind as keyof typeof mysqlDatatypeKinds]?.runtime
-  }
-  return undefined
+  return dbType.runtime
 }
 
 export const runtimeSchemaForDbType = (
@@ -132,7 +107,7 @@ export const runtimeSchemaForDbType = (
   if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
     return Schema.String
   }
-  const runtimeTag = runtimeTagOfBaseDbType(dbType.dialect, dbType.kind)
+  const runtimeTag = runtimeTagOfBaseDbType(dbType)
   return runtimeTag === undefined ? undefined : runtimeSchemaForTag(runtimeTag)
 }
 
@@ -257,7 +232,7 @@ const unionSchemas = (schemas: ReadonlyArray<RuntimeSchema | undefined>): Runtim
 }
 
 const firstSelectedExpression = (
-  plan: Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+  plan: Query.Plan.Any
 ): Expression.Any | undefined => {
   const selection = Query.getAst(plan).select
   return flattenSelection(selection as Record<string, unknown>)[0]?.expression

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

@@ -0,0 +1,22 @@
+import type * as Brand from "effect/Brand";
+import * as Schema from "effect/Schema";
+import type { JsonPrimitive, JsonValue } from "../json/types.js";
+export type { JsonPrimitive, JsonValue } from "../json/types.js";
+export type LocalDateString = string & Brand.Brand<"LocalDateString">;
+export type LocalTimeString = string & Brand.Brand<"LocalTimeString">;
+export type OffsetTimeString = string & Brand.Brand<"OffsetTimeString">;
+export type LocalDateTimeString = string & Brand.Brand<"LocalDateTimeString">;
+export type InstantString = string & Brand.Brand<"InstantString">;
+export type YearString = string & Brand.Brand<"YearString">;
+export type BigIntString = string & Brand.Brand<"BigIntString">;
+export type DecimalString = string & Brand.Brand<"DecimalString">;
+export declare const LocalDateStringSchema: Schema.Schema<string & Brand.Brand<"LocalDateString">, string & Brand.Brand<"LocalDateString">, never>;
+export declare const LocalTimeStringSchema: Schema.Schema<string & Brand.Brand<"LocalTimeString">, string & Brand.Brand<"LocalTimeString">, never>;
+export declare const OffsetTimeStringSchema: Schema.Schema<string & Brand.Brand<"OffsetTimeString">, string & Brand.Brand<"OffsetTimeString">, never>;
+export declare const LocalDateTimeStringSchema: Schema.Schema<string & Brand.Brand<"LocalDateTimeString">, string & Brand.Brand<"LocalDateTimeString">, never>;
+export declare const InstantStringSchema: Schema.Schema<string & Brand.Brand<"InstantString">, string & Brand.Brand<"InstantString">, never>;
+export declare const YearStringSchema: Schema.Schema<string & Brand.Brand<"YearString">, string & Brand.Brand<"YearString">, never>;
+export declare const BigIntStringSchema: Schema.Schema<string & Brand.Brand<"BigIntString">, string & Brand.Brand<"BigIntString">, never>;
+export declare const DecimalStringSchema: Schema.Schema<string & Brand.Brand<"DecimalString">, string & Brand.Brand<"DecimalString">, never>;
+export declare const JsonValueSchema: Schema.Schema<JsonValue>;
+export declare const JsonPrimitiveSchema: Schema.Schema<JsonPrimitive>;

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

@@ -1,9 +1,9 @@
 import type * as Brand from "effect/Brand"
 import * as Schema from "effect/Schema"
 
-import type { JsonPrimitive, JsonValue } from "./json/types.js"
+import type { JsonPrimitive, JsonValue } from "../json/types.js"
 
-export type { JsonPrimitive, JsonValue } from "./json/types.js"
+export type { JsonPrimitive, JsonValue } from "../json/types.js"
 
 export type LocalDateString = string & Brand.Brand<"LocalDateString">
 export type LocalTimeString = string & Brand.Brand<"LocalTimeString">