@quan-erp/shared-backend-core 1.0.1

package/dist/types/0d45f5fd/78464d38.d.ts

@@ -0,0 +1,189 @@
+import "reflect-metadata";
+import { Migration } from "../0274021b/47a09c7e.js";
+import { DataSource, DataSourceOptions } from "typeorm";
+import { Manager } from "./d453df06.js";
+import { IDatabaseMigrationClass } from "@quan-erp/shared-types";
+export declare const DATABASE_METADATA_KEY = "server:database";
+export declare const DB_CONNECTION_KEY = "server:db_connection";
+type DatabaseOptions = {
+    name?: string;
+    plugin: string;
+    options: DataSourceOptions & {
+        entities?: any[];
+    };
+};
+/**
+ * Class decorator to register a database configuration for a class.
+ *
+ * Stores database connection metadata on the class constructor. Multiple
+ * database configurations can be stored for a single class.
+ *
+ * @param options - Database options (except `plugin` which is handled elsewhere)
+ *
+ * @example
+ * ```ts
+ * @Database({
+ *   name: 'default',
+ *   options: {
+ *     type: 'mysql',
+ *     host: 'localhost',
+ *     port: 3306,
+ *     username: 'root',
+ *     password: 'pass',
+ *     database: 'my_db',
+ *     entities: [UserEntity, PostEntity],
+ *   }
+ * })
+ * class AppService {}
+ * ```
+ */
+export declare function Database(options: Omit<DatabaseOptions, 'plugin'>): ClassDecorator;
+export declare function getDatabaseConfig(target: any): DatabaseOptions[] | undefined;
+/**
+ * Property decorator to inject a TypeORM DataSource or connection for a given plugin.
+ *
+ * Stores metadata on the property to be used later by a dependency injector or service
+ * that resolves database connections.
+ *
+ * @param plugin - Optional plugin name to select the database connection
+ * @param name - Database connection name (default: `DataSourceManager.DEFAULT_NAME`)
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class UserService {
+ *   @InjectDatabaseSource('usersPlugin')
+ *   private dataSource: DataSource;
+ * }
+ * ```
+ */
+type InjectDatabaseSourceOptions = {
+    plugin?: string;
+    name: string;
+};
+export declare function InjectDatabaseSource(plugin?: string, name?: string): PropertyDecorator;
+export declare function getDatabaseConnectionKey(target: any, propertyKey: string | symbol): InjectDatabaseSourceOptions | undefined;
+/**
+ * Class decorator to attach a set of database migrations to an entity or module.
+ *
+ * Stores metadata on the class containing the provided migrations array, which can
+ * later be read by migration runners or database initialization services.
+ *
+ * @param migrations - Array of Migration instances to associate with the class
+ *
+ * @example
+ * ```ts
+ * @Migrations([
+ *   new CreateUsersTable(),
+ *   new AddEmailToUsers(),
+ * ])
+ * class UserModule {}
+ * ```
+ */
+export declare function Migrations(migrations: Migration[]): ClassDecorator;
+export declare function getModuleMigrations(target: any): Migration[];
+/**
+ * Class decorator to attach a list of database entities to a class/module.
+ *
+ * Stores metadata on the target class containing the provided entities, which can
+ * later be retrieved by ORM initialization code or module loaders.
+ *
+ * @param entities - Array of entity classes or entity names (strings) to associate with the class
+ *
+ * @example
+ * ```ts
+ * @Entities([UserEntity, PostEntity])
+ * class UserModule {}
+ *
+ * @Entities(['UserEntity', 'PostEntity'])
+ * class UserModule {}
+ * ```
+ */
+export declare function Entities(entities: Function[] | string[]): (target: any) => void;
+export declare function getModuleEntities(moduleClass: any): Function[] | string[];
+type DatasourceRegistryValue = {
+    options: any;
+};
+/**
+ * Orchestrator for all database-related operations in the Quan ERP environment.
+ *
+ * This manager handles the lifecycle of multiple TypeORM `DataSource` instances,
+ * plugin-scoped entity registration, and automated database migrations.
+ * It ensures that each plugin operates against its intended database schema
+ * while allowing for shared connections where necessary.
+ */
+export declare class DataSourceManager extends Manager<DataSource, DatasourceRegistryValue> {
+    /** Internal registry of entities grouped by plugin and datasource name. */
+    private readonly dbEntities;
+    /** Cache of executed migrations to avoid redundant database lookups. */
+    private migrationsCache;
+    /**
+     * Registers a set of entities to a plugin scope and datasource.
+     *
+     * @param entities - Array of TypeORM entity classes.
+     * @param plugin - Plugin name owning the entities.
+     * @param name - Target datasource name.
+     * @param injectBy - The plugin that triggered the injection.
+     */
+    addEntities(entities: any[], plugin: string | undefined, name: string | undefined, injectBy: string): void;
+    /**
+     * Unregisters entities for a specific plugin and name.
+     *
+     * This method removes entities from the datasource registry and also
+     * cleans up references where the plugin might have injected entities
+     * into shared datasources.
+     *
+     * @param plugin - The name of the plugin whose entities should be removed.
+     * @param name - The target datasource name.
+     */
+    removeEntities(plugin: string, name?: string): void;
+    /**
+     * Retrieves all entities registered for the specified plugin and datasource name.
+     */
+    getEntities(plugin: string, name?: string): any[];
+    /**
+     * Finds the singleton entity class/definition registered for a given plugin scope.
+     *
+     * This uses class hashing to ensure the correct entity reference is returned
+     * even when multiple versions of the same entity class might exist in memory
+     * due to dynamic module loading.
+     */
+    findEntityByClass(cls: any, plugin?: string, name?: string): any | null;
+    /**
+     * Creates and initializes a new TypeORM DataSource.
+     *
+     * This method automatically collects all entities registered for the given
+     * plugin/name combination before initializing the physical connection.
+     *
+     * @param newOptions - Standard TypeORM DataSource options.
+     */
+    newDatasource(newOptions: DataSourceOptions, plugin?: string, name?: string): Promise<void>;
+    newDatasources(options: DatabaseOptions[]): Promise<void>;
+    deRegisterByScope(plugin: string, name?: string): Promise<void>;
+    reloadDataSource(plugin: string, name?: string): Promise<void>;
+    /**
+     * Re-initializes all registered datasources.
+     *
+     * This is typically called after adding or removing plugins to ensure
+     * that migrations and entity lists are refreshed across the system.
+     */
+    reloadAllSources(): Promise<void>;
+    /**
+     * Executes a set of database migrations for a specific plugin.
+     *
+     * Logic:
+     * 1. Checks migration history in the database.
+     * 2. Skips already executed migrations.
+     * 3. Executes `up` methods within a managed transaction.
+     * 4. Logs execution status to the internal migration history table.
+     *
+     * @param pluginName - Name of the plugin.
+     * @param pluginVersion - Current version of the plugin.
+     * @param migrations - List of migration classes to run.
+     * @returns List of successfully executed migration classes.
+     */
+    runMigrations(pluginName: string, pluginVersion: string, migrations: (IDatabaseMigrationClass | IDatabaseMigrationClass[])[]): Promise<IDatabaseMigrationClass[]>;
+    runRollbackMigration(pluginName: string, pluginVersion: string, migrations: (IDatabaseMigrationClass | IDatabaseMigrationClass[])[]): Promise<void>;
+    logDebugInfo(): void;
+}
+export {};

package/dist/types/0d45f5fd/7932a0bf.d.ts

@@ -0,0 +1,28 @@
+import "reflect-metadata";
+export declare const SERVICE_METADATA_KEY = "service";
+/**
+ * Class decorator to mark a class as a service.
+ *
+ * Stores metadata for the class, including an optional service name.
+ * If no name is provided, the class name can be used as a default.
+ *
+ * @param {string} [name] - Optional name for the service.
+ *
+ * @returns {ClassDecorator} A decorator that attaches service metadata to the class.
+ *
+ * @example
+ * ```ts
+ * @Service("UserService")
+ * class UserService {
+ *   // service logic
+ * }
+ *
+ * @Service()
+ * class AuthService {
+ *   // service logic, metadata uses class name by default
+ * }
+ * ```
+ */
+export declare function Service(name?: string): ClassDecorator;
+export declare function getServiceName(target: any): string | undefined;
+export declare function ServiceDecorator(arg?: string | Function): any;

package/dist/types/0d45f5fd/7ec9eec1.d.ts

@@ -0,0 +1,28 @@
+import "reflect-metadata";
+export interface CronJobOptions {
+    expression: string;
+    name?: string;
+}
+/**
+ * Method decorator to mark a method as a cron job.
+ *
+ * Stores cron job metadata on the class constructor, which can later
+ * be read by a scheduler to automatically register and run the jobs.
+ *
+ * @param options - Cron job options including `expression` and optional `name`.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @CronJob({ expression: '0 * * * *', name: 'HourlyUserCleanup' })
+ *   cleanupInactiveUsers() {
+ *     // logic to clean up inactive users
+ *   }
+ * }
+ * ```
+ */
+export declare function CronJob(options: CronJobOptions): MethodDecorator;
+export declare function getCronJobs(target: any): {
+    propertyKey: string | symbol;
+    options: CronJobOptions;
+}[];

package/dist/types/0d45f5fd/885b723d.d.ts

@@ -0,0 +1,59 @@
+import { Manager, RegistryValue } from "./d453df06.js";
+/**
+ * The core Dependency Injection (DI) container for the Quan ERP kernel.
+ *
+ * This manager maintains a hierarchical registry of singleton service instances
+ * and "Beans" (dynamically provided objects), partitioned by plugin scope.
+ * It ensures that each plugin can resolve its own dependencies while allowing
+ * for cross-plugin service discovery.
+ *
+ * Key Features:
+ * 1. **Scoped Storage**: Isolates dependencies by plugin name, preventing naming collisions.
+ * 2. **Stable Hashing**: Uses content-based class hashing to maintain instance consistency
+ *    even when modules are dynamically reloaded.
+ * 3. **Bean Support**: Allows registration of plain objects produced by factories.
+ */
+export declare class ContainerRegistryManager extends Manager<any> {
+    /**
+     * @deprecated Use `registerFromClass()` or `registerFromBean()` instead.
+     */
+    register(instance: any, metadata?: (Partial<RegistryValue<any>> & Record<string, any>) | null, plugin?: string, name?: string): void;
+    /**
+     * Registers a singleton instance associated with a class constructor.
+     *
+     * @param cls - The class constructor serving as the registration key.
+     * @param instance - The instantiated singleton of the class.
+     * @param plugin - The name of the plugin owning this service (defaults to 'default').
+     * @param name - Optional custom name for the registration.
+     */
+    registerFromClass(cls: any, instance: any, plugin?: string, name?: string): void;
+    /**
+     * Registers a plain object (Bean) as a dependency.
+     *
+     * @param instance - The object instance to register.
+     * @param plugin - The name of the plugin owning this bean.
+     * @param name - Optional custom name for the registration.
+     */
+    registerFromBean(instance: any, plugin?: string, name?: string): void;
+    /**
+     * Checks if a class is already registered in the global container.
+     */
+    isRegistered(cls: any): boolean;
+    /**
+     * Resolves a singleton instance from the container by its class.
+     *
+     * @param cls - The class constructor to search for.
+     * @param plugin - The plugin scope to search within.
+     * @param name - Optional registration name override.
+     */
+    findByClass(cls: any, plugin?: string, name?: string): RegistryValue<any> | undefined;
+    /**
+     * Generates a stable unique identifier for a class constructor.
+     *
+     * This ID is used as the primary key in the registry. It combines a content
+     * hash of the class with any explicit `@AnnotationName` metadata to ensure
+     * that reloaded classes map to the same singleton instance when appropriate.
+     */
+    protected getClassUniqueName(cls: any, length?: number): any;
+    logDebugInfo(): void;
+}

package/dist/types/0d45f5fd/8e161648.d.ts

@@ -0,0 +1,67 @@
+import "reflect-metadata";
+import { Manager, RegistryValue } from "./d453df06.js";
+export declare enum LifecycleHookType {
+    OnInit = "OnInit",
+    OnAllModuleLoaded = "OnAllModuleLoaded",
+    OnUninstall = "OnUninstall",
+    OnBaseReady = "OnBaseReady",
+    OnShutdown = "OnShutdown",
+    OnProcessKilled = "OnProcessKilled",
+    OnHttpServerStartListening = "OnHttpServerStartListening"
+}
+/**
+ * Lifecycle Hooks Decorators
+ *
+ * These decorators allow methods in a class to be marked for execution
+ * at specific points in the application and plugin lifecycle:
+ *
+ * - `@OnInit()`                     → Called when the class is first instantiated by the container.
+ * - `@OnReady()`                    → Called when the base application or its dependencies are fully ready.
+ * - `@OnAllModuleLoaded()`          → Called after all global and plugin modules have been initialized.
+ * - `@OnHttpServerStartListening()` → Called after the Express server starts listening on its port.
+ * - `@OnUninstall()`                → Called specifically during the plugin uninstallation process.
+ * - `@OnShutdown()`                 → Called when the plugin or application is being shut down.
+ * - `@OnProcessKilled()`            → Called when the Node.js process receives a termination signal.
+ *
+ * Optionally, a `name` can be provided to identify the hook, which is
+ * useful when multiple hooks of the same type exist within a single class.
+ *
+ * Hooks are stored as metadata on the class constructor under the
+ * `LIFECYCLE_HOOKS_KEY` symbol and are retrieved and executed by the `LifeCycleManager`.
+ *
+ * Example:
+ * ```ts
+ * @Service()
+ * class MyService {
+ *   @OnInit()
+ *   initMethod() { console.log('Service instance created'); }
+ *
+ *   @OnAllModuleLoaded()
+ *   afterAllLoaded() { console.log('System is fully initialized'); }
+ *
+ *   @OnShutdown()
+ *   cleanup() { console.log('Cleaning up resources'); }
+ * }
+ * ```
+ */
+export declare const OnInit: (name?: string) => (target: any, propertyKey: string) => void;
+export declare const OnUninstall: (name?: string) => (target: any, propertyKey: string) => void;
+export declare const OnReady: (name?: string) => (target: any, propertyKey: string) => void;
+export declare const OnShutdown: (name?: string) => (target: any, propertyKey: string) => void;
+export declare const OnProcessKilled: (name?: string) => (target: any, propertyKey: string) => void;
+export declare const OnAllModuleLoaded: (name?: string) => (target: any, propertyKey: string) => void;
+export declare const OnHttpServerStartListening: (name?: string) => (target: any, propertyKey: string) => void;
+export declare function getLifecycleHooksForInstance(instance: any): LifeCycleValue[];
+type Handler = (...args: any) => any;
+type LifeCycleValue = {
+    type: LifecycleHookType;
+    handler: Handler;
+    name: string;
+};
+export declare class LifeCycleManager extends Manager<Omit<LifeCycleValue, 'name'>[]> {
+    register(instance: LifeCycleValue[], metadata?: (Partial<RegistryValue<LifeCycleValue[]>> & Record<string, any>) | null, plugin?: string, name?: string): void;
+    addLifecycleHook(hook: Omit<LifeCycleValue, 'name'>, plugin?: string, name?: string): void;
+    findHooksByPlugins(type: LifecycleHookType, plugin: string, name?: string): Omit<LifeCycleValue, 'name'>[];
+    findHooksByType(type: LifecycleHookType): Omit<LifeCycleValue, 'name'>[];
+}
+export {};

package/dist/types/0d45f5fd/8e609bb7.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/0d45f5fd/93c2615f.d.ts

@@ -0,0 +1,27 @@
+export * from "./4db5cc33.js";
+export * from "./0fb8754a.js";
+export * from "./9a2c73cf.js";
+export * from "./78464d38.js";
+export * from "./ba35bfca.js";
+export * from "./6559a8c1.js";
+export * from "./13052334.js";
+export * from "./1c59aca9.js";
+export * from "./a73ae28b.js";
+export * from "./8e161648.js";
+export * from "./7932a0bf.js";
+export * from "./7ec9eec1.js";
+export * from "./a1a2ec11.js";
+export * from "./885b723d.js";
+export * from "./8e609bb7.js";
+export * from "./8e609bb7.js";
+export * from "./ee447758.js";
+export * from "./ec0a65fc.js";
+export * from "./4dd6b41d.js";
+export * from "./b5020a96.js";
+export * from "./4b41f653.js";
+export * from "./000288c6.js";
+export * from "./b528e7a2.js";
+export * from "./60dffdb5.js";
+export * from "./6d626690.js";
+export * from "./4ced2577.js";
+export * from "./da7f739f/3e71dc06.js";

package/dist/types/0d45f5fd/96fd122b.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Marks a class as injectable for dependency injection.
+ *
+ * This decorator stores metadata on the class that indicates it can be
+ * resolved and instantiated by a DI container or manager.
+ *
+ * @param name - Optional name or token for the injectable. Useful when
+ *               multiple instances of the same class need to be distinguished.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class UserService {
+ *   ...
+ * }
+ *
+ * @Injectable('primaryService')
+ * class PrimaryService {
+ *   ...
+ * }
+ * ```
+ */
+export declare const INJECTABLE_METADATA_KEY: string;
+export declare function Injectable(name?: string): ClassDecorator;