@indexeddb-orm/idb-orm 0.0.1

package/src/services/EntityRegistry.ts

@@ -0,0 +1,109 @@
+import type { z } from 'zod';
+
+type ClassConstructor<T = unknown> = abstract new (..._args: never[]) => T;
+
+export type ColumnConfig = {
+  required?: boolean;
+  unique?: boolean;
+  indexed?: boolean;
+  default?: unknown | (() => unknown);
+};
+
+export type RelationConfig = {
+  type: 'one-to-one' | 'one-to-many' | 'many-to-many';
+  target: ClassConstructor | string;
+  foreignKey?: string;
+  joinTable?: string;
+  cascade?: boolean;
+  eager?: boolean;
+};
+
+export type DefineEntityOptions = {
+  tableName?: string;
+  schema?: z.ZodSchema<unknown>;
+  timestamps?: boolean;
+  columns?: Record<string, ColumnConfig>;
+  compoundIndexes?: { name?: string; unique?: boolean; columns: string[] }[];
+  relations?: Record<string, RelationConfig>;
+};
+
+type StoredEntityMeta = Required<Pick<DefineEntityOptions, 'tableName'>> &
+  Omit<DefineEntityOptions, 'tableName'>;
+
+const entityMeta = new Map<ClassConstructor, StoredEntityMeta>();
+
+const columnMeta = new Map<ClassConstructor, Record<string, ColumnConfig>>();
+const compoundIndexMeta =
+new Map<ClassConstructor, { name: string; unique: boolean; columns: string[] }[]>();
+const relationMeta = new Map<ClassConstructor, Record<string, RelationConfig>>();
+
+/**
+ * Define entity metadata without decorators.
+ *
+ * Registers table name, schema, columns, indexes and relations for a given class
+ * so the ORM can work without TypeScript decorators.
+ *
+ * @param EntityClass - The entity constructor/class
+ * @param options - Metadata describing table, schema, columns, indexes and relations
+ * @returns void
+ *
+ * @example
+ * defineEntity(UserEntity, {
+ *   tableName: 'users',
+ *   columns: {
+ *     name: { required: true, indexed: true },
+ *     email: { required: true, unique: true },
+ *   },
+ *   relations: {
+ *     posts: { type: 'one-to-many', target: PostEntity, foreignKey: 'authorId' }
+ *   }
+ * });
+ */
+export function defineEntity<T>(
+  EntityClass: ClassConstructor<T>,
+  options: DefineEntityOptions,
+): void {
+  const tableName = options.tableName || EntityClass.name.toLowerCase() + 's';
+  entityMeta.set(EntityClass, { tableName, ...options });
+
+  if (options.columns) {
+    columnMeta.set(EntityClass, options.columns);
+  }
+
+  if (options.compoundIndexes) {
+    const normalized = options.compoundIndexes.map(ci => ({
+      name: ci.name || ci.columns.join('_'),
+      unique: !!ci.unique,
+      columns: ci.columns,
+    }));
+    compoundIndexMeta.set(EntityClass, normalized);
+  }
+
+  if (options.relations) {
+    relationMeta.set(EntityClass, options.relations);
+  }
+}
+
+export function getDefinedEntityMeta
+(ctor: ClassConstructor): StoredEntityMeta | undefined {
+  return entityMeta.get(ctor);
+}
+
+export function getDefinedColumns
+(ctor: ClassConstructor): Record<string, ColumnConfig> | undefined {
+  return columnMeta.get(ctor);
+}
+
+export function getDefinedCompoundIndexes(
+  ctor: ClassConstructor,
+): { name: string; unique: boolean; columns: string[] }[] | undefined {
+  return compoundIndexMeta.get(ctor);
+}
+
+export function getDefinedRelations(
+  ctor: ClassConstructor,
+): Record<string, RelationConfig> | undefined {
+  return relationMeta.get(ctor);
+}
+
+

package/src/services/EntitySchema.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+
+import { getColumnMetadata } from '../metadata/Column';
+import { getEntityMetadata } from '../metadata/Entity';
+import { BaseEntity } from './BaseEntity';
+import { getDefinedColumns } from './EntityRegistry';
+
+export class EntitySchema<T extends BaseEntity = BaseEntity> {
+  private entityClass: new () => T;
+  private schema?: z.ZodSchema<unknown>;
+
+  constructor(entityClass: new () => T, schema?: z.ZodSchema<unknown>) {
+    this.entityClass = entityClass;
+    this.schema = schema;
+  }
+
+  /**
+   * Get the table name for this entity
+   * @returns The table name (either from metadata or generated from class name)
+   *
+   * @example
+   * const schema = new EntitySchema(User);
+   * const table = schema.getTableName(); // 'users'
+   */
+  getTableName(): string {
+    const metadata = getEntityMetadata(this.entityClass);
+
+    return metadata?.tableName || this.entityClass.name.toLowerCase() + 's';
+  }
+
+  /**
+   * Get the Zod schema for this entity
+   * @returns The Zod schema or undefined if not defined
+   *
+   * @example
+   * const schema = new EntitySchema(User, userZodSchema);
+   * const zod = schema.getSchema();
+   */
+  getSchema(): z.ZodSchema<unknown> | undefined {
+    return this.schema
+    || (this.entityClass as { schema?: z.ZodSchema<unknown> }).schema;
+  }
+
+  /**
+   * Get column metadata for this entity
+   * @returns Object containing column metadata
+   *
+   * @example
+   * const cols = new EntitySchema(User).getColumns();
+   * // cols.name.required === true
+   */
+  getColumns(): Record<string, unknown> {
+    const defined = getDefinedColumns(this.entityClass as unknown as never);
+    if (defined) {
+      return defined as Record<string, unknown>;
+    }
+
+    return getColumnMetadata(this.entityClass);
+  }
+
+  /**
+   * Validate data against entity schema
+   * @param data - Data to validate
+   * @returns Validation result with status and errors
+   *
+   * @example
+   * const { isValid, errors } = new EntitySchema(User, userSchema)
+   *   .validate({ name: 'Alice' });
+   */
+  validate(data: Partial<T>): { isValid: boolean; errors: string[] } {
+    const schema = this.getSchema();
+
+    if (!schema) {
+      const columns = this.getColumns() as Record<string, { required?: boolean }>;
+      const missing: string[] = [];
+
+      for (const [propertyKey, options] of Object.entries(columns)) {
+        if (!options || !options.required) {
+          continue;
+        }
+
+        const value = (data as Record<string, unknown>)[propertyKey];
+
+        if (value === undefined || value === null) {
+          missing.push(propertyKey);
+        }
+      }
+
+      if (missing.length > 0) {
+        return {
+          isValid: false,
+          errors: missing.map(key => `${key}: is required`),
+        };
+      }
+
+      return { isValid: true, errors: [] };
+    }
+
+    try {
+      schema.parse(data);
+
+      return { isValid: true, errors: [] };
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        const errors = error.issues.map(err => `${err.path.join('.')}: ${err.message}`);
+
+        return { isValid: false, errors };
+      }
+
+      return { isValid: false, errors: ['Unknown validation error'] };
+    }
+  }
+
+  /**
+   * Create a new instance of the entity
+   * @param data - Optional data to initialize the entity with
+   * @returns New entity instance
+   *
+   * @example
+   * const user = new EntitySchema(User).create({ name: 'Bob' });
+   */
+  create(data?: Partial<T>): T {
+    const instance = new this.entityClass();
+    const columns = this.getColumns() as Record<string, { default?: unknown }>;
+
+    for (const [propertyKey, options] of Object.entries(columns)) {
+      const hasValueInData = data
+      && (data as Record<string, unknown>)[propertyKey] !== undefined;
+      const hasValueInInstance =
+      (instance as Record<string, unknown>)[propertyKey] !== undefined;
+
+      if (
+        !hasValueInData &&
+        !hasValueInInstance &&
+        options &&
+        Object.prototype.hasOwnProperty.call(options, 'default')
+      ) {
+        const defaultOption = options.default;
+
+        const value = typeof defaultOption === 'function'
+          ? (defaultOption as () => unknown)()
+          : defaultOption;
+
+        (instance as Record<string, unknown>)[propertyKey] = value;
+      }
+    }
+
+    if (data) {
+      Object.assign(instance, data);
+    }
+
+    return instance;
+  }
+}

package/src/services/MigrationManager.ts

@@ -0,0 +1,276 @@
+import type Dexie from 'dexie';
+
+import type {
+ EntityConstructor,Migration,
+} from '../types';
+import { createServiceLogger } from '../utils/logger';
+import { SchemaBuilder } from './SchemaBuilder';
+
+const logger = createServiceLogger('MigrationManager');
+
+export class MigrationManager {
+  private dbName: string;
+  private currentVersion: number;
+  private db: {
+    migrationMetadata: {
+      get: (_key: string) => Promise<{
+        key: string;
+        value: string | number;
+        updatedAt: number
+      } | undefined>;
+      put: (_data: {
+        key: string;
+        value: string | number;
+        updatedAt: number
+      }) => Promise<unknown>;
+    };
+  } | null = null;
+
+  constructor(dbName: string, currentVersion: number) {
+    this.dbName = dbName;
+    this.currentVersion = currentVersion;
+  }
+
+  setDatabase(db: {
+    migrationMetadata: {
+      get: (_key: string) => Promise<{
+        key: string;
+        value: string | number;
+        updatedAt: number
+      } | undefined>;
+      put: (_data: {
+        key: string;
+        value: string | number;
+        updatedAt: number
+      }) => Promise<unknown>;
+    };
+  }): void {
+    this.db = db;
+  }
+
+  private async getLastMigrationVersion(): Promise<number> {
+    if (!this.db) {
+      logger.error('Database not set in MigrationManager');
+
+      throw new Error('MigrationManager database not set');
+    }
+
+    const key = `dexie_orm_migration_${this.dbName}_version`;
+    const metadata = await this.db.migrationMetadata.get(key);
+
+    return metadata?.value as number || 0;
+  }
+
+  private async setLastMigrationVersion(version: number): Promise<void> {
+    if (!this.db) {
+      logger.error('Database not set in MigrationManager');
+
+      throw new Error('MigrationManager database not set');
+    }
+
+    const key = `dexie_orm_migration_${this.dbName}_version`;
+
+    await this.db.migrationMetadata.put({
+      key,
+      value: version,
+      updatedAt: Date.now(),
+    });
+  }
+
+  private async getSchemaHash(): Promise<string | null> {
+    if (!this.db) {
+      logger.error('Database not set in MigrationManager');
+
+      throw new Error('MigrationManager database not set');
+    }
+
+    const key = `dexie_orm_schema_${this.dbName}_hash`;
+    const metadata = await this.db.migrationMetadata.get(key);
+
+    return metadata?.value as string || null;
+  }
+
+  private async setSchemaHash(hash: string): Promise<void> {
+    if (!this.db) {
+      logger.error('Database not set in MigrationManager');
+
+      throw new Error('MigrationManager database not set');
+    }
+
+    const key = `dexie_orm_schema_${this.dbName}_hash`;
+
+    await this.db.migrationMetadata.put({
+      key,
+      value: hash,
+      updatedAt: Date.now(),
+    });
+  }
+
+  /**
+   * Run database migrations
+   * @param migrations - Array of migration objects
+   * @param db - Database instance for running migrations
+   * @returns Promise that resolves when all migrations are complete
+   */
+  async runMigrations(
+    migrations: Migration[],
+    db: (Dexie & { clearAllData: () => Promise<void> }),
+  ): Promise<void> {
+    logger.info('Running migrations...');
+
+    const lastMigrationVersion = await this.getLastMigrationVersion();
+
+    const migrationsToRun = migrations.filter(migration =>
+      migration.version > lastMigrationVersion
+      && migration.version <= this.currentVersion,
+    );
+
+    if (migrationsToRun.length === 0) {
+      logger.info('No migrations to run');
+
+      return;
+    }
+
+    migrationsToRun.sort((a, b) => a.version - b.version);
+
+    for (const migration of migrationsToRun) {
+      logger.info(`Running migration: ${migration.name} (v${migration.version})`);
+
+      try {
+        await migration.up(db);
+        await this.setLastMigrationVersion(migration.version);
+
+        logger.info(`Migration ${migration.name} completed`);
+      } catch (error) {
+        logger.error(`Migration ${migration.name} failed:`, error);
+
+        throw error;
+      }
+    }
+
+    logger.info('All migrations completed');
+  }
+
+  autoRunMigrations(
+    migrations: Migration[],
+    db: (Dexie & { clearAllData: () => Promise<void> }),
+  ): void {
+    setTimeout(async () => {
+      try {
+        await this.runMigrations(migrations, db);
+      } catch (error) {
+        logger.error('Error during auto-migration:', error);
+      }
+    }, 0);
+  }
+
+  /**
+   * Perform selective reset for changed tables only
+   * @param entities - Array of entity constructors
+   * @param db - Database instance for clearing tables
+   * @returns Promise that resolves when selective reset is complete
+   */
+  async performSelectiveReset(
+    entities: EntityConstructor[],
+    db: Dexie,
+  ): Promise<void> {
+    logger.info('Performing selective reset for changed tables...');
+
+    const currentTableSchemas = SchemaBuilder.buildTableSchemas(entities);
+    const storedTableSchemas = SchemaBuilder.getStoredTableSchemas(this.dbName);
+
+    const changes = SchemaBuilder
+    .compareSchemas(storedTableSchemas, currentTableSchemas);
+
+    if (changes.length === 0) {
+      logger.info('No schema changes detected for selective reset');
+
+      return;
+    }
+
+    for (const change of changes) {
+      if (change.changeType === 'removed' || change.changeType === 'modified') {
+        logger.info(`Clearing ${change.changeType} table: ${change.tableName}`);
+
+        try {
+          await db.table(change.tableName).clear();
+        } catch (error) {
+          logger.error(`Could not clear table ${change.tableName}:`, error);
+        }
+      }
+    }
+
+    SchemaBuilder.storeTableSchemas(this.dbName, currentTableSchemas);
+
+    logger.info('Selective reset complete');
+  }
+
+  autoSelectiveReset(
+    entities: EntityConstructor[],
+    db: Dexie,
+  ): void {
+    setTimeout(async () => {
+      try {
+        await this.performSelectiveReset(entities, db);
+      } catch (error) {
+        logger.error('Error during auto-selective reset:', error);
+      }
+    }, 0);
+  }
+
+  /**
+   * Reset entire database by clearing all data
+   * @param db - Database instance for clearing data
+   * @returns Promise that resolves when database is reset
+   */
+  async resetDatabase(db: { clearAllData: () => Promise<void> }): Promise<void> {
+    logger.info('Resetting database due to schema changes...');
+
+    await db.clearAllData();
+
+    await this.setLastMigrationVersion(0);
+    await this.setSchemaHash('');
+
+    logger.info('Database reset complete');
+  }
+
+  /**
+   * Automatically reset database asynchronously
+   * @param db - Database instance for clearing data
+   */
+  autoResetDatabase(db: { clearAllData: () => Promise<void> }): void {
+    setTimeout(async () => {
+      try {
+        await this.resetDatabase(db);
+      } catch (error) {
+        logger.error('Error during auto-reset:', error);
+      }
+    }, 0);
+  }
+
+  /**
+   * Check if schema has changed and reset database if needed
+   * @param entities - Array of entity constructors
+   * @param db - Database instance for clearing data
+   * @returns Promise resolving to true if schema changed, false otherwise
+   */
+  async checkSchemaChanges(
+    entities: EntityConstructor[],
+    db: { clearAllData: () => Promise<void> },
+  ): Promise<boolean> {
+    const currentSchema = SchemaBuilder.buildSchema(entities);
+    const schemaHash = SchemaBuilder.generateSchemaHash(currentSchema);
+    const storedHash = await this.getSchemaHash();
+
+    if (storedHash && storedHash !== schemaHash) {
+      logger.info('Schema changes detected!');
+
+      await this.resetDatabase(db);
+      await this.setSchemaHash(schemaHash);
+
+      return true;
+    }
+
+    return false;
+  }
+}