https://github.com/igorskyflyer/npm-hook

🪝 Hooks onto a JavaScript prototype, either extending or changing its behavior or replacing it completely. 👺
https://github.com/igorskyflyer/npm-hook

back-end biome function hook igorskyflyer javascript js method node npm prototype ts typescript utility vitest

Last synced: 4 months ago
JSON representation

🪝 Hooks onto a JavaScript prototype, either extending or changing its behavior or replacing it completely. 👺

• Host: GitHub
• URL: https://github.com/igorskyflyer/npm-hook
• Owner: igorskyflyer
• License: mit
• Created: 2024-07-08T17:44:30.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2024-07-21T17:07:42.000Z (almost 2 years ago)
• Last Synced: 2025-06-04T07:37:55.169Z (about 1 year ago)
• Topics: back-end, biome, function, hook, igorskyflyer, javascript, js, method, node, npm, prototype, ts, typescript, utility, vitest
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/@igor.dvlpr/hook
• Size: 71.3 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

          


  

  
Hook





  Type-Safe Hooks • Extend Methods • Zero Overhead • Cross-Env





  🪝 Hooks onto a JavaScript prototype, either extending or changing its behavior or replacing it completely. 👺






## 📃 Table of Contents

- [**Features**](#-features)

- [**Usage**](#-usage)

- [**API**](#-api)

    - [**hook()**](#hook-boolean)

- [**Examples**](#️-examples)

- [**Changelog**](#-changelog)

- [**Support**](#-support)

- [**License**](#-license)

- [**Related**](#-related)

- [**Author**](#-author)




## 🤖 Features

- 🪝 Prototype hooking - attach custom logic to any existing JavaScript prototype method

- 🔄 Extend or replace - choose to run native behavior first or fully override it

- 🧠 Smart IntelliSense - automatically suggests valid method names for the given prototype and provides full signature hints for parameters and return types

- 🧩 Type-safe - leverages TypeScript generics for precise method and argument typing

- 🛡 Validation built-in - ensures method exists and handler is a function before hooking

- 🪞 Native method access - passes original bound method to your handler for reuse

- ⚡ Reusable utility - works with arrays, numbers, strings, or any object prototype

- 🎯 Minimal API - single `hook()` call with clear, predictable parameters

- 🏗 Non-invasive - modifies only the targeted method without affecting others




## 🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

```bash

pnpm add @igorskyflyer/hook

```

```bash

yarn add @igorskyflyer/hook

```

```bash

npm i @igorskyflyer/hook

```




## 🤹🏼 API

> ### 🛑 CAUTION

>

> #### Dangerous functionality

>

> This package provides ways of modifying the native prototype(s) of built-in JavaScript objects, use it only if you know what you're doing and with **caution** as it may cause unexpected results!

>




### hook(): boolean

```ts

function hook<

  Prototype extends object,

  Method extends KeysOf & string

>(

  proto: Prototype,

  method: Method,

  handler: NativeMethodHook,

  replace?: boolean

): boolean

```

Hooks onto a JavaScript prototype in order to extend, modify or completely replace a given method of it.




#### `proto`

A prototype, e.g. `Array.prototype`, `Number.prototype`, etc.




#### `method`

A method to hook onto, e.g. `push` of `Array.prototype`.




#### `handler`

A custom function to run when the hooked method is called.

The function has the following signature:

```ts

(

  this: Prototype,

  native: Prototype[Method],

  ...args: Parameters>

) => ReturnType

```




> ### ℹ️ NOTE

>

> #### Binding

>

> The native function is already bound to the same `this` as your handler at call time. This means you can call `native(...)` directly without worrying about `.bind(this)` - it will behave exactly as the original method would on the current instance. 😉

>




`this` will be resolved to the provided prototype.  

`native` is the native method that's being overridden, with its original signature.  

`...args: Parameters>` all other arguments passed after the `native` method.  

`ReturnType` the return type of the handler is the same as the `native` method is.




#### `replace`

An optional Boolean indicating whether the prototype method should be replaced completely.  

Defaults to **false**.




Returns a Boolean whether the hooking onto was successful.







> ### ℹ️ NOTE

>

> #### Unhooking

>

> In situations where a method needs to be hooked temporarily - such as during debugging, instrumentation, or within a testing framework, it is advisable to keep a reference to the original method prior to applying the hook. This practice enables you to restore the prototype to its original condition after executing your custom logic, thereby preventing side effects from affecting unrelated code.

>




For instance, you can save

```ts

const originalUnshift = Array.prototype.unshift

```

apply your hook, execute your code or tests, and subsequently reassign

```ts

Array.prototype.unshift = originalUnshift

```

to undo the modification. This method guarantees that your changes are contained, reversible, and safe for use in collaborative environments.




## 🗒️ Examples

```ts

import { hook } from '@igorskyflyer/hook'

hook(Array.prototype, 'unshift', function (native, x) {

  // any code can be here,

  // not just owned by the prototype

  // you're hooking/replacing

  native(512)

  this.push(x / 2)

  // must adhere to the original method's

  // return type

  // see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift#return_value

  return this.length // returns 3

})

const array: number[] = []

array.unshift(256)

console.log(array) // [512, 256, 128]

```




## 📝 Changelog

📑 Read about the latest changes in the [**CHANGELOG**](https://github.com/igorskyflyer/npm-hook/blob/main/CHANGELOG.md).




## 🪪 License

Licensed under the [**MIT license**](https://github.com/igorskyflyer/npm-hook/blob/main/LICENSE).




## 💖 Support



  I work hard for every project, including this one and your support means a lot to me!

  


  Consider buying me a coffee. ☕

  


  


  

  


  


  Thank you for supporting my efforts! 🙏😊






## 🧬 Related

[**@igorskyflyer/strip-html**](https://www.npmjs.com/package/@igorskyflyer/strip-html)

> _🥞 Removes HTML code from the given string. Can even extract text-only from the given an HTML string. ✨_




[**@igorskyflyer/valid-path**](https://www.npmjs.com/package/@igorskyflyer/valid-path)

> _🧰 Determines whether a given value can be a valid file/directory name. 🏜_




[**@igorskyflyer/vscode-folderpicker**](https://www.npmjs.com/package/@igorskyflyer/vscode-folderpicker)

> _✨ Fast, custom cross-platform folder picker and creator for VS Code with icons, validation, and instant navigation. 🎨_




[**@igorskyflyer/emojilyzer**](https://www.npmjs.com/package/@igorskyflyer/emojilyzer)

> _💬 Emojifies strings, converting textual representations of emojis to graphical ones. 🖌️_




[**@igorskyflyer/zitto**](https://www.npmjs.com/package/@igorskyflyer/zitto)

> _🤫 Zitto - quiet config, loud clarity. A zero-dependency TypeScript/JavaScript helper for merging defaults and options across Node, Deno, Bun, and browsers. 🍯_




## 👨🏻‍💻 Author

Created by **Igor Dimitrijević ([*@igorskyflyer*](https://github.com/igorskyflyer/))**.