hookable 5.5.2 → 6.0.0-rc.1

package/README.md

@@ -10,16 +10,8 @@ Awaitable hooks system.
 
 ## Install
 
-Using yarn:
-
-```bash
-yarn add hookable
-```
-
-Using npm:
-
 ```bash
-npm install hookable
+npx nypm i hookable
 ```
 
 ## Usage
@@ -27,34 +19,39 @@ npm install hookable
 **Method A: Create a hookable instance:**
 
 ```js
-import { createHooks } from 'hookable'
+import { Hookable } from "hookable";
 
 // Create a hookable instance
-const hooks = createHooks()
+const hooks = new Hookable();
 
 // Hook on 'hello'
-hooks.hook('hello', () => { console.log('Hello World' )})
+hooks.hook("hello", () => {
+  console.log("Hello World");
+});
 
 // Call 'hello' hook
-hooks.callHook('hello')
+hooks.callHook("hello");
 ```
 
+> [!TIP]
+> You can use `HookableCore` alternatively for less bundle and runtime footprint if simple `hook`/`callHook` functionality is only needed.
+
 **Method B: Extend your base class from Hookable:**
 
 ```js
-import { Hookable } from 'hookable'
+import { Hookable } from "hookable";
 
 export default class FooLib extends Hookable {
   constructor() {
     // Call to parent to initialize
-    super()
+    super();
     // Initialize Hookable with custom logger
     // super(consola)
   }
 
   async someFunction() {
     // Call and wait for `hook1` hooks (if any) sequential
-    await this.callHook('hook1')
+    await this.callHook("hook1");
   }
 }
 ```
@@ -62,56 +59,67 @@ export default class FooLib extends Hookable {
 **Inside plugins, register for any hook:**
 
 ```js
-const lib = new FooLib()
+const lib = new FooLib();
 
 // Register a handler for `hook2`
-lib.hook('hook2', async () => { /* ... */ })
+lib.hook("hook2", async () => {
+  /* ... */
+});
 
 // Register multiply handlers at once
 lib.addHooks({
-  hook1: async () => { /* ... */ },
-  hook2: [ /* can be also an array */ ]
-})
+  hook1: async () => {
+    /* ... */
+  },
+  hook2: [
+    /* can be also an array */
+  ],
+});
 ```
 
 **Unregistering hooks:**
 
 ```js
-const lib = new FooLib()
+const lib = new FooLib();
 
-const hook0 = async () => { /* ... */ }
-const hook1 = async () => { /* ... */ }
-const hook2 = async () => { /* ... */ }
+const hook0 = async () => {
+  /* ... */
+};
+const hook1 = async () => {
+  /* ... */
+};
+const hook2 = async () => {
+  /* ... */
+};
 
 // The hook() method returns an "unregister" function
-const unregisterHook0 = lib.hook('hook0', hook0)
-const unregisterHooks1and2 = lib.addHooks({ hook1, hook2 })
+const unregisterHook0 = lib.hook("hook0", hook0);
+const unregisterHooks1and2 = lib.addHooks({ hook1, hook2 });
 
 /* ... */
 
-unregisterHook0()
-unregisterHooks1and2()
+unregisterHook0();
+unregisterHooks1and2();
 
 // or
 
-lib.removeHooks({ hook0, hook1 })
-lib.removeHook('hook2', hook2)
+lib.removeHooks({ hook0, hook1 });
+lib.removeHook("hook2", hook2);
 ```
 
 **Triggering a hook handler once:**
 
 ```js
-const lib = new FooLib()
+const lib = new FooLib();
 
-const unregister = lib.hook('hook0', async () => {
+const unregister = lib.hook("hook0", async () => {
   // Unregister as soon as the hook is executed
-  unregister()
+  unregister();
 
   /* ... */
-})
+});
 ```
 
-
 ## Hookable class
 
 ### `constructor()`
@@ -138,10 +146,9 @@ Example:
 hookable.addHooks({
   test: {
     before: () => {},
-    after: () => {}
-  }
-})
-
+    after: () => {},
+  },
+});
 ```
 
 This registers `test:before` and `test:after` hooks at bulk.
@@ -157,6 +164,7 @@ Used by class itself to **sequentially** call handlers of a specific hook.
 If you need custom control over how hooks are called, you can provide a custom function that will receive an array of handlers of a specific hook.
 
 `callerFn` if a callback function that accepts two arguments, `hooks` and `args`:
+
 - `hooks`: Array of user hooks to be called
 - `args`: Array of arguments that should be passed each time calling a hook
 
@@ -179,19 +187,21 @@ Remove multiple hook handlers.
 Example:
 
 ```js
-const handler = async () => { /* ... */ }
+const handler = async () => {
+  /* ... */
+};
 
-hookable.hook('test:before', handler)
-hookable.addHooks({ test: { after: handler } })
+hookable.hook("test:before", handler);
+hookable.addHooks({ test: { after: handler } });
 
 // ...
 
 hookable.removeHooks({
   test: {
     before: handler,
-    after: handler
-  }
-})
+    after: handler,
+  },
+});
 ```
 
 ### `removeAllHooks`
@@ -203,12 +213,16 @@ Remove all hook handlers.
 Registers a (sync) callback to be called before each hook is being called.
 
 ```js
-hookable.beforeEach((event) => { console.log(`${event.name} hook is being called with ${event.args}`)}`)
-hookable.hook('test', () => { console.log('running test hook') })
+hookable.beforeEach((event) => {
+  console.log(`${event.name} hook is being called with ${event.args}`);
+});
+hookable.hook("test", () => {
+  console.log("running test hook");
+});
 
 // test hook is being called with []
 // running test hook
-await hookable.callHook('test')
+await hookable.callHook("test");
 ```
 
 ### `afterEach (syncCallback)`
@@ -216,12 +230,16 @@ await hookable.callHook('test')
 Registers a (sync) callback to be called after each hook is being called.
 
 ```js
-hookable.afterEach((event) => { console.log(`${event.name} hook called with ${event.args}`)}`)
-hookable.hook('test', () => { console.log('running test hook') })
+hookable.afterEach((event) => {
+  console.log(`${event.name} hook called with ${event.args}`);
+});
+hookable.hook("test", () => {
+  console.log("running test hook");
+});
 
 // running test hook
 // test hook called with []
-await hookable.callHook('test')
+await hookable.callHook("test");
 ```
 
 ### `createDebugger`
@@ -229,12 +247,12 @@ await hookable.callHook('test')
 Automatically logs each hook that is called and how long it takes to run.
 
 ```js
-const debug = hookable.createDebugger(hooks, { tag: 'something' })
+const debug = hookable.createDebugger(hooks, { tag: "something" });
 
-hooks.callHook('some-hook', 'some-arg')
+hooks.callHook("some-hook", "some-arg");
 // [something] some-hook: 0.21ms
 
-debug.close()
+debug.close();
 ```
 
 ## Migration
@@ -244,9 +262,9 @@ debug.close()
 - Type checking improved. You can use `Hookable<T>` or `createHooks<T>()` to provide types interface **([c2e1e22](https://github.com/unjs/hookable/commit/c2e1e223d16e7bf87117cd8d72ad3ba211a333d8))**
 - We no longer provide an IE11 compatible umd build. Instead, you should use an ESM-aware bundler such as webpack or rollup to transpile if needed.
 - Logger param is dropped. We use `console.warn` by default for deprecated hooks.
-- Package now uses named exports. You should import `{ Hookable }` instead of  `Hookable` or use new `createHooks` util
+- Package now uses named exports. You should import `{ Hookable }` instead of `Hookable` or use new `createHooks` util
 - `mergeHooks` util is exported standalone. You should replace `Hookable.mergeHooks` and `this.mergeHooks` with new `{ mergeHooks }` export
-- In versions < 5.0.0 when using `callHook` if an error happened by one of the hook callbacks, we was handling errors globally and call global `error` hook + `console.error` instead and resolve `callHook` promise!  This sometimes makes confusing behavior when we think code worked but it didn't. v5 introduced a breaking change that when a hook throws an error, `callHook` also rejects instead of a global `error` event. This means you should be careful to handle all errors when using `callHook` now.
+- In versions < 5.0.0 when using `callHook` if an error happened by one of the hook callbacks, we was handling errors globally and call global `error` hook + `console.error` instead and resolve `callHook` promise! This sometimes makes confusing behavior when we think code worked but it didn't. v5 introduced a breaking change that when a hook throws an error, `callHook` also rejects instead of a global `error` event. This means you should be careful to handle all errors when using `callHook` now.
 
 ## Credits
 
@@ -259,6 +277,7 @@ Thanks to [Joe Paice](https://github.com/RGBboy) for donating [hookable](https:/
 MIT - Made with 💖
 
 <!-- Badges -->
+
 [npm-version-src]: https://img.shields.io/npm/v/hookable?style=flat&colorA=18181B&colorB=F0DB4F
 [npm-version-href]: https://npmjs.com/package/hookable
 [npm-downloads-src]: https://img.shields.io/npm/dm/hookable?style=flat&colorA=18181B&colorB=F0DB4F

package/dist/index.d.mts

@@ -0,0 +1,107 @@
+//#region src/types.d.ts
+type HookCallback = (...arguments_: any) => Promise<void> | void;
+interface Hooks {
+  [key: string]: HookCallback;
+}
+type HookKeys<T> = keyof T & string;
+type DeprecatedHook<T> = {
+  message?: string;
+  to: HookKeys<T>;
+};
+type DeprecatedHooks<T> = { [name in HookKeys<T>]: DeprecatedHook<T> };
+type Thenable<T> = Promise<T> | T;
+type ValueOf<C> = C extends Record<any, any> ? C[keyof C] : never;
+type Strings<T> = Exclude<keyof T, number | symbol>;
+type KnownKeys<T> = keyof { [K in keyof T as string extends K ? never : number extends K ? never : K]: never };
+type StripGeneric<T> = Pick<T, KnownKeys<T> extends keyof T ? KnownKeys<T> : never>;
+type OnlyGeneric<T> = Omit<T, KnownKeys<T> extends keyof T ? KnownKeys<T> : never>;
+type Namespaces<T> = ValueOf<{ [key in Strings<T>]: key extends `${infer Namespace}:${string}` ? Namespace : never }>;
+type BareHooks<T> = ValueOf<{ [key in Strings<T>]: key extends `${string}:${string}` ? never : key }>;
+type HooksInNamespace<T, Namespace$1 extends string> = ValueOf<{ [key in Strings<T>]: key extends `${Namespace$1}:${infer HookName}` ? HookName : never }>;
+type WithoutNamespace<T, Namespace$1 extends string> = { [key in HooksInNamespace<T, Namespace$1>]: `${Namespace$1}:${key}` extends keyof T ? T[`${Namespace$1}:${key}`] : never };
+type NestedHooks<T> = (Partial<StripGeneric<T>> | Partial<OnlyGeneric<T>>) & Partial<{ [key in Namespaces<StripGeneric<T>>]: NestedHooks<WithoutNamespace<T, key>> }> & Partial<{ [key in BareHooks<StripGeneric<T>>]: T[key] }>;
+//#endregion
+//#region src/hookable.d.ts
+type InferCallback<HT, HN extends keyof HT> = HT[HN] extends HookCallback ? HT[HN] : never;
+type InferSpyEvent<HT extends Record<string, any>> = { [key in keyof HT]: {
+  name: key;
+  args: Parameters<HT[key]>;
+  context: Record<string, any>;
+} }[keyof HT];
+declare class Hookable<HooksT extends Record<string, any> = Record<string, HookCallback>, HookNameT extends HookKeys<HooksT> = HookKeys<HooksT>> {
+  private _hooks;
+  private _before?;
+  private _after?;
+  private _deprecatedHooks;
+  private _deprecatedMessages?;
+  constructor();
+  hook<NameT extends HookNameT>(name: NameT, function_: InferCallback<HooksT, NameT>, options?: {
+    allowDeprecated?: boolean;
+  }): () => void;
+  hookOnce<NameT extends HookNameT>(name: NameT, function_: InferCallback<HooksT, NameT>): () => void;
+  removeHook<NameT extends HookNameT>(name: NameT, function_: InferCallback<HooksT, NameT>): void;
+  deprecateHook<NameT extends HookNameT>(name: NameT, deprecated: HookKeys<HooksT> | DeprecatedHook<HooksT>): void;
+  deprecateHooks(deprecatedHooks: Partial<Record<HookNameT, DeprecatedHook<HooksT>>>): void;
+  addHooks(configHooks: NestedHooks<HooksT>): () => void;
+  removeHooks(configHooks: NestedHooks<HooksT>): void;
+  removeAllHooks(): void;
+  callHook<NameT extends HookNameT>(name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): Thenable<any> | void;
+  callHookParallel<NameT extends HookNameT>(name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): Thenable<any[]> | void;
+  callHookWith<NameT extends HookNameT, CallFunction extends (hooks: HookCallback[], args: Parameters<InferCallback<HooksT, NameT>>) => any>(caller: CallFunction, name: NameT, args: Parameters<InferCallback<HooksT, NameT>>): ReturnType<CallFunction>;
+  beforeEach(function_: (event: InferSpyEvent<HooksT>) => void): () => void;
+  afterEach(function_: (event: InferSpyEvent<HooksT>) => void): () => void;
+}
+declare function createHooks<T extends Record<string, any>>(): Hookable<T>;
+declare class HookableCore<HooksT extends Record<string, any> = Record<string, HookCallback>, HookNameT extends HookKeys<HooksT> = HookKeys<HooksT>> {
+  protected _hooks: {
+    [key: string]: HookCallback[] | undefined;
+  };
+  constructor();
+  hook<NameT extends HookNameT>(name: NameT, fn: InferCallback<HooksT, NameT>): () => void;
+  removeHook<NameT extends HookNameT>(name: NameT, function_: InferCallback<HooksT, NameT>): void;
+  callHook<NameT extends HookNameT>(name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): Thenable<any> | void;
+}
+//#endregion
+//#region src/utils.d.ts
+declare function flatHooks<T>(configHooks: NestedHooks<T>, hooks?: T, parentName?: string): T;
+declare function mergeHooks<T>(...hooks: NestedHooks<T>[]): T;
+declare function serial<T>(tasks: T[], function_: (task: T) => Promise<any> | any): Promise<any>;
+type CreateTask = (name?: string) => {
+  run: (function_: () => Promise<any> | any) => Promise<any> | any;
+};
+declare global {
+  interface Console {
+    createTask?: CreateTask;
+  }
+}
+/** @deprecated */
+declare function serialCaller(hooks: HookCallback[], arguments_?: any[]): Promise<any>;
+/** @deprecated */
+declare function parallelCaller(hooks: HookCallback[], args?: any[]): Promise<any>;
+//#endregion
+//#region src/debugger.d.ts
+interface CreateDebuggerOptions {
+  /** An optional tag to prefix console logs with */
+  tag?: string;
+  /**
+  * Show hook params to the console output
+  *
+  * Enabled for browsers by default
+  */
+  inspect?: boolean;
+  /**
+  * Use group/groupEnd wrapper around logs happening during a specific hook
+  *
+  * Enabled for browsers by default
+  */
+  group?: boolean;
+  /** Filter which hooks to enable debugger for. Can be a string prefix or fn. */
+  filter?: string | ((event: string) => boolean);
+}
+/** Start debugging hook names and timing in console */
+declare function createDebugger(hooks: Hookable<any>, _options?: CreateDebuggerOptions): {
+  /** Stop debugging and remove listeners */
+  close: () => void;
+};
+//#endregion
+export { CreateDebuggerOptions, DeprecatedHook, DeprecatedHooks, HookCallback, HookKeys, Hookable, HookableCore, Hooks, NestedHooks, Thenable, createDebugger, createHooks, flatHooks, mergeHooks, parallelCaller, serial, serialCaller };