@thi.ng/system 2.3.0 → 3.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-01-31T12:41:36Z
+- **Last updated**: 2024-02-06T23:18:11Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,17 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/system@3.0.0) (2024-02-01)
+
+#### 🛑 Breaking changes
+
+- Async component factories ([998409d](https://github.com/thi-ng/umbrella/commit/998409d))
+- BREAKING CHANGE: Component factory functions are async now
+  - add async System.init()
+  - update System ctor
+  - add/update docs
+  - update tests
+
 ## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/system@2.3.0) (2024-01-31)
 
 #### 🚀 Features

package/README.md

@@ -19,6 +19,7 @@
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
   - [Example system](#example-system)
   - [System visualization](#system-visualization)
@@ -62,7 +63,7 @@ For Node.js REPL:
 const system = await import("@thi.ng/system");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 539 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 570 bytes
 
 ## Dependencies
 
@@ -70,6 +71,16 @@ Package sizes (brotli'd, pre-treeshake): ESM: 539 bytes
 - [@thi.ng/dgraph](https://github.com/thi-ng/umbrella/tree/develop/packages/dgraph)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 
+## Usage examples
+
+One project in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory is using this package:
+
+| Screenshot                                                                                                                | Description                                                                    | Live demo                                                | Source                                                                                |
+|:--------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------|:---------------------------------------------------------|:--------------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rstream-system-bus.png" width="240"/> | Declarative component-based system with central rstream-based pubsub event bus | [Demo](https://demo.thi.ng/umbrella/rstream-system-bus/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rstream-system-bus) |
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/system/)
@@ -78,7 +89,7 @@ TODO
 
 ### Example system
 
-```ts
+```ts tangle:export/readme.ts
 import { defSystem, ILifecycle } from "@thi.ng/system";
 
 // Step 1: Define the structure / components of your system
@@ -152,16 +163,16 @@ class Cache implements ILifecycle {
 
 const FOO = defSystem<FooSys>({
     db: {
-        factory: (deps) => new DB(deps.logger, deps.state),
-        deps: ["logger", "state"],
+        factory: async (deps) => new DB(deps.logger, deps.cache),
+        deps: ["logger", "cache"],
     },
-    logger: { factory: () => new Logger() },
+    logger: { factory: async () => new Logger() },
     cache: {
-        factory: ({ logger }) => new Cache(logger),
+        factory: async ({ logger }) => new Cache(logger),
         deps: ["logger"],
     },
     dummy: {
-        factory: ({ logger }) => ({
+        factory: async ({ logger }) => ({
             async start() {
                 logger.info("start dummy");
                 return true;
@@ -176,21 +187,21 @@ const FOO = defSystem<FooSys>({
 });
 
 // Step 4: Asynchronously start all components in dependency order
-FOO.start();
+await FOO.start();
 // [info] start logger
 // [info] start cache
 // [info] start dummy
 // [info] start db
 
 // Step 5 (optional): Async shutdown all (in reverse order)
-FOO.stop();
+await FOO.stop();
 // [info] stop db
 // [info] stop dummy
 // [info] stop cache
 // [info] stop logger
 
-// Calls stop() & if successful followed by start()
-FOO.reset();
+// Alternatively, calls stop() & if successful followed by start()
+await FOO.reset();
 ```
 
 ### System visualization
@@ -198,7 +209,9 @@ FOO.reset();
 For a `System` to initialize its components in the correct order, an internal
 [dependency
 graph](https://github.com/thi-ng/umbrella/tree/develop/packages/dgraph) is
-constructed. This graph is not required any further after system construction,
+constructed. This graph is not required any further after system initialization
+(see
+[System.init()](https://docs.thi.ng/umbrella/system/classes/System.html#init)),
 though can be useful for debugging and documentation purposes.
 
 For example, we can utilize the
@@ -206,18 +219,18 @@ For example, we can utilize the
 package to generate a [Graphviz](https://graphviz.org) source file to visualize
 the dependencies between the system's components.
 
-```ts
+```ts tangle:export/readme.ts
 import { toDot } from "@thi.ng/dgraph-dot";
 
 console.log(toDot(FOO.graph, { id: (node) => node }));
 // digraph g {
 // "db"[label="db"];
 // "logger"[label="logger"];
-// "state"[label="state"];
+// "cache"[label="cache"];
 // "dummy"[label="dummy"];
 // "db" -> "logger";
-// "db" -> "state";
-// "state" -> "logger";
+// "db" -> "cache";
+// "cache" -> "logger";
 // "dummy" -> "logger";
 // }
 ```

package/api.d.ts

@@ -33,11 +33,19 @@ export interface ILifecycle<T extends SystemMap<T> = any> {
  */
 export type SystemMap<T> = Record<Keys<T>, ILifecycle>;
 /**
- * Component initialization function.
+ * Async system component initialization function.
  */
-export type ComponentFactory<T extends SystemMap<T>> = Fn<T, ILifecycle>;
+export type ComponentFactory<T extends SystemMap<T>> = Fn<T, Promise<ILifecycle>>;
 export interface SystemSpec<T extends SystemMap<T>> {
+    /**
+     * Async system component initialization function.
+     */
     factory: ComponentFactory<T>;
+    /**
+     * Component IDs which this component directly depends on. Used to construct
+     * the system's dependency graph and to initialize (and later start)
+     * components in the correct order.
+     */
     deps?: Keys<T>[];
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/system",
-  "version": "2.3.0",
+  "version": "3.0.1",
   "description": "Minimal and explicit dependency-injection & lifecycle container for stateful app components",
   "type": "module",
   "module": "./index.js",
@@ -39,8 +39,8 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.9.22",
-    "@thi.ng/dgraph": "^2.1.93",
-    "@thi.ng/logger": "^2.1.8"
+    "@thi.ng/dgraph": "^2.1.94",
+    "@thi.ng/logger": "^2.1.9"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.39.0",
@@ -84,5 +84,5 @@
   "thi.ng": {
     "year": 2020
   },
-  "gitHead": "0edcb19135b9d56983e44541b949a057ee11b683\n"
+  "gitHead": "ce8202c237a367c4038d41919a8acf75e1122507\n"
 }

package/system.d.ts

@@ -4,14 +4,21 @@ import { type ILifecycle, type SystemMap, type SystemSpecs } from "./api.js";
 /**
  * Syntax sugar for {@link System} constructor.
  *
- * @param map
+ * @param specs
  */
-export declare const defSystem: <T extends SystemMap<T>>(map: SystemSpecs<T>) => System<T>;
+export declare const defSystem: <T extends SystemMap<T>>(specs: SystemSpecs<T>) => System<T>;
 export declare class System<T extends SystemMap<T>> implements ILifecycle<T> {
+    protected specs: SystemSpecs<T>;
     components: T;
     topology: Keys<T>[];
     graph: DGraph<Keys<T>>;
-    constructor(map: SystemSpecs<T>);
+    constructor(specs: SystemSpecs<T>);
+    /**
+     * Builds the system component dependency graph and initializes all
+     * components using their async {@link SystemSpec.factory} functions.
+     * Returns the initialized system.
+     */
+    init(): Promise<this>;
     /**
      * Initializes all system components in dependency order. If any component's
      * `start()` method returns false, system start up will be stopped, any

package/system.js

@@ -2,22 +2,31 @@ import { DGraph } from "@thi.ng/dgraph";
 import {
   LOGGER
 } from "./api.js";
-const defSystem = (map) => new System(map);
+const defSystem = (specs) => new System(specs);
 class System {
+  constructor(specs) {
+    this.specs = specs;
+  }
   components;
   topology;
   graph;
-  constructor(map) {
+  /**
+   * Builds the system component dependency graph and initializes all
+   * components using their async {@link SystemSpec.factory} functions.
+   * Returns the initialized system.
+   */
+  async init() {
     this.graph = new DGraph();
-    for (let id in map) {
-      const deps = map[id].deps;
+    for (let id in this.specs) {
+      const deps = this.specs[id].deps;
       deps ? this.graph.addDependencies(id, deps) : this.graph.addNode(id);
     }
     this.topology = this.graph.sort();
     this.components = {};
     for (let id of this.topology) {
-      this.components[id] = map[id].factory(this.components);
+      this.components[id] = await this.specs[id].factory(this.components);
     }
+    return this;
   }
   /**
    * Initializes all system components in dependency order. If any component's
@@ -30,6 +39,8 @@ class System {
    * **not** be intercepted.
    */
   async start() {
+    if (!this.graph)
+      await this.init();
     const topo = this.topology;
     for (let i = 0; i < topo.length; i++) {
       const id = topo[i];