auto-bind-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Alemzadeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# auto-bind-js
+
+> Automatically bind class methods to their instance. Zero dependencies.
+
+A modern, feature-rich alternative to [`auto-bind`](https://www.npmjs.com/package/auto-bind) with extra capabilities: **lazy binding**, **regex pattern matching**, **decorators**, **Symbol-keyed methods**, and full **TypeScript** support.
+
+## Install
+
+```bash
+npm install auto-bind-js
+```
+
+## Usage
+
+### Basic
+
+```js
+import autoBind from 'auto-bind-js';
+
+class Unicorn {
+  constructor(name) {
+    this.name = name;
+    autoBind(this);
+  }
+
+  message() {
+    return `${this.name} is awesome!`;
+  }
+}
+
+const unicorn = new Unicorn('Rainbow');
+const { message } = unicorn;
+message(); //=> 'Rainbow is awesome!'
+```
+
+### Bind specific methods (shorthand)
+
+```js
+autoBind(this, 'handleClick', 'handleSubmit');
+```
+
+### Options
+
+```js
+// Only bind these methods
+autoBind(this, { include: ['handleClick', 'handleSubmit'] });
+
+// Bind all except these
+autoBind(this, { exclude: ['render', 'toString'] });
+
+// Bind only methods matching a pattern
+autoBind(this, { pattern: /^handle/ });
+
+// Lazy binding — binds on first access (better perf for large classes)
+autoBind(this, { lazy: true });
+```
+
+### React
+
+Excludes all React lifecycle methods automatically:
+
+```js
+import autoBindReact from 'auto-bind-js/react';
+
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    autoBindReact(this);
+  }
+
+  handleClick() {
+    // `this` is always the component instance
+  }
+
+  render() {
+    return <button onClick={this.handleClick}>Click</button>;
+  }
+}
+```
+
+### Decorators
+
+```js
+import { boundClass, bound } from 'auto-bind-js/decorator';
+
+// Class decorator — binds ALL methods
+@boundClass
+class Foo {
+  constructor() {
+    this.name = 'foo';
+  }
+
+  handleClick() {
+    return this.name; // always bound
+  }
+}
+
+// Method decorator — bind individual methods
+class Bar {
+  constructor() {
+    this.name = 'bar';
+  }
+
+  @bound
+  handleClick() {
+    return this.name; // always bound
+  }
+}
+```
+
+## API
+
+### `autoBind(self, options?)`
+
+Bind methods of `self` to the instance. Returns `self`.
+
+#### Options
+
+| Option    | Type              | Description                                  |
+| --------- | ----------------- | -------------------------------------------- |
+| `include` | `(string\|symbol)[]` | Only bind these methods                       |
+| `exclude` | `(string\|symbol)[]` | Skip these methods                            |
+| `pattern` | `RegExp`          | Only bind methods whose names match this regex |
+| `lazy`    | `boolean`         | Bind on first access instead of immediately   |
+
+### `autoBindReact(self, options?)`
+
+Same as `autoBind` but automatically excludes React lifecycle methods (`render`, `componentDidMount`, `shouldComponentUpdate`, etc.)
+
+### `boundClass(target)`
+
+Class decorator. Auto-binds all methods when the class is instantiated.
+
+### `bound(target, key, descriptor)`
+
+Method decorator. Lazily binds the decorated method to the instance on first access.
+
+## Features
+
+- ✅ Zero dependencies
+- ✅ Binds inherited methods
+- ✅ Supports Symbol-keyed methods
+- ✅ Include/exclude filters
+- ✅ Regex pattern matching
+- ✅ Lazy binding mode
+- ✅ React lifecycle awareness
+- ✅ Class & method decorators
+- ✅ Full TypeScript declarations
+- ✅ ESM + CommonJS dual package
+- ✅ Lightweight (~2KB)
+
+## License
+
+MIT

package/dist/decorator.cjs

@@ -0,0 +1,6 @@
+'use strict';
+const { boundClass, bound } = require('./index.cjs');
+module.exports = boundClass;
+module.exports.default = boundClass;
+module.exports.boundClass = boundClass;
+module.exports.bound = bound;

package/dist/decorator.d.ts

@@ -0,0 +1 @@
+export { boundClass, bound, boundClass as default } from './index';

package/dist/decorator.mjs

@@ -0,0 +1 @@
+export { boundClass, bound, boundClass as default } from './index.mjs';

package/dist/index.cjs

@@ -0,0 +1,226 @@
+/**
+ * auto-bind-js (CommonJS)
+ */
+
+'use strict';
+
+const BUILTIN_OBJECT_METHODS = new Set([
+  'constructor',
+  'toString',
+  'toLocaleString',
+  'valueOf',
+  'hasOwnProperty',
+  'isPrototypeOf',
+  'propertyIsEnumerable',
+  '__defineGetter__',
+  '__defineSetter__',
+  '__lookupGetter__',
+  '__lookupSetter__',
+]);
+
+function getAllMethodNames(obj) {
+  const methods = new Set();
+  let proto = Object.getPrototypeOf(obj);
+
+  while (proto && proto !== Object.prototype) {
+    const keys = Object.getOwnPropertyNames(proto);
+    for (const key of keys) {
+      if (key === 'constructor') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (descriptor && typeof descriptor.value === 'function') {
+        methods.add(key);
+      }
+    }
+
+    const symbols = Object.getOwnPropertySymbols(proto);
+    for (const sym of symbols) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, sym);
+      if (descriptor && typeof descriptor.value === 'function') {
+        methods.add(sym);
+      }
+    }
+
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  return methods;
+}
+
+function filterMethods(methods, options = {}) {
+  let filtered = [...methods];
+
+  filtered = filtered.filter((m) => typeof m === 'symbol' || !BUILTIN_OBJECT_METHODS.has(m));
+
+  if (options.include) {
+    const includeSet = new Set(options.include);
+    filtered = filtered.filter((m) => includeSet.has(m));
+  }
+
+  if (options.exclude) {
+    const excludeSet = new Set(options.exclude);
+    filtered = filtered.filter((m) => !excludeSet.has(m));
+  }
+
+  if (options.pattern) {
+    filtered = filtered.filter(
+      (m) => typeof m === 'string' && options.pattern.test(m)
+    );
+  }
+
+  return filtered;
+}
+
+function bindEager(self, methods) {
+  for (const method of methods) {
+    const val = self[method];
+    if (typeof val === 'function') {
+      Object.defineProperty(self, method, {
+        value: val.bind(self),
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      });
+    }
+  }
+}
+
+function findDescriptorInChain(obj, key) {
+  let proto = Object.getPrototypeOf(obj);
+  while (proto && proto !== Object.prototype) {
+    const desc = Object.getOwnPropertyDescriptor(proto, key);
+    if (desc) return desc;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return undefined;
+}
+
+function bindLazy(self, methods) {
+  for (const method of methods) {
+    const proto = Object.getPrototypeOf(self);
+    const descriptor = Object.getOwnPropertyDescriptor(proto, method) ||
+      findDescriptorInChain(self, method);
+
+    if (!descriptor || typeof descriptor.value !== 'function') continue;
+
+    const originalFn = descriptor.value;
+
+    Object.defineProperty(self, method, {
+      configurable: true,
+      enumerable: false,
+      get() {
+        const boundFn = originalFn.bind(self);
+        Object.defineProperty(self, method, {
+          value: boundFn,
+          writable: true,
+          configurable: true,
+          enumerable: false,
+        });
+        return boundFn;
+      },
+    });
+  }
+}
+
+function autoBind(self, options) {
+  if (typeof options === 'string') {
+    const methodNames = [options, ...Array.from(arguments).slice(2)];
+    options = { include: methodNames };
+  }
+
+  const allMethods = getAllMethodNames(self);
+  const methods = filterMethods(allMethods, options);
+
+  if (options && options.lazy) {
+    bindLazy(self, methods);
+  } else {
+    bindEager(self, methods);
+  }
+
+  return self;
+}
+
+// React
+const REACT_LIFECYCLE_METHODS = new Set([
+  'render',
+  'componentDidMount',
+  'componentDidUpdate',
+  'componentWillUnmount',
+  'shouldComponentUpdate',
+  'getSnapshotBeforeUpdate',
+  'getDerivedStateFromProps',
+  'getDerivedStateFromError',
+  'componentDidCatch',
+  'UNSAFE_componentWillMount',
+  'UNSAFE_componentWillReceiveProps',
+  'UNSAFE_componentWillUpdate',
+  'getDefaultProps',
+  'getInitialState',
+  'componentWillMount',
+  'componentWillReceiveProps',
+  'componentWillUpdate',
+]);
+
+function autoBindReact(self, options = {}) {
+  const exclude = [
+    ...(options.exclude || []),
+    ...REACT_LIFECYCLE_METHODS,
+  ];
+  return autoBind(self, { ...options, exclude });
+}
+
+// Decorators
+function boundClass(target) {
+  const original = target;
+
+  const wrapped = function (...args) {
+    const instance = new original(...args);
+    autoBind(instance);
+    return instance;
+  };
+
+  wrapped.prototype = original.prototype;
+  Object.defineProperty(wrapped, 'name', { value: original.name });
+  Object.setPrototypeOf(wrapped, original);
+
+  for (const key of Object.getOwnPropertyNames(original)) {
+    if (['length', 'name', 'prototype', 'arguments', 'caller'].includes(key)) continue;
+    const desc = Object.getOwnPropertyDescriptor(original, key);
+    if (desc) Object.defineProperty(wrapped, key, desc);
+  }
+
+  return wrapped;
+}
+
+function bound(target, key, descriptor) {
+  if (!descriptor || typeof descriptor.value !== 'function') {
+    throw new TypeError('@bound can only be applied to methods');
+  }
+
+  const fn = descriptor.value;
+
+  return {
+    configurable: true,
+    enumerable: false,
+    get() {
+      if (this === target) {
+        return fn;
+      }
+
+      const boundFn = fn.bind(this);
+      Object.defineProperty(this, key, {
+        value: boundFn,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      });
+      return boundFn;
+    },
+  };
+}
+
+module.exports = autoBind;
+module.exports.default = autoBind;
+module.exports.autoBind = autoBind;
+module.exports.autoBindReact = autoBindReact;
+module.exports.boundClass = boundClass;
+module.exports.bound = bound;

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+export interface AutoBindOptions {
+  /** Only bind these methods */
+  include?: (string | symbol)[];
+  /** Don't bind these methods */
+  exclude?: (string | symbol)[];
+  /** Only bind methods matching this regex */
+  pattern?: RegExp;
+  /** Use lazy binding (bind on first access via getter) */
+  lazy?: boolean;
+}
+
+/**
+ * Automatically bind all methods of an object to itself.
+ *
+ * @param self - The class instance (usually `this`)
+ * @param options - Configuration options
+ * @returns The instance (for chaining)
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   constructor() {
+ *     autoBind(this);
+ *   }
+ *   myMethod() {
+ *     return this;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Shorthand: bind specific methods
+ * autoBind(this, 'method1', 'method2');
+ * ```
+ */
+declare function autoBind<T extends object>(self: T, options?: AutoBindOptions): T;
+declare function autoBind<T extends object>(self: T, ...methods: string[]): T;
+
+/**
+ * React-aware autoBind. Automatically excludes React lifecycle methods.
+ *
+ * @param self - The React component instance
+ * @param options - Same options as autoBind
+ * @returns The instance
+ */
+export declare function autoBindReact<T extends object>(self: T, options?: AutoBindOptions): T;
+
+/**
+ * Class decorator that auto-binds all methods on instantiation.
+ *
+ * @example
+ * ```ts
+ * @boundClass
+ * class MyClass {
+ *   handleClick() { ... }
+ * }
+ * ```
+ */
+export declare function boundClass<T extends new (...args: any[]) => any>(target: T): T;
+
+/**
+ * Method decorator that lazily binds the method to the instance.
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   @bound
+ *   handleClick() { ... }
+ * }
+ * ```
+ */
+export declare function bound(
+  target: object,
+  key: string | symbol,
+  descriptor: PropertyDescriptor
+): PropertyDescriptor;
+
+export default autoBind;
+export { autoBind };

package/dist/index.mjs

@@ -0,0 +1,288 @@
+/**
+ * auto-bind-js
+ * Automatically bind class methods to their instance.
+ *
+ * Features:
+ * - Bind all own and inherited prototype methods
+ * - Include/exclude specific methods
+ * - Regex pattern matching for method names
+ * - Lazy binding (bind on first access via getter)
+ * - React-aware variant (skips lifecycle methods)
+ * - Class & method decorator support
+ * - Full TypeScript support
+ * - Zero dependencies
+ */
+
+const BUILTIN_OBJECT_METHODS = new Set([
+  'constructor',
+  'toString',
+  'toLocaleString',
+  'valueOf',
+  'hasOwnProperty',
+  'isPrototypeOf',
+  'propertyIsEnumerable',
+  '__defineGetter__',
+  '__defineSetter__',
+  '__lookupGetter__',
+  '__lookupSetter__',
+]);
+
+/**
+ * Get all method names from the prototype chain (excluding Object.prototype)
+ */
+function getAllMethodNames(obj) {
+  const methods = new Set();
+  let proto = Object.getPrototypeOf(obj);
+
+  while (proto && proto !== Object.prototype) {
+    const keys = Object.getOwnPropertyNames(proto);
+    for (const key of keys) {
+      if (key === 'constructor') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (descriptor && typeof descriptor.value === 'function') {
+        methods.add(key);
+      }
+    }
+
+    // Also handle Symbol-keyed methods
+    const symbols = Object.getOwnPropertySymbols(proto);
+    for (const sym of symbols) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, sym);
+      if (descriptor && typeof descriptor.value === 'function') {
+        methods.add(sym);
+      }
+    }
+
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  return methods;
+}
+
+/**
+ * Filter methods based on options
+ */
+function filterMethods(methods, options = {}) {
+  let filtered = [...methods];
+
+  // Remove built-in object methods
+  filtered = filtered.filter((m) => typeof m === 'symbol' || !BUILTIN_OBJECT_METHODS.has(m));
+
+  // Include only specific methods
+  if (options.include) {
+    const includeSet = new Set(options.include);
+    filtered = filtered.filter((m) => includeSet.has(m));
+  }
+
+  // Exclude specific methods
+  if (options.exclude) {
+    const excludeSet = new Set(options.exclude);
+    filtered = filtered.filter((m) => !excludeSet.has(m));
+  }
+
+  // Match pattern
+  if (options.pattern) {
+    filtered = filtered.filter(
+      (m) => typeof m === 'string' && options.pattern.test(m)
+    );
+  }
+
+  return filtered;
+}
+
+/**
+ * Bind methods eagerly (standard mode)
+ */
+function bindEager(self, methods) {
+  for (const method of methods) {
+    const val = self[method];
+    if (typeof val === 'function') {
+      Object.defineProperty(self, method, {
+        value: val.bind(self),
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      });
+    }
+  }
+}
+
+/**
+ * Bind methods lazily (bind on first access)
+ */
+function bindLazy(self, methods) {
+  for (const method of methods) {
+    const proto = Object.getPrototypeOf(self);
+    const descriptor = Object.getOwnPropertyDescriptor(proto, method) ||
+      findDescriptorInChain(self, method);
+
+    if (!descriptor || typeof descriptor.value !== 'function') continue;
+
+    const originalFn = descriptor.value;
+
+    Object.defineProperty(self, method, {
+      configurable: true,
+      enumerable: false,
+      get() {
+        const boundFn = originalFn.bind(self);
+        // Replace getter with the bound value on first access
+        Object.defineProperty(self, method, {
+          value: boundFn,
+          writable: true,
+          configurable: true,
+          enumerable: false,
+        });
+        return boundFn;
+      },
+    });
+  }
+}
+
+function findDescriptorInChain(obj, key) {
+  let proto = Object.getPrototypeOf(obj);
+  while (proto && proto !== Object.prototype) {
+    const desc = Object.getOwnPropertyDescriptor(proto, key);
+    if (desc) return desc;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return undefined;
+}
+
+/**
+ * Main autoBind function
+ *
+ * @param {object} self - The class instance (usually `this`)
+ * @param {object} [options] - Configuration options
+ * @param {string[]} [options.include] - Only bind these methods
+ * @param {string[]} [options.exclude] - Don't bind these methods
+ * @param {RegExp} [options.pattern] - Only bind methods matching this regex
+ * @param {boolean} [options.lazy] - Use lazy binding (bind on first access)
+ * @returns {object} The instance (for chaining)
+ */
+function autoBind(self, options) {
+  // Support autoBind(this, 'method1', 'method2') shorthand
+  if (typeof options === 'string') {
+    const methodNames = [options, ...Array.from(arguments).slice(2)];
+    options = { include: methodNames };
+  }
+
+  const allMethods = getAllMethodNames(self);
+  const methods = filterMethods(allMethods, options);
+
+  if (options && options.lazy) {
+    bindLazy(self, methods);
+  } else {
+    bindEager(self, methods);
+  }
+
+  return self;
+}
+
+// ─── React-aware variant ────────────────────────────────────────────────────
+
+const REACT_LIFECYCLE_METHODS = new Set([
+  'render',
+  'componentDidMount',
+  'componentDidUpdate',
+  'componentWillUnmount',
+  'shouldComponentUpdate',
+  'getSnapshotBeforeUpdate',
+  'getDerivedStateFromProps',
+  'getDerivedStateFromError',
+  'componentDidCatch',
+  'UNSAFE_componentWillMount',
+  'UNSAFE_componentWillReceiveProps',
+  'UNSAFE_componentWillUpdate',
+  'getDefaultProps',
+  'getInitialState',
+  'componentWillMount',
+  'componentWillReceiveProps',
+  'componentWillUpdate',
+]);
+
+/**
+ * React-aware autoBind. Skips React lifecycle methods.
+ *
+ * @param {object} self - The component instance
+ * @param {object} [options] - Same options as autoBind (exclude is merged)
+ * @returns {object} The instance
+ */
+function autoBindReact(self, options = {}) {
+  const exclude = [
+    ...(options.exclude || []),
+    ...REACT_LIFECYCLE_METHODS,
+  ];
+  return autoBind(self, { ...options, exclude });
+}
+
+// ─── Decorator ──────────────────────────────────────────────────────────────
+
+/**
+ * Class decorator: @boundClass
+ * Method decorator: @bound
+ *
+ * Usage:
+ *   @boundClass
+ *   class Foo { ... }
+ *
+ *   class Foo {
+ *     @bound
+ *     handleClick() { ... }
+ *   }
+ */
+function boundClass(target) {
+  const original = target;
+
+  const wrapped = function (...args) {
+    const instance = new original(...args);
+    autoBind(instance);
+    return instance;
+  };
+
+  wrapped.prototype = original.prototype;
+  Object.defineProperty(wrapped, 'name', { value: original.name });
+  Object.setPrototypeOf(wrapped, original);
+
+  // Copy static properties
+  for (const key of Object.getOwnPropertyNames(original)) {
+    if (['length', 'name', 'prototype', 'arguments', 'caller'].includes(key)) continue;
+    const desc = Object.getOwnPropertyDescriptor(original, key);
+    if (desc) Object.defineProperty(wrapped, key, desc);
+  }
+
+  return wrapped;
+}
+
+/**
+ * Method decorator
+ */
+function bound(target, key, descriptor) {
+  if (!descriptor || typeof descriptor.value !== 'function') {
+    throw new TypeError('@bound can only be applied to methods');
+  }
+
+  const fn = descriptor.value;
+
+  return {
+    configurable: true,
+    enumerable: false,
+    get() {
+      // Only define on the instance, not the prototype
+      if (this === target) {
+        return fn;
+      }
+
+      const boundFn = fn.bind(this);
+      Object.defineProperty(this, key, {
+        value: boundFn,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      });
+      return boundFn;
+    },
+  };
+}
+
+export default autoBind;
+export { autoBind, autoBindReact, boundClass, bound };

package/dist/react.cjs

@@ -0,0 +1,5 @@
+'use strict';
+const { autoBindReact } = require('./index.cjs');
+module.exports = autoBindReact;
+module.exports.default = autoBindReact;
+module.exports.autoBindReact = autoBindReact;

package/dist/react.d.ts

@@ -0,0 +1,4 @@
+import { AutoBindOptions } from './index';
+declare function autoBindReact<T extends object>(self: T, options?: AutoBindOptions): T;
+export default autoBindReact;
+export { autoBindReact };

package/dist/react.mjs

@@ -0,0 +1 @@
+export { autoBindReact as default, autoBindReact } from './index.mjs';

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "auto-bind-js",
+  "version": "1.0.0",
+  "description": "Automatically bind class methods to their instance. Supports include/exclude filters, decorator pattern, inheritance, and lazy binding.",
+  "author": "mohammad alemzadeh <alemzadeh.mohammad@outlook.com>",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.cjs",
+      "types": "./dist/react.d.ts"
+    },
+    "./decorator": {
+      "import": "./dist/decorator.mjs",
+      "require": "./dist/decorator.cjs",
+      "types": "./dist/decorator.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "test": "npx jest --no-cache",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "auto-bind",
+    "autobind",
+    "bind",
+    "class",
+    "methods",
+    "this",
+    "context",
+    "react",
+    "decorator",
+    "prototype",
+    "es6",
+    "es2015"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MMDALEM/auto-bind-js"
+  },
+  "engines": {
+    "node": "22"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}