fix: update context api

Author: twlite

apps/website/src/data/docs.json

@@ -133,6 +133,17 @@ const pages = [
             }
         ]
     },
+    {
+        name: 'hooks',
+        displayName: 'Hooks',
+        pages: [
+            {
+                name: 'using-hooks',
+                displayName: 'Using Hooks',
+                component: lazy(() => import('../_guides/hooks/using_hooks.mdx'))
+            }
+        ]
+    },
     {
         name: 'extractors',
         displayName: 'Extractors',
@@ -191,17 +202,7 @@ const pages = [
             }
         ]
     },
-    {
-        name: 'hooks',
-        displayName: 'Hooks',
-        pages: [
-            {
-                name: 'using-hooks',
-                displayName: 'Using Hooks',
-                component: lazy(() => import('../_guides/hooks/using_hooks.mdx'))
-            }
-        ]
-    },
+
     {
         name: 'migrating',
         displayName: 'Migrating',

apps/website/src/pages/guide/[topic]/[page].tsx

@@ -25,18 +25,20 @@ export async function execute(interaction) {
 First of all, your command handler needs to provide context to `HooksContextProvider`:
 
 ```js
-const { withContext } = require('discord-player');
+const { useMainPlayer } = require('discord-player');
 
 client.on('interactionCreate', async (interaction) => {
     if (!interaction.isCommand()) return;
 
+    const player = useMainPlayer();
+
     // assuming the following code is your target command to be executed
     const command = getCommandSomehow(); // shape is roughly { execute: Function }
 
     const context = { guild: interaction.guild };
 
     // provide context and execute the command
-    await withContext(context, () => command.execute(interaction));
+    await player.context.provide(context, () => command.execute(interaction));
 });
 ```
 

apps/website/src/pages/guide/_guides/hooks/using_hooks.mdx

@@ -47,10 +47,10 @@
     "esbuild-plugin-version-injector": "^1.0.2",
     "eslint": "^8.21.0",
     "fs-extra": "^11.1.0",
+    "micro-docgen": "^0.2.0",
     "prettier": "^2.8.2",
     "rimraf": "^4.1.2",
     "turbo": "1.10.16",
-    "typedoc-nextra": "0.1.5",
     "typescript": "^5.2.2",
     "vitest": "^0.34.6"
   }

package.json

@@ -77,4 +77,4 @@
     "readmeFile": "./README.md",
     "tsconfig": "./tsconfig.json"
   }
-}
+}

packages/discord-player/package.json

@@ -15,6 +15,8 @@ import { PlayerEventsEmitter } from './utils/PlayerEventsEmitter';
 import { Exceptions } from './errors';
 import { defaultVoiceStateHandler } from './DefaultVoiceStateHandler';
 import { IPRotator } from './utils/IPRotator';
+import { Context, createContext } from './hooks';
+import { HooksCtx } from './hooks/common';
 
 const kSingleton = Symbol('InstanceDiscordPlayerSingleton');
 
@@ -43,6 +45,7 @@ export class Player extends PlayerEventsEmitter<PlayerEvents> {
     #lagMonitorTimeout!: NodeJS.Timeout;
     #lagMonitorInterval!: NodeJS.Timer;
     #onVoiceStateUpdate: VoiceStateHandler = defaultVoiceStateHandler;
+    #hooksCtx: Context<HooksCtx> | null = null;
     public static readonly version: string = '[VI]{{inject}}[/VI]';
     public static _singletonKey = kSingleton;
     public readonly id = SnowflakeUtil.generate().toString();
@@ -122,6 +125,17 @@ export class Player extends PlayerEventsEmitter<PlayerEvents> {
         }
     }
 
+    /**
+     * The hooks context for this player instance.
+     */
+    public get context() {
+        if (!this.#hooksCtx) {
+            this.#hooksCtx = createContext();
+        }
+
+        return this.#hooksCtx;
+    }
+
     /**
      * Override default voice state update handler
      * @param handler The handler callback

packages/discord-player/src/Player.ts

@@ -1,8 +1,9 @@
 import { Guild } from 'discord.js';
 import type { Player } from '../Player';
-import { createContext, useContext } from './context/async-context';
 import { GuildQueue, NodeResolvable } from '../manager';
 import { instances } from '../utils/__internal__';
+import { Exceptions } from '../errors';
+import { useContext } from './context/async-context';
 
 const preferredInstanceKey = '__discord_player_hook_instance_cache__';
 
@@ -14,15 +15,19 @@ export interface HooksCtx {
     guild: Guild;
 }
 
-export const HooksContextProvider = createContext<HooksCtx>();
-export const withContext = HooksContextProvider.provide.bind(HooksContextProvider);
+/**
+ * @private
+ */
+export function useHooksContext(hookName: string) {
+    const player = getPlayer();
+    if (!player) throw Exceptions.ERR_ILLEGAL_HOOK_INVOCATION('discord-player', 'Player instance must be created before using hooks');
 
-export const useHooksContext = () => {
-    const ctx = useContext(HooksContextProvider);
-    if (!ctx) throw new Error('useHooksContext must be called inside a HooksContextProvider');
+    const context = useContext(player.context);
 
-    return ctx;
-};
+    if (!context) throw Exceptions.ERR_ILLEGAL_HOOK_INVOCATION(hookName, `${hookName} must be called inside a player context created by <Player>.context.provide()`);
+
+    return context;
+}
 
 /**
  * Bind a player instance to the hook system, defaults to the first instance.

packages/discord-player/src/hooks/common.ts

@@ -44,7 +44,7 @@ export class Context<T> {
     /**
      * Get the current value of the context. If the context is lost and no default value is provided, undefined will be returned.
      */
-    public getValue(): T | undefined {
+    public consume(): T | undefined {
         const data = this.storage.getStore();
 
         if (data === undefined && this.defaultValue !== undefined) return this.defaultValue;
@@ -95,5 +95,5 @@ export function createContext<T = unsafe>(defaultValue?: T): Context<T> {
  * @example const value = useContext(context);
  */
 export function useContext<T = unsafe>(context: Context<T>): T | undefined {
-    return context.getValue();
+    return context.consume();
 }

packages/discord-player/src/hooks/context/async-context.ts

@@ -8,7 +8,7 @@ import { getQueue, useHooksContext } from './common';
 export function useHistory<Meta = unknown>(): GuildQueueHistory<Meta> | null;
 export function useHistory<Meta = unknown>(node: NodeResolvable): GuildQueueHistory<Meta> | null;
 export function useHistory<Meta = unknown>(node?: NodeResolvable): GuildQueueHistory<Meta> | null {
-    const _node = node ?? useHooksContext().guild;
+    const _node = node ?? useHooksContext('useHistory').guild;
 
     const queue = getQueue<Meta>(_node);
     if (!queue) return null;

packages/discord-player/src/hooks/useHistory.ts

@@ -12,7 +12,7 @@ export type MetadataDispatch<T> = readonly [() => T, (metadata: T | SetterFN<T,
 export function useMetadata<T = unknown>(): MetadataDispatch<T>;
 export function useMetadata<T = unknown>(node: NodeResolvable): MetadataDispatch<T>;
 export function useMetadata<T = unknown>(node?: NodeResolvable): MetadataDispatch<T> {
-    const _node = node ?? useHooksContext().guild;
+    const _node = node ?? useHooksContext('useMetadata').guild;
     const queue = getQueue<T>(_node);
     const setter = (metadata: T | SetterFN<T, T>) => {
         if (queue) {