feat: add priority to hooks and a blackboard for plugins

components/controller.ts

@@ -380,6 +380,9 @@ export class Controller {
     public locationsWithETA = new Set<string>()
     public parentsWithETA = new Set<string>()
 
+    // A place for plugins to share data.
+    public blackboard: unknown = {}
+
     /**
      * The constructor.
      */

components/hooksImpl.ts

@@ -56,7 +56,15 @@ export class HookMap<Hook> {
 /**
  * The options for a hook. Will either be just the name (as a string), or an object containing the additional options.
  */
-export type TapOptions = string | { name: string; context: boolean }
+export type TapOptions =
+    | string
+    | {
+          name: string
+          // Whether the context object (which can be modified) should be used. Defaults to false.
+          enableContext?: boolean
+          // Priority of the tap, higher goes first. Defaults to 0.
+          priority?: number
+      }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AsArray<T> = T extends any[] ? T : [T]
@@ -68,12 +76,14 @@ interface Tap<T, R> {
     name: string
     func: (...args: AsArray<T>) => R
     enableContext: boolean
+    priority: number
 }
 
 /**
  * The structure of an intercept.
  *
  * @see name
+ * @see priority
  * @see call
  * @see tap
  */
@@ -83,6 +93,11 @@ export interface Intercept<Params, Return> {
      */
     name: string
 
+    /**
+     * The priority of the intercept, higher goes first.
+     */
+    priority: number
+
     /**
      * A function called just after the hook is called, and before all taps run.
      *
@@ -120,6 +135,12 @@ export abstract class BaseImpl<Params, Return = void> {
      */
     public intercept(intercept: Intercept<Params, Return>): void {
         this._intercepts.push(intercept)
+
+        this._intercepts.sort((a, b) => {
+            if (a.priority !== b.priority) return b.priority - a.priority
+
+            return a.name.localeCompare(b.name)
+        })
     }
 
     /**
@@ -138,7 +159,11 @@ export abstract class BaseImpl<Params, Return = void> {
                 ? nameOrOptions
                 : nameOrOptions.name
         const enableContext =
-            typeof nameOrOptions === "string" ? false : nameOrOptions.context
+            typeof nameOrOptions === "string"
+                ? false
+                : nameOrOptions.enableContext ?? false
+        const priority =
+            typeof nameOrOptions === "string" ? 0 : nameOrOptions.priority ?? 0
 
         for (const intercept of this._intercepts) {
             if (intercept.tap) {
@@ -150,6 +175,13 @@ export abstract class BaseImpl<Params, Return = void> {
             name,
             func: consumer,
             enableContext,
+            priority,
+        })
+
+        this._taps.sort((a, b) => {
+            if (a.priority !== b.priority) return b.priority - a.priority
+
+            return a.name.localeCompare(b.name)
         })
     }