@bluelibs/runner 2.2.3 → 3.0.0

package/src/__tests__/typesafety.test.ts

@@ -1,4 +1,9 @@
-import { defineEvent, defineTask, defineResource } from "../define";
+import {
+  defineEvent,
+  defineTask,
+  defineResource,
+  defineMiddleware,
+} from "../define";
 import { RegisterableItems } from "../defs";
 
 describe("typesafety", () => {
@@ -7,6 +12,35 @@ describe("typesafety", () => {
       message: string;
     };
 
+    const middleware = defineMiddleware({
+      id: "middleware",
+      run: async (input, deps) => {
+        return input;
+      },
+    });
+
+    type MiddlewareConfig = {
+      message: string;
+    };
+
+    type MiddlewareOptionalConfig = {
+      message?: string;
+    };
+
+    const middlewareWithConfig = defineMiddleware({
+      id: "middleware.config",
+      run: async (input, deps, config: MiddlewareConfig) => {
+        return input;
+      },
+    });
+
+    const middlewareWithOptionalConfig = defineMiddleware({
+      id: "middleware.optional.config",
+      run: async (input, deps, config: MiddlewareOptionalConfig) => {
+        return input;
+      },
+    });
+
     const event = defineEvent<{ message: string }>({
       id: "event",
     });
@@ -58,6 +92,18 @@ describe("typesafety", () => {
 
     const testResource = defineResource({
       id: "test.resource",
+      middleware: [
+        middleware,
+        // @ts-expect-error
+        middlewareWithConfig,
+        middlewareWithConfig.with({ message: "Hello, World!" }),
+        // @ts-expect-error
+        middlewareWithConfig.with({ message: 123 }),
+        middlewareWithOptionalConfig,
+        middlewareWithOptionalConfig.with({ message: "Hello, World!" }),
+        // @ts-expect-error
+        middlewareWithOptionalConfig.with({ message: 123 }),
+      ],
       dependencies: { task, dummyResource, event },
       init: async (_, deps) => {
         const result = await deps.task({
@@ -82,6 +128,13 @@ describe("typesafety", () => {
         deps.task2;
       },
       register: [
+        middleware,
+        middlewareWithConfig,
+        middlewareWithOptionalConfig,
+        middlewareWithOptionalConfig.with({ message: "Hello, World!" }),
+        middlewareWithConfig.with({ message: "Hello, World!" }),
+        // @ts-expect-error
+        middlewareWithConfig.with({ message: 123 }),
         dummyResourceNoConfig,
         // @ts-expect-error
         dummyResourceNoConfig.with("hello"),
@@ -141,42 +194,4 @@ describe("typesafety", () => {
 
     expect(true).toBe(true);
   });
-
-  it("should work with resources that register other resources and don't infer an any to them", async () => {
-    const resourceBase = defineResource({
-      id: "task",
-      init: async (_, deps) => {
-        deps.resource;
-        return "";
-      },
-      dependencies: () => ({
-        resource,
-      }),
-    });
-
-    const resource = defineResource({
-      id: "resource",
-      register: [],
-    });
-
-    resource.register = [resourceBase];
-
-    // @ts-expect-error
-    resource.DOES_NOT_EXIST;
-
-    expect(true).toBe(true);
-  });
-
-  it("should work to unit test with void arguments?", async () => {
-    const resourceBase = defineResource({
-      id: "task",
-      init: async (_, deps) => {
-        return "";
-      },
-    });
-
-    if (resourceBase.init) {
-      resourceBase.init(undefined, {});
-    }
-  });
 });

package/src/context.ts

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { defineMiddleware } from "./define";
+import { IMiddleware, IMiddlewareConfigured } from "./defs";
+import { requireContextMiddleware } from "./globals/middleware/requireContext.middleware";
+
+/**
+ * Error thrown whenever a requested context is not available.
+ */
+export class ContextError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ContextError";
+  }
+}
+
+/**
+ * The generic Context object returned by `createContext`.
+ */
+export interface Context<T> {
+  /** unique symbol used as key in the AsyncLocalStorage map */
+  readonly id: symbol;
+  /** Retrieve the current context value or throw */
+  use(): T;
+  /**
+   * Provide a value for this context during the lifetime of `fn()`
+   */
+  provide<R>(value: T, fn: () => Promise<R> | R): Promise<R> | R;
+  /**
+   * Generates a middleware that guarantees the context exists (and optionally
+   * enforces that certain keys are present on the context object).
+   */
+  require<K extends keyof T = never>(
+    keys?: K[]
+  ): IMiddlewareConfigured<{ context: Context<T> }>;
+}
+
+// The internal storage maps Context identifiers (symbols) to their values
+export const storage = new AsyncLocalStorage<Map<symbol, unknown>>();
+
+/** Returns the currently active store or undefined. */
+function getCurrentStore(): Map<symbol, unknown> | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Create a new typed Context. The result contains helpers similar to React’s
+ * Context API but adapted for async usage in Runner.
+ */
+export function createContext<T>(name: string = "runner.context"): Context<T> {
+  const ctxId = Symbol(name);
+
+  function use(): T {
+    const store = getCurrentStore();
+    if (!store || !store.has(ctxId)) {
+      throw new ContextError(
+        `Context not available for symbol ${ctxId.toString()}`
+      );
+    }
+    return store.get(ctxId) as T;
+  }
+
+  function provide<R>(value: T, fn: () => Promise<R> | R): Promise<R> | R {
+    const currentStore = getCurrentStore();
+    const map = currentStore
+      ? new Map(currentStore)
+      : new Map<symbol, unknown>();
+    map.set(ctxId, value);
+
+    return storage.run(map, fn as any);
+  }
+
+  /**
+   * Generates a middleware that guarantees the context exists (and optionally
+   * enforces that certain keys are present on the context object).
+   */
+  function require(): IMiddlewareConfigured {
+    return requireContextMiddleware.with({ context: this as Context<T> });
+  }
+
+  return {
+    id: ctxId,
+    use,
+    provide,
+    require,
+  };
+}

package/src/define.ts

@@ -15,6 +15,8 @@ import {
   IEvent,
   IEventDefinitionConfig,
   symbolEvent,
+  RegisterableItems,
+  symbolMiddlewareConfigured,
 } from "./defs";
 import { Errors } from "./errors";
 import { getCallerFile } from "./tools/getCallerFile";
@@ -38,6 +40,7 @@ export function defineTask<
     middleware: taskConfig.middleware || [],
     run: taskConfig.run,
     on: taskConfig.on,
+    listenerOrder: taskConfig.listenerOrder,
     events: {
       beforeRun: {
         ...defineEvent({
@@ -67,10 +70,10 @@ export function defineResource<
   TConfig = void,
   TValue = any,
   TDeps extends DependencyMapType = {},
-  THooks = any
+  TPrivate = any
 >(
-  constConfig: IResourceDefinition<TConfig, TValue, TDeps, THooks>
-): IResource<TConfig, TValue, TDeps> {
+  constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate>
+): IResource<TConfig, TValue, TDeps, TPrivate> {
   const filePath = getCallerFile();
   return {
     [symbols.resource]: true,
@@ -80,7 +83,8 @@ export function defineResource<
     dispose: constConfig.dispose,
     register: constConfig.register || [],
     overrides: constConfig.overrides || [],
-    init: constConfig.init || (async (...args: any[]) => undefined as TValue),
+    init: constConfig.init,
+    context: constConfig.context,
     with: function (config: TConfig) {
       return {
         [symbols.resourceWithConfig]: true,
@@ -115,6 +119,44 @@ export function defineResource<
   };
 }
 
+/**
+ * Creates an "index" resource which groups multiple registerable items under
+ * a single dependency. The resulting resource registers every item, depends
+ * on the same items, and returns the resolved dependency map so users can
+ * access them naturally: `deps.services.myTask()` or `deps.services.myResource`.
+ */
+export 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> {
+  const dependencies = {} as D;
+  const register: RegisterableItems[] = [];
+
+  for (const key of Object.keys(items) as (keyof T)[]) {
+    const item = items[key];
+    register.push(item);
+
+    if (isResourceWithConfig(item)) {
+      (dependencies as any)[key] = item.resource;
+    } else {
+      (dependencies as any)[key] = item as any;
+    }
+  }
+
+  return defineResource({
+    id: `index.${Math.random().toString(36).slice(2)}`,
+    register,
+    dependencies,
+    async init(_, deps) {
+      return deps as any;
+    },
+  });
+}
+
 export function defineEvent<TPayload = any>(
   config: IEventDefinitionConfig<TPayload>
 ): IEventDefinition<TPayload> {
@@ -125,24 +167,52 @@ export function defineEvent<TPayload = any>(
   };
 }
 
-export function defineMiddleware<TDeps extends DependencyMapType = {}>(
-  config: IMiddlewareDefinition<TDeps>
-): IMiddleware<TDeps> {
+export type MiddlewareEverywhereOptions = {
+  /**
+   * Enable this for tasks. Default is true.
+   */
+  tasks?: boolean;
+  /**
+   * Enable this for resources. Default is true.
+   */
+  resources?: boolean;
+};
+
+export function defineMiddleware<
+  TConfig extends Record<string, any>,
+  TDependencies extends DependencyMapType
+>(
+  middlewareDef: IMiddlewareDefinition<TConfig, TDependencies>
+): IMiddleware<TConfig, TDependencies> {
   const object = {
     [symbols.filePath]: getCallerFile(),
     [symbols.middleware]: true,
-    ...config,
-    dependencies: config.dependencies || ({} as TDeps),
-  };
+    config: {} as TConfig,
+    ...middlewareDef,
+    dependencies: middlewareDef.dependencies || ({} as TDependencies),
+  } as IMiddleware<TConfig, TDependencies>;
 
   return {
     ...object,
-    global() {
+    with: (config: TConfig) => {
+      return {
+        ...object,
+        [symbolMiddlewareConfigured]: true,
+        config: {
+          ...object.config,
+          ...config,
+        },
+      };
+    },
+    everywhere(options: MiddlewareEverywhereOptions = {}) {
+      const { tasks = true, resources = true } = options;
+
       return {
         ...object,
-        [symbols.middlewareGlobal]: true,
-        global() {
-          throw Errors.middlewareAlreadyGlobal(config.id);
+        [symbols.middlewareEverywhereTasks]: tasks,
+        [symbols.middlewareEverywhereResources]: resources,
+        everywhere() {
+          throw Errors.middlewareAlreadyGlobal(middlewareDef.id);
         },
       };
     },

package/src/defs.ts

@@ -1,3 +1,5 @@
+export { ICacheInstance } from "./globals/middleware/cache.middleware";
+
 export const symbolTask: unique symbol = Symbol("runner.task");
 export const symbolResource: unique symbol = Symbol("runner.resource");
 export const symbolResourceWithConfig: unique symbol = Symbol(
@@ -5,11 +7,22 @@ export const symbolResourceWithConfig: unique symbol = Symbol(
 );
 export const symbolEvent: unique symbol = Symbol("runner.event");
 export const symbolMiddleware: unique symbol = Symbol("runner.middleware");
+export const symbolMiddlewareConfigured: unique symbol = Symbol(
+  "runner.middlewareConfigured"
+);
 export const symbolMiddlewareGlobal: unique symbol = Symbol(
   "runner.middlewareGlobal"
 );
+export const symbolMiddlewareEverywhereTasks: unique symbol = Symbol(
+  "runner.middlewareGlobalTasks"
+);
+export const symbolMiddlewareEverywhereResources: unique symbol = Symbol(
+  "runner.middlewareGlobalResources"
+);
 
 export const symbolFilePath: unique symbol = Symbol("runner.filePath");
+export const symbolDispose: unique symbol = Symbol("runner.dispose");
+export const symbolStore: unique symbol = Symbol("runner.store");
 
 export const symbols = {
   task: symbolTask,
@@ -17,8 +30,11 @@ export const symbols = {
   resourceWithConfig: symbolResourceWithConfig,
   event: symbolEvent,
   middleware: symbolMiddleware,
-  middlewareGlobal: symbolMiddlewareGlobal,
+  middlewareEverywhereTasks: symbolMiddlewareEverywhereTasks,
+  middlewareEverywhereResources: symbolMiddlewareEverywhereResources,
   filePath: symbolFilePath,
+  dispose: symbolDispose,
+  store: symbolStore,
 };
 
 export interface IMeta {
@@ -83,15 +99,22 @@ type OptionalOrVoidOrAnything<T> = IsVoid<T> extends true
   ? Optional<T>
   : T;
 
+type OnlyOptionalFields<T> = {} extends T ? true : false;
+
 // RegisterableItems Type with Conditional Inclusion
 export type RegisterableItems<T = any> =
   | IResourceWithConfig<any>
-  // | IResource<void, any, any>
-  | IResource<OptionalOrVoidOrAnything<T>, any, any>
+  | IResource<void, any, any, any> // For void configs
+  | IResource<{ [K in any]?: any }, any, any, any> // For optional config
   | ITaskDefinition<any, any, any, any>
   | IMiddlewareDefinition<any>
   | IEventDefinition<any>;
 
+export type MiddlewareAttachments =
+  | IMiddleware<void>
+  | IMiddleware<{ [K in any]?: any }>
+  | IMiddlewareConfigured<any>;
+
 export interface ITaskDefinition<
   TInput = any,
   TOutput extends Promise<any> = any,
@@ -100,7 +123,7 @@ export interface ITaskDefinition<
 > {
   id: string;
   dependencies?: TDependencies | (() => TDependencies);
-  middleware?: IMiddlewareDefinition[];
+  middleware?: MiddlewareAttachments[];
   /**
    * Listen to events in a simple way
    */
@@ -115,11 +138,6 @@ export interface ITaskDefinition<
     input: TOn extends undefined
       ? TInput
       : IEvent<TOn extends "*" ? any : ExtractEventParams<TOn>>,
-    // input: TOn extends "*"
-    //   ? IEvent<any>
-    //   : TEventDefinitionInput extends null | void
-    //   ? TInput
-    // : IEvent<TEventDefinitionInput>,
     dependencies: DependencyValuesType<TDependencies>
   ) => TOutput;
 }
@@ -130,7 +148,8 @@ export type BeforeRunEventPayload<TInput> = {
 
 export type AfterRunEventPayload<TInput, TOutput> = {
   input: TInput;
-  output: TOutput;
+  output: TOutput extends Promise<infer U> ? U : TOutput;
+  setOutput(newOutput: TOutput extends Promise<infer U> ? U : TOutput): void;
 };
 
 export type OnErrorEventPayload = {
@@ -161,7 +180,7 @@ export interface ITask<
 > extends ITaskDefinition<TInput, TOutput, TDependencies, TOn> {
   dependencies: TDependencies | (() => TDependencies);
   computedDependencies?: DependencyValuesType<TDependencies>;
-  middleware: IMiddlewareDefinition[];
+  middleware: MiddlewareAttachments[];
   /**
    * These events are automatically populated after the task has been defined.
    */
@@ -171,18 +190,20 @@ export interface ITask<
     onError: IEventDefinition<OnErrorEventPayload>;
   };
 }
-
-type IsExactlyUnknown<T> = unknown extends T
-  ? T extends unknown
-    ? true
-    : false
-  : false;
-
 // Resource interfaces
+// Conditional type to determine the value type based on whether init is present
+type ResourceValueType<T> = T extends { init: any }
+  ? T["init"] extends (...args: any[]) => Promise<infer R>
+    ? R
+    : unknown
+  : undefined;
+
 export interface IResourceDefinition<
   TConfig = any,
   TValue = unknown,
   TDependencies extends DependencyMapType = {},
+  TContext = any,
+  THooks = any,
   TRegisterableItems = any
 > {
   id: string;
@@ -191,36 +212,38 @@ export interface IResourceDefinition<
     | Array<RegisterableItems>
     | ((config: TConfig) => Array<RegisterableItems>);
   init?: (
+    this: any,
     config: TConfig,
-    dependencies: DependencyValuesType<TDependencies>
+    dependencies: DependencyValuesType<TDependencies>,
+    context: TContext
   ) => Promise<TValue>;
   /**
    * Clean-up function for the resource. This is called when the resource is no longer needed.
    *
-   * @param value The value of the resource
+   * @param value The value of the resource (undefined if no init method)
    * @param config The configuration it received
    * @param dependencies The dependencies it needed
-   * @returns
+   * @returns Promise<void>
    */
   dispose?: (
+    this: any,
     value: TValue,
     config: TConfig,
-    dependencies: DependencyValuesType<TDependencies>
-  ) => Promise<TValue>;
+    dependencies: DependencyValuesType<TDependencies>,
+    context: TContext
+  ) => Promise<void>;
   meta?: IResourceMeta;
   overrides?: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
-  middleware?: IMiddlewareDefinition[];
+  middleware?: MiddlewareAttachments[];
+  context?: () => TContext;
 }
 
 export interface IResource<
   TConfig = void,
   TValue = any,
-  TDependencies extends DependencyMapType = any
-> extends IResourceDefinition<TConfig, TValue, TDependencies> {
-  init: (
-    config: TConfig,
-    dependencies: DependencyValuesType<TDependencies>
-  ) => Promise<TValue>;
+  TDependencies extends DependencyMapType = any,
+  TContext = any
+> extends IResourceDefinition<TConfig, TValue, TDependencies, TContext> {
   with(config: TConfig): IResourceWithConfig<TConfig, TValue, TDependencies>;
   register:
     | Array<RegisterableItems>
@@ -234,7 +257,7 @@ export interface IResource<
     onError: IEventDefinition<OnErrorEventPayload>;
   };
   overrides: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
-  middleware: IMiddlewareDefinition[];
+  middleware: MiddlewareAttachments[];
 }
 
 export interface IResourceWithConfig<
@@ -283,21 +306,39 @@ export interface IEventDefinition<TPayload = void> {
 }
 
 export interface IMiddlewareDefinition<
+  TConfig = any,
   TDependencies extends DependencyMapType = any
 > {
   id: string;
   dependencies?: TDependencies | (() => TDependencies);
   run: (
     input: IMiddlewareExecutionInput,
-    dependencies: DependencyValuesType<TDependencies>
+    dependencies: DependencyValuesType<TDependencies>,
+    config: TConfig
   ) => Promise<any>;
   meta?: IMiddlewareMeta;
 }
 
-export interface IMiddleware<TDependencies extends DependencyMapType = any>
-  extends IMiddlewareDefinition<TDependencies> {
+export interface IMiddleware<
+  TConfig = any,
+  TDependencies extends DependencyMapType = any
+> extends IMiddlewareDefinition<TConfig, TDependencies> {
+  [symbolMiddleware]: true;
+  [symbolMiddlewareConfigured]?: boolean;
+  [symbolMiddlewareEverywhereTasks]?: boolean;
+  [symbolMiddlewareEverywhereResources]?: boolean;
+
   dependencies: TDependencies | (() => TDependencies);
-  global(): IMiddleware<TDependencies>;
+  everywhere(): IMiddleware<TConfig, TDependencies>;
+  config: TConfig;
+  with: (config: TConfig) => IMiddlewareConfigured<TConfig, TDependencies>;
+}
+
+export interface IMiddlewareConfigured<
+  TConfig = any,
+  TDependencies extends DependencyMapType = any
+> extends IMiddleware<TConfig, TDependencies> {
+  [symbolMiddlewareConfigured]: true;
 }
 
 export interface IMiddlewareDefinitionConfigured<
@@ -307,12 +348,21 @@ export interface IMiddlewareDefinitionConfigured<
   config?: C;
 }
 
-export interface IMiddlewareExecutionInput {
-  taskDefinition?: ITask;
-  resourceDefinition?: IResource;
-  config?: any;
-  input?: any;
-  next: (taskInputOrResourceConfig?: any) => Promise<any>;
+export interface IMiddlewareExecutionInput<
+  TTaskInput = any,
+  TResourceConfig = any
+> {
+  task?: {
+    definition: ITask<TTaskInput>;
+    input: TTaskInput;
+  };
+  resource?: {
+    definition: IResource<TResourceConfig>;
+    config: TResourceConfig;
+  };
+  next: (
+    taskInputOrResourceConfig?: TTaskInput | TResourceConfig
+  ) => Promise<any>;
 }
 
 export interface IHookDefinition<

package/src/errors.ts

@@ -18,7 +18,9 @@ export const Errors = {
     new Error(`Event "${id}" not found. Did you forget to register it?`),
 
   middlewareAlreadyGlobal: (id: string) =>
-    new Error("Cannot call global on a global middleware: " + id),
+    new Error(
+      "Cannot call .everywhere() on an already global middleware: " + id
+    ),
 
   locked: (what: string) =>
     new Error(`Cannot modify the ${what} when it is locked.`),