@bjornpagen/bumbledb 0.1.0

package/dist/statements.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dependency statements as typed values (`docs/architecture/30-dependencies.md`
+ * owns the semantics; `docs/architecture/70-api.md` the surface): the FD key
+ * form, conditional containment, the bidirectional `==` abbreviation, and
+ * the cardinality window. A statement value is opaque and inert — no
+ * methods, no fluent continuation: a fact about the theory, not a builder.
+ */
+import { phantom } from "#brand.ts";
+import type { Count } from "#count.ts";
+import { type AnyFace, type FaceData, type SameArity } from "#face.ts";
+import type { AnyRelation, RelationFields } from "#relation.ts";
+import { type WindowSpec } from "#spec.ts";
+/** One statement's runtime description, tagged by form. */
+type StatementData = {
+    readonly kind: "key";
+    readonly owner: AnyRelation;
+    readonly projection: readonly string[];
+} | {
+    readonly kind: "containment";
+    readonly source: FaceData;
+    readonly target: FaceData;
+    readonly bidirectional: boolean;
+} | {
+    readonly kind: "window";
+    readonly target: FaceData;
+    readonly window: WindowSpec;
+    readonly source: FaceData;
+};
+/** An opaque statement value — what `schema()` assembles into a theory. */
+interface Statement {
+    readonly data: StatementData;
+}
+/**
+ * A `key()` statement as a TYPED value: the statement plus a phantom
+ * carrying its owner and projection tuple — what the key-statement-selected
+ * `get(relation, keyStatement, key)` overload types its key object by
+ * (`docs/architecture/70-api.md` § the freeze, the multi-key typed get).
+ * Structurally still a plain {@link Statement}; the phantom is never present
+ * at runtime.
+ */
+interface KeyStatement<R extends AnyRelation, Projection extends readonly string[]> extends Statement {
+    readonly [phantom]?: {
+        readonly owner: R;
+        readonly projection: Projection;
+    };
+}
+/**
+ * `R(X) -> R` — the FD key form, composite keys as tuples. No selection
+ * parameter exists (the FD-with-selection shape is unrepresentable, as in
+ * the grammar), and only ordinary relations are accepted: a closed
+ * relation's key `R(id) -> R` is materialized by the engine, so an
+ * explicit one would only ever be a duplicate. The projection tuple is
+ * carried in the returned value's type ({@link KeyStatement}), so keyed
+ * point reads through THIS statement are typed field-for-field.
+ */
+declare function key<R extends AnyRelation, const Projection extends readonly [keyof RelationFields<R> & string, ...(keyof RelationFields<R> & string)[]]>(relation: R, fields: Projection): KeyStatement<R, Projection>;
+/**
+ * `A(X|φ) <= B(Y|ψ)` — conditional inclusion, source left. The target
+ * side must resolve a declared key of B — DELIBERATELY judged by the
+ * engine at `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
+ * Arity mismatch between the two faces is a type error ({@link SameArity}).
+ */
+declare function contained<A extends AnyFace, B extends AnyFace>(source: A, target: B & SameArity<A, B>): Statement;
+/**
+ * `A(X|φ) == B(Y|ψ)` — the bidirectional abbreviation, one utterance. It
+ * lowers to the two adjacent containments in the `A <= B` first order
+ * (macro parity) and renders as `==` once, in the written orientation.
+ */
+declare function mirrors<A extends AnyFace, B extends AnyFace>(source: A, target: B & SameArity<A, B>): Statement;
+/**
+ * `B(Y|ψ) <={window} A(X|φ)` — the cardinality window. READ CAREFULLY: the
+ * LEFT face is the window's TARGET, the per-group parent (B-family,
+ * target-left — macro parity), and the RIGHT face is the counted source.
+ * `window(on(Holder, "id"), atMost(3n), on(Account, "holder"))` says: each
+ * Holder id groups at most three Account rows by holder.
+ */
+declare function window<B extends AnyFace, A extends AnyFace>(target: B, count: Count, source: A & SameArity<B, A>): Statement;
+/**
+ * Renders one statement in the CANONICAL macro spelling
+ * (`docs/architecture/70-api.md`; the engine's `schema/render.rs` emits the
+ * same shapes for violations) — `Account(id) -> Account`,
+ * `Account(holder) <= Holder(id)`,
+ * `Account(id | kind == Savings) == SavingsTerms(account)`,
+ * `Holder(id) <={0..3} Account(holder)` — so TS-side errors and
+ * engine-side diagnostics read identically. A renderer, never a parser:
+ * strings are output-only.
+ */
+declare function renderStatement(statement: Statement): string;
+export type { KeyStatement, Statement, StatementData };
+export { contained, key, mirrors, renderStatement, window };
+//# sourceMappingURL=statements.d.ts.map

package/dist/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"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"}

package/dist/statements.js

@@ -0,0 +1,101 @@
+/**
+ * Dependency statements as typed values (`docs/architecture/30-dependencies.md`
+ * owns the semantics; `docs/architecture/70-api.md` the surface): the FD key
+ * form, conditional containment, the bidirectional `==` abbreviation, and
+ * the cardinality window. A statement value is opaque and inert — no
+ * methods, no fluent continuation: a fact about the theory, not a builder.
+ */
+import * as errors from "@superbuilders/errors";
+import { phantom } from "#brand.ts";
+import { renderFace } from "#face.ts";
+import { renderWindow } from "#spec.ts";
+/**
+ * `R(X) -> R` — the FD key form, composite keys as tuples. No selection
+ * parameter exists (the FD-with-selection shape is unrepresentable, as in
+ * the grammar), and only ordinary relations are accepted: a closed
+ * relation's key `R(id) -> R` is materialized by the engine, so an
+ * explicit one would only ever be a duplicate. The projection tuple is
+ * carried in the returned value's type ({@link KeyStatement}), so keyed
+ * point reads through THIS statement are typed field-for-field.
+ */
+function key(relation, fields) {
+    if (!("fields" in relation.data)) {
+        throw errors.new(`key(${relation.name}, ...): closedness already materializes ${relation.name}(id) -> ${relation.name} — an explicit key on a closed relation is rejected as a duplicate`);
+    }
+    const data = Object.freeze({
+        kind: "key",
+        owner: relation,
+        projection: Object.freeze([...fields])
+    });
+    return Object.freeze({ data });
+}
+/**
+ * `A(X|φ) <= B(Y|ψ)` — conditional inclusion, source left. The target
+ * side must resolve a declared key of B — DELIBERATELY judged by the
+ * engine at `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
+ * Arity mismatch between the two faces is a type error ({@link SameArity}).
+ */
+function contained(source, target) {
+    const data = Object.freeze({
+        kind: "containment",
+        source: source.data,
+        target: target.data,
+        bidirectional: false
+    });
+    return Object.freeze({ data });
+}
+/**
+ * `A(X|φ) == B(Y|ψ)` — the bidirectional abbreviation, one utterance. It
+ * lowers to the two adjacent containments in the `A <= B` first order
+ * (macro parity) and renders as `==` once, in the written orientation.
+ */
+function mirrors(source, target) {
+    const data = Object.freeze({
+        kind: "containment",
+        source: source.data,
+        target: target.data,
+        bidirectional: true
+    });
+    return Object.freeze({ data });
+}
+/**
+ * `B(Y|ψ) <={window} A(X|φ)` — the cardinality window. READ CAREFULLY: the
+ * LEFT face is the window's TARGET, the per-group parent (B-family,
+ * target-left — macro parity), and the RIGHT face is the counted source.
+ * `window(on(Holder, "id"), atMost(3n), on(Account, "holder"))` says: each
+ * Holder id groups at most three Account rows by holder.
+ */
+function window(target, count, source) {
+    const data = Object.freeze({
+        kind: "window",
+        target: target.data,
+        window: count.window,
+        source: source.data
+    });
+    return Object.freeze({ data });
+}
+/**
+ * Renders one statement in the CANONICAL macro spelling
+ * (`docs/architecture/70-api.md`; the engine's `schema/render.rs` emits the
+ * same shapes for violations) — `Account(id) -> Account`,
+ * `Account(holder) <= Holder(id)`,
+ * `Account(id | kind == Savings) == SavingsTerms(account)`,
+ * `Holder(id) <={0..3} Account(holder)` — so TS-side errors and
+ * engine-side diagnostics read identically. A renderer, never a parser:
+ * strings are output-only.
+ */
+function renderStatement(statement) {
+    const data = statement.data;
+    switch (data.kind) {
+        case "key":
+            return `${data.owner.name}(${data.projection.join(", ")}) -> ${data.owner.name}`;
+        case "containment": {
+            const operator = data.bidirectional ? "==" : "<=";
+            return `${renderFace(data.source)} ${operator} ${renderFace(data.target)}`;
+        }
+        case "window":
+            return `${renderFace(data.target)} <=${renderWindow(data.window)} ${renderFace(data.source)}`;
+    }
+}
+export { contained, key, mirrors, renderStatement, window };
+//# sourceMappingURL=statements.js.map

package/dist/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@bjornpagen/bumbledb",
+  "version": "0.1.0",
+  "description": "Type-theoretic TypeScript SDK for the bumbledb embedded relational engine",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "imports": {
+    "#test/*.ts": "./test/*.ts",
+    "#*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "database",
+    "relational",
+    "datalog",
+    "embedded",
+    "type-safe",
+    "typescript"
+  ],
+  "author": "Bjorn Pagen",
+  "license": "0BSD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bjornpagen/bumbledb.git",
+    "directory": "ts"
+  },
+  "homepage": "https://github.com/bjornpagen/bumbledb#readme",
+  "dependencies": {
+    "@superbuilders/errors": "^4.0.2"
+  },
+  "optionalDependencies": {
+    "@bjornpagen/bumbledb-darwin-arm64": "0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0-beta.5",
+    "@types/node": "^26.1.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "scripts": {
+    "build": "node scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "pnpm run build && node --test test/**/*.test.ts"
+  }
+}

package/src/brand.ts

@@ -0,0 +1,82 @@
+/**
+ * Nominal branding — the TS analog of the Rust macro's host newtypes
+ * (`docs/architecture/10-data-model.md`, the nominal-safety layer). A brand
+ * is a phantom: it exists only in the type, tsc polices the wall exactly as
+ * rustc polices newtype domains, and nothing is allocated or wrapped at
+ * runtime.
+ */
+
+import * as errors from "@superbuilders/errors"
+
+/**
+ * The brand-minting guard behind {@link span} — the one nominal step, as a
+ * type guard carrying the interval's REAL invariant (`start < end`, the
+ * same check Rust's `Interval::new` runs): a value that passes IS a legal
+ * interval of any brand, exactly as a Rust newtype wraps a checked
+ * `Interval<T>` at construction.
+ */
+function isNonemptyInterval<Name extends string>(value: IntervalValue): value is Interval<Name> {
+	return value.start < value.end
+}
+
+/**
+ * The brand key. A real runtime symbol (so modules can import it without a
+ * `declare`-only lie), but no branded value ever carries the property — the
+ * brand is purely a typing device.
+ */
+const brand: unique symbol = Symbol("bumbledb.brand")
+
+/**
+ * The phantom-value key used by field values, field references, and faces
+ * to carry their value type without any runtime representation.
+ */
+const phantom: unique symbol = Symbol("bumbledb.phantom")
+
+/**
+ * A branded scalar: `T` walled off under the literal name `Name`. A
+ * `Brand<bigint, "HolderId">` is not assignable where a
+ * `Brand<bigint, "AccountId">` is expected — the Rust newtype wall,
+ * verbatim. Scalars brand as `bigint` (u64/i64), `Uint8Array` (bytes), and
+ * whole interval objects (`Interval<Name>`); `bool` and `str` take no
+ * newtype, exactly as the macro's `as` grammar refuses them.
+ */
+type Brand<T, Name extends string> = T & { readonly [brand]: Name }
+
+/**
+ * A half-open interval `[start, end)` as a plain value object. The ray is
+ * representable (`end` = the element domain's MAX_END); widths and
+ * signedness are NOT modeled here — the engine judges widths at the typed
+ * write boundary, the brand blocks cross-field assignment, and nothing
+ * else is TS's business. Interval newtypes derive no order (the Rust
+ * refusal, `docs/architecture/10-data-model.md`), so no comparators exist.
+ */
+interface IntervalValue {
+	readonly start: bigint
+	readonly end: bigint
+}
+
+/**
+ * A branded interval: the whole `{ start, end }` object walled under
+ * `Name` — the `interval<i64> as ActiveDuring` analog.
+ */
+type Interval<Name extends string> = Brand<IntervalValue, Name>
+
+/**
+ * Constructs an interval literal — the `start..end` spelling. Half-open
+ * and nonempty by construction: `start >= end` is a typed construction
+ * error (parse, don't validate — the same invariant Rust's
+ * `Interval::new` enforces at the host boundary). The default `never`
+ * brand makes a fresh literal assignable to any interval field or brand,
+ * the wrap-at-construction idiom; pass the brand explicitly
+ * (`span<"ActiveDuring">(0n, 10n)`) to pin it.
+ */
+function span<Name extends string = never>(start: bigint, end: bigint): Interval<Name> {
+	const value: IntervalValue = Object.freeze({ start, end })
+	if (!isNonemptyInterval<Name>(value)) {
+		throw errors.new(`interval is half-open and nonempty: start must be < end (got ${start}..${end})`)
+	}
+	return value
+}
+
+export type { Brand, Interval, IntervalValue }
+export { brand, phantom, span }

package/src/closed.ts

@@ -0,0 +1,228 @@
+/**
+ * Closed relations (`docs/architecture/10-data-model.md` § closed
+ * relations): a vocabulary whose extension is declared in the schema — two
+ * tiers, one function. The emission per closed relation mirrors the macro's
+ * (host-enum analog): handle CONSTANTS on the value (`Kind.Checking`, ids =
+ * declaration order), the `fromId` weld, an `id` field constructor
+ * pre-branded with the handle newtype for other relations' field blocks
+ * (`kind: Kind.id`), and payload readback (`Kind.axioms`). No fact type and
+ * no insert surface exist — closed relations are unwritable by
+ * construction: the value simply lacks the writable relation shape.
+ */
+
+import * as errors from "@superbuilders/errors"
+import type { Brand } from "#brand.ts"
+import {
+	type AnyField,
+	assertDeclarationOrderKey,
+	type ClosedIdField,
+	type ClosedRoster,
+	type FieldData,
+	type FieldValue,
+	fieldData,
+	literalOf
+} from "#fields.ts"
+import type { LiteralSpec } from "#spec.ts"
+
+/**
+ * The value-surface property names a handle may not shadow — the macro's
+ * name-collision diagnostic, here over the closed value's own properties
+ * (`relation`/`selection` are reserved so a closed value can never be
+ * mistaken for a selected relation by `on()`'s discriminant).
+ */
+const reservedHandleNames: readonly string[] = Object.freeze([
+	"name",
+	"id",
+	"data",
+	"axioms",
+	"fromId",
+	"relation",
+	"selection"
+])
+
+/**
+ * Reads one handle's axiom row, refusing absence loudly: the payload tier's
+ * overload types the record exhaustively, so a missing row is ill-typed
+ * input, and the bare tier never reaches here (it declares no columns).
+ */
+function axiomRow(
+	name: string,
+	axioms: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+	handle: string
+): Readonly<Record<string, unknown>> {
+	if (axioms === undefined) {
+		throw errors.new(`closed relation ${name}: payload columns declared without ground axioms`)
+	}
+	const row = axioms[handle]
+	if (row === undefined) {
+		throw errors.new(`closed relation ${name}: no ground axiom for handle ${handle}`)
+	}
+	return row
+}
+
+/**
+ * A payload column of a closed relation: any field constructor except a
+ * fresh-marked one (a vocabulary's rows are ground axioms, never minted).
+ */
+type PayloadField = AnyField & { readonly data: FieldData<false> }
+
+/** One declared payload column: name plus its field description. */
+interface ClosedColumn {
+	readonly name: string
+	readonly field: FieldData
+}
+
+/**
+ * One ground axiom, already lowered: the handle plus one wire literal per
+ * declared column in column-declaration order (row id = index). Lowered
+ * EAGERLY at construction so axiom literals ride the same selection-literal
+ * machine as `where()` bindings, with the same errors (the macro's rule).
+ */
+interface ClosedRow {
+	readonly handle: string
+	readonly values: readonly LiteralSpec[]
+}
+
+/** A closed relation's runtime description. */
+interface ClosedData {
+	readonly name: string
+	readonly handles: readonly string[]
+	readonly columns: readonly ClosedColumn[]
+	readonly rows: readonly ClosedRow[]
+}
+
+/** One axiom row as the host writes and reads it: column name to host value. */
+type AxiomRow<Cols> = { readonly [C in keyof Cols]: FieldValue<Cols[C]> }
+
+/**
+ * The whole axiom record: every handle exactly once, every column exactly
+ * once per row — a missing or extra axiom, column, or handle is a TYPE
+ * error (mapped over the handle tuple).
+ */
+type Axioms<Handles extends readonly string[], Cols> = {
+	readonly [H in Handles[number]]: AxiomRow<Cols>
+}
+
+/**
+ * The named surface of a closed relation value, minus the handle constants
+ * (which {@link Closed} intersects in).
+ */
+interface ClosedCore<Name extends string, Handles extends readonly string[], Cols> {
+	readonly name: Name
+	/**
+	 * The pre-branded u64 field constructor: `kind: Kind.id` in another
+	 * relation's field block is the reference through which bare handles
+	 * become legal in that relation's selections.
+	 */
+	readonly id: ClosedIdField<Name>
+	readonly data: ClosedData
+	/** Payload readback: handle to its declared column values. */
+	readonly axioms: Axioms<Handles, Cols>
+	/** The weld: declaration-order id back to its handle, or undefined beyond the roster. */
+	fromId(id: Brand<bigint, Name>): Handles[number] | undefined
+}
+
+/**
+ * A closed relation value: the core surface plus one branded constant per
+ * handle (`Kind.Checking: Brand<bigint, "Kind">`, ids = declaration order).
+ */
+type Closed<Name extends string, Handles extends readonly string[], Cols> = ClosedCore<Name, Handles, Cols> & {
+	readonly [H in Handles[number]]: Brand<bigint, Name>
+}
+
+/** Any closed relation value, whatever its roster and columns. */
+interface AnyClosed {
+	readonly name: string
+	readonly id: ClosedIdField<string>
+	readonly data: ClosedData
+	readonly axioms: Readonly<Record<string, object>>
+}
+
+/** Bare tier: `closed("Kind", ["Checking", "Savings"])` — handles only. */
+function closed<const Name extends string, const Handles extends readonly [string, ...string[]]>(
+	name: Name,
+	handles: Handles
+): Closed<Name, Handles, Record<never, never>>
+
+/**
+ * Payload tier: declared columns plus ground axioms, every handle with
+ * every column exactly once (type-enforced by {@link Axioms}).
+ */
+function closed<
+	const Name extends string,
+	const Handles extends readonly [string, ...string[]],
+	const Cols extends Record<string, PayloadField>
+>(name: Name, handles: Handles, columns: Cols, axioms: Axioms<Handles, Cols>): Closed<Name, Handles, Cols>
+
+function closed(
+	name: string,
+	handles: readonly [string, ...string[]],
+	columns?: Record<string, PayloadField>,
+	axioms?: Readonly<Record<string, Readonly<Record<string, unknown>>>>
+): unknown {
+	const seen = new Set<string>()
+	for (const handle of handles) {
+		if (seen.has(handle)) {
+			throw errors.new(`closed relation ${name}: duplicate handle ${handle}`)
+		}
+		seen.add(handle)
+		if (reservedHandleNames.includes(handle)) {
+			throw errors.new(
+				`closed relation ${name}: handle ${handle} collides with the closed value's own surface (${reservedHandleNames.join(", ")})`
+			)
+		}
+	}
+	const roster: ClosedRoster = Object.freeze({ name, handles: Object.freeze([...handles]) })
+	const cols: ClosedColumn[] = []
+	if (columns !== undefined) {
+		for (const [columnName, field] of Object.entries(columns)) {
+			assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
+			cols.push(Object.freeze({ name: columnName, field: field.data }))
+		}
+	}
+	const rows: ClosedRow[] = handles.map(function lowerRow(handle) {
+		const values = cols.map(function lowerAxiomLiteral(column) {
+			const row = axiomRow(name, axioms, handle)
+			return Object.freeze(literalOf(column.field, row[column.name]))
+		})
+		return Object.freeze({ handle, values: Object.freeze(values) })
+	})
+	const data: ClosedData = Object.freeze({
+		name,
+		handles: roster.handles,
+		columns: Object.freeze(cols),
+		rows: Object.freeze(rows)
+	})
+	const id: ClosedIdField<string> = Object.freeze({
+		data: fieldData({ kind: "u64" }, name, false, roster)
+	})
+	/**
+	 * Handle names are arbitrary identifiers, so rows and constants are
+	 * minted with OWN-property definition, never assignment: a handle named
+	 * "__proto__" would otherwise ride the Object.prototype accessor —
+	 * silently swapping the record's prototype instead of creating the row,
+	 * and no-oping the constant (a primitive through the setter) — minting a
+	 * value whose type claims Brand<bigint, Name> but reads back an object.
+	 */
+	const axiomsOut: Record<string, object> = {}
+	for (const handle of handles) {
+		const row = axioms === undefined ? Object.freeze({}) : Object.freeze({ ...axiomRow(name, axioms, handle) })
+		Object.defineProperty(axiomsOut, handle, { value: row, enumerable: true })
+	}
+	const value: Record<string, unknown> = {
+		name,
+		id,
+		data,
+		axioms: Object.freeze(axiomsOut),
+		fromId(idValue: bigint): string | undefined {
+			return roster.handles[Number(idValue)]
+		}
+	}
+	handles.forEach(function mintHandleConstant(handle, index) {
+		Object.defineProperty(value, handle, { value: BigInt(index), enumerable: true })
+	})
+	return Object.freeze(value)
+}
+
+export type { AnyClosed, AxiomRow, Axioms, Closed, ClosedColumn, ClosedCore, ClosedData, ClosedRow, PayloadField }
+export { closed }