GithubHelp home page GithubHelp logo

evelynhathaway / bind-deep Goto Github PK

View Code? Open in Web Editor NEW
3.0 2.0 0.0 1.97 MB

๐Ÿ“Ž๐Ÿ•ณ๏ธ Lightweight module for binding a function or object deeply

Home Page: https://npmjs.com/package/bind-deep

License: MIT License

JavaScript 98.58% Shell 1.42%
nodejs bind this context function object deep typescript bound-arguments hacktoberfest

bind-deep's Introduction

Bind Deep icon

Bind Deep

Lightweight module for binding a function or object deeply

npm version check status minified + gzip bundle size license: MIT

Description

Bind an object to this in all methods in a function, object, or array. A simple, single-dependency (only for TypeScript types) alternative to deep-bind.

Features

  • Binds the root function and all own, enumerable property functions including property accessors
  • Compatible with functions, arrays, objects, custom classes, and array-likes
  • Binds the this value and optionally, additional arguments just like func.bind()
  • Copies objects and enumerable properties deeply
  • Preserves and copies prototypes for all types
  • New in v2.1.0: Strict TypeScript type definitions

Installation

npm install bind-deep --save

Usage

bindDeep(object, thisArg, [...args])

Returns: Function | Object | Array - The function or object passed as object but with itself and all methods bound to thisArg

Parameter Type Description
object Function | Object | Array Function or object to bind itself and all of its methods
thisArg Object The value bound to this for each bound function and method when called
[...args] any Arguments provided to the bound function when the bound function is invoked

Example

// Require bind-deep
const bindDeep = require("bind-deep");


// Original object and function
// Could also be an actual object
const func = function() {
    // Use `this`
};
func.method = function() {
    // Use `this` again
};

const obj = {
    method() {
        // Use `this`
    }
};


// Deeply bound object and function
// `thisArg` will be what every function and method will see as `this`
const boundObj = bindDeep(obj, thisArg);
// => {method: [Function: bound]}

const boundFunc = bindDeep(func, thisArg);
// => {[Function: bound] method: [Function: bound]}

TypeScript

All types inferred or annotated are preserved from the original functions and objects. The type definitions are incredibly strong deep types as the only negative side-effects are:

  • If bound arguments are added, the arguments in call signatures are renamed by their bound position.
  • If more than around 39 bound arguments are added, TypeScript will error Type instantiation is excessively deep and possibly infinite.
    • If you somehow do this, slap on an as any or your manually created type

An in-depth explanation is commented inside of index.d.ts and below with example code.

// Import bind-deep
import bindDeep from "bind-deep";


interface OriginalThis {
    discriminator: string;
}

// Original function
const myFunction = function (this: OriginalThis, arg1: string, arg2: number) {
    return this;
};
myFunction.method = function (this: OriginalThis, arg1: string) {
    return this;
};
myFunction.primitive = "string";

// `thisArg` value
const newThis = { newThis: "that's me!"};

// Deeply bound functions
const boundFunction = bindDeep(myFunction, newThis);
const boundFunctionWithArgs = bindDeep(myFunction, newThis, "add arg1 for each function");

/*
    Root call signature: `(arg1: string, arg2: number) => OriginalThis`
    - `this` argument type omitted from the original call signature as it is now bound
    - All other argument types and names are preserved
    - Returns `newThis` as `OriginalThis` due to the return value inferred by TypeScript
*/
boundFunction("arg1", 10); // returns `newThis`
/*
    Root call signature when passing an argument: `((args_0: number) => OriginalThis)`
    - Similar explanation to the root call signature
    - `arg1` argument type omitted from the original call signature as it is now bound
    - `arg2` is represented as `args_0` with the number type preserved
        - This unfortunate renaming only occurs when binding arguments
*/
boundFunctionWithArgs(10); // returns `newThis`

/*
    Method call signature: `(method) method(arg1: string): OriginalThis`
*/
boundFunction.method("arg1"); // returns `newThis`
/*
    Method call signature when passing an argument: `(method) method(): OriginalThis`
*/
boundFunctionWithArgs.method(); // returns `newThis`

/*
    Primitive property type: `primitive: string`
*/
const myString: string = boundFunction.primitive; // still "string", typings preserved

License

Copyright Evelyn Hathaway, MIT License

bind-deep's People

Contributors

dependabot[bot] avatar evelynhathaway avatar semantic-release-bot avatar

Stargazers

 avatar  avatar  avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.