@xwxfox/foxdb 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { TSchema as TSchema6 } from "typebox";
-import { TObject as TObject2, TArray, TSchema as TSchema2, TProperties, TOptional as TOptional2, Static } from "typebox";
+import { TSchema as TSchema10 } from "typebox";
+import { TObject as TObject2, TArray, TSchema as TSchema2, TProperties, TOptional as TOptional2, TString as TString2, TLiteral as TLiteral2, 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>;
@@ -53,7 +53,16 @@ interface TypedRelation<
 	kind: K;
 	as: A;
 }
-import { Database, Statement } from "bun:sqlite";
+import { Database, SQLQueryBindings, Statement } from "bun:sqlite";
+type SweepTask = () => void;
+declare class TableScheduler {
+	private timers;
+	private timersByName;
+	private tasks;
+	schedule(name: string, intervalMs: number, task: SweepTask): void;
+	clear(name: string): void;
+	clearAll(): void;
+}
 /**
 * prepared sqlite statement
 * @category Database
@@ -92,7 +101,10 @@ declare class BunDatabase {
 	/** underlying bun:sqlite database */
 	readonly db: Database;
 	/** scheduler for table maintenance tasks */
-	readonly scheduler;
+	readonly scheduler: TableScheduler;
+	private extensionStatus;
+	/** Tracks nesting depth of user-initiated transactions */
+	_txDepth: number;
 	constructor(opts?: DatabaseOptions);
 	/** execute ddl (create table, index, etc) */
 	exec(sql: string): void;
@@ -106,8 +118,18 @@ declare class BunDatabase {
 	prepare(sql: string): BunStatement;
 	/** set synchronous pragma for bulk load or normal operation */
 	setSynchronous(mode: "OFF" | "NORMAL" | "FULL" | "EXTRA"): void;
+	/**
+	* Drop one cached statement without finalizing it. Recovery path for
+	* holders (see QueryExecutor) whose cached object was finalized
+	* out-of-band: the shared entry may reference the same dead object, so
+	* it must go too, otherwise the next prepare() would hand the corpse
+	* right back.
+	*/
+	dropCached(sql: string): void;
 	/** clear the statement cache */
 	clearCache(): void;
+	/** get stmt stats from extension. Returns [] if ran without --feature DEBUG_SQL_BUILDING */
+	getStmtStats(sql: string): unknown;
 }
 type JsonValue = null | boolean | number | string | JsonValue[] | {
 	[key: string]: JsonValue;
@@ -293,8 +315,18 @@ 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[];
 } | {
@@ -406,7 +438,7 @@ type ArrayFilter<V> = {
 */
 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>> } & {
+}> = { [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> | SubTableScalarPath<T>)]? : PathValue<T, K> extends Array<infer Item> ? ArrayFilter<Item> : ScalarFilter<PathValue<T, K>> } & {
 	AND?: WhereClause<T>[];
 	OR?: WhereClause<T>[];
 	NOT?: WhereClause<T>;
@@ -475,6 +507,54 @@ interface CursorPageResult<T> {
 type SelectableKeys<T extends TSchema2 & {
 	properties: Record<string, TSchema2>;
 }> = ScalarKeys<T> | ObjectKeys<T> | PrimitiveArrayKeys<T> | JsonPath<T>;
+type FilterableFields<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarKeys<T> | ObjectKeys<T> | ScalarJsonPath<T> | SubTableScalarPath<T>;
+/**
+* Filterable fields excluding sub-table paths.
+* Used when no sub-tables have been included via .include().
+* @category Query Types
+*/
+type FilterableFieldsBase<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarKeys<T> | ObjectKeys<T> | ScalarJsonPath<T>;
+/**
+* Filterable fields that include ONLY sub-table paths for the specified tables.
+* @internal
+*/
+type IncludedSubTablePaths<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	I extends string
+> = Extract<SubTableScalarPath<T>, `${I}.${string}`>;
+type FilterableForInclude<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	I extends string | undefined
+> = [I] extends [never] ? FilterableFieldsBase<T> : [I] extends [undefined] ? FilterableFieldsBase<T> : FilterableFieldsBase<T> | IncludedSubTablePaths<T, I & string>;
+type FieldType<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	P extends FilterableFields<T>
+> = PathValue<T, P>;
+type ArrayFilterableFields<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = PrimitiveArrayKeys<T>;
+type ArrayItemType<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	P extends ArrayFilterableFields<T>
+> = UnwrapOptional<T["properties"][P]> extends TArray<infer Item> ? Static<Item> : never;
+type OrderableFields<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarKeys<T> | ScalarJsonPath<T>;
+type DistinctableFields<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = ScalarKeys<T> | ScalarJsonPath<T>;
 interface FindOptions<T extends TSchema2 & {
 	properties: Record<string, TSchema2>;
 }> extends PaginationOptions {
@@ -581,6 +661,39 @@ interface CompressionConfig {
 interface SoftDeleteConfig {
 	column: string;
 }
+/**
+* Full-text search configuration for a table.
+* - `true` indexes every TEXT column.
+* - `{ columns }` indexes an explicit, type-checked column list.
+* @category Schema
+*/
+type FTSConfig = true | {
+	/** Columns to index. Omit to index all TEXT columns. */
+	columns?: readonly ColumnRef<string, TScalarSchema>[];
+	/** FTS5 tokenizer directive, e.g. "porter unicode61", "trigram". Default: "unicode61". */
+	tokenizer?: string;
+	/** FTS5 prefix-index sizes, e.g. [2, 3]. */
+	prefix?: readonly number[];
+};
+/** True when a table has FTS enabled. @internal */
+type FTSEnabled<F> = [F] extends [undefined] ? false : [F] extends [never] ? false : true;
+/** Union of flattened TEXT column names (top-level + nested `a__b`). @internal */
+type FTSAllTextFields<T extends TSchema2 & {
+	properties: Record<string, TSchema2>;
+}> = { [K in keyof ColumnRefs<T>] : ColumnRefs<T>[K] extends ColumnRef<infer N, infer S> ? S extends TString2 ? N : S extends TLiteral2<string> ? N : never : never }[keyof ColumnRefs<T>];
+/** Names extracted from an explicit `{ columns }` FTS config. @internal */
+type FTSConfiguredFields<F> = F extends {
+	columns: readonly (infer C)[];
+} ? C extends ColumnRef<infer N, TScalarSchema> ? N : never : never;
+/** The searchable field-name union for a table given its FTS config. @internal */
+type FTSFields<
+	T extends TSchema2 & {
+		properties: Record<string, TSchema2>;
+	},
+	F
+> = [F] extends [undefined] ? never : [F] extends [false] ? never : F extends {
+	columns: readonly ColumnRef<string, TScalarSchema>[];
+} ? FTSConfiguredFields<F> : FTSAllTextFields<T>;
 type GeneratedColumnConfig = {
 	[name: string]: {
 		expr: string;
@@ -608,7 +721,8 @@ interface TableConfig<
 	},
 	PK extends string = string,
 	TS extends TimestampConfig = undefined,
-	G extends GeneratedColumnConfig | undefined = undefined
+	G extends GeneratedColumnConfig | undefined = undefined,
+	F extends FTSConfig | undefined = undefined
 > {
 	schema: T;
 	primaryKey: ColumnRef<PK>;
@@ -621,6 +735,9 @@ interface TableConfig<
 	compression?: CompressionConfig;
 	softDelete?: SoftDeleteConfig;
 	generated?: G;
+	fts?: F;
+	/** Auto-index TEXT columns on sub-tables. Defaults to false. Set true to enable. */
+	autoIndex?: boolean;
 }
 /**
 * read-only metadata about the current database schema
@@ -638,7 +755,7 @@ interface MetaAccessors {
 * @category Relations
 */
 interface RelationEntry<
-	Tables extends Record<string, TableConfig<any, any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any, any>>,
 	Owner extends keyof Tables,
 	Target extends keyof Tables
 > {
@@ -650,7 +767,7 @@ interface RelationEntry<
 * @internal
 * @category Relations
 */
-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]> };
+type RelationsConfig<Tables extends Record<string, TableConfig<any, 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
@@ -667,7 +784,7 @@ type ScalarMergeNames<
 * @category Relations
 */
 type ScalarMergeType<
-	Tables extends Record<string, TableConfig<any, any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string,
 	Name extends string
@@ -681,7 +798,7 @@ type ScalarMergeType<
 * @category Relations
 */
 type ScalarMerge<
-	Tables extends Record<string, TableConfig<any, any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string
 > = { [K in ScalarMergeNames<Rels, Owner>] : ScalarMergeType<Tables, Rels, Owner, K> };
@@ -703,7 +820,7 @@ type SubMergeNames<
 * @category Relations
 */
 type SubMergeType<
-	Tables extends Record<string, TableConfig<any, any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string,
 	Sub extends string,
@@ -719,7 +836,7 @@ type SubMergeType<
 * @category Relations
 */
 type SubMerge<
-	Tables extends Record<string, TableConfig<any, any, any, any>>,
+	Tables extends Record<string, TableConfig<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[],
 	Owner extends string,
 	Sub extends string
@@ -744,7 +861,7 @@ type Materialized<
 	T extends TSchema2 & {
 		properties: Record<string, TSchema2>;
 	},
-	Tables extends Record<string, TableConfig<any, any, any, any>>,
+	Tables extends Record<string, TableConfig<any, 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>;
@@ -958,15 +1075,15 @@ type AggregationOp<T extends TSchema2 & {
 } = TSchema2 & {
 	properties: Record<string, TSchema2>;
 }> = {
-	sum?: ScalarKeys<T> | ScalarJsonPath<T>;
+	sum?: ScalarKeys<T> | ScalarJsonPath<T> | SubTableScalarPath<T>;
 } | {
-	count?: "*" | ScalarKeys<T> | ScalarJsonPath<T>;
+	count?: "*" | ScalarKeys<T> | ScalarJsonPath<T> | SubTableScalarPath<T>;
 } | {
-	avg?: ScalarKeys<T> | ScalarJsonPath<T>;
+	avg?: ScalarKeys<T> | ScalarJsonPath<T> | SubTableScalarPath<T>;
 } | {
-	min?: ScalarKeys<T> | ScalarJsonPath<T>;
+	min?: ScalarKeys<T> | ScalarJsonPath<T> | SubTableScalarPath<T>;
 } | {
-	max?: ScalarKeys<T> | ScalarJsonPath<T>;
+	max?: ScalarKeys<T> | ScalarJsonPath<T> | SubTableScalarPath<T>;
 };
 /** @category Query Types */
 interface AggregateOptions<
@@ -980,6 +1097,13 @@ interface AggregateOptions<
 	aggregations: A;
 	having?: { [K in keyof A]? : ScalarFilter<unknown> };
 	includeDeleted?: boolean;
+	/**
+	* Aggregate over a sub-table (array relationship) instead of the main table.
+	* Provide the field name of the sub-table (e.g. "PurchaseLineItems").
+	* Column references in aggregations/where/groupBy are resolved against the
+	* sub-table's item schema.
+	*/
+	subTable?: string;
 }
 /** @internal */
 type AggregationOpResult<
@@ -1060,7 +1184,7 @@ type ErrorPolicy = "throw" | "emit" | "emit-swallow" | "crash";
 * @category Setup
 */
 type UnlinkPolicy = true | "onlyGraceful" | "any" | false | undefined;
-import { TSchema as TSchema5 } from "typebox";
+import { TSchema as TSchema8 } from "typebox";
 import { TSchema as TSchema3 } from "typebox";
 /** @category Schema */
 interface SubTableConfig {
@@ -1072,12 +1196,14 @@ interface TableDescriptor<
 	},
 	PK extends string,
 	TS extends TimestampConfig = undefined,
-	G extends GeneratedColumnConfig | undefined = undefined
-> extends TableConfig<T, PK, TS, G> {}
+	G extends GeneratedColumnConfig | undefined = undefined,
+	F extends FTSConfig | undefined = undefined
+> extends TableConfig<T, PK, TS, G, F> {}
 interface TableConfigShape<
 	PK extends string,
 	TS extends TimestampConfig,
-	G extends GeneratedColumnConfig | undefined = undefined
+	G extends GeneratedColumnConfig | undefined = undefined,
+	F extends FTSConfig | undefined = undefined
 > {
 	primaryKey: ColumnRef<PK>;
 	indexes?: IndexDefinition[];
@@ -1087,6 +1213,9 @@ interface TableConfigShape<
 	compression?: CompressionConfig;
 	softDelete?: SoftDeleteConfig;
 	generated?: G;
+	fts?: F;
+	/** Auto-index TEXT columns on sub-tables. Defaults to false. Set true to enable. */
+	autoIndex?: boolean;
 }
 /**
 * Describe a table schema + config for `createORM`.
@@ -1110,8 +1239,9 @@ declare function table<
 	},
 	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>;
+	G extends GeneratedColumnConfig | undefined = undefined,
+	const F extends FTSConfig | undefined = undefined
+>(schema: T, configure: (columns: ColumnRefs<T>) => TableConfigShape<PK, TS, G, F>): TableDescriptor<T, PK, TS, G, F>;
 /** @category Events */
 type Listener = (payload: unknown) => void;
 /**
@@ -1145,7 +1275,7 @@ interface LifecycleEventMap {
 * typed event listener api
 * @category Events
 */
-interface ORMEvents<Tables extends Record<string, TableDescriptor<any, any, any, any>>> {
+interface ORMEvents<Tables extends Record<string, TableDescriptor<any, 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) */
@@ -1170,6 +1300,18 @@ declare class EventBus {
 import { TSchema as TSchema4 } from "typebox";
 /** @category Advanced */
 type SqliteType = "TEXT" | "INTEGER" | "REAL" | "BLOB";
+/**
+* Pre-classified decode strategy for hydration.
+* Avoids per-value heuristic checks by knowing the column's type at schema time.
+*/
+declare const enum ColDecode {
+	/** Scalar string or number – pass through, no processing */
+	Scalar = 0,
+	/** JSON object/array stored as TEXT – always JSON.parse */
+	Json = 1,
+	/** Boolean stored as INTEGER – convert 0/1 to false/true */
+	Bool = 2
+}
 /** @category Advanced */
 interface ColumnMeta {
 	name: string;
@@ -1185,22 +1327,44 @@ interface ColumnMeta {
 	generated?: boolean;
 	/** Expression for generated columns */
 	generatedExpr?: string;
+	/** Pre-built getter function for flattenRow (set during introspectTable) */
+	_get?: (obj: Record<string, unknown>) => unknown;
+	/**
+	* Pre-classified decode strategy for hydration.
+	* Scalar=0 (no processing), Json=1 (JSON.parse), Bool=2 (v===1).
+	*/
+	decode?: ColDecode;
+	/**
+	* If path.length <= 1, pre-stored target key for direct property assignment
+	* (avoids branching in the hydration hot loop).
+	*/
+	_targetKey?: string;
 }
-/** @category Advanced */
-interface SubTableMeta {
-	/** e.g. "lineItems" */
+type SubTableMetaCommon = {
 	fieldName: string;
-	/** e.g. "sales__lineItems" */
 	tableName: string;
-	/** Schema of a single item in the array */
-	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>;
-}
+	/** Pre-built INSERT column SQL fragment, e.g. `"_owner_id", "_index", "col1", "col2"` */
+	insertColsSql?: string;
+	/** Pre-built INSERT value group fragment, e.g. `(?, ?, ?, ?)` */
+	insertValueGroup?: string;
+	/** Ordered column names for INSERT */
+	insertColumnNames?: string[];
+};
+/** @category Advanced */
+type SubTableMeta = SubTableMetaCommon & ({
+	isScalar: true;
+	scalarType: SqliteType;
+	itemSchema?: never;
+} | {
+	isScalar?: false;
+	scalarType?: never;
+	itemSchema?: TSchema4 & {
+		properties: Record<string, TSchema4>;
+	};
+});
 /** @category Advanced */
 interface TableMeta {
 	tableName: string;
@@ -1210,6 +1374,17 @@ interface TableMeta {
 	columnByPath: Map<string, ColumnMeta>;
 	/** Map from column name → ColumnMeta for O(1) resolution */
 	columnByName: Map<string, ColumnMeta>;
+	/** The PK column name of the parent table - used for sub-table filter SQL */
+	primaryKey?: string;
+	/** Non-generated columns - pre-filtered for flattenRow / INSERT / UPDATE */
+	insertColumns: ColumnMeta[];
+	/** Precomputed ordered column names for INSERT SQL */
+	insertColumnNames: string[];
+	/**
+	* Pre-compiled fast hydration function (no codecs, no select/include filtering).
+	* Populated by introspectTable. Use hydrateRowFastCompiled for the common path.
+	*/
+	_hydrateFast?: (flat: Record<string, unknown>) => Record<string, unknown>;
 }
 /** @category Advanced */
 declare function introspectTable(tableName: string, schema: TSchema4 & {
@@ -1218,9 +1393,256 @@ declare function introspectTable(tableName: string, schema: TSchema4 & {
 	name: string;
 	expr: string;
 	sqlType?: SqliteType;
-}>): TableMeta;
+}>, primaryKey?: string): TableMeta;
 /** @category Advanced */
-declare function buildCreateTableSQL(meta: TableMeta, primaryKey: string): string[];
+declare function buildCreateTableSQL(meta: TableMeta, primaryKey: string, autoIndex?: boolean, onDeleteBehavior?: "native" | "foxdb" | "none"): string[];
+import { TSchema as TSchema6 } from "typebox";
+/**
+* Runtime shape of any filter - independent of the column's value type
+*/
+type FilterShape = {
+	eq: unknown;
+} | {
+	ne: unknown;
+} | {
+	gt: unknown;
+} | {
+	gte: unknown;
+} | {
+	lt: unknown;
+} | {
+	lte: unknown;
+} | {
+	like: string;
+} | {
+	between: [unknown, unknown];
+} | {
+	in: readonly unknown[];
+} | {
+	notIn: readonly unknown[];
+} | {
+	isNull: true;
+} | {
+	isNotNull: true;
+} | {
+	arraySome: unknown;
+} | {
+	arrayNot: unknown;
+} | {
+	isEmpty: boolean;
+} | {
+	fastArraySome: unknown;
+} | {
+	fastArrayNot: unknown;
+} | {
+	fastArrayIsEmpty: boolean;
+};
+interface WhereResult {
+	sql: string;
+	params: SQLQueryBindings[];
+}
+type ConditionNode = {
+	type: "condition";
+	field: string;
+	filter: FilterShape;
+} | {
+	type: "raw";
+	sql: string;
+	params: SQLQueryBindings[];
+} | {
+	type: "and";
+	children: ConditionNode[];
+} | {
+	type: "or";
+	children: ConditionNode[];
+} | {
+	type: "not";
+	child: ConditionNode;
+} | {
+	type: "nested";
+	field: string;
+	children: ConditionNode[];
+};
+interface InternalBuilderState {
+	nodes: ConditionNode[];
+	orderBy: Array<{
+		column: string;
+		direction: "ASC" | "DESC";
+	}>;
+	limit: number | undefined;
+	offset: number | undefined;
+	select: string[] | undefined;
+	include: string[] | undefined;
+	includeDeleted: boolean;
+	distinct: boolean;
+	distinctOn: string[] | undefined;
+}
+interface AggregateBuilderState {
+	aggregations: Record<string, {
+		op: string;
+		field: string;
+	}>;
+	groupBy: string[] | undefined;
+	having: ConditionNode[];
+	includeDeleted: boolean;
+}
+declare function buildWhereFromNodes(nodes: ConditionNode[], softDeleteColumn: string | undefined, meta: TableMeta | undefined): WhereResult;
+declare class FilterBuilder<
+	TQuery extends TSchema6 & {
+		properties: Record<string, TSchema6>;
+	},
+	TResult,
+	I extends SubTableKeys<TQuery> | undefined = undefined
+> {
+	private _executor?;
+	private _asyncExecutor?;
+	_nodes: ConditionNode[];
+	private _orderByFields;
+	private _limitValue;
+	private _offsetValue;
+	private _selectFields;
+	private _includeFields;
+	private _includeDeletedValue;
+	private _distinctValue;
+	private _distinctOnFields;
+	constructor(_executor?: ((state: InternalBuilderState) => TResult) | undefined, _asyncExecutor?: ((state: InternalBuilderState) => Promise<TResult>) | undefined);
+	private _assertExecutor;
+	private _collectState;
+	equals<P extends FilterableForInclude<TQuery, I>>(field: P, value: FieldType<TQuery, P>): this;
+	notEquals<P extends FilterableForInclude<TQuery, I>>(field: P, value: FieldType<TQuery, P>): this;
+	greaterThan<P extends FilterableForInclude<TQuery, I>>(field: P, value: FieldType<TQuery, P>): this;
+	greaterThanOrEqual<P extends FilterableForInclude<TQuery, I>>(field: P, value: FieldType<TQuery, P>): this;
+	lessThan<P extends FilterableForInclude<TQuery, I>>(field: P, value: FieldType<TQuery, P>): this;
+	lessThanOrEqual<P extends FilterableForInclude<TQuery, I>>(field: P, value: FieldType<TQuery, P>): this;
+	between<P extends FilterableForInclude<TQuery, I>>(field: P, min: FieldType<TQuery, P>, max: FieldType<TQuery, P>): this;
+	like<P extends FilterableForInclude<TQuery, I>>(field: P, pattern: string): this;
+	contains<P extends FilterableForInclude<TQuery, I>>(field: P, substring: string): this;
+	startsWith<P extends FilterableForInclude<TQuery, I>>(field: P, prefix: string): this;
+	endsWith<P extends FilterableForInclude<TQuery, I>>(field: P, suffix: string): this;
+	in<P extends FilterableForInclude<TQuery, I>>(field: P, values: FieldType<TQuery, P>[]): this;
+	notIn<P extends FilterableForInclude<TQuery, I>>(field: P, values: FieldType<TQuery, P>[]): this;
+	isNull<P extends FilterableForInclude<TQuery, I>>(field: P): this;
+	isNotNull<P extends FilterableForInclude<TQuery, I>>(field: P): this;
+	arraySome<P extends ArrayFilterableFields<TQuery>>(field: P, value: ArrayItemType<TQuery, P>): this;
+	arrayNone<P extends ArrayFilterableFields<TQuery>>(field: P, value: ArrayItemType<TQuery, P>): this;
+	isEmpty<P extends ArrayFilterableFields<TQuery>>(field: P): this;
+	isNotEmpty<P extends ArrayFilterableFields<TQuery>>(field: P): this;
+	arrayEvery<P extends ArrayFilterableFields<TQuery>>(_field: P, _value: ArrayItemType<TQuery, P>): this;
+	arrayContainsAll<P extends ArrayFilterableFields<TQuery>>(_field: P, _values: ArrayItemType<TQuery, P>[]): this;
+	arrayLength<P extends ArrayFilterableFields<TQuery>>(_field: P, _op: "eq" | "ne" | "gt" | "gte" | "lt" | "lte", _value: number): this;
+	nested<P extends FilterableForInclude<TQuery, I>>(field: P, callback: (q: FilterBuilder<TQuery, unknown>) => void): this;
+	and(callback: (q: FilterBuilder<TQuery, unknown>) => void): this;
+	or(callback: (q: FilterBuilder<TQuery, unknown>) => void): this;
+	not(callback: (q: FilterBuilder<TQuery, unknown>) => void): this;
+	raw(sql: string, params?: SQLQueryBindings[]): this;
+	orderBy<P extends OrderableFields<TQuery>>(field: P, direction?: "ASC" | "DESC"): this;
+	thenBy<P extends OrderableFields<TQuery>>(field: P, direction?: "ASC" | "DESC"): this;
+	limit(n: number): this;
+	offset(n: number): this;
+	select<S extends SelectableKeys<TQuery>[]>(...fields: S): this;
+	include<Inc extends SubTableKeys<TQuery>[]>(...relations: Inc): FilterBuilder<TQuery, TResult, Inc[number]>;
+	distinct(): this;
+	distinctOn<D extends DistinctableFields<TQuery>[]>(...fields: D): this;
+	includeDeleted(): this;
+	exec(): TResult;
+	execAsync(): Promise<TResult>;
+	execThrowable(): TResult;
+}
+declare class AggregateBuilder<TQuery extends TSchema6 & {
+	properties: Record<string, TSchema6>;
+}> {
+	private _executor;
+	private _asyncExecutor?;
+	private _aggregations;
+	private _groupByFields;
+	private _havingNodes;
+	private _whereNodes;
+	private _includeDeletedValue;
+	constructor(_executor: (state: AggregateBuilderState) => Record<string, unknown>[], _asyncExecutor?: ((state: AggregateBuilderState) => Promise<Record<string, unknown>[]>) | undefined);
+	sum(field: string, alias: string): this;
+	count(field: string, alias: string): this;
+	avg(field: string, alias: string): this;
+	min(field: string, alias: string): this;
+	max(field: string, alias: string): this;
+	groupBy<G extends string[]>(...fields: G): this;
+	having(callback: (q: FilterBuilder<TQuery, unknown>) => void): this;
+	includeDeleted(): this;
+	exec(): Record<string, unknown>[];
+	execAsync(): Promise<Record<string, unknown>[]>;
+}
+import { TSchema as TSchema7 } from "typebox";
+declare function ftsTableName(tableName: string): string;
+declare function resolveFtsColumns(meta: TableMeta, fts: FTSConfig): string[];
+interface FtsSnippetSpec {
+	field: string;
+	open: string;
+	close: string;
+	ellipsis: string;
+	tokens: number;
+}
+interface FtsHighlightSpec {
+	field: string;
+	open: string;
+	close: string;
+}
+interface FtsSearchState {
+	query: string;
+	limit?: number;
+	offset?: number;
+	weightMap?: Record<string, number>;
+	weights?: number[];
+	snippets: FtsSnippetSpec[];
+	highlights: FtsHighlightSpec[];
+	includeDeleted: boolean;
+	nodes: ConditionNode[];
+}
+type FtsResult<E> = E & {
+	_score: number;
+	_snippet: Record<string, string>;
+	_highlight: Record<string, string>;
+};
+declare function buildFtsSearchSql(tableName: string, ftsColumns: string[], state: FtsSearchState, softDeleteColumn: string | undefined, meta: TableMeta): {
+	sql: string;
+	params: SQLQueryBindings[];
+	snippetAliases: Array<{
+		field: string;
+		alias: string;
+	}>;
+	highlightAliases: Array<{
+		field: string;
+		alias: string;
+	}>;
+};
+declare class FtsSearchBuilder<
+	TQuery extends TSchema7 & {
+		properties: Record<string, TSchema7>;
+	},
+	TEntity,
+	FTS extends string
+> {
+	private _exec;
+	private _execAsync?;
+	_state: FtsSearchState;
+	constructor(query: string, _exec: (state: FtsSearchState) => FtsResult<TEntity>[], _execAsync?: ((state: FtsSearchState) => Promise<FtsResult<TEntity>[]>) | undefined);
+	limit(n: number): this;
+	offset(n: number): this;
+	includeDeleted(): this;
+	weight(field: FTS, w: number): this;
+	weights(map: Partial<Record<FTS, number>>): this;
+	snippet(field: FTS, opts?: {
+		open?: string;
+		close?: string;
+		ellipsis?: string;
+		tokens?: number;
+	}): this;
+	highlight(field: FTS, opts?: {
+		open?: string;
+		close?: string;
+	}): this;
+	where(cb: (q: FilterBuilder<TQuery, unknown>) => void): this;
+	exec(): FtsResult<TEntity>[];
+	execAsync(): Promise<FtsResult<TEntity>[]>;
+}
 interface BatchWriterOptions {
 	maxBuffer?: number;
 	flushIntervalMs?: number;
@@ -1236,7 +1658,7 @@ declare class BatchWriter<
 	private readonly prepare;
 	private readonly onFlush?;
 	private timer?;
-	constructor(tableName: string, db: BunDatabase, opts: BatchWriterOptions, callbacks: {
+	constructor(tableName: string, db: BunDatabase, opts: BatchWriterOptions | undefined, callbacks: {
 		prepare: (row: TInput) => TRow;
 		onFlush?: (rows: TRow[]) => void;
 	});
@@ -1244,6 +1666,25 @@ declare class BatchWriter<
 	flush(): void;
 	close(): void;
 }
+declare class ReadScheduler {
+	private workers;
+	private workerStatus;
+	private taskCounter;
+	private readonly MAX_PENDING_TASKS;
+	private readonly pendingTasks;
+	private readonly overflowQueue;
+	private overflowHead;
+	private nextWorkerHint;
+	private readonly columnCache;
+	constructor(opts?: DatabaseOptions, workerCount?: number);
+	private initWorkers;
+	private dispatch;
+	private dequeueOrIdle;
+	exec<T = any>(sql: string, params?: any[]): Promise<T>;
+	execWithCols<T extends Record<string, unknown> = Record<string, unknown>>(sql: string, params: any[], columns: string[]): Promise<T[]>;
+	private enqueue;
+	terminate(): 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.
@@ -1266,34 +1707,59 @@ declare class BatchWriter<
 * ```
 */
 declare class Repository<
-	TWrite extends TSchema5 & {
-		properties: Record<string, TSchema5>;
+	TWrite extends TSchema8 & {
+		properties: Record<string, TSchema8>;
 	},
-	TQuery extends TSchema5 & {
-		properties: Record<string, TSchema5>;
+	TQuery extends TSchema8 & {
+		properties: Record<string, TSchema8>;
 	},
 	PK extends ScalarKeys<TWrite>,
 	Mat = never,
-	TS = {}
+	TS = {},
+	FTS extends string = never
 > {
 	readonly tableName: string;
 	/** table metadata - columns, sub-tables, indexes */
 	readonly meta: TableMeta;
+	/**
+	* Get the underlying SQLite table name for a sub-table by field name.
+	* Returns undefined if the field is not a sub-table (array relationship).
+	*
+	* @example
+	* ```ts
+	* orm.purchases.getSubTableName("PurchaseLineItems")
+	* // => "archivedPurchases__PurchaseLineItems"
+	* ```
+	*/
+	getSubTableName(fieldName: string): string | undefined;
 	private readonly validator;
 	private readonly db;
 	private readonly descriptor;
 	private _entityProto;
 	private readonly _timestampNames;
+	private readonly _hasTimestamps;
+	private readonly _hasEviction;
 	private _materialize?;
 	private _materializeMany?;
 	private _events?;
 	private _executor;
 	private readonly _codecs;
+	private readonly _insertColsSql;
+	private readonly _insertPlaceholders;
+	private readonly _readScheduler?;
+	private readonly _allColumnNames;
+	private readonly _onDeleteBehavior;
+	private readonly _ftsEnabled;
+	private readonly _ftsTableName;
+	private readonly _ftsColumns;
+	private readonly _ftsColumnSet;
+	private readonly _ftsInsertDirectSql;
+	private readonly _ftsDeleteDirectSql;
 	/** @internal */
 	setEventBus(bus: EventBus): void;
 	/** @internal */
 	setMetricsHook(hook?: (meta: QueryMetrics) => void): void;
-	constructor(tableName: string, config: TableConfig<TWrite, PK & string, TimestampConfig, GeneratedColumnConfig | undefined>, db: BunDatabase);
+	constructor(tableName: string, config: TableConfig<TWrite, PK & string, TimestampConfig, GeneratedColumnConfig | undefined, FTSConfig | undefined>, db: BunDatabase, readScheduler?: ReadScheduler, onDeleteBehavior?: "native" | "foxdb" | "none");
 	/** Ensure PK is selected when include is requested */
 	private _ensureSelectPk;
 	/**
@@ -1303,8 +1769,10 @@ declare class Repository<
 	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 */
+	/** Wrap raw data in an entity object (with sub-table fields) */
 	private _wrap;
+	/** Wrap raw data in an entity object (without sub-table fields) */
+	private _wrapNoSubs;
 	/** 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 */
@@ -1352,6 +1820,7 @@ declare class Repository<
 	* ```
 	*/
 	insert(data: InsertData<TWrite>): Entity<Infer<TQuery>, Mat, TS>;
+	private _insertRow;
 	/**
 	* Insert many records in a single transaction.
 	*
@@ -1426,139 +1895,142 @@ declare class Repository<
 	findById(id: Infer<TQuery>[PK]): Entity<Infer<TQuery>, Mat, TS> | null;
 	/** Internal findById without event emission - used by update() */
 	private _findByIdRaw;
+	/** Internal raw row fetch without hydration - used by update() */
+	private _findFlatRow;
 	/**
 	* Find many records matching the given filters.
+	* Legacy object-based API - use `findMany()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* const adults = orm.users.findMany({
+	* const adults = orm.users.O_findMany({
 	*   where: { age: { gte: 18 } },
 	*   orderBy: { column: "name", direction: "ASC" },
 	*   limit: 10,
 	* });
-	*
-	* // Include sub-tables
-	* const orders = orm.orders.findMany({ include: ["lineItems"] });
 	* ```
 	*/
-	findMany<
+	O_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> & {
+	}): (SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] })[];
+	O_findMany<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): (Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] })[];
+	O_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>[];
+	}): (SelectShape<TQuery, S>)[];
+	O_findMany(opts?: FindOptions<TQuery>): Entity<Infer<TQuery>, Mat, TS>[];
 	/**
 	* Find many with total count - useful for pagination.
+	* Legacy object-based API - use `findPage()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* const page = orm.users.findPage({
+	* const page = orm.users.O_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<
+	O_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> & {
+	}): PageResult<SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] }>;
+	O_findPage<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): PageResult<Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] }>;
+	O_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>>;
+	}): PageResult<SelectShape<TQuery, S>>;
+	O_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.
+	* Legacy object-based API - use `findCursorPage()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* const page = orm.orders.findCursorPage({
-	*   orderBy: { column: "DocumentDate", direction: "DESC" },
-	*   limit: 25,
-	* });
-	*
-	* const next = orm.orders.findCursorPage({
+	* const page = orm.orders.O_findCursorPage({
 	*   orderBy: { column: "DocumentDate", direction: "DESC" },
-	*   cursor: page.nextCursor!,
 	*   limit: 25,
 	* });
 	* ```
 	*/
-	findCursorPage(opts: {
+	O_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`).
+	* Find a single record matching the given filters.
+	* Legacy object-based API - use `findOne()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* const admin = orm.users.findOne({
+	* const admin = orm.users.O_findOne({
 	*   where: { role: { eq: "admin" } },
 	* });
 	* ```
 	*/
-	findOne<
+	O_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> & {
+	}): (SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] }) | null;
+	O_findOne<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): (Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] }) | null;
+	O_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;
+	}): (SelectShape<TQuery, S>) | null;
+	O_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.
+	* Legacy object-based API - use `iterate()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* for (const user of orm.users.iterate({ where: { active: { eq: true } } })) {
+	* for (const user of orm.users.O_iterate({ where: { active: { eq: true } } })) {
 	*   console.log(user.name);
 	* }
 	* ```
 	*/
-	iterate<
+	O_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> & {
+	}): Generator<SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] }>;
+	O_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> & {
+	O_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>>;
+	}): Generator<SelectShape<TQuery, S>>;
+	O_iterate(opts?: FindOptions<TQuery>): Generator<Entity<Infer<TQuery>, Mat, TS>>;
+	private _iterateImpl;
 	private _hydrateWindow;
 	/**
 	* Find many with resolved relations (n+1 safe). If you have cross-table
@@ -1577,35 +2049,32 @@ declare class Repository<
 	findManyMaterialized(opts?: FindOptions<TQuery>): Entity<Infer<TQuery>, Mat, TS>[];
 	/**
 	* Count records matching the given filters.
+	* Legacy object-based API - use `count()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* const total = orm.users.count();
-	* const adults = orm.users.count({ age: { gte: 18 } });
+	* const total = orm.users.O_count();
+	* const adults = orm.users.O_count({ age: { gte: 18 } });
 	* ```
 	*/
-	count(where?: WhereClause<TQuery>): number;
+	O_count(where?: WhereClause<TQuery>): number;
 	/**
 	* Run aggregate queries (sum, count, avg, min, max) with optional
 	* grouping and filtering.
+	* Legacy object-based API - use `aggregate()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* orm.orders.aggregate({
+	* orm.orders.O_aggregate({
 	*   aggregations: { total: { sum: "amount" } },
 	* });
-	*
-	* orm.orders.aggregate({
-	*   groupBy: ["status"],
-	*   aggregations: { count: { count: "*" }, avgAmount: { avg: "amount" } },
-	* });
 	* ```
 	*/
-	aggregate<
+	O_aggregate<
 		const A extends Record<string, AggregationOp<TQuery>>,
 		const G extends readonly (ScalarKeys<TQuery> | ScalarJsonPath<TQuery>)[] | undefined = undefined
 	>(opts: AggregateOptions<TQuery, A> & {
@@ -1614,12 +2083,13 @@ declare class Repository<
 	/**
 	* Run window function queries (rowNumber, rank, denseRank, lead, lag)
 	* with partitioning and ordering.
+	* Legacy object-based API - use `windowQuery()` chain API for new code.
 	*
 	* @group Reading
 	*
 	* @example
 	* ```ts
-	* orm.orders.windowQuery({
+	* orm.orders.O_windowQuery({
 	*   partitionBy: ["Status__Group"],
 	*   orderBy: [{ column: "DocumentDate", direction: "DESC" }],
 	*   select: {
@@ -1631,10 +2101,200 @@ declare class Repository<
 	* });
 	* ```
 	*/
-	windowQuery<const W extends Record<string, WindowFunction<TQuery>>>(opts: WindowQueryOptions<TQuery> & {
+	O_windowQuery<const W extends Record<string, WindowFunction<TQuery>>>(opts: WindowQueryOptions<TQuery> & {
 		select: W;
 	}): WindowResult<TQuery, W>;
 	/**
+	* Async variant of O_findMany - executes on the worker thread pool.
+	*/
+	O_findManyAsync<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): Promise<(SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] })[]>;
+	O_findManyAsync<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): Promise<(Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] })[]>;
+	O_findManyAsync<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): Promise<(SelectShape<TQuery, S>)[]>;
+	O_findManyAsync(opts?: FindOptions<TQuery>): Promise<Entity<Infer<TQuery>, Mat, TS>[]>;
+	/**
+	* Async variant of O_findOne - executes on the worker thread pool.
+	*/
+	O_findOneAsync<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): Promise<(SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] }) | null>;
+	O_findOneAsync<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): Promise<(Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] }) | null>;
+	O_findOneAsync<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): Promise<(SelectShape<TQuery, S>) | null>;
+	O_findOneAsync(opts?: FindOptions<TQuery>): Promise<Entity<Infer<TQuery>, Mat, TS> | null>;
+	/**
+	* Async variant of O_findPage - executes on the worker thread pool.
+	*/
+	O_findPageAsync<
+		const S extends readonly SelectableKeys<TQuery>[],
+		const I extends readonly SubTableKeys<TQuery>[]
+	>(opts: FindOptions<TQuery> & {
+		select: S;
+		include: I;
+	}): Promise<PageResult<SelectShape<TQuery, S> & { [K in I[number]] : SubTableItem<TQuery, K>[] }>>;
+	O_findPageAsync<const I extends readonly SubTableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		include: I;
+	}): Promise<PageResult<Entity<Infer<TQuery>, Mat, TS> & { [K in I[number]] : SubTableItem<TQuery, K>[] }>>;
+	O_findPageAsync<const S extends readonly SelectableKeys<TQuery>[]>(opts: FindOptions<TQuery> & {
+		select: S;
+	}): Promise<PageResult<SelectShape<TQuery, S>>>;
+	O_findPageAsync(opts?: FindOptions<TQuery>): Promise<PageResult<Entity<Infer<TQuery>, Mat, TS>>>;
+	/**
+	* Async variant of O_findCursorPage - executes on the worker thread pool.
+	*/
+	O_findCursorPageAsync(opts: {
+		where?: WhereClause<TQuery>;
+		orderBy: OrderByClause<TQuery>;
+		cursor?: CursorInput;
+		limit?: number;
+	}): Promise<CursorPageResult<Entity<Infer<TQuery>, Mat, TS>>>;
+	/**
+	* Async variant of O_count - executes on the worker thread pool.
+	*/
+	O_countAsync(where?: WhereClause<TQuery>): Promise<number>;
+	/**
+	* Async variant of O_aggregate - executes on the worker thread pool.
+	*/
+	O_aggregateAsync<
+		const A extends Record<string, AggregationOp<TQuery>>,
+		const G extends readonly (ScalarKeys<TQuery> | ScalarJsonPath<TQuery>)[] | undefined = undefined
+	>(opts: AggregateOptions<TQuery, A> & {
+		groupBy?: G;
+	}): Promise<AggregateResult<TQuery, A, G>>;
+	/**
+	* Async variant of O_windowQuery - executes on the worker thread pool.
+	*/
+	O_windowQueryAsync<const W extends Record<string, WindowFunction<TQuery>>>(opts: WindowQueryOptions<TQuery> & {
+		select: W;
+	}): Promise<WindowResult<TQuery, W>>;
+	/**
+	* Async variant of findById - executes on the worker thread pool.
+	*/
+	findByIdAsync(id: Infer<TQuery>[PK]): Promise<Entity<Infer<TQuery>, Mat, TS> | null>;
+	/**
+	* Async variant of findManyMaterialized - executes on the worker thread pool.
+	*/
+	findManyMaterializedAsync(opts?: FindOptions<TQuery>): Promise<Entity<Infer<TQuery>, Mat, TS>[]>;
+	/**
+	* Async variant of raw - executes on the worker thread pool.
+	*/
+	rawAsync<R = DBRow>(sql: string, ...params: DBValue[]): Promise<R[]>;
+	/**
+	* Start a chain filter query that returns many records.
+	*
+	* @group Reading - Chain API
+	*
+	* @example
+	* ```ts
+	* const adults = orm.users
+	*   .findMany()
+	*   .greaterThanOrEqual("age", 18)
+	*   .equals("active", true)
+	*   .orderBy("createdAt", "DESC")
+	*   .limit(10)
+	*   .exec();
+	* ```
+	*/
+	findMany(): FilterBuilder<TQuery, Entity<Infer<TQuery>, Mat, TS>[]>;
+	/**
+	* Start a chain filter query that returns a single record.
+	*
+	* @group Reading - Chain API
+	*
+	* @example
+	* ```ts
+	* const admin = orm.users
+	*   .findOne()
+	*   .equals("role", "admin")
+	*   .exec();
+	* ```
+	*/
+	findOne(): FilterBuilder<TQuery, Entity<Infer<TQuery>, Mat, TS> | null>;
+	/**
+	* Start a chain count query.
+	*
+	* @group Reading - Chain API
+	*
+	* @example
+	* ```ts
+	* const total = orm.users
+	*   .count()
+	*   .equals("active", true)
+	*   .exec();
+	* ```
+	*/
+	count(): FilterBuilder<TQuery, number>;
+	/**
+	* Start a chain paginated query.
+	*
+	* @group Reading - Chain API
+	*
+	* @example
+	* ```ts
+	* const page = orm.users
+	*   .findPage()
+	*   .equals("active", true)
+	*   .limit(10)
+	*   .offset(0)
+	*   .exec();
+	* ```
+	*/
+	findPage(): FilterBuilder<TQuery, PageResult<Entity<Infer<TQuery>, Mat, TS>>>;
+	/**
+	* Start a chain cursor-paginated query.
+	*
+	* @group Reading - Chain API
+	*
+	* @example
+	* ```ts
+	* const page = orm.orders
+	*   .findCursorPage()
+	*   .orderBy("id", "ASC")
+	*   .limit(25)
+	*   .exec();
+	* ```
+	*/
+	findCursorPage(): FilterBuilder<TQuery, CursorPageResult<Entity<Infer<TQuery>, Mat, TS>>>;
+	/**
+	* Start a chain aggregate query.
+	*
+	* @group Reading - Chain API
+	*
+	* @example
+	* ```ts
+	* const totals = orm.orders
+	*   .aggregate()
+	*   .sum("amount", "totalRevenue")
+	*   .count("*", "orderCount")
+	*   .groupBy("status")
+	*   .exec();
+	* ```
+	*/
+	aggregate(): AggregateBuilder<TQuery>;
+	/**
+	* Full-text search (FTS5). Present only on tables with `fts` enabled.
+	* @group Reading - Chain API
+	*/
+	search(query: string): FtsSearchBuilder<TQuery, Entity<Infer<TQuery>, Mat, TS>, FTS>;
+	/** Convenience async full-text search. Present only on tables with `fts` enabled. */
+	searchAsync(query: string): Promise<FtsResult<Entity<Infer<TQuery>, Mat, TS>>[]>;
+	/**
 	* Update a record - must include the primary key. Returns the updated
 	* entity, or `null` if no record matched.
 	*
@@ -1705,6 +2365,13 @@ declare class Repository<
 	* ```
 	*/
 	drop(): void;
+	private _ftsIndexByPk;
+	private _ftsDeleteByPk;
+	private _ftsIndexByRowid;
+	private _ftsDeleteByRowid;
+	private _patchTouchesFts;
+	private _ftsBindInsert;
+	private _ftsBindDelete;
 	private _hydrateOne;
 	/**
 	* Run raw SQL - escape hatch for queries the ORM doesn't support directly.
@@ -1720,7 +2387,7 @@ declare class Repository<
 	*/
 	raw<R = DBRow>(sql: string, ...params: DBValue[]): R[];
 }
-declare class RelationBuilder<Tables extends Record<string, TableDescriptor<any, any, any, any>>> {
+declare class RelationBuilder<Tables extends Record<string, TableDescriptor<any, any, any, any, any>>> {
 	private readonly tables;
 	private readonly relations;
 	constructor(tables: Tables);
@@ -1750,13 +2417,13 @@ declare class RelationBuilder<Tables extends Record<string, TableDescriptor<any,
 	build(): TypedRelation[];
 }
 /** @category Relations */
-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;
-declare const SchemaJSONSchema: unknown;
-declare const TablesSchema: unknown;
-declare const RelationsSchema: unknown;
-declare const VersionSchema: unknown;
+declare function createRelationBuilder<T extends Record<string, TableDescriptor<any, any, any, any, any>>>(tables: T): RelationBuilder<T>;
+import { Static as Static2, TSchema as TSchema9 } from "typebox";
+declare const SchemaHashSchema: TSchema9;
+declare const SchemaJSONSchema: TSchema9;
+declare const TablesSchema: TSchema9;
+declare const RelationsSchema: TSchema9;
+declare const VersionSchema: TSchema9;
 type SchemaHash = Static2<typeof SchemaHashSchema>;
 type SchemaJSON = Static2<typeof SchemaJSONSchema>;
 type TablesList = Static2<typeof TablesSchema>;
@@ -1798,7 +2465,7 @@ declare class MetaStore {
 * @category Lifecycle
 */
 interface ORMContext<
-	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > {
 	orm: foxdb<T, Rels>;
@@ -1816,7 +2483,7 @@ interface ORMContext<
 * @category Lifecycle
 */
 type LifecycleHook<
-	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > = (ctx: ORMContext<T, Rels>) => void | Promise<void>;
 /**
@@ -1824,7 +2491,7 @@ type LifecycleHook<
 * @category Lifecycle
 */
 declare class LifecycleManager<
-	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > {
 	private startHooks;
@@ -1834,17 +2501,17 @@ declare class LifecycleManager<
 	private _ready;
 	private _shutdown;
 	/** true after runReady completes */
-	get isReady();
+	get isReady(): boolean;
 	/** true after runShutdown completes */
-	get isShutdown();
+	get isShutdown(): boolean;
 	/** register a startup hook */
-	onStart(hook: LifecycleHook<T, Rels>);
+	onStart(hook: LifecycleHook<T, Rels>): void;
 	/** register a ready hook */
-	onReady(hook: LifecycleHook<T, Rels>);
+	onReady(hook: LifecycleHook<T, Rels>): void;
 	/** register a shutdown hook */
-	onShutdown(hook: LifecycleHook<T, Rels>);
+	onShutdown(hook: LifecycleHook<T, Rels>): void;
 	/** register an exit hook */
-	onExit(hook: LifecycleHook<T, Rels>);
+	onExit(hook: LifecycleHook<T, Rels>): void;
 	/** @internal */
 	runStart(ctx: ORMContext<T, Rels>): void;
 	/** @internal */
@@ -1869,6 +2536,15 @@ interface CreateORMBaseOptions {
 	vacuumIntervalMs?: number;
 	/** disable fsync during large initial loads */
 	bulkLoadMode?: boolean;
+	/** number of worker threads for async read queries (enables *Async methods) */
+	asyncReaderPool?: number;
+	/**
+	* How sub-table foreign key deletions are handled.
+	* - `"native"` (default): SQLite ON DELETE CASCADE - FK verification on INSERT.
+	* - `"foxdb"`: No FK in DDL, foxdb handles cascading in application code - faster INSERTs.
+	* - `"none"`: No FK, no cascade - sub-table rows become orphaned on parent delete.
+	*/
+	onDeleteBehavior?: "native" | "foxdb" | "none";
 }
 /**
 * Options passed to `createORM`.
@@ -1899,7 +2575,7 @@ interface CreateORMBaseOptions {
 * ```
 */
 interface CreateORMOptions<
-	T extends Record<string, TableDescriptor<any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any>>,
+	T extends Record<string, TableDescriptor<any, any, any, any, any>> = Record<string, TableDescriptor<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 > extends CreateORMBaseOptions {
 	/** table schemas */
@@ -1950,7 +2626,7 @@ interface CreateORMOptions<
 *
 * 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
+* 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
@@ -1965,7 +2641,7 @@ interface CreateORMOptions<
 *   },
 * });
 *
-* // ─── Every table key is a Repository ───
+* // --- Every table key is a Repository ---
 *
 * // Insert
 * orm.users.insert({ id: "u1", name: "alice" });
@@ -1984,7 +2660,7 @@ interface CreateORMOptions<
 * orm.users.deleteById("u1");
 * orm.users.deleteWhere({ status: { eq: "banned" } });
 *
-* // ─── Framework methods (prefixed with _) ───
+* // --- Framework methods (prefixed with _) ---
 *
 * orm._transaction(() => {
 *   orm.users.insert({ id: "t1", name: "txn" });
@@ -1995,11 +2671,11 @@ interface CreateORMOptions<
 * ```
 */
 type foxdb<
-	Tables extends Record<string, TableDescriptor<any, any, any, any>>,
+	Tables extends Record<string, TableDescriptor<any, any, any, any, any>>,
 	Rels extends readonly TypedRelation[] = readonly TypedRelation[]
-> = { [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 } & {
+> = { [K in keyof Tables] : Tables[K] extends TableDescriptor<infer TWrite extends TSchema10 & {
+	properties: Record<string, TSchema10>;
+}, infer PKName extends string, infer Timestamps, infer G extends GeneratedColumnConfig | undefined, infer F> ? FTSEnabled<F> extends true ? Repository<TWrite, QuerySchema<TWrite, G>, PKName extends ScalarKeys<TWrite> ? PKName : never, Materialized<TWrite, Tables, Rels, K & string>, TimestampShape<Timestamps>, FTSFields<TWrite, F> & string> : Omit<Repository<TWrite, QuerySchema<TWrite, G>, PKName extends ScalarKeys<TWrite> ? PKName : never, Materialized<TWrite, Tables, Rels, K & string>, TimestampShape<Timestamps>, never>, "search" | "searchAsync"> : never } & {
 	/** run a transaction */
 	_transaction<R>(fn: () => R): R;
 	/** close the database */
@@ -2023,7 +2699,7 @@ type foxdb<
 };
 /** create a typed orm instance backed by sqlite */
 declare function createORM<
-	const T extends Record<string, TableDescriptor<any, any, any, any>>,
+	const T extends Record<string, TableDescriptor<any, any, any, any, any>>,
 	const Rels extends readonly TypedRelation[] = readonly TypedRelation[]
 >(opts: CreateORMOptions<T, Rels>): foxdb<T, Rels>;
 declare function migrate(opts: MigrateOptions): Promise<void>;
@@ -2133,4 +2809,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, 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 };
+export { AggregateBuilder, AggregateBuilderState, AggregateOptions, AggregationOp, ArrayFilterableFields, ArrayItemType, ArrayOfObjectProperties, BatchWriter, BatchWriterOptions, BroadOperation, BunDatabase, BunStatement, ColumnMeta, ColumnRef, ColumnRefs, ConditionNode, CreateORMBaseOptions, CreateORMOptions, DEFAULT_TIMESTAMP_NAMES, DatabaseOptions, DesiredTable, DistinctableFields, Entity, ErrorPolicy2 as ErrorPolicy, EventBus, FTSConfig, FTSEnabled, FTSFields, FieldType, FilterBuilder, FilterableFields, FindOptions, FtsHighlightSpec, FtsResult, FtsSearchBuilder, FtsSearchState, FtsSnippetSpec, GeneratedColumnConfig, IndexDefinition, Infer, InsertData, InspectorColumn, InspectorIndex, InspectorTable, InternalBuilderState, LifecycleEventMap, LifecycleHook, LifecycleManager, Listener, Materialized, MetaStore, MigrateOptions, Migration, ORMContext, ORMError, ORMErrorContext, ORMEvents, OrderByClause, OrderableFields, PageResult, QueryMetrics, QueryMetricsHook, RelationBuilder, RelationEntry, RelationsConfig, Repository, ScalarFilter, ScalarKeys, ScalarMerge, ScalarMergeNames, ScalarMergeType, ScalarPath, ScalarProperties, SchemaChange, SchemaDiff, SchemaJSON, SchemaJSONSchema, SqliteType, SubMerge, SubMergeNames, SubMergeType, SubTableConfig, SubTableKeys, SubTableMeta, SubTableScalarPath, SyncPolicy, TScalarSchema, TableConfig, TableConfigShape, TableDescriptor, TableEventOperation, TableEventPayload, TableMeta, TableOperation, TimestampConfig2 as TimestampNamesConfig, TimestampShape, TraceEntry, TypedRelation, UnlinkPolicy, UpdateData, UpsertOptions, WhereClause, applySync, buildCreateTableSQL, buildFtsSearchSql, buildWhereFromNodes, computeDiff, createMigration, createORM, createRelationBuilder, foxdb, ftsTableName, inspectAllTables, inspectSchema, introspectTable, migrate, raise, resolveFtsColumns, resolveTimestampNames, table, withTrace };