@bluelibs/runner 3.3.2 → 3.4.0

package/dist/defs.d.ts

@@ -14,6 +14,19 @@
  * - Safe overrides and strong typing around config and register mechanics
  */
 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;
+}
 export { ICacheInstance } from "./globals/middleware/cache.middleware";
 export * from "./models/StoreTypes";
 /**
@@ -39,16 +52,16 @@ export declare const symbolDispose: unique symbol;
 export declare const symbolStore: unique symbol;
 /** @internal Brand used by index() resources */
 export declare const symbolIndexResource: unique symbol;
-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;
 }
@@ -56,16 +69,16 @@ 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;
 }
 /**
@@ -73,16 +86,16 @@ export interface ITag<TConfig = void> extends ITagDefinition<TConfig> {
  * mirroring the same principle used for resources in `RegisterableItems`.
  * Required-config tags must appear as configured instances.
  */
-export type TagType = string | ITag<void> | ITag<{
+export type TagType = string | ITag<void, any> | ITag<{
     [K in any]?: any;
-}> | ITagWithConfig<any>;
+}, any> | ITagWithConfig<any, any>;
 /**
  * Conditional result type for `ITag.extract`:
  * - For void config → just the identifier
  * - 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;
 } : {
@@ -123,7 +136,7 @@ export interface IMiddlewareMeta extends IMeta {
 export type DependencyMapType = Record<string, ITask<any, any, any, any> | IResource<any, any, any> | IEventDefinition<any>>;
 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 : never;
+type ExtractResourceValue<T> = T extends IResource<any, infer V, infer D> ? V extends Promise<infer U> ? U : V : never;
 type ExtractEventParams<T> = T extends IEvent<infer P> ? P : never;
 /**
  * Task dependencies transform into callable functions: call with the task input
@@ -162,7 +175,8 @@ export type RegisterableItems<T = any> = IResourceWithConfig<any> | IResource<vo
 export type MiddlewareAttachments = IMiddleware<void> | IMiddleware<{
     [K in any]?: any;
 }> | IMiddlewareConfigured<any>;
-export interface ITaskDefinition<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> {
+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,
+TMeta extends ITaskMeta = any> {
     /**
      * Stable identifier. If omitted, an anonymous id is generated from file path
      * (see README: Anonymous IDs).
@@ -185,12 +199,17 @@ export interface ITaskDefinition<TInput = any, TOutput extends Promise<any> = an
      */
     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.
      */
-    run: (input: TOn extends undefined ? TInput : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>, dependencies: DependencyValuesType<TDependencies>) => TOutput;
+    run: (input: TOn extends undefined ? TInput : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>, dependencies: DependencyValuesType<TDependencies>) => HasContracts<TMeta> extends true ? EnsureResponseSatisfiesContracts<TMeta, TOutput> : TOutput;
 }
 export type BeforeRunEventPayload<TInput> = {
     input: TInput;
@@ -217,7 +236,7 @@ export type AfterInitEventPayload<TConfig, TValue> = {
 /**
  * This is the response after the definition has been prepared. TODO: better naming?
  */
-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> {
+export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, 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>;
@@ -233,7 +252,7 @@ export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDepend
     [symbolFilePath]: string;
     [symbolTask]: true;
 }
-export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependencies extends DependencyMapType = {}, TContext = any, THooks = any, TRegisterableItems = any> {
+export interface IResourceDefinition<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = {}, TContext = any, THooks = any, TRegisterableItems = any, TMeta extends IResourceMeta = any> {
     /** Stable identifier. Omit to get an anonymous id. */
     id?: string | symbol;
     /** Static or lazy dependency map. Receives `config` when provided. */
@@ -246,7 +265,7 @@ export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependenc
     /**
      * Initialize and return the resource value. Called once during boot.
      */
-    init?: (this: any, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => Promise<TValue>;
+    init?: (this: any, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => HasContracts<TMeta> extends true ? EnsureResponseSatisfiesContracts<TMeta, TValue> : TValue;
     /**
      * Clean-up function for the resource. This is called when the resource is no longer needed.
      *
@@ -255,8 +274,13 @@ export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependenc
      * @param dependencies The dependencies it needed
      * @returns Promise<void>
      */
-    dispose?: (this: any, value: TValue, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
-    meta?: IResourceMeta;
+    dispose?: (this: any, value: TValue extends Promise<infer U> ? U : TValue, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
+    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.
@@ -278,7 +302,7 @@ export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependenc
      */
     [symbolIndexResource]?: boolean;
 }
-export interface IResource<TConfig = void, TValue = any, TDependencies extends DependencyMapType = any, TContext = any> extends IResourceDefinition<TConfig, TValue, TDependencies, TContext> {
+export interface IResource<TConfig = void, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, 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: Array<RegisterableItems> | ((config: TConfig) => Array<RegisterableItems>);
@@ -296,7 +320,7 @@ export interface IResource<TConfig = void, TValue = any, TDependencies extends D
     [symbolIndexResource]: boolean;
     [symbolResource]: true;
 }
-export interface IResourceWithConfig<TConfig = any, TValue = any, TDependencies extends DependencyMapType = any> {
+export interface IResourceWithConfig<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any> {
     /** The id of the underlying resource. */
     id: string;
     /** The underlying resource definition. */
@@ -309,6 +333,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> {
     id: string | symbol;
@@ -357,6 +386,11 @@ export interface IMiddlewareDefinition<TConfig = any, TDependencies extends Depe
     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.
      */
@@ -396,7 +430,7 @@ export interface IMiddlewareExecutionInput<TTaskInput = any, TResourceConfig = a
     };
     /** Resource hook: present when wrapping init/dispose. */
     resource?: {
-        definition: IResource<TResourceConfig>;
+        definition: IResource<TResourceConfig, any, any, any, any>;
         config: TResourceConfig;
     };
     next: (taskInputOrResourceConfig?: TTaskInput | TResourceConfig) => Promise<any>;

package/dist/defs.js.map

@@ -1 +1 @@
-{"version":3,"file":"defs.js","sourceRoot":"","sources":["../src/defs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;AAMH,sDAAoC;AACpC;;;;;GAKG;AACU,QAAA,UAAU,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AAClD,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,wBAAwB,GAAkB,MAAM,CAC3D,2BAA2B,CAC5B,CAAC;AACW,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,QAAA,gBAAgB,GAAkB,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC9D,QAAA,0BAA0B,GAAkB,MAAM,CAC7D,6BAA6B,CAC9B,CAAC;AACW,QAAA,sBAAsB,GAAkB,MAAM,CACzD,yBAAyB,CAC1B,CAAC;AACW,QAAA,+BAA+B,GAAkB,MAAM,CAClE,8BAA8B,CAC/B,CAAC;AACW,QAAA,mCAAmC,GAAkB,MAAM,CACtE,kCAAkC,CACnC,CAAC;AAEF,uEAAuE;AAC1D,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AACvE,2CAA2C;AAC9B,QAAA,aAAa,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACrE,uCAAuC;AAC1B,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AAEjE,gDAAgD;AACnC,QAAA,mBAAmB,GAAkB,MAAM,CACtD,sBAAsB,CACvB,CAAC"}
+{"version":3,"file":"defs.js","sourceRoot":"","sources":["../src/defs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;AAuBH,sDAAoC;AACpC;;;;;GAKG;AACU,QAAA,UAAU,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AAClD,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,wBAAwB,GAAkB,MAAM,CAC3D,2BAA2B,CAC5B,CAAC;AACW,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,QAAA,gBAAgB,GAAkB,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC9D,QAAA,0BAA0B,GAAkB,MAAM,CAC7D,6BAA6B,CAC9B,CAAC;AACW,QAAA,sBAAsB,GAAkB,MAAM,CACzD,yBAAyB,CAC1B,CAAC;AACW,QAAA,+BAA+B,GAAkB,MAAM,CAClE,8BAA8B,CAC/B,CAAC;AACW,QAAA,mCAAmC,GAAkB,MAAM,CACtE,kCAAkC,CACnC,CAAC;AAEF,uEAAuE;AAC1D,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AACvE,2CAA2C;AAC9B,QAAA,aAAa,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACrE,uCAAuC;AAC1B,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AAEjE,gDAAgD;AACnC,QAAA,mBAAmB,GAAkB,MAAM,CACtD,sBAAsB,CACvB,CAAC"}

package/dist/defs.returnTag.d.ts

@@ -0,0 +1,36 @@
+import { ITag, ITagWithConfig } from "./defs";
+import { IMeta } from "./defs";
+type NonVoid<T> = [T] extends [void] ? never : T;
+type ExtractReturnFromTag<T> = T extends ITagWithConfig<any, infer R> ? NonVoid<R> : T extends ITag<any, infer R> ? NonVoid<R> : never;
+type IsTuple<T extends readonly unknown[]> = number extends T["length"] ? false : true;
+type FilterContracts<TTags extends readonly unknown[], Acc extends readonly unknown[] = []> = TTags extends readonly [infer H, ...infer R] ? ExtractReturnFromTag<H> extends never ? FilterContracts<R, Acc> : FilterContracts<R, [...Acc, ExtractReturnFromTag<H>]> : Acc;
+export type ExtractContractsFromTags<TTags extends readonly unknown[]> = IsTuple<TTags> extends true ? FilterContracts<TTags> : Array<ExtractReturnFromTag<TTags[number]>>;
+export type ExtractTagsWithNonVoidReturnTypeFromMeta<TMeta extends IMeta> = TMeta extends {
+    tags?: infer TTags;
+} ? TTags extends readonly unknown[] ? ExtractContractsFromTags<TTags> : [] : [];
+export type HasContracts<T extends IMeta> = ExtractTagsWithNonVoidReturnTypeFromMeta<T> extends never[] ? false : true;
+type UnionToIntersection<U> = (U extends any ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+type ContractsUnion<TMeta extends IMeta> = ExtractTagsWithNonVoidReturnTypeFromMeta<TMeta> extends readonly (infer U)[] ? U : never;
+type ContractsIntersection<TMeta extends IMeta> = UnionToIntersection<ContractsUnion<TMeta>>;
+/**
+ * Pretty-print helper to expand intersections for better IDE display.
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Verbose compile-time error surfaced when a value does not satisfy
+ * the intersection of all tag-enforced contracts.
+ *
+ * Intersected with `never` in call sites when desired to ensure assignment
+ * fails while still surfacing a readable shape in tooltips.
+ */
+export type ContractViolationError<TMeta extends IMeta, TActual> = {
+    message: "Value does not satisfy all tag contracts";
+    expected: Simplify<ContractsIntersection<TMeta>>;
+    received: TActual;
+};
+export type EnsureResponseSatisfiesContracts<TMeta extends IMeta, TResponse> = [
+    ContractsUnion<TMeta>
+] extends [never] ? TResponse : TResponse extends Promise<infer U> ? Promise<U extends ContractsIntersection<TMeta> ? U : ContractViolationError<TMeta, U>> : TResponse extends ContractsIntersection<TMeta> ? TResponse : ContractViolationError<TMeta, TResponse>;
+export {};

package/dist/defs.returnTag.js

@@ -0,0 +1,4 @@
+"use strict";
+// HasContracts<Meta> → true if contracts present, else false
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=defs.returnTag.js.map

package/dist/defs.returnTag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defs.returnTag.js","sourceRoot":"","sources":["../src/defs.returnTag.ts"],"names":[],"mappings":";AAAA,6DAA6D"}

package/dist/errors.d.ts

@@ -1,10 +1,60 @@
-export declare const Errors: {
-    duplicateRegistration: (type: string, id: string | symbol) => Error;
-    dependencyNotFound: (key: string | symbol) => Error;
-    unknownItemType: (item: any) => Error;
-    circularDependencies: (cycles: string[]) => Error;
-    eventNotFound: (id: string | symbol) => Error;
-    middlewareAlreadyGlobal: (id: string | symbol) => Error;
-    locked: (what: string | symbol) => Error;
-    storeAlreadyInitialized: () => Error;
-};
+/**
+ * Base error class for all BlueLibs Runner errors
+ */
+export declare class RuntimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when attempting to register a component with a duplicate ID
+ */
+export declare class DuplicateRegistrationError extends RuntimeError {
+    constructor(type: string, id: string | symbol);
+}
+/**
+ * Error thrown when a dependency is not found in the registry
+ */
+export declare class DependencyNotFoundError extends RuntimeError {
+    constructor(key: string | symbol);
+}
+/**
+ * Error thrown when an unknown item type is encountered
+ */
+export declare class UnknownItemTypeError extends RuntimeError {
+    constructor(item: any);
+}
+/**
+ * Error thrown when circular dependencies are detected
+ */
+export declare class CircularDependenciesError extends RuntimeError {
+    constructor(cycles: string[]);
+}
+/**
+ * Error thrown when an event is not found in the registry
+ */
+export declare class EventNotFoundError extends RuntimeError {
+    constructor(id: string | symbol);
+}
+/**
+ * Error thrown when attempting to make a middleware global when it's already global
+ */
+export declare class MiddlewareAlreadyGlobalError extends RuntimeError {
+    constructor(id: string | symbol);
+}
+/**
+ * Error thrown when attempting to modify a locked component
+ */
+export declare class LockedError extends RuntimeError {
+    constructor(what: string | symbol);
+}
+/**
+ * Error thrown when attempting to initialize a store that's already initialized
+ */
+export declare class StoreAlreadyInitializedError extends RuntimeError {
+    constructor();
+}
+/**
+ * Error thrown when validation fails for task input, resource config, middleware config, or event payload
+ */
+export declare class ValidationError extends RuntimeError {
+    constructor(type: string, id: string | symbol, originalError: Error | string);
+}

package/dist/errors.js

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

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAEa,QAAA,MAAM,GAAG;IACpB,qBAAqB,EAAE,CAAC,IAAY,EAAE,EAAmB,EAAE,EAAE,CAC3D,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,EAAE,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE5D,kBAAkB,EAAE,CAAC,GAAoB,EAAE,EAAE,CAC3C,IAAI,KAAK,CACP,cAAc,GAAG,CAAC,QAAQ,EAAE,+DAA+D,CAC5F;IAEH,eAAe,EAAE,CAAC,IAAS,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC;IAEvE,oBAAoB,EAAE,CAAC,MAAgB,EAAE,EAAE,CACzC,IAAI,KAAK,CAAC,mCAAmC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAEnE,aAAa,EAAE,CAAC,EAAmB,EAAE,EAAE,CACrC,IAAI,KAAK,CACP,UAAU,EAAE,CAAC,QAAQ,EAAE,6CAA6C,CACrE;IAEH,uBAAuB,EAAE,CAAC,EAAmB,EAAE,EAAE,CAC/C,IAAI,KAAK,CACP,6DAA6D;QAC3D,EAAE,CAAC,QAAQ,CACd;IAEH,MAAM,EAAE,CAAC,IAAqB,EAAE,EAAE,CAChC,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IAEtE,uBAAuB,EAAE,GAAG,EAAE,CAC5B,IAAI,KAAK,CAAC,iDAAiD,CAAC;CAC/D,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,MAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AALD,oCAKC;AAED;;GAEG;AACH,MAAa,0BAA2B,SAAQ,YAAY;IAC1D,YAAY,IAAY,EAAE,EAAmB;QAC3C,KAAK,CAAC,GAAG,IAAI,KAAK,EAAE,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AALD,gEAKC;AAED;;GAEG;AACH,MAAa,uBAAwB,SAAQ,YAAY;IACvD,YAAY,GAAoB;QAC9B,KAAK,CACH,cAAc,GAAG,CAAC,QAAQ,EAAE,+DAA+D,CAC5F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAPD,0DAOC;AAED;;GAEG;AACH,MAAa,oBAAqB,SAAQ,YAAY;IACpD,YAAY,IAAS;QACnB,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AALD,oDAKC;AAED;;GAEG;AACH,MAAa,yBAA0B,SAAQ,YAAY;IACzD,YAAY,MAAgB;QAC1B,KAAK,CAAC,mCAAmC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AALD,8DAKC;AAED;;GAEG;AACH,MAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,EAAmB;QAC7B,KAAK,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,6CAA6C,CAAC,CAAC;QAC5E,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED;;GAEG;AACH,MAAa,4BAA6B,SAAQ,YAAY;IAC5D,YAAY,EAAmB;QAC7B,KAAK,CACH,6DAA6D;YAC3D,EAAE,CAAC,QAAQ,EAAE,CAChB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AARD,oEAQC;AAED;;GAEG;AACH,MAAa,WAAY,SAAQ,YAAY;IAC3C,YAAY,IAAqB;QAC/B,KAAK,CAAC,qBAAqB,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AALD,kCAKC;AAED;;GAEG;AACH,MAAa,4BAA6B,SAAQ,YAAY;IAC5D;QACE,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AALD,oEAKC;AAED;;GAEG;AACH,MAAa,eAAgB,SAAQ,YAAY;IAC/C,YAAY,IAAY,EAAE,EAAmB,EAAE,aAA6B;QAC1E,MAAM,YAAY,GAAG,aAAa,YAAY,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACpG,KAAK,CAAC,GAAG,IAAI,0BAA0B,EAAE,CAAC,QAAQ,EAAE,KAAK,YAAY,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAND,0CAMC"}

package/dist/globals/globalMiddleware.d.ts

@@ -11,14 +11,14 @@ export declare const globalMiddlewares: {
         cache: import("../defs").IResource<{
             defaultOptions?: any;
             async?: boolean;
-        }, {
+        }, Promise<{
             map: Map<string | symbol, import("./middleware/cache.middleware").ICacheInstance>;
             cacheFactoryTask: (...args: [] | [any]) => Promise<import("./middleware/cache.middleware").ICacheInstance>;
             async: boolean | undefined;
             defaultOptions: any;
-        }, {
-            cacheFactoryTask: import("../defs").ITask<any, Promise<import("./middleware/cache.middleware").ICacheInstance>, any, undefined>;
-        }, any>;
+        }>, {
+            cacheFactoryTask: import("../defs").ITask<any, Promise<import("./middleware/cache.middleware").ICacheInstance>, any, undefined, any>;
+        }, any, any>;
     }>;
     timeout: import("../defs").IMiddleware<import("./middleware/timeout.middleware").TimeoutMiddlewareConfig, import("../defs").DependencyMapType>;
 };

package/dist/globals/globalResources.d.ts

@@ -3,25 +3,43 @@ import { Logger } from "../models/Logger";
 import { Store } from "../models/Store";
 import { TaskRunner } from "../models/TaskRunner";
 export declare const globalResources: {
-    store: import("../defs").IResource<Store, Store, {}, any>;
-    eventManager: import("../defs").IResource<EventManager, EventManager, {}, any>;
-    taskRunner: import("../defs").IResource<TaskRunner, TaskRunner, {}, any>;
-    logger: import("../defs").IResource<Logger, Logger, {}, any>;
+    store: import("../defs").IResource<Store, Promise<Store>, {}, any, {
+        title: string;
+        description: string;
+        tags: string[];
+    }>;
+    eventManager: import("../defs").IResource<EventManager, Promise<EventManager>, {}, any, {
+        title: string;
+        description: string;
+        tags: string[];
+    }>;
+    taskRunner: import("../defs").IResource<TaskRunner, Promise<TaskRunner>, {}, any, {
+        title: string;
+        description: string;
+        tags: string[];
+    }>;
+    logger: import("../defs").IResource<Logger, Promise<Logger>, {}, any, {
+        title: string;
+        description: string;
+    }>;
     cache: import("../defs").IResource<{
         defaultOptions?: any;
         async?: boolean;
-    }, {
+    }, Promise<{
         map: Map<string | symbol, import("./middleware/cache.middleware").ICacheInstance>;
         cacheFactoryTask: (...args: [] | [any]) => Promise<import("./middleware/cache.middleware").ICacheInstance>;
         async: boolean | undefined;
         defaultOptions: any;
-    }, {
-        cacheFactoryTask: import("../defs").ITask<any, Promise<import("./middleware/cache.middleware").ICacheInstance>, any, undefined>;
-    }, any>;
-    queue: import("../defs").IResource<void, {
+    }>, {
+        cacheFactoryTask: import("../defs").ITask<any, Promise<import("./middleware/cache.middleware").ICacheInstance>, any, undefined, any>;
+    }, any, any>;
+    queue: import("../defs").IResource<void, Promise<{
         map: Map<string | symbol, import("..").Queue>;
         run: <T>(id: string, task: (signal: AbortSignal) => Promise<T>) => Promise<T>;
-    }, {}, {
+    }>, {}, {
         map: Map<string | symbol, import("..").Queue>;
+    }, {
+        title: string;
+        description: string;
     }>;
 };

package/dist/globals/middleware/cache.middleware.d.ts

@@ -4,7 +4,7 @@ export interface ICacheInstance {
     get(key: string): any;
     clear(): void;
 }
-export declare const cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, undefined>;
+export declare const cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, undefined, any>;
 type CacheResourceConfig = {
     defaultOptions?: any;
     /**
@@ -13,22 +13,22 @@ type CacheResourceConfig = {
      */
     async?: boolean;
 };
-export declare const cacheResource: IResource<CacheResourceConfig, {
+export declare const cacheResource: IResource<CacheResourceConfig, Promise<{
     map: Map<string | symbol, ICacheInstance>;
     cacheFactoryTask: (...args: [] | [any]) => Promise<ICacheInstance>;
     async: boolean | undefined;
     defaultOptions: any;
-}, {
-    cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, undefined>;
-}, any>;
+}>, {
+    cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, undefined, any>;
+}, any, any>;
 export declare const cacheMiddleware: import("../../defs").IMiddleware<any, {
-    cache: IResource<CacheResourceConfig, {
+    cache: IResource<CacheResourceConfig, Promise<{
         map: Map<string | symbol, ICacheInstance>;
         cacheFactoryTask: (...args: [] | [any]) => Promise<ICacheInstance>;
         async: boolean | undefined;
         defaultOptions: any;
-    }, {
-        cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, undefined>;
-    }, any>;
+    }>, {
+        cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, undefined, any>;
+    }, any, any>;
 }>;
 export {};

package/dist/globals/resources/queue.resource.d.ts

@@ -1,7 +1,10 @@
 import { Queue } from "../../models/Queue";
-export declare const queueResource: import("../../defs").IResource<void, {
+export declare const queueResource: import("../../defs").IResource<void, Promise<{
     map: Map<string | symbol, Queue>;
     run: <T>(id: string, task: (signal: AbortSignal) => Promise<T>) => Promise<T>;
-}, {}, {
+}>, {}, {
     map: Map<string | symbol, Queue>;
+}, {
+    title: string;
+    description: string;
 }>;