Merge pull request #10 from maifeeulasad/schema-versioning

schema versioning

Author: maifeeulasad

README.md

@@ -39,6 +39,7 @@ npm i idb-ts
 - ⚡ **Easy CRUD Operations** - Perform create, read, update, and delete seamlessly.
 - 🚀 **Fully Typed API** - Benefit from TypeScript’s powerful type system.
 - 🏎️ **Performance Optimized** - Minimal overhead with IndexedDB's native capabilities.
+- 🔄 **Schema Versioning** - Manage database schema evolution with automatic migration support.
 
 ---
 
@@ -172,6 +173,68 @@ const firstElectronic = await db.Product.findOneByIndex('category', 'Electronics
 
 ---
 
+## 🔄 Schema Versioning
+
+idb-ts supports schema versioning to manage database evolution over time. Version your entities and let the library handle automatic migration!
+
+### Basic Usage
+
+```typescript
+@DataClass({ version: 1 })
+class User {
+  @KeyPath() id!: string;
+  @Index() email!: string;
+  name!: string;
+}
+
+@DataClass({ version: 2 })
+class Post {
+  @KeyPath() id!: string;
+  @Index() authorId!: string;
+  title!: string;
+  content!: string;
+}
+
+@DataClass({ version: 3 })
+class Comment {
+  @KeyPath() id!: string;
+  @Index() postId!: string;
+  @Index() authorId!: string;
+  text!: string;
+}
+
+// Database version will be 3 (highest entity version)
+const db = await Database.build("blog", [User, Post, Comment]);
+
+console.log(db.getDatabaseVersion()); // 3
+console.log(db.getEntityVersions()); // Map with entity versions
+```
+
+### Key Features
+
+- **Automatic Version Calculation**: Database version = highest entity version
+- **Seamless Migration**: Only new/updated entities are processed during upgrades
+- **Backward Compatibility**: Entities without version default to version 1
+- **Index Evolution**: New indexes are automatically created during migration
+
+### Version Management
+
+```typescript
+// Check versions
+const dbVersion = db.getDatabaseVersion();
+const entityVersions = db.getEntityVersions();
+const userVersion = db.getEntityVersion('User');
+
+// Version upgrade flow:
+// v1.0: User(v1) → Database v1
+// v1.1: User(v1), Post(v2) → Database v2  
+// v1.2: User(v1), Post(v2), Comment(v3) → Database v3
+```
+
+📖 **[Complete Schema Versioning Guide](./SCHEMA_VERSIONING.md)** - Detailed documentation with examples and best practices.
+
+---
+
 ## 🔗 Useful Links
 - 📂 **GitHub**: [maifeeulasad/idb-ts](https://github.com/maifeeulasad/idb-ts)
 - 📦 **NPM**: [idb-ts](https://www.npmjs.com/package/idb-ts)

__tests__/schema-versioning.test.ts

@@ -0,0 +1,169 @@
+import { Database, KeyPath, DataClass, Index, EntityRepository } from '../index';
+
+// Test entities with different versions
+@DataClass({ version: 1 })
+class UserV1 {
+  @KeyPath()
+  id!: string;
+
+  @Index()
+  email!: string;
+
+  name!: string;
+
+  constructor(id: string, name: string, email: string) {
+    this.id = id;
+    this.name = name;
+    this.email = email;
+  }
+}
+
+@DataClass({ version: 2 })
+class PostV2 {
+  @KeyPath()
+  id!: string;
+
+  @Index()
+  authorId!: string;
+
+  title!: string;
+  content!: string;
+
+  constructor(id: string, authorId: string, title: string, content: string) {
+    this.id = id;
+    this.authorId = authorId;
+    this.title = title;
+    this.content = content;
+  }
+}
+
+@DataClass({ version: 4 })
+class CommentV4 {
+  @KeyPath()
+  id!: string;
+
+  @Index()
+  postId!: string;
+
+  @Index()
+  userId!: string;
+
+  text!: string;
+  timestamp!: Date;
+
+  constructor(id: string, postId: string, userId: string, text: string) {
+    this.id = id;
+    this.postId = postId;
+    this.userId = userId;
+    this.text = text;
+    this.timestamp = new Date();
+  }
+}
+
+// Test with default version (should be 1)
+@DataClass()
+class TagDefault {
+  @KeyPath()
+  id!: string;
+
+  name!: string;
+
+  constructor(id: string, name: string) {
+    this.id = id;
+    this.name = name;
+  }
+}
+
+describe('Schema Versioning', () => {
+  let db: any;
+
+  beforeAll(async () => {
+    // Clear any existing database
+    const deleteRequest = indexedDB.deleteDatabase('VersionTestDB');
+    await new Promise<void>((resolve) => {
+      deleteRequest.onsuccess = () => resolve();
+      deleteRequest.onerror = () => resolve(); // Continue even if deletion fails
+    });
+
+    db = await Database.build('VersionTestDB', [UserV1, PostV2, CommentV4, TagDefault]);
+  });
+
+  it('should calculate correct database version from highest entity version', () => {
+    expect(db.getDatabaseVersion()).toBe(4); // Highest version among entities
+  });
+
+  it('should track entity versions correctly', () => {
+    const versions = db.getEntityVersions();
+    expect(versions.get('UserV1')).toBe(1);
+    expect(versions.get('PostV2')).toBe(2);
+    expect(versions.get('CommentV4')).toBe(4);
+    expect(versions.get('TagDefault')).toBe(1); // Default version
+  });
+
+  it('should get individual entity version', () => {
+    expect(db.getEntityVersion('UserV1')).toBe(1);
+    expect(db.getEntityVersion('PostV2')).toBe(2);
+    expect(db.getEntityVersion('CommentV4')).toBe(4);
+    expect(db.getEntityVersion('TagDefault')).toBe(1);
+    expect(db.getEntityVersion('NonExistent')).toBeUndefined();
+  });
+
+  it('should create and manage entities with different versions', async () => {
+    // Test UserV1 (version 1)
+    const user = new UserV1('u1', 'Alice', 'alice@example.com');
+    await db.UserV1.create(user);
+    const retrievedUser = await db.UserV1.read('u1');
+    expect(retrievedUser).toEqual(user);
+
+    // Test PostV2 (version 2)
+    const post = new PostV2('p1', 'u1', 'Hello World', 'This is my first post');
+    await db.PostV2.create(post);
+    const retrievedPost = await db.PostV2.read('p1');
+    expect(retrievedPost).toEqual(post);
+
+    // Test CommentV4 (version 4)
+    const comment = new CommentV4('c1', 'p1', 'u1', 'Great post!');
+    await db.CommentV4.create(comment);
+    const retrievedComment = await db.CommentV4.read('c1');
+    expect(retrievedComment?.text).toBe('Great post!');
+
+    // Test TagDefault (default version 1)
+    const tag = new TagDefault('t1', 'typescript');
+    await db.TagDefault.create(tag);
+    const retrievedTag = await db.TagDefault.read('t1');
+    expect(retrievedTag).toEqual(tag);
+  });
+
+  it('should handle indexes correctly for different versions', async () => {
+    // Test finding by index in UserV1
+    const users = await db.UserV1.findByIndex('email', 'alice@example.com');
+    expect(users.length).toBe(1);
+    expect(users[0].name).toBe('Alice');
+
+    // Test finding by index in PostV2
+    const posts = await db.PostV2.findByIndex('authorId', 'u1');
+    expect(posts.length).toBe(1);
+    expect(posts[0].title).toBe('Hello World');
+
+    // Test finding by index in CommentV4
+    const comments = await db.CommentV4.findByIndex('postId', 'p1');
+    expect(comments.length).toBe(1);
+    expect(comments[0].text).toBe('Great post!');
+  });
+
+  it('should support query builder with versioned entities', async () => {
+    const posts = await db.PostV2.query()
+      .where('authorId').equals('u1')
+      .execute();
+    
+    expect(posts.length).toBe(1);
+    expect(posts[0].title).toBe('Hello World');
+
+    const comments = await db.CommentV4.query()
+      .where('userId').equals('u1')
+      .execute();
+    
+    expect(comments.length).toBe(1);
+    expect(comments[0].text).toBe('Great post!');
+  });
+});

index.ts

@@ -169,7 +169,11 @@ function Index(): PropertyDecorator {
   };
 }
 
-function DataClass(): ClassDecorator {
+interface DataClassOptions {
+  version?: number;
+}
+
+function DataClass(options: DataClassOptions = {}): ClassDecorator {
   return (target: Function) => {
     if (!Reflect.getMetadata("keypath", target)) {
       throw new Error(`No keypath field defined for the class ${target.name}.`);
@@ -178,7 +182,9 @@ function DataClass(): ClassDecorator {
     if (keyPathFields.length > 1) {
       throw new Error(`Only one keypath field can be defined for the class ${target.name}.`);
     }
+    const version = options.version || 1;
     Reflect.defineMetadata("dataclass", true, target);
+    Reflect.defineMetadata("version", version, target);
   };
 }
 
@@ -209,13 +215,21 @@ class Database {
   private classes: Function[];
   private db: IDBDatabase | null = null;
   private entityRepositories: Map<string, any> = new Map();
+  private dbVersion: number;
 
   private constructor(dbName: string, classes: Function[]) {
     this.dbName = dbName;
     if (!classes.every(cls => Reflect.getMetadata("dataclass", cls))) {
       throw new Error("All classes should be decorated with @DataClass.");
     }
     this.classes = classes;
+    this.dbVersion = this.calculateDatabaseVersion();
+  }
+
+  private calculateDatabaseVersion(): number {
+    // Calculate the database version based on the highest schema version
+    const versions = this.classes.map(cls => Reflect.getMetadata("version", cls) || 1);
+    return Math.max(...versions);
   }
 
   public static async build<T extends Record<string, EntityRepository<any>>>(
@@ -230,32 +244,56 @@ class Database {
 
   private async initDB(): Promise<void> {
     return new Promise((resolve, reject) => {
-      const request = indexedDB.open(this.dbName, 1);
+      const request = indexedDB.open(this.dbName, this.dbVersion);
 
-      request.onupgradeneeded = () => {
+      request.onupgradeneeded = (event) => {
         const db = request.result;
+        const oldVersion = event.oldVersion;
+        const newVersion = event.newVersion || this.dbVersion;
 
+        console.debug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
+
+        // Handle schema evolution based on versions
         this.classes.forEach((cls) => {
           const keyPathFields = Reflect.getMetadata("keypath", cls) || [];
           const indexFields = Reflect.getMetadata("indexes", cls) || [];
+          const classVersion = Reflect.getMetadata("version", cls) || 1;
 
           const storeName = cls.name.toLowerCase();
 
-          if (!db.objectStoreNames.contains(storeName)) {
-            const store = db.createObjectStore(storeName, { keyPath: keyPathFields[0] });
-
-            indexFields.forEach((indexField: string) => {
-              if (!store.indexNames.contains(indexField)) {
-                store.createIndex(indexField, indexField, { unique: false });
+          // Only create/update stores for classes whose version is greater than the old DB version
+          if (classVersion > oldVersion) {
+            if (!db.objectStoreNames.contains(storeName)) {
+              console.debug(`Creating object store: ${storeName} (version ${classVersion})`);
+              const store = db.createObjectStore(storeName, { keyPath: keyPathFields[0] });
+
+              indexFields.forEach((indexField: string) => {
+                if (!store.indexNames.contains(indexField)) {
+                  store.createIndex(indexField, indexField, { unique: false });
+                }
+              });
+            } else {
+              // Store exists, check if we need to update indexes
+              console.debug(`Updating object store: ${storeName} (version ${classVersion})`);
+              const transaction = request.transaction;
+              if (transaction) {
+                const store = transaction.objectStore(storeName);
+                
+                indexFields.forEach((indexField: string) => {
+                  if (!store.indexNames.contains(indexField)) {
+                    console.debug(`Adding index: ${indexField} to ${storeName}`);
+                    store.createIndex(indexField, indexField, { unique: false });
+                  }
+                });
               }
-            });
+            }
           }
         });
       };
 
       request.onsuccess = () => {
         this.db = request.result;
-        console.debug(`Database initialized with object stores for: ${this.classes.map(cls => cls.name).join(", ")}`);
+        console.debug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map(cls => `${cls.name}(v${Reflect.getMetadata("version", cls) || 1})`).join(", ")}`);
         resolve();
       };
 
@@ -502,7 +540,25 @@ class Database {
   getAvailableEntities(): string[] {
     return Array.from(this.entityRepositories.keys());
   }
+
+  getDatabaseVersion(): number {
+    return this.dbVersion;
+  }
+
+  getEntityVersions(): Map<string, number> {
+    const versions = new Map<string, number>();
+    this.classes.forEach(cls => {
+      const version = Reflect.getMetadata("version", cls) || 1;
+      versions.set(cls.name, version);
+    });
+    return versions;
+  }
+
+  getEntityVersion(entityName: string): number | undefined {
+    const cls = this.classes.find(c => c.name === entityName);
+    return cls ? (Reflect.getMetadata("version", cls) || 1) : undefined;
+  }
 }
 
 export { Database, KeyPath, DataClass, Index, EntityRepository };
-export type { DatabaseWithRepositories };
+export type { DatabaseWithRepositories, DataClassOptions };

tsconfig.json

@@ -15,7 +15,7 @@
       // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
       // "jsx": "preserve",                                /* Specify what JSX code is generated. */
       "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
-      // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+      "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
       // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h' */
       // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
       // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using `jsx: react-jsx*`.` */