Merge pull request #7 from maifeeulasad/indexing-field

Indexing support

Author: maifeeulasad

README.md

@@ -48,16 +48,23 @@ npm i idb-ts
 Use decorators to define your data models with automatic schema management.
 
 ```typescript
+import { Database, DataClass, KeyPath, Index } from "idb-ts";
+
 @DataClass()
 class User {
   @KeyPath()
   name: string;
+  
+  @Index()
+  email: string;
+  
   age: number;
   cell?: string;
   address: string;
 
-  constructor(name: string, age: number, address: string, cell?: string) {
+  constructor(name: string, email: string, age: number, address: string, cell?: string) {
     this.name = name;
+    this.email = email;
     this.age = age;
     this.address = address;
     this.cell = cell;
@@ -68,7 +75,10 @@ class User {
 class Location {
   @KeyPath()
   id: string;
+  
+  @Index()
   city: string;
+  
   country: string;
 
   constructor(id: string, city: string, country: string) {
@@ -85,11 +95,15 @@ Perform database operations in an intuitive way:
 ```typescript
 const db = await Database.build("idb-crud", [User, Location]);
 
-const alice = new User("Alice", 25, "123 Main St");
+const alice = new User("Alice", "alice@example.com", 25, "123 Main St");
+const bob = new User("Bob", "bob@example.com", 30, "456 Oak Ave");
 const nyc = new Location("1", "New York", "USA");
+const sf = new Location("2", "San Francisco", "USA");
 
 await db.create(User, alice);
+await db.create(User, bob);
 await db.create(Location, nyc);
+await db.create(Location, sf);
 
 const readAlice = await db.read(User, "Alice");
 console.log("👤 Read user:", readAlice);
@@ -101,6 +115,12 @@ await db.update(User, alice);
 const users = await db.list(User);
 console.log("📋 All users:", users);
 
+const userByEmail = await db.findOneByIndex(User, 'email', 'bob@example.com');
+console.log("🔎 User by email:", userByEmail);
+
+const locationsInSF = await db.findByIndex(Location, 'city', 'San Francisco');
+console.log("🌆 Locations in San Francisco:", locationsInSF);
+
 await db.delete(User, "Alice");
 console.log("❌ User Alice deleted.");
 
@@ -111,6 +131,46 @@ const locations = await db.list(Location);
 console.log("🌍 All locations:", locations);
 ```
 
+### 🔍 Indexing Support
+Create indexes on fields for fast querying:
+
+```typescript
+@DataClass()
+class Product {
+  @KeyPath()
+  id: string;
+  
+  @Index()
+  category: string;
+  
+  @Index()
+  price: number;
+  
+  name: string;
+  description: string;
+
+  constructor(id: string, category: string, price: number, name: string, description: string) {
+    this.id = id;
+    this.category = category;
+    this.price = price;
+    this.name = name;
+    this.description = description;
+  }
+}
+
+const db = await Database.build("products-db", [Product]);
+
+const electronics = await db.findByIndex(Product, 'category', 'Electronics');
+
+const expensiveItems = await db.findByIndex(Product, 'price', 999.99);
+
+const firstElectronic = await db.findOneByIndex(Product, 'category', 'Electronics');
+```
+
+#### Index Methods:
+- `findByIndex<T>(cls, indexName, value): Promise<T[]>` - Find all records matching the index value
+- `findOneByIndex<T>(cls, indexName, value): Promise<T | undefined>` - Find the first record matching the index value
+
 ---
 
 ## 🔗 Useful Links

__tests__/annotation.test.ts

@@ -1,4 +1,4 @@
-import { Database, KeyPath, DataClass } from '../index';
+import { Database, KeyPath, DataClass, Index } from '../index';
 
 describe('IndexedDB annotation', () => {
   it('should throw error if class is missing @KeyPath', async () => {
@@ -54,4 +54,20 @@ describe('IndexedDB annotation', () => {
     }).rejects.toThrow(/All classes should be decorated/);
   });
 
+  it('should work with @Index decorator', async () => {
+    @DataClass()
+    class IndexedUser {
+      @KeyPath()
+      id!: string;
+
+      @Index()
+      email!: string;
+
+      name!: string;
+    }
+
+    const db = await Database.build('IndexedDB', [IndexedUser]);
+    expect(db).toBeDefined();
+  });
+
 });

__tests__/database.test.ts

@@ -1,17 +1,21 @@
-import { Database, KeyPath, DataClass } from '../index';
+import { Database, KeyPath, DataClass, Index } from '../index';
 
 @DataClass()
 class User {
   @KeyPath()
   id!: string;
 
+  @Index()
+  email!: string;
+
   name!: string;
   age!: number;
 
-  constructor(id: string, name: string, age: number) {
+  constructor(id: string, name: string, age: number, email?: string) {
     this.id = id;
     this.name = name;
     this.age = age;
+    this.email = email || `${name.toLowerCase()}@example.com`;
   }
 }
 
@@ -61,4 +65,22 @@ describe('IndexedDB CRUD', () => {
     expect(deleted).toBeUndefined();
   });
 
+  it('should find users by email index', async () => {
+    const user = new User('u5', 'Diana', 35, 'diana@example.com');
+    await db.create(User, user);
+
+    const found = await db.findByIndex(User, 'email', 'diana@example.com');
+    expect(found.length).toBe(1);
+    expect(found[0].name).toBe('Diana');
+  });
+
+  it('should find one user by email index', async () => {
+    const user = new User('u6', 'Eve', 29, 'eve@example.com');
+    await db.create(User, user);
+
+    const found = await db.findOneByIndex(User, 'email', 'eve@example.com');
+    expect(found).toBeDefined();
+    expect(found!.name).toBe('Eve');
+  });
+
 });

__tests__/indexing.test.ts

@@ -0,0 +1,94 @@
+import { Database, KeyPath, DataClass, Index } from '../index';
+
+@DataClass()
+class User {
+  @KeyPath()
+  id!: string;
+
+  @Index()
+  email!: string;
+
+  @Index()
+  age!: number;
+
+  name!: string;
+
+  constructor(id: string, email: string, age: number, name: string) {
+    this.id = id;
+    this.email = email;
+    this.age = age;
+    this.name = name;
+  }
+}
+
+describe('IndexedDB Indexing', () => {
+  let db: Database;
+
+  beforeAll(async () => {
+    db = await Database.build('IndexingTestDB', [User]);
+  });
+
+  beforeEach(async () => {
+    // Clear existing data
+    const users = await db.list(User);
+    for (const user of users) {
+      await db.delete(User, user.id);
+    }
+
+    // Add test data
+    await db.create(User, new User('u1', 'alice@example.com', 30, 'Alice'));
+    await db.create(User, new User('u2', 'bob@example.com', 25, 'Bob'));
+    await db.create(User, new User('u3', 'charlie@example.com', 30, 'Charlie'));
+    await db.create(User, new User('u4', 'alice@work.com', 28, 'Alice Smith'));
+  });
+
+  it('should find users by email index', async () => {
+    const users = await db.findByIndex(User, 'email', 'alice@example.com');
+    expect(users.length).toBe(1);
+    expect(users[0].name).toBe('Alice');
+    expect(users[0].email).toBe('alice@example.com');
+  });
+
+  it('should find multiple users by age index', async () => {
+    const users = await db.findByIndex(User, 'age', 30);
+    expect(users.length).toBe(2);
+    const names = users.map(u => u.name).sort();
+    expect(names).toEqual(['Alice', 'Charlie']);
+  });
+
+  it('should find single user by email index', async () => {
+    const user = await db.findOneByIndex(User, 'email', 'bob@example.com');
+    expect(user).toBeDefined();
+    expect(user!.name).toBe('Bob');
+    expect(user!.age).toBe(25);
+  });
+
+  it('should return undefined when no user found by index', async () => {
+    const user = await db.findOneByIndex(User, 'email', 'nonexistent@example.com');
+    expect(user).toBeUndefined();
+  });
+
+  it('should return empty array when no users found by index', async () => {
+    const users = await db.findByIndex(User, 'age', 99);
+    expect(users).toEqual([]);
+  });
+
+  it('should throw error when querying non-existent index', async () => {
+    await expect(db.findByIndex(User, 'nonexistent', 'value')).rejects.toThrow(
+      "Index 'nonexistent' does not exist on User"
+    );
+  });
+
+  it('should throw error when querying non-existent index with findOneByIndex', async () => {
+    await expect(db.findOneByIndex(User, 'nonexistent', 'value')).rejects.toThrow(
+      "Index 'nonexistent' does not exist on User"
+    );
+  });
+
+  it('should work with non-indexed fields not being queryable by index', async () => {
+    // name field is not indexed, so this should throw an error
+    await expect(db.findByIndex(User, 'name', 'Alice')).rejects.toThrow(
+      "Index 'name' does not exist on User"
+    );
+  });
+});

index.ts

@@ -8,6 +8,14 @@ function KeyPath(): PropertyDecorator {
   };
 }
 
+function Index(): PropertyDecorator {
+  return (target: Object, propertyKey: string | symbol) => {
+    const constructor = target.constructor as Function;
+    const existing = Reflect.getMetadata("indexes", constructor) || [];
+    Reflect.defineMetadata("indexes", [...existing, propertyKey as string], constructor);
+  };
+}
+
 function DataClass(): ClassDecorator {
   return (target: Function) => {
     if (!Reflect.getMetadata("keypath", target)) {
@@ -49,11 +57,18 @@ class Database {
 
         this.classes.forEach((cls) => {
           const keyPathFields = Reflect.getMetadata("keypath", cls) || [];
+          const indexFields = Reflect.getMetadata("indexes", cls) || [];
 
           const storeName = cls.name.toLowerCase() + "s";
 
           if (!db.objectStoreNames.contains(storeName)) {
-            db.createObjectStore(storeName, { keyPath: keyPathFields[0] });
+            const store = db.createObjectStore(storeName, { keyPath: keyPathFields[0] });
+            
+            indexFields.forEach((indexField: string) => {
+              if (!store.indexNames.contains(indexField)) {
+                store.createIndex(indexField, indexField, { unique: false });
+              }
+            });
           }
         });
       };
@@ -183,6 +198,54 @@ class Database {
       };
     });
   }
+
+  async findByIndex<T>(cls: { new(...args: any[]): T }, indexName: string, value: any): Promise<T[]> {
+    return new Promise((resolve, reject) => {
+      const store = this.getObjectStore(cls.name, "readonly");
+      
+      if (!store.indexNames.contains(indexName)) {
+        reject(new Error(`Index '${indexName}' does not exist on ${cls.name}`));
+        return;
+      }
+
+      const index = store.index(indexName);
+      const request = index.getAll(value);
+
+      request.onsuccess = () => {
+        console.debug(`Items found by index ${indexName} with value ${value}:`, request.result);
+        resolve(request.result as T[]);
+      };
+
+      request.onerror = () => {
+        console.error(`Error finding items by index ${indexName}:`, request.error);
+        reject(request.error);
+      };
+    });
+  }
+
+  async findOneByIndex<T>(cls: { new(...args: any[]): T }, indexName: string, value: any): Promise<T | undefined> {
+    return new Promise((resolve, reject) => {
+      const store = this.getObjectStore(cls.name, "readonly");
+      
+      if (!store.indexNames.contains(indexName)) {
+        reject(new Error(`Index '${indexName}' does not exist on ${cls.name}`));
+        return;
+      }
+
+      const index = store.index(indexName);
+      const request = index.get(value);
+
+      request.onsuccess = () => {
+        console.debug(`Item found by index ${indexName} with value ${value}:`, request.result);
+        resolve(request.result as T | undefined);
+      };
+
+      request.onerror = () => {
+        console.error(`Error finding item by index ${indexName}:`, request.error);
+        reject(request.error);
+      };
+    });
+  }
 }
 
-export { Database, KeyPath, DataClass };
+export { Database, KeyPath, DataClass, Index };