@firtoz/idb-collections 0.2.0

package/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "@firtoz/idb-collections",
+	"version": "0.2.0",
+	"description": "IndexedDB collection utilities for TanStack DB — key-value adapter, query optimization",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"require": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/**/*.ts",
+		"!src/**/*.test.ts",
+		"README.md"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"test": "bun test",
+		"lint": "biome check --write src",
+		"lint:ci": "biome ci src",
+		"format": "biome format src --write"
+	},
+	"keywords": [
+		"typescript",
+		"tanstack",
+		"tanstack-db",
+		"indexeddb",
+		"idb",
+		"collections"
+	],
+	"author": "Firtina Ozbalikchi <firtoz@github.com>",
+	"license": "MIT",
+	"homepage": "https://github.com/firtoz/fullstack-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/firtoz/fullstack-toolkit.git",
+		"directory": "packages/idb-collections"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@standard-schema/spec": ">=1.1.0",
+		"@tanstack/db": ">=0.5.33"
+	},
+	"devDependencies": {
+		"@standard-schema/spec": "^1.1.0",
+		"@tanstack/db": "^0.5.33",
+		"bun-types": "^1.3.10",
+		"zod": "^4.3.6"
+	},
+	"dependencies": {
+		"@firtoz/db-helpers": "^2.0.0"
+	}
+}

package/src/idb-query-utils.ts

@@ -0,0 +1,102 @@
+import type { IR } from "@tanstack/db";
+import { extractSimpleComparisons } from "@tanstack/db";
+
+/**
+ * Key range specification for index queries.
+ * Used by IndexedDB implementations to build IDBKeyRange objects.
+ */
+export interface KeyRangeSpec {
+	type: "only" | "lowerBound" | "upperBound" | "bound";
+	value?: unknown;
+	lower?: unknown;
+	upper?: unknown;
+	lowerOpen?: boolean;
+	upperOpen?: boolean;
+}
+
+/**
+ * Attempts to extract a simple indexed query from an IR expression.
+ * Returns the field name and key range if the query can be optimized.
+ *
+ * IndexedDB indexes are much more limited than SQL WHERE clauses:
+ * - Only supports simple comparisons on a SINGLE indexed field
+ * - Supported operators: eq, gt, gte, lt, lte
+ * - Complex queries (AND, OR, NOT, multiple fields) fall back to in-memory filtering
+ */
+export function tryExtractIndexedQuery(
+	expression: IR.BasicExpression,
+	indexes?: Record<string, string>,
+	debug?: boolean,
+): { fieldName: string; indexName: string; keyRange: KeyRangeSpec } | null {
+	if (!indexes) {
+		return null;
+	}
+
+	try {
+		const comparisons = extractSimpleComparisons(expression);
+
+		if (comparisons.length !== 1) {
+			return null;
+		}
+
+		const comparison = comparisons[0];
+		const fieldName = comparison.field.join(".");
+		const indexName = indexes[fieldName];
+
+		if (!indexName) {
+			return null;
+		}
+
+		let keyRange: KeyRangeSpec | null = null;
+
+		switch (comparison.operator) {
+			case "eq":
+				keyRange = { type: "only", value: comparison.value };
+				break;
+			case "gt":
+				keyRange = {
+					type: "lowerBound",
+					lower: comparison.value,
+					lowerOpen: true,
+				};
+				break;
+			case "gte":
+				keyRange = {
+					type: "lowerBound",
+					lower: comparison.value,
+					lowerOpen: false,
+				};
+				break;
+			case "lt":
+				keyRange = {
+					type: "upperBound",
+					upper: comparison.value,
+					upperOpen: true,
+				};
+				break;
+			case "lte":
+				keyRange = {
+					type: "upperBound",
+					upper: comparison.value,
+					upperOpen: false,
+				};
+				break;
+			default:
+				if (debug) {
+					console.warn(
+						`Skipping indexed query extraction for unsupported operator: ${comparison.operator}`,
+					);
+				}
+				return null;
+		}
+
+		if (!keyRange) {
+			return null;
+		}
+
+		return { fieldName, indexName, keyRange };
+	} catch (error) {
+		console.error("Error extracting indexed query", error, expression);
+		return null;
+	}
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+	keyvalCollectionOptions,
+	createKeyValCollection,
+	type KeyValAdapter,
+	type KeyValCollectionConfig,
+	type KeyValCollection,
+} from "./keyvalCollection";
+
+export {
+	tryExtractIndexedQuery,
+	type KeyRangeSpec,
+} from "./idb-query-utils";

package/src/keyvalCollection.ts

@@ -0,0 +1,243 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+	type Collection,
+	type CollectionConfig,
+	createCollection,
+	type InferSchemaInput,
+	type InferSchemaOutput,
+	type IR,
+	type SyncMode,
+	parseOrderByExpression,
+} from "@tanstack/db";
+import type { SyncMessage, CollectionUtils } from "@firtoz/db-helpers";
+import { evaluateExpression } from "@firtoz/db-helpers";
+import {
+	type GenericBaseSyncConfig,
+	type GenericSyncBackend,
+	type GenericSyncFunctionResult,
+	createGenericSyncFunction,
+	createGenericCollectionConfig,
+} from "@firtoz/db-helpers";
+
+/**
+ * Minimal key-value storage adapter.
+ * Compatible with idb-keyval (almost directly) and localforage (via thin wrapper).
+ */
+export interface KeyValAdapter<T = unknown> {
+	get(key: string): Promise<T | null | undefined>;
+	set(key: string, value: T): Promise<void>;
+	del(key: string): Promise<void>;
+	entries(): Promise<[string, T][]>;
+	clear(): Promise<void>;
+	/** Optional batch set for performance. Falls back to sequential set() calls. */
+	setMany?(entries: [string, T][]): Promise<void>;
+	/** Optional batch delete for performance. Falls back to sequential del() calls. */
+	delMany?(keys: string[]): Promise<void>;
+}
+
+export interface KeyValCollectionConfig<TSchema extends StandardSchemaV1> {
+	schema: TSchema;
+	adapter: KeyValAdapter<InferSchemaOutput<TSchema>>;
+	/** Extracts the key from an item. Defaults to `(item) => item.id`. */
+	getKey?: (item: InferSchemaOutput<TSchema>) => string;
+	/** Promise that resolves when the adapter is ready. Defaults to resolved. */
+	readyPromise?: Promise<void>;
+	syncMode?: SyncMode;
+	debug?: boolean;
+	/** Called when a local mutation is persisted; use to broadcast to other peers/tabs. */
+	onBroadcast?: (
+		changes: SyncMessage<InferSchemaOutput<TSchema>, string | number>[],
+	) => void;
+}
+
+type KeyValUtils<TItem> = CollectionUtils<TItem>;
+
+function defaultGetKey<TSchema extends StandardSchemaV1>(
+	item: InferSchemaOutput<TSchema>,
+): string {
+	return (item as { id: string }).id;
+}
+
+export function keyvalCollectionOptions<TSchema extends StandardSchemaV1>(
+	config: KeyValCollectionConfig<TSchema>,
+): CollectionConfig<InferSchemaOutput<TSchema>, string, TSchema> & {
+	utils: KeyValUtils<InferSchemaOutput<TSchema>>;
+	schema: TSchema;
+} {
+	type TItem = InferSchemaOutput<TSchema>;
+
+	const adapter = config.adapter;
+	const getKey = config.getKey ?? defaultGetKey<TSchema>;
+	const readyPromise = config.readyPromise ?? Promise.resolve();
+
+	const adapterSetMany = async (entries: [string, TItem][]) => {
+		if (adapter.setMany) {
+			await adapter.setMany(entries);
+		} else {
+			for (const [key, value] of entries) {
+				await adapter.set(key, value);
+			}
+		}
+	};
+
+	const adapterDelMany = async (keys: string[]) => {
+		if (adapter.delMany) {
+			await adapter.delMany(keys);
+		} else {
+			for (const key of keys) {
+				await adapter.del(key);
+			}
+		}
+	};
+
+	const backend: GenericSyncBackend<TItem> = {
+		initialLoad: async () => {
+			const allEntries = await adapter.entries();
+			return allEntries.map(([, value]) => value);
+		},
+
+		loadSubset: async (options) => {
+			const allEntries = await adapter.entries();
+			let items = allEntries.map(([, value]) => value);
+
+			let combinedWhere = options.where;
+			if (options.cursor?.whereFrom) {
+				if (combinedWhere) {
+					combinedWhere = {
+						type: "func",
+						name: "and",
+						args: [combinedWhere, options.cursor.whereFrom],
+					} as IR.Func;
+				} else {
+					combinedWhere = options.cursor.whereFrom;
+				}
+			}
+
+			if (combinedWhere) {
+				const whereExpression = combinedWhere;
+				items = items.filter((item) =>
+					evaluateExpression(whereExpression, item as Record<string, unknown>),
+				);
+			}
+
+			if (options.orderBy) {
+				const sorts = parseOrderByExpression(options.orderBy);
+				items.sort((a, b) => {
+					for (const sort of sorts) {
+						// biome-ignore lint/suspicious/noExplicitAny: Need any for dynamic field access
+						let aValue: any = a;
+						// biome-ignore lint/suspicious/noExplicitAny: Need any for dynamic field access
+						let bValue: any = b;
+						for (const fieldName of sort.field) {
+							aValue = aValue?.[fieldName];
+							bValue = bValue?.[fieldName];
+						}
+
+						if (aValue < bValue) {
+							return sort.direction === "asc" ? -1 : 1;
+						}
+						if (aValue > bValue) {
+							return sort.direction === "asc" ? 1 : -1;
+						}
+					}
+					return 0;
+				});
+			}
+
+			if (options.offset !== undefined && options.offset > 0) {
+				items = items.slice(options.offset);
+			}
+
+			if (options.limit !== undefined) {
+				items = items.slice(0, options.limit);
+			}
+
+			return items;
+		},
+
+		handleInsert: async (itemsToInsert) => {
+			const entries: [string, TItem][] = itemsToInsert.map((item) => [
+				getKey(item),
+				item,
+			]);
+			await adapterSetMany(entries);
+			return itemsToInsert;
+		},
+
+		handleUpdate: async (mutations) => {
+			const results: TItem[] = [];
+			const entriesToSet: [string, TItem][] = [];
+
+			for (const mutation of mutations) {
+				const existing = await adapter.get(mutation.key);
+				if (existing) {
+					const updatedItem = {
+						...existing,
+						...mutation.changes,
+					} as TItem;
+					entriesToSet.push([mutation.key, updatedItem]);
+					results.push(updatedItem);
+				} else {
+					results.push(mutation.original);
+				}
+			}
+
+			if (entriesToSet.length > 0) {
+				await adapterSetMany(entriesToSet);
+			}
+
+			return results;
+		},
+
+		handleDelete: async (mutations) => {
+			const keysToDelete = mutations.map((m) => m.key);
+			await adapterDelMany(keysToDelete);
+		},
+
+		handleTruncate: async () => {
+			await adapter.clear();
+		},
+	};
+
+	const wrappedBackend: GenericSyncBackend<TItem> = {
+		...backend,
+		initialLoad: async () => {
+			if (config.syncMode === "eager" || !config.syncMode) {
+				return await backend.initialLoad();
+			}
+			return [];
+		},
+	};
+
+	const baseSyncConfig: GenericBaseSyncConfig = {
+		readyPromise,
+		syncMode: config.syncMode,
+		debug: config.debug,
+	};
+
+	const syncResult: GenericSyncFunctionResult<TItem> =
+		createGenericSyncFunction(baseSyncConfig, wrappedBackend);
+
+	return createGenericCollectionConfig<TItem, TSchema>({
+		schema: config.schema,
+		getKey,
+		syncResult,
+		syncMode: config.syncMode,
+	});
+}
+
+export type KeyValCollection<TSchema extends StandardSchemaV1> = Collection<
+	InferSchemaOutput<TSchema>,
+	string,
+	KeyValUtils<InferSchemaOutput<TSchema>>,
+	TSchema,
+	InferSchemaInput<TSchema>
+>;
+
+export function createKeyValCollection<TSchema extends StandardSchemaV1>(
+	config: KeyValCollectionConfig<TSchema>,
+): KeyValCollection<TSchema> {
+	return createCollection(
+		keyvalCollectionOptions(config),
+	) as KeyValCollection<TSchema>;
+}