@bluelibs/runner 3.3.2 → 3.4.0

package/src/defs.ts

@@ -15,6 +15,23 @@
  */
 
 import { MiddlewareEverywhereOptions } from "./define";
+import {
+  EnsureResponseSatisfiesContracts,
+  HasContracts,
+} from "./defs.returnTag";
+
+/**
+ * Generic validation schema interface that can be implemented by any validation library.
+ * Compatible with Zod, Yup, Joi, and other validation libraries.
+ */
+export interface IValidationSchema<T = any> {
+  /**
+   * Parse and validate the input data.
+   * Should throw an error if validation fails.
+   * Can transform the data if the schema supports transformations.
+   */
+  parse(input: unknown): T;
+}
 
 // Re-export public cache type so consumers don’t import from internals.
 export { ICacheInstance } from "./globals/middleware/cache.middleware";
@@ -57,17 +74,17 @@ export const symbolIndexResource: unique symbol = Symbol(
   "runner.indexResource"
 );
 
-export interface ITagDefinition<TConfig = void> {
+export interface ITagDefinition<TConfig = void, TEnforceContract = void> {
   id: string | symbol;
 }
 
 /**
  * A configured instance of a tag as produced by `ITag.with()`.
  */
-export interface ITagWithConfig<TConfig = void> {
+export interface ITagWithConfig<TConfig = void, TEnforceContract = void> {
   id: string | symbol;
   /** The tag definition used to produce this configured instance. */
-  tag: ITag<TConfig>;
+  tag: ITag<TConfig, TEnforceContract>;
   /** The configuration captured for this tag instance. */
   config: TConfig;
 }
@@ -76,16 +93,19 @@ export interface ITagWithConfig<TConfig = void> {
  * A tag definition (builder). Use `.with(config)` to obtain configured instances,
  * and `.extract(tags)` to find either a configured instance or the bare tag in a list.
  */
-export interface ITag<TConfig = void> extends ITagDefinition<TConfig> {
+export interface ITag<TConfig = void, TEnforceContract = void>
+  extends ITagDefinition<TConfig, TEnforceContract> {
   /**
    * Creates a configured instance of the tag.
    */
-  with(config: TConfig): ITagWithConfig<TConfig>;
+  with(config: TConfig): ITagWithConfig<TConfig, TEnforceContract>;
   /**
    * Extracts either a configured instance or the bare tag from a list of tags
    * or from a taggable object (`{ meta: { tags?: [] } }`).
    */
-  extract(target: TagType[] | ITaggable): ExtractedTagResult<TConfig> | null;
+  extract(
+    target: TagType[] | ITaggable
+  ): ExtractedTagResult<TConfig, TEnforceContract> | null;
   [symbolFilePath]: string;
 }
 
@@ -96,9 +116,9 @@ export interface ITag<TConfig = void> extends ITagDefinition<TConfig> {
  */
 export type TagType =
   | string
-  | ITag<void>
-  | ITag<{ [K in any]?: any }>
-  | ITagWithConfig<any>;
+  | ITag<void, any>
+  | ITag<{ [K in any]?: any }, any>
+  | ITagWithConfig<any, any>;
 
 /**
  * Conditional result type for `ITag.extract`:
@@ -106,7 +126,7 @@ export type TagType =
  * - For optional object config → identifier with optional config
  * - For required config → identifier with required config
  */
-export type ExtractedTagResult<TConfig> = {} extends TConfig
+export type ExtractedTagResult<TConfig, TEnforceContract> = {} extends TConfig
   ? { id: string | symbol; config?: TConfig }
   : { id: string | symbol; config: TConfig };
 
@@ -119,7 +139,6 @@ export interface ITaggable {
     tags?: TagType[];
   };
 }
-
 /**
  * Common metadata you can attach to tasks/resources/events/middleware.
  * Useful for docs, filtering and middleware decisions.
@@ -149,7 +168,9 @@ export type DependencyMapType = Record<
 type ExtractTaskInput<T> = T extends ITask<infer I, any, infer D> ? I : never;
 type ExtractTaskOutput<T> = T extends ITask<any, infer O, infer D> ? O : never;
 type ExtractResourceValue<T> = T extends IResource<any, infer V, infer D>
-  ? V
+  ? V extends Promise<infer U>
+    ? U
+    : V
   : never;
 
 type ExtractEventParams<T> = T extends IEvent<infer P> ? P : never;
@@ -213,7 +234,8 @@ export interface ITaskDefinition<
   TInput = any,
   TOutput extends Promise<any> = any,
   TDependencies extends DependencyMapType = {},
-  TOn extends "*" | IEventDefinition<any> | undefined = undefined // Adding a generic to track 'on' type
+  TOn extends "*" | IEventDefinition<any> | undefined = undefined, // Adding a generic to track 'on' type,
+  TMeta extends ITaskMeta = any
 > {
   /**
    * Stable identifier. If omitted, an anonymous id is generated from file path
@@ -237,7 +259,12 @@ export interface ITaskDefinition<
    */
   listenerOrder?: number;
   /** Optional metadata used for docs, filtering and tooling. */
-  meta?: ITaskMeta;
+  meta?: TMeta;
+  /**
+   * Optional validation schema for runtime input validation.
+   * When provided, task input will be validated before execution.
+   */
+  inputSchema?: IValidationSchema<TInput>;
   /**
    * The task body. If `on` is set, the input is an `IEventEmission`. Otherwise,
    * it's the declared input type.
@@ -247,7 +274,9 @@ export interface ITaskDefinition<
       ? TInput
       : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>,
     dependencies: DependencyValuesType<TDependencies>
-  ) => TOutput;
+  ) => HasContracts<TMeta> extends true
+    ? EnsureResponseSatisfiesContracts<TMeta, TOutput>
+    : TOutput;
 }
 
 export type BeforeRunEventPayload<TInput> = {
@@ -284,8 +313,9 @@ export interface ITask<
   TInput = any,
   TOutput extends Promise<any> = any,
   TDependencies extends DependencyMapType = {},
-  TOn extends "*" | IEventDefinition<any> | undefined = undefined
-> extends ITaskDefinition<TInput, TOutput, TDependencies, TOn> {
+  TOn extends "*" | IEventDefinition<any> | undefined = undefined,
+  TMeta extends ITaskMeta = any
+> extends ITaskDefinition<TInput, TOutput, TDependencies, TOn, TMeta> {
   id: string | symbol;
   dependencies: TDependencies | (() => TDependencies);
   computedDependencies?: DependencyValuesType<TDependencies>;
@@ -304,11 +334,12 @@ export interface ITask<
 
 export interface IResourceDefinition<
   TConfig = any,
-  TValue = unknown,
+  TValue extends Promise<any> = Promise<any>,
   TDependencies extends DependencyMapType = {},
   TContext = any,
   THooks = any,
-  TRegisterableItems = any
+  TRegisterableItems = any,
+  TMeta extends IResourceMeta = any
 > {
   /** Stable identifier. Omit to get an anonymous id. */
   id?: string | symbol;
@@ -329,7 +360,9 @@ export interface IResourceDefinition<
     config: TConfig,
     dependencies: DependencyValuesType<TDependencies>,
     context: TContext
-  ) => Promise<TValue>;
+  ) => HasContracts<TMeta> extends true
+    ? EnsureResponseSatisfiesContracts<TMeta, TValue>
+    : TValue;
   /**
    * Clean-up function for the resource. This is called when the resource is no longer needed.
    *
@@ -340,12 +373,17 @@ export interface IResourceDefinition<
    */
   dispose?: (
     this: any,
-    value: TValue,
+    value: TValue extends Promise<infer U> ? U : TValue,
     config: TConfig,
     dependencies: DependencyValuesType<TDependencies>,
     context: TContext
   ) => Promise<void>;
-  meta?: IResourceMeta;
+  meta?: TMeta;
+  /**
+   * Optional validation schema for runtime config validation.
+   * When provided, resource config will be validated when .with() is called.
+   */
+  configSchema?: IValidationSchema<TConfig>;
   /**
    * Safe overrides to swap behavior while preserving identities. See
    * README: Overrides.
@@ -370,10 +408,19 @@ export interface IResourceDefinition<
 
 export interface IResource<
   TConfig = void,
-  TValue = any,
+  TValue extends Promise<any> = Promise<any>,
   TDependencies extends DependencyMapType = any,
-  TContext = any
-> extends IResourceDefinition<TConfig, TValue, TDependencies, TContext> {
+  TContext = any,
+  TMeta extends IResourceMeta = any
+> extends IResourceDefinition<
+    TConfig,
+    TValue,
+    TDependencies,
+    TContext,
+    any,
+    any,
+    TMeta
+  > {
   id: string | symbol;
   with(config: TConfig): IResourceWithConfig<TConfig, TValue, TDependencies>;
   register:
@@ -396,7 +443,7 @@ export interface IResource<
 
 export interface IResourceWithConfig<
   TConfig = any,
-  TValue = any,
+  TValue extends Promise<any> = Promise<any>,
   TDependencies extends DependencyMapType = any
 > {
   /** The id of the underlying resource. */
@@ -415,6 +462,11 @@ export interface IEventDefinition<TPayload = void> {
   /** Stable identifier. Omit to get an anonymous id. */
   id?: string | symbol;
   meta?: IEventMeta;
+  /**
+   * Optional validation schema for runtime payload validation.
+   * When provided, event payload will be validated when emitted.
+   */
+  payloadSchema?: IValidationSchema<TPayload>;
 }
 
 export interface IEvent<TPayload = any> extends IEventDefinition<TPayload> {
@@ -469,6 +521,11 @@ export interface IMiddlewareDefinition<
   id?: string | symbol;
   /** Static or lazy dependency map. */
   dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+  /**
+   * Optional validation schema for runtime config validation.
+   * When provided, middleware config will be validated when .with() is called.
+   */
+  configSchema?: IValidationSchema<TConfig>;
   /**
    * The middleware body, called with task/resource execution input.
    */
@@ -530,7 +587,7 @@ export interface IMiddlewareExecutionInput<
   };
   /** Resource hook: present when wrapping init/dispose. */
   resource?: {
-    definition: IResource<TResourceConfig>;
+    definition: IResource<TResourceConfig, any, any, any, any>;
     config: TResourceConfig;
   };
   next: (

package/src/errors.ts

@@ -1,33 +1,105 @@
-import { ITask, IResource } from "./defs";
+/**
+ * Base error class for all BlueLibs Runner errors
+ */
+export class RuntimeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RuntimeError";
+  }
+}
 
-export const Errors = {
-  duplicateRegistration: (type: string, id: string | symbol) =>
-    new Error(`${type} "${id.toString()}" already registered`),
+/**
+ * Error thrown when attempting to register a component with a duplicate ID
+ */
+export class DuplicateRegistrationError extends RuntimeError {
+  constructor(type: string, id: string | symbol) {
+    super(`${type} "${id.toString()}" already registered`);
+    this.name = "DuplicateRegistrationError";
+  }
+}
 
-  dependencyNotFound: (key: string | symbol) =>
-    new Error(
+/**
+ * Error thrown when a dependency is not found in the registry
+ */
+export class DependencyNotFoundError extends RuntimeError {
+  constructor(key: string | symbol) {
+    super(
       `Dependency ${key.toString()} not found. Did you forget to register it through a resource?`
-    ),
+    );
+    this.name = "DependencyNotFoundError";
+  }
+}
 
-  unknownItemType: (item: any) => new Error(`Unknown item type: ${item}`),
+/**
+ * Error thrown when an unknown item type is encountered
+ */
+export class UnknownItemTypeError extends RuntimeError {
+  constructor(item: any) {
+    super(`Unknown item type: ${item}`);
+    this.name = "UnknownItemTypeError";
+  }
+}
 
-  circularDependencies: (cycles: string[]) =>
-    new Error(`Circular dependencies detected: ${cycles.join(", ")}`),
+/**
+ * Error thrown when circular dependencies are detected
+ */
+export class CircularDependenciesError extends RuntimeError {
+  constructor(cycles: string[]) {
+    super(`Circular dependencies detected: ${cycles.join(", ")}`);
+    this.name = "CircularDependenciesError";
+  }
+}
 
-  eventNotFound: (id: string | symbol) =>
-    new Error(
-      `Event "${id.toString()}" not found. Did you forget to register it?`
-    ),
+/**
+ * Error thrown when an event is not found in the registry
+ */
+export class EventNotFoundError extends RuntimeError {
+  constructor(id: string | symbol) {
+    super(`Event "${id.toString()}" not found. Did you forget to register it?`);
+    this.name = "EventNotFoundError";
+  }
+}
 
-  middlewareAlreadyGlobal: (id: string | symbol) =>
-    new Error(
+/**
+ * Error thrown when attempting to make a middleware global when it's already global
+ */
+export class MiddlewareAlreadyGlobalError extends RuntimeError {
+  constructor(id: string | symbol) {
+    super(
       "Cannot call .everywhere() on an already global middleware: " +
-        id.toString
-    ),
+        id.toString()
+    );
+    this.name = "MiddlewareAlreadyGlobalError";
+  }
+}
 
-  locked: (what: string | symbol) =>
-    new Error(`Cannot modify the ${what.toString()} when it is locked.`),
+/**
+ * Error thrown when attempting to modify a locked component
+ */
+export class LockedError extends RuntimeError {
+  constructor(what: string | symbol) {
+    super(`Cannot modify the ${what.toString()} when it is locked.`);
+    this.name = "LockedError";
+  }
+}
 
-  storeAlreadyInitialized: () =>
-    new Error("Store already initialized. Cannot reinitialize."),
-};
+/**
+ * Error thrown when attempting to initialize a store that's already initialized
+ */
+export class StoreAlreadyInitializedError extends RuntimeError {
+  constructor() {
+    super("Store already initialized. Cannot reinitialize.");
+    this.name = "StoreAlreadyInitializedError";
+  }
+}
+
+/**
+ * Error thrown when validation fails for task input, resource config, middleware config, or event payload
+ */
+export class ValidationError extends RuntimeError {
+  constructor(type: string, id: string | symbol, originalError: Error | string) {
+    const errorMessage = originalError instanceof Error ? originalError.message : String(originalError);
+    super(`${type} validation failed for ${id.toString()}: ${errorMessage}`);
+    this.name = "ValidationError";
+  }
+}

package/src/index.ts

@@ -36,3 +36,4 @@ export {
 
 export * as definitions from "./defs";
 export { Semaphore, Store, EventManager, TaskRunner, Queue } from "./models";
+export * as Errors from "./errors";

package/src/models/DependencyProcessor.ts

@@ -13,7 +13,11 @@ import * as utils from "../define";
 import { EventManager } from "./EventManager";
 import { ResourceInitializer } from "./ResourceInitializer";
 import { TaskRunner } from "./TaskRunner";
-import { Errors } from "../errors";
+import {
+  DependencyNotFoundError,
+  EventNotFoundError,
+  UnknownItemTypeError,
+} from "../errors";
 import { Logger } from "./Logger";
 
 /**
@@ -148,7 +152,7 @@ export class DependencyProcessor {
           });
         } else {
           if (this.store.events.get(eventDefinition.id) === undefined) {
-            throw Errors.eventNotFound(eventDefinition.id);
+            throw new EventNotFoundError(eventDefinition.id);
           }
           this.eventManager.addListener(eventDefinition, handler, {
             order: task.task.listenerOrder || 0,
@@ -179,7 +183,7 @@ export class DependencyProcessor {
     } else if (utils.isEvent(object)) {
       return this.extractEventDependency(object, source);
     } else {
-      throw Errors.unknownItemType(object);
+      throw new UnknownItemTypeError(object);
     }
   }
 
@@ -197,7 +201,7 @@ export class DependencyProcessor {
   async extractTaskDependency(object: ITask<any, any, {}>) {
     const storeTask = this.store.tasks.get(object.id);
     if (storeTask === undefined) {
-      throw Errors.dependencyNotFound(`Task ${object.id.toString()}`);
+      throw new DependencyNotFoundError(`Task ${object.id.toString()}`);
     }
 
     if (!storeTask.isInitialized) {
@@ -221,7 +225,7 @@ export class DependencyProcessor {
     // check if it exists in the store with the value
     const storeResource = this.store.resources.get(object.id);
     if (storeResource === undefined) {
-      throw Errors.dependencyNotFound(`Resource ${object.id.toString()}`);
+      throw new DependencyNotFoundError(`Resource ${object.id.toString()}`);
     }
 
     const { resource, config } = storeResource;

package/src/models/EventManager.ts

@@ -4,7 +4,7 @@ import {
   IEventDefinition,
   IEventEmission,
 } from "../defs";
-import { Errors } from "../errors";
+import { LockedError, ValidationError } from "../errors";
 import { Logger } from "./Logger";
 
 const HandlerOptionsDefaults = { order: 0 };
@@ -42,7 +42,7 @@ export class EventManager {
 
   checkLock() {
     if (this.#isLocked) {
-      throw Errors.locked("EventManager");
+      throw new LockedError("EventManager");
     }
   }
 
@@ -106,6 +106,15 @@ export class EventManager {
     data: TInput,
     source: string | symbol
   ): Promise<void> {
+    // Validate payload with schema if provided
+    if (eventDefinition.payloadSchema) {
+      try {
+        data = eventDefinition.payloadSchema.parse(data);
+      } catch (error) {
+        throw new ValidationError("Event payload", eventDefinition.id, error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+    
     const allListeners = this.getCachedMergedListeners(eventDefinition.id);
 
     if (allListeners.length === 0) {
@@ -130,7 +139,7 @@ export class EventManager {
       if (propagationStopped) {
         break;
       }
-      
+
       if (!listener.filter || listener.filter(event)) {
         await listener.handler(event);
       }

package/src/models/Logger.ts

@@ -48,6 +48,34 @@ export class Logger {
     boundContext: Record<string, any> = {}
   ) {
     this.boundContext = { ...boundContext };
+    this.printThreshold = this.getDefaultPrintThreshold();
+  }
+
+  /**
+   * Determines the default print threshold based on environment variables
+   */
+  private getDefaultPrintThreshold(): LogLevels | null {
+    // Check if logging is explicitly disabled
+    const disableLogs = process.env.RUNNER_DISABLE_LOGS;
+    if (disableLogs === "true" || disableLogs === "1") {
+      return null;
+    }
+
+    // Check for specific log level override
+    const logLevel = process.env.RUNNER_LOG_LEVEL;
+    if (logLevel && this.isValidLogLevel(logLevel)) {
+      return logLevel as LogLevels;
+    }
+
+    // Default to 'info' level for better developer experience
+    return "info";
+  }
+
+  /**
+   * Validates if a string is a valid log level
+   */
+  private isValidLogLevel(level: string): boolean {
+    return Object.keys(Logger.Severity).includes(level);
   }
 
   /**

package/src/models/OverrideManager.ts

@@ -6,12 +6,7 @@ import {
   RegisterableItems,
 } from "../defs";
 import * as utils from "../define";
-import { Errors } from "../errors";
-import {
-  TaskStoreElementType,
-  MiddlewareStoreElementType,
-  ResourceStoreElementType,
-} from "./StoreTypes";
+import { DependencyNotFoundError } from "../errors";
 import { StoreRegistry } from "./StoreRegistry";
 
 export class OverrideManager {
@@ -65,7 +60,7 @@ export class OverrideManager {
           ? override.resource.id
           : override.id;
 
-        throw Errors.dependencyNotFound(id);
+        throw new DependencyNotFoundError(id);
       }
     }
 

package/src/models/ResourceInitializer.ts

@@ -23,7 +23,7 @@ export class ResourceInitializer {
    */
   public async initializeResource<
     TConfig = null,
-    TValue = any,
+    TValue extends Promise<any> = Promise<any>,
     TDeps extends DependencyMapType = {},
     TContext = any
   >(
@@ -109,11 +109,16 @@ export class ResourceInitializer {
 
       if (!isSuppressed) throw e;
 
-      return { value: undefined as TValue, context: {} as TContext };
+      return { value: undefined as unknown as TValue, context: {} as TContext };
     }
   }
 
-  public async initWithMiddleware<C, V, D extends DependencyMapType, TContext>(
+  public async initWithMiddleware<
+    C,
+    V extends Promise<any>,
+    D extends DependencyMapType,
+    TContext
+  >(
     resource: IResource<C, V, D, TContext>,
     config: C,
     dependencies: DependencyValuesType<D>,

package/src/models/Store.ts

@@ -6,7 +6,7 @@ import {
 } from "../defs";
 import { IDependentNode } from "../tools/findCircularDependencies";
 import { globalEventsArray } from "../globals/globalEvents";
-import { Errors } from "../errors";
+import { StoreAlreadyInitializedError } from "../errors";
 import { EventManager } from "./EventManager";
 import { Logger } from "./Logger";
 import { StoreRegistry } from "./StoreRegistry";
@@ -125,9 +125,9 @@ export class Store {
     this.registry.resources.set(root.id, this.root);
   }
 
-  initializeStore(root: IResource<any>, config: any) {
+  initializeStore(root: IResource<any, any, any, any, any>, config: any) {
     if (this.#isInitialized) {
-      throw Errors.storeAlreadyInitialized();
+      throw new StoreAlreadyInitializedError();
     }
 
     this.registerGlobalComponents();

package/src/models/StoreRegistry.ts

@@ -12,7 +12,7 @@ import {
   IEvent,
 } from "../defs";
 import * as utils from "../define";
-import { Errors } from "../errors";
+import { UnknownItemTypeError } from "../errors";
 import {
   TaskStoreElementType,
   MiddlewareStoreElementType,
@@ -55,7 +55,7 @@ export class StoreRegistry {
     } else if (utils.isResourceWithConfig(item)) {
       this.storeResourceWithConfig<C>(item);
     } else {
-      throw Errors.unknownItemType(item);
+      throw new UnknownItemTypeError(item);
     }
   }
 

package/src/models/StoreTypes.ts

@@ -13,7 +13,7 @@ import {
 
 export type ResourceStoreElementType<
   C = any,
-  V = any,
+  V extends Promise<any> = any,
   D extends DependencyMapType = {},
   TContext = any
 > = {

package/src/models/StoreValidator.ts

@@ -1,4 +1,4 @@
-import { Errors } from "../errors";
+import { DependencyNotFoundError, DuplicateRegistrationError } from "../errors";
 import {
   TaskStoreElementType,
   MiddlewareStoreElementType,
@@ -16,16 +16,16 @@ export class StoreValidator {
 
   checkIfIDExists(id: string | symbol): void | never {
     if (this.tasks.has(id)) {
-      throw Errors.duplicateRegistration("Task", id);
+      throw new DuplicateRegistrationError("Task", id);
     }
     if (this.resources.has(id)) {
-      throw Errors.duplicateRegistration("Resource", id);
+      throw new DuplicateRegistrationError("Resource", id);
     }
     if (this.events.has(id)) {
-      throw Errors.duplicateRegistration("Event", id);
+      throw new DuplicateRegistrationError("Event", id);
     }
     if (this.middlewares.has(id)) {
-      throw Errors.duplicateRegistration("Middleware", id);
+      throw new DuplicateRegistrationError("Middleware", id);
     }
   }
 
@@ -33,7 +33,7 @@ export class StoreValidator {
     for (const task of this.tasks.values()) {
       task.task.middleware.forEach((middleware) => {
         if (!this.middlewares.has(middleware.id)) {
-          throw Errors.dependencyNotFound(
+          throw new DependencyNotFoundError(
             `Middleware ${middleware.id.toString()} in Task ${task.task.id.toString()}`
           );
         }