📃 Table of Contents

• Features
• Usage
• API
  • hook()
• Examples
• Changelog
• Support
• License
• Related
• 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:

pnpm add @igorskyflyer/hook

yarn add @igorskyflyer/hook

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

function hook<
  Prototype extends object,
  Method extends KeysOf<Prototype> & string
>(
  proto: Prototype,
  method: Method,
  handler: NativeMethodHook<Prototype, Method>,
  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:

(
  this: Prototype,
  native: Prototype[Method],
  ...args: Parameters<Extract<Prototype[Method], Func>>
) => ReturnType<Prototype[Method]>

ℹ️ 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<Extract<Prototype[Method], Func>> all other arguments passed after the native method.

ReturnType<Prototype[Method]> 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

const originalUnshift = Array.prototype.unshift

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

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

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.

🪪 License

Licensed under the MIT license.

💖 Support

🧬 Related

@igorskyflyer/strip-html

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

@igorskyflyer/valid-path

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

@igorskyflyer/vscode-folderpicker

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

@igorskyflyer/emojilyzer

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

@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).