@xwxfox/foxdb 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,1463 @@
+import { TObject as TObject2, TArray, TSchema, TProperties, Static } from "typebox";
+import { TObject, TString, TNumber, TInteger, TBoolean, TLiteral } from "typebox";
+/** @category Schema */
+type TScalarSchema = TString | TNumber | TInteger | TBoolean | TLiteral<string> | TLiteral<number> | TLiteral<boolean>;
+/**
+* typed reference to a scalar column
+* @category Schema
+*/
+interface ColumnRef<
+	N extends string = string,
+	S extends TScalarSchema = TScalarSchema
+> {
+	readonly _tag: "ColumnRef";
+	readonly name: N;
+	readonly schema: S;
+}
+/**
+* map of scalar columns to their typed refs
+* @category Schema
+*/
+type ColumnRefs<T extends TObject> = { readonly [K in keyof T["properties"] as T["properties"][K] extends TScalarSchema ? K : never] : T["properties"][K] extends TScalarSchema ? ColumnRef<K & string, T["properties"][K]> : never };
+/**
+* foxdb/src/typed-relation.ts
+* Runtime + compile-time representation of a single relation.
+* @category Relations
+*/
+interface TypedRelation<
+	O extends string = string,
+	F extends string = string,
+	T extends string = string,
+	TF extends string = string,
+	K extends "scalar" | "subTable" = "scalar" | "subTable",
+	A extends string | undefined = string | undefined
+> {
+	ownerTable: O;
+	ownerField: F;
+	targetTable: T;
+	targetField: TF;
+	kind: K;
+	as: A;
+}
+import { Database, SQLQueryBindings } from "bun:sqlite";
+/**
+* prepared sqlite statement
+* @category Database
+*/
+interface BunStatement {
+	run(...params: SQLQueryBindings[]): {
+		changes: number;
+		lastInsertRowid: number | bigint;
+	};
+	all(...params: SQLQueryBindings[]): unknown[];
+	get(...params: SQLQueryBindings[]): unknown;
+	finalize(): void;
+}
+/** @category Database */
+interface DatabaseOptions {
+	/** Path to the SQLite file. Defaults to ":memory:" */
+	path?: string;
+	/**
+	* Cache size in pages (each page is typically 4 KB).
+	* Negative value = kilobytes. Defaults to -64000 (~64 MB).
+	*/
+	cacheSize?: number;
+	/**
+	* Busy timeout in milliseconds while waiting for a write lock.
+	* Defaults to 5000.
+	*/
+	busyTimeout?: number;
+	/**
+	* PRAGMA synchronous level.
+	* "OFF" | "NORMAL" | "FULL" | "EXTRA". Defaults to "NORMAL".
+	* NORMAL is safe with WAL and gives the best perf/safety trade-off.
+	*/
+	synchronous?: "OFF" | "NORMAL" | "FULL" | "EXTRA";
+	/** PRAGMA mmap_size in bytes. 0 disables. Defaults to 256 MB. */
+	mmapSize?: number;
+}
+/**
+* sqlite database with statement caching and pragma tuning
+* @category Database
+*/
+declare class BunDatabase {
+	/** underlying bun:sqlite database */
+	readonly db: Database;
+	constructor(opts?: DatabaseOptions);
+	/** execute ddl (create table, index, etc) */
+	exec(sql: string): void;
+	/** run a block inside a transaction */
+	transaction<T>(fn: () => T): T;
+	/** close the database and finalize cached statements */
+	close(): void;
+	private static readonly _MAX_CACHE_SIZE;
+	private readonly _stmtCache;
+	/** get or compile a prepared statement */
+	prepare(sql: string): BunStatement;
+	/** clear the statement cache */
+	clearCache(): void;
+}
+/**
+* @internal
+* @category Advanced
+*/
+type ScalarProperties<P extends TProperties> = { [K in keyof P as P[K] extends TArray<infer _> ? never : K] : P[K] };
+/**
+* @internal
+* @category Advanced
+*/
+type ArrayOfObjectProperties<P extends TProperties> = { [K in keyof P as P[K] extends TArray<TObject2> ? K : never] : P[K] extends TArray<infer Item> ? Item : never };
+/**
+* column names that are scalar (not arrays or nested objects)
+* @category Query Types
+*/
+type ScalarKeys<T extends TObject2> = keyof ScalarProperties<T["properties"]> & string;
+/**
+* @internal
+* @category Query Types
+*/
+type SubTableKeys<T extends TObject2> = keyof ArrayOfObjectProperties<T["properties"]> & string;
+/**
+* @internal
+* @category Advanced
+*/
+type SubTableScalarPath<T extends TObject2> = { [K in SubTableKeys<T>] : T["properties"][K] extends TArray<infer Item> ? Item extends TObject2 ? `${K}.${ScalarKeys<Item>}` : never : never }[SubTableKeys<T>];
+/**
+* @internal
+* @category Advanced
+*/
+type ScalarPath<T extends TObject2> = ScalarKeys<T> | SubTableScalarPath<T>;
+/**
+* the typescript type that matches a typebox schema
+* @category Query Types
+*/
+type Infer<T extends TSchema> = Static<T>;
+/** @category Query Types */
+type ScalarFilter<V> = V extends string ? {
+	eq: V;
+} | {
+	ne: V;
+} | {
+	like: string;
+} | {
+	in: V[];
+} | {
+	notIn: V[];
+} | {
+	isNull: true;
+} | {
+	isNotNull: true;
+} : V extends number | bigint ? {
+	eq: V;
+} | {
+	ne: V;
+} | {
+	gt: V;
+} | {
+	gte: V;
+} | {
+	lt: V;
+} | {
+	lte: V;
+} | {
+	between: [V, V];
+} | {
+	in: V[];
+} | {
+	isNull: true;
+} | {
+	isNotNull: true;
+} : V extends boolean ? {
+	eq: V;
+} | {
+	isNull: true;
+} | {
+	isNotNull: true;
+} : {
+	isNull: true;
+} | {
+	isNotNull: true;
+};
+/**
+* Where filters for queries - only scalar columns are filterable.
+*
+* @example
+* ```ts
+* // String filters
+* orm.users.findMany({ where: { name: { like: "%alice%" } } });
+* orm.users.findMany({ where: { email: { in: ["a@x.com", "b@x.com"] } } });
+*
+* // Number filters
+* orm.users.findMany({ where: { age: { gte: 18, lte: 65 } } });
+* orm.products.findMany({ where: { price: { between: [10, 100] } } });
+*
+* // Boolean / null filters
+* orm.users.findMany({ where: { active: { eq: true } } });
+* orm.users.findMany({ where: { deletedAt: { isNull: true } } });
+* ```
+* @category Query Types
+* @category Query Types
+*/
+type WhereClause<T extends TObject2> = { [K in ScalarKeys<T>]? : ScalarFilter<Static<T["properties"][K]>> };
+/**
+* sort direction for queries
+* @category Query Types
+*/
+type OrderByClause<T extends TObject2> = {
+	column: ScalarKeys<T>;
+	direction?: "ASC" | "DESC";
+};
+/**
+* @internal
+* @category Advanced
+*/
+interface PaginationOptions {
+	limit?: number;
+	offset?: number;
+}
+/**
+* Options for `findMany`, `findPage`, and `findOne`.
+*
+* @example
+* ```ts
+* orm.users.findMany({
+*   where: { age: { gte: 18 } },
+*   orderBy: { column: "name", direction: "ASC" },
+*   limit: 10,
+*   offset: 0,
+* });
+*
+* // Multiple orderBy clauses
+* orm.users.findMany({
+*   orderBy: [
+*     { column: "status", direction: "DESC" },
+*     { column: "createdAt", direction: "ASC" },
+*   ],
+* });
+*
+* // Include sub-tables
+* orm.orders.findMany({ include: ["lineItems"] });
+* ```
+* @category Query Types
+* @category Query Types
+*/
+interface FindOptions<T extends TObject2> extends PaginationOptions {
+	where?: WhereClause<T>;
+	orderBy?: OrderByClause<T> | OrderByClause<T>[];
+	include?: SubTableKeys<T>[];
+}
+/**
+* full record to insert
+* @category Query Types
+*/
+type InsertData<T extends TObject2> = Infer<T>;
+/**
+* update payload - must include the primary key
+* @category Query Types
+*/
+type UpdateData<
+	T extends TObject2,
+	PK extends ScalarKeys<T>
+> = Pick<Infer<T>, PK> & Partial<Omit<Infer<T>, PK>>;
+/**
+* index on one or more columns
+* @category Schema
+*/
+interface IndexDefinition {
+	name?: string;
+	columns: ColumnRef<string, TScalarSchema>[];
+	unique?: boolean;
+}
+/**
+* timestamp configuration for a table
+* @category Schema
+*/
+type TimestampConfig = true | false | {
+	createdAt?: string;
+	updatedAt?: string;
+} | undefined;
+/**
+* @internal
+* @category Schema
+*/
+type TimestampShape<T extends TimestampConfig> = true extends T ? {
+	createdAt: number;
+	updatedAt: number;
+} : [T] extends [{
+	createdAt?: infer C;
+	updatedAt?: infer U;
+}] ? (C extends string ? { [K in C] : number } : {}) & (U extends string ? { [K in U] : number } : {}) : {};
+/**
+* A database row with optional timestamps and materialized relations.
+*
+* @example
+* ```ts
+* // Without relations
+* type User = Entity<{ id: string; name: string }>;
+* // → { id: string; name: string }
+*
+* // With timestamps
+* type UserWithTS = Entity<{ id: string }, never, { createdAt: number }>;
+* // → { id: string; createdAt: number }
+*
+* // With relations
+* type UserWithRels = Entity<{ id: string }, { posts: Post[] }>;
+* // → { id: string; materialize(): { posts: Post[] } }
+* ```
+* @category Query Types
+* @category Query Types
+*/
+type Entity<
+	T,
+	Mat = never,
+	TS = {}
+> = [Mat] extends [never] ? T & TS : T & TS & {
+	materialize(): Mat;
+};
+/**
+* table descriptor passed to createORM
+* @category Schema
+*/
+interface TableConfig<
+	T extends TObject2 = TObject2,
+	PK extends string = string,
+	TS extends TimestampConfig = undefined
+> {
+	schema: T;
+	primaryKey: ColumnRef<PK>;
+	indexes?: IndexDefinition[];
+	subTables?: Partial<Record<string, {
+		indexes?: IndexDefinition[];
+	}>>;
+	timestamps?: TS;
+}
+/**
+* read-only metadata about the current database schema
+* @category Setup
+*/
+interface MetaAccessors {
+	schemaHash: string | null;
+	schemaJSON: string | null;
+	tables: string[] | null;
+	relations: unknown[] | null;
+	version: string | null;
+}
+/**
+* @internal
+* @category Relations
+*/
+interface RelationEntry<
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Owner extends keyof Tables,
+	Target extends keyof Tables
+> {
+	ownerField: ScalarPath<Tables[Owner]["schema"]>;
+	targetTableName: Target;
+	targetField: ScalarKeys<Tables[Target]["schema"]>;
+}
+/**
+* @internal
+* @category Relations
+*/
+type RelationsConfig<Tables extends Record<string, TableConfig<any, any, any>>> = { [K in keyof Tables & string]? : Array<{ [Target in keyof Tables & string] : RelationEntry<Tables, K, Target> }[keyof Tables & string]> };
+/**
+* @internal
+* @category Relations
+*/
+type ScalarMergeNames<
+	Rels extends readonly TypedRelation[],
+	Owner extends string
+> = Extract<Rels[number], {
+	ownerTable: Owner;
+	kind: "scalar";
+}> extends TypedRelation<any, any, any, any, any, infer A> ? A extends string ? A : never : never;
+/**
+* @internal
+* @category Relations
+*/
+type ScalarMergeType<
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[],
+	Owner extends string,
+	Name extends string
+> = Extract<Rels[number], {
+	ownerTable: Owner;
+	kind: "scalar";
+	as: Name;
+}> extends TypedRelation<any, any, infer TT, any, any, any> ? TT extends keyof Tables ? Infer<Tables[TT]["schema"]> | null : never : never;
+/**
+* @internal
+* @category Relations
+*/
+type ScalarMerge<
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[],
+	Owner extends string
+> = { [K in ScalarMergeNames<Rels, Owner>] : ScalarMergeType<Tables, Rels, Owner, K> };
+/**
+* @internal
+* @category Relations
+*/
+type SubMergeNames<
+	Rels extends readonly TypedRelation[],
+	Owner extends string,
+	Sub extends string
+> = Extract<Rels[number], {
+	ownerTable: Owner;
+	kind: "subTable";
+	ownerField: `${Sub}.${string}`;
+}> extends TypedRelation<any, any, any, any, any, infer A> ? A extends string ? A : never : never;
+/**
+* @internal
+* @category Relations
+*/
+type SubMergeType<
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[],
+	Owner extends string,
+	Sub extends string,
+	Name extends string
+> = Extract<Rels[number], {
+	ownerTable: Owner;
+	kind: "subTable";
+	ownerField: `${Sub}.${string}`;
+	as: Name;
+}> extends TypedRelation<any, any, infer TT, any, any, any> ? TT extends keyof Tables ? Infer<Tables[TT]["schema"]> | null : never : never;
+/**
+* @internal
+* @category Relations
+*/
+type SubMerge<
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[],
+	Owner extends string,
+	Sub extends string
+> = { [K in SubMergeNames<Rels, Owner, Sub>] : SubMergeType<Tables, Rels, Owner, Sub, K> };
+/**
+* Entity with resolved relations. Sub-table arrays get their related entities
+* merged in, and scalar relations appear as direct properties.
+*
+* @example
+* ```ts
+* // Given: OrderSchema with lineItems: Array<{ sku: string; qty: number }>
+* // And a relation: lineItems.sku → products.sku (as "product")
+*
+* type M = Materialized<OrderSchema, Tables, Rels, "orders">;
+* // M.lineItems becomes Array<{ sku: string; qty: number; product: Product | null }>
+* // M also gets scalar relation properties like `.related` accessors
+* ```
+* @category Relations
+* @category Relations
+*/
+type Materialized<
+	T extends TObject2,
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[],
+	Owner extends string
+> = { [K in keyof Infer<T>] : K extends string ? Infer<T>[K] extends Array<infer Item> ? Array<Item & SubMerge<Tables, Rels, Owner, K>> : Infer<T>[K] : Infer<T>[K] } & ScalarMerge<Tables, Rels, Owner>;
+/**
+* paginated query result
+* @category Query Types
+*/
+interface PageResult<T> {
+	data: T[];
+	total: number;
+	limit: number;
+	offset: number;
+}
+/**
+* insert or update on conflict
+* @category Query Types
+*/
+interface UpsertOptions<
+	T extends TObject2,
+	PK extends ScalarKeys<T>
+> {
+	data: InsertData<T>;
+	conflictTarget: PK | PK[];
+	/** columns to update on conflict - defaults to all non-pk columns */
+	update?: Array<ScalarKeys<T>>;
+}
+/**
+* a single migration step
+* @category Migration
+*/
+interface Migration {
+	name: string;
+	date: string;
+	up: (db: BunDatabase) => void;
+	down?: (db: BunDatabase) => void;
+}
+/**
+* options for migrate()
+* @category Migration
+*/
+interface MigrateOptions {
+	path: string;
+	migrationsDir: string;
+	direction?: "up";
+	target?: string;
+}
+/**
+* @internal
+* @category Migration
+*/
+type SchemaChange = {
+	kind: "add-table";
+	table: string;
+} | {
+	kind: "add-column";
+	table: string;
+	column: {
+		name: string;
+		sqlType: string;
+		nullable: boolean;
+		optional: boolean;
+	};
+	hasDefault: boolean;
+} | {
+	kind: "add-index";
+	table: string;
+	index: {
+		name: string;
+		unique: number;
+		columns: string[];
+	};
+} | {
+	kind: "add-subtable";
+	table: string;
+	subTable: {
+		fieldName: string;
+		tableName: string;
+		columns: {
+			name: string;
+			sqlType: string;
+			nullable: boolean;
+			optional: boolean;
+		}[];
+	};
+} | {
+	kind: "drop-column";
+	table: string;
+	column: string;
+} | {
+	kind: "rename-column";
+	table: string;
+	from: string;
+	to: string;
+} | {
+	kind: "change-type";
+	table: string;
+	column: string;
+	from: string;
+	to: string;
+} | {
+	kind: "change-nullable";
+	table: string;
+	column: string;
+	to: boolean;
+} | {
+	kind: "drop-table";
+	table: string;
+} | {
+	kind: "change-pk";
+	table: string;
+} | {
+	kind: "drop-index";
+	table: string;
+	index: {
+		name: string;
+		unique: number;
+		columns: string[];
+	};
+};
+/**
+* @internal
+* @category Migration
+*/
+interface SchemaDiff {
+	safe: SchemaChange[];
+	unsafe: SchemaChange[];
+}
+/**
+* how to handle schema drift on startup
+* @category Migration
+*/
+type SyncPolicy = "ignore" | "warn" | "error" | "auto" | ((diff: SchemaDiff, db: BunDatabase) => boolean | void);
+/**
+* specific operations that can be listened to per table
+* @category Events
+*/
+type TableOperation = "insert" | "insertMany" | "update" | "delete" | "deleteWhere" | "upsert" | "findById" | "findMany" | "findOne" | "findPage" | "count" | "flush";
+/**
+* broad categories for event listening
+* @category Events
+*/
+type BroadOperation = "read" | "write" | "delete";
+/**
+* @internal
+* @category Events
+*/
+type TableEventOperation = TableOperation | BroadOperation;
+/**
+* payload delivered to event listeners
+* @category Events
+*/
+interface TableEventPayload<
+	T = unknown,
+	Op extends TableEventOperation = TableEventOperation
+> {
+	table: string;
+	operation: Op;
+	data?: T | T[] | Partial<T> | Record<string, unknown>;
+	result?: T | T[] | PageResult<T> | number | null;
+	id?: unknown;
+	where?: unknown;
+	options?: unknown;
+	timestamp: number;
+}
+/**
+* how to handle errors
+* @category Errors
+*/
+type ErrorPolicy = "throw" | "emit" | "emit-swallow" | "crash";
+/**
+* when to delete db files on shutdown
+* @category Setup
+*/
+type UnlinkPolicy = true | "onlyGraceful" | "any" | false | undefined;
+import { TObject as TObject4 } from "typebox";
+/** @category Events */
+type Listener = (payload: unknown) => void;
+/**
+* lifecycle events emitted by the orm
+* @category Events
+*/
+interface LifecycleEventMap {
+	start: {
+		phase: "start";
+		timestamp: number;
+	};
+	ready: {
+		phase: "ready";
+		timestamp: number;
+	};
+	shutdown: {
+		phase: "shutdown";
+		timestamp: number;
+	};
+	exit: {
+		phase: "exit";
+		timestamp: number;
+	};
+	fail: {
+		phase: "fail";
+		error: Error;
+		timestamp: number;
+	};
+}
+/**
+* typed event listener api
+* @category Events
+*/
+interface ORMEvents<Tables extends Record<string, TableConfig<any, any, any>>> {
+	/** listen to lifecycle events (start, ready, shutdown, exit, fail) */
+	on<K extends (keyof LifecycleEventMap) & string>(event: K, listener: (payload: LifecycleEventMap[K]) => void): () => void;
+	/** listen to table events (insert, update, findMany, etc) */
+	on<
+		Table extends keyof Tables & string,
+		Op extends TableOperation | BroadOperation
+	>(table: Table, operation: Op, listener: (payload: TableEventPayload<Tables[Table] extends TableConfig<infer S> ? Infer<S> : never, Op extends TableOperation ? Op : BroadOperation>) => void): () => void;
+}
+/**
+* @internal
+* @category Events
+*/
+declare class EventBus {
+	private readonly listeners;
+	private readonly tableActive;
+	has(event: string): boolean;
+	hasAny(tableName: string): boolean;
+	on(event: string, fn: Listener): () => void;
+	emit(event: string, payload: unknown): void;
+	emitIf(event: string, payload: unknown): void;
+}
+import { TObject as TObject3 } from "typebox";
+/** @category Advanced */
+type SqliteType = "TEXT" | "INTEGER" | "REAL" | "BLOB";
+/** @category Advanced */
+interface ColumnMeta {
+	name: string;
+	sqlType: SqliteType;
+	nullable: boolean;
+	/** True if this is actually an `Optional` wrapper */
+	optional: boolean;
+}
+/** @category Advanced */
+interface SubTableMeta {
+	/** e.g. "lineItems" */
+	fieldName: string;
+	/** e.g. "sales__lineItems" */
+	tableName: string;
+	/** Schema of a single item in the array */
+	itemSchema: TObject3;
+	/** Columns of the sub-table row (owner PK is prepended automatically) */
+	columns: ColumnMeta[];
+}
+/** @category Advanced */
+interface TableMeta {
+	tableName: string;
+	columns: ColumnMeta[];
+	subTables: SubTableMeta[];
+}
+/** @category Advanced */
+declare function introspectTable(tableName: string, schema: TObject3): TableMeta;
+/** @category Advanced */
+declare function buildCreateTableSQL(meta: TableMeta, primaryKey: string): string[];
+/**
+* Typed repository for a single table. Every entry in your `tables` config
+* becomes one of these on the ORM object, fully typed to its schema.
+*
+* @category Repositories
+*
+* @example
+* ```ts
+* const orm = createORM({
+*   tables: {
+*     users: table(UserSchema, (s) => ({ primaryKey: s.id })),
+*   },
+* });
+*
+* // All methods are fully typed - wrong property names are caught at compile time
+* orm.users.insert({ id: "u1", name: "alice", email: "a@x.com" });
+* const user = orm.users.findById("u1");
+* orm.users.update({ id: "u1", name: "alice smith" });
+* orm.users.deleteById("u1");
+* ```
+*/
+declare class Repository<
+	T extends TObject4,
+	PK extends ScalarKeys<T>,
+	Mat = never,
+	TS = {}
+> {
+	readonly tableName: string;
+	/** table metadata - columns, sub-tables, indexes */
+	readonly meta: TableMeta;
+	private readonly validator;
+	private readonly db;
+	private readonly descriptor;
+	private _entityProto;
+	private readonly _timestampNames;
+	private _materialize?;
+	private _materializeMany?;
+	private _events?;
+	/** @internal */
+	setEventBus(bus: EventBus): void;
+	constructor(tableName: string, config: TableConfig<T, PK>, db: BunDatabase);
+	/** Inject materializers after ORM two-pass init */
+	setMaterializer(single: (record: Record<string, unknown>) => Record<string, unknown>, many: (records: Record<string, unknown>[]) => Record<string, unknown>[]): void;
+	/** Wrap raw data in an entity object */
+	private _wrap;
+	/** Narrow a parsed schema value to a plain record for dynamic property access */
+	private _record;
+	private _emit;
+	private _migrate;
+	/**
+	* Validate and coerce data against the schema. Throws on invalid input.
+	*
+	* @group Validation
+	*
+	* @example
+	* ```ts
+	* const user = orm.users.parse({ id: "u1", name: "alice" });
+	* // user is typed as Infer<typeof UserSchema>
+	* ```
+	*/
+	parse(data: unknown): Infer<T>;
+	/**
+	* Type-guard - returns true if data matches the schema.
+	*
+	* @group Validation
+	*
+	* @example
+	* ```ts
+	* if (orm.users.check(someData)) {
+	*   // someData is now typed as Infer<typeof UserSchema>
+	* }
+	* ```
+	*/
+	check(data: unknown): data is Infer<T>;
+	/**
+	* Insert a single record. Returns the inserted entity.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* const user = orm.users.insert({
+	*   id: "u1",
+	*   name: "alice",
+	*   email: "alice@example.com",
+	* });
+	* ```
+	*/
+	insert(data: InsertData<T>): Entity<Infer<T>, Mat, TS>;
+	/**
+	* Insert many records in a single transaction.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* orm.users.insertMany([
+	*   { id: "u1", name: "alice", email: "a@x.com" },
+	*   { id: "u2", name: "bob", email: "b@x.com" },
+	* ]);
+	* ```
+	*/
+	insertMany(records: InsertData<T>[]): Entity<Infer<T>, Mat, TS>[];
+	private _insertParsed;
+	/**
+	* Insert or update on conflict. If the record exists (by conflict target),
+	* it updates the specified columns instead.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* orm.users.upsert({
+	*   data: { id: "u1", name: "alice", email: "new@x.com" },
+	*   conflictTarget: "id",
+	* });
+	* ```
+	*/
+	upsert(opts: UpsertOptions<T, PK>): Entity<Infer<T>, Mat, TS>;
+	/**
+	* Find a record by its primary key.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const user = orm.users.findById("u1");
+	* if (user) console.log(user.name);
+	* ```
+	*/
+	findById(id: Infer<T>[PK]): Entity<Infer<T>, Mat, TS> | null;
+	/** Internal findById without event emission - used by update() */
+	private _findByIdRaw;
+	/**
+	* Find many records matching the given filters.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const adults = orm.users.findMany({
+	*   where: { age: { gte: 18 } },
+	*   orderBy: { column: "name", direction: "ASC" },
+	*   limit: 10,
+	* });
+	*
+	* // Include sub-tables
+	* const orders = orm.orders.findMany({ include: ["lineItems"] });
+	* ```
+	*/
+	findMany(opts?: FindOptions<T>): Entity<Infer<T>, Mat, TS>[];
+	/**
+	* Find many with total count - useful for pagination.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const page = orm.users.findPage({
+	*   where: { status: { eq: "active" } },
+	*   limit: 10,
+	*   offset: 0,
+	* });
+	* // page.data - the records
+	* // page.total - total matching records
+	* // page.limit, page.offset - what you passed in
+	* ```
+	*/
+	findPage(opts?: FindOptions<T>): PageResult<Entity<Infer<T>, Mat, TS>>;
+	/**
+	* Find a single record matching the given filters. Equivalent to `findMany`
+	* with `limit: 1`, but returns the entity directly (or `null`).
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const admin = orm.users.findOne({
+	*   where: { role: { eq: "admin" } },
+	* });
+	* ```
+	*/
+	findOne(opts?: FindOptions<T>): Entity<Infer<T>, Mat, TS> | null;
+	/**
+	* Find many with resolved relations (n+1 safe). If you have cross-table
+	* relations configured, this eagerly loads them in a single batch query.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const orders = orm.orders.findManyMaterialized();
+	* for (const item of orders[0].lineItems) {
+	*   console.log(item.product.name); // eagerly resolved
+	* }
+	* ```
+	*/
+	findManyMaterialized(opts?: FindOptions<T>): Entity<Infer<T>, Mat, TS>[];
+	/**
+	* Count records matching the given filters.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const total = orm.users.count();
+	* const adults = orm.users.count({ age: { gte: 18 } });
+	* ```
+	*/
+	count(where?: WhereClause<T>): number;
+	/**
+	* Update a record - must include the primary key. Returns the updated
+	* entity, or `null` if no record matched.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* orm.users.update({ id: "u1", name: "alice smith" });
+	* ```
+	*/
+	update(data: UpdateData<T, PK>): Entity<Infer<T>, Mat, TS> | null;
+	/**
+	* Delete a record by its primary key. Returns `true` if a record was deleted.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* const deleted = orm.users.deleteById("u1");
+	* ```
+	*/
+	deleteById(id: Infer<T>[PK]): boolean;
+	/**
+	* Delete records matching the given filters. Returns the number of rows deleted.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* const removed = orm.users.deleteWhere({ status: { eq: "banned" } });
+	* ```
+	*/
+	deleteWhere(where: WhereClause<T>): number;
+	/**
+	* Truncate the table and all sub-tables. Deletes all rows but keeps the schema.
+	*
+	* @group Lifecycle
+	*
+	* @example
+	* ```ts
+	* orm.users.flush(); // users table is now empty
+	* ```
+	*/
+	flush(): void;
+	/**
+	* Drop the table and all sub-tables. **This destroys the schema and all data.**
+	*
+	* @group Lifecycle
+	*
+	* @example
+	* ```ts
+	* orm.users.drop(); // table no longer exists
+	* ```
+	*/
+	drop(): void;
+	private _hydrateOne;
+	/**
+	* Run raw SQL - escape hatch for queries the ORM doesn't support directly.
+	*
+	* @group Raw SQL
+	*
+	* @example
+	* ```ts
+	* const rows = orm.users.raw<{ name: string; count: number }>(
+	*   'SELECT name, COUNT(*) as count FROM users GROUP BY name'
+	* );
+	* ```
+	*/
+	raw<R = unknown>(sql: string, ...params: unknown[]): R[];
+}
+declare class RelationBuilder<Tables extends Record<string, TableConfig<any, any, any>>> {
+	private readonly tables;
+	private readonly relations;
+	constructor(tables: Tables);
+	from<Owner extends keyof Tables & string>(ownerTable: Owner): {
+		scalar: <const Field extends ScalarKeys<Tables[Owner]["schema"]>>(field: Field) => {
+			to: <
+				Target extends keyof Tables & string,
+				TField extends ScalarKeys<Tables[Target]["schema"]>,
+				const As extends string | undefined = undefined
+			>(targetTable: Target, targetField: TField, opts?: {
+				as?: As;
+			}) => TypedRelation<Owner, Field, Target, TField, "scalar", As>;
+		};
+		subTable: <
+			const Sub extends string,
+			const Col extends string
+		>(subField: Sub, subColumn: Col) => {
+			to: <
+				Target extends keyof Tables & string,
+				TField extends ScalarKeys<Tables[Target]["schema"]>,
+				const As extends string | undefined = undefined
+			>(targetTable: Target, targetField: TField, opts?: {
+				as?: As;
+			}) => TypedRelation<Owner, `${Sub}.${Col}`, Target, TField, "subTable", As>;
+		};
+	};
+	build(): TypedRelation[];
+}
+/** @category Relations */
+declare function createRelationBuilder<T extends Record<string, TableConfig<any, any, any>>>(tables: T): RelationBuilder<T>;
+import { Static as Static2 } from "typebox";
+declare const SchemaHashSchema: unknown;
+/** @category Database */
+declare const SchemaJSONSchema: unknown;
+declare const TablesSchema: unknown;
+declare const RelationsSchema: unknown;
+declare const VersionSchema: unknown;
+type SchemaHash = Static2<typeof SchemaHashSchema>;
+/** @category Database */
+type SchemaJSON = Static2<typeof SchemaJSONSchema>;
+type TablesList = Static2<typeof TablesSchema>;
+type RelationsList = Static2<typeof RelationsSchema>;
+type Version = Static2<typeof VersionSchema>;
+/** @category Database */
+declare class MetaStore {
+	private readonly db;
+	private static readonly KEY_SCHEMA_HASH;
+	private static readonly KEY_SCHEMA_JSON;
+	private static readonly KEY_TABLES;
+	private static readonly KEY_RELATIONS;
+	private static readonly KEY_VERSION;
+	constructor(db: BunDatabase);
+	private getRow;
+	private setRow;
+	private getValidatedJSON;
+	private setValidatedJSON;
+	getString(key: string): string | null;
+	setString(key: string, value: string): void;
+	getJSON<T>(key: string): T | null;
+	setJSON(key: string, value: unknown): void;
+	getCompressed(key: string): Uint8Array | null;
+	setCompressed(key: string, data: Uint8Array): void;
+	delete(key: string): void;
+	getSchemaHash(): SchemaHash | null;
+	setSchemaHash(value: SchemaHash): void;
+	getSchemaJSON(): SchemaJSON | null;
+	setSchemaJSON(value: SchemaJSON): void;
+	getTables(): TablesList | null;
+	setTables(value: TablesList): void;
+	getRelations(): RelationsList | null;
+	setRelations(value: RelationsList): void;
+	getVersion(): Version | null;
+	setVersion(value: Version): void;
+}
+/**
+* context passed to lifecycle hooks
+* @category Lifecycle
+*/
+interface ORMContext<
+	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
+> {
+	orm: foxdb<T, Rels>;
+	db: BunDatabase;
+	meta: MetaStore;
+	tables: string[];
+	repos: Map<string, unknown>;
+	logger: {
+		log: (...args: unknown[]) => void;
+		error: (...args: unknown[]) => void;
+	};
+}
+/**
+* lifecycle hook signature
+* @category Lifecycle
+*/
+type LifecycleHook<
+	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
+> = (ctx: ORMContext<T, Rels>) => void | Promise<void>;
+/**
+* manages startup and shutdown hook execution
+* @category Lifecycle
+*/
+declare class LifecycleManager<
+	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
+> {
+	private startHooks;
+	private readyHooks;
+	private shutdownHooks;
+	private exitHooks;
+	private _ready;
+	private _shutdown;
+	/** true after runReady completes */
+	get isReady();
+	/** true after runShutdown completes */
+	get isShutdown();
+	/** register a startup hook */
+	onStart(hook: LifecycleHook<T, Rels>);
+	/** register a ready hook */
+	onReady(hook: LifecycleHook<T, Rels>);
+	/** register a shutdown hook */
+	onShutdown(hook: LifecycleHook<T, Rels>);
+	/** register an exit hook */
+	onExit(hook: LifecycleHook<T, Rels>);
+	/** @internal */
+	runStart(ctx: ORMContext<T, Rels>): void;
+	/** @internal */
+	runReady(ctx: ORMContext<T, Rels>): void;
+	/** @internal */
+	runShutdown(ctx: ORMContext<T, Rels>): void;
+	/** @internal */
+	runExit(ctx: ORMContext<T, Rels>): void;
+}
+/**
+* Base options for opening a SQLite database.
+* @category Setup
+*/
+interface CreateORMBaseOptions {
+	/** file path - defaults to ":memory:" */
+	path?: string;
+	cacheSize?: number;
+	busyTimeout?: number;
+	synchronous?: "OFF" | "NORMAL" | "FULL" | "EXTRA";
+	mmapSize?: number;
+}
+/**
+* Options passed to `createORM`.
+*
+* @category Setup
+*
+* @example
+* ```ts
+* const orm = createORM({
+*   path: "app.db",
+*   tables: {
+*     users: table(UserSchema, (s) => ({
+*       primaryKey: s.id,
+*       indexes: [{ columns: [s.email] }],
+*       timestamps: true,
+*     })),
+*   },
+*   relations: (r) => [
+*     r.from("users").scalar("profileId").to("profiles", "id"),
+*   ],
+*   seed: (o) => {
+*     o.users.insert({ id: "1", name: "alice" });
+*   },
+*   onReady: () => console.log("db ready"),
+*   autoMigrate: true,
+*   migrations: { dir: "./migrations" },
+* });
+* ```
+*/
+interface CreateORMOptions<
+	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
+> extends CreateORMBaseOptions {
+	/** table schemas */
+	tables: T;
+	/** cross-table relations */
+	relations?: RelationsConfig<any> | ((builder: RelationBuilder<T>) => Rels);
+	/** how to handle schema drift */
+	sync?: SyncPolicy;
+	/** migration directory */
+	migrations?: {
+		dir: string;
+	};
+	/** runs before schema validation */
+	onStart?: LifecycleHook<T, Rels>;
+	/** runs after the db is fully ready */
+	onReady?: LifecycleHook<T, Rels>;
+	/** runs before closing the db */
+	onShutdown?: LifecycleHook<T, Rels>;
+	/** runs after the db is closed */
+	onExit?: LifecycleHook<T, Rels>;
+	/** run pending migrations on startup */
+	autoMigrate?: boolean;
+	/** seed data after sync */
+	seed?: (orm: foxdb<T, Rels>) => void;
+	/** wipe and recreate the db on every launch */
+	rebuildOnLaunch?: boolean;
+	/** flush these tables before seed */
+	flushOnStart?: Array<keyof T & string>;
+	/** flush these tables before close */
+	flushOnExit?: Array<keyof T & string>;
+	/** drop these tables before seed */
+	dropOnStart?: Array<keyof T & string>;
+	/** drop these tables before close */
+	dropOnExit?: Array<keyof T & string>;
+	/** wipe metadata on startup */
+	flushMetaOnStart?: boolean;
+	/** wipe metadata on exit */
+	flushMetaOnExit?: boolean;
+	/** how to handle errors */
+	errorPolicy?: ErrorPolicy;
+	/** delete db files on exit */
+	unlinkDbFilesOnExit?: UnlinkPolicy;
+}
+/**
+* The ORM object returned by `createORM`.
+*
+* Every key in your `tables` config becomes a fully typed **Repository**
+* with CRUD methods. The type definition below is a mapped type that
+* transforms your schema config into the actual runtime API — TypeDoc
+* cannot expand it, so see the example for how it works in practice.
+*
+* @see {@link Repository} for the full method reference
+*
+* @category Setup
+*
+* @example
+* ```ts
+* const orm = createORM({
+*   tables: {
+*     users: table(UserSchema, (s) => ({ primaryKey: s.id })),
+*   },
+* });
+*
+* // ─── Every table key is a Repository ───
+*
+* // Insert
+* orm.users.insert({ id: "u1", name: "alice" });
+* orm.users.insertMany([{ id: "u2", name: "bob" }]);
+*
+* // Query
+* const user   = orm.users.findById("u1");
+* const all    = orm.users.findMany();
+* const page   = orm.users.findPage({ limit: 10, offset: 0 });
+* const one    = orm.users.findOne({ where: { name: { eq: "alice" } } });
+* const count  = orm.users.count({ age: { gte: 18 } });
+*
+* // Update & delete
+* orm.users.update({ id: "u1", name: "alice smith" });
+* orm.users.upsert({ data: { id: "u1", name: "alice" }, conflictTarget: "id" });
+* orm.users.deleteById("u1");
+* orm.users.deleteWhere({ status: { eq: "banned" } });
+*
+* // ─── Framework methods (prefixed with _) ───
+*
+* orm._transaction(() => {
+*   orm.users.insert({ id: "t1", name: "txn" });
+*   orm.users.deleteById("old");
+* });
+*
+* orm._close();
+* ```
+*/
+type foxdb<
+	Tables extends Record<string, TableConfig<any, any, any>>,
+	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
+> = { [K in keyof Tables] : Tables[K] extends TableConfig<infer T, infer PK, infer TS> ? Repository<T, PK extends ScalarKeys<T> ? PK : never, Materialized<T, Tables, Rels, K & string>, TimestampShape<TS>> : never } & {
+	/** run a transaction */
+	_transaction<R>(fn: () => R): R;
+	/** close the database */
+	_close(): void;
+	/** read-only metadata */
+	_meta: MetaAccessors;
+	/** resolve relations for a single record */
+	_materialize<Owner extends keyof Tables & string>(ownerTable: Owner, record: Record<string, unknown>): Record<string, unknown>;
+	/** resolve relations for many records (n+1 safe) */
+	_materializeMany<Owner extends keyof Tables & string>(ownerTable: Owner, records: Record<string, unknown>[]): Array<Record<string, unknown>>;
+	/** truncate all tables */
+	_flush(opts?: {
+		includeMeta?: boolean;
+	}): void;
+	/** run pending migrations */
+	_migrate(): Promise<void>;
+	/** listen to table or lifecycle events */
+	_events: ORMEvents<Tables>;
+};
+/** create a typed orm instance backed by sqlite */
+declare function createORM<
+	const T extends Record<string, TableConfig<any, any, any>>,
+	const Rels extends readonly TypedRelation[] = readonly TypedRelation[]
+>(opts: CreateORMOptions<T, Rels>): foxdb<T, Rels>;
+import { TObject as TObject5 } from "typebox";
+/** @category Schema */
+interface SubTableConfig {
+	indexes?: IndexDefinition[];
+}
+/** @category Schema */
+interface TableDescriptor<
+	T extends TObject5,
+	PK extends string,
+	TS extends TimestampConfig = undefined
+> extends TableConfig<T, PK, TS> {}
+/** @category Schema */
+interface TableConfigShape<
+	PK extends string,
+	TS extends TimestampConfig
+> {
+	primaryKey: ColumnRef<PK>;
+	indexes?: IndexDefinition[];
+	subTables?: Partial<Record<string, SubTableConfig>>;
+	timestamps?: TS;
+}
+/**
+* Describe a table schema + config for `createORM`.
+*
+* @example
+* ```ts
+* const UserSchema = Object({ id: String(), name: String(), email: String() });
+*
+* const users = table(UserSchema, (s) => ({
+*   primaryKey: s.id,
+*   indexes: [{ columns: [s.email], unique: true }],
+*   timestamps: true, // adds createdAt / updatedAt
+* }));
+* ```
+* @category Schema
+* @category Schema
+*/
+declare function table<
+	T extends TObject5,
+	PK extends string,
+	const TS extends boolean
+>(schema: T, configure: (columns: ColumnRefs<T>) => TableConfigShape<PK, TS> & {
+	timestamps: TS;
+}): TableDescriptor<T, PK, TS>;
+/** @category Schema */
+declare function table<
+	T extends TObject5,
+	PK extends string,
+	const TS extends {
+		createdAt?: string;
+		updatedAt?: string;
+	}
+>(schema: T, configure: (columns: ColumnRefs<T>) => TableConfigShape<PK, TS> & {
+	timestamps: TS;
+}): TableDescriptor<T, PK, TS>;
+/** @category Schema */
+declare function table<
+	T extends TObject5,
+	PK extends string
+>(schema: T, configure: (columns: ColumnRefs<T>) => TableConfigShape<PK, undefined>): TableDescriptor<T, PK, undefined>;
+declare function migrate(opts: MigrateOptions): Promise<void>;
+/** @category Migration */
+declare function createMigration(name: string, migrationsDir: string): string;
+/**
+* src/errors.ts
+* Central error type with invisible tracing and structured context.
+*/
+/**
+* a single entry in the error trace
+* @category Errors
+*/
+interface TraceEntry {
+	label: string;
+	time: number;
+	details?: Record<string, unknown>;
+}
+/**
+* context captured when an error occurs
+* @category Errors
+*/
+interface ORMErrorContext {
+	table?: string;
+	operation?: string;
+	sql?: string;
+	params?: unknown[];
+	schema?: unknown;
+	[key: string]: unknown;
+}
+/**
+* structured error with trace and context
+* @category Errors
+*/
+declare class ORMError extends Error {
+	readonly code: string;
+	readonly trace: TraceEntry[];
+	readonly context: ORMErrorContext;
+	constructor(message: string, opts: {
+		code: string;
+		trace: TraceEntry[];
+		context?: ORMErrorContext;
+	});
+}
+/**
+* @internal
+* @category Errors
+*/
+declare function withTrace<T>(label: string, details: Record<string, unknown> | undefined, fn: () => T): T;
+/**
+* throw an ORMError with trace and context
+* @category Errors
+*/
+declare function raise(code: string, message: string, context?: ORMErrorContext): never;
+/**
+* how to handle runtime errors
+* @category Errors
+*/
+type ErrorPolicy2 = "throw" | "emit" | "emit-swallow" | "crash";
+/** @category Schema */
+interface TimestampConfig2 {
+	createdAt?: string;
+	updatedAt?: string;
+}
+/** @category Schema */
+declare const DEFAULT_TIMESTAMP_NAMES: Required<Pick<TimestampConfig2, "createdAt" | "updatedAt">>;
+/** @category Schema */
+declare function resolveTimestampNames(config: boolean | TimestampConfig2 | undefined, meta: TableMeta): {
+	createdAt: string | null;
+	updatedAt: string | null;
+};
+/** @category Advanced */
+interface InspectorColumn {
+	name: string;
+	type: string;
+	notnull: number;
+	dflt_value: string | null;
+	pk: number;
+}
+/** @category Advanced */
+interface InspectorIndex {
+	name: string;
+	unique: number;
+	columns: string[];
+}
+/** @category Advanced */
+interface InspectorTable {
+	name: string;
+	columns: InspectorColumn[];
+	indexes: InspectorIndex[];
+}
+/** @category Advanced */
+declare function inspectSchema(db: BunDatabase, tableName: string): InspectorTable;
+/** @category Advanced */
+declare function inspectAllTables(db: BunDatabase): InspectorTable[];
+interface DesiredTable {
+	name: string;
+	columns: ColumnMeta[];
+	indexes: Array<{
+		name?: string;
+		columns: string[];
+		unique?: boolean;
+	}>;
+	primaryKey: string;
+}
+/** @category Migration */
+declare function computeDiff(desired: DesiredTable[], actual: InspectorTable[]): SchemaDiff;
+/** @category Migration */
+declare function applySync(diff: SchemaDiff, db: BunDatabase, policy: SyncPolicy, desired: DesiredTable[]): void;
+export { withTrace, table, resolveTimestampNames, raise, migrate, introspectTable, inspectSchema, inspectAllTables, foxdb, createRelationBuilder, createORM, createMigration, computeDiff, buildCreateTableSQL, applySync, WhereClause, UpsertOptions, UpdateData, UnlinkPolicy, TypedRelation, TraceEntry, TimestampShape, TimestampConfig2 as TimestampNamesConfig, TableOperation, TableMeta, TableEventPayload, TableEventOperation, TableDescriptor, TableConfigShape, TableConfig, TScalarSchema, SyncPolicy, SubTableScalarPath, SubTableMeta, SubTableKeys, SubTableConfig, SubMergeType, SubMergeNames, SubMerge, SqliteType, SchemaJSONSchema, SchemaJSON, SchemaDiff, SchemaChange, ScalarProperties, ScalarPath, ScalarMergeType, ScalarMergeNames, ScalarMerge, ScalarKeys, ScalarFilter, Repository, RelationsConfig, RelationEntry, RelationBuilder, PageResult, OrderByClause, ORMEvents, ORMErrorContext, ORMError, ORMContext, Migration, MigrateOptions, MetaStore, Materialized, Listener, LifecycleManager, LifecycleHook, LifecycleEventMap, InspectorTable, InspectorIndex, InspectorColumn, InsertData, Infer, IndexDefinition, FindOptions, EventBus, ErrorPolicy2 as ErrorPolicy, Entity, DesiredTable, DatabaseOptions, DEFAULT_TIMESTAMP_NAMES, CreateORMOptions, CreateORMBaseOptions, ColumnRefs, ColumnRef, ColumnMeta, BunStatement, BunDatabase, BroadOperation, ArrayOfObjectProperties };