locality-idb 1.0.1 → 1.1.1

package/README.md

@@ -128,7 +128,7 @@ const users = await db.from('users').findAll();
 const alice = await db
   .from('users')
   .where((user) => user.email === 'alice@example.com')
-  .first();
+  .findFirst();
 
 // Update data
 await db
@@ -400,7 +400,7 @@ const topTenUsers = await db
 const user = await db
   .from('users')
   .where((user) => user.email === 'john@example.com')
-  .first();
+  .findFirst();
 // Returns: User | null
 ```
 
@@ -467,7 +467,7 @@ const names = await db
   .findAll();
 ```
 
-> **Note:** `sortByIndex()` uses IndexedDB cursor iteration for optimal performance when no `where()` filter is applied.
+> **Note:** `sortByIndex()` uses IndexedDB cursor iteration for optimal performance when `where()` filter is applied without index.
 
 #### Chain Multiple Methods
 
@@ -787,6 +787,32 @@ Filters rows based on a predicate function.
 db.from('users').where((user) => user.age >= 18)
 ```
 
+##### `where<IdxKey>(indexName: IdxKey, query: T[IdxKey] | IDBKeyRange): SelectQuery`
+
+Filters rows using an indexed field.
+
+```typescript
+db.from('users').where('age', IDBKeyRange.bound(18, 30))
+```
+
+##### `sortByIndex<IdxKey>(indexName: IdxKey, dir?: 'asc' | 'desc'): SelectQuery`
+
+Sorts results by an indexed field using IndexedDB cursor iteration (avoiding in-memory sorting).
+
+**Type Safety:** `indexName` must be a field with an index.
+
+**Performance:** Uses IndexedDB's cursor for optimized sorting. For large datasets, this is significantly more efficient than in-memory sorting.
+
+> For sorting on non-indexed fields, use [`orderBy()`](#orderbykeykey-key-direction-asc--desc-selectquery) which performs in-memory sorting.
+
+```typescript
+// Optimized cursor-based sort
+const sorted = await db.from('users').sortByIndex('age', 'desc').findAll();
+
+// Efficient pagination
+const page = await db.from('users').sortByIndex('createdAt', 'desc').limit(20).findAll();
+```
+
 ##### `orderBy<Key>(key: Key, direction?: 'asc' | 'desc'): SelectQuery`
 
 Orders results by a specified key. Supports nested keys using dot notation.
@@ -796,6 +822,8 @@ db.from('users').orderBy('name', 'asc')
 db.from('users').orderBy('profile.age', 'desc')
 ```
 
+> **Note:** This method performs in-memory sorting. For large datasets, consider using [`sortByIndex()`](#sortbyindexidxkeyindexname-idxkey-dir-asc--desc-selectquery) with an indexed field for better performance.
+
 ##### `limit(count: number): SelectQuery`
 
 Limits the number of results.
@@ -812,12 +840,12 @@ Fetches all matching records.
 const users = await db.from('users').findAll()
 ```
 
-##### `first(): Promise<T | null>`
+##### `findFirst(): Promise<T | null>`
 
 Fetches the first matching record.
 
 ```typescript
-const user = await db.from('users').first()
+const user = await db.from('users').findFirst()
 ```
 
 ##### `findByPk<Key>(key: Key): Promise<T | null>`
@@ -828,10 +856,10 @@ Finds a single record by its primary key value using IndexedDB's optimized `get(
 
 ```typescript
 const user = await db.from('users').findByPk(1);
-const post = await db.from('posts').findByPk('uuid-string');
+const post = await db.from('posts').findByPk('some-uuid-string');
 ```
 
-##### `findByIndex<IndexKey>(indexName: IndexKey, query: T[IndexKey] | IDBKeyRange): Promise<T[]>`
+##### `findByIndex<IdxKey>(indexName: IdxKey, query: T[IdxKey] | IDBKeyRange): Promise<T[]>`
 
 Finds records using an indexed field. Only accepts field names that are marked with `.index()` or `.unique()`.
 
@@ -852,22 +880,31 @@ const adults = await db.from('users').findByIndex('age', IDBKeyRange.bound(18, 6
 > - Unique columns are automatically indexed.
 > - Unique indexes are recommended for this method to ensure a single result.
 
-##### `sortByIndex<IndexKey>(indexName: IndexKey, dir?: 'asc' | 'desc'): SelectQuery`
+##### `count(): Promise<number>`
 
-Sorts results by an indexed field using IndexedDB cursor iteration (avoiding in-memory sorting).
+Counts the number of matching records.
 
-**Type Safety:** `indexName` must be a field with an index.
+```typescript
+const userCount = await db.from('users').where((user) => user.isActive).count()
+```
 
-**Performance:** When no `where()` filter is applied, uses optimized cursor iteration. Otherwise falls back to in-memory sorting.
+> **Note:**
+>
+> - This method internally uses IndexedDB's `count()` for optimal performance.
+> - If a `where()` filter is applied without index, it falls back to in-memory counting.
 
-```typescript
-// Optimized cursor-based sort
-const sorted = await db.from('users').sortByIndex('age', 'desc').findAll();
+##### `exists(): Promise<boolean>`
 
-// Efficient pagination
-const page = await db.from('users').sortByIndex('createdAt', 'desc').limit(20).findAll();
+Checks if any matching records exist.
+
+```typescript
+const hasAdmins = await db.from('users').where((user) => user.role === 'admin').exists()
 ```
 
+> **Note:** This method internally uses [`count()`](#count-promisenumber) for checking existence.
+
+---
+
 #### InsertQuery Methods
 
 ##### `values<T>(data: T | T[]): InsertQuery`
@@ -913,6 +950,8 @@ Executes the update query and returns the number of updated records.
 const count = await db.update('users').set({ name: 'Jane' }).run()
 ```
 
+---
+
 #### DeleteQuery Methods
 
 ##### `where(predicate: (row: T) => boolean): DeleteQuery`

package/dist/index.cjs

@@ -12,6 +12,9 @@ function isInteger(value) {
 function isBoolean(value) {
 	return typeof value === "boolean";
 }
+function isUndefined(value) {
+	return value === void 0;
+}
 function isBigInt(value) {
 	return typeof value === "bigint";
 }
@@ -33,6 +36,9 @@ function isObject(value) {
 function isNotEmptyObject(value) {
 	return isObject(value) && Object.keys(value)?.length > 0;
 }
+function isFunction(value) {
+	return typeof value === "function";
+}
 function isDate(value) {
 	return value instanceof Date;
 }
@@ -456,6 +462,8 @@ var SelectQuery = class {
 	#readyPromise;
 	#dbGetter;
 	#whereCondition;
+	#whereIndexName;
+	#whereIndexQuery;
 	#orderByKey;
 	#orderByDir = "asc";
 	#limitCount;
@@ -465,6 +473,49 @@ var SelectQuery = class {
 		this.#dbGetter = dbGetter;
 		this.#readyPromise = readyPromise;
 	}
+	#createTransaction() {
+		return this.#dbGetter().transaction(this.#table, "readonly");
+	}
+	#getStoreWithTransaction() {
+		return this.#createTransaction().objectStore(this.#table);
+	}
+	/** @internal Check if key is an index on the store for the `#whereIndexName` */
+	#isIndexKey(store) {
+		return isNonEmptyString(this.#whereIndexName) && store.indexNames.contains(this.#whereIndexName);
+	}
+	/** @internal Check if key is the primary key on the store for the `#whereIndexName` */
+	#isPrimaryKey(store) {
+		return isNonEmptyString(this.#whereIndexName) && store.keyPath === this.#whereIndexName;
+	}
+	/** @internal Build indexed store (primary key or index) for where queries */
+	#buildIndexedStore(store, reject) {
+		const isPK = this.#isPrimaryKey(store);
+		const isIndex = this.#isIndexKey(store);
+		if (!isPK && !isIndex) {
+			reject(/* @__PURE__ */ new RangeError(`Index '${this.#whereIndexName}' does not exist on table '${this.#table}'`));
+			return null;
+		}
+		return isPK ? store : store.index(this.#whereIndexName);
+	}
+	/** @internal Sort data in memory if needed */
+	#sort(data) {
+		if (this.#orderByKey) return sortAnArray(data, {
+			sortOrder: this.#orderByDir,
+			sortByField: this.#orderByKey
+		});
+		return data;
+	}
+	/** Projects a row based on selected fields */
+	#projectRow(row) {
+		if (!isNotEmptyObject(this?.[Selected])) return row;
+		const projected = {};
+		const selectionEntries = Object.entries(this[Selected]);
+		const selectionKeys = new Set(Object.keys(this[Selected]));
+		if (selectionEntries.some(([, value]) => value === true)) {
+			for (const [key, value] of selectionEntries) if (value === true) projected[key] = row[key];
+		} else for (const key of Object.keys(row)) if (!selectionKeys.has(key) || this[Selected][key] !== false) projected[key] = row[key];
+		return projected;
+	}
 	/**
 	* @instance Select or exclude specific columns
 	* @param cols Columns to select or exclude
@@ -473,18 +524,26 @@ var SelectQuery = class {
 		this[Selected] = cols;
 		return this;
 	}
-	/**
-	* @instance  Filter rows based on predicate function
-	* @param predicate Filtering function
-	*/
-	where(predicate) {
-		this.#whereCondition = predicate;
+	where(condition, query) {
+		if (isFunction(condition)) {
+			this.#whereCondition = condition;
+			this.#whereIndexName = void 0;
+			this.#whereIndexQuery = void 0;
+		} else if (isNonEmptyString(condition) && !isUndefined(query)) {
+			this.#whereIndexName = condition;
+			this.#whereIndexQuery = query;
+			this.#whereCondition = void 0;
+		}
 		return this;
 	}
 	/**
 	* @instance  Order results by specified key and direction
 	* @param key Key to order by
 	* @param dir Direction: 'asc' | 'desc' (default: 'asc')
+	*
+	* @remarks
+	* - This method performs in-memory sorting.
+	* - For optimized sorting using `IndexedDB` indexes, use {@link sortByIndex} instead.
 	*/
 	orderBy(key, dir = "asc") {
 		this.#orderByKey = key;
@@ -492,6 +551,22 @@ var SelectQuery = class {
 		return this;
 	}
 	/**
+	* @instance Order results by index using optimized `IndexedDB` cursor
+	* @param indexName Name of the index to sort by
+	* @param dir Direction: 'asc' | 'desc' (default: 'asc')
+	*
+	* @remarks
+	* - This method uses `IndexedDB` indexes for sorting, which is more efficient for large datasets.
+	* - Ensure that the specified index exists on the table.
+	* - For in-memory sorting, use {@link orderBy} instead.
+	*/
+	sortByIndex(indexName, dir = "asc") {
+		this.#orderByKey = indexName;
+		this.#orderByDir = dir;
+		this.#useIndexCursor = true;
+		return this;
+	}
+	/**
 	* @instance Limit number of results
 	* @param count Maximum number of results to return
 	*/
@@ -499,21 +574,23 @@ var SelectQuery = class {
 		this.#limitCount = count;
 		return this;
 	}
-	/** Projects a row based on selected fields */
-	#projectRow(row) {
-		if (!isNotEmptyObject(this?.[Selected])) return row;
-		const projected = {};
-		const selectionEntries = Object.entries(this[Selected]);
-		const selectionKeys = new Set(Object.keys(this[Selected]));
-		if (selectionEntries.some(([, value]) => value === true)) {
-			for (const [key, value] of selectionEntries) if (value === true) projected[key] = row[key];
-		} else for (const key of Object.keys(row)) if (!selectionKeys.has(key) || this[Selected][key] !== false) projected[key] = row[key];
-		return projected;
-	}
 	async findAll() {
 		await this.#readyPromise;
 		return new Promise((resolve, reject) => {
-			const store = this.#dbGetter().transaction(this.#table, "readonly").objectStore(this.#table);
+			const store = this.#getStoreWithTransaction();
+			if (this.#whereIndexName && !isUndefined(this.#whereIndexQuery)) {
+				const source = this.#buildIndexedStore(store, reject);
+				if (!source) return;
+				const request = source.getAll(this.#whereIndexQuery);
+				request.onsuccess = () => {
+					let results = request.result;
+					results = this.#sort(results);
+					if (this.#limitCount) results = results.slice(0, this.#limitCount);
+					resolve(results.map((row) => this.#projectRow(row)));
+				};
+				request.onerror = () => reject(request.error);
+				return;
+			}
 			if (this.#useIndexCursor && this.#orderByKey && isNonEmptyString(this.#orderByKey) && store.indexNames.contains(this.#orderByKey) && !this.#whereCondition) {
 				const index = store.index(this.#orderByKey);
 				const direction = this.#orderByDir === "desc" ? "prev" : "next";
@@ -546,10 +623,23 @@ var SelectQuery = class {
 			}
 		});
 	}
-	async first() {
+	async findFirst() {
 		await this.#readyPromise;
 		return new Promise((resolve, reject) => {
-			const request = this.#dbGetter().transaction(this.#table, "readonly").objectStore(this.#table).getAll();
+			const store = this.#getStoreWithTransaction();
+			if (this.#whereIndexName && !isUndefined(this.#whereIndexQuery)) {
+				const source = this.#buildIndexedStore(store, reject);
+				if (!source) return;
+				const request = source.getAll(this.#whereIndexQuery);
+				request.onsuccess = () => {
+					const results = request.result;
+					if (results.length > 0) resolve(this.#projectRow(results[0]));
+					else resolve(null);
+				};
+				request.onerror = () => reject(request.error);
+				return;
+			}
+			const request = store.getAll();
 			request.onsuccess = () => {
 				let results = request.result;
 				if (this.#whereCondition) results = results.filter(this.#whereCondition);
@@ -562,11 +652,16 @@ var SelectQuery = class {
 	/**
 	* @instance Find record by primary key (optimized `IndexedDB` get)
 	* @param key Primary key value
+	*
+	* @remarks
+	* - This method uses the `IndexedDB` primary key for efficient querying.
+	* - Ensure that the specified key exists on the table.
+	* - To find by index, use {@link findByIndex} instead.
 	*/
 	async findByPk(key) {
 		await this.#readyPromise;
 		return new Promise((resolve, reject) => {
-			const request = this.#dbGetter().transaction(this.#table, "readonly").objectStore(this.#table).get(key);
+			const request = this.#getStoreWithTransaction().get(key);
 			request.onsuccess = () => {
 				const result = request.result;
 				if (!result) {
@@ -583,16 +678,21 @@ var SelectQuery = class {
 		});
 	}
 	/**
-	* @instance Find records by index (optimized IndexedDB index query)
+	* @instance Find records by index (optimized `IndexedDB` index query)
 	* @param indexName Name of the index to query
 	* @param query Key value to search for
+	*
+	* @remarks
+	* - This method uses `IndexedDB` indexes for efficient querying.
+	* - Ensure that the specified index exists on the table.
+	* - To find by primary key, use {@link findByPk} instead.
 	*/
 	async findByIndex(indexName, query) {
 		await this.#readyPromise;
 		return new Promise((resolve, reject) => {
-			const store = this.#dbGetter().transaction(this.#table, "readonly").objectStore(this.#table);
+			const store = this.#getStoreWithTransaction();
 			if (!store.indexNames.contains(indexName)) {
-				reject(/* @__PURE__ */ new Error(`Index "${indexName}" does not exist on table "${this.#table}"`));
+				reject(/* @__PURE__ */ new Error(`Index '${indexName}' does not exist on table '${this.#table}'`));
 				return;
 			}
 			const request = store.index(indexName).getAll(query);
@@ -606,24 +706,34 @@ var SelectQuery = class {
 			request.onerror = () => reject(request.error);
 		});
 	}
-	/**
-	* @instance Order results by index using optimized IndexedDB cursor
-	* @param indexName Name of the index to sort by
-	* @param dir Direction: 'asc' | 'desc' (default: 'asc')
-	*/
-	sortByIndex(indexName, dir = "asc") {
-		this.#orderByKey = indexName;
-		this.#orderByDir = dir;
-		this.#useIndexCursor = true;
-		return this;
-	}
-	/** @internal Sort data in memory if needed */
-	#sort(data) {
-		if (this.#orderByKey) return sortAnArray(data, {
-			sortOrder: this.#orderByDir,
-			sortByField: this.#orderByKey
+	/** @instance Count matching records */
+	async count() {
+		await this.#readyPromise;
+		return new Promise((resolve, reject) => {
+			const store = this.#getStoreWithTransaction();
+			if (this.#whereIndexName && !isUndefined(this.#whereIndexQuery)) {
+				const source = this.#buildIndexedStore(store, reject);
+				if (!source) return;
+				const request = source.count(this.#whereIndexQuery);
+				request.onsuccess = () => resolve(request.result);
+				request.onerror = () => reject(request.error);
+				return;
+			}
+			if (this.#whereCondition) {
+				const request = store.getAll();
+				request.onsuccess = () => {
+					resolve(request.result.filter(this.#whereCondition).length);
+				};
+				request.onerror = () => reject(request.error);
+				return;
+			}
+			const request = store.count();
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error);
 		});
-		return data;
+	}
+	async exists() {
+		return await this.count() > 0;
 	}
 };
 /** @class Insert query builder. */

package/dist/index.d.cts

@@ -329,6 +329,8 @@ type $InferTimestamp<T extends ColumnDefinition> = { [K in keyof T]: T[K] extend
 type Timestamp = Branded<string, 'Timestamp'>;
 /** Sort direction type for ordering queries */
 type SortDirection = 'asc' | 'desc';
+/** Predicate function type for WHERE clauses in queries */
+type WherePredicate<T extends GenericObject> = (row: T) => boolean;
 /** Creates a type for insert operations with auto-generated fields optional. */
 type InferInsertType<T extends Table> = Prettify<Omit<$InferRow<T['columns']>, $InferAutoInc<T['columns']> | $InferDefault<T['columns']> | $InferTimestamp<T['columns']> | $InferUUID<T['columns']>> & { [K in $InferAutoInc<T['columns']> | $InferDefault<T['columns']> | $InferTimestamp<T['columns']> | $InferUUID<T['columns']>]?: K extends keyof $InferRow<T['columns']> ? $InferRow<T['columns']>[K] : never }>;
 /** Creates a type for update operations with all fields optional except primary key. */
@@ -376,13 +378,34 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
    * @instance  Filter rows based on predicate function
    * @param predicate Filtering function
    */
-  where(predicate: (row: T) => boolean): this;
+  where(predicate: WherePredicate<T>): this;
+  /**
+   * @instance  Filter rows based on index query
+   * @param indexName Name of the index/primary key to query
+   * @param query Key value or {@link IDBKeyRange} to search for
+   */
+  where<IdxKey extends $InferPrimaryKey<Tbl['columns']> | $InferIndex<Tbl['columns']>>(indexName: IdxKey, query: IDBKeyRange | T[IdxKey]): this;
   /**
    * @instance  Order results by specified key and direction
    * @param key Key to order by
    * @param dir Direction: 'asc' | 'desc' (default: 'asc')
+   *
+   * @remarks
+   * - This method performs in-memory sorting.
+   * - For optimized sorting using `IndexedDB` indexes, use {@link sortByIndex} instead.
    */
   orderBy<Key extends NestedPrimitiveKey<T>>(key: Key, dir?: SortDirection): this;
+  /**
+   * @instance Order results by index using optimized `IndexedDB` cursor
+   * @param indexName Name of the index to sort by
+   * @param dir Direction: 'asc' | 'desc' (default: 'asc')
+   *
+   * @remarks
+   * - This method uses `IndexedDB` indexes for sorting, which is more efficient for large datasets.
+   * - Ensure that the specified index exists on the table.
+   * - For in-memory sorting, use {@link orderBy} instead.
+   */
+  sortByIndex<IdxKey extends $InferIndex<Tbl['columns']> | $InferPrimaryKey<Tbl['columns']>>(indexName: IdxKey, dir?: SortDirection): this;
   /**
    * @instance Limit number of results
    * @param count Maximum number of results to return
@@ -393,26 +416,33 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
   /** Fetch all matching records with selected fields */
   findAll<Selection extends Partial<Record<keyof T, boolean>>>(this: SelectQuery<T, Selection>): Promise<SelectFields<T, Selection>[]>;
   /** Fetch first matching record */
-  first(this: SelectQuery<T, null>): Promise<T | null>;
+  findFirst(this: SelectQuery<T, null>): Promise<T | null>;
   /** Fetch first matching record with selected fields */
-  first<Selection extends Partial<Record<keyof T, boolean>>>(this: SelectQuery<T, Selection>): Promise<SelectFields<T, Selection> | null>;
+  findFirst<Selection extends Partial<Record<keyof T, boolean>>>(this: SelectQuery<T, Selection>): Promise<SelectFields<T, Selection> | null>;
   /**
    * @instance Find record by primary key (optimized `IndexedDB` get)
    * @param key Primary key value
+   *
+   * @remarks
+   * - This method uses the `IndexedDB` primary key for efficient querying.
+   * - Ensure that the specified key exists on the table.
+   * - To find by index, use {@link findByIndex} instead.
    */
   findByPk(key: $InferPrimaryKey<Tbl['columns']> extends keyof T ? T[$InferPrimaryKey<Tbl['columns']>] : T[keyof T]): Promise<S extends null ? T | null : S extends Partial<Record<keyof T, boolean>> ? SelectFields<T, S> | null : never>;
   /**
-   * @instance Find records by index (optimized IndexedDB index query)
+   * @instance Find records by index (optimized `IndexedDB` index query)
    * @param indexName Name of the index to query
    * @param query Key value to search for
-   */
-  findByIndex<IndexKey extends $InferIndex<Tbl['columns']> & keyof T & string>(indexName: IndexKey, query: T[IndexKey] | IDBKeyRange): Promise<S extends null ? T[] : S extends Partial<Record<keyof T, boolean>> ? SelectFields<T, S>[] : never>;
-  /**
-   * @instance Order results by index using optimized IndexedDB cursor
-   * @param indexName Name of the index to sort by
-   * @param dir Direction: 'asc' | 'desc' (default: 'asc')
-   */
-  sortByIndex<IndexKey extends ($InferIndex<Tbl['columns']> | $InferPrimaryKey<Tbl['columns']>) & keyof T & string>(indexName: IndexKey, dir?: SortDirection): this;
+   *
+   * @remarks
+   * - This method uses `IndexedDB` indexes for efficient querying.
+   * - Ensure that the specified index exists on the table.
+   * - To find by primary key, use {@link findByPk} instead.
+   */
+  findByIndex<IdxKey extends $InferIndex<Tbl['columns']> & keyof T & string>(indexName: IdxKey, query: T[IdxKey] | IDBKeyRange): Promise<S extends null ? T[] : S extends Partial<Record<keyof T, boolean>> ? SelectFields<T, S>[] : never>;
+  /** @instance Count matching records */
+  count(): Promise<number>;
+  exists(): Promise<boolean>;
 }
 /** @class Insert query builder. */
 declare class InsertQuery<Raw extends GenericObject, Inserted extends Raw | Raw[], Data extends GenericObject, Return extends (Inserted extends Array<infer _> ? Data[] : Data)> {
@@ -848,4 +878,4 @@ declare function deleteDB(name: string): Promise<void>;
  */
 declare function validateColumnType<T extends TypeName>(type: T, value: unknown): string | null;
 //#endregion
-export { $InferAutoInc, $InferDefault, $InferIndex, $InferOptional, $InferPrimaryKey, $InferRow, $InferTimestamp, $InferUUID, $InferUnique, $UUID, $UUIDVersion, $UnionToIntersection, $ValidateSinglePK, AdvancedTypes, ArrayToTuple, AsyncFunction, BasicPrimitive, Branded, type Column, ColumnDefinition, ColumnRecord, Constructor, DateLike, FirstOverloadParams, GenericFn, GenericObject, IndexConfig, IndexKeyType, InferInsertType, InferSelectType, InferUpdateType, List, Locality, LocalityConfig, LooseLiteral, MapObjectValues, Maybe, NestedPrimitiveKey, NormalPrimitive, Numeric, Prettify, PrimaryKeyType, Primitive, RejectFn, SchemaDefinition, SchemaRecord, SelectFields, SortDirection, StoreConfig, type Table, Timestamp, Tuple, TypeName, UUID, UUIDVersion, UniqueKeyType, ValidatedColumnDefinition, VoidFn, column, defineSchema, deleteDB, getTimestamp, isTimestamp, openDBWithStores, table, uuidV4, validateColumnType };
+export { $InferAutoInc, $InferDefault, $InferIndex, $InferOptional, $InferPrimaryKey, $InferRow, $InferTimestamp, $InferUUID, $InferUnique, $UUID, $UUIDVersion, $UnionToIntersection, $ValidateSinglePK, AdvancedTypes, ArrayToTuple, AsyncFunction, BasicPrimitive, Branded, type Column, ColumnDefinition, ColumnRecord, Constructor, DateLike, FirstOverloadParams, GenericFn, GenericObject, IndexConfig, IndexKeyType, InferInsertType, InferSelectType, InferUpdateType, List, Locality, LocalityConfig, LooseLiteral, MapObjectValues, Maybe, NestedPrimitiveKey, NormalPrimitive, Numeric, Prettify, PrimaryKeyType, Primitive, RejectFn, SchemaDefinition, SchemaRecord, SelectFields, SortDirection, StoreConfig, type Table, Timestamp, Tuple, TypeName, UUID, UUIDVersion, UniqueKeyType, ValidatedColumnDefinition, VoidFn, WherePredicate, column, defineSchema, deleteDB, getTimestamp, isTimestamp, openDBWithStores, table, uuidV4, validateColumnType };

package/dist/index.d.mts

@@ -329,6 +329,8 @@ type $InferTimestamp<T extends ColumnDefinition> = { [K in keyof T]: T[K] extend
 type Timestamp = Branded<string, 'Timestamp'>;
 /** Sort direction type for ordering queries */
 type SortDirection = 'asc' | 'desc';
+/** Predicate function type for WHERE clauses in queries */
+type WherePredicate<T extends GenericObject> = (row: T) => boolean;
 /** Creates a type for insert operations with auto-generated fields optional. */
 type InferInsertType<T extends Table> = Prettify<Omit<$InferRow<T['columns']>, $InferAutoInc<T['columns']> | $InferDefault<T['columns']> | $InferTimestamp<T['columns']> | $InferUUID<T['columns']>> & { [K in $InferAutoInc<T['columns']> | $InferDefault<T['columns']> | $InferTimestamp<T['columns']> | $InferUUID<T['columns']>]?: K extends keyof $InferRow<T['columns']> ? $InferRow<T['columns']>[K] : never }>;
 /** Creates a type for update operations with all fields optional except primary key. */
@@ -376,13 +378,34 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
    * @instance  Filter rows based on predicate function
    * @param predicate Filtering function
    */
-  where(predicate: (row: T) => boolean): this;
+  where(predicate: WherePredicate<T>): this;
+  /**
+   * @instance  Filter rows based on index query
+   * @param indexName Name of the index/primary key to query
+   * @param query Key value or {@link IDBKeyRange} to search for
+   */
+  where<IdxKey extends $InferPrimaryKey<Tbl['columns']> | $InferIndex<Tbl['columns']>>(indexName: IdxKey, query: IDBKeyRange | T[IdxKey]): this;
   /**
    * @instance  Order results by specified key and direction
    * @param key Key to order by
    * @param dir Direction: 'asc' | 'desc' (default: 'asc')
+   *
+   * @remarks
+   * - This method performs in-memory sorting.
+   * - For optimized sorting using `IndexedDB` indexes, use {@link sortByIndex} instead.
    */
   orderBy<Key extends NestedPrimitiveKey<T>>(key: Key, dir?: SortDirection): this;
+  /**
+   * @instance Order results by index using optimized `IndexedDB` cursor
+   * @param indexName Name of the index to sort by
+   * @param dir Direction: 'asc' | 'desc' (default: 'asc')
+   *
+   * @remarks
+   * - This method uses `IndexedDB` indexes for sorting, which is more efficient for large datasets.
+   * - Ensure that the specified index exists on the table.
+   * - For in-memory sorting, use {@link orderBy} instead.
+   */
+  sortByIndex<IdxKey extends $InferIndex<Tbl['columns']> | $InferPrimaryKey<Tbl['columns']>>(indexName: IdxKey, dir?: SortDirection): this;
   /**
    * @instance Limit number of results
    * @param count Maximum number of results to return
@@ -393,26 +416,33 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
   /** Fetch all matching records with selected fields */
   findAll<Selection extends Partial<Record<keyof T, boolean>>>(this: SelectQuery<T, Selection>): Promise<SelectFields<T, Selection>[]>;
   /** Fetch first matching record */
-  first(this: SelectQuery<T, null>): Promise<T | null>;
+  findFirst(this: SelectQuery<T, null>): Promise<T | null>;
   /** Fetch first matching record with selected fields */
-  first<Selection extends Partial<Record<keyof T, boolean>>>(this: SelectQuery<T, Selection>): Promise<SelectFields<T, Selection> | null>;
+  findFirst<Selection extends Partial<Record<keyof T, boolean>>>(this: SelectQuery<T, Selection>): Promise<SelectFields<T, Selection> | null>;
   /**
    * @instance Find record by primary key (optimized `IndexedDB` get)
    * @param key Primary key value
+   *
+   * @remarks
+   * - This method uses the `IndexedDB` primary key for efficient querying.
+   * - Ensure that the specified key exists on the table.
+   * - To find by index, use {@link findByIndex} instead.
    */
   findByPk(key: $InferPrimaryKey<Tbl['columns']> extends keyof T ? T[$InferPrimaryKey<Tbl['columns']>] : T[keyof T]): Promise<S extends null ? T | null : S extends Partial<Record<keyof T, boolean>> ? SelectFields<T, S> | null : never>;
   /**
-   * @instance Find records by index (optimized IndexedDB index query)
+   * @instance Find records by index (optimized `IndexedDB` index query)
    * @param indexName Name of the index to query
    * @param query Key value to search for
-   */
-  findByIndex<IndexKey extends $InferIndex<Tbl['columns']> & keyof T & string>(indexName: IndexKey, query: T[IndexKey] | IDBKeyRange): Promise<S extends null ? T[] : S extends Partial<Record<keyof T, boolean>> ? SelectFields<T, S>[] : never>;
-  /**
-   * @instance Order results by index using optimized IndexedDB cursor
-   * @param indexName Name of the index to sort by
-   * @param dir Direction: 'asc' | 'desc' (default: 'asc')
-   */
-  sortByIndex<IndexKey extends ($InferIndex<Tbl['columns']> | $InferPrimaryKey<Tbl['columns']>) & keyof T & string>(indexName: IndexKey, dir?: SortDirection): this;
+   *
+   * @remarks
+   * - This method uses `IndexedDB` indexes for efficient querying.
+   * - Ensure that the specified index exists on the table.
+   * - To find by primary key, use {@link findByPk} instead.
+   */
+  findByIndex<IdxKey extends $InferIndex<Tbl['columns']> & keyof T & string>(indexName: IdxKey, query: T[IdxKey] | IDBKeyRange): Promise<S extends null ? T[] : S extends Partial<Record<keyof T, boolean>> ? SelectFields<T, S>[] : never>;
+  /** @instance Count matching records */
+  count(): Promise<number>;
+  exists(): Promise<boolean>;
 }
 /** @class Insert query builder. */
 declare class InsertQuery<Raw extends GenericObject, Inserted extends Raw | Raw[], Data extends GenericObject, Return extends (Inserted extends Array<infer _> ? Data[] : Data)> {
@@ -848,4 +878,4 @@ declare function deleteDB(name: string): Promise<void>;
  */
 declare function validateColumnType<T extends TypeName>(type: T, value: unknown): string | null;
 //#endregion
-export { $InferAutoInc, $InferDefault, $InferIndex, $InferOptional, $InferPrimaryKey, $InferRow, $InferTimestamp, $InferUUID, $InferUnique, $UUID, $UUIDVersion, $UnionToIntersection, $ValidateSinglePK, AdvancedTypes, ArrayToTuple, AsyncFunction, BasicPrimitive, Branded, type Column, ColumnDefinition, ColumnRecord, Constructor, DateLike, FirstOverloadParams, GenericFn, GenericObject, IndexConfig, IndexKeyType, InferInsertType, InferSelectType, InferUpdateType, List, Locality, LocalityConfig, LooseLiteral, MapObjectValues, Maybe, NestedPrimitiveKey, NormalPrimitive, Numeric, Prettify, PrimaryKeyType, Primitive, RejectFn, SchemaDefinition, SchemaRecord, SelectFields, SortDirection, StoreConfig, type Table, Timestamp, Tuple, TypeName, UUID, UUIDVersion, UniqueKeyType, ValidatedColumnDefinition, VoidFn, column, defineSchema, deleteDB, getTimestamp, isTimestamp, openDBWithStores, table, uuidV4, validateColumnType };
+export { $InferAutoInc, $InferDefault, $InferIndex, $InferOptional, $InferPrimaryKey, $InferRow, $InferTimestamp, $InferUUID, $InferUnique, $UUID, $UUIDVersion, $UnionToIntersection, $ValidateSinglePK, AdvancedTypes, ArrayToTuple, AsyncFunction, BasicPrimitive, Branded, type Column, ColumnDefinition, ColumnRecord, Constructor, DateLike, FirstOverloadParams, GenericFn, GenericObject, IndexConfig, IndexKeyType, InferInsertType, InferSelectType, InferUpdateType, List, Locality, LocalityConfig, LooseLiteral, MapObjectValues, Maybe, NestedPrimitiveKey, NormalPrimitive, Numeric, Prettify, PrimaryKeyType, Primitive, RejectFn, SchemaDefinition, SchemaRecord, SelectFields, SortDirection, StoreConfig, type Table, Timestamp, Tuple, TypeName, UUID, UUIDVersion, UniqueKeyType, ValidatedColumnDefinition, VoidFn, WherePredicate, column, defineSchema, deleteDB, getTimestamp, isTimestamp, openDBWithStores, table, uuidV4, validateColumnType };