schema-idb 0.0.4 → 0.0.6

package/README.md

@@ -2,10 +2,12 @@
 
 A type-safe IndexedDB layer that brings structure to client-side storage.
 
+[Live Example](https://stackblitz.com/edit/schema-idb)
+
 ```ts
 const db = openDB({
   name: "MyApp",
-  version: 1,
+  versionStrategy: "auto",
   stores: [usersStore] as const,
 });
 
@@ -13,8 +15,6 @@ await db.users.put({ id: "u1", name: "Kim", email: "kim@example.com" });
 const user = await db.users.get("u1");
 ```
 
-[Live Example](https://stackblitz.com/edit/schema-idb)
-
 ---
 
 ## What schema-idb provides
@@ -60,7 +60,7 @@ import { openDB } from "schema-idb";
 
 const db = openDB({
   name: "MyApp",
-  version: 1,
+  versionStrategy: "auto",
   stores: [usersStore] as const,
 });
 ```
@@ -223,6 +223,10 @@ const user = await db.users
 schema-idb exposes transactions as synchronous write batches across multiple stores.
 
 ```ts
+// Single store
+const tx = db.startTransaction("accounts");
+
+// Multiple stores
 const tx = db.startTransaction(["accounts", "logs"]);
 
 // Queue operations (no await between them)
@@ -235,9 +239,12 @@ await tx.commit();
 
 // Or abort
 tx.abort();
+
+// Access underlying IDBTransaction if needed
+tx.raw;
 ```
 
-Read operations are not available inside transactions. IndexedDB transactions auto-commit after any `await`, so reads must happen outside the transaction.
+Read operations are not available inside transactions. IndexedDB transactions auto-commit after any `await`, so schema-idb only supports synchronous write batching.
 
 ---
 
@@ -312,11 +319,55 @@ const db = openDB({
 - Index modifications
 - Index deletions
 
-### Requires manual migration (throws error)
+### Requires manual migration (throws error by default)
 
 - Store deletions (data loss)
 - keyPath changes (requires store recreation)
 
+### Handling removed stores
+
+When a store is removed from the schema, you can choose how to handle it:
+
+```ts
+const db = openDB({
+  name: "MyApp",
+  versionStrategy: "auto",
+  // 'error' (default): Throws an error when stores are removed
+  // 'preserve': Renames removed stores to __storeName_deleted_v{version}__ as backup.
+  //             Preserved stores are isolated from the typed API to avoid future name collisions.
+  removedStoreStrategy: "preserve",
+  stores: [usersStore] as const,
+});
+```
+
+#### Behavior with explicit versioning
+
+When `versionStrategy` is `"explicit"`:
+
+- Schema changes are **detected** but **NOT applied** automatically
+- `removedStoreStrategy` is evaluated for preview purposes only
+- A warning is logged if schema changes are detected but version is not bumped
+
+```
+[schema-idb] Schema changes detected but version not bumped:
+- Rename store "oldStore" to "__oldStore_deleted_v2__"
+Current DB version: 1, Provided version: 1
+Bump the version to apply these changes.
+```
+
+**Important:** `removedStoreStrategy` does not perform migrations in explicit mode. It only describes what _would_ happen after a version bump. To apply the changes, increment the `version` number.
+
+To explicitly delete a store (including backups), use a migration:
+
+```ts
+const usersStore = defineStore("users", {
+  // ...
+}).addMigration("003-delete-old-store", (db) => {
+  db.deleteObjectStore("oldStore");
+  db.deleteObjectStore("__oldStore_deleted_v2__"); // Remove backup too
+});
+```
+
 ---
 
 ## Type Inference
@@ -333,39 +384,689 @@ type User = InferStore<typeof usersStore>;
 
 ## API Reference
 
-### Database
+> This section is intended as a complete, authoritative reference.
+> Most users will not need to read it top-to-bottom.
+> For a guided introduction and examples, see the sections above.
+
+### openDB
+
+Opens a database connection with the given configuration.
+
+```ts
+function openDB<T extends readonly SchemaStoreDefinition[]>(options: {
+  name: string;
+  stores: T;
+  versionStrategy?: "auto" | "explicit";
+  version?: number;
+  removedStoreStrategy?: "error" | "preserve";
+}): SchemaDatabase<T>;
+```
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `name` | `string` | Database name |
+| `stores` | `readonly SchemaStoreDefinition[]` | Store definitions created with `defineStore` |
+| `versionStrategy` | `"auto" \| "explicit"` | `"auto"` detects schema changes automatically. Default: `"explicit"` (recommended for production control) |
+| `version` | `number` | Required when `versionStrategy` is `"explicit"` |
+| `removedStoreStrategy` | `"error" \| "preserve"` | How to handle removed stores. Default: `"error"` |
+
+### SchemaDatabase
+
+The database object returned by `openDB`.
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `name` | `string` | Database name |
+| `version` | `number` | Current schema version |
+| `ready` | `boolean` | Whether the database is ready |
+| `raw` | `IDBDatabase` | Underlying IndexedDB instance |
+| `[storeName]` | `StoreAccessor` | Direct access to stores (e.g., `db.users`) |
+
+| Method | Signature | Description |
+| ------ | --------- | ----------- |
+| `waitForReady` | `() => Promise<void>` | Wait for database initialization |
+| `close` | `() => void` | Close the database connection |
+| `startTransaction` | `(stores, options?) => Transaction` | Start a multi-store transaction |
+
+### Store Accessor
+
+Each store is accessible as a property on the database object (e.g., `db.users`).
+
+#### get
+
+```ts
+get(key: K): Promise<T | undefined>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `key` | `K` | Primary key value |
+
+Returns the record matching the key, or `undefined` if not found.
+
+#### getAll
+
+```ts
+getAll(): Promise<T[]>
+```
+
+Returns all records in the store.
+
+#### getBy
+
+```ts
+getBy<I extends IndexedFields>(indexName: I, query: V | IDBKeyRange): Promise<T | undefined>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `indexName` | `I` | Name of the index to query |
+| `query` | `V \| IDBKeyRange` | Value to match or key range |
+
+Returns the first record matching the index value.
+
+#### getAllBy
+
+```ts
+getAllBy<I extends IndexedFields>(indexName: I, query?: V | IDBKeyRange): Promise<T[]>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `indexName` | `I` | Name of the index to query |
+| `query` | `V \| IDBKeyRange` | Value to match or key range (optional) |
+
+Returns all records matching the index value. If `query` is omitted, returns all records ordered by the index.
+
+#### put
+
+```ts
+put(value: T, key?: K): Promise<K>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `T` | Record to insert or update |
+| `key` | `K` | Optional key (only needed if store has no keyPath) |
+
+Inserts a new record or updates an existing one. Returns the primary key.
+
+#### add
+
+```ts
+add(value: T, key?: K): Promise<K>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `T` | Record to insert |
+| `key` | `K` | Optional key (only needed if store has no keyPath) |
+
+Inserts a new record. Throws an error if the key already exists.
+
+#### delete
+
+```ts
+delete(key: K | IDBKeyRange): Promise<void>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `key` | `K \| IDBKeyRange` | Primary key or key range to delete |
+
+Deletes record(s) matching the key or range.
+
+#### clear
+
+```ts
+clear(): Promise<void>
+```
+
+Deletes all records in the store.
+
+#### count
+
+```ts
+count(query?: IDBKeyRange | IDBValidKey): Promise<number>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `query` | `IDBKeyRange \| IDBValidKey` | Optional key or range to count |
+
+Returns the number of records. If `query` is provided, counts only matching records.
+
+#### query
+
+```ts
+query(options: QueryOptions): Promise<T[]>
+query(): QueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `options` | `QueryOptions` | Query configuration (optional) |
+
+When called with options, executes the query and returns results. When called without arguments, returns a `QueryBuilder` for chaining.
+
+### Query Options
+
+Used with `db.store.query(options)`.
+
+```ts
+interface QueryOptions {
+  index: string;
+  where?: WhereCondition;
+  orderBy?: "asc" | "desc";
+  limit?: number;
+  offset?: number;
+}
+```
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `index` | `string` | Index name to query on |
+| `where` | `WhereCondition` | Filter conditions (optional) |
+| `orderBy` | `"asc" \| "desc"` | Sort order. Default: `"asc"` |
+| `limit` | `number` | Maximum number of results (optional) |
+| `offset` | `number` | Number of results to skip. Default: `0` |
+
+#### WhereCondition
+
+```ts
+interface WhereCondition {
+  eq?: T;
+  gt?: T;
+  gte?: T;
+  lt?: T;
+  lte?: T;
+  between?: [T, T];
+  startsWith?: string;
+}
+```
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `eq` | `T` | Exact match |
+| `gt` | `T` | Greater than |
+| `gte` | `T` | Greater than or equal |
+| `lt` | `T` | Less than |
+| `lte` | `T` | Less than or equal |
+| `between` | `[T, T]` | Inclusive range `[lower, upper]` |
+| `startsWith` | `string` | Prefix match (string indexes only) |
+
+### Query Builder
+
+Returned when calling `db.store.query()` without arguments.
+
+#### index
+
+```ts
+index<I extends IndexedFields>(name: I): IndexQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `I` | Index name to query on |
+
+Returns an `IndexQueryBuilder` for the specified index.
+
+#### key
+
+```ts
+key(): IndexQueryBuilder
+```
+
+Returns an `IndexQueryBuilder` that queries by primary key.
+
+#### findAll
+
+```ts
+findAll(): Promise<T[]>
+```
+
+Executes the query and returns all matching records.
+
+### IndexQueryBuilder
+
+Provides condition methods for filtering. All methods return a `FinalQueryBuilder`.
+
+#### equals
+
+```ts
+equals(value: V): FinalQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `V` | Value to match exactly |
+
+#### gt / gte / lt / lte
+
+```ts
+gt(value: V): FinalQueryBuilder   // Greater than
+gte(value: V): FinalQueryBuilder  // Greater than or equal
+lt(value: V): FinalQueryBuilder   // Less than
+lte(value: V): FinalQueryBuilder  // Less than or equal
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `V` | Boundary value for comparison |
+
+#### between
+
+```ts
+between(lower: V, upper: V): FinalQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `lower` | `V` | Lower bound (inclusive) |
+| `upper` | `V` | Upper bound (inclusive) |
+
+#### startsWith
+
+```ts
+startsWith(prefix: string): FinalQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `prefix` | `string` | Prefix to match |
+
+Only available for string indexes.
+
+### FinalQueryBuilder
+
+Provides result modifiers and execution methods.
+
+#### orderBy
+
+```ts
+orderBy(order: "asc" | "desc"): FinalQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `order` | `"asc" \| "desc"` | Sort direction |
+
+#### limit
+
+```ts
+limit(count: number): FinalQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `count` | `number` | Maximum number of results |
+
+#### offset
+
+```ts
+offset(count: number): FinalQueryBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `count` | `number` | Number of results to skip |
+
+#### findAll
+
+```ts
+findAll(): Promise<T[]>
+```
+
+Executes the query and returns all matching records.
+
+#### find
+
+```ts
+find(): Promise<T | undefined>
+```
+
+Executes the query and returns the first matching record, or `undefined` if none found.
+
+#### count
+
+```ts
+count(): Promise<number>
+```
+
+Returns the number of matching records without fetching them.
+
+### Transaction
+
+#### startTransaction
+
+```ts
+startTransaction(
+  stores: string | string[],
+  options?: TransactionOptions
+): Transaction
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `stores` | `string \| string[]` | Store name(s) to include in the transaction |
+| `options` | `TransactionOptions` | Transaction configuration (optional) |
+
+##### TransactionOptions
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `mode` | `"write"` | Transaction mode. Currently only `"write"` is supported |
+| `durability` | `"default" \| "strict" \| "relaxed"` | Durability hint for the transaction. Default: `"default"` |
+
+#### Transaction Object
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `raw` | `IDBTransaction` | Underlying IndexedDB transaction |
+| `[storeName]` | `TransactionStoreAccessor` | Synchronous store accessor for each included store |
+
+##### commit
+
+```ts
+commit(): Promise<void>
+```
+
+Commits all queued operations and waits for completion.
+
+##### abort
+
+```ts
+abort(): void
+```
+
+Aborts the transaction, discarding all queued operations.
+
+#### TransactionStoreAccessor
+
+Synchronous operations for use within transactions. Operations are queued and executed when `commit()` is called.
+
+##### put
+
+```ts
+put(value: T, key?: K): void
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `T` | Record to insert or update |
+| `key` | `K` | Optional key (only needed if store has no keyPath) |
+
+##### add
+
+```ts
+add(value: T, key?: K): void
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `T` | Record to insert |
+| `key` | `K` | Optional key (only needed if store has no keyPath) |
+
+##### delete
+
+```ts
+delete(key: K | IDBKeyRange): void
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `key` | `K \| IDBKeyRange` | Primary key or key range to delete |
+
+##### clear
+
+```ts
+clear(): void
+```
+
+Queues deletion of all records in the store.
+
+### defineStore
+
+Creates a store definition with schema.
+
+```ts
+defineStore<N extends string, S extends StoreSchema>(
+  name: N,
+  schema: S
+): SchemaStoreDefinition<N, S>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `N` | Store name (used as `db.name` accessor) |
+| `schema` | `S` | Object defining fields using `field` builders |
+
+Returns a `SchemaStoreDefinition` with the following method:
+
+#### addMigration
+
+```ts
+addMigration(
+  name: string,
+  fn: (db: IDBDatabase, tx: IDBTransaction) => void
+): this
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | Unique migration identifier (sorted alphabetically) |
+| `fn` | `MigrationFn` | Migration function with access to database and transaction |
+
+Migrations run during version upgrades in alphabetical order by name.
+
+### field
+
+Field type builders for schema definition.
+
+#### field.string
+
+```ts
+field.string(): FieldBuilder<string>
+```
+
+Creates a string field.
+
+#### field.number
+
+```ts
+field.number(): FieldBuilder<number>
+```
+
+Creates a number field.
+
+#### field.boolean
 
 ```ts
-const db = openDB({ name, version, stores });
+field.boolean(): FieldBuilder<boolean>
+```
+
+Creates a boolean field.
 
-db.waitForReady(); // Promise<void>
-db.ready; // boolean
-db.close(); // Close connection
-db.version; // Current version number
-db.raw; // Underlying IDBDatabase
+#### field.date
+
+```ts
+field.date(): FieldBuilder<Date>
 ```
 
-### Store operations
+Creates a Date field.
+
+#### field.object
 
 ```ts
-db.store.get(key); // Get by primary key
-db.store.getAll(); // Get all records
-db.store.getAllByIndex(index, value); // Get by index value
-db.store.put(value); // Insert or update
-db.store.add(value); // Insert (fails if exists)
-db.store.delete(key); // Delete by key
-db.store.clear(); // Delete all
-db.store.count(); // Count records
-db.store.query(options); // Query with conditions
+field.object<S>(schema: (t: TypeFactory) => S): FieldBuilder<InferObjectType<S>>
 ```
 
-### Utilities
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `schema` | `(t: TypeFactory) => S` | Function returning an object schema using type builders |
+
+Creates a nested object field.
 
 ```ts
-import { deleteDB, isIndexedDBAvailable } from "schema-idb";
+field.object(t => ({
+  street: t.string(),
+  city: t.string(),
+  zipCode: t.number().optional(),
+}))
+```
+
+#### field.tuple
 
-await deleteDB("MyApp");
-isIndexedDBAvailable();
+```ts
+field.tuple<T>(schema: (t: TypeFactory) => T): FieldBuilder<InferTupleType<T>>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `schema` | `(t: TypeFactory) => T` | Function returning a tuple schema as array |
+
+Creates a fixed-length tuple field.
+
+```ts
+field.tuple(t => [t.number(), t.number()])  // [number, number]
+```
+
+#### field.enum
+
+```ts
+field.enum<T extends readonly string[]>(values: T): FieldBuilder<T[number]>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `values` | `readonly string[]` | Array of allowed string values |
+
+Creates a string union type field.
+
+```ts
+field.enum(['active', 'inactive', 'pending'] as const)
+```
+
+#### field.nativeEnum
+
+```ts
+field.nativeEnum<T extends Record<string, string | number>>(enumObj: T): FieldBuilder<T[keyof T]>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `enumObj` | `T` | TypeScript enum object |
+
+Creates a field from a TypeScript enum.
+
+```ts
+enum Status { Active = 'active', Inactive = 'inactive' }
+field.nativeEnum(Status)
+```
+
+### FieldBuilder
+
+Methods available on all field builders. All methods return `this` for chaining.
+
+#### primaryKey
+
+```ts
+primaryKey(): FieldBuilder
+```
+
+Marks the field as the store's primary key. Exactly one field per store must be marked as primary key.
+
+#### index
+
+```ts
+index(options?: IndexOptions): FieldBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `options.unique` | `boolean` | If `true`, enforces unique values. Default: `false` |
+| `options.multiEntry` | `boolean` | If `true`, indexes each array element separately. Default: `false` |
+
+Creates an index on this field, enabling queries via `query()`, `getBy()`, and `getAllBy()`.
+
+#### optional
+
+```ts
+optional(): FieldBuilder
+```
+
+Marks the field as optional, allowing `undefined` values.
+
+#### default
+
+```ts
+default(value: T | (() => T)): FieldBuilder
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `value` | `T \| (() => T)` | Default value or factory function |
+
+Sets a default value applied on read when the field is missing. Factory functions are called for each read.
+
+```ts
+field.number().default(0)
+field.date().default(() => new Date())
+```
+
+#### array
+
+```ts
+array(): FieldBuilder<T[]>
+```
+
+Converts the field type to an array.
+
+```ts
+field.string().array()  // string[]
+```
+
+### Utility Functions
+
+#### deleteDB
+
+```ts
+deleteDB(name: string): Promise<void>
+```
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | Database name to delete |
+
+Deletes the database and all its data.
+
+#### isIndexedDBAvailable
+
+```ts
+isIndexedDBAvailable(): boolean
+```
+
+Returns `true` if IndexedDB is available in the current environment.
+
+### Type Utilities
+
+#### InferStore
+
+```ts
+type InferStore<T> = /* inferred output type from store definition */
+```
+
+Extracts the TypeScript type from a store definition:
+
+```ts
+const usersStore = defineStore("users", {
+  id: field.string().primaryKey(),
+  name: field.string(),
+  age: field.number().optional().default(0),
+});
+
+type User = InferStore<typeof usersStore>;
+// { id: string; name: string; age: number }
 ```
 
 ---

package/dist/createSchemaDB.d.ts

@@ -1,4 +1,4 @@
-import type { StoreSchema, InferInput, InferOutput, PrimaryKeyType, IndexedFields } from './field.js';
+import type { StoreSchema, InferInput, InferOutput, PrimaryKeyType, IndexedFields, IndexFieldTypes } from './field.js';
 import type { SchemaStoreDefinition } from './schema.js';
 import type { TypedQueryOptions, TypedQueryBuilder } from './query.js';
 import type { Transaction, TransactionOptions } from './transaction.js';
@@ -7,7 +7,8 @@ type StoreNames<TStores extends readonly AnySchemaStore[]> = TStores[number]['na
 export interface SchemaStoreAccessor<S extends StoreSchema> {
     get(key: PrimaryKeyType<S>): Promise<InferOutput<S> | undefined>;
     getAll(): Promise<InferOutput<S>[]>;
-    getAllByIndex<I extends IndexedFields<S> & string>(indexName: I, query?: IDBKeyRange | IDBValidKey): Promise<InferOutput<S>[]>;
+    getBy<I extends IndexedFields<S> & string>(indexName: I, query: IDBKeyRange | IndexFieldTypes<S>[I]): Promise<InferOutput<S> | undefined>;
+    getAllBy<I extends IndexedFields<S> & string>(indexName: I, query?: IDBKeyRange | IndexFieldTypes<S>[I]): Promise<InferOutput<S>[]>;
     put(value: InferInput<S>, key?: PrimaryKeyType<S>): Promise<PrimaryKeyType<S>>;
     add(value: InferInput<S>, key?: PrimaryKeyType<S>): Promise<PrimaryKeyType<S>>;
     delete(key: PrimaryKeyType<S> | IDBKeyRange): Promise<void>;
@@ -20,6 +21,7 @@ export interface SchemaDBConfig<TStores extends readonly AnySchemaStore[]> {
     name: string;
     version?: number;
     versionStrategy?: 'explicit' | 'auto';
+    removedStoreStrategy?: 'error' | 'preserve';
     stores: TStores;
     onBlocked?: () => void;
     onVersionChange?: () => void;

package/dist/createSchemaDB.js

@@ -1 +1,9 @@
-"use strict";var P=Object.defineProperty;var c=(e,r)=>P(e,"name",{value:r,configurable:!0});import{openDatabase as T}from"./utils.js";import{createStoreAccessor as b}from"./storeAccessor.js";import{createStartTransaction as v}from"./transaction.js";import{determineAutoVersion as D,applySafeChanges as E,openDatabaseForSchemaRead as h}from"./schemaDetection.js";import{ensureSchemaHistoryStore as A,getAppliedMigrations as p,recordMigrationApplied as R,initializeSchemaHistory as x}from"./migrationHistory.js";function G(e){return e}c(G,"getKeyPathString");function z(e,r,o){const t=c(async()=>{if(await e.readyPromise,!e.idb)throw new Error("Database initialization failed");return b(e.idb,r,o)},"getAccessor");return new Proxy({},{get(n,d){return d==="query"?s=>s?t().then(i=>i.query(s)):M(e,r,o):async(...s)=>(await t())[d](...s)}})}c(z,"createLazyStoreAccessor");function M(e,r,o){const t=c(async()=>{if(await e.readyPromise,!e.idb)throw new Error("Database initialization failed");return b(e.idb,r,o).query()},"getQueryBuilder"),n=c(d=>new Proxy({},{get(s,i){return i==="findAll"||i==="find"||i==="count"?()=>d().then(a=>a[i]()):(...a)=>n(c(()=>d().then(l=>l[i](...a)),"newGetBuilder"))}}),"createBuilderProxy");return n(t)}c(M,"createLazyQueryBuilder");function k(e,r){const o={get name(){return e.idb?.name??r},get version(){return e.idb?.version??0},get raw(){if(!e.idb)throw new Error("Database not ready. Call waitForReady() first or check ready property.");return e.idb},get ready(){return e.ready},waitForReady(){return e.readyPromise},close(){e.idb?.close()},startTransaction(...t){if(!e.startTransaction){const[n,d]=t,s=Array.isArray(n)?n:[n];return j(e,s,d)}return e.startTransaction(...t)}};for(const t of e.stores)Object.defineProperty(o,t.name,{get(){return z(e,t.name,t.defaults)},enumerable:!0});return o}c(k,"buildSchemaDatabase");function j(e,r,o){const t={get raw(){throw new Error("Transaction raw is not available before ready state. Use await db.waitForReady() before starting transactions.")},async commit(){if(await e.readyPromise,!e.startTransaction)throw new Error("Database initialization failed");return e.startTransaction(r,o).commit()},abort(){}};for(const n of r)e.stores.find(s=>s.name===n)&&Object.defineProperty(t,n,{get(){throw new Error("Transaction operations before ready state are not yet supported. Use await db.waitForReady() before starting transactions.")},enumerable:!0});return t}c(j,"createLazyTransaction");function q(e){const r=[],o=new Set;for(const t of e)for(const n of t.migrations){if(o.has(n.name))throw new Error(`Duplicate migration name "${n.name}" found across stores`);o.add(n.name),r.push(n)}return r.sort((t,n)=>t.name.localeCompare(n.name))}c(q,"collectMigrations");function S(e,r){const o=new Set(r);return e.filter(t=>!o.has(t.name)).sort((t,n)=>t.name.localeCompare(n.name))}c(S,"filterPendingMigrations");function B(e,r,o,t,n,d,s){if(A(e),o===0){for(const a of t){const f=e.createObjectStore(a.name,{keyPath:a.keyPath});for(const l of a.indexes)f.createIndex(l.name,l.keyPath,{unique:l.unique??!1,multiEntry:l.multiEntry??!1})}x(r)}else s&&s.safe.length>0&&E(e,r,s.safe,t);let i=[...d];for(const a of n)try{const f=a.up(e,r);f instanceof Promise&&f.catch(l=>{console.error(`Migration "${a.name}" failed:`,l),r.abort()}),R(r,a.name,i),i=[...i,a.name].sort()}catch(f){throw console.error(`Migration "${a.name}" failed:`,f),r.abort(),f}}c(B,"handleUpgrade");export function openDB(e){const{name:r,version:o,versionStrategy:t="explicit",stores:n,onBlocked:d,onVersionChange:s}=e,i=new Set;for(const m of n){if(i.has(m.name))throw new Error(`Duplicate store name: "${m.name}"`);i.add(m.name)}const a=q(n);let f=c(()=>{},"readyResolve"),l=c(()=>{},"readyReject");const w={idb:null,ready:!1,error:null,readyPromise:new Promise((m,y)=>{f=m,l=y}),readyResolve:f,readyReject:l,stores:n,startTransaction:null},u=k(w,r);return C(w,r,o,t,n,a,d,s),u}c(openDB,"openDB");async function C(e,r,o,t,n,d,s,i){try{let a=[],f=null,l;if(t==="auto"){const u=await D(r,n);if(l=u.version,f=u.changes,u.version>1){const y=await h(r);y&&(a=await p(y),y.close())}S(d,a).length>0&&!u.needsUpgrade&&(l=u.version+1)}else{if(o===void 0)throw new Error('Version is required when versionStrategy is "explicit"');l=o;const u=await h(r);u&&(a=await p(u),u.close())}const g=S(d,a),w=await T(r,l,(u,m,y)=>{B(u,m,y,n,g,a,f)},s);i&&(w.onversionchange=i),e.idb=w,e.startTransaction=v(w,n),e.ready=!0,e.readyResolve()}catch(a){e.error=a instanceof Error?a:new Error(String(a)),e.readyReject(e.error)}}c(C,"initializeDatabase");
+"use strict";var E=Object.defineProperty;var d=(e,r)=>E(e,"name",{value:r,configurable:!0});import{openDatabase as T}from"./utils.js";import{createStoreAccessor as D}from"./storeAccessor.js";import{createStartTransaction as A}from"./transaction.js";import{determineAutoVersion as k,applySafeChanges as R,openDatabaseForSchemaRead as $,readExistingSchema as M,toDesiredSchema as z,detectSchemaChanges as j}from"./schemaDetection.js";import{ensureSchemaHistoryStore as B,getAppliedMigrations as x,recordMigrationApplied as C,initializeSchemaHistory as q}from"./migrationHistory.js";function Y(e){return e}d(Y,"getKeyPathString");function U(e,r,a){const n=d(async()=>{if(await e.readyPromise,!e.idb)throw new Error("Database initialization failed");return D(e.idb,r,a)},"getAccessor");return new Proxy({},{get(t,o){return o==="query"?c=>c?n().then(u=>u.query(c)):F(e,r,a):async(...c)=>(await n())[o](...c)}})}d(U,"createLazyStoreAccessor");function F(e,r,a){const n=d(async()=>{if(await e.readyPromise,!e.idb)throw new Error("Database initialization failed");return D(e.idb,r,a).query()},"getQueryBuilder"),t=d(o=>new Proxy({},{get(c,u){return u==="findAll"||u==="find"||u==="count"?()=>o().then(s=>s[u]()):(...s)=>t(d(()=>o().then(l=>l[u](...s)),"newGetBuilder"))}}),"createBuilderProxy");return t(n)}d(F,"createLazyQueryBuilder");function K(e,r){const a={get name(){return e.idb?.name??r},get version(){return e.idb?.version??0},get raw(){if(!e.idb)throw new Error("Database not ready. Call waitForReady() first or check ready property.");return e.idb},get ready(){return e.ready},waitForReady(){return e.readyPromise},close(){e.idb?.close()},startTransaction(...n){if(!e.startTransaction){const[t,o]=n,c=Array.isArray(t)?t:[t];return L(e,c,o)}return e.startTransaction(...n)}};for(const n of e.stores)Object.defineProperty(a,n.name,{get(){return U(e,n.name,n.defaults)},enumerable:!0});return a}d(K,"buildSchemaDatabase");function L(e,r,a){const n={get raw(){throw new Error("Transaction raw is not available before ready state. Use await db.waitForReady() before starting transactions.")},async commit(){if(await e.readyPromise,!e.startTransaction)throw new Error("Database initialization failed");return e.startTransaction(r,a).commit()},abort(){}};for(const t of r)e.stores.find(c=>c.name===t)&&Object.defineProperty(n,t,{get(){throw new Error("Transaction operations before ready state are not yet supported. Use await db.waitForReady() before starting transactions.")},enumerable:!0});return n}d(L,"createLazyTransaction");function O(e){const r=[],a=new Set;for(const n of e)for(const t of n.migrations){if(a.has(t.name))throw new Error(`Duplicate migration name "${t.name}" found across stores`);a.add(t.name),r.push(t)}return r.sort((n,t)=>n.name.localeCompare(t.name))}d(O,"collectMigrations");function N(e,r){const a=new Set(r);return e.filter(n=>!a.has(n.name)).sort((n,t)=>n.name.localeCompare(t.name))}d(N,"filterPendingMigrations");function V(e,r,a,n,t,o,c){if(B(e),a===0){for(const s of n){const i=e.createObjectStore(s.name,{keyPath:s.keyPath});for(const l of s.indexes)i.createIndex(l.name,l.keyPath,{unique:l.unique??!1,multiEntry:l.multiEntry??!1})}q(r)}else c&&c.safe.length>0&&R(e,r,c.safe,n);let u=[...o];for(const s of t)try{const i=s.up(e,r);i instanceof Promise&&i.catch(l=>{console.error(`Migration "${s.name}" failed:`,l),r.abort()}),C(r,s.name,u),u=[...u,s.name].sort()}catch(i){throw console.error(`Migration "${s.name}" failed:`,i),r.abort(),i}}d(V,"handleUpgrade");export function openDB(e){const{name:r,version:a,versionStrategy:n="explicit",removedStoreStrategy:t="error",stores:o,onBlocked:c,onVersionChange:u}=e,s=new Set;for(const f of o){if(s.has(f.name))throw new Error(`Duplicate store name: "${f.name}"`);s.add(f.name)}const i=O(o);let l=d(()=>{},"readyResolve"),g=d(()=>{},"readyReject");const p={idb:null,ready:!1,error:null,readyPromise:new Promise((f,y)=>{l=f,g=y}),readyResolve:l,readyReject:g,stores:o,startTransaction:null},m=K(p,r);return G(p,r,a,n,t,o,i,c,u),m}d(openDB,"openDB");async function G(e,r,a,n,t,o,c,u,s){try{let i=[],l=null,g;if(n==="auto"){const m=await k(r,o,{removedStoreStrategy:t});if(g=m.version,l=m.changes,m.version>1){const y=await $(r);y&&(i=await x(y),y.close())}N(c,i).length>0&&!m.needsUpgrade&&(g=m.version+1)}else{if(a===void 0)throw new Error('Version is required when versionStrategy is "explicit"');g=a;const m=await $(r);if(m){const f=m.version;i=await x(m);const y=M(m),_=z(o);m.close();const b=j(y,_);if(b.hasChanges){const S=[];for(const w of b.dangerous)w.type==="store_delete"&&t==="preserve"?b.safe.push({type:"store_rename",oldName:w.storeName,newName:`__${w.storeName}_deleted_v${f}__`}):S.push(w);if(S.length>0){const h=`Dangerous schema changes detected:
+${S.map(v=>{switch(v.type){case"store_delete":return`Store "${v.storeName}" would be deleted. Use removedStoreStrategy: 'preserve' to backup, or add a migration to explicitly delete it.`;case"keypath_change":return`Store "${v.storeName}" keyPath changed from "${v.oldKeyPath}" to "${v.newKeyPath}". This requires recreating the store with a manual migration.`;default:return"Unknown dangerous change"}}).join(`
+`)}
+
+Add explicit migrations to handle these changes safely.`;throw console.error("[schema-idb]",h),new Error(h)}if(b.dangerous=S,l=b,g<=f){const w=b.safe.map(h=>{switch(h.type){case"store_add":return`- Add store "${h.storeName}"`;case"store_rename":return`- Rename store "${h.oldName}" to "${h.newName}"`;case"index_add":return`- Add index "${h.indexName}" on "${h.storeName}"`;case"index_delete":return`- Delete index "${h.indexName}" from "${h.storeName}"`;default:return"- Schema change"}});console.warn(`[schema-idb] Schema changes detected but version not bumped:
+${w.join(`
+`)}
+Current DB version: ${f}, Provided version: ${g}
+Bump the version to apply these changes.`)}}}}const P=N(c,i),p=await T(r,g,(m,f,y)=>{V(m,f,y,o,P,i,l)},u);s&&(p.onversionchange=s),e.idb=p,e.startTransaction=A(p,o),e.ready=!0,e.readyResolve()}catch(i){e.error=i instanceof Error?i:new Error(String(i)),e.readyReject(e.error)}}d(G,"initializeDatabase");

package/dist/field.d.ts

@@ -92,6 +92,7 @@ export type IndexedFields<S extends StoreSchema> = {
 export type IndexFieldTypes<S extends StoreSchema> = {
     [K in IndexedFields<S>]: S[K] extends FieldBuilder<infer T, boolean, boolean, boolean> ? T : never;
 };
+export type FieldType<S extends StoreSchema, K extends keyof S> = S[K] extends FieldBuilder<infer T, boolean, boolean, boolean> ? T : never;
 export type InferStore<TStore> = TStore extends {
     schema: infer S;
 } ? S extends StoreSchema ? InferOutput<S> : never : never;

package/dist/query.d.ts

@@ -9,6 +9,22 @@ export interface WhereCondition<T = unknown> {
     between?: [T, T];
     startsWith?: string;
 }
+export type TypedWhereCondition<T> = T extends string ? {
+    eq?: T;
+    gt?: T;
+    gte?: T;
+    lt?: T;
+    lte?: T;
+    between?: [T, T];
+    startsWith?: string;
+} : {
+    eq?: T;
+    gt?: T;
+    gte?: T;
+    lt?: T;
+    lte?: T;
+    between?: [T, T];
+};
 export interface QueryOptions {
     index?: string;
     where?: WhereCondition;
@@ -16,13 +32,21 @@ export interface QueryOptions {
     limit?: number;
     offset?: number;
 }
-export interface TypedQueryOptions<S extends StoreSchema> {
-    index?: IndexedFields<S>;
+export type TypedQueryOptions<S extends StoreSchema> = {
+    [I in IndexedFields<S>]: {
+        index: I;
+        where?: TypedWhereCondition<IndexFieldTypes<S>[I]>;
+        orderBy?: SortOrder;
+        limit?: number;
+        offset?: number;
+    };
+}[IndexedFields<S>] | {
+    index?: undefined;
     where?: WhereCondition<unknown>;
     orderBy?: SortOrder;
     limit?: number;
     offset?: number;
-}
+};
 interface QueryState {
     indexName?: string;
     useKey: boolean;
@@ -125,20 +149,23 @@ export interface IndexQueryBuilder<T> {
     findAll(): Promise<T[]>;
     find(): Promise<T | undefined>;
 }
-export interface TypedIndexQueryBuilder<T, S extends StoreSchema, I extends IndexedFields<S>> {
-    equals(value: IndexFieldTypes<S>[I]): FinalQueryBuilder<T>;
-    gt(value: IndexFieldTypes<S>[I]): FinalQueryBuilder<T>;
-    gte(value: IndexFieldTypes<S>[I]): FinalQueryBuilder<T>;
-    lt(value: IndexFieldTypes<S>[I]): FinalQueryBuilder<T>;
-    lte(value: IndexFieldTypes<S>[I]): FinalQueryBuilder<T>;
-    between(lower: IndexFieldTypes<S>[I], upper: IndexFieldTypes<S>[I]): FinalQueryBuilder<T>;
-    startsWith(prefix: IndexFieldTypes<S>[I] extends string ? string : never): FinalQueryBuilder<T>;
+interface BaseIndexQueryBuilder<T, V> {
+    equals(value: V): FinalQueryBuilder<T>;
+    gt(value: V): FinalQueryBuilder<T>;
+    gte(value: V): FinalQueryBuilder<T>;
+    lt(value: V): FinalQueryBuilder<T>;
+    lte(value: V): FinalQueryBuilder<T>;
+    between(lower: V, upper: V): FinalQueryBuilder<T>;
     orderBy(order: SortOrder): FinalQueryBuilder<T>;
     limit(count: number): FinalQueryBuilder<T>;
     offset(count: number): FinalQueryBuilder<T>;
     findAll(): Promise<T[]>;
     find(): Promise<T | undefined>;
 }
+interface StringIndexQueryBuilder<T> {
+    startsWith(prefix: string): FinalQueryBuilder<T>;
+}
+export type TypedIndexQueryBuilder<T, S extends StoreSchema, I extends IndexedFields<S>> = BaseIndexQueryBuilder<T, IndexFieldTypes<S>[I]> & (IndexFieldTypes<S>[I] extends string ? StringIndexQueryBuilder<T> : {});
 export interface FinalQueryBuilder<T> {
     orderBy(order: SortOrder): FinalQueryBuilder<T>;
     limit(count: number): FinalQueryBuilder<T>;

package/dist/schemaDetection.d.ts

@@ -19,6 +19,10 @@ export type SchemaChangeType = {
 } | {
     type: 'store_delete';
     storeName: string;
+} | {
+    type: 'store_rename';
+    oldName: string;
+    newName: string;
 } | {
     type: 'keypath_change';
     storeName: string;
@@ -61,19 +65,16 @@ export declare function applySafeChanges(db: IDBDatabase, tx: IDBTransaction, ch
     keyPath: string | string[] | undefined;
     indexes: IndexDefinition[];
 }[]): void;
-export declare function generateSchemaFingerprint(stores: readonly {
-    name: string;
-    keyPath: string | string[] | undefined;
-    indexes: IndexDefinition[];
-}[]): string;
-export declare function hashFingerprint(fingerprint: string): number;
 export declare function getCurrentDatabaseVersion(dbName: string): Promise<number>;
 export declare function openDatabaseForSchemaRead(dbName: string): Promise<IDBDatabase | null>;
+export interface AutoVersionOptions {
+    removedStoreStrategy?: 'error' | 'preserve';
+}
 export declare function determineAutoVersion(dbName: string, stores: readonly {
     name: string;
     keyPath: string | string[] | undefined;
     indexes: IndexDefinition[];
-}[]): Promise<{
+}[], options?: AutoVersionOptions): Promise<{
     version: number;
     changes: SchemaChanges | null;
     needsUpgrade: boolean;

package/dist/schemaDetection.js

@@ -1,5 +1,5 @@
-"use strict";var y=Object.defineProperty;var c=(t,n)=>y(t,"name",{value:n,configurable:!0});function x(t){return t.startsWith("__")}c(x,"isInternalStore");export function readExistingSchema(t){const n=new Map,e=Array.from({length:t.objectStoreNames.length},(a,r)=>t.objectStoreNames.item(r)).filter(a=>!x(a));for(const a of e){const r=t.transaction(a,"readonly"),o=r.objectStore(a),i=new Map,u=Array.from({length:o.indexNames.length},(s,d)=>o.indexNames.item(d));for(const s of u){const d=o.index(s);i.set(s,{keyPath:d.keyPath,unique:d.unique,multiEntry:d.multiEntry})}n.set(a,{name:a,keyPath:o.keyPath,indexes:i}),r.abort()}return n}c(readExistingSchema,"readExistingSchema");export function toDesiredSchema(t){const n=new Map;for(const e of t)n.set(e.name,{name:e.name,keyPath:e.keyPath,indexes:e.indexes});return n}c(toDesiredSchema,"toDesiredSchema");function h(t,n){return t===n||t==null&&n==null?!0:t==null||n==null?!1:Array.isArray(t)&&Array.isArray(n)?t.length!==n.length?!1:t.every((e,a)=>e===n[a]):t===n}c(h,"keyPathEquals");export function detectSchemaChanges(t,n){const e=[],a=[];for(const[r,o]of n){const i=t.get(r);if(!i){e.push({type:"store_add",storeName:r});continue}if(!h(i.keyPath,o.keyPath)){a.push({type:"keypath_change",storeName:r,oldKeyPath:i.keyPath,newKeyPath:o.keyPath});continue}for(const s of o.indexes){const d=i.indexes.get(s.name);if(!d)e.push({type:"index_add",storeName:r,indexName:s.name,index:s});else{const m=!h(d.keyPath,s.keyPath),l=d.unique!==(s.unique??!1),f=d.multiEntry!==(s.multiEntry??!1);(m||l||f)&&(e.push({type:"index_delete",storeName:r,indexName:s.name}),e.push({type:"index_add",storeName:r,indexName:s.name,index:s}))}}const u=new Set(o.indexes.map(s=>s.name));for(const s of i.indexes.keys())u.has(s)||e.push({type:"index_delete",storeName:r,indexName:s})}for(const r of t.keys())n.has(r)||a.push({type:"store_delete",storeName:r});return{safe:e,dangerous:a,hasChanges:e.length>0||a.length>0}}c(detectSchemaChanges,"detectSchemaChanges");export function applySafeChanges(t,n,e,a){for(const r of e)switch(r.type){case"store_add":{const o=a.find(i=>i.name===r.storeName);if(o){const i=t.createObjectStore(o.name,{keyPath:o.keyPath});for(const u of o.indexes)i.createIndex(u.name,u.keyPath,{unique:u.unique??!1,multiEntry:u.multiEntry??!1})}break}case"index_add":{n.objectStore(r.storeName).createIndex(r.indexName,r.index.keyPath,{unique:r.index.unique??!1,multiEntry:r.index.multiEntry??!1});break}case"index_delete":{n.objectStore(r.storeName).deleteIndex(r.indexName);break}}}c(applySafeChanges,"applySafeChanges");export function generateSchemaFingerprint(t){const n=t.map(e=>({name:e.name,keyPath:e.keyPath,indexes:e.indexes.map(a=>({name:a.name,keyPath:a.keyPath,unique:a.unique??!1,multiEntry:a.multiEntry??!1})).sort((a,r)=>a.name.localeCompare(r.name))})).sort((e,a)=>e.name.localeCompare(a.name));return JSON.stringify(n)}c(generateSchemaFingerprint,"generateSchemaFingerprint");export function hashFingerprint(t){let n=0;for(let e=0;e<t.length;e++){const a=t.charCodeAt(e);n=(n<<5)-n+a,n=n&n}return Math.abs(n)}c(hashFingerprint,"hashFingerprint");export async function getCurrentDatabaseVersion(t){return new Promise(n=>{const e=indexedDB.open(t);e.onsuccess=()=>{const a=e.result,r=a.version;a.close(),n(r)},e.onerror=()=>{n(0)}})}c(getCurrentDatabaseVersion,"getCurrentDatabaseVersion");export async function openDatabaseForSchemaRead(t){return new Promise(n=>{const e=indexedDB.open(t);e.onsuccess=()=>{n(e.result)},e.onerror=()=>{n(null)},e.onupgradeneeded=()=>{e.transaction?.abort()}})}c(openDatabaseForSchemaRead,"openDatabaseForSchemaRead");export async function determineAutoVersion(t,n){const e=await openDatabaseForSchemaRead(t);if(!e)return{version:1,changes:null,needsUpgrade:!0};const a=e.version,r=readExistingSchema(e),o=toDesiredSchema(n);e.close();const i=detectSchemaChanges(r,o);if(!i.hasChanges)return{version:a,changes:null,needsUpgrade:!1};if(i.dangerous.length>0){const u=i.dangerous.map(s=>{switch(s.type){case"store_delete":return`Store "${s.storeName}" would be deleted. Use a manual migration to handle this.`;case"keypath_change":return`Store "${s.storeName}" keyPath changed from "${s.oldKeyPath}" to "${s.newKeyPath}". This requires recreating the store with a manual migration.`;default:return"Unknown dangerous change"}});throw new Error(`Dangerous schema changes detected:
-${u.join(`
+"use strict";var g=Object.defineProperty;var l=(r,t)=>g(r,"name",{value:t,configurable:!0});function p(r){return r.startsWith("__")}l(p,"isInternalStore");export function readExistingSchema(r){const t=new Map,n=Array.from({length:r.objectStoreNames.length},(a,o)=>r.objectStoreNames.item(o)).filter(a=>!p(a));for(const a of n){const o=r.transaction(a,"readonly"),u=o.objectStore(a),s=new Map,c=Array.from({length:u.indexNames.length},(e,i)=>u.indexNames.item(i));for(const e of c){const i=u.index(e);s.set(e,{keyPath:i.keyPath,unique:i.unique,multiEntry:i.multiEntry})}t.set(a,{name:a,keyPath:u.keyPath,indexes:s}),o.abort()}return t}l(readExistingSchema,"readExistingSchema");export function toDesiredSchema(r){const t=new Map;for(const n of r)t.set(n.name,{name:n.name,keyPath:n.keyPath,indexes:n.indexes});return t}l(toDesiredSchema,"toDesiredSchema");function x(r,t){return r===t||r==null&&t==null?!0:r==null||t==null?!1:Array.isArray(r)&&Array.isArray(t)?r.length!==t.length?!1:r.every((n,a)=>n===t[a]):r===t}l(x,"keyPathEquals");export function detectSchemaChanges(r,t){const n=[],a=[];for(const[o,u]of t){const s=r.get(o);if(!s){n.push({type:"store_add",storeName:o});continue}if(!x(s.keyPath,u.keyPath)){a.push({type:"keypath_change",storeName:o,oldKeyPath:s.keyPath,newKeyPath:u.keyPath});continue}for(const e of u.indexes){const i=s.indexes.get(e.name);if(!i)n.push({type:"index_add",storeName:o,indexName:e.name,index:e});else{const m=!x(i.keyPath,e.keyPath),h=i.unique!==(e.unique??!1),d=i.multiEntry!==(e.multiEntry??!1);(m||h||d)&&(n.push({type:"index_delete",storeName:o,indexName:e.name}),n.push({type:"index_add",storeName:o,indexName:e.name,index:e}))}}const c=new Set(u.indexes.map(e=>e.name));for(const e of s.indexes.keys())c.has(e)||n.push({type:"index_delete",storeName:o,indexName:e})}for(const o of r.keys())t.has(o)||a.push({type:"store_delete",storeName:o});return{safe:n,dangerous:a,hasChanges:n.length>0||a.length>0}}l(detectSchemaChanges,"detectSchemaChanges");export function applySafeChanges(r,t,n,a){const o=n.filter(s=>s.type==="store_rename"),u=new Map;for(const s of o){const c=t.objectStore(s.oldName),e=[],i=Array.from({length:c.indexNames.length},(h,d)=>c.indexNames.item(d));for(const h of i){const d=c.index(h);e.push({name:h,keyPath:d.keyPath,unique:d.unique,multiEntry:d.multiEntry})}u.set(s.oldName,{keyPath:c.keyPath,indexes:e,newName:s.newName});const m=c.getAll();m.onsuccess=()=>{const h=m.result,d=u.get(s.oldName),y=r.createObjectStore(d.newName,{keyPath:d.keyPath});for(const f of d.indexes)y.createIndex(f.name,f.keyPath,{unique:f.unique,multiEntry:f.multiEntry});for(const f of h)y.put(f)},r.deleteObjectStore(s.oldName)}for(const s of n)switch(s.type){case"store_add":{const c=a.find(e=>e.name===s.storeName);if(c){const e=r.createObjectStore(c.name,{keyPath:c.keyPath});for(const i of c.indexes)e.createIndex(i.name,i.keyPath,{unique:i.unique??!1,multiEntry:i.multiEntry??!1})}break}case"index_add":{t.objectStore(s.storeName).createIndex(s.indexName,s.index.keyPath,{unique:s.index.unique??!1,multiEntry:s.index.multiEntry??!1});break}case"index_delete":{t.objectStore(s.storeName).deleteIndex(s.indexName);break}}}l(applySafeChanges,"applySafeChanges");export async function getCurrentDatabaseVersion(r){return new Promise(t=>{const n=indexedDB.open(r);n.onsuccess=()=>{const a=n.result,o=a.version;a.close(),t(o)},n.onerror=()=>{t(0)}})}l(getCurrentDatabaseVersion,"getCurrentDatabaseVersion");export async function openDatabaseForSchemaRead(r){return new Promise(t=>{const n=indexedDB.open(r);n.onsuccess=()=>{t(n.result)},n.onerror=()=>{t(null)},n.onupgradeneeded=()=>{n.transaction?.abort(),t(null)}})}l(openDatabaseForSchemaRead,"openDatabaseForSchemaRead");export async function determineAutoVersion(r,t,n={}){const{removedStoreStrategy:a="error"}=n,o=await openDatabaseForSchemaRead(r);if(!o)return{version:1,changes:null,needsUpgrade:!0};const u=o.version,s=readExistingSchema(o),c=toDesiredSchema(t);o.close();const e=detectSchemaChanges(s,c);if(!e.hasChanges)return{version:u,changes:null,needsUpgrade:!1};const i=[];for(const m of e.dangerous)m.type==="store_delete"&&a==="preserve"?e.safe.push({type:"store_rename",oldName:m.storeName,newName:`__${m.storeName}_deleted_v${u}__`}):i.push(m);if(e.dangerous=i,e.dangerous.length>0){const h=`Dangerous schema changes detected:
+${e.dangerous.map(d=>{switch(d.type){case"store_delete":return`Store "${d.storeName}" would be deleted. Use removedStoreStrategy: 'preserve' to backup, or add a migration to explicitly delete it.`;case"keypath_change":return`Store "${d.storeName}" keyPath changed from "${d.oldKeyPath}" to "${d.newKeyPath}". This requires recreating the store with a manual migration.`;default:return"Unknown dangerous change"}}).join(`
 `)}
 
-Add explicit migrations to handle these changes safely.`)}return{version:a+1,changes:i,needsUpgrade:!0}}c(determineAutoVersion,"determineAutoVersion");
+Add explicit migrations to handle these changes safely.`;throw console.error("[schema-idb]",h),new Error(h)}return{version:u+1,changes:e,needsUpgrade:!0}}l(determineAutoVersion,"determineAutoVersion");

package/dist/storeAccessor.js

@@ -1 +1 @@
-"use strict";var p=Object.defineProperty;var a=(r,t)=>p(r,"name",{value:t,configurable:!0});import{promisifyTransaction as i}from"./utils.js";import{createQueryFunction as S}from"./query.js";async function u(r,t){return await i(r),t.result}a(u,"getResult");function f(r,t){if(r!==void 0)return{...t,...r}}a(f,"applyDefaults");function w(r,t){return Object.keys(t).length===0?r:r.map(s=>({...t,...s}))}a(w,"applyDefaultsToArray");export function createStoreAccessor(r,t,s={}){const y=Object.keys(s).length>0,x=S(r,t,s);return{async get(c){const n=r.transaction(t,"readonly"),e=n.objectStore(t),o=await u(n,e.get(c));return y?f(o,s):o},async getAll(c){const n=r.transaction(t,"readonly"),e=n.objectStore(t),o=await u(n,e.getAll(c?.query,c?.count));return y?w(o,s):o},async getAllByIndex(c,n){const e=r.transaction(t,"readonly"),j=e.objectStore(t).index(c),l=await u(e,j.getAll(n));return y?w(l,s):l},async put(c,n){const e=r.transaction(t,"readwrite"),o=e.objectStore(t);return u(e,o.put(c,n))},async add(c,n){const e=r.transaction(t,"readwrite"),o=e.objectStore(t);return u(e,o.add(c,n))},async delete(c){const n=r.transaction(t,"readwrite");n.objectStore(t).delete(c),await i(n)},async clear(){const c=r.transaction(t,"readwrite");c.objectStore(t).clear(),await i(c)},async count(c){const n=r.transaction(t,"readonly"),o=n.objectStore(t).count(c);return await i(n),o.result},async raw(c){const n=r.transaction(t,"readwrite"),e=n.objectStore(t),o=c(e);return await i(n),o.result},query:x}}a(createStoreAccessor,"createStoreAccessor");
+"use strict";var S=Object.defineProperty;var u=(r,t)=>S(r,"name",{value:t,configurable:!0});import{promisifyTransaction as y}from"./utils.js";import{createQueryFunction as p}from"./query.js";async function a(r,t){return await y(r),t.result}u(a,"getResult");function x(r,t){if(r!==void 0)return{...t,...r}}u(x,"applyDefaults");function j(r,t){return Object.keys(t).length===0?r:r.map(s=>({...t,...s}))}u(j,"applyDefaultsToArray");export function createStoreAccessor(r,t,s={}){const l=Object.keys(s).length>0,g=p(r,t,s);return{async get(c){const n=r.transaction(t,"readonly"),o=n.objectStore(t),e=await a(n,o.get(c));return l?x(e,s):e},async getAll(c){const n=r.transaction(t,"readonly"),o=n.objectStore(t),e=await a(n,o.getAll(c?.query,c?.count));return l?j(e,s):e},async getBy(c,n){const o=r.transaction(t,"readonly"),w=o.objectStore(t).index(c),i=await a(o,w.get(n));return l?x(i,s):i},async getAllBy(c,n){const o=r.transaction(t,"readonly"),w=o.objectStore(t).index(c),i=await a(o,w.getAll(n));return l?j(i,s):i},async put(c,n){const o=r.transaction(t,"readwrite"),e=o.objectStore(t);return a(o,e.put(c,n))},async add(c,n){const o=r.transaction(t,"readwrite"),e=o.objectStore(t);return a(o,e.add(c,n))},async delete(c){const n=r.transaction(t,"readwrite");n.objectStore(t).delete(c),await y(n)},async clear(){const c=r.transaction(t,"readwrite");c.objectStore(t).clear(),await y(c)},async count(c){const n=r.transaction(t,"readonly"),e=n.objectStore(t).count(c);return await y(n),e.result},async raw(c){const n=r.transaction(t,"readwrite"),o=n.objectStore(t),e=c(o);return await y(n),e.result},query:g}}u(createStoreAccessor,"createStoreAccessor");

package/dist/types.d.ts

@@ -83,7 +83,8 @@ export interface WriteChain<TStores extends readonly StoreDefinition[]> {
 export interface StoreAccessor<T, K> {
     get(key: K): Promise<T | undefined>;
     getAll(options?: GetAllOptions): Promise<T[]>;
-    getAllByIndex(indexName: string, query?: IDBKeyRange | IDBValidKey): Promise<T[]>;
+    getBy(indexName: string, query: IDBKeyRange | IDBValidKey): Promise<T | undefined>;
+    getAllBy(indexName: string, query?: IDBKeyRange | IDBValidKey): Promise<T[]>;
     put(value: T, key?: K): Promise<K>;
     add(value: T, key?: K): Promise<K>;
     delete(key: K | IDBKeyRange): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-idb",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Type-safe IndexedDB wrapper with chainable transactions",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/dist/createDB.d.ts

@@ -1,2 +0,0 @@
-import type { StoreDefinition, DatabaseConfig, DatabaseWithStores } from './types.js';
-export declare function openDB<const TStores extends readonly StoreDefinition[]>(config: DatabaseConfig<TStores>): Promise<DatabaseWithStores<TStores>>;

package/dist/createDB.js

@@ -1 +0,0 @@
-"use strict";var w=Object.defineProperty;var f=(n,t)=>w(n,"name",{value:t,configurable:!0});import{openDatabase as y,promisifyTransaction as b}from"./utils.js";import{createReadChain as S}from"./readChain.js";import{createWriteChain as v}from"./writeChain.js";import{createStoreAccessor as x}from"./storeAccessor.js";function D(n){const t=[],s=new Set;for(const r of n)for(const e of r.migrations){if(s.has(e.name))throw new Error(`Duplicate migration name "${e.name}" found across stores`);s.add(e.name),t.push(e)}return t.sort((r,e)=>r.name.localeCompare(e.name))}f(D,"collectMigrations");function E(n,t,s){const r={...n};for(const e of s)r[e.name]=x(t,e.name);return r}f(E,"buildDatabaseWithStores");function P(n,t,s,r,e){if(s===0)for(const a of r){const i=n.createObjectStore(a.name,{keyPath:a.keyPath,autoIncrement:a.autoIncrement});for(const c of a.indexes)i.createIndex(c.name,c.keyPath,{unique:c.unique??!1,multiEntry:c.multiEntry??!1})}for(const a of e)try{const i=a.up(n,t);i instanceof Promise&&i.catch(c=>{console.error(`Migration "${a.name}" failed:`,c),t.abort()})}catch(i){throw console.error(`Migration "${a.name}" failed:`,i),t.abort(),i}}f(P,"handleUpgrade");export async function openDB(n){const{name:t,version:s,versionStrategy:r="explicit",stores:e,onBlocked:a,onVersionChange:i}=n,c=new Set;for(const o of e){if(c.has(o.name))throw new Error(`Duplicate store name: "${o.name}"`);c.add(o.name)}let u;if(r==="auto")u=1;else{if(s===void 0)throw new Error('Version is required when versionStrategy is "explicit"');u=s}const p=D(e),m=await y(t,u,(o,l,d)=>{P(o,l,d,e,p)},a);return i&&(m.onversionchange=i),E({get name(){return m.name},get version(){return m.version},get raw(){return m},close(){m.close()},read(o){return S(m,o)},write(o){return v(m,o)},async transaction(o,l,d){const h=m.transaction(o,l),g=d(h);g instanceof Promise&&await g,await b(h)}},m,e)}f(openDB,"openDB");

package/dist/defineStore.d.ts

@@ -1,5 +0,0 @@
-import type { StoreDefinition, StoreKeyPath, ExtractKeyType, StoreOptionsWithKeyPath, StoreOptionsWithoutKeyPath } from './types.js';
-export declare function defineStore<T>(): {
-    <const TName extends string, const KP extends StoreKeyPath<T>>(name: TName, options: StoreOptionsWithKeyPath<T, KP>): StoreDefinition<T, ExtractKeyType<T, KP>, TName>;
-    <const TName extends string, K extends IDBValidKey = IDBValidKey>(name: TName, options?: StoreOptionsWithoutKeyPath<T, K>): StoreDefinition<T, K, TName>;
-};

package/dist/defineStore.js

@@ -1 +0,0 @@
-"use strict";var p=Object.defineProperty;var i=(t,e)=>p(t,"name",{value:e,configurable:!0});function g(t){if(!t)return[];const e=[];for(const[r,o]of Object.entries(t))o!==!1&&(o===!0?e.push({name:r,keyPath:r}):e.push({name:r,keyPath:r,unique:o.unique,multiEntry:o.multiEntry}));return e}i(g,"parseIndexConfig");export function defineStore(){function t(e,r={}){const{keyPath:o,autoIncrement:u=!1,indexes:m,migrations:a=[]}=r,f=g(m);if(!e||typeof e!="string")throw new Error("Store name is required and must be a string");const s=new Set;for(const n of a){if(!n.name||typeof n.name!="string")throw new Error(`Invalid migration name in store "${e}": must be a non-empty string`);if(s.has(n.name))throw new Error(`Duplicate migration name "${n.name}" in store "${e}"`);s.add(n.name)}return{name:e,keyPath:o,autoIncrement:u,indexes:f,migrations:[...a].sort((n,c)=>n.name.localeCompare(c.name)),_schema:{},_keyType:{}}}return i(t,"createStore"),t}i(defineStore,"defineStore");

package/dist/readChain.d.ts

@@ -1,2 +0,0 @@
-import type { ReadChain, StoreDefinition } from './types.js';
-export declare function createReadChain<TStores extends readonly StoreDefinition[]>(db: IDBDatabase, storeNames: string[]): ReadChain<TStores, []>;

package/dist/readChain.js

@@ -1 +0,0 @@
-"use strict";var l=Object.defineProperty;var i=(s,u)=>l(s,"name",{value:u,configurable:!0});import{promisifyTransaction as p}from"./utils.js";function g(s){return s}i(g,"toReadChain");export function createReadChain(s,u){const r=[],c={get(n,t){return r.push({type:"get",storeName:n,key:t}),c},getAll(n,t){return r.push({type:"getAll",storeName:n,query:t?.query,count:t?.count}),c},getAllByIndex(n,t,o){return r.push({type:"getAllByIndex",storeName:n,indexName:t,query:o}),c},count(n,t){return r.push({type:"count",storeName:n,query:t}),c},async execute(){if(r.length===0)return[];const n=[...new Set(r.map(e=>e.storeName))];for(const e of n)if(!u.includes(e))throw new Error(`Store "${e}" is not in the transaction scope. Available stores: ${u.join(", ")}`);const t=s.transaction(u,"readonly"),o=[];for(const e of r){const a=t.objectStore(e.storeName);switch(e.type){case"get":o.push(a.get(e.key));break;case"getAll":o.push(a.getAll(e.query,e.count));break;case"getAllByIndex":o.push(a.index(e.indexName).getAll(e.query));break;case"count":o.push(a.count(e.query));break}}return await p(t),o.map(e=>e.result)}};return c}i(createReadChain,"createReadChain");

package/dist/writeChain.d.ts

@@ -1,2 +0,0 @@
-import type { WriteChain, StoreDefinition } from './types.js';
-export declare function createWriteChain<TStores extends readonly StoreDefinition[]>(db: IDBDatabase, storeNames: string[]): WriteChain<TStores>;

package/dist/writeChain.js

@@ -1 +0,0 @@
-"use strict";var u=Object.defineProperty;var i=(n,o)=>u(n,"name",{value:o,configurable:!0});import{promisifyTransaction as p}from"./utils.js";function h(n){return n}i(h,"toWriteChain");export function createWriteChain(n,o){const a=[],s={put(t,r,e){return a.push({type:"put",storeName:t,value:r,key:e}),s},add(t,r,e){return a.push({type:"add",storeName:t,value:r,key:e}),s},delete(t,r){return a.push({type:"delete",storeName:t,key:r}),s},clear(t){return a.push({type:"clear",storeName:t}),s},async execute(){if(a.length===0)return;const t=[...new Set(a.map(e=>e.storeName))];for(const e of t)if(!o.includes(e))throw new Error(`Store "${e}" is not in the transaction scope. Available stores: ${o.join(", ")}`);const r=n.transaction(o,"readwrite");for(const e of a){const c=r.objectStore(e.storeName);switch(e.type){case"put":c.put(e.value,e.key);break;case"add":c.add(e.value,e.key);break;case"delete":c.delete(e.key);break;case"clear":c.clear();break}}await p(r)}};return s}i(createWriteChain,"createWriteChain");