{"id":18396730,"url":"https://github.com/igorskyflyer/npm-hook","last_synced_at":"2026-01-29T09:08:03.048Z","repository":{"id":247470401,"uuid":"825890706","full_name":"igorskyflyer/npm-hook","owner":"igorskyflyer","description":"🪝 Hooks onto a JavaScript prototype, either extending or changing its behavior or replacing it completely. 👺","archived":false,"fork":false,"pushed_at":"2024-07-21T17:07:42.000Z","size":73,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-04T07:37:55.169Z","etag":null,"topics":["back-end","biome","function","hook","igorskyflyer","javascript","js","method","node","npm","prototype","ts","typescript","utility","vitest"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@igor.dvlpr/hook","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igorskyflyer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"igorskyflyer"}},"created_at":"2024-07-08T17:44:30.000Z","updated_at":"2024-07-21T17:07:44.000Z","dependencies_parsed_at":"2024-07-09T00:45:00.830Z","dependency_job_id":null,"html_url":"https://github.com/igorskyflyer/npm-hook","commit_stats":null,"previous_names":["igorskyflyer/npm-hook"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-hook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-hook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-hook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-hook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorskyflyer","download_url":"https://codeload.github.com/igorskyflyer/npm-hook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-hook/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259146580,"owners_count":22812269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["back-end","biome","function","hook","igorskyflyer","javascript","js","method","node","npm","prototype","ts","typescript","utility","vitest"],"created_at":"2024-11-06T02:14:41.120Z","updated_at":"2026-01-29T09:08:03.039Z","avatar_url":"https://github.com/igorskyflyer.png","language":"TypeScript","funding_links":["https://ko-fi.com/igorskyflyer"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-hook/main/media/hook.png\" alt=\"Icon of Hook\" width=\"256\" height=\"256\"\u003e\n  \u003ch1\u003eHook\u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cblockquote align=\"center\"\u003e\n  Type-Safe Hooks • Extend Methods • Zero Overhead • Cross-Env\n\u003c/blockquote\u003e\n\n\n\u003ch4 align=\"center\"\u003e\n  🪝 Hooks onto a JavaScript prototype, either extending or changing its behavior or replacing it completely. 👺\n\u003c/h4\u003e\n\n\u003cbr\u003e\n\n## 📃 Table of Contents\n\n- [**Features**](#-features)\n- [**Usage**](#-usage)\n- [**API**](#-api)\n    - [**hook()**](#hook-boolean)\n- [**Examples**](#️-examples)\n- [**Changelog**](#-changelog)\n- [**Support**](#-support)\n- [**License**](#-license)\n- [**Related**](#-related)\n- [**Author**](#-author)\n\n\u003cbr\u003e\n\n## 🤖 Features\n\n- 🪝 Prototype hooking - attach custom logic to any existing JavaScript prototype method\n- 🔄 Extend or replace - choose to run native behavior first or fully override it\n- 🧠 Smart IntelliSense - automatically suggests valid method names for the given prototype and provides full signature hints for parameters and return types\n- 🧩 Type-safe - leverages TypeScript generics for precise method and argument typing\n- 🛡 Validation built-in - ensures method exists and handler is a function before hooking\n- 🪞 Native method access - passes original bound method to your handler for reuse\n- ⚡ Reusable utility - works with arrays, numbers, strings, or any object prototype\n- 🎯 Minimal API - single `hook()` call with clear, predictable parameters\n- 🏗 Non-invasive - modifies only the targeted method without affecting others\n\n\u003cbr\u003e\n\n## 🕵🏼 Usage\n\nInstall it by executing any of the following, depending on your preferred package manager:\n\n```bash\npnpm add @igorskyflyer/hook\n```\n\n```bash\nyarn add @igorskyflyer/hook\n```\n\n```bash\nnpm i @igorskyflyer/hook\n```\n\n\u003cbr\u003e\n\n## 🤹🏼 API\n\n\u003e ### 🛑 CAUTION\n\u003e\n\u003e #### Dangerous functionality\n\u003e\n\u003e 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!\n\u003e\n\n\u003cbr\u003e\n\n### hook(): boolean\n\n```ts\nfunction hook\u003c\n  Prototype extends object,\n  Method extends KeysOf\u003cPrototype\u003e \u0026 string\n\u003e(\n  proto: Prototype,\n  method: Method,\n  handler: NativeMethodHook\u003cPrototype, Method\u003e,\n  replace?: boolean\n): boolean\n```\n\nHooks onto a JavaScript prototype in order to extend, modify or completely replace a given method of it.\n\n\u003cbr\u003e\n\n#### `proto`\n\nA prototype, e.g. `Array.prototype`, `Number.prototype`, etc.\n\n\u003cbr\u003e\n\n#### `method`\n\nA method to hook onto, e.g. `push` of `Array.prototype`.\n\n\u003cbr\u003e\n\n#### `handler`\n\nA custom function to run when the hooked method is called.\nThe function has the following signature:\n\n```ts\n(\n  this: Prototype,\n  native: Prototype[Method],\n  ...args: Parameters\u003cExtract\u003cPrototype[Method], Func\u003e\u003e\n) =\u003e ReturnType\u003cPrototype[Method]\u003e\n```\n\n\u003cbr\u003e\n\n\u003e ### ℹ️ NOTE\n\u003e\n\u003e #### Binding\n\u003e\n\u003e 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. 😉\n\u003e\n\n\u003cbr\u003e\n\n`this` will be resolved to the provided prototype.  \n\n\n`native` is the native method that's being overridden, with its original signature.  \n\n\n`...args: Parameters\u003cExtract\u003cPrototype[Method], Func\u003e\u003e` all other arguments passed after the `native` method.  \n\n\n`ReturnType\u003cPrototype[Method]\u003e` the return type of the handler is the same as the `native` method is.\n\n\u003cbr\u003e\n\n#### `replace`\n\nAn optional Boolean indicating whether the prototype method should be replaced completely.  \nDefaults to **false**.\n\n\u003cbr\u003e\n\nReturns a Boolean whether the hooking onto was successful.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003e ### ℹ️ NOTE\n\u003e\n\u003e #### Unhooking\n\u003e\n\u003e 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.\n\u003e\n\n\u003cbr\u003e\n\nFor instance, you can save\n```ts\nconst originalUnshift = Array.prototype.unshift\n```\n\napply your hook, execute your code or tests, and subsequently reassign\n\n```ts\nArray.prototype.unshift = originalUnshift\n```\n\nto undo the modification. This method guarantees that your changes are contained, reversible, and safe for use in collaborative environments.\n\u003cbr\u003e\n\n## 🗒️ Examples\n\n```ts\nimport { hook } from '@igorskyflyer/hook'\n\nhook(Array.prototype, 'unshift', function (native, x) {\n  // any code can be here,\n  // not just owned by the prototype\n  // you're hooking/replacing\n\n  native(512)\n  this.push(x / 2)\n\n  // must adhere to the original method's\n  // return type\n  // see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift#return_value\n  return this.length // returns 3\n})\n\nconst array: number[] = []\n\narray.unshift(256)\nconsole.log(array) // [512, 256, 128]\n```\n\n\u003cbr\u003e\n\n## 📝 Changelog\n\n📑 Read about the latest changes in the [**CHANGELOG**](https://github.com/igorskyflyer/npm-hook/blob/main/CHANGELOG.md).\n\n\u003cbr\u003e\n\n## 🪪 License\n\nLicensed under the [**MIT license**](https://github.com/igorskyflyer/npm-hook/blob/main/LICENSE).\n\n\u003cbr\u003e\n\n## 💖 Support\n\n\u003cdiv align=\"center\"\u003e\n  I work hard for every project, including this one and your support means a lot to me!\n  \u003cbr\u003e\n  Consider buying me a coffee. ☕\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://ko-fi.com/igorskyflyer\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/igorskyflyer/main/assets/ko-fi.png\" alt=\"Donate to igorskyflyer\" width=\"180\" height=\"46\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003cem\u003eThank you for supporting my efforts!\u003c/em\u003e 🙏😊\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n## 🧬 Related\n\n[**@igorskyflyer/strip-html**](https://www.npmjs.com/package/@igorskyflyer/strip-html)\n\n\u003e _🥞 Removes HTML code from the given string. Can even extract text-only from the given an HTML string. ✨_\n\n\u003cbr\u003e\n\n[**@igorskyflyer/valid-path**](https://www.npmjs.com/package/@igorskyflyer/valid-path)\n\n\u003e _🧰 Determines whether a given value can be a valid file/directory name. 🏜_\n\n\u003cbr\u003e\n\n[**@igorskyflyer/vscode-folderpicker**](https://www.npmjs.com/package/@igorskyflyer/vscode-folderpicker)\n\n\u003e _✨ Fast, custom cross-platform folder picker and creator for VS Code with icons, validation, and instant navigation. 🎨_\n\n\u003cbr\u003e\n\n[**@igorskyflyer/emojilyzer**](https://www.npmjs.com/package/@igorskyflyer/emojilyzer)\n\n\u003e _💬 Emojifies strings, converting textual representations of emojis to graphical ones. 🖌️_\n\n\u003cbr\u003e\n\n[**@igorskyflyer/zitto**](https://www.npmjs.com/package/@igorskyflyer/zitto)\n\n\u003e _🤫 Zitto - quiet config, loud clarity. A zero-dependency TypeScript/JavaScript helper for merging defaults and options across Node, Deno, Bun, and browsers. 🍯_\n\n\u003cbr\u003e\n\n## 👨🏻‍💻 Author\nCreated by **Igor Dimitrijević ([*@igorskyflyer*](https://github.com/igorskyflyer/))**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorskyflyer%2Fnpm-hook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorskyflyer%2Fnpm-hook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorskyflyer%2Fnpm-hook/lists"}