keryx 0.24.1 → 0.25.0

package/classes/API.ts

@@ -86,9 +86,9 @@ export class API {
         this.logger.debug(`Initialized initializer ${initializer.name}`);
       } catch (e) {
         throw new TypedError({
-          message: `${e}`,
+          message: `Failed to initialize initializer "${initializer.name}": ${e instanceof Error ? e.message : e}`,
           type: ErrorType.SERVER_INITIALIZATION,
-          originalError: e,
+          cause: e,
         });
       }
     }
@@ -132,9 +132,9 @@ export class API {
         this.logger.debug(`Started initializer ${initializer.name}`);
       } catch (e) {
         throw new TypedError({
-          message: `${e}`,
+          message: `Failed to start initializer "${initializer.name}": ${e instanceof Error ? e.message : e}`,
           type: ErrorType.SERVER_START,
-          originalError: e,
+          cause: e,
         });
       }
     }
@@ -167,9 +167,9 @@ export class API {
         this.logger.debug(`Stopped initializer ${initializer.name}`);
       } catch (e) {
         throw new TypedError({
-          message: `${e}`,
+          message: `Failed to stop initializer "${initializer.name}": ${e instanceof Error ? e.message : e}`,
           type: ErrorType.SERVER_STOP,
-          originalError: e,
+          cause: e,
         });
       }
     }

package/classes/Connection.ts

@@ -161,7 +161,7 @@ export class Connection<
           : new TypedError({
               message: `${e}`,
               type: ErrorType.CONNECTION_ACTION_RUN,
-              originalError: e,
+              cause: e,
             });
     } finally {
       if (action && formattedParams) {
@@ -337,7 +337,7 @@ export class Connection<
         throw new TypedError({
           message: `Error validating params: ${e}`,
           type: ErrorType.CONNECTION_ACTION_PARAM_VALIDATION,
-          originalError: e,
+          cause: e,
         });
       }
     }

package/classes/TypedError.ts

@@ -73,8 +73,11 @@ export type TypedErrorArgs = {
   message: string;
   /** The error category, which determines the HTTP status code. */
   type: ErrorType;
-  /** The original caught error, if wrapping. Its stack trace is preserved on the `TypedError`. */
-  originalError?: unknown;
+  /**
+   * The underlying error being wrapped. Exposed via the standard ES2022 `Error.cause`
+   * field, so `console.error(err)` prints the full "Caused by:" chain natively.
+   */
+  cause?: unknown;
   /** The param key that caused the error (for validation errors). */
   key?: string;
   /** The param value that caused the error (for validation errors). */
@@ -84,7 +87,9 @@ export type TypedErrorArgs = {
 /**
  * Structured error class for action and framework failures. Extends `Error` with an
  * `ErrorType` that maps to an HTTP status code, and optional `key`/`value` fields for
- * param validation errors. If `originalError` is provided, its stack trace is preserved.
+ * param validation errors. When `cause` is provided, it is forwarded to the base
+ * `Error` constructor so the native ES2022 cause chain is preserved — tooling that
+ * inspects errors (Node's default printer, debuggers) will walk both stacks.
  */
 export class TypedError extends Error {
   /** The error category, used to determine the HTTP status code via `ErrorStatusCodes`. */
@@ -95,17 +100,12 @@ export class TypedError extends Error {
   value?: any;
 
   constructor(args: TypedErrorArgs) {
-    super(args.message);
+    super(
+      args.message,
+      args.cause !== undefined ? { cause: args.cause } : undefined,
+    );
     this.type = args.type;
     this.key = args.key;
     this.value = args.value;
-
-    if (args.originalError !== undefined) {
-      if (args.originalError instanceof Error) {
-        this.stack = args.originalError.stack;
-      } else {
-        this.stack = `OriginalStringError: ${args.originalError}`;
-      }
-    }
   }
 }

package/initializers/channels.ts

@@ -12,6 +12,16 @@ const namespace = "channels";
 const PRESENCE_KEY_PREFIX = "presence:";
 const LUA_DIR = join(import.meta.dir, "..", "lua");
 
+const ADD_PRESENCE_LUA = await Bun.file(
+  join(LUA_DIR, "add-presence.lua"),
+).text();
+const REMOVE_PRESENCE_LUA = await Bun.file(
+  join(LUA_DIR, "remove-presence.lua"),
+).text();
+const REFRESH_PRESENCE_LUA = await Bun.file(
+  join(LUA_DIR, "refresh-presence.lua"),
+).text();
+
 declare module "../classes/API" {
   export interface API {
     [namespace]: Awaited<ReturnType<Channels["initialize"]>>;
@@ -19,9 +29,6 @@ declare module "../classes/API" {
 }
 
 export class Channels extends Initializer {
-  private addPresenceLua = "";
-  private removePresenceLua = "";
-  private refreshPresenceLua = "";
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor() {
@@ -107,7 +114,7 @@ export class Channels extends Initializer {
     const connectionSetKey = `${PRESENCE_KEY_PREFIX}${channelName}:${key}`;
 
     const added = await api.redis.redis.eval(
-      this.addPresenceLua,
+      ADD_PRESENCE_LUA,
       2,
       connectionSetKey,
       channelKey,
@@ -140,7 +147,7 @@ export class Channels extends Initializer {
     const connectionSetKey = `${PRESENCE_KEY_PREFIX}${channelName}:${key}`;
 
     const shouldLeave = await api.redis.redis.eval(
-      this.removePresenceLua,
+      REMOVE_PRESENCE_LUA,
       2,
       connectionSetKey,
       channelKey,
@@ -190,7 +197,7 @@ export class Channels extends Initializer {
 
     const keys = [...keysToRefresh];
     await api.redis.redis.eval(
-      this.refreshPresenceLua,
+      REFRESH_PRESENCE_LUA,
       keys.length,
       ...keys,
       config.channels.presenceTTL,
@@ -218,16 +225,6 @@ export class Channels extends Initializer {
   };
 
   async initialize() {
-    this.addPresenceLua = await Bun.file(
-      join(LUA_DIR, "add-presence.lua"),
-    ).text();
-    this.removePresenceLua = await Bun.file(
-      join(LUA_DIR, "remove-presence.lua"),
-    ).text();
-    this.refreshPresenceLua = await Bun.file(
-      join(LUA_DIR, "refresh-presence.lua"),
-    ).text();
-
     // Load plugin channels
     const pluginChannels: Channel[] = [];
     for (const plugin of config.plugins) {

package/initializers/db.ts

@@ -11,7 +11,10 @@ import { api, logger } from "../api";
 import { Initializer } from "../classes/Initializer";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
-import { formatConnectionStringForLogging } from "../util/connectionString";
+import {
+  formatConnectionStringForLogging,
+  throwConnectionError,
+} from "../util/connectionString";
 
 const namespace = "db";
 
@@ -59,10 +62,7 @@ export class DB extends Initializer {
     try {
       await api.db.db.execute(sql`SELECT NOW()`);
     } catch (e) {
-      throw new TypedError({
-        type: ErrorType.SERVER_INITIALIZATION,
-        message: `Cannot connect to database (${formatConnectionStringForLogging(config.database.connectionString)}): ${e}`,
-      });
+      throwConnectionError("database", config.database.connectionString, e);
     }
 
     if (config.database.autoMigrate) {

package/initializers/redis.ts

@@ -1,9 +1,11 @@
 import { Redis as RedisClient } from "ioredis";
 import { api, logger } from "../api";
 import { Initializer } from "../classes/Initializer";
-import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
-import { formatConnectionStringForLogging } from "../util/connectionString";
+import {
+  formatConnectionStringForLogging,
+  throwConnectionError,
+} from "../util/connectionString";
 
 const namespace = "redis";
 const testKey = `__keryx_test_key:${config.process.name}`;
@@ -42,10 +44,7 @@ export class Redis extends Initializer {
       await api.redis.subscription.set(testKey, Date.now());
       await api.redis.subscription.del(testKey);
     } catch (e) {
-      throw new TypedError({
-        type: ErrorType.SERVER_INITIALIZATION,
-        message: `Cannot connect to redis (${formatConnectionStringForLogging(config.redis.connectionString)}): ${e}`,
-      });
+      throwConnectionError("redis", config.redis.connectionString, e);
     }
 
     logger.info(

package/package.json

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

package/util/connectionString.ts

@@ -1,6 +1,20 @@
+import { ErrorType, TypedError } from "../classes/TypedError";
+
 /** Strip the password from a connection string for safe logging. Preserves protocol, user, host, port, and path. */
 export function formatConnectionStringForLogging(connectionString: string) {
   const connectionStringParsed = new URL(connectionString);
   const connectionStringInfo = `${connectionStringParsed.protocol ? `${connectionStringParsed.protocol}//` : ""}${connectionStringParsed.username ? `${connectionStringParsed.username}@` : ""}${connectionStringParsed.hostname}:${connectionStringParsed.port}${connectionStringParsed.pathname}`;
   return connectionStringInfo;
 }
+
+/** Throw a standardized `SERVER_INITIALIZATION` error for a failed connection probe. The connection string is password-stripped via {@link formatConnectionStringForLogging} before being embedded in the message. */
+export function throwConnectionError(
+  service: string,
+  connectionString: string,
+  error: unknown,
+): never {
+  throw new TypedError({
+    type: ErrorType.SERVER_INITIALIZATION,
+    message: `Cannot connect to ${service} (${formatConnectionStringForLogging(connectionString)}): ${error}`,
+  });
+}

package/util/glob.ts

@@ -38,7 +38,7 @@ export async function globLoader<T>(searchDir: string) {
           throw new TypedError({
             message: `Error loading from ${dir} -  ${name} - ${error}`,
             type: ErrorType.SERVER_INITIALIZATION,
-            originalError: error,
+            cause: error,
           });
         }
       }

package/util/transaction.ts

@@ -73,7 +73,7 @@ export async function withTransaction<T>(
     throw new TypedError({
       message: `${e}`,
       type: ErrorType.CONNECTION_ACTION_RUN,
-      originalError: e,
+      cause: e,
     });
   } finally {
     client.release();

package/util/webRouting.ts

@@ -77,7 +77,7 @@ export async function parseRequestParams(
       throw new TypedError({
         message: `cannot parse request body: ${e}`,
         type: ErrorType.CONNECTION_ACTION_RUN,
-        originalError: e,
+        cause: e,
       });
     }
   } else if (

package/util/webSocket.ts

@@ -122,7 +122,7 @@ export async function handleWebsocketSubscribe(
         : new TypedError({
             message: `${e}`,
             type: ErrorType.CONNECTION_CHANNEL_AUTHORIZATION,
-            originalError: e,
+            cause: e,
           });
     ws.send(
       JSON.stringify({
@@ -174,7 +174,7 @@ export async function handleWebsocketUnsubscribe(
         : new TypedError({
             message: `${e}`,
             type: ErrorType.CONNECTION_CHANNEL_VALIDATION,
-            originalError: e,
+            cause: e,
           });
     ws.send(
       JSON.stringify({