@devisfuture/electron-modular 1.1.16 → 1.2.16

package/README.md

@@ -12,6 +12,34 @@
 - Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
 - Security policy: [SECURITY.md](SECURITY.md)
 
+## Navigation
+
+- [Overview](#overview) — High-level summary and goals.
+  - [What It Solves](#what-it-solves) — Practical pain points addressed.
+  - [What You Get](#what-you-get) — Core capabilities provided.
+  - [Key Features](#key-features) — Quick feature checklist.
+- [Example App](#example-app) — Starter/example repositories.
+- [Installation](#installation) — Install and peer dependency notes.
+- [Folders (build outputs)](#folders-build-outputs) — Build output locations.
+- [Quick Start](#quick-start) — Minimal bootstrap example for `main.ts`.
+- [Module Structure](#module-structure) — Recommended file layout for a feature module.
+- [Two Approaches to Using Modules](#two-approaches-to-using-modules) — Design choices for module APIs.
+  - [Approach 1: Direct Service Injection](#approach-1-direct-service-injection-simple) — Simple DI usage.
+  - [Approach 2: Provider Pattern](#approach-2-provider-pattern-advanced) — Provider/factory-based contracts.
+- [IPC Handlers](#ipc-handlers) — Organizing main ↔ renderer communication.
+- [Window Managers](#window-managers) — Window lifecycle and helpers.
+  - [Preload script — default behavior](#preload-script--default-behavior-) — Default preload handling.
+  - [Lifecycle Hooks (Window & WebContents events)](#lifecycle-hooks-window--webcontents-events-) — Event hook mapping.
+  - [Opening windows with URL params](#opening-windows-with-url-params-dynamic-routes-) — Route/hash usage.
+- [TypeScript types — TWindows["myWindow"]](#typescript-types--twindowsmywindow) — Typing conventions for windows.
+- [API Reference](#api-reference) — Reference for decorators and core functions.
+  - [Core Decorators](#core-decorators) — `@RgModule`, `@Injectable`, `@Inject`, `@IpcHandler`, `@WindowManager`.
+  - [Core Functions](#core-functions) — `initSettings`, `bootstrapModules`, `getWindow`, `destroyWindows`.
+  - [Lazy Loading modules](#lazy-loading-modules) — Deferred init behavior and constraints.
+  - [Lifecycle Interfaces](#lifecycle-interfaces) — IPC and window interface contracts.
+- [Best Practices](#best-practices) — Recommended development patterns.
+  - [Type Everything](#5-type-everything) — Type-safety guidance and tips.
+
 ## Overview
 
 A lightweight dependency injection container for Electron's main process that brings modular architecture and clean code organization to your desktop applications.
@@ -544,6 +572,7 @@ Defines a module with its dependencies and providers.
 - `ipc?: Class[]` - IPC handler classes
 - `windows?: Class[]` - Window manager classes
 - `exports?: Class[]` - Providers to export
+- `lazy?: { enabled: true; trigger: string }` - Defers module initialization until renderer invokes the trigger channel
 
 #### `@Injectable()`
 
@@ -643,6 +672,110 @@ Bootstraps all modules and initializes the DI container.
 await bootstrapModules([AppModule, AuthModule, ResourcesModule]);
 ```
 
+Lazy modules are registered but not initialized during bootstrap. Initialization happens on first `ipcRenderer.invoke(trigger)` from renderer process.
+
+```typescript
+@RgModule({
+  providers: [AnalyticsService],
+  ipc: [AnalyticsIpc],
+  lazy: {
+    enabled: true,
+    trigger: "analytics",
+  },
+})
+export class AnalyticsModule {}
+
+await bootstrapModules([UserModule, AnalyticsModule]);
+// UserModule: initialized immediately
+// AnalyticsModule: initialized on first ipcRenderer.invoke("analytics")
+```
+
+Notes:
+
+- Lazy loading defers runtime initialization work (provider resolution, module instantiation, IPC `onInit`).
+- It does not perform JavaScript code-splitting by itself; module code is still loaded by your app bundle strategy.
+- Each lazy trigger must be unique across modules in the same bootstrap call.
+
+### Lazy Loading modules
+
+Lazy Loading lets you defer module initialization until the renderer explicitly requests it via `ipcRenderer.invoke(trigger)`.
+
+Why it exists:
+
+- Reduces startup work in the main process for modules that are not needed immediately.
+- Improves perceived startup time when some features are rarely used.
+
+When to use it:
+
+- Heavy modules (database connections, expensive service wiring, feature-specific IPC setup).
+- Feature modules opened only after a user action (analytics, advanced settings, reports).
+
+When it usually does not help:
+
+- Modules required at application start (auth bootstrap, app shell wiring, core windows).
+- Very small modules where deferred initialization adds complexity without measurable gain.
+
+Important constraints:
+
+- A lazy module **cannot** declare `exports`.
+- A lazy module can import only eager modules.
+- An eager module cannot import a lazy module.
+
+These constraints guarantee clear module boundaries: lazy modules are activated explicitly, while shared cross-module dependencies stay eager and deterministic.
+
+#### Example: valid lazy module
+
+```typescript
+@RgModule({
+  imports: [DatabaseCoreModule], // eager module
+  providers: [AnalyticsService],
+  ipc: [AnalyticsIpc],
+  lazy: {
+    enabled: true,
+    trigger: "analytics:init",
+  },
+})
+export class AnalyticsModule {}
+
+await bootstrapModules([AppModule, AnalyticsModule]);
+
+// Renderer side:
+await ipcRenderer.invoke("analytics:init");
+```
+
+#### Example: invalid (lazy + exports)
+
+```typescript
+@RgModule({
+  providers: [AnalyticsService],
+  exports: [AnalyticsService], // ❌ not allowed for lazy modules
+  lazy: {
+    enabled: true,
+    trigger: "analytics:init",
+  },
+})
+export class AnalyticsModule {}
+```
+
+#### Example: invalid (eager imports lazy)
+
+```typescript
+@RgModule({
+  providers: [],
+  lazy: {
+    enabled: true,
+    trigger: "database:init",
+  },
+})
+export class DatabaseModule {}
+
+@RgModule({
+  imports: [DatabaseModule], // ❌ eager module cannot import lazy module
+  providers: [ReportsService],
+})
+export class ReportsModule {}
+```
+
 #### `getWindow<T>(hash)`
 
 Retrieves a window instance by its hash identifier.
@@ -784,6 +917,7 @@ Defines a module.
 - `ipc?: Class[]` - IPC handler classes
 - `windows?: Class[]` - Window manager classes
 - `exports?: Class[]` - Providers to export
+- `lazy?: { enabled: true; trigger: string }` - Defers module initialization until renderer invokes the trigger channel
 
 ### `@Injectable()`
 

package/dist/@core/bootstrap/bootstrap.js

@@ -1,14 +1,35 @@
-import { ModuleDecoratorMissingError } from "../errors/index.js";
+import { ModuleDecoratorMissingError, DuplicateLazyTriggerError, InvalidLazyTriggerError, } from "../errors/index.js";
 import { instantiateModule } from "./instantiate-module.js";
 import { initializeModule } from "./initialize-module.js";
 import { container } from "../container.js";
 import { initializeIpcHandlers } from "./initialize-ipc/handlers.js";
+import { registerLazyModule } from "./register-lazy-module.js";
+import { validateLazyConstraints } from "./validate-lazy-constraints.js";
+const getValidLazyTrigger = (moduleClass, metadata) => {
+    const trigger = metadata.lazy?.trigger;
+    if (typeof trigger !== "string" || trigger.trim().length === 0) {
+        throw new InvalidLazyTriggerError(moduleClass.name);
+    }
+    return trigger.trim();
+};
 export const bootstrapModules = async (modulesClass) => {
+    const lazyTriggerRegistry = new Map();
     for (const moduleClass of modulesClass) {
         const metadata = Reflect.getMetadata("RgModule", moduleClass);
         if (!metadata) {
             throw new ModuleDecoratorMissingError(moduleClass.name);
         }
+        validateLazyConstraints(moduleClass, metadata);
+        if (metadata.lazy?.enabled) {
+            const trigger = getValidLazyTrigger(moduleClass, metadata);
+            const existingModule = lazyTriggerRegistry.get(trigger);
+            if (existingModule) {
+                throw new DuplicateLazyTriggerError(trigger, existingModule, moduleClass.name);
+            }
+            lazyTriggerRegistry.set(trigger, moduleClass.name);
+            registerLazyModule(moduleClass, metadata);
+            continue;
+        }
         await initializeModule(moduleClass, metadata);
         await instantiateModule(moduleClass);
         await container.resolve(moduleClass, moduleClass);

package/dist/@core/bootstrap/initialize-ipc/handlers.js

@@ -41,7 +41,7 @@ export const initializeIpcHandlers = async (moduleClass, metadata) => {
     for (const ipcClass of metadata.ipc) {
         const ipcInstance = await container.resolve(moduleClass, ipcClass);
         if (ipcInstance?.onInit) {
-            ipcInstance.onInit({ getWindow });
+            await ipcInstance.onInit({ getWindow });
         }
     }
 };

package/dist/@core/bootstrap/initialize-module.js

@@ -3,7 +3,9 @@ import { registerProviders } from "./register-providers.js";
 import { registerImports } from "./register-imports.js";
 import { registerWindows } from "./register-windows.js";
 import { registerIpcHandlers } from "./register-ipc-handlers.js";
+import { validateLazyConstraints } from "./validate-lazy-constraints.js";
 export const initializeModule = async (moduleClass, metadata) => {
+    validateLazyConstraints(moduleClass, metadata);
     const isNewModule = container.addModule(moduleClass, metadata);
     container.setModuleMetadata(moduleClass, metadata);
     if (!isNewModule) {
@@ -11,7 +13,7 @@ export const initializeModule = async (moduleClass, metadata) => {
     }
     await Promise.all([
         registerProviders(moduleClass, metadata),
-        registerImports(metadata),
+        registerImports(moduleClass, metadata),
         registerWindows(moduleClass, metadata),
         registerIpcHandlers(moduleClass, metadata),
     ]);

package/dist/@core/bootstrap/register-imports.d.ts

@@ -1,2 +1,3 @@
 import type { RgModuleMetadata } from "../types/module-metadata.js";
-export declare const registerImports: (metadata: RgModuleMetadata) => Promise<void>;
+import type { Constructor } from "../types/constructor.js";
+export declare const registerImports: (moduleClass: Constructor, metadata: RgModuleMetadata) => Promise<void>;

package/dist/@core/bootstrap/register-imports.js

@@ -1,10 +1,14 @@
+import { EagerModuleCannotImportLazyModuleError } from "../errors/index.js";
 import { initializeModule } from "./initialize-module.js";
-export const registerImports = async (metadata) => {
+export const registerImports = async (moduleClass, metadata) => {
     if (!metadata.imports) {
         return;
     }
     for (const importedModuleClass of metadata.imports) {
         const importedModuleMetadata = Reflect.getMetadata("RgModule", importedModuleClass);
+        if (importedModuleMetadata?.lazy?.enabled && !metadata.lazy?.enabled) {
+            throw new EagerModuleCannotImportLazyModuleError(moduleClass.name, importedModuleClass.name);
+        }
         if (importedModuleMetadata) {
             await initializeModule(importedModuleClass, importedModuleMetadata);
         }

package/dist/@core/bootstrap/register-lazy-module.d.ts

@@ -0,0 +1,3 @@
+import type { RgModuleMetadata } from "../types/module-metadata.js";
+import type { Constructor } from "../types/constructor.js";
+export declare const registerLazyModule: (moduleClass: Constructor, metadata: RgModuleMetadata) => void;

package/dist/@core/bootstrap/register-lazy-module.js

@@ -0,0 +1,48 @@
+import { ipcMain } from "electron";
+import { initializeModule } from "./initialize-module.js";
+import { instantiateModule } from "./instantiate-module.js";
+import { container } from "../container.js";
+import { initializeIpcHandlers } from "./initialize-ipc/handlers.js";
+import { InvalidLazyTriggerError } from "../errors/index.js";
+const getValidLazyTrigger = (moduleClass, metadata) => {
+    const trigger = metadata.lazy?.trigger;
+    if (typeof trigger !== "string" || trigger.trim().length === 0) {
+        throw new InvalidLazyTriggerError(moduleClass.name);
+    }
+    return trigger.trim();
+};
+export const registerLazyModule = (moduleClass, metadata) => {
+    const trigger = getValidLazyTrigger(moduleClass, metadata);
+    let initPromise = null;
+    ipcMain.handle(trigger, async () => {
+        if (initPromise) {
+            return initPromise;
+        }
+        initPromise = (async () => {
+            try {
+                await initializeModule(moduleClass, metadata);
+                await instantiateModule(moduleClass);
+                await container.resolve(moduleClass, moduleClass);
+                if (metadata.windows?.length && !metadata.ipc?.length) {
+                    console.warn(`Warning: Window(s) declared in module "${moduleClass.name}" but no IPC handlers found to manage them.`);
+                }
+                await initializeIpcHandlers(moduleClass, metadata);
+                return {
+                    initialized: true,
+                    name: trigger,
+                };
+            }
+            catch (error) {
+                initPromise = null;
+                return {
+                    initialized: false,
+                    name: trigger,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+        })();
+        return initPromise;
+    });
+};

package/dist/@core/bootstrap/validate-lazy-constraints.d.ts

@@ -0,0 +1,3 @@
+import type { Constructor } from "../types/constructor.js";
+import type { RgModuleMetadata } from "../types/module-metadata.js";
+export declare const validateLazyConstraints: (moduleClass: Constructor, metadata: RgModuleMetadata) => void;

package/dist/@core/bootstrap/validate-lazy-constraints.js

@@ -0,0 +1,18 @@
+import { LazyModuleCannotImportLazyModuleError, LazyModuleExportsNotAllowedError, } from "../errors/index.js";
+export const validateLazyConstraints = (moduleClass, metadata) => {
+    if (!metadata.lazy?.enabled) {
+        return;
+    }
+    if ((metadata.exports?.length ?? 0) > 0) {
+        throw new LazyModuleExportsNotAllowedError(moduleClass.name);
+    }
+    if (!metadata.imports?.length) {
+        return;
+    }
+    for (const importedModuleClass of metadata.imports) {
+        const importedModuleMetadata = Reflect.getMetadata("RgModule", importedModuleClass);
+        if (importedModuleMetadata?.lazy?.enabled) {
+            throw new LazyModuleCannotImportLazyModuleError(moduleClass.name, importedModuleClass.name);
+        }
+    }
+};

package/dist/@core/errors/index.d.ts

@@ -16,4 +16,19 @@ export declare class InvalidProviderError extends BaseError {
 export declare class SettingsNotInitializedError extends BaseError {
     constructor();
 }
+export declare class InvalidLazyTriggerError extends BaseError {
+    constructor(moduleName: string);
+}
+export declare class DuplicateLazyTriggerError extends BaseError {
+    constructor(trigger: string, firstModule: string, secondModule: string);
+}
+export declare class LazyModuleExportsNotAllowedError extends BaseError {
+    constructor(moduleName: string);
+}
+export declare class LazyModuleCannotImportLazyModuleError extends BaseError {
+    constructor(moduleName: string, importedModuleName: string);
+}
+export declare class EagerModuleCannotImportLazyModuleError extends BaseError {
+    constructor(moduleName: string, importedModuleName: string);
+}
 export {};

package/dist/@core/errors/index.js

@@ -29,3 +29,28 @@ export class SettingsNotInitializedError extends BaseError {
         super("App settings cache has not been initialized.", "SettingsNotInitializedError");
     }
 }
+export class InvalidLazyTriggerError extends BaseError {
+    constructor(moduleName) {
+        super(`Invalid lazy trigger in module "${moduleName}". "lazy.trigger" must be a non-empty string.`, "InvalidLazyTriggerError");
+    }
+}
+export class DuplicateLazyTriggerError extends BaseError {
+    constructor(trigger, firstModule, secondModule) {
+        super(`Duplicate lazy trigger "${trigger}" detected in modules "${firstModule}" and "${secondModule}". Each lazy module must use a unique trigger.`, "DuplicateLazyTriggerError");
+    }
+}
+export class LazyModuleExportsNotAllowedError extends BaseError {
+    constructor(moduleName) {
+        super(`Invalid lazy module "${moduleName}". Lazy modules cannot declare exports.`, "LazyModuleExportsNotAllowedError");
+    }
+}
+export class LazyModuleCannotImportLazyModuleError extends BaseError {
+    constructor(moduleName, importedModuleName) {
+        super(`Invalid lazy module "${moduleName}". It cannot import lazy module "${importedModuleName}". Lazy modules can only import eager modules.`, "LazyModuleCannotImportLazyModuleError");
+    }
+}
+export class EagerModuleCannotImportLazyModuleError extends BaseError {
+    constructor(moduleName, importedModuleName) {
+        super(`Invalid eager module "${moduleName}". It cannot import lazy module "${importedModuleName}". Eager modules must import only eager modules.`, "EagerModuleCannotImportLazyModuleError");
+    }
+}

package/dist/@core/types/index.d.ts

@@ -5,3 +5,4 @@ export type { TProviderToken, TClassProvider, TFactoryProvider, TValueProvider,
 export type { TWindowFactory, TWindowCreate } from "./window-factory.js";
 export type { WindowManagerOptions, TWindowManagerWithHandlers, } from "./window-manager.js";
 export type { TMetadataWindow } from "./window-metadata.js";
+export type { TLazyConfig, TLazyModuleResponse } from "./lazy.js";

package/dist/@core/types/ipc-handler.d.ts

@@ -3,5 +3,5 @@ export type TParamOnInit<N = string> = {
     getWindow: (name?: N) => TWindowFactory;
 };
 export type TIpcHandlerInterface = {
-    onInit: (data: TParamOnInit) => void;
+    onInit?: (data: TParamOnInit) => void | Promise<void>;
 };

package/dist/@core/types/lazy.d.ts

@@ -0,0 +1,11 @@
+export type TLazyConfig = {
+    enabled: true;
+    trigger: string;
+};
+export type TLazyModuleResponse = {
+    initialized: boolean;
+    name: string;
+    error?: {
+        message: string;
+    };
+};

package/dist/@core/types/lazy.js

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

package/dist/@core/types/module-metadata.d.ts

@@ -1,10 +1,12 @@
 import type { TIpcHandlerInterface } from "./ipc-handler.js";
 import type { Constructor } from "./constructor.js";
 import type { TProvider, TProviderToken } from "./provider.js";
+import type { TLazyConfig } from "./lazy.js";
 export type RgModuleMetadata = {
     imports?: Constructor[];
     ipc?: (new (...args: any[]) => TIpcHandlerInterface)[];
     windows?: Constructor[];
     providers?: TProvider[];
     exports?: TProviderToken[];
+    lazy?: TLazyConfig;
 };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./@core/bootstrap/register-imports.js";
 export * from "./@core/bootstrap/register-ipc-handlers.js";
 export * from "./@core/bootstrap/register-providers.js";
 export * from "./@core/bootstrap/register-windows.js";
+export * from "./@core/bootstrap/register-lazy-module.js";
 export * from "./@core/bootstrap/settings.js";
 export * from "./@core/bootstrap/initialize-ipc/handlers.js";
 export * from "./@core/bootstrap/initialize-ipc/window-creator.js";

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./@core/bootstrap/register-imports.js";
 export * from "./@core/bootstrap/register-ipc-handlers.js";
 export * from "./@core/bootstrap/register-providers.js";
 export * from "./@core/bootstrap/register-windows.js";
+export * from "./@core/bootstrap/register-lazy-module.js";
 export * from "./@core/bootstrap/settings.js";
 export * from "./@core/bootstrap/initialize-ipc/handlers.js";
 export * from "./@core/bootstrap/initialize-ipc/window-creator.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devisfuture/electron-modular",
-  "version": "1.1.16",
+  "version": "1.2.16",
   "description": "Core module system, DI container, IPC handlers, and window utilities for Electron main process.",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,6 +41,7 @@
   "devDependencies": {
     "@types/node": "^20.11.0",
     "@vitest/coverage-v8": "^2.1.9",
+    "@vitest/ui": "^2.1.9",
     "electron": "^36.4.0",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"