locality-idb 1.1.0 → 1.1.1

package/README.md

@@ -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.
@@ -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<IdxKey>(indexName: IdxKey, 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

@@ -487,6 +487,7 @@ var SelectQuery = class {
 	#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);
@@ -523,13 +524,13 @@ var SelectQuery = class {
 		this[Selected] = cols;
 		return this;
 	}
-	where(predicate, query) {
-		if (isFunction(predicate)) {
-			this.#whereCondition = predicate;
+	where(condition, query) {
+		if (isFunction(condition)) {
+			this.#whereCondition = condition;
 			this.#whereIndexName = void 0;
 			this.#whereIndexQuery = void 0;
-		} else if (isNonEmptyString(predicate) && !isUndefined(query)) {
-			this.#whereIndexName = predicate;
+		} else if (isNonEmptyString(condition) && !isUndefined(query)) {
+			this.#whereIndexName = condition;
 			this.#whereIndexQuery = query;
 			this.#whereCondition = void 0;
 		}
@@ -731,6 +732,9 @@ var SelectQuery = class {
 			request.onerror = () => reject(request.error);
 		});
 	}
+	async exists() {
+		return await this.count() > 0;
+	}
 };
 /** @class Insert query builder. */
 var InsertQuery = class {

package/dist/index.d.cts

@@ -384,7 +384,7 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
    * @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[keyof T]): this;
+  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
@@ -442,6 +442,7 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
   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)> {

package/dist/index.d.mts

@@ -384,7 +384,7 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
    * @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[keyof T]): this;
+  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
@@ -442,6 +442,7 @@ declare class SelectQuery<T extends GenericObject, S extends Partial<Record<stri
   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)> {

package/dist/index.iife.js

@@ -489,6 +489,7 @@ var LocalityIDB = (function(exports) {
 		#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);
@@ -525,13 +526,13 @@ var LocalityIDB = (function(exports) {
 			this[Selected] = cols;
 			return this;
 		}
-		where(predicate, query) {
-			if (isFunction(predicate)) {
-				this.#whereCondition = predicate;
+		where(condition, query) {
+			if (isFunction(condition)) {
+				this.#whereCondition = condition;
 				this.#whereIndexName = void 0;
 				this.#whereIndexQuery = void 0;
-			} else if (isNonEmptyString(predicate) && !isUndefined(query)) {
-				this.#whereIndexName = predicate;
+			} else if (isNonEmptyString(condition) && !isUndefined(query)) {
+				this.#whereIndexName = condition;
 				this.#whereIndexQuery = query;
 				this.#whereCondition = void 0;
 			}
@@ -733,6 +734,9 @@ var LocalityIDB = (function(exports) {
 				request.onerror = () => reject(request.error);
 			});
 		}
+		async exists() {
+			return await this.count() > 0;
+		}
 	};
 	/** @class Insert query builder. */
 	var InsertQuery = class {

package/dist/index.mjs

@@ -486,6 +486,7 @@ var SelectQuery = class {
 	#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);
@@ -522,13 +523,13 @@ var SelectQuery = class {
 		this[Selected] = cols;
 		return this;
 	}
-	where(predicate, query) {
-		if (isFunction(predicate)) {
-			this.#whereCondition = predicate;
+	where(condition, query) {
+		if (isFunction(condition)) {
+			this.#whereCondition = condition;
 			this.#whereIndexName = void 0;
 			this.#whereIndexQuery = void 0;
-		} else if (isNonEmptyString(predicate) && !isUndefined(query)) {
-			this.#whereIndexName = predicate;
+		} else if (isNonEmptyString(condition) && !isUndefined(query)) {
+			this.#whereIndexName = condition;
 			this.#whereIndexQuery = query;
 			this.#whereCondition = void 0;
 		}
@@ -730,6 +731,9 @@ var SelectQuery = class {
 			request.onerror = () => reject(request.error);
 		});
 	}
+	async exists() {
+		return await this.count() > 0;
+	}
 };
 /** @class Insert query builder. */
 var InsertQuery = class {

package/dist/index.umd.js

@@ -492,6 +492,7 @@
 		#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);
@@ -528,13 +529,13 @@
 			this[Selected] = cols;
 			return this;
 		}
-		where(predicate, query) {
-			if (isFunction(predicate)) {
-				this.#whereCondition = predicate;
+		where(condition, query) {
+			if (isFunction(condition)) {
+				this.#whereCondition = condition;
 				this.#whereIndexName = void 0;
 				this.#whereIndexQuery = void 0;
-			} else if (isNonEmptyString(predicate) && !isUndefined(query)) {
-				this.#whereIndexName = predicate;
+			} else if (isNonEmptyString(condition) && !isUndefined(query)) {
+				this.#whereIndexName = condition;
 				this.#whereIndexQuery = query;
 				this.#whereCondition = void 0;
 			}
@@ -736,6 +737,9 @@
 				request.onerror = () => reject(request.error);
 			});
 		}
+		async exists() {
+			return await this.count() > 0;
+		}
 	};
 	/** @class Insert query builder. */
 	var InsertQuery = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locality-idb",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "SQL-like query builder for IndexedDB with Drizzle-style API",
   "type": "module",
   "sideEffects": false,