@indexeddb-orm/idb-orm 0.0.1

package/dist/Database.js

@@ -0,0 +1,288 @@
+import Dexie from 'dexie';
+import { getEntityMetadata } from './metadata/Entity';
+import { AggregationService } from './services/AggregationService';
+import { CloudSyncService } from './services/CloudSyncService';
+import { MigrationManager } from './services/MigrationManager';
+import { RelationLoader } from './services/RelationLoader';
+import { SchemaBuilder } from './services/SchemaBuilder';
+import { logger } from './utils/logger';
+export class Database extends Dexie {
+    entitySchemas = new Map();
+    migrationManager;
+    relationLoader;
+    aggregationService;
+    cloudSyncService;
+    migrationMetadata;
+    constructor(config) {
+        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(entityClass) {
+        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);
+    }
+    /**
+     * Perform aggregation on entity data
+     *
+     * @example
+     * const result = await db.aggregate({
+     *   entityClass: Post,
+     *   options: { where: { category: 'tech' } },
+     * });
+     */
+    async aggregate(params) {
+        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) {
+        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;
+    }
+    /**
+     * Clear all data from database
+     *
+     * @example
+     * await db.clearAllData();
+     */
+    async clearAllData() {
+        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() {
+        await this.migrationManager.resetDatabase(this);
+    }
+    /**
+     * Check if schema has changed and reset if needed
+     *
+     * @example
+     * const changed = await db.checkSchemaChanges();
+     */
+    async checkSchemaChanges() {
+        return this.migrationManager.checkSchemaChanges(Array.from(this.entitySchemas.values()), this);
+    }
+    /**
+     * Manually perform selective reset for changed tables only
+     *
+     * @example
+     * await db.performSelectiveReset();
+     */
+    async performSelectiveReset() {
+        await this.migrationManager.performSelectiveReset(Array.from(this.entitySchemas.values()), this);
+    }
+    /**
+     * Run migrations for schema changes
+     *
+     * @example
+     * await db.runMigrations(migrations);
+     */
+    async runMigrations(migrations) {
+        await this.migrationManager.runMigrations(migrations, this);
+    }
+    /**
+     * Get typed table for entity
+     *
+     * @example
+     * const posts = db.getTypedTable(Post);
+     */
+    getTypedTable(entityClass) {
+        const metadata = getEntityMetadata(entityClass);
+        const tableName = metadata?.tableName || entityClass.name.toLowerCase() + 's';
+        return this.table(tableName);
+    }
+    /**
+     * Get table with proper typing for specific entity
+     *
+     * @example
+     * const users = db.getTableForEntity(User);
+     */
+    getTableForEntity(entityClass) {
+        return this.getTypedTable(entityClass);
+    }
+    /**
+     * Get all entities
+     *
+     * @example
+     * const all = db.getEntities();
+     */
+    getEntities() {
+        return Array.from(this.entitySchemas.values());
+    }
+    /**
+     * Get entity by table name
+     *
+     * @example
+     * const UserClass = db.getEntity('users');
+     */
+    getEntity(tableName) {
+        return this.entitySchemas.get(tableName);
+    }
+    /**
+     * Load relations for an entity
+     *
+     * @example
+     * const userWithRelations = await db.loadRelations({
+     *   entity: user,
+     *   entityClass: User,
+     *   relationNames: ['posts'],
+     * });
+     */
+    async loadRelations(params) {
+        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(params) {
+        return this.relationLoader.loadRelationByName(params.entity, params.entityClass, params.relationName);
+    }
+    /**
+     * Save entity with relations
+     *
+     * @example
+     * const saved = await db.saveWithRelations({
+     *   entity: user,
+     *   entityClass: User,
+     * });
+     */
+    async saveWithRelations(params) {
+        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(params) {
+        return this.relationLoader
+            .deleteWithRelations(params.entity, params.entityClass);
+    }
+    /**
+     * Manual sync with cloud
+     */
+    async sync() {
+        return this.cloudSyncService.sync();
+    }
+    /**
+     * Get sync status
+     */
+    getSyncStatus() {
+        return this.cloudSyncService.getSyncStatus();
+    }
+    /**
+     * Enable cloud sync (if not already enabled)
+     */
+    async enableCloudSync(config) {
+        return this.cloudSyncService.enableCloudSync(config);
+    }
+    /**
+     * Disable cloud sync
+     */
+    disableCloudSync() {
+        this.cloudSyncService.disableCloudSync();
+    }
+    /**
+     * Check if cloud sync is enabled
+     */
+    isCloudSyncEnabled() {
+        return this.cloudSyncService.isCloudSyncEnabled();
+    }
+    /**
+     * Get cloud sync configuration
+     */
+    getCloudSyncConfig() {
+        return this.cloudSyncService.getCloudSyncConfig();
+    }
+    /**
+     * Force sync specific tables
+     */
+    async syncTables(tableNames) {
+        return this.cloudSyncService.syncTables(tableNames);
+    }
+}

package/dist/decorators/Column.d.ts

@@ -0,0 +1,79 @@
+import type { ClassConstructor } from '../services/DecoratorUtils';
+import type { ColumnOptions, CompoundIndexOptions } from '../types';
+export interface ColumnMetadata extends ColumnOptions {
+    propertyKey: string;
+}
+export declare abstract class BaseDecorator {
+    static getMetadata<T>(key: symbol, target: object | ClassConstructor): T | undefined;
+    static setMetadata<T>(key: symbol, value: T, target: object | ClassConstructor): void;
+}
+/**
+ * Column decorator: marks a class field as a persisted column with options.
+ * @param options - Column options (required, default, indexed, unique, etc.)
+ * @returns Property decorator function
+ *
+ * @example
+ * class User {
+ *   @Column({ required: true })
+ *   name!: string;
+ * }
+ */
+export declare function Column(options?: ColumnOptions): (...args: unknown[]) => void;
+/**
+ * Primary key decorator: marks a field as primary key.
+ * @param params - Options (autoIncrement: defaults to true)
+ * @returns Property decorator function
+ *
+ * @example
+ * class User {
+ *   @PrimaryKey()
+ *   id!: number;
+ * }
+ */
+export declare function PrimaryKey(params?: {
+    autoIncrement?: boolean;
+}): (...args: unknown[]) => void;
+/**
+ * Index decorator: marks a field as indexed.
+ * @returns Property decorator function
+ *
+ * @example
+ * class Post { @Index() @Column() authorId?: number }
+ */
+export declare function Index(): (...args: unknown[]) => void;
+/**
+ * Unique decorator: marks a field as unique.
+ * @returns Property decorator function
+ *
+ * @example
+ * class User { @Unique() @Column() email!: string }
+ */
+export declare function Unique(): (...args: unknown[]) => void;
+/**
+ * CompoundIndex decorator: defines a compound index on multiple fields.
+ * @param options - name (optional), unique (optional), columns (required)
+ * @returns Class decorator function
+ *
+ * @example
+ * @CompoundIndex({ columns: ['firstName', 'lastName'] })
+ * class User { /* fields *\/ }
+ */
+export declare function CompoundIndex(options: CompoundIndexOptions): (target: ClassConstructor) => void;
+/**
+ * Retrieve column metadata for a class.
+ * @param target - The entity class (constructor) or prototype
+ * @returns Record mapping propertyKey -> ColumnMetadata
+ *
+ * @example
+ * const cols = getColumnMetadata(User);
+ */
+export declare function getColumnMetadata(target: object | ClassConstructor): Record<string, ColumnMetadata>;
+/**
+ * Retrieve compound index metadata for a class.
+ * @param target - The entity class (constructor) or prototype
+ * @returns Array of compound index options
+ *
+ * @example
+ * const indexes = getCompoundIndexMetadata(User);
+ */
+export declare function getCompoundIndexMetadata(target: object | ClassConstructor): CompoundIndexOptions[];

package/dist/decorators/Column.js

@@ -0,0 +1,236 @@
+// reflect-metadata no longer required
+import { isFieldContext, isLegacyArgs, } from '../services/DecoratorUtils';
+import { getDefinedColumns, getDefinedCompoundIndexes, } from '../services/EntityRegistry';
+const COLUMNS_METADATA_KEY = Symbol('columns');
+const COMPOUND_INDEXES_METADATA_KEY = Symbol('compoundIndexes');
+export class BaseDecorator {
+    static getMetadata(key, target) {
+        // Access reflect-metadata only if available
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const reflectGet = Reflect?.getMetadata?.bind(Reflect);
+        return reflectGet ? reflectGet(key, target) : undefined;
+    }
+    static setMetadata(key, value, target) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const reflectDefine = Reflect?.defineMetadata?.bind(Reflect);
+        if (reflectDefine) {
+            reflectDefine(key, value, target);
+        }
+    }
+}
+/**
+ * Column decorator: marks a class field as a persisted column with options.
+ * @param options - Column options (required, default, indexed, unique, etc.)
+ * @returns Property decorator function
+ *
+ * @example
+ * class User {
+ *   @Column({ required: true })
+ *   name!: string;
+ * }
+ */
+export function Column(options = {}) {
+    return function (...args) {
+        // Legacy TS decorators
+        if (isLegacyArgs(args)) {
+            const [target, propertyKey] = args;
+            const columns = BaseDecorator.getMetadata(COLUMNS_METADATA_KEY, target.constructor) || {};
+            columns[propertyKey] = { propertyKey, ...options };
+            BaseDecorator.setMetadata(COLUMNS_METADATA_KEY, columns, target.constructor);
+            return;
+        }
+        // Standard decorators (TC39)
+        if (isFieldContext(args)) {
+            const [, context] = args;
+            const propertyKey = context.name;
+            context.addInitializer(function () {
+                const ctor = this.constructor;
+                const columns = BaseDecorator.getMetadata(COLUMNS_METADATA_KEY, ctor) || {};
+                columns[propertyKey] = { propertyKey, ...options };
+                BaseDecorator.setMetadata(COLUMNS_METADATA_KEY, columns, ctor);
+            });
+        }
+    };
+}
+/**
+ * Primary key decorator: marks a field as primary key.
+ * @param params - Options (autoIncrement: defaults to true)
+ * @returns Property decorator function
+ *
+ * @example
+ * class User {
+ *   @PrimaryKey()
+ *   id!: number;
+ * }
+ */
+export function PrimaryKey(params = {}) {
+    return function (...args) {
+        const apply = (ctor, propertyKey) => {
+            const columns = BaseDecorator.getMetadata(COLUMNS_METADATA_KEY, ctor) || {};
+            columns[propertyKey] = {
+                propertyKey,
+                primaryKey: true,
+                autoIncrement: params.autoIncrement ?? true,
+            };
+            BaseDecorator.setMetadata(COLUMNS_METADATA_KEY, columns, 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 () {
+                apply(this.constructor, propertyKey);
+            });
+        }
+    };
+}
+/**
+ * Index decorator: marks a field as indexed.
+ * @returns Property decorator function
+ *
+ * @example
+ * class Post { @Index() @Column() authorId?: number }
+ */
+export function Index() {
+    return function (...args) {
+        const apply = (ctor, propertyKey) => {
+            const columns = BaseDecorator.getMetadata(COLUMNS_METADATA_KEY, ctor) || {};
+            if (columns[propertyKey]) {
+                columns[propertyKey].indexed = true;
+            }
+            else {
+                columns[propertyKey] = { propertyKey, indexed: true };
+            }
+            BaseDecorator.setMetadata(COLUMNS_METADATA_KEY, columns, 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 () {
+                apply(this.constructor, propertyKey);
+            });
+        }
+    };
+}
+/**
+ * Unique decorator: marks a field as unique.
+ * @returns Property decorator function
+ *
+ * @example
+ * class User { @Unique() @Column() email!: string }
+ */
+export function Unique() {
+    return function (...args) {
+        const apply = (ctor, propertyKey) => {
+            const columns = BaseDecorator.getMetadata(COLUMNS_METADATA_KEY, ctor) || {};
+            if (columns[propertyKey]) {
+                columns[propertyKey].unique = true;
+            }
+            else {
+                columns[propertyKey] = { propertyKey, unique: true };
+            }
+            BaseDecorator.setMetadata(COLUMNS_METADATA_KEY, columns, 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 () {
+                apply(this.constructor, propertyKey);
+            });
+        }
+    };
+}
+/**
+ * CompoundIndex decorator: defines a compound index on multiple fields.
+ * @param options - name (optional), unique (optional), columns (required)
+ * @returns Class decorator function
+ *
+ * @example
+ * @CompoundIndex({ columns: ['firstName', 'lastName'] })
+ * class User { /* fields *\/ }
+ */
+export function CompoundIndex(options) {
+    return function (target) {
+        const compoundIndexes = BaseDecorator.getMetadata(COMPOUND_INDEXES_METADATA_KEY, target) || [];
+        compoundIndexes.push({
+            name: options.name || options.columns.join('_'),
+            unique: options.unique || false,
+            columns: options.columns,
+        });
+        BaseDecorator
+            .setMetadata(COMPOUND_INDEXES_METADATA_KEY, compoundIndexes, target);
+    };
+}
+/**
+ * Retrieve column metadata for a class.
+ * @param target - The entity class (constructor) or prototype
+ * @returns Record mapping propertyKey -> ColumnMetadata
+ *
+ * @example
+ * const cols = getColumnMetadata(User);
+ */
+export function getColumnMetadata(target) {
+    const ctor = (typeof target === 'function')
+        ? target
+        : target.constructor;
+    const defined = getDefinedColumns(ctor);
+    if (defined) {
+        const out = {};
+        for (const [key, cfg] of Object.entries(defined)) {
+            out[key] = { propertyKey: key, ...cfg };
+        }
+        // If no explicit primary key was defined via defineEntity,
+        // assume conventional auto-increment primary key on `id`.
+        const hasPrimary = Object.values(out).some(c => c.primaryKey);
+        if (!hasPrimary) {
+            if (!out.id) {
+                out.id = { propertyKey: 'id', primaryKey: true, autoIncrement: true };
+            }
+            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?.getMetadata?.bind(Reflect);
+    return reflectGet ? (reflectGet(COLUMNS_METADATA_KEY, ctor) || {}) : {};
+}
+/**
+ * Retrieve compound index metadata for a class.
+ * @param target - The entity class (constructor) or prototype
+ * @returns Array of compound index options
+ *
+ * @example
+ * const indexes = getCompoundIndexMetadata(User);
+ */
+export function getCompoundIndexMetadata(target) {
+    const ctor = (typeof target === 'function')
+        ? target
+        : target.constructor;
+    const defined = getDefinedCompoundIndexes(ctor);
+    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?.getMetadata?.bind(Reflect);
+    return reflectGet ? (reflectGet(COMPOUND_INDEXES_METADATA_KEY, ctor) || []) : [];
+}

package/dist/decorators/Entity.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { ClassConstructor } from '../services/DecoratorUtils';
+import type { EntityOptions } from '../types';
+export interface EntityMetadata {
+    tableName: string;
+    schema?: z.ZodSchema<unknown>;
+    timestamps?: boolean;
+}
+/**
+ * Entity decorator: marks a class as a persisted entity and attaches metadata.
+ *
+ * @param options - Optional entity options:
+ * - tableName: custom table name (defaults to className + 's')
+ * - schema: zod schema used for validation
+ * - timestamps: enable automatic timestamp fields (future use)
+ * @returns Class decorator function
+ *
+ * @example
+ * @Entity({ tableName: 'users', schema: userSchema })
+ * class User { /* ... *\/ }
+ */
+export declare function Entity(_options?: EntityOptions): (_target: ClassConstructor) => void;
+/**
+ * Get entity metadata previously set by @Entity.
+ * @param target - The entity class (constructor)
+ * @returns EntityMetadata or undefined if not set
+ *
+ * @example
+ * const meta = getEntityMetadata(User);
+ * console.log(meta?.tableName);
+ */
+export declare function getEntityMetadata(target: ClassConstructor): EntityMetadata | undefined;

package/dist/decorators/Entity.js

@@ -0,0 +1,44 @@
+import { getDefinedEntityMeta } from '../services/EntityRegistry';
+const ENTITY_METADATA_KEY = Symbol('entity');
+/**
+ * Entity decorator: marks a class as a persisted entity and attaches metadata.
+ *
+ * @param options - Optional entity options:
+ * - tableName: custom table name (defaults to className + 's')
+ * - schema: zod schema used for validation
+ * - timestamps: enable automatic timestamp fields (future use)
+ * @returns Class decorator function
+ *
+ * @example
+ * @Entity({ tableName: 'users', schema: userSchema })
+ * class User { /* ... *\/ }
+ */
+export function Entity(_options = {}) {
+    // No-op decorator retained for backwards compatibility
+    return function (_target) { };
+}
+/**
+ * Get entity metadata previously set by @Entity.
+ * @param target - The entity class (constructor)
+ * @returns EntityMetadata or undefined if not set
+ *
+ * @example
+ * const meta = getEntityMetadata(User);
+ * console.log(meta?.tableName);
+ */
+export function getEntityMetadata(target) {
+    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?.getMetadata?.bind(Reflect);
+    if (reflectGet) {
+        return reflectGet(ENTITY_METADATA_KEY, target);
+    }
+    return undefined;
+}