@thi.ng/system 2.1.95 → 2.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-01-29T21:04:46Z
+- **Last updated**: 2024-01-30T15:21:30Z
 - **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.
 
+## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/system@2.2.0) (2024-01-30)
+
+#### 🚀 Features
+
+- update start/stop logic ([71f2dc5](https://github.com/thi-ng/umbrella/commit/71f2dc5))
+  - update System.start() to stop already started components if current
+  component startup failed
+  - update System.stop() to only return true if _all_ components did shutdown
+  - update docs
+  - add tests
+
 ### [2.1.80](https://github.com/thi-ng/umbrella/tree/@thi.ng/system@2.1.80) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -33,6 +33,9 @@ Inspired by Stuart Sierra's
 [component](https://github.com/stuartsierra/component) framework for
 Clojure/ClojureScript.
 
+Uses a declarative approach to define system components with a simple [lifecycle
+API](https://docs.thi.ng/umbrella/system/interfaces/ILifecycle.html).
+
 ## Status
 
 **STABLE** - used in production
@@ -59,7 +62,7 @@ For Node.js REPL:
 const system = await import("@thi.ng/system");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 490 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 539 bytes
 
 ## Dependencies
 

package/api.d.ts

@@ -2,22 +2,26 @@ import type { Fn, Keys } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 export interface ILifecycle {
     /**
-     * Starts component. Defined as async method to simplify internal
-     * use of `await` for starting any child/sub-components. Usually
-     * called by {@link System.start} which synchronously starts all of
-     * its components in dependency order.
+     * Starts component. Defined as async method to simplify internal use of
+     * `await` for starting any child/sub-components. Usually called by
+     * {@link System.start} which synchronously starts all of its components in
+     * dependency order.
      *
-     * Returns false to indicate component startup failed and to cancel
-     * initialization of dependent components. Alternatively, an error
-     * can be thrown, but it's the user's responsibility to catch it.
+     * Returns false to indicate component startup failed and to cancel startup
+     * of any further components. Alternatively, an error can be thrown, but
+     * it's the user's responsibility to catch it.
+     *
+     * If a component's start method returns false, any already started
+     * components will be stopped (see {@link ILifecycle.stop}) in reverse
+     * order.
      */
     start?(): Promise<boolean>;
     /**
      * Similar to {@link ILifecycle.start} but for stopping components.
      *
-     * Returns false to indicate component startup failed and log a
-     * warning message to the console. Unlike with `start()`, returning
-     * false will NOT stop decommision other components.
+     * Returns false to indicate component shutdown failed. Unlike with
+     * {@link ILifecycle.start}, returning false will **not** stop the shutdown
+     * of other components.
      */
     stop?(): Promise<boolean>;
     [id: string]: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/system",
-  "version": "2.1.95",
+  "version": "2.2.0",
   "description": "Minimal and explicit dependency-injection & lifecycle container for stateful app components",
   "type": "module",
   "module": "./index.js",
@@ -38,9 +38,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.20",
-    "@thi.ng/dgraph": "^2.1.91",
-    "@thi.ng/logger": "^2.1.6"
+    "@thi.ng/api": "^8.9.21",
+    "@thi.ng/dgraph": "^2.1.92",
+    "@thi.ng/logger": "^2.1.7"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.39.0",
@@ -84,5 +84,5 @@
   "thi.ng": {
     "year": 2020
   },
-  "gitHead": "3fa30b2dc2de762f24fd64b881b68d4da33d4c38\n"
+  "gitHead": "ded7c5e87ebc7f6279c24f183c24ff348db8f304\n"
 }

package/system.d.ts

@@ -1,6 +1,11 @@
 import type { Keys } from "@thi.ng/api";
 import { DGraph } from "@thi.ng/dgraph";
 import { type ILifecycle, type SystemMap, type SystemSpecs } from "./api.js";
+/**
+ * Syntax sugar for {@link System} constructor.
+ *
+ * @param map
+ */
 export declare const defSystem: <T extends SystemMap<T>>(map: SystemSpecs<T>) => System<T>;
 export declare class System<T extends SystemMap<T>> implements ILifecycle {
     components: T;
@@ -8,12 +13,14 @@ export declare class System<T extends SystemMap<T>> implements ILifecycle {
     graph: DGraph<Keys<T>>;
     constructor(map: SystemSpecs<T>);
     /**
-     * Initializes all system components in dependency order. If any
-     * component's `start()` method returns false, system start up will
-     * be stopped and this method returns false itself.
+     * Initializes all system components in dependency order. If any component's
+     * `start()` method returns false, system start up will be stopped, any
+     * already started components will be stopped (in reverse order) and this
+     * method returns false itself.
      *
-     * Also any errors thrown during child component startup will not be
-     * intercepted.
+     * @remarks
+     * Any errors thrown during child component startup (or shutdown) will
+     * **not** be intercepted.
      */
     start(): Promise<boolean>;
     /**
@@ -27,8 +34,17 @@ export declare class System<T extends SystemMap<T>> implements ILifecycle {
      */
     stop(): Promise<boolean>;
     /**
-     * Syntax sugar for `stop() && start()` sequence.
+     * Syntax sugar for `stop() && start()` sequence. The restart phase will
+     * only be executed if **all** components could be stopped successfully.
      */
     reset(): Promise<boolean>;
+    /**
+     * Calls {@link ILifecycle.stop} on the `n` first items in given topo array
+     * (in reverse order).
+     *
+     * @param topo
+     * @param n
+     */
+    protected __stop(topo: Keys<T>[], n?: number): Promise<boolean>;
 }
 //# sourceMappingURL=system.d.ts.map

package/system.js

@@ -20,18 +20,23 @@ class System {
     }
   }
   /**
-   * Initializes all system components in dependency order. If any
-   * component's `start()` method returns false, system start up will
-   * be stopped and this method returns false itself.
+   * Initializes all system components in dependency order. If any component's
+   * `start()` method returns false, system start up will be stopped, any
+   * already started components will be stopped (in reverse order) and this
+   * method returns false itself.
    *
-   * Also any errors thrown during child component startup will not be
-   * intercepted.
+   * @remarks
+   * Any errors thrown during child component startup (or shutdown) will
+   * **not** be intercepted.
    */
   async start() {
-    for (let id of this.topology) {
+    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()) {
         LOGGER.warn(`error starting component: ${String(id)}`);
+        await this.__stop(topo, i);
         return false;
       }
     }
@@ -47,21 +52,33 @@ class System {
    * intercepted.
    */
   async stop() {
-    const topo = this.topology;
-    for (let i = topo.length; i-- > 0; ) {
+    return this.__stop(this.topology);
+  }
+  /**
+   * Syntax sugar for `stop() && start()` sequence. The restart phase will
+   * only be executed if **all** components could be stopped successfully.
+   */
+  async reset() {
+    return await this.stop() && await this.start();
+  }
+  /**
+   * Calls {@link ILifecycle.stop} on the `n` first items in given topo array
+   * (in reverse order).
+   *
+   * @param topo
+   * @param n
+   */
+  async __stop(topo, n = topo.length) {
+    let result = true;
+    for (let i = n; i-- > 0; ) {
       const id = topo[i];
       const comp = this.components[id];
       if (comp.stop && !await comp.stop()) {
         LOGGER.warn(`error stopping component: ${String(id)}`);
+        result = false;
       }
     }
-    return true;
-  }
-  /**
-   * Syntax sugar for `stop() && start()` sequence.
-   */
-  async reset() {
-    return await this.stop() && await this.start();
+    return result;
   }
 }
 export {