@zudojs/core 0.1.0 → 1.1.0

package/dist/logging/console/loggerFactory.factory.d.ts

@@ -16,8 +16,13 @@ export interface LoggerFactoryOptions extends LoggerOptions {
      * Logger implementation to use.
      *
      * Defaults to "console".
+     *
+     * The type is deliberately widened to accept arbitrary
+     * strings because this value frequently arrives from
+     * configuration files; unknown implementations fail with a
+     * descriptive error at creation time.
      */
-    readonly implementation?: LoggerImplementation;
+    readonly implementation?: LoggerImplementation | (string & {});
 }
 /**
  * Creates and configures Zudojs logger instances.
@@ -37,9 +42,5 @@ export declare class LoggerFactory {
      * module-specific or operation-specific context.
      */
     child(logger: Logger, context: LoggerContext): Logger;
-    /**
-     * Handles unsupported logger implementations.
-     */
-    private unsupportedImplementation;
 }
 //# sourceMappingURL=loggerFactory.factory.d.ts.map

package/dist/logging/console/loggerFactory.factory.js

@@ -15,7 +15,7 @@ export class LoggerFactory {
             case "console":
                 return new ConsoleLogger(options, context);
             default:
-                return this.unsupportedImplementation(implementation);
+                throw new Error(`Unsupported logger implementation: ${String(implementation)}`);
         }
     }
     /**
@@ -27,11 +27,5 @@ export class LoggerFactory {
     child(logger, context) {
         return logger.child(context);
     }
-    /**
-     * Handles unsupported logger implementations.
-     */
-    unsupportedImplementation(implementation) {
-        throw new Error(`Unsupported logger implementation: ${String(implementation)}`);
-    }
 }
 //# sourceMappingURL=loggerFactory.factory.js.map

package/dist/logging/core/index.d.ts

@@ -4,8 +4,9 @@
  * Core logger types, levels, entries, context, and options.
  */
 export { BaseLogger, type Logger, type LogContext } from "./logger.js";
-export { LogLevel, LogLevelPriority, shouldLog, type LogLevel as LogLevelType, } from "./logLevel.level.js";
-export { createLoggerContext, type LoggerContext, } from "./loggerContext.context.js";
-export { serializeLogError, type LogEntry, type LogError, } from "./logEntry.entry.js";
+export { LogLevel, LogLevelPriority, DEFAULT_LOG_LEVEL, shouldLog, isLogLevel, resolveLogLevel, type LogLevel as LogLevelType, } from "./logLevel.level.js";
+export { createLoggerContext, loggerContextFromExecution, type LoggerContext, } from "./loggerContext.context.js";
+export { serializeLogError, sanitizeLogValue, safeLogStringify, type LogEntry, type LogError, type LogErrorSerializationOptions, } from "./logEntry.entry.js";
+export { createLogRedactor, type LogRedactionHook, type LogRedactorOptions, } from "./logRedaction.redaction.js";
 export { DEFAULT_LOGGER_OPTIONS, type LoggerOptions, type LogLevelOption, } from "./loggerOptions.options.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/logging/core/index.js

@@ -4,8 +4,9 @@
  * Core logger types, levels, entries, context, and options.
  */
 export { BaseLogger } from "./logger.js";
-export { LogLevel, LogLevelPriority, shouldLog, } from "./logLevel.level.js";
-export { createLoggerContext, } from "./loggerContext.context.js";
-export { serializeLogError, } from "./logEntry.entry.js";
+export { LogLevel, LogLevelPriority, DEFAULT_LOG_LEVEL, shouldLog, isLogLevel, resolveLogLevel, } from "./logLevel.level.js";
+export { createLoggerContext, loggerContextFromExecution, } from "./loggerContext.context.js";
+export { serializeLogError, sanitizeLogValue, safeLogStringify, } from "./logEntry.entry.js";
+export { createLogRedactor, } from "./logRedaction.redaction.js";
 export { DEFAULT_LOGGER_OPTIONS, } from "./loggerOptions.options.js";
 //# sourceMappingURL=index.js.map

package/dist/logging/core/logEntry.entry.d.ts

@@ -1,5 +1,6 @@
 import type { LogLevel } from "./logLevel.level.js";
 import type { LoggerContext } from "./loggerContext.context.js";
+import type { LogContext } from "./logger.js";
 /**
  * Represents a single structured log entry.
  *
@@ -21,9 +22,12 @@ export interface LogEntry {
      */
     readonly timestamp: Date;
     /**
-     * Structured framework context.
+     * Structured context attached to the entry.
+     *
+     * Either well-known framework context fields (LoggerContext)
+     * or arbitrary structured metadata supplied by the caller.
      */
-    readonly context?: LoggerContext;
+    readonly context?: LoggerContext | LogContext;
     /**
      * Error associated with the log event.
      */
@@ -58,6 +62,16 @@ export interface LogError {
      */
     readonly cause?: unknown;
 }
+/**
+ * Options controlling error serialization.
+ */
+export interface LogErrorSerializationOptions {
+    /**
+     * Redaction hook applied to the sanitized details of every
+     * error in the cause chain.
+     */
+    readonly redact?: (value: unknown) => unknown;
+}
 /**
  * Creates a structured LogError from an unknown thrown value.
  *
@@ -68,6 +82,30 @@ export interface LogError {
  * Strings
  * Objects
  * Unknown thrown values
+ *
+ * Nested causes are serialized recursively up to a bounded
+ * depth, and details pass through the safe sanitizer (and the
+ * optional redaction hook) so circular references and BigInt
+ * values cannot crash logging and secrets do not leak.
+ */
+export declare function serializeLogError(error: unknown, options?: LogErrorSerializationOptions): LogError;
+/**
+ * Converts an arbitrary value into a JSON-safe structure.
+ *
+ * Handles the cases that break JSON.stringify:
+ *
+ * circular references → "[Circular]"
+ * BigInt              → decimal string
+ * throwing toJSON     → "[Unserializable]"
+ * functions           → "[Function name]"
+ * symbols             → their string description
+ */
+export declare function sanitizeLogValue(value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
+/**
+ * Safely serializes an arbitrary value to a JSON string.
+ *
+ * Never throws: values that resist serialization degrade to
+ * placeholder strings.
  */
-export declare function serializeLogError(error: unknown): LogError;
+export declare function safeLogStringify(value: unknown): string;
 //# sourceMappingURL=logEntry.entry.d.ts.map

package/dist/logging/core/logEntry.entry.js

@@ -1,3 +1,7 @@
+/**
+ * Maximum depth to which nested error causes are serialized.
+ */
+const MAX_ERROR_CAUSE_DEPTH = 5;
 /**
  * Creates a structured LogError from an unknown thrown value.
  *
@@ -8,8 +12,20 @@
  * Strings
  * Objects
  * Unknown thrown values
+ *
+ * Nested causes are serialized recursively up to a bounded
+ * depth, and details pass through the safe sanitizer (and the
+ * optional redaction hook) so circular references and BigInt
+ * values cannot crash logging and secrets do not leak.
  */
-export function serializeLogError(error) {
+export function serializeLogError(error, options = {}) {
+    return serializeLogErrorAtDepth(error, options, 0);
+}
+function serializeDetails(value, options) {
+    const sanitized = sanitizeLogValue(value);
+    return options.redact ? options.redact(sanitized) : sanitized;
+}
+function serializeLogErrorAtDepth(error, options, depth) {
     if (error instanceof Error) {
         const candidate = error;
         return {
@@ -17,8 +33,14 @@ export function serializeLogError(error) {
             message: candidate.message,
             stack: candidate.stack,
             code: candidate.code,
-            details: candidate.details,
-            cause: candidate.cause,
+            details: candidate.details !== undefined
+                ? serializeDetails(candidate.details, options)
+                : undefined,
+            cause: candidate.cause !== undefined
+                ? depth < MAX_ERROR_CAUSE_DEPTH
+                    ? serializeLogErrorAtDepth(candidate.cause, options, depth + 1)
+                    : "[MaxDepth]"
+                : undefined,
         };
     }
     if (typeof error === "string") {
@@ -28,11 +50,110 @@ export function serializeLogError(error) {
     }
     if (error !== null && typeof error === "object") {
         return {
-            details: error,
+            details: serializeDetails(error, options),
         };
     }
     return {
         message: String(error),
     };
 }
+/**
+ * Maximum depth to which arbitrary values are sanitized.
+ */
+const MAX_SANITIZE_DEPTH = 16;
+/**
+ * Converts an arbitrary value into a JSON-safe structure.
+ *
+ * Handles the cases that break JSON.stringify:
+ *
+ * circular references → "[Circular]"
+ * BigInt              → decimal string
+ * throwing toJSON     → "[Unserializable]"
+ * functions           → "[Function name]"
+ * symbols             → their string description
+ */
+export function sanitizeLogValue(value, seen = new WeakSet(), depth = 0) {
+    if (value === null || value === undefined)
+        return value;
+    const type = typeof value;
+    if (type === "bigint")
+        return value.toString();
+    if (type === "function")
+        return `[Function ${value.name || "anonymous"}]`;
+    if (type === "symbol")
+        return String(value);
+    if (type !== "object")
+        return value;
+    const objectValue = value;
+    if (seen.has(objectValue))
+        return "[Circular]";
+    if (depth >= MAX_SANITIZE_DEPTH)
+        return "[MaxDepth]";
+    if (objectValue instanceof Date)
+        return objectValue.toISOString();
+    if (objectValue instanceof Error)
+        return serializeLogErrorAtDepth(objectValue, {}, MAX_ERROR_CAUSE_DEPTH);
+    seen.add(objectValue);
+    try {
+        const withToJson = objectValue;
+        if (typeof withToJson.toJSON === "function") {
+            let converted;
+            try {
+                converted = withToJson.toJSON();
+            }
+            catch {
+                return "[Unserializable]";
+            }
+            if (converted !== objectValue) {
+                return sanitizeLogValue(converted, seen, depth + 1);
+            }
+        }
+        if (Array.isArray(objectValue)) {
+            return objectValue.map((item) => sanitizeLogValue(item, seen, depth + 1));
+        }
+        if (objectValue instanceof Map) {
+            const result = {};
+            for (const [key, item] of objectValue.entries()) {
+                result[String(key)] = sanitizeLogValue(item, seen, depth + 1);
+            }
+            return result;
+        }
+        if (objectValue instanceof Set) {
+            return [...objectValue].map((item) => sanitizeLogValue(item, seen, depth + 1));
+        }
+        const result = {};
+        for (const [key, item] of Object.entries(objectValue)) {
+            /*
+             * Assigning result["__proto__"] would replace the prototype
+             * (and drop the value from serialized output) instead of
+             * storing the key, so own "__proto__" keys — as produced by
+             * JSON.parse on untrusted input — are defined explicitly.
+             */
+            Object.defineProperty(result, key, {
+                value: sanitizeLogValue(item, seen, depth + 1),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        return result;
+    }
+    finally {
+        seen.delete(objectValue);
+    }
+}
+/**
+ * Safely serializes an arbitrary value to a JSON string.
+ *
+ * Never throws: values that resist serialization degrade to
+ * placeholder strings.
+ */
+export function safeLogStringify(value) {
+    try {
+        return JSON.stringify(sanitizeLogValue(value));
+    }
+    catch {
+        return '"[Unserializable]"';
+    }
+}
 //# sourceMappingURL=logEntry.entry.js.map

package/dist/logging/core/logLevel.level.d.ts

@@ -21,9 +21,27 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
  * Higher values represent more severe events.
  */
 export declare const LogLevelPriority: Record<LogLevel, number>;
+/**
+ * The level used when a configured level is unknown.
+ */
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+/**
+ * Checks whether a value is a known log level.
+ */
+export declare function isLogLevel(value: unknown): value is LogLevel;
+/**
+ * Resolves an arbitrary value to a known log level.
+ *
+ * Unknown values fall back to "info" so a configuration typo
+ * can never silently disable all logging.
+ */
+export declare function resolveLogLevel(value: unknown): LogLevel;
 /**
  * Determines whether a log level should be emitted when
  * the configured minimum level is applied.
+ *
+ * Unknown minimum levels are treated as "info" instead of
+ * silently disabling all logging.
  */
 export declare function shouldLog(level: LogLevel, minimumLevel: LogLevel): boolean;
 //# sourceMappingURL=logLevel.level.d.ts.map

package/dist/logging/core/logLevel.level.js

@@ -24,11 +24,35 @@ export const LogLevelPriority = {
     error: 50,
     fatal: 60,
 };
+/**
+ * The level used when a configured level is unknown.
+ */
+export const DEFAULT_LOG_LEVEL = LogLevel.INFO;
+/**
+ * Checks whether a value is a known log level.
+ */
+export function isLogLevel(value) {
+    return typeof value === "string" && Object.hasOwn(LogLevelPriority, value);
+}
+/**
+ * Resolves an arbitrary value to a known log level.
+ *
+ * Unknown values fall back to "info" so a configuration typo
+ * can never silently disable all logging.
+ */
+export function resolveLogLevel(value) {
+    return isLogLevel(value) ? value : DEFAULT_LOG_LEVEL;
+}
 /**
  * Determines whether a log level should be emitted when
  * the configured minimum level is applied.
+ *
+ * Unknown minimum levels are treated as "info" instead of
+ * silently disabling all logging.
  */
 export function shouldLog(level, minimumLevel) {
-    return LogLevelPriority[level] >= LogLevelPriority[minimumLevel];
+    const levelPriority = LogLevelPriority[level] ?? LogLevelPriority[DEFAULT_LOG_LEVEL];
+    const minimumPriority = LogLevelPriority[minimumLevel] ?? LogLevelPriority[DEFAULT_LOG_LEVEL];
+    return levelPriority >= minimumPriority;
 }
 //# sourceMappingURL=logLevel.level.js.map

package/dist/logging/core/logRedaction.redaction.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Hook applied to structured log data before it is written.
+ *
+ * The hook receives already-sanitized (JSON-safe) values: the
+ * merged context object of an entry, and the details of each
+ * serialized error in an error's cause chain. It returns the
+ * value to emit instead.
+ */
+export type LogRedactionHook = (value: unknown) => unknown;
+/**
+ * Options for the built-in key-based log redactor.
+ */
+export interface LogRedactorOptions {
+    /**
+     * Additional key patterns treated as sensitive, on top of the
+     * framework defaults (password, secret, token, api key, ...).
+     */
+    readonly patterns?: readonly string[];
+    /**
+     * Exact dot-paths (relative to the redacted value) treated as
+     * sensitive.
+     */
+    readonly paths?: readonly string[];
+    /**
+     * Replacement value. Defaults to "[REDACTED]".
+     */
+    readonly replacement?: string;
+}
+/**
+ * Creates a redaction hook that replaces values stored under
+ * sensitive-looking keys.
+ *
+ * Key matching is word-boundary aware (shared with the
+ * configuration redactor): "apiToken" and "db.password" are
+ * redacted, "tokenizer" is not.
+ */
+export declare function createLogRedactor(options?: LogRedactorOptions): LogRedactionHook;
+//# sourceMappingURL=logRedaction.redaction.d.ts.map

package/dist/logging/core/logRedaction.redaction.js

@@ -0,0 +1,19 @@
+import { ConfigurationRedactor } from "../../configuration/error/configurationRedactor.redactor.js";
+import { sanitizeLogValue } from "./logEntry.entry.js";
+/**
+ * Creates a redaction hook that replaces values stored under
+ * sensitive-looking keys.
+ *
+ * Key matching is word-boundary aware (shared with the
+ * configuration redactor): "apiToken" and "db.password" are
+ * redacted, "tokenizer" is not.
+ */
+export function createLogRedactor(options = {}) {
+    const redactor = new ConfigurationRedactor({
+        sensitivePatterns: options.patterns,
+        sensitivePaths: options.paths,
+        redactionValue: options.replacement,
+    });
+    return (value) => redactor.redactObject(sanitizeLogValue(value));
+}
+//# sourceMappingURL=logRedaction.redaction.js.map

package/dist/logging/core/logger.d.ts

@@ -1,18 +1,8 @@
-export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+import type { LogLevel } from "./logLevel.level.js";
 /**
  * Structured metadata attached to a log entry.
  */
 export type LogContext = Record<string, unknown>;
-/**
- * A structured log entry.
- */
-export interface LogEntry {
-    readonly level: LogLevel;
-    readonly message: string;
-    readonly context?: LogContext;
-    readonly timestamp: Date;
-    readonly error?: unknown;
-}
 /**
  * Logger contract used throughout Zudojs.
  *
@@ -59,6 +49,19 @@ export interface Logger {
 export declare abstract class BaseLogger implements Logger {
     private readonly persistentContext;
     protected constructor(context?: LogContext);
+    /**
+     * Merges the persistent (constructor/child) context under the
+     * per-call context. Per-call values win on key conflicts.
+     *
+     * Returns undefined only when there is no context at all, so
+     * implementations can keep omitting empty context objects.
+     */
+    protected mergeCallContext(context?: LogContext): LogContext | undefined;
+    /**
+     * Returns a copy of the persistent context attached to this
+     * logger.
+     */
+    protected getPersistentContext(): LogContext;
     trace(message: string, context?: LogContext): void;
     debug(message: string, context?: LogContext): void;
     info(message: string, context?: LogContext): void;

package/dist/logging/core/logger.js

@@ -11,23 +11,48 @@ export class BaseLogger {
             ...context,
         };
     }
+    /**
+     * Merges the persistent (constructor/child) context under the
+     * per-call context. Per-call values win on key conflicts.
+     *
+     * Returns undefined only when there is no context at all, so
+     * implementations can keep omitting empty context objects.
+     */
+    mergeCallContext(context) {
+        const hasPersistent = Object.keys(this.persistentContext).length > 0;
+        if (!hasPersistent)
+            return context;
+        if (context === undefined)
+            return { ...this.persistentContext };
+        return {
+            ...this.persistentContext,
+            ...context,
+        };
+    }
+    /**
+     * Returns a copy of the persistent context attached to this
+     * logger.
+     */
+    getPersistentContext() {
+        return { ...this.persistentContext };
+    }
     trace(message, context) {
-        this.write("trace", message, context);
+        this.write("trace", message, this.mergeCallContext(context));
     }
     debug(message, context) {
-        this.write("debug", message, context);
+        this.write("debug", message, this.mergeCallContext(context));
     }
     info(message, context) {
-        this.write("info", message, context);
+        this.write("info", message, this.mergeCallContext(context));
     }
     warn(message, context) {
-        this.write("warn", message, context);
+        this.write("warn", message, this.mergeCallContext(context));
     }
     error(message, error, context) {
-        this.write("error", message, context, error);
+        this.write("error", message, this.mergeCallContext(context), error);
     }
     fatal(message, error, context) {
-        this.write("fatal", message, context, error);
+        this.write("fatal", message, this.mergeCallContext(context), error);
     }
     child(context) {
         return this.createChild({

package/dist/logging/core/loggerContext.context.d.ts

@@ -1,3 +1,4 @@
+import type { ExecutionContext } from "../../context/core/executionContext.context.js";
 /**
  * Standard context fields that Zudojs can attach to log entries.
  *
@@ -17,6 +18,10 @@ export interface LoggerContext {
      * Unique identifier for the current execution.
      */
     readonly executionId?: string;
+    /**
+     * Identifier of the runtime the execution belongs to.
+     */
+    readonly runtimeId?: string;
     /**
      * Correlation identifier used to connect related operations.
      */
@@ -54,6 +59,13 @@ export interface LoggerContext {
      */
     readonly metadata?: Record<string, unknown>;
 }
+/**
+ * Extracts the LoggerContext fields carried by an execution context.
+ *
+ * Only defined values are returned, so merging the result never
+ * overwrites explicit context with `undefined`.
+ */
+export declare function loggerContextFromExecution(context: ExecutionContext): LoggerContext;
 /**
  * Creates a new logger context by merging existing context
  * with additional values.

package/dist/logging/core/loggerContext.context.js

@@ -1,3 +1,22 @@
+/**
+ * Extracts the LoggerContext fields carried by an execution context.
+ *
+ * Only defined values are returned, so merging the result never
+ * overwrites explicit context with `undefined`.
+ */
+export function loggerContextFromExecution(context) {
+    const fields = { executionId: context.executionId };
+    if (context.correlationId !== undefined)
+        fields.correlationId = context.correlationId;
+    if (context.traceId !== undefined)
+        fields.traceId = context.traceId;
+    if (context.spanId !== undefined)
+        fields.spanId = context.spanId;
+    const runtimeId = context.metadata.runtimeId;
+    if (typeof runtimeId === "string")
+        fields.runtimeId = runtimeId;
+    return fields;
+}
 /**
  * Creates a new logger context by merging existing context
  * with additional values.

package/dist/logging/core/loggerOptions.options.d.ts

@@ -1,3 +1,5 @@
+import type { LogRedactionHook } from "./logRedaction.redaction.js";
+import type { ContextStorage } from "../../context/provider/contextStorage.storage.js";
 /**
  * Configuration options for the Zudojs logging system.
  *
@@ -54,6 +56,21 @@ export interface LoggerOptions {
      * Additional default context attached to every log entry.
      */
     readonly context?: Record<string, unknown>;
+    /**
+     * Redaction hook applied to structured log data (entry context
+     * and error details) before it is written.
+     *
+     * See createLogRedactor for a key-based implementation.
+     */
+    readonly redact?: LogRedactionHook;
+    /**
+     * ContextStorage consulted on every write. When an execution
+     * context is active, its `executionId`, `correlationId`,
+     * `traceId`, `spanId`, and `metadata.runtimeId` are merged into
+     * the entry context beneath the logger's persistent and per-call
+     * context (explicit values win). Child loggers inherit it.
+     */
+    readonly contextStorage?: ContextStorage;
 }
 /**
  * Logging levels accepted by LoggerOptions.

package/dist/modules/index.d.ts

@@ -7,7 +7,6 @@
  * Module implementation logic belongs in the individual
  * module files.
  */
-export {} from "./module.js";
 export { type ModuleId, type ModuleOptions, type ModuleLifecycle, type Module, BaseModule, isModule, createModule, } from "./module.js";
 export * from "./moduleDefinition.definition.js";
 export * from "./moduleMetadata.metadata.js";

package/dist/modules/index.js

@@ -10,12 +10,6 @@
 /*
  * Module contract
  */
-export {} from // Export everything publicly exposed by module.ts.
- 
-//
-// Using `export *` here keeps the barrel synchronized
-// with the module contract as it evolves.
-"./module.js";
 export { BaseModule, isModule, createModule, } from "./module.js";
 /*
  * Module definition

package/dist/modules/module.d.ts

@@ -12,7 +12,13 @@ export type ModuleOptions = Readonly<Record<string, unknown>>;
 /**
  * Lifecycle hooks supported by a module.
  *
- * Modules can implement only the hooks they need.
+ * Modules can implement only the hooks they need. These are the
+ * only hook names the lifecycle engine invokes:
+ *
+ * initialize step → onInitialize
+ * start step      → onReady
+ * stop step       → onShutdown
+ * destroy step    → onDestroy
  */
 export interface ModuleLifecycle {
     /**