@bluelibs/runner 3.3.2 → 3.4.0

package/src/__tests__/validation-interface.test.ts

@@ -0,0 +1,428 @@
+import { defineTask, defineResource, defineEvent, defineMiddleware } from "../define";
+import { run } from "../run";
+import { IValidationSchema } from "../defs";
+
+// Simple mock validation schemas for testing the interface
+class MockValidationSchema<T> implements IValidationSchema<T> {
+  constructor(
+    private validator: (input: unknown) => T,
+    private errorMessage?: string
+  ) {}
+
+  parse(input: unknown): T {
+    try {
+      return this.validator(input);
+    } catch (error) {
+      throw new Error(this.errorMessage || "Validation failed");
+    }
+  }
+}
+
+// Helper functions to create mock schemas similar to Zod
+const mockSchema = {
+  object: <T extends Record<string, any>>(shape: Record<keyof T, string>): IValidationSchema<T> => {
+    return new MockValidationSchema((input: unknown) => {
+      if (typeof input !== "object" || input === null) {
+        throw new Error("Expected object");
+      }
+      const obj = input as any;
+      for (const [key, expectedType] of Object.entries(shape)) {
+        if (expectedType === "string" && typeof obj[key] !== "string") {
+          throw new Error(`${key} must be string`);
+        }
+        if (expectedType === "number" && typeof obj[key] !== "number") {
+          throw new Error(`${key} must be number`);
+        }
+        if (expectedType === "boolean" && typeof obj[key] !== "boolean") {
+          throw new Error(`${key} must be boolean`);
+        }
+      }
+      return obj as T;
+    });
+  },
+  
+  string: (): IValidationSchema<string> => {
+    return new MockValidationSchema((input: unknown) => {
+      if (typeof input !== "string") {
+        throw new Error("Expected string");
+      }
+      return input;
+    });
+  },
+  
+  number: (): IValidationSchema<number> => {
+    return new MockValidationSchema((input: unknown) => {
+      if (typeof input !== "number") {
+        throw new Error("Expected number");
+      }
+      return input;
+    });
+  },
+  
+  boolean: (): IValidationSchema<boolean> => {
+    return new MockValidationSchema((input: unknown) => {
+      if (typeof input !== "boolean") {
+        throw new Error("Expected boolean");
+      }
+      return input;
+    });
+  },
+
+  transform: <T, U>(schema: IValidationSchema<T>, transformer: (value: T) => U): IValidationSchema<U> => {
+    return new MockValidationSchema((input: unknown) => {
+      const validated = schema.parse(input);
+      return transformer(validated);
+    });
+  },
+
+  withDefaults: <T>(defaultValue: T): IValidationSchema<T> => {
+    return new MockValidationSchema((input: unknown) => {
+      return input === undefined ? defaultValue : (input as T);
+    });
+  },
+};
+
+describe("Generic Validation Interface", () => {
+  describe("Task Input Validation", () => {
+    it("should validate task input successfully with valid data", async () => {
+      const userSchema = mockSchema.object<{
+        name: string;
+        age: number;
+      }>({
+        name: "string",
+        age: "number",
+      });
+
+      const createUserTask = defineTask({
+        id: "task.createUser",
+        inputSchema: userSchema,
+        run: async (input) => {
+          return `Created user ${(input as any).name}`;
+        },
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [createUserTask],
+        dependencies: { createUserTask },
+        init: async (_, { createUserTask }) => {
+          const result = await createUserTask({
+            name: "John Doe",
+            age: 30,
+          });
+          expect(result).toBe("Created user John Doe");
+          return result;
+        },
+      });
+
+      await run(app);
+    });
+
+    it("should throw validation error for invalid task input", async () => {
+      const userSchema = new MockValidationSchema((input: unknown) => {
+        if (typeof input !== "object" || input === null) {
+          throw new Error("Expected object");
+        }
+        const obj = input as any;
+        if (typeof obj.name !== "string") {
+          throw new Error("name must be string");
+        }
+        if (typeof obj.age !== "number" || obj.age < 0) {
+          throw new Error("age must be positive number");
+        }
+        return obj;
+      });
+
+      const createUserTask = defineTask({
+        id: "task.createUser.invalid",
+        inputSchema: userSchema,
+        run: async (input) => {
+          return `Created user ${(input as any).name}`;
+        },
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [createUserTask],
+        dependencies: { createUserTask },
+        init: async (_, { createUserTask }) => {
+          await createUserTask({
+            name: "John Doe",
+            age: -5, // Invalid: negative age
+          });
+        },
+      });
+
+      await expect(run(app)).rejects.toThrow(/Task input validation failed/);
+    });
+
+    it("should transform input data when schema supports it", async () => {
+      const stringToNumberSchema = mockSchema.transform(
+        mockSchema.string(),
+        (val: string) => parseInt(val, 10)
+      );
+
+      const mathTask = defineTask({
+        id: "task.math",
+        inputSchema: stringToNumberSchema,
+        run: async (input: number) => {
+          expect(typeof input).toBe("number");
+          return input * 2;
+        },
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [mathTask],
+        dependencies: { mathTask },
+        init: async (_, { mathTask }) => {
+          const result = await (mathTask as any)("42"); // String input should be transformed to number
+          expect(result).toBe(84);
+          return result;
+        },
+      });
+
+      await run(app);
+    });
+  });
+
+  describe("Resource Config Validation", () => {
+    it("should validate resource config when .with() is called (fail fast)", async () => {
+      const configSchema = new MockValidationSchema((input: unknown) => {
+        if (typeof input !== "object" || input === null) {
+          throw new Error("Expected object");
+        }
+        const obj = input as any;
+        if (typeof obj.host !== "string") {
+          throw new Error("host must be string");
+        }
+        if (typeof obj.port !== "number" || obj.port < 1 || obj.port > 65535) {
+          throw new Error("port must be number between 1-65535");
+        }
+        return obj;
+      });
+
+      const databaseResource = defineResource({
+        id: "resource.database",
+        configSchema: configSchema,
+        init: async (config) => {
+          return {
+            connect: () => `Connected to ${(config as any).host}:${(config as any).port}`,
+          };
+        },
+      });
+
+      // This should throw immediately when .with() is called, not during init
+      expect(() => {
+        databaseResource.with({
+          host: "localhost",
+          port: 99999, // Invalid: port too high
+        });
+      }).toThrow(/Resource config validation failed/);
+    });
+
+    it("should work with valid resource config", async () => {
+      const configSchema = mockSchema.object<{
+        host: string;
+        port: number;
+      }>({
+        host: "string",
+        port: "number",
+      });
+
+      const databaseResource = defineResource({
+        id: "resource.database.valid",
+        configSchema: configSchema,
+        init: async (config) => {
+          return {
+            connect: () => `Connected to ${(config as any).host}:${(config as any).port}`,
+          };
+        },
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [
+          databaseResource.with({
+            host: "localhost",
+            port: 5432,
+          }),
+        ],
+        dependencies: { database: databaseResource },
+        init: async (_, { database }) => {
+          const result = database.connect();
+          expect(result).toBe("Connected to localhost:5432");
+          return result;
+        },
+      });
+
+      await run(app);
+    });
+  });
+
+  describe("Event Payload Validation", () => {
+    it("should validate event payload when emitted", async () => {
+      const payloadSchema = new MockValidationSchema((input: unknown) => {
+        if (typeof input !== "object" || input === null) {
+          throw new Error("Expected object");
+        }
+        const obj = input as any;
+        if (typeof obj.message !== "string") {
+          throw new Error("message must be string");
+        }
+        return obj;
+      });
+
+      const testEvent = defineEvent({
+        id: "event.test",
+        payloadSchema: payloadSchema,
+      });
+
+      let receivedMessage = "";
+      const listenerTask = defineTask({
+        id: "task.listener",
+        on: testEvent,
+        run: async (event) => {
+          receivedMessage = (event.data as any).message;
+        },
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [testEvent, listenerTask],
+        dependencies: { testEvent },
+        init: async (_, { testEvent }) => {
+          // This should work with valid payload
+          await testEvent({ message: "Hello World" });
+          expect(receivedMessage).toBe("Hello World");
+
+          // This should throw with invalid payload
+          await expect(testEvent({ invalidField: 123 } as any)).rejects.toThrow(/Event payload validation failed/);
+        },
+      });
+
+      await run(app);
+    });
+  });
+
+  describe("Middleware Config Validation", () => {
+    it("should validate middleware config when .with() is called (fail fast)", async () => {
+      const configSchema = new MockValidationSchema((input: unknown) => {
+        if (typeof input !== "object" || input === null) {
+          throw new Error("Expected object");
+        }
+        const obj = input as any;
+        if (typeof obj.timeout !== "number" || obj.timeout <= 0) {
+          throw new Error("timeout must be positive number");
+        }
+        return obj;
+      });
+
+      const timingMiddleware = defineMiddleware({
+        id: "middleware.timing",
+        configSchema: configSchema,
+        run: async ({ next }, _, config) => {
+          return next();
+        },
+      });
+
+      // This should throw immediately when .with() is called
+      expect(() => {
+        timingMiddleware.with({
+          timeout: -5, // Invalid: negative timeout
+        });
+      }).toThrow(/Middleware config validation failed/);
+    });
+
+    it("should work with valid middleware config", async () => {
+      const configSchema = mockSchema.object<{
+        timeout: number;
+      }>({
+        timeout: "number",
+      });
+
+      const timingMiddleware = defineMiddleware({
+        id: "middleware.timing.valid",
+        configSchema: configSchema,
+        run: async ({ next }, _, config) => {
+          const start = Date.now();
+          const result = await next();
+          const duration = Date.now() - start;
+          expect(typeof (config as any).timeout).toBe("number");
+          return result;
+        },
+      });
+
+      const testTask = defineTask({
+        id: "task.test",
+        middleware: [timingMiddleware.with({ timeout: 5000 })],
+        run: async () => {
+          return "success";
+        },
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [timingMiddleware, testTask],
+        dependencies: { testTask },
+        init: async (_, { testTask }) => {
+          const result = await testTask();
+          expect(result).toBe("success");
+          return result;
+        },
+      });
+
+      await run(app);
+    });
+  });
+
+  describe("No Validation (Backward Compatibility)", () => {
+    it("should work without any validation schemas", async () => {
+      const task = defineTask({
+        id: "task.noValidation",
+        run: async (input: any) => {
+          return `Received: ${JSON.stringify(input)}`;
+        },
+      });
+
+      const resource = defineResource({
+        id: "resource.noValidation",
+        init: async (config: any) => {
+          return { config };
+        },
+      });
+
+      const event = defineEvent<any>({
+        id: "event.noValidation",
+      });
+
+      const middleware = defineMiddleware({
+        id: "middleware.noValidation",
+        run: async ({ next }) => next(),
+      });
+
+      const app = defineResource({
+        id: "app",
+        register: [
+          task,
+          resource.with({ anything: "goes" }),
+          event,
+          middleware,
+        ],
+        dependencies: { task, resource, event },
+        init: async (_, { task, resource, event }) => {
+          const taskResult = await task({ any: "data" });
+          expect(taskResult).toBe('Received: {"any":"data"}');
+          
+          expect(resource.config.anything).toBe("goes");
+          
+          await event({ any: "payload" }); // Should work without validation
+          
+          return "success";
+        },
+      });
+
+      await run(app);
+    });
+  });
+});

package/src/define.ts

@@ -33,8 +33,10 @@ import {
   symbolResourceWithConfig,
   symbolResource,
   symbolMiddleware,
+  ITaskMeta,
+  IResourceMeta,
 } from "./defs";
-import { Errors } from "./errors";
+import { MiddlewareAlreadyGlobalError, ValidationError } from "./errors";
 import { generateCallerIdFromFile, getCallerFile } from "./tools/getCallerFile";
 
 // Helper function to get the caller file
@@ -43,10 +45,11 @@ export function defineTask<
   Input = undefined,
   Output extends Promise<any> = any,
   Deps extends DependencyMapType = any,
-  TOn extends "*" | IEventDefinition | undefined = undefined
+  TOn extends "*" | IEventDefinition | undefined = undefined,
+  TMeta extends ITaskMeta = any
 >(
-  taskConfig: ITaskDefinition<Input, Output, Deps, TOn>
-): ITask<Input, Output, Deps, TOn> {
+  taskConfig: ITaskDefinition<Input, Output, Deps, TOn, TMeta>
+): ITask<Input, Output, Deps, TOn, TMeta> {
   /**
    * Creates a task definition.
    * - Generates an anonymous id based on file path when `id` is omitted
@@ -65,6 +68,7 @@ export function defineTask<
     run: taskConfig.run,
     on: taskConfig.on,
     listenerOrder: taskConfig.listenerOrder,
+    inputSchema: taskConfig.inputSchema,
     events: {
       beforeRun: {
         ...defineEvent({
@@ -91,19 +95,28 @@ export function defineTask<
         [symbolFilePath]: getCallerFile(),
       },
     },
-    meta: taskConfig.meta || {},
+    meta: taskConfig.meta || ({} as TMeta),
     // autorun,
   };
 }
 
 export function defineResource<
   TConfig = void,
-  TValue = any,
+  TValue extends Promise<any> = Promise<any>,
   TDeps extends DependencyMapType = {},
-  TPrivate = any
+  TPrivate = any,
+  TMeta extends IResourceMeta = any
 >(
-  constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate>
-): IResource<TConfig, TValue, TDeps, TPrivate> {
+  constConfig: IResourceDefinition<
+    TConfig,
+    TValue,
+    TDeps,
+    TPrivate,
+    any,
+    any,
+    TMeta
+  >
+): IResource<TConfig, TValue, TDeps, TPrivate, TMeta> {
   /**
    * Creates a resource definition.
    * - Generates anonymous id when omitted (resource or index flavor)
@@ -129,7 +142,17 @@ export function defineResource<
     overrides: constConfig.overrides || [],
     init: constConfig.init,
     context: constConfig.context,
+    configSchema: constConfig.configSchema,
     with: function (config: TConfig) {
+      // Validate config with schema if provided (fail fast)
+      if (this.configSchema) {
+        try {
+          config = this.configSchema.parse(config);
+        } catch (error) {
+          throw new ValidationError("Resource config", this.id, error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+      
       return {
         [symbolResourceWithConfig]: true,
         id: this.id,
@@ -164,7 +187,7 @@ export function defineResource<
         [symbolFilePath]: filePath,
       },
     },
-    meta: constConfig.meta || {},
+    meta: (constConfig.meta || {}) as TMeta,
     middleware: constConfig.middleware || [],
   };
 }
@@ -182,7 +205,7 @@ export function defineIndex<
       ? T[K]["resource"]
       : T[K];
   } & DependencyMapType
->(items: T): IResource<void, DependencyValuesType<D>, D> {
+>(items: T): IResource<void, Promise<DependencyValuesType<D>>, D> {
   // Build dependency map from given items; unwrap `.with()` to the base resource
   const dependencies = {} as D;
   const register: RegisterableItems[] = [];
@@ -263,6 +286,15 @@ export function defineMiddleware<
   return {
     ...object,
     with: (config: TConfig) => {
+      // Validate config with schema if provided (fail fast)
+      if (object.configSchema) {
+        try {
+          config = object.configSchema.parse(config);
+        } catch (error) {
+          throw new ValidationError("Middleware config", object.id, error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+      
       return {
         ...object,
         [symbolMiddlewareConfigured]: true,
@@ -280,7 +312,7 @@ export function defineMiddleware<
         [symbolMiddlewareEverywhereTasks]: tasks,
         [symbolMiddlewareEverywhereResources]: resources,
         everywhere() {
-          throw Errors.middlewareAlreadyGlobal(object.id);
+          throw new MiddlewareAlreadyGlobalError(object.id);
         },
       };
     },
@@ -343,9 +375,9 @@ export function defineOverride(
  * - `.with(config)` to create configured instances
  * - `.extract(tags)` to extract this tag from a list of tags
  */
-export function defineTag<TConfig = void>(
-  definition: ITagDefinition<TConfig>
-): ITag<TConfig> {
+export function defineTag<TConfig = void, TEnforceContract = void>(
+  definition: ITagDefinition<TConfig, TEnforceContract>
+): ITag<TConfig, TEnforceContract> {
   const id = definition.id;
 
   return {

package/src/defs.returnTag.ts

@@ -0,0 +1,91 @@
+// HasContracts<Meta> → true if contracts present, else false
+
+import { ITag, ITagWithConfig } from "./defs";
+import { IMeta } from "./defs";
+
+// Keep these param names aligned with your defs.ts: ITag<TConfig, TEnforceContract>
+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>
+      : []
+    : [];
+
+type IsNeverTuple<T extends readonly unknown[]> = T extends [] ? true : false;
+
+export type HasContracts<T extends IMeta> =
+  ExtractTagsWithNonVoidReturnTypeFromMeta<T> extends never[] ? false : true; // HasContracts and enforcement
+
+// Ensure a response type satisfies ALL contracts (intersection)
+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 // no contracts, allow as-is
+  : TResponse extends Promise<infer U>
+  ? Promise<
+      U extends ContractsIntersection<TMeta>
+        ? U
+        : ContractViolationError<TMeta, U>
+    >
+  : TResponse extends ContractsIntersection<TMeta>
+  ? TResponse
+  : ContractViolationError<TMeta, TResponse>;