@xwxfox/foxdb 0.0.1 → 0.1.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { TObject as TObject2, TArray, TSchema, TProperties, Static } from "typebox";
-import { TObject, TString, TNumber, TInteger, TBoolean, TLiteral } from "typebox";
+import { TSchema as TSchema6 } from "typebox";
+import { TObject as TObject2, TArray, TSchema as TSchema2, TProperties, TOptional as TOptional2, Static } from "typebox";
+import { TObject, TString, TNumber, TInteger, TBoolean, TLiteral, TSchema, TOptional } from "typebox";
 /** @category Schema */
 type TScalarSchema = TString | TNumber | TInteger | TBoolean | TLiteral<string> | TLiteral<number> | TLiteral<boolean>;
 /**
@@ -14,11 +15,24 @@ interface ColumnRef<
 	readonly name: N;
 	readonly schema: S;
 }
+type UnwrapOptionalSchema<S extends TSchema> = S extends TOptional<infer U> ? U : S;
+type IsScalarSchema<S extends TSchema> = S extends TString ? true : S extends TNumber ? true : S extends TInteger ? true : S extends TBoolean ? true : S extends TLiteral<string | number | boolean> ? true : false;
+type NestedColumnKeys<T extends TSchema & {
+	properties: Record<string, TSchema>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptionalSchema<T["properties"][K]> extends TObject<infer P> ? { [K2 in keyof P & string] : IsScalarSchema<UnwrapOptionalSchema<P[K2]>> extends true ? `${K}__${K2}` : UnwrapOptionalSchema<P[K2]> extends TObject<infer P2> ? { [K3 in keyof P2 & string] : IsScalarSchema<UnwrapOptionalSchema<P2[K3]>> extends true ? `${K}__${K2}__${K3}` : never }[keyof P2 & string] : never }[keyof P & string] : never }[keyof T["properties"] & string];
+type NestedColumnRef<
+	T extends TSchema & {
+		properties: Record<string, TSchema>;
+	},
+	N extends string
+> = N extends `${infer K}__${infer K2}__${infer K3}` ? K extends keyof T["properties"] & string ? UnwrapOptionalSchema<T["properties"][K]> extends TObject<infer P> ? K2 extends keyof P & string ? UnwrapOptionalSchema<P[K2]> extends TObject<infer P2> ? K3 extends keyof P2 & string ? UnwrapOptionalSchema<P2[K3]> extends infer U ? U extends TScalarSchema ? ColumnRef<N, U> : never : never : never : never : never : never : never : N extends `${infer K}__${infer K2}` ? K extends keyof T["properties"] & string ? UnwrapOptionalSchema<T["properties"][K]> extends TObject<infer P> ? K2 extends keyof P & string ? UnwrapOptionalSchema<P[K2]> extends infer U ? U extends TScalarSchema ? ColumnRef<N, U> : never : never : never : never : never : never;
 /**
 * 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 };
+type ColumnRefs<T extends TSchema & {
+	properties: Record<string, TSchema>;
+}> = { 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 } & { readonly [K in NestedColumnKeys<T>] : NestedColumnRef<T, K> };
 /**
 * foxdb/src/typed-relation.ts
 * Runtime + compile-time representation of a single relation.
@@ -39,20 +53,12 @@ interface TypedRelation<
 	kind: K;
 	as: A;
 }
-import { Database, SQLQueryBindings } from "bun:sqlite";
+import { Database, Statement } 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;
-}
+type BunStatement = Statement;
 /** @category Database */
 interface DatabaseOptions {
 	/** Path to the SQLite file. Defaults to ":memory:" */
@@ -75,6 +81,8 @@ interface DatabaseOptions {
 	synchronous?: "OFF" | "NORMAL" | "FULL" | "EXTRA";
 	/** PRAGMA mmap_size in bytes. 0 disables. Defaults to 256 MB. */
 	mmapSize?: number;
+	/** PRAGMA auto_vacuum level. "incremental" | "full" | false. Defaults to false. */
+	autoVacuum?: "incremental" | "full" | false;
 }
 /**
 * sqlite database with statement caching and pragma tuning
@@ -83,6 +91,8 @@ interface DatabaseOptions {
 declare class BunDatabase {
 	/** underlying bun:sqlite database */
 	readonly db: Database;
+	/** scheduler for table maintenance tasks */
+	readonly scheduler;
 	constructor(opts?: DatabaseOptions);
 	/** execute ddl (create table, index, etc) */
 	exec(sql: string): void;
@@ -94,46 +104,192 @@ declare class BunDatabase {
 	private readonly _stmtCache;
 	/** get or compile a prepared statement */
 	prepare(sql: string): BunStatement;
+	/** set synchronous pragma for bulk load or normal operation */
+	setSynchronous(mode: "OFF" | "NORMAL" | "FULL" | "EXTRA"): void;
 	/** clear the statement cache */
 	clearCache(): void;
 }
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+	[key: string]: JsonValue;
+};
+type DBBinary = Uint8Array;
+type DBScalar = string | number | boolean | bigint | null;
+type DBValue = DBScalar | JsonValue | DBBinary;
+type DBRow = Record<string, DBValue | undefined>;
+/** @internal */
+type UnwrapOptional<T> = T extends TOptional2<infer U> ? U : T;
+/** @internal */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** @internal */
+type IsOptionalKey<
+	O,
+	K extends keyof O
+> = {} extends Pick<O, K> ? true : false;
+/** @internal */
+type MergePath<
+	O,
+	P extends string
+> = P extends `${infer K}.${infer Rest}` ? K extends keyof O ? IsOptionalKey<O, K> extends true ? { [k in K]? : MergePath<NonNullable<O[K]>, Rest> } : { [k in K] : MergePath<NonNullable<O[K]>, Rest> } : never : P extends keyof O ? IsOptionalKey<O, P> extends true ? { [k in P]? : O[P] } : { [k in P] : O[P] } : never;
+/** @internal */
+type SelectShape<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	S extends readonly string[]
+> = UnionToIntersection<S[number] extends infer P ? P extends string ? MergePath<Infer<T>, P> : never : never>;
+/**
+* scalar values sqlite can store natively
+* @category Advanced
+*/
+type SqliteScalar = string | number | boolean | null | bigint;
 /**
 * @internal
 * @category Advanced
 */
-type ScalarProperties<P extends TProperties> = { [K in keyof P as P[K] extends TArray<infer _> ? never : K] : P[K] };
+type ScalarProperties<P extends TProperties> = { [K in keyof P as P[K] extends TArray<infer _> ? never : P[K] extends TObject2 ? 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 };
+type ArrayOfObjectProperties<P extends TProperties> = { [K in keyof P as P[K] extends TArray<{
+	properties: Record<string, TSchema2>;
+}> ? 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;
+type ScalarKeys<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = keyof ScalarProperties<T["properties"]> & string;
+/** @internal */
+type ObjectKeys<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends TObject2 ? K : never }[keyof T["properties"] & string];
+/** @internal */
+type PrimitiveArrayKeys<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends TArray<infer Item> ? Item extends TScalarSchema ? K : never : never }[keyof T["properties"] & string];
 /**
 * @internal
 * @category Query Types
 */
-type SubTableKeys<T extends TObject2> = keyof ArrayOfObjectProperties<T["properties"]> & string;
+type SubTableKeys<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = 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>];
+type SubTableScalarPath<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in SubTableKeys<T>] : T["properties"][K] extends TArray<infer Item> ? Item extends {
+	properties: Record<string, TSchema2>;
+} ? `${K}.${ScalarKeys<Item>}` : never : never }[SubTableKeys<T>];
 /**
 * @internal
 * @category Advanced
 */
-type ScalarPath<T extends TObject2> = ScalarKeys<T> | SubTableScalarPath<T>;
+type ScalarPath<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarKeys<T> | SubTableScalarPath<T>;
+/** @internal */
+type JsonPathLevel1<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends {
+	properties: Record<string, TSchema2>;
+} ? `${K}.${keyof UnwrapOptional<T["properties"][K]>["properties"] & string}` : never }[keyof T["properties"] & string];
+/** @internal */
+type JsonPathLevel2<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends {
+	properties: Record<string, TSchema2>;
+} ? { [K2 in keyof UnwrapOptional<T["properties"][K]>["properties"] & string] : UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]> extends {
+	properties: Record<string, TSchema2>;
+} ? `${K}.${K2}.${keyof UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"] & string}` : never }[keyof UnwrapOptional<T["properties"][K]>["properties"] & string] : never }[keyof T["properties"] & string];
+/** @internal */
+type JsonPathLevel3<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends {
+	properties: Record<string, TSchema2>;
+} ? { [K2 in keyof UnwrapOptional<T["properties"][K]>["properties"] & string] : UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]> extends {
+	properties: Record<string, TSchema2>;
+} ? { [K3 in keyof UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"] & string] : UnwrapOptional<UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][K3]> extends {
+	properties: Record<string, TSchema2>;
+} ? `${K}.${K2}.${K3}.${keyof UnwrapOptional<UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][K3]>["properties"] & string}` : never }[keyof UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"] & string] : never }[keyof UnwrapOptional<T["properties"][K]>["properties"] & string] : never }[keyof T["properties"] & string];
+/** @internal */
+type JsonPath<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = JsonPathLevel1<T> | JsonPathLevel2<T> | JsonPathLevel3<T>;
+/** @internal */
+type ScalarJsonPathLevel1<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends TObject2<infer P> ? { [K2 in keyof P & string] : UnwrapOptional<P[K2]> extends TScalarSchema ? `${K}.${K2}` : never }[keyof P & string] : never }[keyof T["properties"] & string];
+/** @internal */
+type ScalarJsonPathLevel2<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends TObject2<infer P> ? { [K2 in keyof P & string] : UnwrapOptional<P[K2]> extends TObject2<infer P2> ? { [K3 in keyof P2 & string] : UnwrapOptional<P2[K3]> extends TScalarSchema ? `${K}.${K2}.${K3}` : never }[keyof P2 & string] : never }[keyof P & string] : never }[keyof T["properties"] & string];
+/** @internal */
+type ScalarJsonPathLevel3<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof T["properties"] & string] : UnwrapOptional<T["properties"][K]> extends TObject2<infer P> ? { [K2 in keyof P & string] : UnwrapOptional<P[K2]> extends TObject2<infer P2> ? { [K3 in keyof P2 & string] : UnwrapOptional<P2[K3]> extends TObject2<infer P3> ? { [K4 in keyof P3 & string] : UnwrapOptional<P3[K4]> extends TScalarSchema ? `${K}.${K2}.${K3}.${K4}` : never }[keyof P3 & string] : never }[keyof P2 & string] : never }[keyof P & string] : never }[keyof T["properties"] & string];
+/** @internal */
+type ScalarJsonPath<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarJsonPathLevel1<T> | ScalarJsonPathLevel2<T> | ScalarJsonPathLevel3<T>;
+/** @internal */
+type PathValue<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	P extends string
+> = P extends `${infer K}.${infer Rest}` ? UnwrapOptional<T["properties"][K]> extends {
+	properties: Record<string, TSchema2>;
+} ? Rest extends `${infer K2}.${infer Rest2}` ? UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]> extends {
+	properties: Record<string, TSchema2>;
+} ? Rest2 extends `${infer K3}.${infer Rest3}` ? UnwrapOptional<UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][K3]> extends {
+	properties: Record<string, TSchema2>;
+} ? UnwrapOptional<UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][K3]>["properties"][Rest3] extends TSchema2 ? Static<UnwrapOptional<UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][K3]>["properties"][Rest3]> : never : never : UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][Rest2] extends TSchema2 ? Static<UnwrapOptional<UnwrapOptional<T["properties"][K]>["properties"][K2]>["properties"][Rest2]> : never : never : UnwrapOptional<T["properties"][K]>["properties"][Rest] extends TSchema2 ? Static<UnwrapOptional<T["properties"][K]>["properties"][Rest]> : never : never : P extends keyof T["properties"] ? Static<T["properties"][P]> : never;
 /**
 * the typescript type that matches a typebox schema
 * @category Query Types
 */
-type Infer<T extends TSchema> = Static<T>;
+type Infer<T extends TSchema2> = Static<T>;
+/**
+* @internal
+* @category Advanced
+*/
+type SubTableItem<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	K extends SubTableKeys<T>
+> = T["properties"][K] extends TArray<infer Item extends TSchema2> ? Static<Item> : never;
 /** @category Query Types */
-type ScalarFilter<V> = V extends string ? {
+type ScalarFilter<V> = unknown extends V ? {
+	eq: V;
+} | {
+	ne: V;
+} | {
+	gt: V;
+} | {
+	gte: V;
+} | {
+	lt: V;
+} | {
+	lte: V;
+} | {
+	like: string;
+} | {
+	between: [V, V];
+} | {
+	in: V[];
+} | {
+	notIn: V[];
+} | {
+	isNull: true;
+} | {
+	isNotNull: true;
+} : V extends string ? {
 	eq: V;
 } | {
 	ne: V;
@@ -173,11 +329,57 @@ type ScalarFilter<V> = V extends string ? {
 	isNull: true;
 } | {
 	isNotNull: true;
+} : V extends object ? {
+	eq: V;
+} | {
+	ne: V;
+} | {
+	isNull: true;
+} | {
+	isNotNull: true;
 } : {
 	isNull: true;
 } | {
 	isNotNull: true;
 };
+/** @category Query Types */
+type ArrayFilter<V> = {
+	/** matches if at least one element in the array equals this value */
+	arraySome?: V;
+	/** matches if no element in the array equals this value */
+	arrayNot?: V;
+	/** matches if the array is empty (length 0 or NULL) */
+	isEmpty?: boolean;
+	/** 
+	* HIGH PERFORMANCE: matches if at least one element in the array equals this value.
+	* Uses string-based matching which is significantly faster than JSON parsing but 
+	* sensitive to JSON formatting/whitespace.
+	*/
+	fastArraySome?: V;
+	/** 
+	* HIGH PERFORMANCE: matches if no element in the array equals this value.
+	* Uses string-based matching which is significantly faster than JSON parsing but 
+	* sensitive to JSON formatting/whitespace.
+	*/
+	fastArrayNot?: V;
+	/** 
+	* HIGH PERFORMANCE: matches if the array is empty ('[]' or NULL).
+	* Significantly faster than isEmpty and can be indexed with a standard index.
+	*/
+	fastArrayIsEmpty?: boolean;
+	/** matches if the entire array equals this value */
+	eq?: V[];
+	/** matches if the entire array does not equal this value */
+	ne?: V[];
+	/** matches if the column is NULL */
+	isNull?: true;
+	/** matches if the column is NOT NULL */
+	isNotNull?: true;
+	/** matches if the entire array is in the list of arrays */
+	in?: V[][];
+	/** matches if the entire array is not in the list of arrays */
+	notIn?: V[][];
+};
 /**
 * Where filters for queries - only scalar columns are filterable.
 *
@@ -187,6 +389,10 @@ type ScalarFilter<V> = V extends string ? {
 * orm.users.findMany({ where: { name: { like: "%alice%" } } });
 * orm.users.findMany({ where: { email: { in: ["a@x.com", "b@x.com"] } } });
 *
+* // Array filters
+* orm.users.findMany({ where: { tags: { arraySome: "typescript" } } });
+* orm.users.findMany({ where: { scores: { isEmpty: true } } });
+*
 * // Number filters
 * orm.users.findMany({ where: { age: { gte: 18, lte: 65 } } });
 * orm.products.findMany({ where: { price: { between: [10, 100] } } });
@@ -198,13 +404,25 @@ type ScalarFilter<V> = V extends string ? {
 * @category Query Types
 * @category Query Types
 */
-type WhereClause<T extends TObject2> = { [K in ScalarKeys<T>]? : ScalarFilter<Static<T["properties"][K]>> };
+type WhereClause<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in ScalarKeys<T>]? : ScalarFilter<Static<T["properties"][K]>> } & { [K in ObjectKeys<T>]? : ScalarFilter<Static<T["properties"][K]>> } & { [K in PrimitiveArrayKeys<T>]? : ArrayFilter<Static<UnwrapOptional<T["properties"][K]> extends TArray<infer Item> ? Item : never>> } & { [K in JsonPath<T>]? : PathValue<T, K> extends Array<infer Item> ? ArrayFilter<Item> : ScalarFilter<PathValue<T, K>> } & {
+	AND?: WhereClause<T>[];
+	OR?: WhereClause<T>[];
+	NOT?: WhereClause<T>;
+	_raw?: {
+		sql: string;
+		params: unknown[];
+	};
+};
 /**
 * sort direction for queries
 * @category Query Types
 */
-type OrderByClause<T extends TObject2> = {
-	column: ScalarKeys<T>;
+type OrderByClause<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = {
+	column: ScalarKeys<T> | ScalarJsonPath<T>;
 	direction?: "ASC" | "DESC";
 };
 /**
@@ -215,6 +433,18 @@ interface PaginationOptions {
 	limit?: number;
 	offset?: number;
 }
+interface Cursor {
+	column: string;
+	value: SqliteScalar;
+}
+interface CursorInput extends Cursor {
+	direction: "next" | "prev";
+}
+interface CursorPageResult<T> {
+	data: T[];
+	nextCursor: Cursor | null;
+	prevCursor: Cursor | null;
+}
 /**
 * Options for `findMany`, `findPage`, and `findOne`.
 *
@@ -241,22 +471,36 @@ interface PaginationOptions {
 * @category Query Types
 * @category Query Types
 */
-interface FindOptions<T extends TObject2> extends PaginationOptions {
+/** @internal */
+type SelectableKeys<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarKeys<T> | ObjectKeys<T> | PrimitiveArrayKeys<T> | JsonPath<T>;
+interface FindOptions<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> extends PaginationOptions {
 	where?: WhereClause<T>;
 	orderBy?: OrderByClause<T> | OrderByClause<T>[];
 	include?: SubTableKeys<T>[];
+	select?: SelectableKeys<T>[];
+	includeDeleted?: boolean;
+	distinct?: boolean;
+	distinctOn?: (ScalarKeys<T> | ScalarJsonPath<T>)[];
 }
 /**
 * full record to insert
 * @category Query Types
 */
-type InsertData<T extends TObject2> = Infer<T>;
+type InsertData<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = Infer<T>;
 /**
 * update payload - must include the primary key
 * @category Query Types
 */
 type UpdateData<
-	T extends TObject2,
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
 	PK extends ScalarKeys<T>
 > = Pick<Infer<T>, PK> & Partial<Omit<Infer<T>, PK>>;
 /**
@@ -265,8 +509,14 @@ type UpdateData<
 */
 interface IndexDefinition {
 	name?: string;
-	columns: ColumnRef<string, TScalarSchema>[];
+	columns: Array<ColumnRef<string, TScalarSchema> | {
+		name: string;
+	}>;
 	unique?: boolean;
+	where?: string;
+	include?: Array<ColumnRef<string, TScalarSchema> | {
+		name: string;
+	}>;
 }
 /**
 * timestamp configuration for a table
@@ -318,10 +568,47 @@ type Entity<
 * table descriptor passed to createORM
 * @category Schema
 */
+interface EvictionConfig {
+	maxRows?: number;
+	ttlColumn?: string;
+	ttlMs?: number;
+	lruColumn?: string;
+}
+interface CompressionConfig {
+	columns: ColumnRef<string, TScalarSchema>[];
+	algorithm: "gzip" | "none";
+}
+interface SoftDeleteConfig {
+	column: string;
+}
+type GeneratedColumnConfig = {
+	[name: string]: {
+		expr: string;
+		type: TSchema2;
+	};
+};
+type GeneratedColumnValues<C extends GeneratedColumnConfig> = { [K in keyof C & string] : Static<C[K]["type"]> };
+type AugmentSchema<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	G extends GeneratedColumnConfig
+> = TObject2<T["properties"] & GeneratedColumnValues<G>>;
+type QuerySchema<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	G extends GeneratedColumnConfig | undefined
+> = [G] extends [undefined] ? T : [G] extends [GeneratedColumnConfig] ? AugmentSchema<T, G> : T;
 interface TableConfig<
-	T extends TObject2 = TObject2,
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	} = TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
 	PK extends string = string,
-	TS extends TimestampConfig = undefined
+	TS extends TimestampConfig = undefined,
+	G extends GeneratedColumnConfig | undefined = undefined
 > {
 	schema: T;
 	primaryKey: ColumnRef<PK>;
@@ -330,6 +617,10 @@ interface TableConfig<
 		indexes?: IndexDefinition[];
 	}>>;
 	timestamps?: TS;
+	eviction?: EvictionConfig;
+	compression?: CompressionConfig;
+	softDelete?: SoftDeleteConfig;
+	generated?: G;
 }
 /**
 * read-only metadata about the current database schema
@@ -347,7 +638,7 @@ interface MetaAccessors {
 * @category Relations
 */
 interface RelationEntry<
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any>>,
 	Owner extends keyof Tables,
 	Target extends keyof Tables
 > {
@@ -359,7 +650,7 @@ interface RelationEntry<
 * @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]> };
+type RelationsConfig<Tables extends Record<string, TableConfig<any, any, any, any>>> = { [K in keyof Tables & string]? : Array<{ [Target in keyof Tables & string] : RelationEntry<Tables, K, Target> }[keyof Tables & string]> };
 /**
 * @internal
 * @category Relations
@@ -376,7 +667,7 @@ type ScalarMergeNames<
 * @category Relations
 */
 type ScalarMergeType<
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string,
 	Name extends string
@@ -390,7 +681,7 @@ type ScalarMergeType<
 * @category Relations
 */
 type ScalarMerge<
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string
 > = { [K in ScalarMergeNames<Rels, Owner>] : ScalarMergeType<Tables, Rels, Owner, K> };
@@ -412,7 +703,7 @@ type SubMergeNames<
 * @category Relations
 */
 type SubMergeType<
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string,
 	Sub extends string,
@@ -428,7 +719,7 @@ type SubMergeType<
 * @category Relations
 */
 type SubMerge<
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string,
 	Sub extends string
@@ -450,8 +741,10 @@ type SubMerge<
 * @category Relations
 */
 type Materialized<
-	T extends TObject2,
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	Tables extends Record<string, TableConfig<any, 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>;
@@ -470,7 +763,9 @@ interface PageResult<T> {
 * @category Query Types
 */
 interface UpsertOptions<
-	T extends TObject2,
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
 	PK extends ScalarKeys<T>
 > {
 	data: InsertData<T>;
@@ -479,6 +774,35 @@ interface UpsertOptions<
 	update?: Array<ScalarKeys<T>>;
 }
 /**
+* bulk conditional update
+* @category Query Types
+*/
+interface UpdateWhereOptions<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	PK extends ScalarKeys<T>
+> {
+	where: WhereClause<T>;
+	data: Partial<Omit<Infer<T>, PK>>;
+	includeDeleted?: boolean;
+}
+/**
+* bulk upsert with conflict resolution
+* @category Query Types
+*/
+interface UpsertManyOptions<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	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
 */
@@ -584,11 +908,121 @@ interface SchemaDiff {
 * @category Migration
 */
 type SyncPolicy = "ignore" | "warn" | "error" | "auto" | ((diff: SchemaDiff, db: BunDatabase) => boolean | void);
+/** @category Query Types */
+type WindowFunction<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = {
+	rowNumber: true;
+} | {
+	rank: true;
+} | {
+	denseRank: true;
+} | {
+	lead: ScalarKeys<T> | ScalarJsonPath<T>;
+	offset?: number;
+} | {
+	lag: ScalarKeys<T> | ScalarJsonPath<T>;
+	offset?: number;
+};
+/** @category Query Types */
+interface WindowQueryOptions<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> {
+	partitionBy?: (ScalarKeys<T> | ScalarJsonPath<T>)[];
+	orderBy?: OrderByClause<T> | OrderByClause<T>[];
+	where?: WhereClause<T>;
+	limit?: number;
+	select: Record<string, WindowFunction<T>>;
+}
+/** @internal */
+type WindowFunctionResult<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	W extends WindowFunction<T>
+> = W extends {
+	lead: infer C extends string;
+} ? PathValue<T, C> | null : W extends {
+	lag: infer C extends string;
+} ? PathValue<T, C> | null : number;
+/** @category Query Types */
+type WindowResult<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	W extends Record<string, WindowFunction<T>>
+> = Array<{ [K in keyof W] : WindowFunctionResult<T, W[K]> }>;
+/** @category Query Types */
+type AggregationOp<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+} = TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = {
+	sum?: ScalarKeys<T> | ScalarJsonPath<T>;
+} | {
+	count?: "*" | ScalarKeys<T> | ScalarJsonPath<T>;
+} | {
+	avg?: ScalarKeys<T> | ScalarJsonPath<T>;
+} | {
+	min?: ScalarKeys<T> | ScalarJsonPath<T>;
+} | {
+	max?: ScalarKeys<T> | ScalarJsonPath<T>;
+};
+/** @category Query Types */
+interface AggregateOptions<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	A extends Record<string, AggregationOp<T>> = Record<string, AggregationOp<T>>
+> {
+	where?: WhereClause<T>;
+	groupBy?: readonly (ScalarKeys<T> | ScalarJsonPath<T>)[];
+	aggregations: A;
+	having?: { [K in keyof A]? : ScalarFilter<unknown> };
+	includeDeleted?: boolean;
+}
+/** @internal */
+type AggregationOpResult<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	Op extends AggregationOp<T>
+> = Op extends {
+	sum: string;
+} ? number | null : Op extends {
+	count: string;
+} ? number : Op extends {
+	avg: string;
+} ? number | null : Op extends {
+	min: infer C extends string;
+} ? PathValue<T, C> | null : Op extends {
+	max: infer C extends string;
+} ? PathValue<T, C> | null : never;
+/** @category Query Types */
+type AggregateResult<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	A extends Record<string, AggregationOp<T>>,
+	G extends readonly string[] | undefined = undefined
+> = Array<{ [K in keyof A] : AggregationOpResult<T, A[K]> } & (G extends readonly string[] ? { [K in G[number]] : PathValue<T, K> } : {})>;
+/** @category Observability */
+interface QueryMetrics {
+	table: string;
+	operation: string;
+	sql: string;
+	durationMs: number;
+	rowCount: number;
+}
+/** @category Observability */
+interface QueryMetricsHook {
+	onQuery: (meta: QueryMetrics) => 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";
+type TableOperation = "insert" | "insertMany" | "update" | "updateWhere" | "delete" | "deleteWhere" | "upsert" | "upsertMany" | "findById" | "findMany" | "findOne" | "findPage" | "findCursorPage" | "iterate" | "count" | "flush" | "aggregate" | "windowQuery";
 /**
 * broad categories for event listening
 * @category Events
@@ -626,7 +1060,58 @@ type ErrorPolicy = "throw" | "emit" | "emit-swallow" | "crash";
 * @category Setup
 */
 type UnlinkPolicy = true | "onlyGraceful" | "any" | false | undefined;
-import { TObject as TObject4 } from "typebox";
+import { TSchema as TSchema5 } from "typebox";
+import { TSchema as TSchema3 } from "typebox";
+/** @category Schema */
+interface SubTableConfig {
+	indexes?: IndexDefinition[];
+}
+interface TableDescriptor<
+	T extends TSchema3 & {
+		properties: Record<string, TSchema3>;
+	},
+	PK extends string,
+	TS extends TimestampConfig = undefined,
+	G extends GeneratedColumnConfig | undefined = undefined
+> extends TableConfig<T, PK, TS, G> {}
+interface TableConfigShape<
+	PK extends string,
+	TS extends TimestampConfig,
+	G extends GeneratedColumnConfig | undefined = undefined
+> {
+	primaryKey: ColumnRef<PK>;
+	indexes?: IndexDefinition[];
+	subTables?: Partial<Record<string, SubTableConfig>>;
+	timestamps?: TS;
+	eviction?: EvictionConfig;
+	compression?: CompressionConfig;
+	softDelete?: SoftDeleteConfig;
+	generated?: G;
+}
+/**
+* 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 TSchema3 & {
+		properties: Record<string, TSchema3>;
+	},
+	PK extends string,
+	TS extends TimestampConfig = undefined,
+	G extends GeneratedColumnConfig | undefined = undefined
+>(schema: T, configure: (columns: ColumnRefs<T>) => TableConfigShape<PK, TS, G>): TableDescriptor<T, PK, TS, G>;
 /** @category Events */
 type Listener = (payload: unknown) => void;
 /**
@@ -660,7 +1145,7 @@ interface LifecycleEventMap {
 * typed event listener api
 * @category Events
 */
-interface ORMEvents<Tables extends Record<string, TableConfig<any, any, any>>> {
+interface ORMEvents<Tables extends Record<string, TableDescriptor<any, 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) */
@@ -682,7 +1167,7 @@ declare class EventBus {
 	emit(event: string, payload: unknown): void;
 	emitIf(event: string, payload: unknown): void;
 }
-import { TObject as TObject3 } from "typebox";
+import { TSchema as TSchema4 } from "typebox";
 /** @category Advanced */
 type SqliteType = "TEXT" | "INTEGER" | "REAL" | "BLOB";
 /** @category Advanced */
@@ -692,6 +1177,14 @@ interface ColumnMeta {
 	nullable: boolean;
 	/** True if this is actually an `Optional` wrapper */
 	optional: boolean;
+	/** Path segments for flattened nested columns, e.g. ["Status", "Group"] */
+	path?: string[];
+	/** True if the underlying schema is a boolean (stored as INTEGER) */
+	isBoolean?: boolean;
+	/** True if this is a generated column */
+	generated?: boolean;
+	/** Expression for generated columns */
+	generatedExpr?: string;
 }
 /** @category Advanced */
 interface SubTableMeta {
@@ -700,20 +1193,57 @@ interface SubTableMeta {
 	/** e.g. "sales__lineItems" */
 	tableName: string;
 	/** Schema of a single item in the array */
-	itemSchema: TObject3;
+	itemSchema: TSchema4 & {
+		properties: Record<string, TSchema4>;
+	};
 	/** Columns of the sub-table row (owner PK is prepended automatically) */
 	columns: ColumnMeta[];
+	columnByName: Map<string, ColumnMeta>;
+	columnByPath: Map<string, ColumnMeta>;
 }
 /** @category Advanced */
 interface TableMeta {
 	tableName: string;
 	columns: ColumnMeta[];
 	subTables: SubTableMeta[];
+	/** Map from dotted path → ColumnMeta for O(1) resolution */
+	columnByPath: Map<string, ColumnMeta>;
+	/** Map from column name → ColumnMeta for O(1) resolution */
+	columnByName: Map<string, ColumnMeta>;
 }
 /** @category Advanced */
-declare function introspectTable(tableName: string, schema: TObject3): TableMeta;
+declare function introspectTable(tableName: string, schema: TSchema4 & {
+	properties: Record<string, TSchema4>;
+}, generated?: Array<{
+	name: string;
+	expr: string;
+	sqlType?: SqliteType;
+}>): TableMeta;
 /** @category Advanced */
 declare function buildCreateTableSQL(meta: TableMeta, primaryKey: string): string[];
+interface BatchWriterOptions {
+	maxBuffer?: number;
+	flushIntervalMs?: number;
+}
+declare class BatchWriter<
+	TInput,
+	TRow extends Record<string, unknown>
+> {
+	private buffer;
+	private readonly maxBuffer;
+	private readonly tableName;
+	private readonly db;
+	private readonly prepare;
+	private readonly onFlush?;
+	private timer?;
+	constructor(tableName: string, db: BunDatabase, opts: BatchWriterOptions, callbacks: {
+		prepare: (row: TInput) => TRow;
+		onFlush?: (rows: TRow[]) => void;
+	});
+	insert(row: TInput): void;
+	flush(): void;
+	close(): void;
+}
 /**
 * 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.
@@ -736,8 +1266,13 @@ declare function buildCreateTableSQL(meta: TableMeta, primaryKey: string): strin
 * ```
 */
 declare class Repository<
-	T extends TObject4,
-	PK extends ScalarKeys<T>,
+	TWrite extends TSchema5 & {
+		properties: Record<string, TSchema5>;
+	},
+	TQuery extends TSchema5 & {
+		properties: Record<string, TSchema5>;
+	},
+	PK extends ScalarKeys<TWrite>,
 	Mat = never,
 	TS = {}
 > {
@@ -752,17 +1287,31 @@ declare class Repository<
 	private _materialize?;
 	private _materializeMany?;
 	private _events?;
+	private _executor;
+	private readonly _codecs;
 	/** @internal */
 	setEventBus(bus: EventBus): void;
-	constructor(tableName: string, config: TableConfig<T, PK>, db: BunDatabase);
+	/** @internal */
+	setMetricsHook(hook?: (meta: QueryMetrics) => void): void;
+	constructor(tableName: string, config: TableConfig<TWrite, PK & string, TimestampConfig, GeneratedColumnConfig | undefined>, db: BunDatabase);
+	/** Ensure PK is selected when include is requested */
+	private _ensureSelectPk;
+	/**
+	* Two-phase row fetch: first get PKs via index, then fetch full rows.
+	* Avoids reading all columns for rows that don't match the WHERE clause.
+	*/
+	private _fetchRows;
 	/** 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;
+	/** Validate that a value is a valid SQLite scalar for use as a primary key */
+	private _assertPk;
 	private _emit;
 	private _migrate;
+	private _runEviction;
 	/**
 	* Validate and coerce data against the schema. Throws on invalid input.
 	*
@@ -774,7 +1323,7 @@ declare class Repository<
 	* // user is typed as Infer<typeof UserSchema>
 	* ```
 	*/
-	parse(data: unknown): Infer<T>;
+	parse(data: unknown): Infer<TWrite>;
 	/**
 	* Type-guard - returns true if data matches the schema.
 	*
@@ -787,7 +1336,7 @@ declare class Repository<
 	* }
 	* ```
 	*/
-	check(data: unknown): data is Infer<T>;
+	check(data: unknown): data is Infer<TWrite>;
 	/**
 	* Insert a single record. Returns the inserted entity.
 	*
@@ -802,7 +1351,7 @@ declare class Repository<
 	* });
 	* ```
 	*/
-	insert(data: InsertData<T>): Entity<Infer<T>, Mat, TS>;
+	insert(data: InsertData<TWrite>): Entity<Infer<TQuery>, Mat, TS>;
 	/**
 	* Insert many records in a single transaction.
 	*
@@ -816,8 +1365,20 @@ declare class Repository<
 	* ]);
 	* ```
 	*/
-	insertMany(records: InsertData<T>[]): Entity<Infer<T>, Mat, TS>[];
-	private _insertParsed;
+	insertMany(records: InsertData<TWrite>[]): Entity<Infer<TQuery>, Mat, TS>[];
+	/**
+	* Create a batch writer for high-throughput insert streaming.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* const writer = orm.users.createBatchWriter({ maxBuffer: 500 });
+	* writer.insert({ id: "u1", name: "alice" });
+	* writer.close();
+	* ```
+	*/
+	createBatchWriter(opts?: BatchWriterOptions): BatchWriter<InsertData<TWrite>, Record<string, unknown>>;
 	/**
 	* Insert or update on conflict. If the record exists (by conflict target),
 	* it updates the specified columns instead.
@@ -832,7 +1393,25 @@ declare class Repository<
 	* });
 	* ```
 	*/
-	upsert(opts: UpsertOptions<T, PK>): Entity<Infer<T>, Mat, TS>;
+	upsert(opts: UpsertOptions<TWrite, PK>): Entity<Infer<TQuery>, Mat, TS>;
+	/**
+	* Bulk upsert with conflict resolution.
+	* Sub-table rows are reconciled by deleting old rows and re-inserting.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* orm.users.upsertMany({
+	*   data: [
+	*     { id: "u1", name: "alice" },
+	*     { id: "u2", name: "bob" },
+	*   ],
+	*   conflictTarget: "id",
+	* });
+	* ```
+	*/
+	upsertMany(opts: UpsertManyOptions<TWrite, PK>): number;
 	/**
 	* Find a record by its primary key.
 	*
@@ -844,7 +1423,7 @@ declare class Repository<
 	* if (user) console.log(user.name);
 	* ```
 	*/
-	findById(id: Infer<T>[PK]): Entity<Infer<T>, Mat, TS> | null;
+	findById(id: Infer<TQuery>[PK]): Entity<Infer<TQuery>, Mat, TS> | null;
 	/** Internal findById without event emission - used by update() */
 	private _findByIdRaw;
 	/**
@@ -864,7 +1443,17 @@ declare class Repository<
 	* const orders = orm.orders.findMany({ include: ["lineItems"] });
 	* ```
 	*/
-	findMany(opts?: FindOptions<T>): Entity<Infer<T>, Mat, TS>[];
+	findMany<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): (SelectShape<TQuery, S> & TS & { [K in I[number]] : SubTableItem<TQuery, K>[] })[];
+	findMany<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): (SelectShape<TQuery, S> & TS)[];
+	findMany(opts?: FindOptions<TQuery>): Entity<Infer<TQuery>, Mat, TS>[];
 	/**
 	* Find many with total count - useful for pagination.
 	*
@@ -882,7 +1471,43 @@ declare class Repository<
 	* // page.limit, page.offset - what you passed in
 	* ```
 	*/
-	findPage(opts?: FindOptions<T>): PageResult<Entity<Infer<T>, Mat, TS>>;
+	findPage<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): PageResult<SelectShape<TQuery, S> & TS & { [K in I[number]] : SubTableItem<TQuery, K>[] }>;
+	findPage<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): PageResult<SelectShape<TQuery, S> & TS>;
+	findPage(opts?: FindOptions<TQuery>): PageResult<Entity<Infer<TQuery>, Mat, TS>>;
+	/**
+	* Cursor-based pagination (seek method). Avoids OFFSET degradation on
+	* large tables by using a boundary value from the previous page.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* const page = orm.orders.findCursorPage({
+	*   orderBy: { column: "DocumentDate", direction: "DESC" },
+	*   limit: 25,
+	* });
+	*
+	* const next = orm.orders.findCursorPage({
+	*   orderBy: { column: "DocumentDate", direction: "DESC" },
+	*   cursor: page.nextCursor!,
+	*   limit: 25,
+	* });
+	* ```
+	*/
+	findCursorPage(opts: {
+		where?: WhereClause<TQuery>;
+		orderBy: OrderByClause<TQuery>;
+		cursor?: CursorInput;
+		limit?: number;
+	}): CursorPageResult<Entity<Infer<TQuery>, Mat, TS>>;
 	/**
 	* Find a single record matching the given filters. Equivalent to `findMany`
 	* with `limit: 1`, but returns the entity directly (or `null`).
@@ -896,7 +1521,45 @@ declare class Repository<
 	* });
 	* ```
 	*/
-	findOne(opts?: FindOptions<T>): Entity<Infer<T>, Mat, TS> | null;
+	findOne<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): (SelectShape<TQuery, S> & TS & { [K in I[number]] : SubTableItem<TQuery, K>[] }) | null;
+	findOne<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): (SelectShape<TQuery, S> & TS) | null;
+	findOne(opts?: FindOptions<TQuery>): Entity<Infer<TQuery>, Mat, TS> | null;
+	/**
+	* Iterate over records matching the given filters, yielding one row at a time.
+	* Sub-tables are hydrated in windows to keep memory stable.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* for (const user of orm.users.iterate({ where: { active: { eq: true } } })) {
+	*   console.log(user.name);
+	* }
+	* ```
+	*/
+	iterate<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): Generator<SelectShape<TQuery, S> & TS & { [K in I[number]] : SubTableItem<TQuery, K>[] }>;
+	iterate<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): Generator<Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] }>;
+	iterate<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): Generator<SelectShape<TQuery, S> & TS>;
+	iterate(opts?: FindOptions<TQuery>): Generator<Entity<Infer<TQuery>, Mat, TS>>;
+	private _hydrateWindow;
 	/**
 	* Find many with resolved relations (n+1 safe). If you have cross-table
 	* relations configured, this eagerly loads them in a single batch query.
@@ -911,7 +1574,7 @@ declare class Repository<
 	* }
 	* ```
 	*/
-	findManyMaterialized(opts?: FindOptions<T>): Entity<Infer<T>, Mat, TS>[];
+	findManyMaterialized(opts?: FindOptions<TQuery>): Entity<Infer<TQuery>, Mat, TS>[];
 	/**
 	* Count records matching the given filters.
 	*
@@ -923,7 +1586,54 @@ declare class Repository<
 	* const adults = orm.users.count({ age: { gte: 18 } });
 	* ```
 	*/
-	count(where?: WhereClause<T>): number;
+	count(where?: WhereClause<TQuery>): number;
+	/**
+	* Run aggregate queries (sum, count, avg, min, max) with optional
+	* grouping and filtering.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* orm.orders.aggregate({
+	*   aggregations: { total: { sum: "amount" } },
+	* });
+	*
+	* orm.orders.aggregate({
+	*   groupBy: ["status"],
+	*   aggregations: { count: { count: "*" }, avgAmount: { avg: "amount" } },
+	* });
+	* ```
+	*/
+	aggregate<
+		const A extends Record<string, AggregationOp<TQuery>>,
+		const G extends readonly (ScalarKeys<TQuery> | ScalarJsonPath<TQuery>)[] | undefined = undefined
+	>(opts: AggregateOptions<TQuery, A> & {
+		groupBy?: G;
+	}): AggregateResult<TQuery, A, G>;
+	/**
+	* Run window function queries (rowNumber, rank, denseRank, lead, lag)
+	* with partitioning and ordering.
+	*
+	* @group Reading
+	*
+	* @example
+	* ```ts
+	* orm.orders.windowQuery({
+	*   partitionBy: ["Status__Group"],
+	*   orderBy: [{ column: "DocumentDate", direction: "DESC" }],
+	*   select: {
+	*     rowNumber: { rowNumber: true },
+	*     rank: { rank: true },
+	*     leadTotal: { lead: "TotalTurnover", offset: 1 },
+	*   },
+	*   limit: 100,
+	* });
+	* ```
+	*/
+	windowQuery<const W extends Record<string, WindowFunction<TQuery>>>(opts: WindowQueryOptions<TQuery> & {
+		select: W;
+	}): WindowResult<TQuery, W>;
 	/**
 	* Update a record - must include the primary key. Returns the updated
 	* entity, or `null` if no record matched.
@@ -935,7 +1645,22 @@ declare class Repository<
 	* orm.users.update({ id: "u1", name: "alice smith" });
 	* ```
 	*/
-	update(data: UpdateData<T, PK>): Entity<Infer<T>, Mat, TS> | null;
+	update(data: UpdateData<TWrite, PK>): Entity<Infer<TQuery>, Mat, TS> | null;
+	/**
+	* Update multiple records matching the given filters.
+	* Returns the number of rows changed.
+	*
+	* @group Writing
+	*
+	* @example
+	* ```ts
+	* orm.users.updateWhere({
+	*   where: { status: { eq: "pending" } },
+	*   data: { status: { group: "completed" } },
+	* });
+	* ```
+	*/
+	updateWhere(opts: UpdateWhereOptions<TWrite, PK>): number;
 	/**
 	* Delete a record by its primary key. Returns `true` if a record was deleted.
 	*
@@ -946,7 +1671,7 @@ declare class Repository<
 	* const deleted = orm.users.deleteById("u1");
 	* ```
 	*/
-	deleteById(id: Infer<T>[PK]): boolean;
+	deleteById(id: Infer<TWrite>[PK]): boolean;
 	/**
 	* Delete records matching the given filters. Returns the number of rows deleted.
 	*
@@ -957,7 +1682,7 @@ declare class Repository<
 	* const removed = orm.users.deleteWhere({ status: { eq: "banned" } });
 	* ```
 	*/
-	deleteWhere(where: WhereClause<T>): number;
+	deleteWhere(where: WhereClause<TQuery>): number;
 	/**
 	* Truncate the table and all sub-tables. Deletes all rows but keeps the schema.
 	*
@@ -993,9 +1718,9 @@ declare class Repository<
 	* );
 	* ```
 	*/
-	raw<R = unknown>(sql: string, ...params: unknown[]): R[];
+	raw<R = DBRow>(sql: string, ...params: DBValue[]): R[];
 }
-declare class RelationBuilder<Tables extends Record<string, TableConfig<any, any, any>>> {
+declare class RelationBuilder<Tables extends Record<string, TableDescriptor<any, any, any, any>>> {
 	private readonly tables;
 	private readonly relations;
 	constructor(tables: Tables);
@@ -1025,16 +1750,14 @@ declare class RelationBuilder<Tables extends Record<string, TableConfig<any, any
 	build(): TypedRelation[];
 }
 /** @category Relations */
-declare function createRelationBuilder<T extends Record<string, TableConfig<any, any, any>>>(tables: T): RelationBuilder<T>;
+declare function createRelationBuilder<T extends Record<string, TableDescriptor<any, 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>;
@@ -1051,7 +1774,7 @@ declare class MetaStore {
 	private getRow;
 	private setRow;
 	private getValidatedJSON;
-	private setValidatedJSON;
+	private validateAndSetJSON;
 	getString(key: string): string | null;
 	setString(key: string, value: string): void;
 	getJSON<T>(key: string): T | null;
@@ -1075,7 +1798,7 @@ declare class MetaStore {
 * @category Lifecycle
 */
 interface ORMContext<
-	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > {
 	orm: foxdb<T, Rels>;
@@ -1093,7 +1816,7 @@ interface ORMContext<
 * @category Lifecycle
 */
 type LifecycleHook<
-	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > = (ctx: ORMContext<T, Rels>) => void | Promise<void>;
 /**
@@ -1101,7 +1824,7 @@ type LifecycleHook<
 * @category Lifecycle
 */
 declare class LifecycleManager<
-	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > {
 	private startHooks;
@@ -1142,6 +1865,10 @@ interface CreateORMBaseOptions {
 	busyTimeout?: number;
 	synchronous?: "OFF" | "NORMAL" | "FULL" | "EXTRA";
 	mmapSize?: number;
+	autoVacuum?: "incremental" | "full" | false;
+	vacuumIntervalMs?: number;
+	/** disable fsync during large initial loads */
+	bulkLoadMode?: boolean;
 }
 /**
 * Options passed to `createORM`.
@@ -1172,7 +1899,7 @@ interface CreateORMBaseOptions {
 * ```
 */
 interface CreateORMOptions<
-	T extends Record<string, TableConfig<any, any, any>> = Record<string, TableConfig<any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > extends CreateORMBaseOptions {
 	/** table schemas */
@@ -1215,6 +1942,8 @@ interface CreateORMOptions<
 	errorPolicy?: ErrorPolicy;
 	/** delete db files on exit */
 	unlinkDbFilesOnExit?: UnlinkPolicy;
+	/** observability hooks */
+	hooks?: QueryMetricsHook;
 }
 /**
 * The ORM object returned by `createORM`.
@@ -1266,15 +1995,19 @@ interface CreateORMOptions<
 * ```
 */
 type foxdb<
-	Tables extends Record<string, TableConfig<any, any, any>>,
+	Tables extends Record<string, TableDescriptor<any, 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 } & {
+> = { [K in keyof Tables] : Tables[K] extends TableDescriptor<infer TWrite extends TSchema6 & {
+	properties: Record<string, TSchema6>;
+}, infer PKName extends string, infer Timestamps, infer G extends GeneratedColumnConfig | undefined> ? Repository<TWrite, QuerySchema<TWrite, G>, PKName extends ScalarKeys<TWrite> ? PKName : never, Materialized<TWrite, Tables, Rels, K & string>, TimestampShape<Timestamps>> : never } & {
 	/** run a transaction */
 	_transaction<R>(fn: () => R): R;
 	/** close the database */
 	_close(): void;
 	/** read-only metadata */
 	_meta: MetaAccessors;
+	/** toggle bulk-load mode (disables synchronous fsync) */
+	_setBulkLoadMode(enabled: boolean): void;
 	/** 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) */
@@ -1290,69 +2023,9 @@ type foxdb<
 };
 /** create a typed orm instance backed by sqlite */
 declare function createORM<
-	const T extends Record<string, TableConfig<any, any, any>>,
+	const T extends Record<string, TableDescriptor<any, 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;
@@ -1460,4 +2133,4 @@ interface DesiredTable {
 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 };
+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, QueryMetricsHook, QueryMetrics, PageResult, OrderByClause, ORMEvents, ORMErrorContext, ORMError, ORMContext, Migration, MigrateOptions, MetaStore, Materialized, Listener, LifecycleManager, LifecycleHook, LifecycleEventMap, InspectorTable, InspectorIndex, InspectorColumn, InsertData, Infer, IndexDefinition, GeneratedColumnConfig, FindOptions, EventBus, ErrorPolicy2 as ErrorPolicy, Entity, DesiredTable, DatabaseOptions, DEFAULT_TIMESTAMP_NAMES, CreateORMOptions, CreateORMBaseOptions, ColumnRefs, ColumnRef, ColumnMeta, BunStatement, BunDatabase, BroadOperation, BatchWriterOptions, BatchWriter, ArrayOfObjectProperties, AggregationOp, AggregateOptions };