effect-qb 0.15.0 → 0.17.0

package/src/internal/renderer.ts

@@ -1,5 +1,7 @@
 import * as Query from "./query.js"
-import { type Projection, validateProjections } from "./projections.js"
+import type * as Expression from "./scalar.js"
+import { flattenSelection, type Projection, validateProjections } from "./projections.js"
+import * as Plan from "./row-set.js"
 
 /** Symbol used to attach rendered-query phantom row metadata. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Renderer")
@@ -21,6 +23,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
@@ -42,7 +45,7 @@ export interface Renderer<Dialect extends string = string> {
   readonly dialect: Dialect
   render<PlanValue extends Query.Plan.Any>(
     plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
-  ): RenderedQuery<any, Dialect>
+  ): RenderedQuery<Query.ResultRow<PlanValue>, Dialect>
 }
 
 type CustomRender<Dialect extends string> = <PlanValue extends Query.Plan.Any>(
@@ -51,6 +54,30 @@ type CustomRender<Dialect extends string> = <PlanValue extends Query.Plan.Any>(
   readonly sql: string
   readonly params?: readonly unknown[]
   readonly projections?: readonly Projection[]
+  readonly valueMappings?: Expression.DriverValueMappings
+}
+
+const projectionPathKey = (path: readonly string[]): string => JSON.stringify(path)
+
+const formatProjectionPath = (path: readonly string[]): string => path.join(".")
+
+const validateProjectionPathsMatchSelection = (
+  plan: Query.Plan.Any,
+  projections: readonly Projection[]
+): void => {
+  const expected = flattenSelection(Query.getAst(plan).select as Record<string, unknown>)
+  const expectedPaths = new Set(expected.map((projection) => projectionPathKey(projection.path)))
+  const actualPaths = new Set(projections.map((projection) => projectionPathKey(projection.path)))
+  for (const projection of projections) {
+    if (!expectedPaths.has(projectionPathKey(projection.path))) {
+      throw new Error(`Projection path ${formatProjectionPath(projection.path)} does not exist in the query selection`)
+    }
+  }
+  for (const projection of expected) {
+    if (!actualPaths.has(projectionPathKey(projection.path))) {
+      throw new Error(`Projection path ${formatProjectionPath(projection.path)} is missing from rendered projections`)
+    }
+  }
 }
 
 /**
@@ -70,13 +97,23 @@ export function make<Dialect extends string>(
   return {
     dialect,
     render(plan) {
+      const required = Query.currentRequiredList(plan[Plan.TypeId].required)
+      if (required.length > 0) {
+        throw new Error(`query references sources that are not yet in scope: ${required.join(", ")}`)
+      }
+      const planDialect = plan[Plan.TypeId].dialect
+      if (planDialect !== dialect) {
+        throw new Error("effect-qb: plan dialect is not compatible with the target renderer or executor")
+      }
       const rendered = render(plan)
       const projections = rendered.projections ?? []
       validateProjections(projections)
+      validateProjectionPathsMatchSelection(plan as Query.Plan.Any, projections)
       return {
         sql: rendered.sql,
         params: rendered.params ?? [],
         projections,
+        valueMappings: rendered.valueMappings,
         dialect,
         [TypeId]: {
           row: undefined as any,

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

@@ -0,0 +1,244 @@
+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 isJsonDbType = (dbType: Expression.DbType.Any | undefined): boolean => {
+  if (dbType === undefined) {
+    return false
+  }
+  if ("base" in dbType) {
+    return isJsonDbType(dbType.base)
+  }
+  if (!("variant" in dbType)) {
+    return false
+  }
+  const variant = dbType.variant as string
+  return variant === "json" || variant === "jsonb"
+}
+
+const schemaAccepts = (
+  schema: Schema.Schema.Any | undefined,
+  value: unknown
+): boolean =>
+  schema !== undefined && (Schema.is(schema) as (candidate: unknown) => boolean)(value)
+
+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
+  }
+}
+
+const normalizeJsonDriverString = (
+  value: string,
+  context: DriverValueContext
+): unknown | undefined => {
+  if (!isJsonDbType(context.dbType) || context.runtimeSchema === undefined) {
+    return undefined
+  }
+  try {
+    const parsed = JSON.parse(value)
+    if (value.trimStart().startsWith("\"") && schemaAccepts(context.runtimeSchema, parsed)) {
+      return parsed
+    }
+    if (schemaAccepts(context.runtimeSchema, value) && !schemaAccepts(context.runtimeSchema, parsed)) {
+      return value
+    }
+  } catch (error) {
+    if (error instanceof SyntaxError && schemaAccepts(context.runtimeSchema, value)) {
+      return value
+    }
+    if (!(error instanceof SyntaxError)) {
+      throw error
+    }
+  }
+  return undefined
+}
+
+export const toDriverValue = (
+  value: unknown,
+  context: DriverValueContext
+): unknown => {
+  if (value === null) {
+    return null
+  }
+  if (value instanceof Date && Number.isNaN(value.getTime())) {
+    throw new Error("Expected a valid Date value")
+  }
+  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)
+  }
+  if (encoded.encoded && typeof current === "string" && isJsonDbType(dbType)) {
+    return current
+  }
+  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)
+  }
+  if (typeof value === "string") {
+    const normalizedJsonString = normalizeJsonDriverString(value, context)
+    if (normalizedJsonString !== undefined) {
+      return normalizedJsonString
+    }
+  }
+  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

@@ -1,13 +1,30 @@
 import type * as Expression from "../scalar.js"
 import type { RuntimeTag } from "../datatypes/shape.js"
+import {
+  canonicalizeBigIntString,
+  canonicalizeDecimalString,
+  isValidInstantString,
+  isValidLocalDateString,
+  isValidLocalDateTimeString,
+  isValidLocalTimeString,
+  isValidOffsetTimeString
+} from "./value.js"
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
+const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (!isRecord(value)) {
+    return false
+  }
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
 const pad = (value: number, width = 2): string => value.toString().padStart(width, "0")
 
 const formatLocalDate = (value: Date): string =>
-  `${value.getUTCFullYear()}-${pad(value.getUTCMonth() + 1)}-${pad(value.getUTCDate())}`
+  `${pad(value.getUTCFullYear(), 4)}-${pad(value.getUTCMonth() + 1)}-${pad(value.getUTCDate())}`
 
 const formatLocalTime = (value: Date): string => {
   const milliseconds = value.getUTCMilliseconds()
@@ -34,12 +51,17 @@ const expectString = (value: unknown, label: string): string => {
   throw new Error(`Expected ${label} as string`)
 }
 
+const finiteNumberStringPattern = /^[+-]?(?:(?:\d+\.?\d*)|(?:\.\d+))(?:[eE][+-]?\d+)?$/
+
 const normalizeNumber = (value: unknown): number => {
   if (typeof value === "number" && Number.isFinite(value)) {
     return value
   }
-  if (typeof value === "string" && value.trim() !== "") {
-    const parsed = Number(value)
+  if (typeof value === "string") {
+    const trimmed = value.trim()
+    const parsed = finiteNumberStringPattern.test(trimmed)
+      ? Number(trimmed)
+      : Number.NaN
     if (Number.isFinite(parsed)) {
       return parsed
     }
@@ -81,27 +103,12 @@ const normalizeBigIntString = (value: unknown): string => {
   if (typeof value === "number" && Number.isSafeInteger(value)) {
     return BigInt(value).toString()
   }
-  if (typeof value === "string" && /^-?\d+$/.test(value.trim())) {
-    return BigInt(value.trim()).toString()
+  if (typeof value === "string") {
+    return canonicalizeBigIntString(value)
   }
   throw new Error("Expected an integer-like bigint value")
 }
 
-const canonicalizeDecimalString = (input: string): string => {
-  const trimmed = input.trim()
-  const match = /^([+-]?)(\d+)(?:\.(\d+))?$/.exec(trimmed)
-  if (match === null) {
-    throw new Error("Expected a decimal string")
-  }
-  const sign = match[1] === "-" ? "-" : ""
-  const integer = match[2]!.replace(/^0+(?=\d)/, "") || "0"
-  const fraction = (match[3] ?? "").replace(/0+$/, "")
-  if (fraction.length === 0) {
-    return `${sign}${integer}`
-  }
-  return `${sign}${integer}.${fraction}`
-}
-
 const normalizeDecimalString = (value: unknown): string => {
   if (typeof value === "string") {
     return canonicalizeDecimalString(value)
@@ -121,12 +128,15 @@ const normalizeLocalDate = (value: unknown): string => {
     return formatLocalDate(value)
   }
   const raw = expectString(value, "local date").trim()
-  if (/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+  if (isValidLocalDateString(raw)) {
     return raw
   }
-  const parsed = new Date(raw)
-  if (!Number.isNaN(parsed.getTime())) {
-    return formatLocalDate(parsed)
+  const canonicalInstant = raw.replace(" ", "T").replace(/z$/, "Z")
+  if (isValidInstantString(canonicalInstant)) {
+    const parsed = new Date(canonicalInstant)
+    if (!Number.isNaN(parsed.getTime())) {
+      return formatLocalDate(parsed)
+    }
   }
   throw new Error("Expected a local-date value")
 }
@@ -136,7 +146,7 @@ const normalizeLocalTime = (value: unknown): string => {
     return formatLocalTime(value)
   }
   const raw = expectString(value, "local time").trim()
-  if (/^\d{2}:\d{2}:\d{2}(?:\.\d+)?$/.test(raw)) {
+  if (isValidLocalTimeString(raw)) {
     return raw
   }
   throw new Error("Expected a local-time value")
@@ -147,7 +157,7 @@ const normalizeOffsetTime = (value: unknown): string => {
     return `${formatLocalTime(value)}Z`
   }
   const raw = expectString(value, "offset time").trim()
-  if (/^\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(raw)) {
+  if (isValidOffsetTimeString(raw)) {
     return raw
   }
   throw new Error("Expected an offset-time value")
@@ -158,11 +168,13 @@ const normalizeLocalDateTime = (value: unknown): string => {
     return formatLocalDateTime(value)
   }
   const raw = expectString(value, "local datetime").trim()
-  if (/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?$/.test(raw)) {
-    return raw.replace(" ", "T")
+  const canonicalLocalDateTime = raw.replace(" ", "T")
+  if (isValidLocalDateTimeString(canonicalLocalDateTime)) {
+    return canonicalLocalDateTime
   }
-  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(raw)) {
-    const parsed = new Date(raw)
+  const canonicalInstant = raw.replace(" ", "T").replace(/z$/, "Z")
+  if (isValidInstantString(canonicalInstant)) {
+    const parsed = new Date(canonicalInstant)
     if (!Number.isNaN(parsed.getTime())) {
       return formatLocalDateTime(parsed)
     }
@@ -178,7 +190,11 @@ const normalizeInstant = (value: unknown): string => {
   if (!/[zZ]|[+-]\d{2}:\d{2}$/.test(raw)) {
     throw new Error("Instant values require a timezone offset")
   }
-  const parsed = new Date(raw)
+  const canonicalInstant = raw.replace(" ", "T").replace(/z$/, "Z")
+  if (!isValidInstantString(canonicalInstant)) {
+    throw new Error("Expected an ISO instant value")
+  }
+  const parsed = new Date(canonicalInstant)
   if (Number.isNaN(parsed.getTime())) {
     throw new Error("Expected an ISO instant value")
   }
@@ -209,20 +225,21 @@ const normalizeBytes = (value: unknown): Uint8Array => {
   throw new Error("Expected a byte array value")
 }
 
-const isJsonValue = (value: unknown): boolean => {
+export const isJsonValue = (value: unknown): boolean => {
   if (value === null) {
     return true
   }
   switch (typeof value) {
     case "string":
-    case "number":
     case "boolean":
       return true
+    case "number":
+      return Number.isFinite(value)
     case "object":
       if (Array.isArray(value)) {
         return value.every(isJsonValue)
       }
-      return isRecord(value) && Object.values(value).every(isJsonValue)
+      return isPlainRecord(value) && Object.values(value).every(isJsonValue)
     default:
       return false
   }
@@ -230,11 +247,18 @@ const isJsonValue = (value: unknown): boolean => {
 
 const normalizeJson = (value: unknown): unknown => {
   if (typeof value === "string") {
-    const parsed = JSON.parse(value)
-    if (isJsonValue(parsed)) {
-      return parsed
+    try {
+      const parsed = JSON.parse(value)
+      if (isJsonValue(parsed)) {
+        return parsed
+      }
+      throw new Error("Parsed JSON value is not a valid JSON runtime")
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return value
+      }
+      throw error
     }
-    throw new Error("Parsed JSON value is not a valid JSON runtime")
   }
   if (isJsonValue(value)) {
     return value

package/src/internal/runtime/schema.ts

@@ -38,12 +38,14 @@ const schemaCache = new WeakMap<Expression.Any, RuntimeSchema | undefined>()
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
+const FiniteNumberSchema = Schema.Number.pipe(Schema.finite())
+
 const runtimeSchemaForTag = (tag: RuntimeTag): RuntimeSchema | undefined => {
   switch (tag) {
     case "string":
       return Schema.String
     case "number":
-      return Schema.Number
+      return FiniteNumberSchema
     case "bigintString":
       return BigIntStringSchema
     case "boolean":
@@ -388,7 +390,7 @@ const deriveRuntimeSchema = (
       return Schema.String
     case "count":
     case "jsonLength":
-      return Schema.Number
+      return FiniteNumberSchema
     case "max":
     case "min":
       return expressionRuntimeSchema(ast.value, context)
@@ -404,7 +406,7 @@ const deriveRuntimeSchema = (
     case "window":
       return ast.function === "over" && ast.value !== undefined
         ? expressionRuntimeSchema(ast.value, context)
-        : Schema.Number
+        : FiniteNumberSchema
     case "jsonGet":
     case "jsonPath":
     case "jsonAccess":