@bjornpagen/bumbledb 1.1.0 → 1.2.1

package/src/schema.ts

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util"
 import { AuthoringError, SdkInvariantError } from "#errors.ts"
 /**
  * `schema` — assembles relations and statements into a theory value (the
@@ -17,13 +18,15 @@ import { AuthoringError, SdkInvariantError } from "#errors.ts"
  */
 
 import type { AnyClosed } from "#closed.ts"
-import { isClosedMember, sealedFieldOf } from "#closed.ts"
-import type { FaceData } from "#face.ts"
+import { isClosedMember, memberDescriptor, membersAgree, sealedFieldOf } from "#closed.ts"
+import type { AnyFace } from "#face.ts"
 import { assertDeclarationOrderKey, assertDeclarationRecord, rosterOf } from "#fields.ts"
+import { descriptorCache, isImmutable } from "#immutable.ts"
 import { type ClassesOf, classesComplete, computeClasses, type LawfulStatements, type SchemaClasses } from "#law.ts"
 import type { AnyRelation } from "#relation.ts"
 import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
-import { isStatement, renderStatement, type Statement } from "#statements.ts"
+import { renderStatement, type Statement, statementDescriptor } from "#statements.ts"
+import { arrayValue, recordValue } from "#values.ts"
 
 interface ImpliedKeys {
 	readonly rendered: ReadonlySet<string>
@@ -54,7 +57,7 @@ function collectImplied(name: string, relations: SchemaRelations): ImpliedKeys {
 }
 
 function statementOwners(statement: Statement): readonly SchemaRelation[] {
-	const data = statement.data
+	const data = statement
 	if (data.kind === "key") {
 		return [data.owner]
 	}
@@ -69,9 +72,9 @@ function verifyMembership(name: string, relations: SchemaRelations, statement: S
 				message: `schema ${name}: relation ${owner.name} is not declared in this schema — ${rendered}`
 			})
 		}
-		if (member !== owner) {
+		if (!membersAgree(member, owner)) {
 			throw new AuthoringError({
-				message: `schema ${name}: statement references a different relation value named ${owner.name} than the one this schema declares — ${rendered}`
+				message: `schema ${name}: statement references a different relation declaration named ${owner.name} than the one this schema declares — ${rendered}`
 			})
 		}
 	}
@@ -86,7 +89,7 @@ function bindingLiterals(set: LiteralSetSpec): readonly LiteralSpec[] {
 
 function verifyBindingHandles(
 	name: string,
-	face: FaceData,
+	face: AnyFace,
 	binding: { readonly field: string; readonly set: LiteralSetSpec },
 	rendered: string
 ): void {
@@ -109,7 +112,7 @@ function verifyBindingHandles(
 }
 
 function verifyHandles(name: string, statement: Statement, rendered: string): void {
-	const data = statement.data
+	const data = statement
 	if (data.kind === "key") {
 		return
 	}
@@ -122,11 +125,11 @@ function verifyHandles(name: string, statement: Statement, rendered: string): vo
 
 function closedTargetOf(statements: readonly Statement[], owner: string, field: string): string | undefined {
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind !== "containment" && data.kind !== "mirrors") {
 			continue
 		}
-		const pairs: Array<readonly [FaceData, FaceData]> = [[data.source, data.target]]
+		const pairs: Array<readonly [AnyFace, AnyFace]> = [[data.source, data.target]]
 		if (data.kind === "mirrors") {
 			pairs.push([data.target, data.source])
 		}
@@ -148,7 +151,7 @@ function closedTargetOf(statements: readonly Statement[], owner: string, field:
 
 function verifyClosedReferences(name: string, statements: readonly Statement[]): void {
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind === "key") {
 			continue
 		}
@@ -164,7 +167,7 @@ function verifyClosedReferences(name: string, statements: readonly Statement[]):
 function verifyClosedReferenceBinding(
 	name: string,
 	statements: readonly Statement[],
-	face: FaceData,
+	face: AnyFace,
 	binding: { readonly field: string; readonly set: LiteralSetSpec },
 	rendered: string
 ): void {
@@ -213,7 +216,7 @@ function verifyTargetKeys(
 ): void {
 	const declared = new Map<string, Array<readonly string[]>>()
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind !== "key") {
 			continue
 		}
@@ -225,7 +228,7 @@ function verifyTargetKeys(
 		}
 	}
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind === "key") {
 			continue
 		}
@@ -251,7 +254,7 @@ function verifyTargetKeys(
  */
 function verifyTargetKeyFace(
 	name: string,
-	face: FaceData,
+	face: AnyFace,
 	implied: ReadonlyMap<string, ReadonlyArray<readonly string[]>>,
 	declared: ReadonlyMap<string, ReadonlyArray<readonly string[]>>,
 	rendered: string
@@ -310,25 +313,92 @@ interface Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = S
 
 type AnySchema = Schema<SchemaRelations>
 
+/**
+ * Logical schema equivalence, including the ordered native ordinals and
+ * host decoding domains. Schema display names do not change the theory.
+ * A database/snapshot still has its own resource identity and lifetime.
+ */
+function schemasAgree(leftInput: AnySchema, rightInput: AnySchema): boolean {
+	const left = schemaDescriptor(leftInput)
+	const right = schemaDescriptor(rightInput)
+	if (left === right) return true
+	const cacheable = isImmutable(left) && isImmutable(right)
+	const cached = schemaComparisons.get(left)?.get(right)
+	if (cacheable && cached !== undefined) return cached
+	const names = Object.keys(left.relations)
+	const otherNames = Object.keys(right.relations)
+	const equal =
+		names.length === otherNames.length &&
+		names.every((name, index) => {
+			const member = right.relations[name]
+			return name === otherNames[index] && member !== undefined && membersAgree(left.relations[name], member)
+		}) &&
+		isDeepStrictEqual(left.statements, right.statements) &&
+		isDeepStrictEqual(left.classes, right.classes)
+	if (cacheable) {
+		let comparisons = schemaComparisons.get(left)
+		if (comparisons === undefined) {
+			comparisons = new WeakMap()
+			schemaComparisons.set(left, comparisons)
+		}
+		comparisons.set(right, equal)
+	}
+	return equal
+}
+
+const schemaComparisons = new WeakMap<AnySchema, WeakMap<AnySchema, boolean>>()
+
+function schemaDescriptor<S extends AnySchema>(input: S): S
+function schemaDescriptor(input: unknown): AnySchema
+function schemaDescriptor(input: unknown): AnySchema {
+	return checkedSchema(input)
+}
+
+const checkedSchema = descriptorCache((input): AnySchema => {
+	const raw = recordValue("schema", input, ["name", "relations", "statements", "classes"])
+	if (typeof raw.name !== "string") throw new AuthoringError({ message: "schema: expected a name" })
+	const relations = ownRelations(raw.name, raw.relations)
+	const statements = arrayValue("schema statements", raw.statements, (_, statement) => statementDescriptor(statement))
+	const result = schema(raw.name, relations, statements)
+	const classes = recordValue("schema classes", raw.classes, Object.keys(result.classes))
+	for (const [name, fields] of Object.entries(result.classes)) {
+		const supplied = recordValue(`schema classes.${name}`, classes[name], Object.keys(fields))
+		for (const [field, value] of Object.entries(fields)) {
+			if (supplied[field] !== value)
+				throw new AuthoringError({ message: `schema classes.${name}.${field}: incorrect class` })
+		}
+	}
+	return result
+})
+
 type EvaluatedClasses<C extends SchemaClasses> = C extends SchemaClasses
 	? { readonly [N in keyof C]: { readonly [F in keyof C[N]]: C[N][F] } }
 	: never
 
+function ownRelations<R extends SchemaRelations>(name: string, input: R): R
+function ownRelations(name: string, input: unknown): SchemaRelations
+function ownRelations(name: string, input: unknown): SchemaRelations {
+	if (typeof input !== "object" || input === null)
+		throw new AuthoringError({ message: `schema ${name}: expected relations` })
+	assertDeclarationRecord(`schema ${name} relations`, input)
+	return Object.freeze(
+		Object.fromEntries(Object.entries(input).map(([name, member]) => [name, memberDescriptor(member)]))
+	)
+}
+
 function schema<const Rels extends SchemaRelations, const Stmts extends readonly Statement[]>(
 	name: string,
 	relations: Rels,
 	statements: Stmts & LawfulStatements<Rels, Stmts>
 ): Schema<Rels, EvaluatedClasses<ClassesOf<Rels, Stmts>>> {
-	const implied = collectImplied(name, relations)
+	assertDeclarationOrderKey("schema", name)
+	const ownedRelations = ownRelations(name, relations)
+	const ownedStatements = arrayValue("schema statements", statements, (_, statement) => statementDescriptor(statement))
+	const implied = collectImplied(name, ownedRelations)
 	const seen = new Set<string>()
-	for (const statement of statements) {
-		if (!isStatement(statement)) {
-			throw new AuthoringError({
-				message: `schema ${name}: a statement is minted only by key/contained/mirrors/capacity — a structural literal skips the construction-time arity and roster walls`
-			})
-		}
+	for (const statement of ownedStatements) {
 		const rendered = renderStatement(statement)
-		verifyMembership(name, relations, statement, rendered)
+		verifyMembership(name, ownedRelations, statement, rendered)
 		if (implied.rendered.has(rendered)) {
 			throw new AuthoringError({
 				message: `schema ${name}: ${rendered} is redundant here (closedness already implies it) — and rejected as a duplicate`
@@ -340,14 +410,14 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 		seen.add(rendered)
 		verifyHandles(name, statement, rendered)
 	}
-	verifyClosedReferences(name, statements)
-	verifyTargetKeys(name, statements, implied.roster)
-	const classes = computeClasses(name, relations, statements)
-	if (!classesComplete<EvaluatedClasses<ClassesOf<Rels, Stmts>>>(classes, relations)) {
+	verifyClosedReferences(name, ownedStatements)
+	verifyTargetKeys(name, ownedStatements, implied.roster)
+	const classes = computeClasses(name, ownedRelations, ownedStatements)
+	if (!classesComplete<EvaluatedClasses<ClassesOf<Rels, Stmts>>>(classes, ownedRelations)) {
 		throw new SdkInvariantError({ message: `schema ${name}: class-map construction incomplete` })
 	}
-	return Object.freeze({ name, relations, statements: Object.freeze([...statements]), classes })
+	return Object.freeze({ name, relations: ownedRelations, statements: Object.freeze(ownedStatements), classes })
 }
 
 export type { AnySchema, Schema, SchemaRelation, SchemaRelations }
-export { schema }
+export { schema, schemaDescriptor, schemasAgree }

package/src/selection.ts

@@ -0,0 +1,124 @@
+import { type AnyClosed, memberDescriptor, sealedFieldOf, sealedFieldsOf } from "#closed.ts"
+import { AuthoringError } from "#errors.ts"
+import { type AnyField, assertDeclarationRecord, type ClosedIdField, type Infer, literalOf } from "#fields.ts"
+import type { AnyRelation, RelationFields } from "#relation.ts"
+import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
+import { arrayValue, recordValue } from "#values.ts"
+
+type Selectable = AnyRelation | AnyClosed
+type FieldsOf<R extends Selectable> = R extends AnyRelation
+	? RelationFields<R>
+	: R extends AnyClosed
+		? { readonly id: ClosedIdField<R["name"], R["handles"]> } & R["columns"]
+		: never
+type SelectionInput<R extends Selectable> = {
+	readonly [K in keyof FieldsOf<R>]?: Infer<FieldsOf<R>[K]> | readonly Infer<FieldsOf<R>[K]>[]
+}
+interface SelectionBinding {
+	readonly field: string
+	readonly set: LiteralSetSpec
+}
+interface Selected<R extends Selectable = Selectable> {
+	readonly relation: R
+	readonly selection: readonly SelectionBinding[]
+}
+type AnySelected = Selected
+
+/** Checked logical literals use the same field interpreter as fact values. */
+function selectionLiteral(field: AnyField, input: unknown): LiteralSpec {
+	const raw = recordValue("selection literal", input, "closed" in field ? ["kind", "handle"] : ["kind", "value"])
+	if ("closed" in field) {
+		if (raw.kind !== "handle") throw new AuthoringError({ message: "closed selection requires a handle literal" })
+		return Object.freeze(literalOf(field, raw.handle))
+	}
+	if (raw.kind !== "value") throw new AuthoringError({ message: "selection requires a value literal" })
+	const value = recordValue(
+		"selection value",
+		raw.value,
+		field.kind === "interval" ? ["kind", "start", "end"] : ["kind", "value"]
+	)
+	let kind: string = field.kind
+	if (field.kind === "str") kind = "string"
+	if (field.kind === "bytes") kind = "fixedBytes"
+	if (field.kind === "interval") kind = { u64: "intervalU64", i64: "intervalI64", f64: "intervalF64" }[field.element]
+	if (value.kind !== kind) throw new AuthoringError({ message: `selection requires the ${kind} value tag` })
+	const literal = literalOf(field, field.kind === "interval" ? { start: value.start, end: value.end } : value.value)
+	if (literal.kind === "value") Object.freeze(literal.value)
+	return Object.freeze(literal)
+}
+
+function selectionBindings(owner: Selectable, input: unknown): readonly SelectionBinding[] {
+	if (!Array.isArray(input)) throw new AuthoringError({ message: "selection: expected bindings" })
+	const selected = new Set<string>()
+	return Object.freeze(
+		arrayValue("selection", input, (_, raw) => {
+			const binding = recordValue("selection binding", raw, ["field", "set"])
+			if (typeof binding.field !== "string") throw new AuthoringError({ message: "selection: expected a field name" })
+			const field = sealedFieldOf(owner, binding.field)
+			if (field === undefined)
+				throw new AuthoringError({ message: `relation ${owner.name} has no field ${binding.field}` })
+			if (selected.has(binding.field)) throw new AuthoringError({ message: "selection: duplicate field" })
+			selected.add(binding.field)
+			const set = binding.set
+			if (typeof set !== "object" || set === null || !("kind" in set))
+				throw new AuthoringError({ message: "literal set: expected a descriptor" })
+			assertDeclarationRecord("literal set", set)
+			if (set.kind === "one") {
+				const rawSet = recordValue("literal set", set, ["kind", "literal"])
+				return Object.freeze({
+					field: binding.field,
+					set: Object.freeze({ kind: "one" as const, literal: selectionLiteral(field, rawSet.literal) })
+				})
+			}
+			if (set.kind !== "many") throw new AuthoringError({ message: "literal set: unknown kind" })
+			const rawSet = recordValue("literal set", set, ["kind", "literals"])
+			if (!Array.isArray(rawSet.literals) || rawSet.literals.length < 2)
+				throw new AuthoringError({ message: "literal set: expected at least two distinct literals" })
+			const literals = arrayValue("selection literals", rawSet.literals, (_, literal) =>
+				selectionLiteral(field, literal)
+			)
+			if (new Set(literals.map(renderLiteral)).size !== literals.length)
+				throw new AuthoringError({ message: "literal set: duplicate literal" })
+			return Object.freeze({
+				field: binding.field,
+				set: Object.freeze({ kind: "many" as const, literals: Object.freeze(literals) })
+			})
+		})
+	)
+}
+
+function select<R extends Selectable>(relation: R, input: SelectionInput<R>): Selected<R> {
+	const owner = memberDescriptor(relation)
+	assertDeclarationRecord(`relation ${owner.name} selection`, input)
+	const fields = sealedFieldsOf(owner)
+	const selection: SelectionBinding[] = Object.entries(input).map(([name, entry]) => {
+		const field = fields.find((field) => field.name === name)?.field
+		if (field === undefined) throw new AuthoringError({ message: `relation ${owner.name} has no field ${name}` })
+		if (!Array.isArray(entry)) return { field: name, set: { kind: "one", literal: literalOf(field, entry) } }
+		const context = `relation ${owner.name}.${name}`
+		if (entry.length < 2)
+			throw new AuthoringError({
+				message:
+					entry.length === 0
+						? `${context}: an empty literal set selects nothing — write the selection you mean`
+						: `${context}: a one-element literal set is the bare literal respelled — write the literal`
+			})
+		const literals = arrayValue(context, entry, (_, value) => literalOf(field, value))
+		const seen = new Set<string>()
+		for (const literal of literals) {
+			const rendered = renderLiteral(literal)
+			if (seen.has(rendered))
+				throw new AuthoringError({ message: `${context}: the literal set spells ${rendered} twice — write it once` })
+			seen.add(rendered)
+		}
+		return { field: name, set: { kind: "many", literals } }
+	})
+	if (selection.length === 0)
+		throw new AuthoringError({
+			message: `relation ${owner.name}: an empty selection is the bare relation respelled — pass the relation itself`
+		})
+	return Object.freeze({ relation: owner, selection: selectionBindings(owner, selection) })
+}
+
+export type { AnySelected, FieldsOf, Selectable, Selected, SelectionBinding, SelectionInput }
+export { select, selectionBindings, selectionLiteral }

package/src/shape.ts

@@ -1,30 +1,36 @@
 import type { Query } from "#query/lower.ts"
-import type { ParamsRecord } from "#query/scope.ts"
+import type { inferred, ParamsRecord } from "#query/scope.ts"
 /**
  * Shared derived types: `S` is a
  * declared core schema value's type, `Rel<S>` its ordinary (writable)
- * relations, `Fact<R>` the inferred row object, `Key<R>` the primary-key
- * object accepted by `QueryReader.get`, and `QueryTemplate<S, P, A>` the
+ * relations, `Fact<R>` the inferred row object, `Key<K>` the exact value
+ * of a declared key accepted by `QueryReader.get`, and `QueryTemplate<S, P, A>` the
  * immutable schema-bound logical query template. All are derived from the
  * existing typed descriptors — no second hand-maintained roster.
  */
 import type { AnyRelation, Fact } from "#relation.ts"
 import type { AnySchema } from "#schema.ts"
+import type { KeyStatement } from "#statements.ts"
 
 /** The ordinary relations of a schema (closed vocabularies are ground axioms, never ingestion targets). */
 type Rel<S extends AnySchema> = Extract<S["relations"][keyof S["relations"]], AnyRelation>
 
 /**
- * The primary-key object of a relation: the fields of its FIRST
- * materialized key statement (a closed relation's synthetic `(id)`,
- * otherwise the first declared `key`). The exact projection is a schema
- * fact, verified at execution against the compiled tables; the type admits
- * any subset of the fact's own fields and the runtime refuses a mismatch
- * with a typed `DbError` before any native work.
+ * The structural value of one declared key, derived from its owner's
+ * fields and its exact projection. Every selected field is required.
  */
-type Key<R extends AnyRelation> = Partial<Fact<R>>
+type Key<K extends KeyStatement<AnyRelation, readonly string[]>> = Pick<
+	Fact<K["owner"]>,
+	Extract<K["projection"][number], keyof Fact<K["owner"]>>
+>
 
-/** Immutable typed query template. */
-type QueryTemplate<S extends AnySchema, P extends ParamsRecord, A> = Query<S["relations"], A, P>
+/** The immutable executable view of a query. Readers consume its schema/data
+ * and inferred result/parameters, not the author's rule-building methods.
+ * Runtime schema identity remains authoritative for dynamically built schemas.
+ */
+type QueryTemplate<S extends AnySchema, P extends ParamsRecord, A> = Pick<
+	Query<S["relations"], A, P>,
+	"schema" | "data" | typeof inferred
+>
 
 export type { Key, QueryTemplate, Rel }