@indexeddb-orm/idb-orm 0.0.1

package/src/services/AggregationService.ts

@@ -0,0 +1,348 @@
+import type { Database } from '../Database';
+import { getRelationMetadata } from '../metadata/Relation';
+import type {
+  AggregationOptions,
+  AggregationResult,
+  EntityConstructor,
+  RelationMetadata,
+} from '../types';
+import { BaseEntity } from './BaseEntity';
+
+export class AggregationService {
+  private db: Database;
+
+  constructor(database: Database) {
+    this.db = database;
+  }
+
+  /**
+   * Perform aggregation operations on entity data
+   * @param entityClass - The entity class to aggregate
+   * @param options - Aggregation options including filters, sorting, grouping, etc.
+   * @returns Promise resolving to aggregation results
+   *
+   * @example
+   * const result = await aggregationService.aggregate(Post, {
+   *   where: { category: 'tech' },
+   *   sort: { field: 'views', direction: 'desc' },
+   *   limit: 10,
+   *   count: true,
+   *   sum: ['views'],
+   * });
+   */
+  async aggregate<T extends BaseEntity>(
+    entityClass: EntityConstructor<T>,
+    options: AggregationOptions<T>,
+  ): Promise<AggregationResult> {
+    const table = this.db.getRepository(entityClass);
+    let collection = table.toCollection();
+
+    if (options.where) {
+      const whereConditions = options.where;
+      collection = collection.filter((record: T) => {
+        return Object.entries(whereConditions).every(([key, value]) => {
+          return record[key as keyof T] === value;
+        });
+      });
+    }
+
+    let records = await collection.toArray();
+
+    if (options.include && options.include.length > 0) {
+      const relations = getRelationMetadata(entityClass);
+      if (relations) {
+        for (const record of records) {
+          for (const relationName of options.include) {
+            if (relations[relationName]) {
+              (record as Record<string, unknown>)[relationName] =
+              await this.loadRelation(
+                record as Record<string, unknown>,
+                relations[relationName],
+              );
+            }
+          }
+        }
+      }
+    }
+
+    if (options.sort) {
+      const sortField = options.sort.field;
+      const sortDirection = options.sort.direction;
+
+      records.sort((a: T, b: T) => {
+        const aVal = a[sortField];
+        const bVal = b[sortField];
+        const direction = sortDirection === 'asc' ? 1 : -1;
+
+        if (aVal < bVal)  {
+          return -1 * direction;
+        }
+
+        if (aVal > bVal) {
+          return 1 * direction;
+        }
+
+        return 0;
+      });
+    }
+
+    if (options.limit) {
+      records = records.slice(0, options.limit);
+    }
+
+    const result: AggregationResult = {};
+
+    if (options.count) {
+      result.count = records.length;
+    }
+
+    if (options.sum || options.avg || options.min || options.max) {
+      const numericFields = [
+        ...(options.sum || []),
+        ...(options.avg || []),
+        ...(options.min || []),
+        ...(options.max || []),
+      ];
+
+      for (const field of numericFields) {
+        const values = records
+          .map((r: T) => r[field])
+          .filter((v: unknown) => typeof v === 'number' && !isNaN(v)) as number[];
+
+        if (values.length === 0) {
+          continue;
+        }
+
+        if (options.sum?.includes(field)) {
+          result.sum = result.sum || {};
+
+          result.sum[field as string] = values.reduce((sum, val) => sum + val, 0);
+        }
+
+        if (options.avg?.includes(field)) {
+          result.avg = result.avg || {};
+
+          result.avg[field as string] = values
+          .reduce((sum, val) => sum + val, 0) / values.length;
+        }
+
+        if (options.min?.includes(field)) {
+          result.min = result.min || {};
+
+          result.min[field as string] = Math.min(...values);
+        }
+
+        if (options.max?.includes(field)) {
+          result.max = result.max || {};
+
+          result.max[field as string] = Math.max(...values);
+        }
+      }
+    }
+
+    if (options.groupBy) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const groups = new Map<any, any[]>();
+
+      for (const record of records) {
+        const key = record[options.groupBy];
+
+        if (!groups.has(key)) {
+          groups.set(key, []);
+        }
+
+        const group = groups.get(key);
+
+        if (group) {
+          group.push(record);
+        }
+      }
+
+      result.groups = Array.from(groups.entries()).map(([key, groupRecords]) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const groupResult: any = { key, count: groupRecords.length };
+
+        if (options.sum || options.avg || options.min || options.max) {
+          const numericFields = [
+            ...(options.sum || []),
+            ...(options.avg || []),
+            ...(options.min || []),
+            ...(options.max || []),
+          ];
+
+          for (const field of numericFields) {
+            const values = groupRecords
+              .map(r => r[field])
+              .filter(v => typeof v === 'number' && !isNaN(v)) as number[];
+
+            if (values.length === 0)  {
+              continue;
+            }
+
+            if (options.sum?.includes(field)) {
+              groupResult.sum = groupResult.sum || {};
+
+              groupResult.sum[field as string] = values
+              .reduce((sum, val) => sum + val, 0);
+            }
+
+            if (options.avg?.includes(field)) {
+              groupResult.avg = groupResult.avg || {};
+
+              groupResult.avg[field as string] = values.reduce(
+                (sum, val) => sum + val,
+                0,
+              ) / values.length;
+            }
+
+            if (options.min?.includes(field)) {
+              groupResult.min = groupResult.min || {};
+
+              groupResult.min[field as string] = Math.min(...values);
+            }
+
+            if (options.max?.includes(field)) {
+              groupResult.max = groupResult.max || {};
+
+              groupResult.max[field as string] = Math.max(...values);
+            }
+          }
+        }
+
+        return groupResult;
+      });
+    }
+
+    if (
+      !options.count &&
+      !options.sum &&
+      !options.avg &&
+      !options.min &&
+      !options.max &&
+      !options.groupBy
+    ) {
+      result.data = records;
+    }
+
+    return result;
+  }
+
+  /**
+   * Load a specific relation based on metadata.
+   * @param entity - The source entity to load relation for
+   * @param relationMeta - Relation metadata (type, target, keys)
+   * @returns Promise resolving to the loaded relation data
+   *
+   * @example
+   * const related = await (aggregationService as any).loadRelation(record, {
+   *   type: 'one-to-many', target: Post, foreignKey: 'authorId',
+   * });
+   */
+  private async loadRelation(
+    entity: Record<string, unknown>,
+    relationMeta: RelationMetadata,
+  ): Promise<unknown> {
+    const targetTable = this.db
+    .getRepository(relationMeta.target as EntityConstructor);
+
+    switch (relationMeta.type) {
+      case 'one-to-one':
+        return await this.loadOneToOne(entity, targetTable, relationMeta);
+
+      case 'one-to-many':
+        return await this.loadOneToMany(entity, targetTable, relationMeta);
+
+      case 'many-to-many':
+        return await this.loadManyToMany(entity, targetTable, relationMeta);
+
+      default:
+        throw new Error(`Unsupported relation type: ${relationMeta.type}`);
+    }
+  }
+
+  private async loadOneToOne(
+    entity: Record<string, unknown>,
+    _targetTable: unknown,
+    relationMeta: RelationMetadata,
+  ): Promise<unknown> {
+    const targetTableInstance = this.db.getRepository(
+      relationMeta.target as EntityConstructor,
+    );
+
+    if (relationMeta.foreignKey) {
+      return await (targetTableInstance as {
+        where: (_key: string) => {
+          equals: (_value: unknown) => {
+            first: () => Promise<unknown>;
+          };
+        };
+      })
+        .where(relationMeta.foreignKey)
+        .equals(entity.id)
+        .first();
+    } else {
+      const foreignKeyValue = relationMeta.foreignKey
+      ? entity[relationMeta.foreignKey] : undefined;
+      if (!foreignKeyValue) return null;
+
+      return await (targetTableInstance as {
+        get: (_id: unknown) => Promise<unknown>;
+      }).get(foreignKeyValue);
+    }
+  }
+
+  private async loadOneToMany(
+    entity: Record<string, unknown>,
+    _targetTable: unknown,
+    relationMeta: RelationMetadata,
+  ): Promise<unknown[]> {
+    const targetTableInstance = this.db.getRepository(
+      relationMeta.target as EntityConstructor,
+    );
+
+    return await (targetTableInstance as {
+      where: (_key: string) => {
+        equals: (_value: unknown) => {
+          toArray: () => Promise<unknown[]>;
+        };
+      };
+    })
+      .where(relationMeta.foreignKey as string)
+      .equals(entity.id)
+      .toArray();
+  }
+
+  private async loadManyToMany(
+    entity: Record<string, unknown>,
+    _targetTable: unknown,
+    relationMeta: RelationMetadata,
+  ): Promise<unknown[]> {
+    const joinTable = this.db.table(relationMeta.joinTable as string);
+    const joinRecords = await joinTable
+      .where('sourceId')
+      .equals(entity.id as string | number)
+      .toArray();
+    const targetIds = joinRecords.map(
+      (record: Record<string, unknown>) => record.targetId,
+    ) as (string | number)[];
+
+    if (targetIds.length === 0)  {
+      return [];
+    }
+
+    const targetTableInstance = this.db.getRepository(
+      relationMeta.target as EntityConstructor,
+    );
+
+    return await (targetTableInstance as {
+      where: (_key: string) => {
+        anyOf: (_values: unknown[]) => {
+          toArray: () => Promise<unknown[]>;
+        };
+      };
+    })
+      .where('id')
+      .anyOf(targetIds)
+      .toArray();
+  }
+}

package/src/services/BaseEntity.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+import { ValidationError } from '../errors/ValidationError';
+import type { ValidationResult } from '../types';
+
+export abstract class BaseEntity<TKey extends string | number = number | string> {
+  id?: TKey;
+
+  constructor(data?: Partial<BaseEntity<TKey>>) {
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+
+  /**
+   * Validate entity data against its schema
+   * @returns ValidationResult containing validation status and errors
+   *
+   * @example
+   * const result = user.validate();
+   * if (!result.isValid) console.error(result.errors);
+   */
+  validate(): ValidationResult {
+    const constructor = this.constructor as typeof BaseEntity
+    & { schema?: z.ZodSchema<unknown> };
+
+    if (!constructor.schema) {
+      return { isValid: true, errors: [] };
+    }
+
+    try {
+      constructor.schema.parse(this);
+
+      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'] };
+    }
+  }
+
+  /**
+   * Validate entity data and throw error if invalid
+   * @throws ValidationError if validation fails
+   *
+   * @example
+   * user.validateOrThrow(); // throws ValidationError on invalid data
+   */
+  validateOrThrow(): void {
+    const result = this.validate();
+
+    if (!result.isValid) {
+      throw new ValidationError('Entity validation failed', result.errors);
+    }
+  }
+
+  /**
+   * Initialize entity with data and validate
+   * @param data - Partial data to initialize entity with
+   * @returns The initialized entity instance
+   * @throws ValidationError if validation fails
+   *
+   * @example
+   * const user = new User().init({ name: 'Alice' });
+   */
+  init(data: Partial<this>): this {
+    Object.assign(this, data);
+
+    this.validateOrThrow();
+
+    return this;
+  }
+}

package/src/services/CloudSyncService.ts

@@ -0,0 +1,248 @@
+import type { Database } from '../Database';
+import type { CloudSyncConfig } from '../types';
+import { createServiceLogger } from '../utils/logger';
+
+const logger = createServiceLogger('CloudSyncService');
+
+export class CloudSyncService {
+  private db: Database;
+  private cloudSyncConfig?: CloudSyncConfig;
+  private cloudSyncEnabled = false;
+  private syncIntervalId?: number;
+
+  declare cloud: {
+    sync: () => Promise<void>;
+    lastSync?: number;
+    isOnline?: boolean;
+  };
+
+  constructor(database: Database) {
+    this.db = database;
+  }
+
+  /**
+   * Initialize cloud synchronization with configuration
+   * @param config - Cloud sync configuration
+   * @returns Promise that resolves when initialization is complete
+   *
+   * @example
+   * await cloudService.initializeCloudSync({
+   *   databaseUrl: 'https://example.cloud',
+   *   enableOfflineSupport: true,
+   *   syncInterval: 30000,
+   * });
+   */
+  async initializeCloudSync(config: CloudSyncConfig): Promise<void> {
+    this.cloudSyncConfig = config;
+
+      if (!this.cloudSyncConfig) {
+        logger.error('Cloud sync config not provided');
+
+        return;
+      }
+
+      try {
+        const cloudApi =
+        (this.db as unknown as { cloud?: { configure: (_config: unknown) => void } })
+        .cloud;
+
+        if (!cloudApi) {
+          logger.error('Dexie cloud addon not detected. Initialize Dexie with dexie-cloud-addon: new Dexie(name, { addons: [dexieCloud] })');
+
+          return;
+        }
+
+        logger.info('Initializing cloud sync...');
+
+        cloudApi.configure({
+          databaseUrl: this.cloudSyncConfig.databaseUrl,
+          enableOfflineSupport: this.cloudSyncConfig.enableOfflineSupport ?? true,
+        });
+
+        this.cloudSyncEnabled = true;
+
+        logger.info('Cloud sync initialized successfully');
+
+        if (this.cloudSyncConfig.syncInterval
+          && this.cloudSyncConfig.syncInterval > 0) {
+          this.startPeriodicSync();
+        }
+
+      } catch (error) {
+        logger.error('Failed to initialize cloud sync:', error);
+      }
+  }
+
+  private startPeriodicSync(): void {
+    if (!this.cloudSyncConfig?.syncInterval) return;
+
+    this.syncIntervalId = window.setInterval(async () => {
+      try {
+        await this.sync();
+        } catch (error) {
+          logger.error('Periodic sync failed:', error);
+        }
+    }, this.cloudSyncConfig.syncInterval);
+
+    logger.info(
+      `Started periodic sync every ${this.cloudSyncConfig.syncInterval}ms`,
+    );
+  }
+
+  /**
+   * Stop periodic synchronization
+   *
+   * @example
+   * cloudService.stopPeriodicSync();
+   */
+  stopPeriodicSync(): void {
+    if (this.syncIntervalId) {
+      window.clearInterval(this.syncIntervalId);
+
+        this.syncIntervalId = undefined;
+
+        logger.info('Stopped periodic sync');
+    }
+  }
+
+  /**
+   * Perform manual synchronization
+   * @returns Promise that resolves when sync is complete
+   * @throws Error if cloud sync is not enabled
+   *
+   * @example
+   * await cloudService.sync();
+   */
+  async sync(): Promise<void> {
+    if (!this.cloudSyncEnabled) {
+      throw new Error('Cloud sync is not enabled. Make sure cloudSync config is provided.');
+    }
+
+    try {
+      logger.info('Starting manual sync...');
+
+      await (this.db as unknown as { cloud: { sync: () => Promise<void> } })
+      .cloud.sync();
+
+      logger.info('Sync completed successfully');
+      } catch (error) {
+        logger.error('Sync failed:', error);
+
+        throw error;
+      }
+  }
+
+  /**
+   * Get current synchronization status
+   * @returns Object containing sync status information
+   *
+   * @example
+   * const { enabled, lastSync, isOnline } = cloudService.getSyncStatus();
+   */
+  getSyncStatus(): { enabled: boolean; lastSync?: Date; isOnline?: boolean } {
+    if (!this.cloudSyncEnabled) {
+      return { enabled: false };
+    }
+
+    const cloudDb = this.db as unknown as {
+      cloud: {
+        lastSync?: number;
+        isOnline?: boolean;
+      };
+    };
+
+    return {
+      enabled: true,
+      lastSync: cloudDb.cloud.lastSync
+      ? new Date(cloudDb.cloud.lastSync)
+       : undefined,
+      isOnline: cloudDb.cloud.isOnline,
+    };
+  }
+
+  /**
+   * Enable cloud synchronization
+   * @param config - Cloud sync configuration
+   * @returns Promise that resolves when cloud sync is enabled
+   *
+   * @example
+   * await cloudService.enableCloudSync({ databaseUrl: 'https://example.cloud' });
+   */
+  async enableCloudSync(config: CloudSyncConfig): Promise<void> {
+      if (this.cloudSyncEnabled) {
+        logger.warn('Cloud sync is already enabled');
+
+        return;
+      }
+
+    await this.initializeCloudSync(config);
+  }
+
+  /**
+   * Disable cloud synchronization
+   *
+   * @example
+   * cloudService.disableCloudSync();
+   */
+  disableCloudSync(): void {
+    this.stopPeriodicSync();
+    this.cloudSyncEnabled = false;
+      this.cloudSyncConfig = undefined;
+
+      logger.info('Cloud sync disabled');
+  }
+
+  /**
+   * Check if cloud sync is currently enabled
+   * @returns True if cloud sync is enabled, false otherwise
+   *
+   * @example
+   * if (cloudService.isCloudSyncEnabled()) {
+   *   // ...
+   * }
+   */
+  isCloudSyncEnabled(): boolean {
+    return this.cloudSyncEnabled;
+  }
+
+  /**
+   * Get current cloud sync configuration
+   * @returns Cloud sync configuration or undefined if not set
+   *
+   * @example
+   * const cfg = cloudService.getCloudSyncConfig();
+   */
+  getCloudSyncConfig(): CloudSyncConfig | undefined {
+    return this.cloudSyncConfig;
+  }
+
+  /**
+   * Synchronize specific tables
+   * @param tableNames - Array of table names to sync
+   * @returns Promise that resolves when sync is complete
+   * @throws Error if cloud sync is not enabled
+   *
+   * @example
+   * await cloudService.syncTables(['users', 'posts']);
+   */
+  async syncTables(tableNames: string[]): Promise<void> {
+    if (!this.cloudSyncEnabled) {
+      throw new Error('Cloud sync is not enabled');
+    }
+
+    try {
+      logger.info(`Syncing tables: ${tableNames.join(', ')}`);
+
+      for (const tableName of tableNames) {
+        const table = this.db.table(tableName);
+
+        await table.toCollection().modify(() => {});
+      }
+
+      logger.info('Table sync completed');
+      } catch (error) {
+        logger.error('Table sync failed:', error);
+        throw error;
+      }
+  }
+}

package/src/services/EntityFactory.ts

@@ -0,0 +1,35 @@
+import type { BaseEntity } from './BaseEntity';
+
+/**
+ * Create a new entity instance and validate it in a single call.
+ *
+ * This helper instantiates the provided entity class, assigns the given
+ * partial data, and immediately validates it using the entity's
+ * `init` method (which calls `validateOrThrow` under the hood).
+ *
+ * - Preferred construction style matches the project convention:
+ *   empty constructor followed by property assignment and validation.
+ * - If the entity defines a Zod schema, invalid data will cause a
+ *   ValidationError to be thrown.
+ *
+ * @typeParam T - Concrete entity type extending BaseEntity
+ * @param EntityClass - Entity constructor (must have a zero-arg constructor)
+ * @param data - Partial entity data to assign before validation
+ * @returns A fully initialized and validated entity instance
+ * @throws {import('../errors/ValidationError').ValidationError}
+ * If validation fails according to the entity schema
+ *
+ * @example
+ * const user = newEntity(User, { name: 'Alice' });
+ * // user is validated; throws if required fields are missing or invalid
+ */
+export function newEntity<T extends BaseEntity>(
+  EntityClass: new () => T,
+  data: Partial<T>,
+): T {
+  const instance = new EntityClass();
+
+  return instance.init(data);
+}
+
+