@indexeddb-orm/idb-orm 0.0.1

package/src/Database.ts

@@ -0,0 +1,405 @@
+import Dexie, { type Table } from 'dexie';
+
+import { getEntityMetadata } from './metadata/Entity';
+import { AggregationService } from './services/AggregationService';
+import { BaseEntity } from './services/BaseEntity';
+import { CloudSyncService } from './services/CloudSyncService';
+import { MigrationManager } from './services/MigrationManager';
+import { RelationLoader } from './services/RelationLoader';
+import { SchemaBuilder } from './services/SchemaBuilder';
+import type {
+  AggregationOptions,
+  AggregationResult,
+  CloudSyncConfig,
+  DatabaseConfig,
+  EntityConstructor,
+  Migration,
+} from './types';
+import { logger } from './utils/logger';
+
+export class Database extends Dexie {
+  private entitySchemas = new Map<string, EntityConstructor>();
+  private migrationManager: MigrationManager;
+  private relationLoader: RelationLoader;
+  private aggregationService: AggregationService;
+  private cloudSyncService: CloudSyncService;
+
+  migrationMetadata!: Table<{
+    key: string;
+    value: string | number;
+    updatedAt: number;
+  }>;
+
+  constructor(config: DatabaseConfig) {
+    super(config.name);
+
+    this.migrationManager = new MigrationManager(config.name, config.version);
+    this.relationLoader = new RelationLoader(this);
+    this.aggregationService = new AggregationService(this);
+    this.cloudSyncService = new CloudSyncService(this);
+
+    const currentSchema = SchemaBuilder.buildSchema(config.entities);
+
+    const schemaHash = SchemaBuilder.generateSchemaHash(currentSchema);
+    const storedHash = localStorage.getItem(`${config.name}_schema_hash`);
+
+    let version = config.version;
+
+    if (storedHash && storedHash !== schemaHash) {
+      logger.info('Schema changed, incrementing version...');
+
+      version = config.version + 1;
+      localStorage.setItem(`${config.name}_schema_hash`, schemaHash);
+
+      if (config.migrations && config.migrations.length > 0) {
+        logger.info('Running migrations due to schema change...');
+
+        this.migrationManager.autoRunMigrations(config.migrations, this);
+      } else {
+        if (config.onSchemaChangeStrategy === 'all') {
+          logger.info('Auto-resetting entire database due to schema change...');
+
+          this.migrationManager.autoResetDatabase(this);
+        } else if (config.onSchemaChangeStrategy === 'selective') {
+          logger.info('Auto-resetting only changed tables...');
+
+          this.migrationManager.autoSelectiveReset(config.entities, this);
+        }
+      }
+    }
+
+    this.version(version).stores(currentSchema);
+    this.migrationManager.setDatabase(this);
+
+    config.entities.forEach(entity => {
+      const metadata = getEntityMetadata(entity);
+      const tableName = metadata?.tableName || entity.name.toLowerCase() + 's';
+      this.entitySchemas.set(tableName, entity);
+    });
+
+    if (config.cloudSync) {
+      this.cloudSyncService.initializeCloudSync(config.cloudSync);
+    }
+  }
+
+  /**
+   * Get repository for entity (TypeORM style)
+   *
+   * @example
+   * const users = db.getRepository(User);
+   * const id = await users.add({ name: 'Ann' } as User);
+   */
+  getRepository<
+    T extends BaseEntity,
+    TKey extends Extract<
+      NonNullable<T['id']>,
+      string | number
+    > = Extract<NonNullable<T['id']>, string | number>
+  >(entityClass: EntityConstructor<T>): Table<T, TKey> {
+    const fromRegistry = Array.from(this.entitySchemas.entries()).find(
+      ([, ctor]) => ctor === entityClass,
+    )?.[0];
+
+    const metadata = getEntityMetadata(entityClass);
+    let tableName = fromRegistry
+      || metadata?.tableName
+      || entityClass.name.toLowerCase() + 's';
+
+    if (!fromRegistry && !metadata?.tableName) {
+      const n = entityClass.name;
+      if (/Entity$/i.test(n)) {
+        const base = n.replace(/Entity$/i, '');
+        tableName = base.toLowerCase() + 's';
+      }
+    }
+
+    return this.table(tableName) as Table<T, TKey>;
+  }
+
+  /**
+   * Perform aggregation on entity data
+   *
+   * @example
+   * const result = await db.aggregate({
+   *   entityClass: Post,
+   *   options: { where: { category: 'tech' } },
+   * });
+   */
+  async aggregate<T extends BaseEntity>(params: {
+    entityClass: EntityConstructor<T>;
+    options: AggregationOptions<T>;
+  }): Promise<AggregationResult> {
+    return this.aggregationService.aggregate(params.entityClass, params.options);
+  }
+
+  /**
+   * Create database with entity registration
+   *
+   * @example
+   * const db = Database.createDatabase({
+   *   name: 'app-db',
+   *   version: 1,
+   *   entities: [User, Post],
+   * });
+   */
+  static createDatabase(params: {
+    name: string;
+    version: number;
+    entities: EntityConstructor[];
+    config?: Partial<DatabaseConfig>;
+  }): Database {
+    const db = new Database({
+      name: params.name,
+      version: params.version,
+      entities: params.entities,
+      onSchemaChangeStrategy: params.config?.onSchemaChangeStrategy,
+      migrations: params.config?.migrations,
+      cloudSync: params.config?.cloudSync,
+    });
+
+    return db as Database;
+  }
+
+  /**
+   * Clear all data from database
+   *
+   * @example
+   * await db.clearAllData();
+   */
+  async clearAllData(): Promise<void> {
+    const tableNames = this.tables.map(table => table.name);
+
+    await Promise.all(tableNames.map(name => this.table(name).clear()));
+  }
+
+  /**
+   * Reset database when schema changes
+   *
+   * @example
+   * await db.resetDatabase();
+   */
+  async resetDatabase(): Promise<void> {
+    await this.migrationManager.resetDatabase(this);
+  }
+
+  /**
+   * Check if schema has changed and reset if needed
+   *
+   * @example
+   * const changed = await db.checkSchemaChanges();
+   */
+  async checkSchemaChanges(): Promise<boolean> {
+    return this.migrationManager.checkSchemaChanges(
+      Array.from(this.entitySchemas.values()),
+      this,
+    );
+  }
+
+  /**
+   * Manually perform selective reset for changed tables only
+   *
+   * @example
+   * await db.performSelectiveReset();
+   */
+  async performSelectiveReset(): Promise<void> {
+    await this.migrationManager.performSelectiveReset(
+      Array.from(this.entitySchemas.values()),
+      this,
+    );
+  }
+
+  /**
+   * Run migrations for schema changes
+   *
+   * @example
+   * await db.runMigrations(migrations);
+   */
+  async runMigrations(migrations: Migration[]): Promise<void> {
+    await this.migrationManager.runMigrations(migrations, this);
+  }
+
+  /**
+   * Get typed table for entity
+   *
+   * @example
+   * const posts = db.getTypedTable(Post);
+   */
+  getTypedTable<
+    T extends BaseEntity,
+    TKey extends Extract<
+      NonNullable<T['id']>,
+      string | number
+    > = Extract<NonNullable<T['id']>, string | number>
+  >(entityClass: EntityConstructor<T>): Table<T, TKey> {
+    const metadata = getEntityMetadata(entityClass);
+    const tableName =
+      metadata?.tableName || entityClass.name.toLowerCase() + 's';
+
+    return this.table(tableName) as Table<T, TKey>;
+  }
+
+  /**
+   * Get table with proper typing for specific entity
+   *
+   * @example
+   * const users = db.getTableForEntity(User);
+   */
+  getTableForEntity<
+    T extends BaseEntity,
+    TKey extends Extract<
+      NonNullable<T['id']>,
+      string | number
+    > = Extract<NonNullable<T['id']>, string | number>
+  >(entityClass: EntityConstructor<T>): Table<T, TKey> {
+    return this.getTypedTable<T, TKey>(entityClass);
+  }
+
+  /**
+   * Get all entities
+   *
+   * @example
+   * const all = db.getEntities();
+   */
+  getEntities(): EntityConstructor[] {
+    return Array.from(this.entitySchemas.values());
+  }
+
+  /**
+   * Get entity by table name
+   *
+   * @example
+   * const UserClass = db.getEntity('users');
+   */
+  getEntity(tableName: string): EntityConstructor | undefined {
+    return this.entitySchemas.get(tableName);
+  }
+
+  /**
+   * Load relations for an entity
+   *
+   * @example
+   * const userWithRelations = await db.loadRelations({
+   *   entity: user,
+   *   entityClass: User,
+   *   relationNames: ['posts'],
+   * });
+   */
+  async loadRelations<T extends BaseEntity>(params: {
+    entity: T;
+    entityClass: EntityConstructor<T>;
+    relationNames?: string[];
+  }): Promise<T> {
+    return this.relationLoader.loadRelations(
+      params.entity,
+      params.entityClass,
+      params.relationNames,
+    );
+  }
+
+  /**
+   * Load a specific relation by name
+   *
+   * @example
+   * const posts = await db.loadRelationByName({
+   *   entity: { id: userId },
+   *   entityClass: User,
+   *   relationName: 'posts',
+   * });
+   */
+  async loadRelationByName<
+    T extends BaseEntity,
+    K extends keyof T
+  >(params: {
+    entity: T | { id: string | number };
+    entityClass: EntityConstructor<T>;
+    relationName: K;
+  }): Promise<T[K]> {
+    return this.relationLoader.loadRelationByName<T, K>(
+      params.entity as T,
+      params.entityClass,
+      params.relationName,
+    );
+  }
+
+  /**
+   * Save entity with relations
+   *
+   * @example
+   * const saved = await db.saveWithRelations({
+   *   entity: user,
+   *   entityClass: User,
+   * });
+   */
+  async saveWithRelations<T extends BaseEntity>(params: {
+    entity: T;
+    entityClass: EntityConstructor<T>;
+  }): Promise<T> {
+    return this.relationLoader.saveWithRelations(params.entity, params.entityClass);
+  }
+
+  /**
+   * Delete entity with cascade handling for relations
+   *
+   * @example
+   * await db.deleteWithRelations({
+   *   entity: user,
+   *   entityClass: User,
+   * });
+   */
+  async deleteWithRelations<T extends BaseEntity>(params: {
+    entity: T;
+    entityClass: EntityConstructor<T>;
+  }): Promise<void> {
+    return this.relationLoader
+    .deleteWithRelations(params.entity, params.entityClass);
+  }
+
+  /**
+   * Manual sync with cloud
+   */
+  async sync(): Promise<void> {
+    return this.cloudSyncService.sync();
+  }
+
+  /**
+   * Get sync status
+   */
+  getSyncStatus(): { enabled: boolean; lastSync?: Date; isOnline?: boolean } {
+    return this.cloudSyncService.getSyncStatus();
+  }
+
+  /**
+   * Enable cloud sync (if not already enabled)
+   */
+  async enableCloudSync(config: CloudSyncConfig): Promise<void> {
+    return this.cloudSyncService.enableCloudSync(config);
+  }
+
+  /**
+   * Disable cloud sync
+   */
+  disableCloudSync(): void {
+    this.cloudSyncService.disableCloudSync();
+  }
+
+  /**
+   * Check if cloud sync is enabled
+   */
+  isCloudSyncEnabled(): boolean {
+    return this.cloudSyncService.isCloudSyncEnabled();
+  }
+
+  /**
+   * Get cloud sync configuration
+   */
+  getCloudSyncConfig(): CloudSyncConfig | undefined {
+    return this.cloudSyncService.getCloudSyncConfig();
+  }
+
+  /**
+   * Force sync specific tables
+   */
+  async syncTables(tableNames: string[]): Promise<void> {
+    return this.cloudSyncService.syncTables(tableNames);
+  }
+}

package/src/errors/ValidationError.ts

@@ -0,0 +1,9 @@
+export class ValidationError extends Error {
+  public errors: string[];
+
+  constructor(message: string, errors: string[] = []) {
+    super(message);
+    this.name = 'ValidationError';
+    this.errors = errors;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { Database } from './Database';
+export { ValidationError } from './errors/ValidationError';
+export {
+ Entity, ManyToMany,
+OneToMany, OneToOne, Relation,
+} from './metadata';
+export { BaseEntity } from './services/BaseEntity';
+export { newEntity } from './services/EntityFactory';
+export { defineEntity } from './services/EntityRegistry';
+export { EntitySchema } from './services/EntitySchema';
+export type {
+ CloudSyncConfig, DatabaseConfig,EntityConstructor, EntityInstance,
+} from './types';

package/src/metadata/Column.ts

@@ -0,0 +1,74 @@
+type ClassConstructor<T = unknown> = abstract new (..._args: never[]) => T;
+import {
+  getDefinedColumns,
+  getDefinedCompoundIndexes,
+} from '../services/EntityRegistry';
+import type {
+ ColumnOptions, CompoundIndexOptions,
+} from '../types';
+
+const COLUMNS_METADATA_KEY = Symbol('columns');
+const COMPOUND_INDEXES_METADATA_KEY = Symbol('compoundIndexes');
+
+export interface ColumnMetadata extends ColumnOptions {
+  propertyKey: string;
+}
+
+export function getColumnMetadata(
+  target: object | ClassConstructor,
+): Record<string, ColumnMetadata> {
+  const ctor: ClassConstructor =
+    (typeof target === 'function')
+      ? (target as ClassConstructor)
+      : (target as { constructor: ClassConstructor }).constructor;
+  const defined = getDefinedColumns(ctor as ClassConstructor);
+
+  if (defined) {
+    const out: Record<string, ColumnMetadata> = {};
+
+    for (const [key, cfg] of Object.entries(defined)) {
+      out[key] = { propertyKey: key, ...cfg } as ColumnMetadata;
+    }
+
+    const hasPrimary = Object.values(out).some(c => c.primaryKey);
+    if (!hasPrimary) {
+      if (!out.id) {
+        out.id = { propertyKey: 'id', primaryKey: true, autoIncrement: true } as ColumnMetadata;
+      } else {
+        out.id.primaryKey = true;
+        if (out.id.autoIncrement === undefined) {
+          out.id.autoIncrement = true;
+        }
+      }
+    }
+
+    return out;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reflectGet = (Reflect as any)?.getMetadata?.bind(Reflect);
+
+  return reflectGet ? (reflectGet(COLUMNS_METADATA_KEY, ctor) || {}) : {};
+}
+
+export function getCompoundIndexMetadata(
+  target: object | ClassConstructor,
+): CompoundIndexOptions[] {
+  const ctor: ClassConstructor =
+    (typeof target === 'function')
+      ? (target as ClassConstructor)
+      : (target as { constructor: ClassConstructor }).constructor;
+  const defined = getDefinedCompoundIndexes(ctor as ClassConstructor);
+
+  if (defined) {
+    return defined
+    .map(ci => ({ name: ci.name, unique: ci.unique, columns: ci.columns }));
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reflectGet = (Reflect as any)?.getMetadata?.bind(Reflect);
+
+  return reflectGet ? (reflectGet(COMPOUND_INDEXES_METADATA_KEY, ctor) || []) : [];
+}
+
+

package/src/metadata/Entity.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+
+type ClassConstructor<T = unknown> = abstract new (..._args: never[]) => T;
+import { getDefinedEntityMeta } from '../services/EntityRegistry';
+import type { EntityOptions } from '../types';
+
+const ENTITY_METADATA_KEY = Symbol('entity');
+
+export interface EntityMetadata {
+  tableName: string;
+  schema?: z.ZodSchema<unknown>;
+  timestamps?: boolean;
+}
+
+export function Entity(_options: EntityOptions = {}):
+(_target: ClassConstructor) => void {
+  return function(_target: ClassConstructor): void {};
+}
+
+export function getEntityMetadata(target: ClassConstructor):
+EntityMetadata | undefined {
+  const defined = getDefinedEntityMeta(target);
+
+  if (defined) {
+    return {
+      tableName: defined.tableName,
+      schema: defined.schema,
+      timestamps: defined.timestamps,
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reflectGet = (Reflect as any)?.getMetadata?.bind(Reflect);
+
+  if (reflectGet) {
+    return reflectGet(ENTITY_METADATA_KEY, target);
+  }
+
+  return undefined;
+}
+
+

package/src/metadata/Relation.ts

@@ -0,0 +1,121 @@
+type ClassConstructor<T = unknown> = abstract new (..._args: never[]) => T;
+type LegacyArgs = [Record<'constructor', ClassConstructor>, string];
+type FieldContext = {
+  kind: 'field';
+  name: string;
+  addInitializer(
+    _init: (_this: { constructor: ClassConstructor }) => void
+  ): void;
+};
+type StandardArgs = [unknown, FieldContext];
+function isLegacyArgs(args: unknown[]): args is LegacyArgs {
+  return Array.isArray(args) && typeof (args as unknown[])[1] === 'string';
+}
+function isFieldContext(args: unknown[]): args is StandardArgs {
+  const ctx = (args as unknown[])[1] as FieldContext | undefined;
+
+  return !!ctx && typeof ctx === 'object' && ctx.kind === 'field' && typeof ctx.name === 'string';
+}
+import { getDefinedRelations } from '../services/EntityRegistry';
+import type {
+ EntityConstructor,RelationMetadata, RelationOptions,
+} from '../types';
+
+const RELATIONS_METADATA_KEY = Symbol('relations');
+
+export function Relation(options: RelationOptions): (..._args: unknown[]) => void {
+  return function (...args: unknown[]): void {
+    const apply = (ctor: ClassConstructor, propertyKey: string) => {
+      const existingRelations = getRelationMetadata(ctor) || {};
+      const relationMetadata: RelationMetadata = { propertyKey, ...options };
+
+      existingRelations[propertyKey] = relationMetadata;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const reflectDefine = (Reflect as any)?.defineMetadata?.bind(Reflect);
+
+      if (reflectDefine) {
+        reflectDefine(RELATIONS_METADATA_KEY, existingRelations, ctor);
+      }
+    };
+
+    if (isLegacyArgs(args)) {
+      const [target, propertyKey] = args;
+
+      apply(target.constructor, propertyKey);
+
+      return;
+    }
+
+    if (isFieldContext(args)) {
+      const [, context] = args;
+      const propertyKey = context.name;
+
+      context.addInitializer(function (_this: { constructor: ClassConstructor }) {
+        apply(_this.constructor, propertyKey);
+      });
+    }
+  };
+}
+
+export function getRelationMetadata(
+  entityClass: ClassConstructor,
+): Record<string, RelationMetadata> | undefined {
+  const defined = getDefinedRelations(entityClass);
+
+  if (defined) {
+    const out: Record<string, RelationMetadata> = {};
+    for (const [key, rel] of Object.entries(defined)) {
+      out[key] = { propertyKey: key, ...rel } as RelationMetadata;
+    }
+
+    return out;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reflectGet = (Reflect as any)?.getMetadata?.bind(Reflect);
+
+  return reflectGet
+  ? (reflectGet(RELATIONS_METADATA_KEY, entityClass) || {})
+  : {};
+}
+
+export function OneToOne(params: {
+  target: EntityConstructor | string;
+  foreignKey?: string;
+  options?: Partial<RelationOptions>;
+}): (..._args: unknown[]) => void {
+  return Relation({
+    type: 'one-to-one',
+    target: params.target,
+    foreignKey: params.foreignKey,
+    ...params.options,
+  });
+}
+
+export function OneToMany(params: {
+  target: EntityConstructor | string;
+  foreignKey: string;
+  options?: Partial<RelationOptions>;
+}): (..._args: unknown[]) => void {
+  return Relation({
+    type: 'one-to-many',
+    target: params.target,
+    foreignKey: params.foreignKey,
+    ...params.options,
+  });
+}
+
+export function ManyToMany(params: {
+  target: EntityConstructor | string;
+  joinTable: string;
+  options?: Partial<RelationOptions>;
+}): (..._args: unknown[]) => void {
+  return Relation({
+    type: 'many-to-many',
+    target: params.target,
+    joinTable: params.joinTable,
+    ...params.options,
+  });
+}
+
+

package/src/metadata/index.ts

@@ -0,0 +1,5 @@
+export * from './Column';
+export * from './Entity';
+export * from './Relation';
+
+