keryx 0.23.2 → 0.24.1

package/classes/API.ts

@@ -8,7 +8,7 @@ import {
   formatLoadedMessage,
 } from "../util/config";
 import { globLoader } from "../util/glob";
-import type { Initializer, InitializerSortKeys } from "./Initializer";
+import type { Initializer } from "./Initializer";
 import { Logger } from "./Logger";
 import { ErrorType, TypedError } from "./TypedError";
 
@@ -18,8 +18,6 @@ export enum RUN_MODE {
   SERVER = "server",
 }
 
-let flapPreventer = false;
-
 /**
  * The global singleton that manages the full framework lifecycle: initialize → start → stop.
  * All initializers attach their namespaces to this object (e.g., `api.db`, `api.actions`, `api.redis`).
@@ -42,8 +40,10 @@ export class API {
   logger: Logger;
   /** The current run mode (SERVER or CLI), set during `start()`. */
   runMode!: RUN_MODE;
-  /** All discovered initializer instances, sorted by the most-recently-used priority key. */
+  /** All discovered initializer instances, topologically sorted by `dependsOn` after discovery. */
   initializers: Initializer[];
+  /** Guards `restart()` against concurrent re-entry so rapid stop/start cycles get coalesced. */
+  private flapPreventer = false;
 
   // allow arbitrary properties to be set on the API, to be added and typed later
   [key: string]: any;
@@ -63,7 +63,7 @@ export class API {
 
   /**
    * Load configuration overrides and discover + run all initializers.
-   * Calls each initializer's `initialize()` method in `loadPriority` order.
+   * Calls each initializer's `initialize()` method in dependency order (topological sort of `dependsOn`).
    * The return value of each initializer is attached to `api[initializer.name]`.
    *
    * @throws {TypedError} With `ErrorType.SERVER_INITIALIZATION` if any initializer fails.
@@ -75,7 +75,8 @@ export class API {
     await this.loadLocalConfig();
     this.loadPluginConfig();
     await this.findInitializers();
-    this.sortInitializers("loadPriority");
+    this.topologicallySortInitializers();
+    this.logInitializerDag();
 
     for (const initializer of this.initializers) {
       try {
@@ -101,7 +102,7 @@ export class API {
   /**
    * Start the framework: connect to external services, bind server ports, start workers.
    * Calls `initialize()` first if it hasn't been run yet, then calls each initializer's
-   * `start()` method in `startPriority` order. Initializers whose `runModes` do not include
+   * `start()` method in dependency order. Initializers whose `runModes` do not include
    * the current `runMode` are skipped.
    *
    * @param runMode - Whether to start in SERVER mode (HTTP/WebSocket) or CLI mode.
@@ -117,8 +118,6 @@ export class API {
 
     this.logger.warn("--- 🔼  Starting process ---");
 
-    this.sortInitializers("startPriority");
-
     for (const initializer of this.initializers) {
       if (!initializer.runModes.includes(runMode)) {
         this.logger.debug(
@@ -148,7 +147,8 @@ export class API {
 
   /**
    * Gracefully shut down the framework: disconnect from services, close server ports, stop workers.
-   * Calls each initializer's `stop()` method in `stopPriority` order. No-ops if already stopped.
+   * Calls each initializer's `stop()` method in reverse dependency order (dependents stop before
+   * their dependencies). No-ops if already stopped.
    *
    * @throws {TypedError} With `ErrorType.SERVER_STOP` if any initializer fails to stop.
    */
@@ -160,9 +160,7 @@ export class API {
 
     this.logger.warn("--- 🔽  Stopping process ---");
 
-    this.sortInitializers("stopPriority");
-
-    for (const initializer of this.initializers) {
+    for (const initializer of [...this.initializers].reverse()) {
       try {
         this.logger.debug(`Stopping initializer ${initializer.name}`);
         await initializer.stop?.();
@@ -186,12 +184,12 @@ export class API {
    * concurrent restart calls to avoid rapid stop/start cycles.
    */
   async restart() {
-    if (flapPreventer) return;
+    if (this.flapPreventer) return;
 
-    flapPreventer = true;
+    this.flapPreventer = true;
     await this.stop();
     await this.start();
-    flapPreventer = false;
+    this.flapPreventer = false;
   }
 
   private async loadLocalConfig() {
@@ -228,6 +226,11 @@ export class API {
   }
 
   private async findInitializers() {
+    // Reset so that re-running `initialize()` (e.g. between test files that share
+    // the `globalThis.api` singleton) produces a deterministic graph rather than
+    // accumulating duplicates from previous runs.
+    this.initializers = [];
+
     // Load framework initializers from the package directory
     const frameworkInitializers = await globLoader<Initializer>(
       path.join(this.packageDir, "initializers"),
@@ -273,8 +276,108 @@ export class API {
     );
   }
 
-  private sortInitializers(key: InitializerSortKeys) {
-    this.initializers.sort((a, b) => a[key] - b[key]);
+  /**
+   * Reorder `this.initializers` into a topological execution order derived from each
+   * initializer's `dependsOn` list. Uses Kahn's algorithm with insertion-order tie-breaking
+   * so framework initializers keep their relative load order when they are mutually
+   * independent. Throws on missing dependencies or cycles — both indicate misconfiguration
+   * that would otherwise surface as confusing runtime errors.
+   *
+   * @throws {TypedError} With `ErrorType.INITIALIZER_VALIDATION` on unknown dependency
+   *   names or circular dependency chains.
+   */
+  private topologicallySortInitializers() {
+    const byName = new Map<string, Initializer>();
+    for (const i of this.initializers) byName.set(i.name, i);
+
+    // Validate dependency names exist before we try to sort.
+    for (const i of this.initializers) {
+      for (const dep of i.dependsOn) {
+        if (!byName.has(dep)) {
+          throw new TypedError({
+            type: ErrorType.INITIALIZER_VALIDATION,
+            message: `Initializer "${i.name}" depends on unknown initializer "${dep}". Available: ${[...byName.keys()].join(", ")}.`,
+          });
+        }
+      }
+    }
+
+    // Kahn's algorithm. `indegree[name]` = number of unresolved deps.
+    const indegree = new Map<string, number>();
+    for (const i of this.initializers) indegree.set(i.name, i.dependsOn.length);
+
+    // Reverse adjacency: for each dep, who depends on it?
+    const dependents = new Map<string, string[]>();
+    for (const i of this.initializers) {
+      for (const dep of i.dependsOn) {
+        const list = dependents.get(dep) ?? [];
+        list.push(i.name);
+        dependents.set(dep, list);
+      }
+    }
+
+    const sorted: Initializer[] = [];
+    // Seed the queue with zero-indegree initializers, preserving original insertion order.
+    const queue: Initializer[] = this.initializers.filter(
+      (i) => indegree.get(i.name) === 0,
+    );
+
+    while (queue.length > 0) {
+      const next = queue.shift()!;
+      sorted.push(next);
+      for (const dependentName of dependents.get(next.name) ?? []) {
+        const remaining = indegree.get(dependentName)! - 1;
+        indegree.set(dependentName, remaining);
+        if (remaining === 0) {
+          // Insert in original position to keep deterministic ordering.
+          const dependent = byName.get(dependentName)!;
+          // Keep queue ordered by original index among ready items.
+          const dependentIndex = this.initializers.indexOf(dependent);
+          let insertAt = queue.length;
+          for (let i = 0; i < queue.length; i++) {
+            if (this.initializers.indexOf(queue[i]) > dependentIndex) {
+              insertAt = i;
+              break;
+            }
+          }
+          queue.splice(insertAt, 0, dependent);
+        }
+      }
+    }
+
+    if (sorted.length !== this.initializers.length) {
+      const unresolved = this.initializers
+        .filter((i) => (indegree.get(i.name) ?? 0) > 0)
+        .map((i) => i.name);
+      throw new TypedError({
+        type: ErrorType.INITIALIZER_VALIDATION,
+        message: `Circular dependency detected among initializers: ${unresolved.join(" → ")}. Check each initializer's \`dependsOn\` list for a cycle.`,
+      });
+    }
+
+    this.initializers = sorted;
+  }
+
+  /**
+   * Render the resolved initializer dependency graph to the logs as a numbered list,
+   * one line per initializer, with each dependency shown to the right. Leaf initializers
+   * (no deps) render without an arrow.
+   */
+  private logInitializerDag() {
+    const longestName = this.initializers.reduce(
+      (max, i) => Math.max(max, i.name.length),
+      0,
+    );
+    const digits = String(this.initializers.length).length;
+
+    this.logger.debug("--- 🔗  Initializer dependency graph ---");
+    this.initializers.forEach((i, idx) => {
+      const num = String(idx + 1).padStart(digits, "0");
+      const name = i.name.padEnd(longestName);
+      const deps =
+        i.dependsOn.length > 0 ? `  ← ${i.dependsOn.join(", ")}` : "";
+      this.logger.debug(`  ${num}  ${name}${deps}`);
+    });
   }
 
   /**

package/classes/Initializer.ts

@@ -2,19 +2,19 @@ import { RUN_MODE } from "./../api";
 
 /**
  * Abstract base class for lifecycle components. Initializers are discovered automatically
- * and run in priority order during the framework's initialize → start → stop phases.
- * Each initializer typically extends the `API` interface via module augmentation and
- * returns its namespace object from `initialize()`.
+ * and run in topological order derived from `dependsOn` during the framework's
+ * `initialize → start → stop` phases. Each initializer typically extends the `API`
+ * interface via module augmentation and returns its namespace object from `initialize()`.
  */
 export abstract class Initializer {
   /** The unique name of this initializer (also used as the key on the `api` object). */
   name: string;
-  /** Priority order for `initialize()`. Lower values run first. Default: 1000; core initializers use < 1000. */
-  loadPriority: number;
-  /** Priority order for `start()`. Lower values run first. Default: 1000; core initializers use < 1000. */
-  startPriority: number;
-  /** Priority order for `stop()`. Lower values run first. Default: 1000; core initializers use < 1000. */
-  stopPriority: number;
+  /**
+   * Names of other initializers that must complete their `initialize()` and `start()`
+   * phases before this one runs. Also reverses for `stop()` — dependents shut down
+   * before their dependencies. Unknown names or cycles cause a startup error.
+   */
+  dependsOn: string[];
   /** Which run modes this initializer participates in. Defaults to both SERVER and CLI. */
   runModes: RUN_MODE[];
   /**
@@ -27,9 +27,7 @@ export abstract class Initializer {
 
   constructor(name: string) {
     this.name = name;
-    this.loadPriority = 1000;
-    this.startPriority = 1000;
-    this.stopPriority = 1000;
+    this.dependsOn = [];
     this.runModes = [RUN_MODE.SERVER, RUN_MODE.CLI];
     this.declaresAPIProperty = true;
   }
@@ -50,8 +48,3 @@ export abstract class Initializer {
    */
   async stop?(): Promise<any>;
 }
-
-export type InitializerSortKeys =
-  | "loadPriority"
-  | "startPriority"
-  | "stopPriority";

package/initializers/actionts.ts

@@ -71,7 +71,6 @@ export type TaskInputs = Record<string, any>;
 export class Actions extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 100;
   }
 
   /**

package/initializers/channels.ts

@@ -26,9 +26,7 @@ export class Channels extends Initializer {
 
   constructor() {
     super(namespace);
-    this.loadPriority = 100;
-    this.startPriority = 600;
-    this.stopPriority = 50;
+    this.dependsOn = ["redis", "pubsub"];
   }
 
   /**

package/initializers/connections.ts

@@ -12,7 +12,6 @@ declare module "../classes/API" {
 export class Connections extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 1;
   }
 
   async initialize() {

package/initializers/db.ts

@@ -24,9 +24,6 @@ declare module "../classes/API" {
 export class DB extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 100;
-    this.startPriority = 100;
-    this.stopPriority = 910;
   }
 
   async initialize() {

package/initializers/mcp.ts

@@ -31,9 +31,7 @@ declare module "../classes/API" {
 export class McpInitializer extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 200;
-    this.startPriority = 560;
-    this.stopPriority = 90;
+    this.dependsOn = ["actions", "oauth", "connections", "pubsub"];
   }
 
   async initialize() {

package/initializers/oauth.ts

@@ -36,8 +36,7 @@ declare module "../classes/API" {
 export class OAuthInitializer extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 175;
-    this.startPriority = 175;
+    this.dependsOn = ["redis", "actions"];
   }
 
   async initialize() {

package/initializers/observability.ts

@@ -28,9 +28,7 @@ declare module "../classes/API" {
 export class Observability extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 50;
-    this.startPriority = 50;
-    this.stopPriority = 50;
+    this.dependsOn = ["actions", "connections"];
   }
 
   async initialize() {

package/initializers/process.ts

@@ -13,7 +13,6 @@ declare module "../classes/API" {
 export class Process extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 2;
   }
 
   async initialize() {

package/initializers/pubsub.ts

@@ -33,8 +33,7 @@ declare module "../classes/API" {
 export class PubSub extends Initializer {
   constructor() {
     super(namespace);
-    this.startPriority = 150;
-    this.stopPriority = 950;
+    this.dependsOn = ["redis", "connections"];
   }
 
   async initialize() {

package/initializers/redis.ts

@@ -22,9 +22,6 @@ declare module "../classes/API" {
 export class Redis extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 200;
-    this.startPriority = 110;
-    this.stopPriority = 990;
   }
 
   async initialize() {

package/initializers/resque.ts

@@ -49,10 +49,7 @@ let SERVER_JOB_COUNTER = 1;
 export class Resque extends Initializer {
   constructor() {
     super(namespace);
-
-    this.loadPriority = 250;
-    this.startPriority = 10000;
-    this.stopPriority = 900;
+    this.dependsOn = ["redis", "actions", "process"];
   }
 
   /** Create and connect the resque `Queue` instance (used for enqueuing jobs). */

package/initializers/servers.ts

@@ -17,9 +17,7 @@ declare module "../classes/API" {
 export class Servers extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 800;
-    this.startPriority = 550;
-    this.stopPriority = 100;
+    this.dependsOn = ["actions"];
     this.runModes = [RUN_MODE.SERVER];
   }
 

package/initializers/session.ts

@@ -96,7 +96,7 @@ declare module "../classes/API" {
 export class Session extends Initializer {
   constructor() {
     super(namespace);
-    this.startPriority = 600;
+    this.dependsOn = ["redis"];
   }
 
   async initialize() {

package/initializers/signals.ts

@@ -14,7 +14,6 @@ declare module "../classes/API" {
 export class Signals extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 1;
   }
 
   async initialize() {

package/initializers/swagger.ts

@@ -19,7 +19,7 @@ declare module "../classes/API" {
 export class SwaggerInitializer extends Initializer {
   constructor() {
     super(namespace);
-    this.loadPriority = 150; // After actions (100)
+    this.dependsOn = ["actions"];
   }
 
   async initialize() {

package/package.json

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

package/testing/http.ts

@@ -0,0 +1,49 @@
+/**
+ * Default test user credentials. Matches the inline values used in the example
+ * backend tests prior to this helper.
+ */
+export const DEFAULT_TEST_USER = {
+  name: "Mario Mario",
+  email: "mario@example.com",
+  password: "mushroom1",
+} as const;
+
+/**
+ * Create a test user via HTTP PUT `/api/user`. Defaults to the Mario credentials
+ * used across example backend tests; override any field per call.
+ *
+ * Returns the raw `Response` so callers can assert on status and parse the body
+ * into whatever response type they need.
+ *
+ * @param url - Base server URL (from `useTestServer()`'s getter).
+ * @param overrides - Override any of `name`, `email`, `password`.
+ */
+export async function createTestUser(
+  url: string,
+  overrides?: Partial<{ name: string; email: string; password: string }>,
+): Promise<Response> {
+  return fetch(url + "/api/user", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ ...DEFAULT_TEST_USER, ...overrides }),
+  });
+}
+
+/**
+ * Log in as a test user via HTTP PUT `/api/session`. Pair with `createTestUser`.
+ * Returns the raw `Response`.
+ */
+export async function createTestSession(
+  url: string,
+  overrides?: Partial<{ email: string; password: string }>,
+): Promise<Response> {
+  return fetch(url + "/api/session", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      email: DEFAULT_TEST_USER.email,
+      password: DEFAULT_TEST_USER.password,
+      ...overrides,
+    }),
+  });
+}

package/testing/index.ts

@@ -2,6 +2,11 @@ import { afterAll, beforeAll } from "bun:test";
 import { api } from "../api";
 import type { WebServer } from "../servers/web";
 
+export {
+  createTestSession,
+  createTestUser,
+  DEFAULT_TEST_USER,
+} from "./http";
 export {
   buildWebSocket,
   createSession,