@bluelibs/runner 3.3.2 → 3.4.1

package/README.md

@@ -4,7 +4,7 @@ _Or: How I Learned to Stop Worrying and Love Dependency Injection_
 
 <p align="center">
 <a href="https://github.com/bluelibs/runner/actions/workflows/ci.yml"><img src="https://github.com/bluelibs/runner/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build Status" /></a>
-<a href="https://coveralls.io/github/bluelibs/runner?branch=main"><img src="https://coveralls.io/repos/github/bluelibs/runner/badge.svg?branch=main" alt="Coverage Status" /></a>
+<a href="https://github.com/bluelibs/runner"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Coverage 100% is enforced. Code does not build without 100% on all branches, lines, etc." /></a>
 <a href="https://bluelibs.github.io/runner/" target="_blank"><img src="https://img.shields.io/badge/read-typedocs-blue" alt="Docs" /></a>
 <a href="https://github.com/bluelibs/runner" target="_blank"><img src="https://img.shields.io/badge/github-blue" alt="GitHub" /></a>
 </p>
@@ -601,6 +601,58 @@ The retry middleware can be configured with:
 - `delayStrategy`: A function that returns the delay in milliseconds before the next attempt.
 - `stopRetryIf`: A function to prevent retries for certain types of errors.
 
+## Timeout Middleware: Never Wait Forever
+
+The built-in timeout middleware prevents operations from hanging indefinitely by racing them against a configurable
+timeout:
+
+```typescript
+import { globals } from "@bluelibs/runner";
+
+const apiTask = task({
+  id: "app.tasks.externalApi",
+  middleware: [
+    globals.middleware.timeout.with({ ttl: 5000 }), // 5 second timeout
+  ],
+  run: async () => {
+    // This operation will be aborted if it takes longer than 5 seconds
+    return await fetch("https://slow-api.example.com/data");
+  },
+});
+
+// Combine with retry for robust error handling
+const resilientTask = task({
+  id: "app.tasks.resilient",
+  middleware: [
+    // Order matters here. Imagine a big onion.
+    globals.middleware.retry.with({
+      retries: 3,
+      delayStrategy: (attempt) => 1000 * attempt, // 1s, 2s, 3s delays
+    }),
+    globals.middleware.timeout.with({ ttl: 10000 }), // 10 second timeout per attempt
+  ],
+  run: async () => {
+    // Each retry attempt gets its own 10-second timeout
+    return await unreliableOperation();
+  },
+});
+```
+
+How it works:
+
+- Uses AbortController and Promise.race() for clean cancellation
+- Throws TimeoutError when the timeout is reached
+- Works with any async operation in tasks and resources
+- Integrates seamlessly with retry middleware for layered resilience
+- Zero timeout (ttl: 0) throws immediately for testing edge cases
+
+Best practices:
+
+- Set timeouts based on expected operation duration plus buffer
+- Combine with retry middleware for transient failures
+- Use longer timeouts for resource initialization than task execution
+- Consider network conditions when setting API call timeouts
+
 ## Logging: Because Console.log Isn't Professional
 
 _The structured logging system that actually makes debugging enjoyable_
@@ -616,18 +668,32 @@ const businessTask = task({
   id: "app.tasks.business",
   dependencies: { logger: globals.resources.logger },
   run: async (_, { logger }) => {
-    logger.info("Starting business process");
-    logger.warn("This might take a while");
+    logger.info("Starting business process"); // ✅ Visible by default
+    logger.warn("This might take a while"); // ✅ Visible by default
     logger.error("Oops, something went wrong", {
+      // ✅ Visible by default
       error: new Error("Database connection failed"),
     });
     logger.critical("System is on fire", {
+      // ✅ Visible by default
       data: { temperature: "9000°C" },
     });
+    logger.debug("Debug information"); // ❌ Hidden by default
+    logger.trace("Very detailed trace"); // ❌ Hidden by default
   },
 });
 ```
 
+**Good news!** Logs at `info` level and above are visible by default, so you'll see your application logs immediately without any configuration. For development and debugging, you can easily show more detailed logs:
+
+```bash
+# Show debug logs and framework internals
+RUNNER_LOG_LEVEL=debug node your-app.js
+
+# Hide all logs for production
+RUNNER_DISABLE_LOGS=true node your-app.js
+```
+
 ### Log Levels: From Whispers to Screams
 
 The logger supports six log levels with increasing severity:
@@ -733,18 +799,31 @@ const requestHandler = task({
 
 ### Print Threshold: Control What Shows Up
 
-By default, logs are just events - they don't print to console unless you tell them to. Set a print threshold to automatically output logs at or above a certain level:
+By default, logs at `info` level and above are automatically printed to console for better developer experience. You can easily control this behavior through environment variables or by setting a print threshold programmatically:
+
+#### Environment Variable Controls
+
+```bash
+# Disable all logging output
+RUNNER_DISABLE_LOGS=true node your-app.js
+
+# Set specific log level (trace, debug, info, warn, error, critical)
+RUNNER_LOG_LEVEL=debug node your-app.js
+RUNNER_LOG_LEVEL=error node your-app.js
+```
+
+#### Programmatic Control
 
 ```typescript
-// Set up log printing (they don't print by default)
+// Override the default print threshold programmatically
 const setupLogging = task({
   id: "app.logging.setup",
   on: globals.resources.logger.events.afterInit,
   run: async (event) => {
     const logger = event.data.value;
 
-    // Print info level and above (info, warn, error, critical)
-    logger.setPrintThreshold("info");
+    // Print debug level and above (debug, info, warn, error, critical)
+    logger.setPrintThreshold("debug");
 
     // Print only errors and critical issues
     logger.setPrintThreshold("error");
@@ -1164,6 +1243,8 @@ const apiEndpoint = task({
 });
 ```
 
+To process these tags you can hook into `globals.events.afterInit`, use the global store as dependency and use the `getTasksWithTag()` and `getResourcesWithTag()` functionality.
+
 #### Smart Middleware Using Structured Tags
 
 ```typescript
@@ -1171,16 +1252,16 @@ const performanceMiddleware = middleware({
   id: "app.middleware.performance",
   run: async ({ task, next }) => {
     const tags = task.definition.meta?.tags || [];
-    const perfConfig = performanceTag.extract(tags);
+    const perfConfigTag = performanceTag.extract(tags); // or easier: .extract(task.definition)
 
-    if (perfConfig) {
+    if (perfConfigTag) {
       const startTime = Date.now();
 
       try {
         const result = await next(task.input);
         const duration = Date.now() - startTime;
 
-        if (duration > perfConfig.config.criticalAboveMs) {
+        if (duration > perfConfigTag.config.criticalAboveMs) {
           await alerting.critical(
             `Task ${task.definition.id} took ${duration}ms`
           );
@@ -1202,38 +1283,74 @@ const performanceMiddleware = middleware({
     return next(task.input);
   },
 });
+```
 
-const rateLimitMiddleware = middleware({
-  id: "app.middleware.rateLimit",
-  dependencies: { redis },
-  run: async ({ task, next }, { redis }) => {
-    // Extraction can be done at task.definition level or at task.definition.meta.tags
-    const rateLimitCurrentTag = rateLimitTag.extract(task.definition);
+#### Contract Tags: Enforcing Return Types
 
-    // Alternative way
-    const tags = task.definition.meta?.tags;
-    const rateLimitCurrentTag = rateLimitTag.extract(tags);
+You can attach contracts to tags to enforce the shape of a task's returned value and a resource's `init()` value at compile time. Contracts are specified via the second generic of `defineTag<TConfig, TContract>`.
 
-    if (rateLimitCurrentTag) {
-      const key = `rateLimit:${task.definition.id}`;
-      const current = await redis.incr(key);
+```typescript
+// A tag that enforces the returned value to include { name: string }
+const userContract = tag<void, { name: string }>({ id: "contract.user" });
 
-      if (current === 1) {
-        await redis.expire(key, 60); // 1 minute window
-      }
+// Another tag that enforces { age: number }
+const ageContract = tag<void, { age: number }>({ id: "contract.age" });
 
-      if (current > rateLimitCurrentTag.config.maxRequestsPerMinute) {
-        throw new Error("Rate limit exceeded");
-      }
-    }
+// Works with configured tags too
+const preferenceContract = tag<{ locale: string }, { preferredLocale: string }>(
+  { id: "contract.preferences" }
+);
+```
 
-    return next(task.input);
+When these tags are present in `meta.tags`, the returned value must satisfy the intersection of all contract types:
+
+```typescript
+// Task: the awaited return value must satisfy { name: string } & { age: number }
+const getProfile = task({
+  id: "app.tasks.getProfile",
+  meta: {
+    tags: [
+      userContract,
+      ageContract,
+      preferenceContract.with({ locale: "en" }),
+    ],
+  },
+  run: async () => {
+    return { name: "Ada", age: 37, preferredLocale: "en" }; // OK
   },
 });
+
+// Resource: init() return must satisfy the same intersection
+const profileService = resource({
+  id: "app.resources.profileService",
+  meta: { tags: [userContract, ageContract] },
+  init: async () => {
+    return { name: "Ada", age: 37 }; // OK
+  },
+});
+```
+
+If the returned value does not satisfy the intersection, TypeScript surfaces a readable, verbose type error that includes what was expected and what was received.
+
+```typescript
+const badTask = task({
+  id: "app.tasks.bad",
+  meta: { tags: [userContract, ageContract] },
+  //    vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
+  run: async () => ({ name: "Ada" }), // Missing { age: number }
+  // Type error includes a helpful shape similar to:
+  // ContractViolationError<
+  //   { message: "Value does not satisfy all tag contracts";
+  //     expected: { name: string } & { age: number };
+  //     received: { name: string } }
+  // >
+});
 ```
 
 ### When to Use Metadata
 
+Always strive to provide a title and a description.
+
 #### ✅ Great Use Cases
 
 **Documentation & Discovery**
@@ -1284,33 +1401,6 @@ const developmentTask = task({
 });
 ```
 
-#### ❌ When NOT to Use Metadata
-
-**Simple Internal Logic** - Don't overcomplicate straightforward code:
-
-```typescript
-// ❌ Overkill
-const simple = task({
-  meta: { tags: ["internal", "utility"] },
-  run: () => Math.random(),
-});
-
-// ✅ Better
-const generateId = () => Math.random().toString(36);
-```
-
-**One-Off Tasks** - If it's used once, metadata won't help:
-
-```typescript
-// ❌ Unnecessary
-const oneTimeScript = task({
-  meta: { title: "Migration Script", tags: ["migration"] },
-  run: () => {
-    /* run once and forget */
-  },
-});
-```
-
 ### Extending Metadata: Custom Properties
 
 For advanced use cases, you can extend the metadata interfaces to add your own properties:
@@ -1365,23 +1455,6 @@ const database = resource({
 
 ### Advanced Patterns
 
-#### Tag-Based Component Selection
-
-```typescript
-// Find all API endpoints
-function getApiTasks(store: Store) {
-  return store.getAllTasks().filter((task) => task.meta?.tags?.includes("api"));
-}
-
-// Find all tasks with specific performance requirements
-function getPerformanceCriticalTasks(store: Store) {
-  return store.getAllTasks().filter((task) => {
-    const tags = task.meta?.tags || [];
-    return performanceTag.extract(tags) !== null;
-  });
-}
-```
-
 #### Dynamic Middleware Application
 
 ```typescript
@@ -1512,6 +1585,350 @@ const app = resource({
 });
 ```
 
+### Runtime Input and Config Validation
+
+BlueLibs Runner includes a generic validation interface that works with any validation library, including [Zod](https://zod.dev/), [Yup](https://github.com/jquense/yup), [Joi](https://joi.dev/), and others. The framework provides runtime validation with excellent TypeScript inference while remaining library-agnostic.
+
+#### The Validation Interface
+
+The framework defines a simple `IValidationSchema<T>` interface that any validation library can implement:
+
+```typescript
+interface IValidationSchema<T> {
+  parse(input: unknown): T;
+}
+```
+
+Popular validation libraries already implement this interface:
+
+- **Zod**: `.parse()` method works directly
+- **Yup**: Use `.validateSync()` or create a wrapper
+- **Joi**: Use `.assert()` or create a wrapper
+- **Custom validators**: Implement the interface yourself
+
+#### Task Input Validation
+
+Add an `inputSchema` to any task to validate inputs before execution:
+
+```typescript
+import { z } from "zod";
+import { task, resource, run } from "@bluelibs/runner";
+
+const userSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  age: z.number().min(0).max(150),
+});
+
+const createUserTask = task({
+  id: "app.tasks.createUser",
+  inputSchema: userSchema, // Works directly with Zod!
+  run: async (userData) => {
+    // userData is validated and properly typed
+    return { id: "user-123", ...userData };
+  },
+});
+
+const app = resource({
+  id: "app",
+  register: [createUserTask],
+  dependencies: { createUserTask },
+  init: async (_, { createUserTask }) => {
+    // This works - valid input
+    const user = await createUserTask({
+      name: "John Doe",
+      email: "john@example.com",
+      age: 30,
+    });
+
+    // This throws a validation error at runtime
+    try {
+      await createUserTask({
+        name: "J", // Too short
+        email: "invalid-email", // Invalid format
+        age: -5, // Negative age
+      });
+    } catch (error) {
+      console.log(error.message);
+      // "Task input validation failed for app.tasks.createUser: ..."
+    }
+  },
+});
+```
+
+#### Resource Config Validation (Fail Fast)
+
+Add a `configSchema` to resources to validate configurations. **Validation happens immediately when `.with()` is called**, ensuring configuration errors are caught early:
+
+```typescript
+const databaseConfigSchema = z.object({
+  host: z.string(),
+  port: z.number().min(1).max(65535),
+  database: z.string(),
+  ssl: z.boolean().default(false), // Optional with default
+});
+
+const databaseResource = resource({
+  id: "app.resources.database",
+  configSchema: databaseConfigSchema, // Validation on .with()
+  init: async (config) => {
+    // config is already validated and has proper types
+    return createConnection({
+      host: config.host,
+      port: config.port,
+      database: config.database,
+      ssl: config.ssl,
+    });
+  },
+});
+
+// Validation happens here, not during init!
+try {
+  const configuredResource = databaseResource.with({
+    host: "localhost",
+    port: 99999, // Invalid: port too high
+    database: "myapp",
+  });
+} catch (error) {
+  // "Resource config validation failed for app.resources.database: ..."
+}
+
+const app = resource({
+  id: "app",
+  register: [
+    databaseResource.with({
+      host: "localhost",
+      port: 5432,
+      database: "myapp",
+      // ssl defaults to false
+    }),
+  ],
+});
+```
+
+#### Event Payload Validation
+
+Add a `payloadSchema` to events to validate payloads every time they're emitted:
+
+```typescript
+const userActionSchema = z.object({
+  userId: z.string().uuid(),
+  action: z.enum(["created", "updated", "deleted"]),
+  timestamp: z.date().default(() => new Date()),
+});
+
+const userActionEvent = event({
+  id: "app.events.userAction",
+  payloadSchema: userActionSchema, // Validates on emit
+});
+
+const notificationTask = task({
+  id: "app.tasks.sendNotification",
+  on: userActionEvent,
+  run: async (eventData) => {
+    // eventData.data is validated and properly typed
+    console.log(`User ${eventData.data.userId} was ${eventData.data.action}`);
+  },
+});
+
+const app = resource({
+  id: "app",
+  register: [userActionEvent, notificationTask],
+  dependencies: { userActionEvent },
+  init: async (_, { userActionEvent }) => {
+    // This works - valid payload
+    await userActionEvent({
+      userId: "123e4567-e89b-12d3-a456-426614174000",
+      action: "created",
+    });
+
+    // This throws validation error when emitted
+    try {
+      await userActionEvent({
+        userId: "invalid-uuid",
+        action: "unknown",
+      });
+    } catch (error) {
+      // "Event payload validation failed for app.events.userAction: ..."
+    }
+  },
+});
+```
+
+#### Middleware Config Validation (Fail Fast)
+
+Add a `configSchema` to middleware to validate configurations. Like resources, **validation happens immediately when `.with()` is called**:
+
+```typescript
+const timingConfigSchema = z.object({
+  timeout: z.number().positive(),
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  logSuccessful: z.boolean().default(true),
+});
+
+const timingMiddleware = middleware({
+  id: "app.middleware.timing",
+  configSchema: timingConfigSchema, // Validation on .with()
+  run: async ({ next }, _, config) => {
+    const start = Date.now();
+    try {
+      const result = await next();
+      const duration = Date.now() - start;
+      if (config.logSuccessful && config.logLevel === "debug") {
+        console.log(`Operation completed in ${duration}ms`);
+      }
+      return result;
+    } catch (error) {
+      const duration = Date.now() - start;
+      console.log(`Operation failed after ${duration}ms`);
+      throw error;
+    }
+  },
+});
+
+// Validation happens here, not during execution!
+try {
+  const configuredMiddleware = timingMiddleware.with({
+    timeout: -5, // Invalid: negative timeout
+    logLevel: "invalid", // Invalid: not in enum
+  });
+} catch (error) {
+  // "Middleware config validation failed for app.middleware.timing: ..."
+}
+
+const myTask = task({
+  id: "app.tasks.example",
+  middleware: [
+    timingMiddleware.with({
+      timeout: 5000,
+      logLevel: "debug",
+      logSuccessful: true,
+    }),
+  ],
+  run: async () => "success",
+});
+```
+
+#### Advanced Validation Features
+
+Any validation library features work with the generic interface. Here's an example with transformations and refinements:
+
+```typescript
+const advancedSchema = z
+  .object({
+    userId: z.string().uuid(),
+    amount: z.string().transform((val) => parseFloat(val)), // Transform string to number
+    currency: z.enum(["USD", "EUR", "GBP"]),
+    metadata: z.record(z.string()).optional(),
+  })
+  .refine((data) => data.amount > 0, {
+    message: "Amount must be positive",
+    path: ["amount"],
+  });
+
+const paymentTask = task({
+  id: "app.tasks.payment",
+  inputSchema: advancedSchema,
+  run: async (payment) => {
+    // payment.amount is now a number (transformed from string)
+    // All validations have passed
+    return processPayment(payment);
+  },
+});
+```
+
+#### Error Handling
+
+Validation errors are thrown with clear, descriptive messages that include the component ID:
+
+```typescript
+// Task validation error format:
+// "Task input validation failed for {taskId}: {validationErrorMessage}"
+
+// Resource validation error format (thrown on .with() call):
+// "Resource config validation failed for {resourceId}: {validationErrorMessage}"
+
+// Event validation error format (thrown on emit):
+// "Event payload validation failed for {eventId}: {validationErrorMessage}"
+
+// Middleware validation error format (thrown on .with() call):
+// "Middleware config validation failed for {middlewareId}: {validationErrorMessage}"
+```
+
+#### Using Different Validation Libraries
+
+The framework works with any validation library that implements the `IValidationSchema<T>` interface:
+
+```typescript
+// Zod (works directly)
+import { z } from "zod";
+const zodSchema = z.string().email();
+
+// Yup (with wrapper)
+import * as yup from "yup";
+const yupSchema = {
+  parse: (input: unknown) => yup.string().email().validateSync(input),
+};
+
+// Joi (with wrapper)
+import Joi from "joi";
+const joiSchema = {
+  parse: (input: unknown) => {
+    const { error, value } = Joi.string().email().validate(input);
+    if (error) throw error;
+    return value;
+  },
+};
+
+// Custom validation
+const customSchema = {
+  parse: (input: unknown) => {
+    if (typeof input !== "string" || !input.includes("@")) {
+      throw new Error("Must be a valid email");
+    }
+    return input;
+  },
+};
+```
+
+#### When to Use Validation
+
+- **API boundaries**: Validating user inputs from HTTP requests
+- **External data**: Processing data from files, databases, or APIs
+- **Configuration**: Ensuring environment variables and configs are correct (fail fast)
+- **Event payloads**: Validating data in event-driven architectures
+- **Middleware configs**: Validating middleware settings at registration time (fail fast)
+
+#### Performance Notes
+
+- Validation only runs when schemas are provided (zero overhead when not used)
+- Resource and middleware validation happens once at registration time (`.with()`)
+- Task and event validation happens at runtime
+- Consider the validation library's performance characteristics for your use case
+- All major validation libraries are optimized for runtime validation
+
+#### TypeScript Integration
+
+While runtime validation happens with your chosen library, TypeScript still enforces compile-time types. For the best experience:
+
+```typescript
+// With Zod, define your type and schema together
+type UserData = z.infer<typeof userSchema>;
+
+const userSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const createUser = task({
+  inputSchema: userSchema,
+  run: async (input: UserData) => {
+    // Both runtime validation AND compile-time typing
+    return { id: "user-123", ...input };
+  },
+});
+```
+
 ### Internal Services: For When You Need Direct Access
 
 We expose the internal services for advanced use cases (but try not to use them unless you really need to):

package/dist/define.d.ts

@@ -5,9 +5,9 @@
  * metadata: anonymous IDs, file path tags (for better debugging), lifecycle
  * events, and global middleware flags. See README for high-level concepts.
  */
-import { ITask, ITaskDefinition, IResource, IResourceWithConfig, IResourceDefinition, IEventDefinition, IMiddlewareDefinition, DependencyMapType, DependencyValuesType, IMiddleware, IEvent, RegisterableItems, ITag, ITagDefinition } from "./defs";
-export declare function defineTask<Input = undefined, Output extends Promise<any> = any, Deps extends DependencyMapType = any, TOn extends "*" | IEventDefinition | undefined = undefined>(taskConfig: ITaskDefinition<Input, Output, Deps, TOn>): ITask<Input, Output, Deps, TOn>;
-export declare function defineResource<TConfig = void, TValue = any, TDeps extends DependencyMapType = {}, TPrivate = any>(constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate>): IResource<TConfig, TValue, TDeps, TPrivate>;
+import { ITask, ITaskDefinition, IResource, IResourceWithConfig, IResourceDefinition, IEventDefinition, IMiddlewareDefinition, DependencyMapType, DependencyValuesType, IMiddleware, IEvent, RegisterableItems, ITag, ITagDefinition, ITaskMeta, IResourceMeta } from "./defs";
+export declare function defineTask<Input = undefined, Output extends Promise<any> = any, Deps extends DependencyMapType = any, TOn extends "*" | IEventDefinition | undefined = undefined, TMeta extends ITaskMeta = any>(taskConfig: ITaskDefinition<Input, Output, Deps, TOn, TMeta>): ITask<Input, Output, Deps, TOn, TMeta>;
+export declare function defineResource<TConfig = void, TValue extends Promise<any> = Promise<any>, TDeps extends DependencyMapType = {}, TPrivate = any, TMeta extends IResourceMeta = any>(constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate, any, any, TMeta>): IResource<TConfig, TValue, TDeps, TPrivate, TMeta>;
 /**
  * Creates an "index" resource which groups multiple registerable items under
  * a single dependency. The resulting resource registers every item, depends
@@ -16,7 +16,7 @@ export declare function defineResource<TConfig = void, TValue = any, TDeps exten
  */
 export declare function defineIndex<T extends Record<string, RegisterableItems>, D extends {
     [K in keyof T]: T[K] extends IResourceWithConfig<any, any, any> ? T[K]["resource"] : T[K];
-} & DependencyMapType>(items: T): IResource<void, DependencyValuesType<D>, D>;
+} & DependencyMapType>(items: T): IResource<void, Promise<DependencyValuesType<D>>, D>;
 export declare function defineEvent<TPayload = void>(config?: IEventDefinition<TPayload>): IEvent<TPayload>;
 export type MiddlewareEverywhereOptions = {
     /**
@@ -46,4 +46,4 @@ export declare function defineOverride<T extends IMiddleware<any, any>>(base: T,
  * - `.with(config)` to create configured instances
  * - `.extract(tags)` to extract this tag from a list of tags
  */
-export declare function defineTag<TConfig = void>(definition: ITagDefinition<TConfig>): ITag<TConfig>;
+export declare function defineTag<TConfig = void, TEnforceContract = void>(definition: ITagDefinition<TConfig, TEnforceContract>): ITag<TConfig, TEnforceContract>;