@indexeddb-orm/idb-orm 0.0.1

package/dist/services/AggregationService.js

@@ -0,0 +1,229 @@
+import { getRelationMetadata } from '../metadata/Relation';
+export class AggregationService {
+    db;
+    constructor(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(entityClass, options) {
+        const table = this.db.getRepository(entityClass);
+        let collection = table.toCollection();
+        if (options.where) {
+            const whereConditions = options.where;
+            collection = collection.filter((record) => {
+                return Object.entries(whereConditions).every(([key, value]) => {
+                    return record[key] === 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[relationName] =
+                                await this.loadRelation(record, relations[relationName]);
+                        }
+                    }
+                }
+            }
+        }
+        if (options.sort) {
+            const sortField = options.sort.field;
+            const sortDirection = options.sort.direction;
+            records.sort((a, b) => {
+                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 = {};
+        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) => r[field])
+                    .filter((v) => typeof v === 'number' && !isNaN(v));
+                if (values.length === 0) {
+                    continue;
+                }
+                if (options.sum?.includes(field)) {
+                    result.sum = result.sum || {};
+                    result.sum[field] = values.reduce((sum, val) => sum + val, 0);
+                }
+                if (options.avg?.includes(field)) {
+                    result.avg = result.avg || {};
+                    result.avg[field] = values
+                        .reduce((sum, val) => sum + val, 0) / values.length;
+                }
+                if (options.min?.includes(field)) {
+                    result.min = result.min || {};
+                    result.min[field] = Math.min(...values);
+                }
+                if (options.max?.includes(field)) {
+                    result.max = result.max || {};
+                    result.max[field] = Math.max(...values);
+                }
+            }
+        }
+        if (options.groupBy) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const groups = new Map();
+            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 = { 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));
+                        if (values.length === 0) {
+                            continue;
+                        }
+                        if (options.sum?.includes(field)) {
+                            groupResult.sum = groupResult.sum || {};
+                            groupResult.sum[field] = values
+                                .reduce((sum, val) => sum + val, 0);
+                        }
+                        if (options.avg?.includes(field)) {
+                            groupResult.avg = groupResult.avg || {};
+                            groupResult.avg[field] = values.reduce((sum, val) => sum + val, 0) / values.length;
+                        }
+                        if (options.min?.includes(field)) {
+                            groupResult.min = groupResult.min || {};
+                            groupResult.min[field] = Math.min(...values);
+                        }
+                        if (options.max?.includes(field)) {
+                            groupResult.max = groupResult.max || {};
+                            groupResult.max[field] = 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',
+     * });
+     */
+    async loadRelation(entity, relationMeta) {
+        const targetTable = this.db
+            .getRepository(relationMeta.target);
+        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}`);
+        }
+    }
+    async loadOneToOne(entity, _targetTable, relationMeta) {
+        const targetTableInstance = this.db.getRepository(relationMeta.target);
+        if (relationMeta.foreignKey) {
+            return await targetTableInstance
+                .where(relationMeta.foreignKey)
+                .equals(entity.id)
+                .first();
+        }
+        else {
+            const foreignKeyValue = relationMeta.foreignKey
+                ? entity[relationMeta.foreignKey] : undefined;
+            if (!foreignKeyValue)
+                return null;
+            return await targetTableInstance.get(foreignKeyValue);
+        }
+    }
+    async loadOneToMany(entity, _targetTable, relationMeta) {
+        const targetTableInstance = this.db.getRepository(relationMeta.target);
+        return await targetTableInstance
+            .where(relationMeta.foreignKey)
+            .equals(entity.id)
+            .toArray();
+    }
+    async loadManyToMany(entity, _targetTable, relationMeta) {
+        const joinTable = this.db.table(relationMeta.joinTable);
+        const joinRecords = await joinTable
+            .where('sourceId')
+            .equals(entity.id)
+            .toArray();
+        const targetIds = joinRecords.map((record) => record.targetId);
+        if (targetIds.length === 0) {
+            return [];
+        }
+        const targetTableInstance = this.db.getRepository(relationMeta.target);
+        return await targetTableInstance
+            .where('id')
+            .anyOf(targetIds)
+            .toArray();
+    }
+}

package/dist/services/BaseEntity.d.ts

@@ -0,0 +1,32 @@
+import type { ValidationResult } from '../types';
+export declare abstract class BaseEntity<TKey extends string | number = number | string> {
+    id?: TKey;
+    constructor(data?: Partial<BaseEntity<TKey>>);
+    /**
+     * 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;
+    /**
+     * Validate entity data and throw error if invalid
+     * @throws ValidationError if validation fails
+     *
+     * @example
+     * user.validateOrThrow(); // throws ValidationError on invalid data
+     */
+    validateOrThrow(): void;
+    /**
+     * 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;
+}

package/dist/services/BaseEntity.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { ValidationError } from '../errors/ValidationError';
+export class BaseEntity {
+    id;
+    constructor(data) {
+        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() {
+        const constructor = this.constructor;
+        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() {
+        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) {
+        Object.assign(this, data);
+        this.validateOrThrow();
+        return this;
+    }
+}

package/dist/services/CloudSyncService.d.ts

@@ -0,0 +1,100 @@
+import type { Database } from '../Database';
+import type { CloudSyncConfig } from '../types';
+export declare class CloudSyncService {
+    private db;
+    private cloudSyncConfig?;
+    private cloudSyncEnabled;
+    private syncIntervalId?;
+    cloud: {
+        sync: () => Promise<void>;
+        lastSync?: number;
+        isOnline?: boolean;
+    };
+    constructor(database: 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,
+     * });
+     */
+    initializeCloudSync(config: CloudSyncConfig): Promise<void>;
+    private startPeriodicSync;
+    /**
+     * Stop periodic synchronization
+     *
+     * @example
+     * cloudService.stopPeriodicSync();
+     */
+    stopPeriodicSync(): void;
+    /**
+     * Perform manual synchronization
+     * @returns Promise that resolves when sync is complete
+     * @throws Error if cloud sync is not enabled
+     *
+     * @example
+     * await cloudService.sync();
+     */
+    sync(): Promise<void>;
+    /**
+     * Get current synchronization status
+     * @returns Object containing sync status information
+     *
+     * @example
+     * const { enabled, lastSync, isOnline } = cloudService.getSyncStatus();
+     */
+    getSyncStatus(): {
+        enabled: boolean;
+        lastSync?: Date;
+        isOnline?: boolean;
+    };
+    /**
+     * 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' });
+     */
+    enableCloudSync(config: CloudSyncConfig): Promise<void>;
+    /**
+     * Disable cloud synchronization
+     *
+     * @example
+     * cloudService.disableCloudSync();
+     */
+    disableCloudSync(): void;
+    /**
+     * Check if cloud sync is currently enabled
+     * @returns True if cloud sync is enabled, false otherwise
+     *
+     * @example
+     * if (cloudService.isCloudSyncEnabled()) {
+     *   // ...
+     * }
+     */
+    isCloudSyncEnabled(): boolean;
+    /**
+     * Get current cloud sync configuration
+     * @returns Cloud sync configuration or undefined if not set
+     *
+     * @example
+     * const cfg = cloudService.getCloudSyncConfig();
+     */
+    getCloudSyncConfig(): CloudSyncConfig | undefined;
+    /**
+     * 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']);
+     */
+    syncTables(tableNames: string[]): Promise<void>;
+}

package/dist/services/CloudSyncService.js

@@ -0,0 +1,196 @@
+import { createServiceLogger } from '../utils/logger';
+const logger = createServiceLogger('CloudSyncService');
+export class CloudSyncService {
+    db;
+    cloudSyncConfig;
+    cloudSyncEnabled = false;
+    syncIntervalId;
+    constructor(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) {
+        this.cloudSyncConfig = config;
+        if (!this.cloudSyncConfig) {
+            logger.error('Cloud sync config not provided');
+            return;
+        }
+        try {
+            const cloudApi = this.db
+                .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);
+        }
+    }
+    startPeriodicSync() {
+        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() {
+        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() {
+        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
+                .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() {
+        if (!this.cloudSyncEnabled) {
+            return { enabled: false };
+        }
+        const cloudDb = this.db;
+        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) {
+        if (this.cloudSyncEnabled) {
+            logger.warn('Cloud sync is already enabled');
+            return;
+        }
+        await this.initializeCloudSync(config);
+    }
+    /**
+     * Disable cloud synchronization
+     *
+     * @example
+     * cloudService.disableCloudSync();
+     */
+    disableCloudSync() {
+        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() {
+        return this.cloudSyncEnabled;
+    }
+    /**
+     * Get current cloud sync configuration
+     * @returns Cloud sync configuration or undefined if not set
+     *
+     * @example
+     * const cfg = cloudService.getCloudSyncConfig();
+     */
+    getCloudSyncConfig() {
+        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) {
+        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/dist/services/DecoratorUtils.d.ts

@@ -0,0 +1,12 @@
+export type ClassConstructor<T = unknown> = abstract new (..._args: never[]) => T;
+export type LegacyArgs = [Record<'constructor', ClassConstructor>, string];
+export type FieldContext = {
+    kind: 'field';
+    name: string;
+    addInitializer(_init: (_this: {
+        constructor: ClassConstructor;
+    }) => void): void;
+};
+export type StandardArgs = [unknown, FieldContext];
+export declare function isLegacyArgs(args: unknown[]): args is LegacyArgs;
+export declare function isFieldContext(args: unknown[]): args is StandardArgs;

package/dist/services/DecoratorUtils.js

@@ -0,0 +1,10 @@
+export function isLegacyArgs(args) {
+    return Array.isArray(args) && typeof args[1] === 'string';
+}
+export function isFieldContext(args) {
+    const ctx = args[1];
+    return !!ctx &&
+        typeof ctx === 'object' &&
+        ctx.kind === 'field' &&
+        typeof ctx.name === 'string';
+}

package/dist/services/EntityFactory.d.ts

@@ -0,0 +1,25 @@
+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 declare function newEntity<T extends BaseEntity>(EntityClass: new () => T, data: Partial<T>): T;