@electrojs/runtime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Ryuben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# @electrojs/runtime
+
+The main-process runtime for Electro applications.
+
+`@electrojs/runtime` manages the full lifecycle of an Electron main process: scanning decorator metadata, building the module graph, wiring dependency injection, running lifecycle hooks, exposing a typed IPC bridge, dispatching signals, and scheduling background jobs. It is the layer between your application code and the Electron APIs.
+
+---
+
+## Installation
+
+```bash
+npm install @electrojs/runtime
+```
+
+> Peer dependency: `@electrojs/common` must be installed alongside.
+
+---
+
+## Quick start
+
+```ts
+import { Module, Injectable, command, query } from "@electrojs/common";
+import { AppKernel, createConsoleLogger } from "@electrojs/runtime";
+
+@Injectable()
+class GreetingService {
+    @query()
+    hello() {
+        return "world";
+    }
+
+    @command()
+    setLocale(locale: string) {
+        // ...
+    }
+}
+
+@Module({ providers: [GreetingService] })
+class AppModule {}
+
+const kernel = AppKernel.create(AppModule, {
+    logger: createConsoleLogger(),
+});
+await kernel.start();
+```
+
+`AppKernel.create` scans `AppModule`, validates the module graph, creates the DI container, instantiates module declarations, and runs startup lifecycle hooks. That single call is enough to bootstrap a working application.
+
+Modules, providers, windows, and views also receive `this.logger` through the authoring API, so app-level logs can use the same runtime logger contract and be redirected to a file, Sentry, or any other sink by passing a custom logger into `AppKernel.create(...)`.
+
+---
+
+## Modules
+
+Every feature lives inside a module. A module declares what it owns and what it shares:
+
+```ts
+@Module({
+    imports: [DatabaseModule],
+    providers: [UserService],
+    views: [UserView],
+    windows: [UserWindow],
+    exports: [UserService, UserWindow],
+})
+class UserModule {}
+```
+
+- **imports** -- modules this module depends on. Their exported declarations become available for injection.
+- **providers** -- service and infrastructure classes managed by this module.
+- **views** -- renderer view classes owned by this module.
+- **windows** -- window host classes owned by this module.
+- **exports** -- declarations shared with modules that import this one.
+
+The framework builds a directed acyclic graph from imports, detects cycles at startup, and instantiates modules in dependency-first (topological) order.
+
+---
+
+## Providers and dependency injection
+
+Providers are classes decorated with `@Injectable()`. They hold business logic, repositories, and infrastructure. Views and windows are declared separately in `@Module({ views, windows })`.
+
+Inject dependencies with the `inject()` function:
+
+```ts
+import { inject, Injector } from "@electrojs/runtime";
+
+@Injectable()
+class AuthService {
+    private readonly db = inject(DatabaseService);
+    private readonly config = inject(ConfigService);
+
+    @query()
+    getMe() {
+        return this.db.findUser(this.config.get("userId"));
+    }
+}
+```
+
+`inject()` works inside:
+
+- **Property initializers** -- during construction of framework-managed classes
+- **Lifecycle hooks** -- `onInit`, `onReady`, `onShutdown`, `onDispose`
+- **Capability handlers** -- methods decorated with `@command`, `@query`, `@signal`, `@job`
+
+Calling it outside these scopes throws a `DIError`.
+
+### Scopes
+
+- `singleton` (default) -- one instance per module injector
+- `transient` -- a new instance every time the token is resolved
+
+```ts
+@Injectable({ scope: "transient" })
+class RequestContext {}
+```
+
+---
+
+## Lifecycle hooks
+
+Modules and providers can implement lifecycle hooks to participate in startup and shutdown:
+
+```ts
+@Injectable()
+class DatabaseService {
+    async onInit() {
+        await this.pool.connect();
+    }
+
+    async onReady() {
+        await this.runMigrations();
+    }
+
+    async onShutdown() {
+        await this.pool.end();
+    }
+
+    onDispose() {
+        this.logger.flush();
+    }
+}
+```
+
+| Hook         | Phase    | Purpose                                              |
+| ------------ | -------- | ---------------------------------------------------- |
+| `onInit`     | Startup  | Set up resources (connections, state)                |
+| `onReady`    | Startup  | Cross-module coordination, everything is initialized |
+| `onShutdown` | Shutdown | Release resources gracefully                         |
+| `onDispose`  | Shutdown | Final cleanup (file handles, timers)                 |
+
+**Ordering:** Startup hooks run per-module in dependency-first order. Within each module, provider hooks run before the module's own hook. Shutdown runs in the reverse order -- module first, then its providers.
+
+If a startup hook throws, the framework automatically rolls back already-initialized modules by calling their shutdown hooks.
+
+---
+
+## Bridge (IPC)
+
+The bridge connects the main process to renderer views with typed channels. Decorate methods with `@command()` or `@query()` to expose them to the renderer:
+
+```ts
+@Injectable()
+class FileService {
+    @query()
+    async listFiles(directory: string): Promise<string[]> {
+        return fs.readdir(directory);
+    }
+
+    @command()
+    async deleteFile(path: string): Promise<void> {
+        await fs.unlink(path);
+    }
+}
+```
+
+- **Queries** are read-only operations -- they return data without side effects.
+- **Commands** perform mutations.
+
+Channel names are derived as `moduleId:methodName` (e.g. `file:listFiles`). Views declare which channels they can access:
+
+```ts
+@View({
+    source: "view:main",
+    access: ["file:listFiles", "file:deleteFile"],
+})
+class MainView extends ViewProvider {}
+```
+
+Calls from a view to channels not listed in `access` are rejected by the `BridgeAccessGuard`.
+
+---
+
+## Signals
+
+Signals provide fire-and-forget cross-module communication. Any provider can publish; any provider can subscribe.
+
+### Declarative handlers
+
+Use the `@signal()` decorator to subscribe a method at bootstrap time:
+
+```ts
+@Injectable()
+class NotificationService {
+    @signal({ id: "user-logged-in" })
+    onUserLogin(payload: { userId: string }) {
+        this.showWelcome(payload.userId);
+    }
+}
+```
+
+### Programmatic API
+
+Use `SignalBus` directly for runtime subscriptions:
+
+```ts
+@Injectable()
+class AuditService {
+    private readonly bus = inject(SignalBus);
+
+    onInit() {
+        this.bus.subscribe("user-logged-in", (payload) => {
+            this.log("login", payload);
+        });
+    }
+}
+```
+
+Publishing a signal:
+
+```ts
+this.bus.publish("user-logged-in", { userId: "42" });
+```
+
+Handlers run asynchronously via microtasks. Each handler retains the injection context from the point where it was subscribed, so `inject()` works correctly inside handlers.
+
+---
+
+## Jobs
+
+Jobs are background tasks that can run on a cron schedule or be triggered manually. Decorate a method with `@job()`:
+
+```ts
+@Injectable()
+class SyncService {
+    @job({ cron: "0 * * * *" })
+    async syncUsers(context: JobContext) {
+        const users = await this.fetchRemoteUsers();
+
+        for (const [i, user] of users.entries()) {
+            if (context.isCancelled) break;
+            context.reportProgress(((i + 1) / users.length) * 100);
+            await this.upsert(user);
+        }
+    }
+}
+```
+
+The first argument is always a `JobContext`, which provides:
+
+- `isCancelled` -- check whether the job was cancelled
+- `reportProgress(percent)` -- report 0-100 progress
+
+Jobs without a `cron` option are manual-only. Use `JobRegistry` to control them at runtime:
+
+```ts
+const jobs = inject(JobRegistry);
+await jobs.run("sync:syncUsers"); // trigger manually
+jobs.cancel("sync:syncUsers"); // cancel a running job
+const state = jobs.getState("sync:syncUsers"); // { status, progress, lastRunAt }
+```
+
+---
+
+## Desktop
+
+Windows and views are first-class providers. Extend the base classes `WindowProvider` and `ViewProvider` to manage Electron windows and their content.
+
+### Windows
+
+```ts
+@Window({ id: "main", configuration: { width: 1280, height: 800 } })
+class MainWindow extends WindowProvider {
+    private readonly mainView = inject(MainView);
+
+    onReady() {
+        this.create();
+        this.mount(this.mainView);
+        this.show();
+    }
+}
+```
+
+`WindowProvider` gives you: `create()`, `mount(view)`, `show()`, `hide()`, `focus()`, `close()`, `getBounds()`.
+
+### Views
+
+```ts
+@View({
+    source: "view:main",
+    access: ["file:listFiles", "file:deleteFile"],
+    signals: ["user-logged-in"],
+})
+class MainView extends ViewProvider {
+    async onReady() {
+        await this.load();
+        this.setBounds({ x: 0, y: 0, width: 1280, height: 800 });
+        this.setBackgroundColor("#00000000");
+    }
+}
+```
+
+`ViewProvider` gives you: `load()`, `setBounds(rect)`, `setBackgroundColor(color)`, `focus()`. Views are created with strict security defaults: `sandbox: true`, `contextIsolation: true`, `nodeIntegration: false`.
+
+---
+
+## Exports
+
+```ts
+// App
+import { AppKernel } from "@electrojs/runtime";
+
+// Container
+import { inject, InjectionContext, Injector } from "@electrojs/runtime";
+
+// Modules
+import { ModuleRef, ProviderRef, ModuleRegistry } from "@electrojs/runtime";
+import { scanModules, validateAppDefinition } from "@electrojs/runtime";
+
+// Signals
+import { SignalBus, SignalContext } from "@electrojs/runtime";
+
+// Jobs
+import { JobContext, JobRegistry } from "@electrojs/runtime";
+
+// Desktop
+import { WindowProvider, ViewProvider, WindowManager, ViewManager, RendererRegistry, RendererSession } from "@electrojs/runtime";
+
+// Bridge
+import { BridgeAccessGuard, BridgeDispatcher, BridgeHandler, serializeBridgeError } from "@electrojs/runtime";
+
+// Errors
+import { RuntimeError, BootstrapError, DIError, LifecycleError, BridgeError, SignalError, JobError } from "@electrojs/runtime";
+```
+
+Type-only imports:
+
+```ts
+import type {
+    AppDefinition,
+    ModuleDefinition,
+    ProviderDefinition,
+    ViewDefinition,
+    WindowDefinition,
+    BridgeMethodDefinition,
+    SignalHandlerDefinition,
+    JobDefinition,
+    KernelState,
+    ModuleStatus,
+    LifecycleTarget,
+    ModuleSnapshot,
+    ProviderSnapshot,
+    JobStatus,
+    JobRuntimeState,
+    BridgeRequest,
+    BridgeResponse,
+    SignalHandler,
+    SignalListener,
+    ContextualSignalHandler,
+    ProviderKind,
+    BridgeMethodKind,
+} from "@electrojs/runtime";
+```
+
+---
+
+## Package layering
+
+```txt
+@electrojs/common        ← decorators, metadata, DI primitives
+    ↑
+@electrojs/runtime       ← this package: DI container, lifecycle, bridge, signals, jobs, desktop
+    ↑
+@electrojs/renderer      ← renderer-side bridge client, signal subscriptions
+```
+
+`@electrojs/common` defines the shared vocabulary. `@electrojs/runtime` implements the main-process engine. `@electrojs/renderer` provides the renderer-side counterpart.

package/dist/client-CD3ueTol.mjs

@@ -0,0 +1 @@
+const e=`electro:bridge`,t=`electro:register`;function n(e){return new Promise(t=>setTimeout(t,e))}function r(r){let{viewId:a,ipcRenderer:o}=r,s=o.invoke(t,{viewId:a});async function c(t,n){let r=crypto.randomUUID();return await o.invoke(e,{callId:r,channel:t,args:n})}async function l(e,t){await s;for(let r=0;r<80;r+=1){let i=await c(e,t);if(i.error?.code!==`ELECTRO_BRIDGE_KERNEL_NOT_READY`||r===79)return i;await n(25)}return c(e,t)}return{async invoke(e,t){let n=await l(e,t);if(n.error){let e=Error(n.error.message);throw n.error.code&&(e.code=n.error.code),e}return n.result},subscribe(e,t){let n=(n,...r)=>{let i=r[0];i.signalId===e&&t(i.payload)};return o.on(i,n),()=>{o.removeListener(i,n)}},once(e,t){let n=!1,r=(a,...s)=>{let c=s[0];c.signalId===e&&!n&&(n=!0,o.removeListener(i,r),t(c.payload))};return o.on(i,r),()=>{n||(n=!0,o.removeListener(i,r))}}}}const i=`electro:signal`,a={bridge:e,register:t,signal:i};export{r as n,a as t};

package/dist/client-CVXQ55OB.d.mts

@@ -0,0 +1,62 @@
+//#region src/bridge/client.d.ts
+/**
+ * Creates the preload-side bridge client that connects renderer processes
+ * to the main process via Electron IPC.
+ *
+ * This function is called inside generated preload scripts. It returns an object
+ * matching the {@link RendererPreloadApi} contract expected by `@electrojs/renderer`:
+ * - `invoke(channel, payload)` — sends a bridge request to the main process
+ * - `subscribe(signalKey, listener)` — listens for signals forwarded from the main process
+ * - `once(signalKey, listener)` — like `subscribe`, but auto-removes after the first match
+ *
+ * On creation the client sends an `electro:register` message so the main process
+ * can create a {@link RendererSession} for this renderer's `webContentsId`.
+ *
+ * @example Generated preload script (produced by `@electrojs/codegen`):
+ * ```ts
+ * import { contextBridge, ipcRenderer } from "electron";
+ * import { createBridgeClient } from "@electrojs/runtime";
+ *
+ * contextBridge.exposeInMainWorld("__ELECTRO_RENDERER__", createBridgeClient({
+ *     viewId: "main",
+ *     ipcRenderer,
+ * }));
+ * ```
+ */
+/**
+ * Minimal subset of Electron's `IpcRenderer` used by the bridge client.
+ * Avoids importing the full Electron types at the package level.
+ */
+interface ElectroIpcRenderer {
+  invoke(channel: string, ...args: unknown[]): Promise<unknown>;
+  on(channel: string, listener: (event: unknown, ...args: unknown[]) => void): void;
+  removeListener(channel: string, listener: (event: unknown, ...args: unknown[]) => void): void;
+}
+/** Configuration accepted by {@link createBridgeClient}. */
+interface BridgeClientConfig {
+  /** The view ID this renderer is associated with (from `@View({ id })` or derived from source). */
+  readonly viewId: string;
+  /** Electron's `ipcRenderer` instance, available in preload scripts. */
+  readonly ipcRenderer: ElectroIpcRenderer;
+}
+/** The object exposed on `window.__ELECTRO_RENDERER__` for the renderer package to consume. */
+interface PreloadBridgeApi {
+  invoke(channel: string, payload: readonly unknown[]): Promise<unknown>;
+  subscribe(signalKey: string, listener: (payload: unknown) => void): () => void;
+  once(signalKey: string, listener: (payload: unknown) => void): () => void;
+}
+/**
+ * Create a bridge client for use in Electron preload scripts.
+ *
+ * The returned object is intended to be passed to
+ * `contextBridge.exposeInMainWorld("__ELECTRO_RENDERER__", ...)`.
+ */
+declare function createBridgeClient(config: BridgeClientConfig): PreloadBridgeApi;
+/** Well-known IPC channel names used by the Electro bridge protocol. */
+declare const IPC_CHANNELS: {
+  readonly bridge: "electro:bridge";
+  readonly register: "electro:register";
+  readonly signal: "electro:signal";
+};
+//#endregion
+export { createBridgeClient as a, PreloadBridgeApi as i, ElectroIpcRenderer as n, IPC_CHANNELS as r, BridgeClientConfig as t };

package/dist/client.d.mts

@@ -0,0 +1,2 @@
+import { a as createBridgeClient, i as PreloadBridgeApi, n as ElectroIpcRenderer, r as IPC_CHANNELS, t as BridgeClientConfig } from "./client-CVXQ55OB.mjs";
+export { type BridgeClientConfig, type ElectroIpcRenderer, IPC_CHANNELS, type PreloadBridgeApi, createBridgeClient };

package/dist/client.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./client-CD3ueTol.mjs";export{t as IPC_CHANNELS,e as createBridgeClient};