effect-qb 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-qb",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/internal/analytics.ts

@@ -0,0 +1,264 @@
+import * as ExpressionAst from "./expression-ast.js"
+import * as Expression from "./scalar.js"
+import {
+  makeExpression,
+  mergeManyDependencies,
+  type MergeDialect,
+  type MergeNullabilityTuple,
+  type TupleDependencies,
+  type TupleDialect
+} from "./query.js"
+import { literal } from "./standard-dsl.js"
+import { validateWindowFrame } from "./window-frame.js"
+
+export interface WindowOrderTerm<
+  Value extends Expression.Any = Expression.Any
+> {
+  readonly value: Value
+  readonly direction?: "asc" | "desc"
+}
+
+export interface WindowOrderSpec<
+  PartitionBy extends readonly Expression.Any[] = readonly Expression.Any[],
+  OrderBy extends readonly [WindowOrderTerm, ...WindowOrderTerm[]] =
+    readonly [WindowOrderTerm, ...WindowOrderTerm[]]
+> {
+  readonly partitionBy?: PartitionBy
+  readonly orderBy: OrderBy
+  readonly frame?: never
+}
+
+export interface WindowSpec<
+  PartitionBy extends readonly Expression.Any[] = readonly Expression.Any[],
+  OrderBy extends readonly [WindowOrderTerm, ...WindowOrderTerm[]] =
+    readonly [WindowOrderTerm, ...WindowOrderTerm[]]
+> {
+  readonly partitionBy?: PartitionBy
+  readonly orderBy: OrderBy
+  readonly frame?: ExpressionAst.WindowFrameNode<"rows" | "range">
+}
+
+type PartitionExpressions<Spec extends WindowSpec> =
+  Spec["partitionBy"] extends readonly Expression.Any[] ? Spec["partitionBy"] : readonly []
+
+type OrderExpression<Spec extends WindowSpec> =
+  Spec["orderBy"][number] extends WindowOrderTerm<infer Value> ? Value : never
+
+type SpecExpressions<Spec extends WindowSpec> = readonly [
+  ...PartitionExpressions<Spec>,
+  ...ReadonlyArray<OrderExpression<Spec>>
+]
+
+type WindowInputDialect<
+  Value extends Expression.Any,
+  Spec extends WindowSpec,
+  Extra extends readonly Expression.Any[] = readonly []
+> = TupleDialect<readonly [Value, ...SpecExpressions<Spec>, ...Extra]>
+
+type WindowDialectConstraint<
+  Dialect extends string,
+  Value extends Expression.Any,
+  Spec extends WindowSpec
+> = Exclude<WindowInputDialect<Value, Spec>, Dialect | "standard"> extends never
+  ? unknown
+  : {
+      readonly __effect_qb_error__: "effect-qb: window expression is incompatible with this dialect"
+      readonly __effect_qb_expression_dialect__: WindowInputDialect<Value, Spec>
+      readonly __effect_qb_target_dialect__: Dialect
+    }
+
+type WindowResult<
+  Kind extends Extract<ExpressionAst.WindowKind, "lag" | "lead" | "firstValue" | "lastValue">,
+  Value extends Expression.Any,
+  Spec extends WindowSpec,
+  Nullable extends Expression.Nullability,
+  Extra extends readonly Expression.Any[] = readonly [],
+  Dialect extends string = WindowInputDialect<Value, Spec, Extra>
+> = Expression.Scalar<
+  Expression.RuntimeOf<Value>,
+  Expression.DbTypeOf<Value>,
+  Nullable,
+  Dialect,
+  "window",
+  TupleDependencies<readonly [Value, ...SpecExpressions<Spec>, ...Extra]>
+> & {
+  readonly [ExpressionAst.TypeId]: ExpressionAst.WindowNode<
+    Kind,
+    Value,
+    PartitionExpressions<Spec>,
+    readonly ExpressionAst.WindowOrderByNode[]
+  >
+}
+
+const normalizeSpec = <Spec extends WindowSpec>(spec: Spec) => {
+  validateWindowFrame(spec.frame)
+  return {
+    partitionBy: spec.partitionBy ?? [],
+    orderBy: spec.orderBy.map((term) => ({
+      value: term.value,
+      direction: term.direction ?? "asc"
+    })),
+    frame: spec.frame
+  }
+}
+
+const rejectExplicitPortableFrame = (
+  functionName: string,
+  spec: WindowOrderSpec
+): void => {
+  if ((spec as WindowSpec).frame !== undefined) {
+    throw new Error(
+      `${functionName} does not accept an explicit frame on the portable Function API; use a dialect Function helper`
+    )
+  }
+}
+
+const windowExpression = <
+  Kind extends Extract<ExpressionAst.WindowKind, "lag" | "lead" | "firstValue" | "lastValue">,
+  Value extends Expression.Any,
+  Spec extends WindowSpec,
+  Nullable extends Expression.Nullability
+>(
+  kind: Kind,
+  value: Value,
+  spec: Spec,
+  nullability: Nullable,
+  options: {
+    readonly offset?: Expression.Any
+    readonly defaultValue?: Expression.Any
+    readonly fallbackDialect?: string
+  } = {}
+): WindowResult<Kind, Value, Spec, Nullable> => {
+  const normalized = normalizeSpec(spec)
+  const { fallbackDialect, ...astOptions } = options
+  const expressions = [
+    value,
+    ...normalized.partitionBy,
+    ...normalized.orderBy.map((term) => term.value),
+    ...(options.offset === undefined ? [] : [options.offset]),
+    ...(options.defaultValue === undefined ? [] : [options.defaultValue])
+  ]
+  return makeExpression({
+    runtime: undefined as unknown as Expression.RuntimeOf<Value>,
+    dbType: value[Expression.TypeId].dbType,
+    runtimeSchema: value[Expression.TypeId].runtimeSchema,
+    driverValueMapping: value[Expression.TypeId].driverValueMapping,
+    nullability,
+    dialect: expressions.find((entry) => entry[Expression.TypeId].dialect !== "standard")?.[Expression.TypeId].dialect ??
+      fallbackDialect ??
+      value[Expression.TypeId].dialect,
+    kind: "window",
+    dependencies: mergeManyDependencies(expressions)
+  }, {
+    kind: "window",
+    function: kind,
+    value,
+    ...astOptions,
+    ...normalized
+  }) as never
+}
+
+export interface OffsetOptions<
+  Value extends Expression.Any,
+  Spec extends WindowOrderSpec
+> {
+  readonly spec: Spec
+  readonly offset?: number
+  readonly default?: Expression.RuntimeOf<Value>
+}
+
+/** Value from a preceding row in the ordered window. */
+export const lag = <
+  Value extends Expression.Any,
+  Spec extends WindowOrderSpec
+>(
+  value: Value,
+  options: OffsetOptions<Value, Spec>
+): WindowResult<"lag", Value, Spec, "maybe"> => {
+  rejectExplicitPortableFrame("lag", options.spec)
+  if (options.offset !== undefined && (!Number.isSafeInteger(options.offset) || options.offset < 0)) {
+    throw new Error("lag offset must be a non-negative safe integer")
+  }
+  return windowExpression("lag", value, options.spec, "maybe", {
+    ...(options.offset === undefined && options.default === undefined
+      ? {}
+      : { offset: literal(options.offset ?? 1) }),
+    ...(options.default === undefined ? {} : { defaultValue: literal(options.default as any) })
+  })
+}
+
+/** Value from a following row in the ordered window. */
+export const lead = <
+  Value extends Expression.Any,
+  Spec extends WindowOrderSpec
+>(
+  value: Value,
+  options: OffsetOptions<Value, Spec>
+): WindowResult<"lead", Value, Spec, "maybe"> => {
+  rejectExplicitPortableFrame("lead", options.spec)
+  if (options.offset !== undefined && (!Number.isSafeInteger(options.offset) || options.offset < 0)) {
+    throw new Error("lead offset must be a non-negative safe integer")
+  }
+  return windowExpression("lead", value, options.spec, "maybe", {
+    ...(options.offset === undefined && options.default === undefined
+      ? {}
+      : { offset: literal(options.offset ?? 1) }),
+    ...(options.default === undefined ? {} : { defaultValue: literal(options.default as any) })
+  })
+}
+
+/** First value in the portable default window frame. */
+export const firstValue = <
+  Value extends Expression.Any,
+  Spec extends WindowOrderSpec
+>(
+  value: Value,
+  spec: Spec
+): WindowResult<"firstValue", Value, Spec, Expression.NullabilityOf<Value>> => {
+  rejectExplicitPortableFrame("firstValue", spec)
+  return windowExpression("firstValue", value, spec, value[Expression.TypeId].nullability)
+}
+
+/** Last value in the portable default window frame. */
+export const lastValue = <
+  Value extends Expression.Any,
+  Spec extends WindowOrderSpec
+>(
+  value: Value,
+  spec: Spec
+): WindowResult<"lastValue", Value, Spec, Expression.NullabilityOf<Value>> => {
+  rejectExplicitPortableFrame("lastValue", spec)
+  return windowExpression("lastValue", value, spec, value[Expression.TypeId].nullability)
+}
+
+export const makeDialectFirstValue = <Dialect extends string>(dialect: Dialect) =>
+  <
+    Value extends Expression.Any,
+    Spec extends WindowSpec
+  >(
+    value: Value,
+    spec: Spec & WindowDialectConstraint<Dialect, Value, Spec>
+  ): WindowResult<
+    "firstValue",
+    Value,
+    Spec,
+    "maybe",
+    readonly [],
+    MergeDialect<WindowInputDialect<Value, Spec>, Dialect>
+  > => windowExpression("firstValue", value, spec, "maybe", { fallbackDialect: dialect }) as never
+
+export const makeDialectLastValue = <Dialect extends string>(dialect: Dialect) =>
+  <
+    Value extends Expression.Any,
+    Spec extends WindowSpec
+  >(
+    value: Value,
+    spec: Spec & WindowDialectConstraint<Dialect, Value, Spec>
+  ): WindowResult<
+    "lastValue",
+    Value,
+    Spec,
+    "maybe",
+    readonly [],
+    MergeDialect<WindowInputDialect<Value, Spec>, Dialect>
+  > => windowExpression("lastValue", value, spec, "maybe", { fallbackDialect: dialect }) as never

package/src/internal/coercion/errors.d.ts

@@ -13,5 +13,5 @@ export type CastTargetError<Source extends Expression.DbType.Any, Target extends
     readonly __effect_qb_source_db_type__: Source;
     readonly __effect_qb_target_db_type__: Target;
     readonly __effect_qb_dialect__: Dialect;
-    readonly __effect_qb_hint__: "Use one of the supported Q.type.<kind>() witnesses";
+    readonly __effect_qb_hint__: "Use one of the supported Type.<kind>() witnesses";
 };

package/src/internal/coercion/errors.ts

@@ -25,5 +25,5 @@ export type CastTargetError<
   readonly __effect_qb_source_db_type__: Source
   readonly __effect_qb_target_db_type__: Target
   readonly __effect_qb_dialect__: Dialect
-  readonly __effect_qb_hint__: "Use one of the supported Q.type.<kind>() witnesses"
+  readonly __effect_qb_hint__: "Use one of the supported Type.<kind>() witnesses"
 }

package/src/internal/custom-sql-renderer.ts

@@ -0,0 +1,20 @@
+import type { RenderState, SqlDialect } from "./dialect.js"
+import type * as ExpressionAst from "./expression-ast.js"
+import * as Expression from "./scalar.js"
+
+export const renderCustomSql = (
+  node: ExpressionAst.CustomSqlNode,
+  state: RenderState,
+  dialect: SqlDialect,
+  renderExpression: (expression: Expression.Any, state: RenderState, dialect: SqlDialect) => string
+): string => node.strings.map((part, index) => {
+  const value = node.values[index]
+  if (value === undefined) {
+    return part
+  }
+  return part + (
+    Expression.TypeId in value
+      ? renderExpression(value, state, dialect)
+      : value.parts.map((segment) => dialect.quoteIdentifier(segment)).join(".")
+  )
+}).join("")

package/src/internal/dialect-numeric.ts

@@ -0,0 +1,332 @@
+import * as ExpressionAst from "./expression-ast.js"
+import {
+  makeExpression,
+  mergeAggregationManyRuntime,
+  mergeManyDependencies,
+  type MergeAggregation,
+  type MergeNullabilityTuple,
+  type TupleDependencies
+} from "./query.js"
+import * as Expression from "./scalar.js"
+
+export type Input = Expression.Any | number
+
+export type Literal<
+  Value extends number,
+  Db extends Expression.DbType.Any,
+  Dialect extends string
+> = Expression.Scalar<Value, Db, "never", Dialect, "scalar", never> & {
+  readonly [ExpressionAst.TypeId]: ExpressionAst.LiteralNode<Value>
+}
+
+export type AsExpression<
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = Value extends Expression.Any
+  ? Value
+  : Literal<Extract<Value, number>, LiteralDb, Dialect>
+
+export type DbTypeOfInput<
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = Expression.DbTypeOf<AsExpression<Value, LiteralDb, Dialect>>
+
+export type InputDialect<
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = AsExpression<Value, LiteralDb, Dialect>[typeof Expression.TypeId]["dialect"]
+
+export type DialectConstraint<
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = Exclude<InputDialect<Value, LiteralDb, Dialect>, Dialect | "standard"> extends never
+  ? unknown
+  : {
+      readonly __effect_qb_error__: "effect-qb: numeric expression is incompatible with this dialect"
+      readonly __effect_qb_expression_dialect__: InputDialect<Value, LiteralDb, Dialect>
+      readonly __effect_qb_target_dialect__: Dialect
+    }
+
+type BinaryValues<
+  Left extends Input,
+  Right extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = readonly [
+  AsExpression<Left, LiteralDb, Dialect>,
+  AsExpression<Right, LiteralDb, Dialect>
+]
+
+export type BinaryNullability<
+  Left extends Input,
+  Right extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = MergeNullabilityTuple<BinaryValues<Left, Right, LiteralDb, Dialect>>
+
+type ZeroPossibility<Value extends Input> = Value extends number
+  ? number extends Value ? "possible" : Value extends 0 ? "always" : "never"
+  : "possible"
+
+export type ZeroDivisorNullability<
+  Left extends Input,
+  Right extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  Dialect extends string
+> = BinaryNullability<Left, Right, LiteralDb, Dialect> extends infer Nullable extends Expression.Nullability
+  ? Nullable extends "always"
+    ? "always"
+    : ZeroPossibility<Right> extends "always" ? "always"
+      : ZeroPossibility<Right> extends "possible" ? "maybe" : Nullable
+  : never
+
+export type BinaryResult<
+  Left extends Input,
+  Right extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  ResultDb extends Expression.DbType.Any,
+  Nullable extends Expression.Nullability,
+  Dialect extends string
+> = Expression.Scalar<
+  Expression.RuntimeOfDbType<ResultDb>,
+  ResultDb,
+  Nullable,
+  Dialect,
+  MergeAggregation<
+    Expression.KindOf<AsExpression<Left, LiteralDb, Dialect>>,
+    Expression.KindOf<AsExpression<Right, LiteralDb, Dialect>>
+  >,
+  TupleDependencies<BinaryValues<Left, Right, LiteralDb, Dialect>>
+> & {
+  readonly [ExpressionAst.TypeId]: ExpressionAst.BinaryNode<"modulo">
+}
+
+export type RoundResult<
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  ResultDb extends Expression.DbType.Any,
+  Nullable extends Expression.Nullability,
+  Dialect extends string,
+  WithScale extends boolean
+> = Expression.Scalar<
+  Expression.RuntimeOfDbType<ResultDb>,
+  ResultDb,
+  Nullable,
+  Dialect,
+  Expression.KindOf<AsExpression<Value, LiteralDb, Dialect>>,
+  Expression.DependenciesOf<AsExpression<Value, LiteralDb, Dialect>>
+> & {
+  readonly [ExpressionAst.TypeId]: WithScale extends true
+    ? ExpressionAst.FunctionCallNode<"round">
+    : ExpressionAst.UnaryNode<"round">
+}
+
+export type AggregateResult<
+  Kind extends "sum" | "avg",
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  ResultDb extends Expression.DbType.Any,
+  Dialect extends string
+> = Expression.Scalar<
+  Expression.RuntimeOfDbType<ResultDb>,
+  ResultDb,
+  "maybe",
+  Dialect,
+  "aggregate",
+  Expression.DependenciesOf<AsExpression<Value, LiteralDb, Dialect>>
+> & {
+  readonly [ExpressionAst.TypeId]: ExpressionAst.UnaryNode<
+    Kind,
+    AsExpression<Value, LiteralDb, Dialect>
+  >
+}
+
+const literal = <
+  Value extends number,
+  Db extends Expression.DbType.Any,
+  Dialect extends string
+>(
+  value: Value,
+  dbType: Db,
+  dialect: Dialect
+): Literal<Value, Db, Dialect> =>
+  makeExpression({
+    runtime: value,
+    dbType,
+    driverValueMapping: dbType.driverValueMapping,
+    nullability: "never",
+    dialect,
+    kind: "scalar",
+    dependencies: {}
+  }, {
+    kind: "literal",
+    value
+  })
+
+const asExpression = <
+  Value extends Input,
+  Db extends Expression.DbType.Any,
+  Dialect extends string
+>(
+  value: Value,
+  literalDb: Db,
+  dialect: Dialect
+): AsExpression<Value, Db, Dialect> =>
+  (typeof value === "number"
+    ? literal(value, literalDb, dialect)
+    : value) as AsExpression<Value, Db, Dialect>
+
+export const modulo = <
+  Left extends Input,
+  Right extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  ResultDb extends Expression.DbType.Any,
+  Nullable extends Expression.Nullability,
+  Dialect extends string
+>(
+  left: Left,
+  right: Right,
+  options: {
+    readonly dialect: Dialect
+    readonly literalDb: LiteralDb
+    readonly resultDb: ResultDb
+    readonly nullability: Nullable
+  }
+): BinaryResult<Left, Right, LiteralDb, ResultDb, Nullable, Dialect> => {
+  const leftExpression = asExpression(left, options.literalDb, options.dialect)
+  const rightExpression = asExpression(right, options.literalDb, options.dialect)
+  const values = [leftExpression, rightExpression] as const
+  return (makeExpression as any)({
+    runtime: undefined,
+    dbType: options.resultDb,
+    driverValueMapping: options.resultDb.driverValueMapping,
+    nullability: options.nullability,
+    dialect: options.dialect,
+    kind: mergeAggregationManyRuntime(values),
+    dependencies: mergeManyDependencies(values)
+  }, {
+    kind: "modulo",
+    left: leftExpression,
+    right: rightExpression
+  }) as BinaryResult<Left, Right, LiteralDb, ResultDb, Nullable, Dialect>
+}
+
+export const round = <
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  ScaleDb extends Expression.DbType.Any,
+  ResultDb extends Expression.DbType.Any,
+  Nullable extends Expression.Nullability,
+  Dialect extends string,
+  WithScale extends boolean
+>(
+  value: Value,
+  scale: number | undefined,
+  options: {
+    readonly dialect: Dialect
+    readonly literalDb: LiteralDb
+    readonly scaleDb: ScaleDb
+    readonly resultDb: ResultDb
+    readonly nullability: Nullable
+  }
+): RoundResult<Value, LiteralDb, ResultDb, Nullable, Dialect, WithScale> => {
+  const expression = asExpression(value, options.literalDb, options.dialect)
+  if (scale === undefined) {
+    return (makeExpression as any)({
+      runtime: undefined,
+      dbType: options.resultDb,
+      driverValueMapping: options.resultDb.driverValueMapping,
+      nullability: options.nullability,
+      dialect: options.dialect,
+      kind: expression[Expression.TypeId].kind,
+      dependencies: expression[Expression.TypeId].dependencies
+    }, {
+      kind: "round",
+      value: expression
+    }) as RoundResult<Value, LiteralDb, ResultDb, Nullable, Dialect, WithScale>
+  }
+  if (!Number.isSafeInteger(scale)) {
+    throw new Error("round scale must be a safe integer")
+  }
+  const scaleExpression = literal(scale, options.scaleDb, options.dialect)
+  return (makeExpression as any)({
+    runtime: undefined,
+    dbType: options.resultDb,
+    driverValueMapping: options.resultDb.driverValueMapping,
+    nullability: options.nullability,
+    dialect: options.dialect,
+    kind: expression[Expression.TypeId].kind,
+    dependencies: expression[Expression.TypeId].dependencies
+  }, {
+    kind: "function",
+    name: "round",
+    args: [expression, scaleExpression]
+  }) as RoundResult<Value, LiteralDb, ResultDb, Nullable, Dialect, WithScale>
+}
+
+export const aggregate = <
+  Kind extends "sum" | "avg",
+  Value extends Input,
+  LiteralDb extends Expression.DbType.Any,
+  ResultDb extends Expression.DbType.Any,
+  Dialect extends string
+>(
+  kind: Kind,
+  value: Value,
+  options: {
+    readonly dialect: Dialect
+    readonly literalDb: LiteralDb
+    readonly resultDb: ResultDb
+  }
+): AggregateResult<Kind, Value, LiteralDb, ResultDb, Dialect> => {
+  const expression = asExpression(value, options.literalDb, options.dialect)
+  return (makeExpression as any)({
+    runtime: undefined,
+    dbType: options.resultDb,
+    driverValueMapping: options.resultDb.driverValueMapping,
+    nullability: "maybe",
+    dialect: options.dialect,
+    kind: "aggregate",
+    dependencies: expression[Expression.TypeId].dependencies
+  }, {
+    kind,
+    value: expression
+  }) as AggregateResult<Kind, Value, LiteralDb, ResultDb, Dialect>
+}
+
+const inputNullability = (value: Input): Expression.Nullability =>
+  typeof value === "number"
+    ? "never"
+    : value[Expression.TypeId].nullability
+
+export const binaryInputNullability = (
+  left: Input,
+  right: Input
+): Expression.Nullability => {
+  const leftNullability = inputNullability(left)
+  const rightNullability = inputNullability(right)
+  if (leftNullability === "always" || rightNullability === "always") {
+    return "always"
+  }
+  return leftNullability === "maybe" || rightNullability === "maybe"
+    ? "maybe"
+    : "never"
+}
+
+export const nullableForZeroDivisor = (
+  left: Input,
+  right: Input
+): Expression.Nullability => {
+  const merged = binaryInputNullability(left, right)
+  if (merged === "always") {
+    return "always"
+  }
+  if (typeof right === "number") {
+    return right === 0 ? "always" : merged
+  }
+  return "maybe"
+}