@bjornpagen/bumbledb 0.20.2 → 1.0.0

package/src/query/atom.ts

@@ -1,6 +1,7 @@
-import * as errors from "@superbuilders/errors"
-import type { AnyClosedRoster, AnyField, Infer, IntervalValue } from "#fields.ts"
+import { AuthoringError } from "#errors.ts"
+import type { AnyClosedRoster, AnyField, FloatIntervalValue, Infer, IntervalValue } from "#fields.ts"
 import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
+import type { QueryNode } from "#query/compute.ts"
 import type {
 	AntiJoinOk,
 	AnyVar,
@@ -16,6 +17,8 @@ import type {
 } from "#query/scope.ts"
 import { isTerm, term } from "#query/scope.ts"
 import type { FieldsShape } from "#relation.ts"
+import type { ScalarKind } from "#scalar.ts"
+import type { Uuid } from "#uuid.ts"
 
 type BindingTermData =
 	| { readonly kind: "var"; readonly ref: AnyVar }
@@ -65,14 +68,16 @@ type AggData =
 	| { readonly op: "count" }
 	| {
 			readonly op: "fold"
-			readonly fold: "sum" | "min" | "max"
+			readonly fold: "sum" | "mean" | "min" | "max"
 			readonly over: AnyVar
 	  }
 	| { readonly op: "pack"; readonly over: AnyVar }
 
+/** Compute `expr` is the shared `#scalar.ts` query-var node (one grammar). */
 type FindEntryData =
 	| { readonly kind: "var"; readonly over: AnyVar }
 	| { readonly kind: "aggregate"; readonly agg: AggData }
+	| { readonly kind: "compute"; readonly expr: QueryNode; readonly result: ScalarKind }
 
 interface FindColumn {
 	readonly name: string
@@ -141,7 +146,11 @@ type DerivedTable = InteriorData | RecHead
 type BindingInput<F extends AnyField> =
 	| Infer<F>
 	| (F extends { readonly closed: { readonly handles: readonly string[] } } ? readonly Infer<F>[] : never)
-	| (F extends { readonly kind: "interval" } ? bigint : never)
+	| (F extends { readonly kind: "interval"; readonly element: "f64" }
+			? number
+			: F extends { readonly kind: "interval" }
+				? bigint
+				: never)
 	| AnyVar
 	| Param<string>
 	| SetParam<string>
@@ -216,15 +225,34 @@ type AnyNotInteriorAtom = NotInteriorAtom<unknown>
 
 type AnyCond = AnyCmp | Tree<readonly AnyTreeChild[]> | AnyNotAtom | AnyNotInteriorAtom
 
-type EqRight = AnyVar | Param<string> | SetParam<string> | bigint | string | boolean | Uint8Array | IntervalValue
-
-type NeRight = AnyVar | Param<string> | bigint | string | boolean | Uint8Array | IntervalValue
+type EqRight =
+	| AnyVar
+	| Param<string>
+	| SetParam<string>
+	| bigint
+	| number
+	| string
+	| boolean
+	| Uint8Array
+	| IntervalValue
+	| FloatIntervalValue
+
+type NeRight =
+	| AnyVar
+	| Param<string>
+	| bigint
+	| number
+	| string
+	| boolean
+	| Uint8Array
+	| IntervalValue
+	| FloatIntervalValue
 
-type OrderSide = AnyVar | Param<string> | bigint | boolean
+type OrderSide = AnyVar | Param<string> | bigint | number | boolean | Uuid
 
-type PointSide = AnyVar | Param<string> | bigint
+type PointSide = AnyVar | Param<string> | bigint | number
 
-type IntervalSide = AnyVar | Param<string> | IntervalValue
+type IntervalSide = AnyVar | Param<string> | IntervalValue | FloatIntervalValue
 
 function comparison<Op extends CmpKind, L, R, M>(op: Op, lhs: L, rhs: R, mask: M): Cmp<Op, L, R, M> {
 	return Object.freeze({ cond: "cmp", op, lhs, rhs, mask })
@@ -236,9 +264,9 @@ function isVariableSide(value: unknown): boolean {
 
 function assertTermSide(op: string, lhs: unknown, rhs: unknown): void {
 	if (!isVariableSide(lhs) && !isVariableSide(rhs)) {
-		throw errors.new(
-			`${op}: a comparison without a variable side is constant-valued (a parameter is a constant at execution) — write the query you mean`
-		)
+		throw new AuthoringError({
+			message: `${op}: a comparison without a variable side is constant-valued (a parameter is a constant at execution) — write the query you mean`
+		})
 	}
 }
 
@@ -313,9 +341,9 @@ function allen<const A extends IntervalSide, const B extends IntervalSide>(
 ): Cmp<"allen", A, B, number> {
 	assertTermSide("allen", left, right)
 	if (!Number.isInteger(mask) || mask < 0 || mask > ALLEN_ALL_BITS) {
-		throw errors.new(
-			`allen mask ${mask} is not a 13-bit mask — build masks from the ALLEN constants (bumbledb allen.rs: bits above the low 13 are unrepresentable)`
-		)
+		throw new AuthoringError({
+			message: `allen mask ${mask} is not a 13-bit mask — build masks from the ALLEN constants (bumbledb allen.rs: bits above the low 13 are unrepresentable)`
+		})
 	}
 	return comparison("allen", left, right, mask)
 }
@@ -354,7 +382,7 @@ function not(
 }
 
 /**
- * Whether a variable's OWN field is NUMERIC (u64/i64) — the judgment the
+ * Whether a variable's OWN field is NUMERIC (u64/i64/f64) — the judgment the
  * point side of `pointIn` and the `sum` input read: a point lives in the
  * interval's element domain, and a quantifier is not an addition, so bool
  * (orderable, never numeric) is exactly here refused. A CLOSED reference
@@ -366,11 +394,11 @@ function not(
  */
 type NumericVarOk<V extends AnyVar> = V["field"] extends { readonly closed: AnyClosedRoster }
 	? false
-	: V["field"]["kind"] extends "u64" | "i64"
+	: V["field"]["kind"] extends "u64" | "i64" | "f64"
 		? true
 		: false
 
-type OrderVarOk<V extends AnyVar> = V["field"]["kind"] extends "bool" ? true : NumericVarOk<V>
+type OrderVarOk<V extends AnyVar> = V["field"]["kind"] extends "bool" | "uuid" ? true : NumericVarOk<V>
 
 type IntervalVarOk<V extends AnyVar> = V["field"]["kind"] extends "interval" ? true : false
 
@@ -384,9 +412,13 @@ type OrderDomain<T> = T extends AnyVar
 		? "open"
 		: T extends bigint
 			? "integer"
-			: T extends boolean
-				? "bool"
-				: never
+			: T extends number
+				? "f64"
+				: T extends boolean
+					? "bool"
+					: T extends Uuid
+						? "uuid"
+						: never
 
 type OrderDomainsOk<A, B> = [A] extends [never]
 	? false
@@ -403,9 +435,13 @@ type OrderDomainsOk<A, B> = [A] extends [never]
 					: B extends "bool"
 						? false
 						: A extends "integer"
-							? true
-							: B extends "integer"
+							? B extends "integer" | "u64" | "i64"
 								? true
+								: false
+							: B extends "integer"
+								? A extends "u64" | "i64"
+									? true
+									: false
 								: A extends B
 									? true
 									: false
@@ -413,7 +449,7 @@ type OrderDomainsOk<A, B> = [A] extends [never]
 type OrderPairOk<L, R> = CmpVarSideOk<L, R> extends true ? OrderDomainsOk<OrderDomain<L>, OrderDomain<R>> : false
 
 type IntervalElementDomain<T> = T extends AnyVar
-	? T["field"] extends { readonly kind: "interval"; readonly element: infer E extends "u64" | "i64" }
+	? T["field"] extends { readonly kind: "interval"; readonly element: infer E extends "u64" | "i64" | "f64" }
 		? E
 		: never
 	: "open"

package/src/query/compute.ts

@@ -0,0 +1,237 @@
+/**
+ * Query-scoped scalar expressions (C05 `FindTerm::Compute`): the
+ * variable-addressed leaf scope over the ONE shared operator roster in
+ * `#scalar.ts`. Leaves are bound query variables that lower to `VarId`s.
+ * Operators are the shared constructors — this module only admits known
+ * schema kinds at query-var leaves.
+ *
+ * `ComputeExpr<K>` is a `ScalarNode<"query-var", K>`. Distinct I64 and U64
+ * survive host inference; they do not collapse to plain `bigint`.
+ */
+import { AuthoringError } from "#errors.ts"
+import type { AnyField } from "#fields.ts"
+import { bool as boolField, f64 as f64Field, i64 as i64Field, rosterOf, u64 as u64Field } from "#fields.ts"
+import type { AnyVar } from "#query/scope.ts"
+import { isTerm, term } from "#query/scope.ts"
+import type { ScalarKind, ScalarLiteral, ScalarNode } from "#scalar.ts"
+import {
+	checkBool,
+	checkF64,
+	checkI64,
+	checkU64,
+	isScalarNode,
+	MAX_SCALAR_DEPTH,
+	queryVarLeaf,
+	queryVarsOf,
+	scalarBinary,
+	scalarCast,
+	scalarFloatPredicate,
+	scalarLiteral,
+	scalarNegate
+} from "#scalar.ts"
+
+/** Query-var tree: the shared AST restricted to this leaf scope. */
+type QueryNode = ScalarNode<"query-var">
+
+/** Host value for a derived query compute kind. */
+type ComputeValue<K extends ScalarKind> = K extends "f64" ? number : K extends "bool" ? boolean : bigint
+
+type ComputeExpr<K extends ScalarKind> = ScalarNode<"query-var", K>
+
+type AnyComputeExpr = ComputeExpr<"u64"> | ComputeExpr<"i64"> | ComputeExpr<"f64"> | ComputeExpr<"bool">
+
+/** One operand as the runtime judgment sees it. */
+type Operand = AnyVar | AnyComputeExpr
+
+type NumericVarOperand = AnyVar & { readonly field: { readonly kind: "u64" | "i64" | "f64" } }
+type ArithmeticOperand = ComputeExpr<"u64"> | ComputeExpr<"i64"> | ComputeExpr<"f64"> | NumericVarOperand
+type SignedOperand =
+	| ComputeExpr<"i64">
+	| ComputeExpr<"f64">
+	| (AnyVar & { readonly field: { readonly kind: "i64" | "f64" } })
+type FloatOperand = ComputeExpr<"f64"> | (AnyVar & { readonly field: { readonly kind: "f64" } })
+
+type OperandKind<O> =
+	O extends ComputeExpr<infer K extends ScalarKind>
+		? K
+		: O extends AnyVar
+			? O["field"]["kind"] extends "u64" | "i64" | "f64" | "bool"
+				? O["field"]["kind"]
+				: never
+			: never
+
+function isComputeExpr(value: unknown): value is AnyComputeExpr {
+	return isScalarNode(value) && value.scope === "query-var" && value.result !== "unresolved"
+}
+
+function varKindOf(where: string, ref: AnyVar): ScalarKind {
+	const roster = rosterOf(ref.field)
+	if (roster !== undefined) {
+		throw new AuthoringError({
+			message: `${where}: ${ref.label} is a ${roster.name} reference — declaration order is an accident, not semantics: a closed reference never enters arithmetic`
+		})
+	}
+	const kind = ref.field.kind
+	if (kind === "u64" || kind === "i64" || kind === "f64" || kind === "bool") {
+		return kind
+	}
+	throw new AuthoringError({
+		message: `${where}: ${ref.label} is ${kind} — a scalar expression reads u64/i64/f64/bool variables only`
+	})
+}
+
+function asQueryNode(where: string, operand: Operand): QueryNode {
+	if (isComputeExpr(operand)) {
+		return operand
+	}
+	if (isTerm(operand) && operand[term] === "var") {
+		return queryVarLeaf(operand, varKindOf(where, operand))
+	}
+	throw new AuthoringError({
+		message: `${where}: expected a query variable or a Compute expression — literals are tagged (Compute.u64/i64/f64/bool)`
+	})
+}
+
+function literal<K extends ScalarKind>(value: ScalarLiteral): ComputeExpr<K> {
+	return scalarLiteral("query-var", value) as ComputeExpr<K>
+}
+
+function u64(value: bigint): ComputeExpr<"u64"> {
+	checkU64(value, "Compute.u64")
+	return literal({ u64: value })
+}
+
+function i64(value: bigint): ComputeExpr<"i64"> {
+	checkI64(value, "Compute.i64")
+	return literal({ i64: value })
+}
+
+function f64(value: number): ComputeExpr<"f64"> {
+	checkF64(value, "Compute.f64")
+	return literal({ f64: value })
+}
+
+function bool(value: boolean): ComputeExpr<"bool"> {
+	checkBool(value, "Compute.bool")
+	return literal({ bool: value })
+}
+
+type BinaryKind = "add" | "subtract" | "multiply" | "divide"
+
+/** The right operand must have the left operand's kind, never an inferred union. */
+type SameKind<L, R> = [OperandKind<R>] extends [OperandKind<L>]
+	? [OperandKind<L>] extends [OperandKind<R>]
+		? R
+		: never
+	: never
+
+function binary<K extends "u64" | "i64" | "f64">(
+	op: BinaryKind,
+	left: ArithmeticOperand,
+	right: ArithmeticOperand
+): ComputeExpr<K> {
+	const where = `Compute.${op}`
+	return scalarBinary(where, op, asQueryNode(where, left), asQueryNode(where, right)) as ComputeExpr<K>
+}
+
+function add<L extends ArithmeticOperand, R extends ArithmeticOperand>(
+	left: L,
+	right: R & SameKind<NoInfer<L>, R>
+): ComputeExpr<OperandKind<L> & OperandKind<R> & ("u64" | "i64" | "f64")> {
+	return binary("add", left, right)
+}
+
+function subtract<L extends ArithmeticOperand, R extends ArithmeticOperand>(
+	left: L,
+	right: R & SameKind<NoInfer<L>, R>
+): ComputeExpr<OperandKind<L> & OperandKind<R> & ("u64" | "i64" | "f64")> {
+	return binary("subtract", left, right)
+}
+
+function multiply<L extends ArithmeticOperand, R extends ArithmeticOperand>(
+	left: L,
+	right: R & SameKind<NoInfer<L>, R>
+): ComputeExpr<OperandKind<L> & OperandKind<R> & ("u64" | "i64" | "f64")> {
+	return binary("multiply", left, right)
+}
+
+function divide<L extends ArithmeticOperand, R extends ArithmeticOperand>(
+	left: L,
+	right: R & SameKind<NoInfer<L>, R>
+): ComputeExpr<OperandKind<L> & OperandKind<R> & ("u64" | "i64" | "f64")> {
+	return binary("divide", left, right)
+}
+
+function negate<O extends SignedOperand>(operand: O): ComputeExpr<OperandKind<O> & ("i64" | "f64")> {
+	const where = "Compute.negate"
+	return scalarNegate(where, asQueryNode(where, operand)) as ComputeExpr<OperandKind<O> & ("i64" | "f64")>
+}
+
+function toF64(operand: ArithmeticOperand): ComputeExpr<"f64"> {
+	const where = "Compute.toF64"
+	return scalarCast(where, "toF64", "f64", asQueryNode(where, operand)) as ComputeExpr<"f64">
+}
+
+function toF64Exact(operand: ArithmeticOperand): ComputeExpr<"f64"> {
+	const where = "Compute.toF64Exact"
+	return scalarCast(where, "toF64Exact", "f64", asQueryNode(where, operand)) as ComputeExpr<"f64">
+}
+
+function toI64Exact(operand: ArithmeticOperand): ComputeExpr<"i64"> {
+	const where = "Compute.toI64Exact"
+	return scalarCast(where, "toI64Exact", "i64", asQueryNode(where, operand)) as ComputeExpr<"i64">
+}
+
+function toU64Exact(operand: ArithmeticOperand): ComputeExpr<"u64"> {
+	const where = "Compute.toU64Exact"
+	return scalarCast(where, "toU64Exact", "u64", asQueryNode(where, operand)) as ComputeExpr<"u64">
+}
+
+function isNaNExpr(operand: FloatOperand): ComputeExpr<"bool"> {
+	const where = "Compute.isNaN"
+	return scalarFloatPredicate(where, "isNaN", asQueryNode(where, operand))
+}
+
+function isFiniteExpr(operand: FloatOperand): ComputeExpr<"bool"> {
+	const where = "Compute.isFinite"
+	return scalarFloatPredicate(where, "isFinite", asQueryNode(where, operand))
+}
+
+/** Every variable the expression reads (validation binds them like any term). */
+function computeVarsOf(data: QueryNode): readonly AnyVar[] {
+	return queryVarsOf(data) as readonly AnyVar[]
+}
+
+function computeFieldOf(kind: ScalarKind): AnyField {
+	switch (kind) {
+		case "u64":
+			return u64Field
+		case "i64":
+			return i64Field
+		case "f64":
+			return f64Field
+		case "bool":
+			return boolField
+	}
+}
+
+const Compute = Object.freeze({
+	u64,
+	i64,
+	f64,
+	bool,
+	negate,
+	add,
+	subtract,
+	multiply,
+	divide,
+	toF64,
+	toF64Exact,
+	toI64Exact,
+	toU64Exact,
+	isNaN: isNaNExpr,
+	isFinite: isFiniteExpr
+})
+
+export type { AnyComputeExpr, ComputeExpr, ComputeValue, QueryNode }
+export { Compute, computeFieldOf, computeVarsOf, isComputeExpr, MAX_SCALAR_DEPTH as MAX_COMPUTE_DEPTH }

package/src/query/find.ts

@@ -1,9 +1,11 @@
-import type { Infer } from "#fields.ts"
+import type { AnyField, Infer } from "#fields.ts"
 import type { SchemaClasses } from "#law.ts"
 import type { IntervalVarOk, NumericVarOk } from "#query/atom.ts"
+import type { AnyComputeExpr, ComputeExpr, ComputeValue } from "#query/compute.ts"
 import type { AnyVar, MintSlotOf } from "#query/scope.ts"
+import type { ScalarKind } from "#scalar.ts"
 
-type FoldOpName = "sum" | "min" | "max" | "pack"
+type FoldOpName = "sum" | "mean" | "min" | "max" | "pack"
 
 interface CountAgg {
 	readonly agg: "count"
@@ -16,7 +18,7 @@ interface Agg<Op extends FoldOpName, Over extends AnyVar> {
 
 type AnyAgg = CountAgg | Agg<FoldOpName, AnyVar>
 
-type FindEntry = AnyVar | AnyAgg
+type FindEntry = AnyVar | AnyAgg | AnyComputeExpr
 
 type FindShape = Readonly<Record<string, FindEntry>>
 
@@ -29,7 +31,7 @@ function count(): CountAgg {
 }
 
 /**
- * Exact checked sum over a NUMERIC (u64/i64) variable — wide accumulator,
+ * Exact checked sum over a NUMERIC (u64/i64/f64) variable — wide accumulator,
  * one finalize range check; overflow is the engine's typed runtime error —
  * or over the measure (`r.sum(r.duration(w))`). Bool stays refused: a
  * quantifier is not an addition (R3).
@@ -38,6 +40,11 @@ function sum<const O extends AnyVar>(over: O): Agg<"sum", O> {
 	return aggregate("sum", over)
 }
 
+/** Exact sum divided by the binding count, rounded once. F64 inputs only. */
+function mean<const O extends AnyVar>(over: O): Agg<"mean", O> {
+	return aggregate("mean", over)
+}
+
 function min<const O extends AnyVar>(over: O): Agg<"min", O> {
 	return aggregate("min", over)
 }
@@ -54,11 +61,17 @@ type FindEntryOk<E> = E extends AnyVar
 	? true
 	: E extends CountAgg
 		? true
-		: E extends Agg<"sum" | "min" | "max", infer O extends AnyVar>
-			? NumericVarOk<O>
-			: E extends Agg<"pack", infer V extends AnyVar>
-				? IntervalVarOk<V>
+		: E extends Agg<"mean", infer O extends AnyVar>
+			? O["field"]["kind"] extends "f64"
+				? true
 				: false
+			: E extends Agg<"sum" | "min" | "max", infer O extends AnyVar>
+				? NumericVarOk<O>
+				: E extends Agg<"pack", infer V extends AnyVar>
+					? IntervalVarOk<V>
+					: E extends AnyComputeExpr
+						? true
+						: false
 
 type CheckFind<F extends FindShape> = {
 	readonly [K in keyof F]: FindEntryOk<F[K]> extends true ? F[K] : never
@@ -72,11 +85,13 @@ type FindValue<E> = E extends AnyVar
 	? Infer<E["field"]>
 	: E extends CountAgg
 		? bigint
-		: E extends Agg<"sum" | "min" | "max", infer O extends AnyVar>
+		: E extends Agg<"sum" | "mean" | "min" | "max", infer O extends AnyVar>
 			? Infer<O["field"]>
 			: E extends Agg<"pack", infer V extends AnyVar>
 				? Infer<V["field"]>
-				: never
+				: E extends ComputeExpr<infer K extends ScalarKind>
+					? ComputeValue<K>
+					: never
 
 type RowOfFind<F extends FindShape> = { readonly [K in keyof F]: FindValue<F[K]> }
 
@@ -86,8 +101,12 @@ type RowOfFind<F extends FindShape> = { readonly [K in keyof F]: FindValue<F[K]>
  * signature an interior join pairs against (`F` is variable-only there).
  */
 type HeadRecordOf<Classes extends SchemaClasses, F extends FindShape> = {
-	readonly [K in keyof F]: F[K] extends AnyVar ? MintSlotOf<Classes, F[K]> : never
+	readonly [K in keyof F]: F[K] extends AnyVar
+		? MintSlotOf<Classes, F[K]>
+		: F[K] extends AnyComputeExpr
+			? { readonly field: AnyField; readonly class: undefined }
+			: never
 }
 
 export type { Agg, CheckFind, CheckRecFind, FindEntry, FindShape, HeadRecordOf, RowOfFind }
-export { count, max, min, pack, sum }
+export { count, max, mean, min, pack, sum }