hookified 1.12.0 → 1.12.2

package/README.md

@@ -16,6 +16,9 @@
 - Browser Support and Delivered via CDN
 - Ability to throw errors in hooks
 - Ability to pass in a logger (such as Pino) for errors
+- Enforce consistent hook naming conventions with `enforceBeforeAfter`
+- Deprecation warnings for hooks with `deprecatedHooks`
+- Control deprecated hook execution with `allowDeprecated`
 - No package dependencies and only 100KB in size
 - Fast and Efficient with [Benchmarks](#benchmarks)
 - Maintained on a regular basis!
@@ -27,6 +30,9 @@
 - [API - Hooks](#api---hooks)
   - [.throwHookErrors](#throwhookerrors)
   - [.logger](#logger)
+  - [.enforceBeforeAfter](#enforcebeforeafter)
+  - [.deprecatedHooks](#deprecatedhooks)
+  - [.allowDeprecated](#allowdeprecated)
   - [.onHook(eventName, handler)](#onhookeventname-handler)
   - [.onHookEntry(hookEntry)](#onhookentryhookentry)
   - [.addHook(eventName, handler)](#addhookeventname-handler)
@@ -57,9 +63,9 @@
   - [.eventNames()](#eventnames)
   - [.listenerCount(eventName?)](#listenercounteventname)
   - [.rawListeners(eventName?)](#rawlistenerseventname)
-- [Development and Contribution](#development-and-contribution)
 - [Benchmarks](#benchmarks)
-- [License](#license)
+- [How to Contribute](#how-to-contribute)
+- [License and Copyright](#license-and-copyright)
 
 # Installation
 ```bash
@@ -231,6 +237,197 @@ myClass.onHook('before:myMethod2', async () => {
 await myClass.hook('before:myMethod2');
 ```
 
+## .enforceBeforeAfter
+
+If set to true, enforces that all hook names must start with 'before' or 'after'. This is useful for maintaining consistent hook naming conventions in your application. Default is false.
+
+```javascript
+import { Hookified } from 'hookified';
+
+class MyClass extends Hookified {
+  constructor() {
+    super({ enforceBeforeAfter: true });
+  }
+}
+
+const myClass = new MyClass();
+
+console.log(myClass.enforceBeforeAfter); // true
+
+// These will work fine
+myClass.onHook('beforeSave', async () => {
+  console.log('Before save hook');
+});
+
+myClass.onHook('afterSave', async () => {
+  console.log('After save hook');
+});
+
+myClass.onHook('before:validation', async () => {
+  console.log('Before validation hook');
+});
+
+// This will throw an error
+try {
+  myClass.onHook('customEvent', async () => {
+    console.log('This will not work');
+  });
+} catch (error) {
+  console.log(error.message); // Hook event "customEvent" must start with "before" or "after" when enforceBeforeAfter is enabled
+}
+
+// You can also change it dynamically
+myClass.enforceBeforeAfter = false;
+myClass.onHook('customEvent', async () => {
+  console.log('This will work now');
+});
+```
+
+The validation applies to all hook-related methods:
+- `onHook()`, `addHook()`, `onHookEntry()`, `onHooks()`
+- `prependHook()`, `onceHook()`, `prependOnceHook()`
+- `hook()`, `callHook()`
+- `getHooks()`, `removeHook()`, `removeHooks()`
+
+Note: The `beforeHook()` and `afterHook()` helper methods automatically generate proper hook names and work regardless of the `enforceBeforeAfter` setting.
+
+## .deprecatedHooks
+
+A Map of deprecated hook names to deprecation messages. When a deprecated hook is used, a warning will be emitted via the 'warn' event and logged to the logger (if available). Default is an empty Map.
+
+```javascript
+import { Hookified } from 'hookified';
+
+// Define deprecated hooks with custom messages
+const deprecatedHooks = new Map([
+  ['oldHook', 'Use newHook instead'],
+  ['legacyMethod', 'This hook will be removed in v2.0'],
+  ['deprecatedFeature', ''] // Empty message - will just say "deprecated"
+]);
+
+class MyClass extends Hookified {
+  constructor() {
+    super({ deprecatedHooks });
+  }
+}
+
+const myClass = new MyClass();
+
+console.log(myClass.deprecatedHooks); // Map with deprecated hooks
+
+// Listen for deprecation warnings
+myClass.on('warn', (event) => {
+  console.log(`Deprecation warning: ${event.message}`);
+  // event.hook contains the hook name
+  // event.message contains the full warning message
+});
+
+// Using a deprecated hook will emit warnings
+myClass.onHook('oldHook', () => {
+  console.log('This hook is deprecated');
+});
+// Output: Hook "oldHook" is deprecated: Use newHook instead
+
+// Using a deprecated hook with empty message
+myClass.onHook('deprecatedFeature', () => {
+  console.log('This hook is deprecated');
+});
+// Output: Hook "deprecatedFeature" is deprecated
+
+// You can also set deprecated hooks dynamically
+myClass.deprecatedHooks.set('anotherOldHook', 'Please migrate to the new API');
+
+// Works with logger if provided
+import pino from 'pino';
+const logger = pino();
+
+const myClassWithLogger = new Hookified({ 
+  deprecatedHooks,
+  logger 
+});
+
+// Deprecation warnings will be logged to logger.warn
+```
+
+The deprecation warning system applies to all hook-related methods:
+- Registration: `onHook()`, `addHook()`, `onHookEntry()`, `onHooks()`, `prependHook()`, `onceHook()`, `prependOnceHook()`
+- Execution: `hook()`, `callHook()`
+- Management: `getHooks()`, `removeHook()`, `removeHooks()`
+
+Deprecation warnings are emitted in two ways:
+1. **Event**: A 'warn' event is emitted with `{ hook: string, message: string }`
+2. **Logger**: Logged to `logger.warn()` if a logger is configured and has a `warn` method
+
+## .allowDeprecated
+
+Controls whether deprecated hooks are allowed to be registered and executed. Default is true. When set to false, deprecated hooks will still emit warnings but will be prevented from registration and execution.
+
+```javascript
+import { Hookified } from 'hookified';
+
+const deprecatedHooks = new Map([
+  ['oldHook', 'Use newHook instead']
+]);
+
+class MyClass extends Hookified {
+  constructor() {
+    super({ deprecatedHooks, allowDeprecated: false });
+  }
+}
+
+const myClass = new MyClass();
+
+console.log(myClass.allowDeprecated); // false
+
+// Listen for deprecation warnings (still emitted even when blocked)
+myClass.on('warn', (event) => {
+  console.log(`Warning: ${event.message}`);
+});
+
+// Try to register a deprecated hook - will emit warning but not register
+myClass.onHook('oldHook', () => {
+  console.log('This will never execute');
+});
+// Output: Warning: Hook "oldHook" is deprecated: Use newHook instead
+
+// Verify hook was not registered
+console.log(myClass.getHooks('oldHook')); // undefined
+
+// Try to execute a deprecated hook - will emit warning but not execute
+await myClass.hook('oldHook');
+// Output: Warning: Hook "oldHook" is deprecated: Use newHook instead
+// (but no handlers execute)
+
+// Non-deprecated hooks work normally
+myClass.onHook('validHook', () => {
+  console.log('This works fine');
+});
+
+console.log(myClass.getHooks('validHook')); // [handler function]
+
+// You can dynamically change the setting
+myClass.allowDeprecated = true;
+
+// Now deprecated hooks can be registered and executed
+myClass.onHook('oldHook', () => {
+  console.log('Now this works');
+});
+
+console.log(myClass.getHooks('oldHook')); // [handler function]
+```
+
+**Behavior when `allowDeprecated` is false:**
+- **Registration**: All hook registration methods (`onHook`, `addHook`, `prependHook`, etc.) will emit warnings but skip registration
+- **Execution**: Hook execution methods (`hook`, `callHook`) will emit warnings but skip execution  
+- **Management**: Hook management methods (`getHooks`, `removeHook`) will emit warnings and return undefined/skip operations
+- **Warnings**: Deprecation warnings are always emitted regardless of `allowDeprecated` setting
+
+**Use cases:**
+- **Development**: Keep `allowDeprecated: true` to maintain functionality while seeing warnings
+- **Testing**: Set `allowDeprecated: false` to ensure no deprecated hooks are accidentally used
+- **Migration**: Gradually disable deprecated hooks during API transitions
+- **Production**: Disable deprecated hooks to prevent legacy code execution
+
 ## .onHook(eventName, handler)
 
 Subscribe to a hook event.
@@ -999,7 +1196,31 @@ myClass.on('message', (message) => {
 console.log(myClass.rawListeners('message'));
 ```
 
-# Development and Contribution
+# Benchmarks
+
+We are doing very simple benchmarking to see how this compares to other libraries using `tinybench`. This is not a full benchmark but just a simple way to see how it performs. Our goal is to be as close or better than the other libraries including native (EventEmitter).
+
+## Hooks
+
+|         name          |  summary  |  ops/sec  |  time/op  |  margin  |  samples  |
+|-----------------------|:---------:|----------:|----------:|:--------:|----------:|
+|  Hookified (v1.12.1)  |    🥇     |       5M  |    243ns  |  ±0.89%  |       4M  |
+|  Hookable (v5.5.3)    |   -69%    |       1M  |    835ns  |  ±2.23%  |       1M  |
+
+## Emits
+
+This shows how on par `hookified` is to the native `EventEmitter` and popular `eventemitter3`. These are simple emitting benchmarks to see how it performs.
+
+|           name            |  summary  |  ops/sec  |  time/op  |  margin  |  samples  |
+|---------------------------|:---------:|----------:|----------:|:--------:|----------:|
+|  Hookified (v1.12.1)      |    🥇     |      12M  |     89ns  |  ±2.56%  |      11M  |
+|  EventEmitter3 (v5.0.1)   |   -1.7%   |      12M  |     91ns  |  ±3.31%  |      11M  |
+|  EventEmitter (v20.17.0)  |    -4%    |      11M  |     92ns  |  ±0.38%  |      11M  |
+|  Emittery (v1.2.0)        |   -91%    |       1M  |      1µs  |  ±1.59%  |     993K  |
+
+_Note: the `EventEmitter` version is Nodejs versioning._
+
+# How to Contribute
 
 Hookified is written in TypeScript and tests are written in `vitest`. To run the tests, use the following command:
 
@@ -1017,31 +1238,19 @@ npm install -g pnpm
 
 To contribute follow the [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
 
-# Benchmarks
-
-We are doing very simple benchmarking to see how this compares to other libraries using `tinybench`. This is not a full benchmark but just a simple way to see how it performs. Our goal is to be as close or better than the other libraries including native (EventEmitter).
-
-## Hooks
-
-|       name        |  summary  |  ops/sec  |  time/op  |  margin  |  samples  |
-|-------------------|:---------:|----------:|----------:|:--------:|----------:|
-|  Hookified 1.8.0  |    🥇     |       4M  |    299ns  |  ±2.42%  |       3M  |
-|  Hookable 5.5.3   |   -73%    |     982K  |      1µs  |  ±2.92%  |     812K  |
-
-## Emits
+```bash
+pnpm i && pnpm test
+```
 
-This shows how on par `hookified` is to the native `EventEmitter` and popular `eventemitter3`. These are simple emitting benchmarks to see how it performs.
+Note that we are using `pnpm` as our package manager. If you don't have it installed, you can install it globally with:
 
-|          name           |  summary  |  ops/sec  |  time/op  |  margin  |  samples  |
-|-------------------------|:---------:|----------:|----------:|:--------:|----------:|
-|  Hookified 1.8.0        |    🥇     |      10M  |    112ns  |  ±1.13%  |       9M  |
-|  EventEmitter3 5.0.1    |   -1.3%   |      10M  |    114ns  |  ±1.84%  |       9M  |
-|  EventEmitter v22.12.0  |   -1.5%   |       9M  |    114ns  |  ±1.18%  |       9M  |
-|  Emittery 1.1.0         |   -92%    |     785K  |      1µs  |  ±0.45%  |     761K  |
+```bash
+npm install -g pnpm
+```
 
-_Note: the `EventEmitter` version is Nodejs versioning._
+To contribute follow the [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
 
-# License
+# License and Copyright
 
 [MIT & © Jared Wray](LICENSE)