ee-core 5.0.0-beta.8 → 5.0.0

package/README.md

@@ -4,7 +4,7 @@ Enterprise-grade Electron application framework core — TypeScript edition with
 
 ## Overview
 
-`ee-core` provides the runtime foundation for [electron-egg](https://github.com/wallace5303/electron-egg) applications. It handles the complete lifecycle from boot to shutdown: configuration loading, controller registration, IPC communication, window management, logging, storage, background jobs, and cross-process coordination.
+`ee-core` is the runtime foundation for [electron-egg](https://github.com/wallace5303/electron-egg) applications. It handles the complete lifecycle from boot to shutdown: configuration loading, controller registration, IPC communication, window management, logging, storage, background jobs, and cross-process coordination.
 
 The package outputs dual module formats (CJS + ESM) via conditional exports in `package.json`, making it compatible with both `require()` and `import` environments.
 
@@ -19,13 +19,13 @@ npm install ee-core
 ee-core exposes fine-grained subpath modules. Each can be imported individually:
 
 ```ts
-// Main entry (boot, app, config, etc.)
+// Main entry (boot, app, config, events, etc.)
 import { ElectronEgg } from 'ee-core';
 
 // Specific submodules
 import { ControllerLoader } from 'ee-core/controller';
 import { Cross, cross } from 'ee-core/cross';
-import { extend } from 'ee-core/utils';
+import { extend, is } from 'ee-core/utils';
 import { SqliteStorage } from 'ee-core/storage';
 import { ChildJob, ChildPoolJob, LoadBalancer } from 'ee-core/jobs';
 import type { Config, DevConfig } from 'ee-core/types';
@@ -35,51 +35,88 @@ Available subpaths:
 
 | Subpath | Description |
 |---|---|
-| `ee-core` | Main entry — boot, application, config, events |
-| `ee-core/app` | Application lifecycle and event bus |
+| `ee-core` | Main entry — boot, application, config, events, all modules |
+| `ee-core/app` | Application lifecycle, event bus, directory init |
 | `ee-core/config` | Configuration loading and merging |
+| `ee-core/const` | IPC channel and event constants |
 | `ee-core/controller` | Controller loader and registry |
-| `ee-core/core` | FileLoader and core utilities |
-| `ee-core/cross` | IPC communication (socket.io, HTTP, Electron IPC) |
+| `ee-core/core` | FileLoader, Timing, core utilities |
+| `ee-core/cross` | External process management (Go/Python backends) |
 | `ee-core/electron` | Electron app/window management |
-| `ee-core/exception` | Exception handling |
-| `ee-core/html` | HTML static resource path utility |
+| `ee-core/exception` | Global exception handling (uncaught/unhandled) |
+| `ee-core/html` | Static HTML page path utility (failure pages) |
 | `ee-core/jobs` | Background jobs (ChildJob, ChildPoolJob, LoadBalancer) |
 | `ee-core/loader` | File/module loading utilities |
-| `ee-core/log` | Pino-based logging (pino-roll + pino-pretty) |
-| `ee-core/message` | IPC message routing |
-| `ee-core/ps` | Process/environment utilities (paths, env detection) |
-| `ee-core/socket` | Socket.IO, HTTP, IPC servers |
+| `ee-core/log` | Pino logging (pino-roll + pino-pretty) |
+| `ee-core/message` | Child process IPC message routing |
+| `ee-core/ps` | Process state, environment detection, path utilities |
+| `ee-core/socket` | Socket.IO, HTTP (Koa), IPC servers |
 | `ee-core/storage` | SQLite storage (better-sqlite3) |
 | `ee-core/types` | TypeScript type definitions |
-| `ee-core/utils` | extend, is, json, helper, pargv, port |
+| `ee-core/utils` | extend, is, json, wrap, helper, pargv, port, ip |
 
 ## Architecture
 
 ### Lifecycle
 
-Boot → loadConfig → loadLog → loadDir → loadController → loadSocket → loadElectron
+The `ElectronEgg` startup sequence is strictly ordered:
+
+```
+init() → loadException → loadConfig → loadDir → loadLog
+run() → loadController → loadSocket → emitLifecycle(Ready) → loadElectron
+```
+
+Exception handling must register first to catch subsequent errors; config is the foundation for all modules; directories must exist before writing logs; controllers precede communication services; Ready fires after core modules are loaded; Electron starts last.
+
+### Lifecycle Events
+
+Five framework milestones managed by `EventBus`:
+
+| Event | When |
+|---|---|
+| `Ready` | Core modules loaded, before Electron |
+| `ElectronAppReady` | `app.whenReady()` completed |
+| `WindowReady` | BrowserWindow created |
+| `BeforeClose` | Window close triggered |
+| `Preload` | Preload scripts executing |
+
+Register handlers via `app.register(eventName, handler)` or custom events via `eventBus.on()/emit()`.
 
 ### Controller Loading Pipeline
 
-- **Build time** (ee-bin): `controllerRegistryPlugin` scans `electron/controller/`, generates `ee-core:controller-registry` virtual module with lazy getters.
-- **Runtime** (ee-core): If `globalThis.__EE_CONTROLLER_REGISTRY__` exists (bundle mode), loads from registry. Otherwise falls back to filesystem scanning via globby.
+- **Build time** (ee-bin): `bundleRegistryPlugin` scans `electron/controller/`, computes property paths (`defaultCamelize` with `caseStyle: 'lower'`), generates `app:controller-registry` virtual module setting `global.__EE_CONTROLLER_REGISTRY__` with lazy getters (`get module() { return require(...) }`).
+- **Bundle entry** (`app:bundle-entry`): loads config registry → controller registry → real `main.js`.
+- **Runtime** (ee-core): If `globalThis.__EE_CONTROLLER_REGISTRY__` exists (bundle mode), `FileLoader.parseFromRegistry()` reads from it. Otherwise, falls back to filesystem scanning via `scanDirSync()`.
+
+### Configuration Loading Pipeline
+
+Same dual-mode pattern as controllers:
+
+- **Build time** (ee-bin): `bundleRegistryPlugin` scans `electron/config/`, generates `app:config-registry` virtual module.
+- **Runtime** (ee-core): If `globalThis.__EE_CONFIG_REGISTRY__` exists, `ConfigLoader._loadConfig()` loads by filename. Otherwise, reads from filesystem using `loadFile()`.
 
-### IPC Communication
+Config layering (dev mode only): `config.default.js` → `config.local.js` / `config.prod.js`, merged by `ConfigLoader`.
 
-Main ↔ renderer via `ee-core/cross`, supporting three transport modes:
-- Socket.IO (bidirectional real-time)
-- HTTP server (RESTful)
-- Electron IPC (native)
+### Communication Services
 
-Channels follow pattern `controller/{name}/{method}`.
+Three channels created in order during `loadSocket()`:
+
+| Server | Use Case | Implementation |
+|---|---|---|
+| `SocketServer` | Third-party process communication (Go/Python) | Socket.IO |
+| `HttpServer` | RESTful API for external HTTP clients | Koa + middleware |
+| `IpcServer` | Main ↔ renderer process | `ipcMain.handle/on` + `ipcRenderer.invoke/send` |
+
+All share `resolveControllerFn()` routing — channel pattern: `controller/{name}/{method}`.
 
 ### Window Loading Strategy
 
-- Remote mode → Load remote URL
-- Dev mode → Wait for frontend dev server, show loading page first
-- Prod + cross takeover → Wait for cross-process service
-- Prod (default) → Load local HTML file
+`loadServer()` selects strategy based on config and environment:
+
+1. **Remote mode** (`remote.enable=true`) → Load remote URL
+2. **Dev mode** → Poll frontend dev server (`waitForUrl`), show loading page first
+3. **Prod + cross takeover** → Wait for cross-process service to be ready
+4. **Prod (default)** → Load local HTML file
 
 ## Key APIs
 
@@ -89,7 +126,10 @@ Channels follow pattern `controller/{name}/{method}`.
 import { ElectronEgg } from 'ee-core';
 
 // Start the framework
-const app = new ElectronEgg();
+const boot = new ElectronEgg();
+
+// Async startup (ESM)
+await boot.runAsync();
 ```
 
 ### Configuration
@@ -98,32 +138,83 @@ const app = new ElectronEgg();
 import { getConfig, setConfig } from 'ee-core/config';
 
 const config = getConfig();
+
+// Child processes can receive config without filesystem access
+setConfig(config);
 ```
 
 ### Controller
 
 ```ts
-import { getController } from 'ee-core/controller';
+import { getController, getControllers } from 'ee-core/controller';
 
+// Get specific controller
 const userController = getController('user');
+
+// Get all loaded controllers
+const all = getControllers();
 ```
 
 ### Cross-Process Communication
 
 ```ts
 import { cross } from 'ee-core/cross';
+import type { CrossTargetConfig } from 'ee-core';
+
+// Run Go backend with custom config
+const opt: CrossTargetConfig = {
+  name: 'goapp',
+  cmd: path.join(getExtraResourcesDir(), 'goapp'),
+  directory: getExtraResourcesDir(),
+  args: ['--port=7073'],
+  appExit: true,
+};
+const entity = await cross.run('go', opt);
+
+// Get service URL
+const url = cross.getUrl('goapp');
+
+// Kill by name
+cross.killByName('goapp');
+```
+
+### Communication Servers
 
-// Send IPC message to renderer
-cross.sendToRenderer('controller/user/info', data);
+```ts
+import { getSocketServer, getHttpServer, getIpcServer } from 'ee-core/socket';
+
+// All getters return non-null instances after Ready event
+const socket = getSocketServer();
+const http = getHttpServer();
+const ipc = getIpcServer();
+```
+
+### Main Window
+
+```ts
+import { getMainWindow } from 'ee-core/electron';
+
+// Returns BrowserWindow (non-null) after WindowReady event
+const win = getMainWindow();
+win.setMenuBarVisibility(false);
 ```
 
 ### Jobs
 
 ```ts
-import { ChildJob, ChildPoolJob, LoadBalancer } from 'ee-core/jobs';
+import { ChildJob, ChildPoolJob, LoadBalancer, AlgorithmType } from 'ee-core/jobs';
 
+// Single task execution
 const job = new ChildJob();
-const result = await job.exec({ name: 'task', script: './jobs/demo.js' });
+const result = await job.exec('./jobs/demo.js', { taskName: 'cleanup' });
+
+// Process pool with load balancing
+const pool = new ChildPoolJob();
+pool.create(3); // Create 3 workers
+const result = await pool.run('./jobs/demo.js', { taskName: 'batch' });
+
+// 8 algorithms: polling, weights, random, specify, weightsPolling,
+// weightsRandom, minimumConnection, weightsMinimumConnection
 ```
 
 ### Storage
@@ -131,28 +222,99 @@ const result = await job.exec({ name: 'task', script: './jobs/demo.js' });
 ```ts
 import { SqliteStorage } from 'ee-core/storage';
 
-const db = new SqliteStorage('./data/app.db');
-db.prepare('CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY, name TEXT)').run();
+// Four modes: memory, onlyName, relative, absolute
+const db = new SqliteStorage({ mode: 'onlyName', name: 'app' });
 ```
 
 ### Logging
 
 ```ts
-import { coreLogger, getLoggers } from 'ee-core/log';
+import { logger, coreLogger } from 'ee-core/log';
+
+// Supports three call styles: pino standard, pino printf, concatenation
+logger.info('Application started');
+logger.info('User %s logged in', 'admin');
+logger.info('data:', { id: 1, name: 'test' });
 
-coreLogger.info('Application started');
+// Log files: ee.log, ee-core.log, ee-error.log
+// Rotation: daily/hourly via pino-roll
+// Dev mode: pino-pretty for terminal output
 ```
 
 ### Process/Environment
 
 ```ts
-import { isDev, getBaseDir, env } from 'ee-core/ps';
+import { isDev, isProd, getBaseDir, getDataDir, getLogDir } from 'ee-core/ps';
+import { is } from 'ee-core/utils';
 
 if (isDev()) {
   // Development-specific logic
 }
+
+// Platform detection
+if (is.macOS()) { /* macOS */ }
+if (is.windows()) { /* Windows */ }
+if (is.linux()) { /* Linux */ }
+if (is.openharmony()) { /* OpenHarmony */ }
+
+// Path utilities
+const baseDir = getBaseDir();
+const dataDir = getDataDir();
+const logDir = getLogDir();
+const extraRes = getExtraResourcesDir();
+```
+
+### Event Bus
+
+```ts
+import { eventBus, BeforeClose } from 'ee-core/app';
+
+// Register lifecycle hook
+app.register(BeforeClose, async () => {
+  // Cleanup before app closes
+});
+
+// Custom events
+eventBus.on('myEvent', (data) => { /* handle */ });
+eventBus.emit('myEvent', { key: 'value' });
+```
+
+### Exception Handling
+
+```ts
+// Auto-registered during boot. Controls exit behavior:
+// exception.mainExit / childExit / rendererExit
+// Errors logged via coreLogger, dev mode sends to terminal
+```
+
+### Utility Functions
+
+```ts
+import { extend, strictParse, getPort, parseArgv, sleep } from 'ee-core/utils';
+
+// Deep merge with prototype pollution guard
+const merged = extend(true, {}, defaults, userConfig);
+
+// Port allocation with two-level locking
+const port = await getPort({ port: 7070 });
+
+// CLI argument parser
+const args = parseArgv(process.argv);
+
+// Sync sleep (Atomics.wait-based, no subprocess)
+sleep(1000);
 ```
 
+## TypeScript Types
+
+All types are exported from `ee-core/types`:
+
+```ts
+import type { Config, CrossTargetConfig, DevConfig, AppInfo } from 'ee-core/types';
+```
+
+Key type interfaces: `ElectronEggOptions`, `Config`, `AppInfo`, `CrossTargetConfig`, `CrossRunOptions`, `LoggerConfig`, `ExceptionConfig`, `FileLoaderOptions`, `LoadBalancerOptions`, `JobProcessOptions`, `MessageData`.
+
 ## Build
 
 ```bash
@@ -161,10 +323,21 @@ npm run build:cjs      # Build CommonJS only
 npm run build:esm      # Build ESM only
 npm run typecheck      # TypeScript type checking
 npm run test           # Run vitest
+npm run test:watch     # Run vitest in watch mode
 ```
 
 The `exports` map in `package.json` is auto-generated by `scripts/gen-exports.js`. Do not edit manually — run `npm run gen-exports` after adding new subpath modules.
 
+## Debug Logging
+
+ee-core uses the `debug` library for verbose namespace-scoped logging. Enable to see runtime internals (config merging, controller loading, module resolution):
+
+```bash
+DEBUG=ee-* node your-app            # All ee-* namespaces
+DEBUG=ee-core:config:* node your-app  # Config subsystem only
+DEBUG=ee-core:controller:* node your-app  # Controller loading only
+```
+
 ## Requirements
 
 - Node.js >= 20.19.0
@@ -174,5 +347,6 @@ The `exports` map in `package.json` is auto-generated by `scripts/gen-exports.js
 ## Notes
 
 - ESM imports in ee-core source must include `.js` extensions (required by `module: NodeNext`)
-- ee-core is NOT bundled into the Electron main process bundle — it's an esbuild external loaded from `node_modules` at runtime
-- The framework uses the `debug` library for verbose logging. Enable with `DEBUG=ee-*` environment variable
+- ee-core is NOT bundled into the Electron main process bundle — it's an esbuild external loaded from `node_modules` at runtime. This allows `child_process.fork()` to find `app.js` as a real disk file
+- `getMainWindow()`, `getSocketServer()`, `getHttpServer()`, `getIpcServer()` return non-null instances. If called before the corresponding lifecycle event, they throw an Error indicating a lifecycle ordering bug
+- The `exports` map is auto-generated — run `npm run gen-exports` after adding new modules

package/dist/cjs/jobs/child/jobProcess.js

@@ -55,7 +55,7 @@ class JobProcess {
             processOptions: {
                 cwd,
                 env: (0, index_js_2.allEnv)(),
-                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc']
             },
         };
         const options = (0, extend_js_1.extend)(true, defaultOptions, opt);

package/dist/esm/jobs/child/jobProcess.js

@@ -55,7 +55,7 @@ class JobProcess {
             processOptions: {
                 cwd,
                 env: (0, index_js_2.allEnv)(),
-                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc']
             },
         };
         const options = (0, extend_js_1.extend)(true, defaultOptions, opt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ee-core",
-  "version": "5.0.0-beta.8",
+  "version": "5.0.0",
   "description": "ee core - TypeScript edition with dual module support",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",