@indexeddb-orm/idb-orm 0.0.1

package/dist/services/EntityFactory.js

@@ -0,0 +1,27 @@
+/**
+ * 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(EntityClass, data) {
+    const instance = new EntityClass();
+    return instance.init(data);
+}

package/dist/services/EntityRegistry.d.ts

@@ -0,0 +1,61 @@
+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'>;
+/**
+ * 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 declare function defineEntity<T>(EntityClass: ClassConstructor<T>, options: DefineEntityOptions): void;
+export declare function getDefinedEntityMeta(ctor: ClassConstructor): StoredEntityMeta | undefined;
+export declare function getDefinedColumns(ctor: ClassConstructor): Record<string, ColumnConfig> | undefined;
+export declare function getDefinedCompoundIndexes(ctor: ClassConstructor): {
+    name: string;
+    unique: boolean;
+    columns: string[];
+}[] | undefined;
+export declare function getDefinedRelations(ctor: ClassConstructor): Record<string, RelationConfig> | undefined;
+export {};

package/dist/services/EntityRegistry.js

@@ -0,0 +1,56 @@
+const entityMeta = new Map();
+const columnMeta = new Map();
+const compoundIndexMeta = new Map();
+const relationMeta = new Map();
+/**
+ * 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(EntityClass, options) {
+    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) {
+    return entityMeta.get(ctor);
+}
+export function getDefinedColumns(ctor) {
+    return columnMeta.get(ctor);
+}
+export function getDefinedCompoundIndexes(ctor) {
+    return compoundIndexMeta.get(ctor);
+}
+export function getDefinedRelations(ctor) {
+    return relationMeta.get(ctor);
+}

package/dist/services/EntitySchema.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { BaseEntity } from './BaseEntity';
+export declare class EntitySchema<T extends BaseEntity = BaseEntity> {
+    private entityClass;
+    private schema?;
+    constructor(entityClass: new () => T, schema?: z.ZodSchema<unknown>);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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>;
+    /**
+     * 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[];
+    };
+    /**
+     * 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;
+}

package/dist/services/EntitySchema.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { getColumnMetadata } from '../metadata/Column';
+import { getEntityMetadata } from '../metadata/Entity';
+import { getDefinedColumns } from './EntityRegistry';
+export class EntitySchema {
+    entityClass;
+    schema;
+    constructor(entityClass, schema) {
+        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() {
+        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() {
+        return this.schema
+            || this.entityClass.schema;
+    }
+    /**
+     * Get column metadata for this entity
+     * @returns Object containing column metadata
+     *
+     * @example
+     * const cols = new EntitySchema(User).getColumns();
+     * // cols.name.required === true
+     */
+    getColumns() {
+        const defined = getDefinedColumns(this.entityClass);
+        if (defined) {
+            return defined;
+        }
+        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) {
+        const schema = this.getSchema();
+        if (!schema) {
+            const columns = this.getColumns();
+            const missing = [];
+            for (const [propertyKey, options] of Object.entries(columns)) {
+                if (!options || !options.required) {
+                    continue;
+                }
+                const value = data[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) {
+        const instance = new this.entityClass();
+        const columns = this.getColumns();
+        for (const [propertyKey, options] of Object.entries(columns)) {
+            const hasValueInData = data
+                && data[propertyKey] !== undefined;
+            const hasValueInInstance = instance[propertyKey] !== undefined;
+            if (!hasValueInData &&
+                !hasValueInInstance &&
+                options &&
+                Object.prototype.hasOwnProperty.call(options, 'default')) {
+                const defaultOption = options.default;
+                const value = typeof defaultOption === 'function'
+                    ? defaultOption()
+                    : defaultOption;
+                instance[propertyKey] = value;
+            }
+        }
+        if (data) {
+            Object.assign(instance, data);
+        }
+        return instance;
+    }
+}

package/dist/services/MigrationManager.d.ts

@@ -0,0 +1,70 @@
+import type Dexie from 'dexie';
+import type { EntityConstructor, Migration } from '../types';
+export declare class MigrationManager {
+    private dbName;
+    private currentVersion;
+    private db;
+    constructor(dbName: string, currentVersion: number);
+    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;
+    private getLastMigrationVersion;
+    private setLastMigrationVersion;
+    private getSchemaHash;
+    private setSchemaHash;
+    /**
+     * 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
+     */
+    runMigrations(migrations: Migration[], db: (Dexie & {
+        clearAllData: () => Promise<void>;
+    })): Promise<void>;
+    autoRunMigrations(migrations: Migration[], db: (Dexie & {
+        clearAllData: () => Promise<void>;
+    })): void;
+    /**
+     * 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
+     */
+    performSelectiveReset(entities: EntityConstructor[], db: Dexie): Promise<void>;
+    autoSelectiveReset(entities: EntityConstructor[], db: Dexie): void;
+    /**
+     * Reset entire database by clearing all data
+     * @param db - Database instance for clearing data
+     * @returns Promise that resolves when database is reset
+     */
+    resetDatabase(db: {
+        clearAllData: () => Promise<void>;
+    }): Promise<void>;
+    /**
+     * Automatically reset database asynchronously
+     * @param db - Database instance for clearing data
+     */
+    autoResetDatabase(db: {
+        clearAllData: () => Promise<void>;
+    }): void;
+    /**
+     * 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
+     */
+    checkSchemaChanges(entities: EntityConstructor[], db: {
+        clearAllData: () => Promise<void>;
+    }): Promise<boolean>;
+}

package/dist/services/MigrationManager.js

@@ -0,0 +1,181 @@
+import { createServiceLogger } from '../utils/logger';
+import { SchemaBuilder } from './SchemaBuilder';
+const logger = createServiceLogger('MigrationManager');
+export class MigrationManager {
+    dbName;
+    currentVersion;
+    db = null;
+    constructor(dbName, currentVersion) {
+        this.dbName = dbName;
+        this.currentVersion = currentVersion;
+    }
+    setDatabase(db) {
+        this.db = db;
+    }
+    async getLastMigrationVersion() {
+        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 || 0;
+    }
+    async setLastMigrationVersion(version) {
+        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(),
+        });
+    }
+    async getSchemaHash() {
+        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 || null;
+    }
+    async setSchemaHash(hash) {
+        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, db) {
+        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, db) {
+        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, db) {
+        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, db) {
+        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) {
+        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) {
+        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, db) {
+        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;
+    }
+}

package/dist/services/RelationLoader.d.ts

@@ -0,0 +1,66 @@
+import type { EntityConstructor } from '../types';
+import { BaseEntity } from './BaseEntity';
+export declare class RelationLoader {
+    private db;
+    constructor(database: {
+        table: (_name: string) => unknown;
+    });
+    private resolveTableName;
+    /**
+     * Load relations for an entity
+     * @param entity - The entity to load relations for
+     * @param entityClass - The entity class
+     * @param relationNames - Optional array of specific relation names to load.
+     * If not provided, loads all eager relations.
+     */
+    loadRelations<T extends BaseEntity>(entity: T, entityClass: EntityConstructor<T>, relationNames?: string[]): Promise<T>;
+    /**
+     * Load a specific relation by name
+     * @param entity - The entity to load relation for
+     * @param entityClass - The entity class
+     * @param relationName - The name of the relation to load
+     * @returns Promise resolving to the loaded relation data
+     */
+    loadRelationByName<T extends BaseEntity, K extends keyof T>(entity: T, entityClass: EntityConstructor<T>, relationName: K): Promise<T[K]>;
+    /**
+     * Load a specific relation based on metadata
+     * @param entity - The entity to load relation for
+     * @param relationMeta - The relation metadata containing:
+     * type, target, and configuration
+     * @returns Promise resolving to the loaded relation data
+     */
+    loadRelation<T extends BaseEntity>(entity: T, relationMeta: {
+        type: string;
+        target: string | EntityConstructor;
+        foreignKey?: string;
+        joinTable?: string;
+    }): Promise<unknown>;
+    private loadOneToOne;
+    private loadOneToMany;
+    /**
+     * Load many-to-many relation
+     */
+    private loadManyToMany;
+    /**
+     * Save entity with all its relations
+     * @param entity - The entity to save with relations
+     * @param entityClass - The entity class
+     * @returns Promise resolving to the saved entity with relations
+     */
+    saveWithRelations<T extends BaseEntity>(entity: T, entityClass: EntityConstructor<T>): Promise<T>;
+    /**
+     * Delete entity with cascade handling for relations
+     * @param entity - The entity to delete
+     * @param entityClass - The entity class
+     */
+    deleteWithRelations<T extends BaseEntity>(entity: T, entityClass: EntityConstructor<T>): Promise<void>;
+    private deleteRelation;
+    private deleteOneToOne;
+    private deleteOneToMany;
+    private deleteManyToMany;
+    private saveEntity;
+    private saveRelation;
+    private saveOneToOne;
+    private saveOneToMany;
+    private saveManyToMany;
+}