@thi.ng/system 2.2.1 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-01-30T21:37:19Z
+- **Last updated**: 2024-02-01T13:52:02Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,24 @@ 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
+
+- update ILifecycle, add system arg ([89d341a](https://github.com/thi-ng/umbrella/commit/89d341a))
+  - add/update tests
+
 ## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/system@2.2.0) (2024-01-30)
 
 #### 🚀 Features

package/README.md

@@ -62,7 +62,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
 
@@ -78,7 +78,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 +152,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 +176,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 +198,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 +208,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

@@ -1,6 +1,7 @@
 import type { Fn, Keys } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-export interface ILifecycle {
+import type { System } from "./system.js";
+export interface ILifecycle<T extends SystemMap<T> = any> {
     /**
      * Starts component. Defined as async method to simplify internal use of
      * `await` for starting any child/sub-components. Usually called by
@@ -15,7 +16,7 @@ export interface ILifecycle {
      * components will be stopped (see {@link ILifecycle.stop}) in reverse
      * order.
      */
-    start?(): Promise<boolean>;
+    start?(sys: System<T>): Promise<boolean>;
     /**
      * Similar to {@link ILifecycle.start} but for stopping components.
      *
@@ -23,7 +24,7 @@ export interface ILifecycle {
      * {@link ILifecycle.start}, returning false will **not** stop the shutdown
      * of other components.
      */
-    stop?(): Promise<boolean>;
+    stop?(sys: System<T>): Promise<boolean>;
     [id: string]: any;
 }
 /**
@@ -32,11 +33,19 @@ export interface ILifecycle {
  */
 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.2.1",
+  "version": "3.0.0",
   "description": "Minimal and explicit dependency-injection & lifecycle container for stateful app components",
   "type": "module",
   "module": "./index.js",
@@ -84,5 +84,5 @@
   "thi.ng": {
     "year": 2020
   },
-  "gitHead": "a86521dfac00768f7e51a607209325eb72004730\n"
+  "gitHead": "2137e8a24ecea66997b53032fec96e73fa0d0e02\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 class System<T extends SystemMap<T>> implements ILifecycle {
+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,11 +39,13 @@ 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];
       const comp = this.components[id];
-      if (comp.start && !await comp.start()) {
+      if (comp.start && !await comp.start(this)) {
         LOGGER.warn(`error starting component: ${String(id)}`);
         await this.__stop(topo, i);
         return false;
@@ -73,7 +84,7 @@ class System {
     for (let i = n; i-- > 0; ) {
       const id = topo[i];
       const comp = this.components[id];
-      if (comp.stop && !await comp.stop()) {
+      if (comp.stop && !await comp.stop(this)) {
         LOGGER.warn(`error stopping component: ${String(id)}`);
         result = false;
       }