keryx 0.21.6 → 0.21.7

package/classes/API.ts

@@ -92,6 +92,8 @@ export class API {
       }
     }
 
+    this.validateInitializerProperties("initialize");
+
     this.initialized = true;
     this.logger.warn("--- 🔄  Initializing complete ---");
   }
@@ -138,6 +140,8 @@ export class API {
       }
     }
 
+    this.validateInitializerProperties("start");
+
     this.started = true;
     this.logger.warn("--- 🔼  Starting complete ---");
   }
@@ -272,4 +276,37 @@ export class API {
   private sortInitializers(key: InitializerSortKeys) {
     this.initializers.sort((a, b) => a[key] - b[key]);
   }
+
+  /**
+   * Assert that every initializer which claims an API namespace (via
+   * `declaresAPIProperty`) has actually attached `api[initializer.name]`.
+   * Closes the silent-drift gap between TypeScript module augmentation
+   * and runtime property assignment — a missing namespace becomes a fast,
+   * loud startup failure instead of a confusing `Cannot read property of
+   * undefined` deep inside a request handler.
+   *
+   * Initializers excluded from the current `runMode` are skipped during the
+   * `start` phase since their `start()` method never ran.
+   */
+  private validateInitializerProperties(phase: "initialize" | "start") {
+    const missing: string[] = [];
+    for (const initializer of this.initializers) {
+      if (initializer.declaresAPIProperty === false) continue;
+      if (phase === "start" && !initializer.runModes.includes(this.runMode)) {
+        continue;
+      }
+      if (this[initializer.name] == null) {
+        missing.push(initializer.name);
+      }
+    }
+    if (missing.length > 0) {
+      throw new TypedError({
+        type: ErrorType.INITIALIZER_VALIDATION,
+        message:
+          `Initializers did not attach their namespace to api after the ${phase} phase: ` +
+          `${missing.join(", ")}. Each initializer must either return a namespace object ` +
+          `from initialize() (and/or populate it in start()), or set declaresAPIProperty = false.`,
+      });
+    }
+  }
 }

package/classes/Initializer.ts

@@ -17,6 +17,13 @@ export abstract class Initializer {
   stopPriority: number;
   /** Which run modes this initializer participates in. Defaults to both SERVER and CLI. */
   runModes: RUN_MODE[];
+  /**
+   * Whether this initializer attaches a property named `this.name` on the `api` singleton.
+   * Runtime validation in `API.initialize()` and `API.start()` will fail if the declared
+   * property is missing. Default: `true`. Set to `false` for initializers that intentionally
+   * don't augment the `API` interface.
+   */
+  declaresAPIProperty: boolean;
 
   constructor(name: string) {
     this.name = name;
@@ -24,6 +31,7 @@ export abstract class Initializer {
     this.startPriority = 1000;
     this.stopPriority = 1000;
     this.runModes = [RUN_MODE.SERVER, RUN_MODE.CLI];
+    this.declaresAPIProperty = true;
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.21.6",
+  "version": "0.21.7",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",