Module binder

utility functions for creating other general purpose functions that can bind their passed function's functionality to some specific object.
those are certainly a lot of words thrown in the air with no clarity as to what am I even saying.
just as they say, a code block example is worth a thousand assembly instructions. here's the gist of it:

import { bindMethodFactory, bindMethodFactoryByName } from "./kitchensink_ts/binder.ts"

const bind_pushing_to = bindMethodFactory(Array.prototype.push) // equivalent to `bindMethodFactoryByName(Array.prototype, "push")`
const bind_seek_to = bindMethodFactory(Array.prototype.at, -1) // equivalent to `bindMethodFactoryByName(Array.prototype, "at", -1)`
const bind_splicing_to = bindMethodFactoryByName(Array.prototype, "splice") // equivalent to `bindMethodFactory(Array.prototype.splice)`
const bind_clear_to = bindMethodFactoryByName(Array.prototype, "splice", 0) // equivalent to `bindMethodFactory(Array.prototype.splice, 0)`

const my_array = [1, 2, 3, 4, 5, 6]
const push_my_array = bind_pushing_to(my_array)
const seek_my_array = bind_seek_to(my_array)
const splice_my_array = bind_splicing_to(my_array)
const clear_my_array = bind_clear_to(my_array)
const log_my_array = () => { console.log(my_array) }

push_my_array(7, 8, 9); log_my_array() // [1, 2, 3, 4, 5, 6, 7, 8, 9]
console.log(seek_my_array(9)) // 9
splice_my_array(4, 3); log_my_array() // [1, 2, 3, 4, 8, 9]
clear_my_array(); log_my_array() // []
Copy

you may have some amateur level questions about why? would anyone want to do that. here is why:

• calling a method via property access is slower. so when you call an array arr's push or pop methods a million times, having a bound function for that specific purpose will be quicker by about x1.3 times:

let i = 1000000, j = 1000000
const arr = Array(777).fill(0).map(Math.random)
// slower way:
while(i--) { arr.push(Math.random); arr.pop() }
// faster way:
const push_arr = Array.prototype.push.bind(arr)
const pop_arr = Array.prototype.pop.bind(arr)
while(j--) { push_arr(Math.random); pop_arr() }
Copy

• next, you may be wondering why not destructure the method or assign it to a variable? this cannot be generally done for prototype-bound methods, because it needs the context of who is the caller (and therefor the this of interest). all builtin javascript class methods are prototype-bound. meaning that for every instance of a builtin class no new functions are specifically created for that instance, and instead, the instance holds a reference to the class's prototype object's method, but applies itself as the this when called.

const arr = [1, 2, 3, 4, 5, 6]
// prototype-bound methods need to be called via property access, otherwise they will loose their `this` context when uncoupled from their parent object
const { push, pop } = arr
push(7, 8, 9) // `TypeError: Cannot convert undefined or null to object`
pop() // `TypeError: Cannot convert undefined or null to object`
const push2 = arr.push, pop2 = arr.pop
push2(7, 8, 9) // `TypeError: Cannot convert undefined or null to object`
pop2() // `TypeError: Cannot convert undefined or null to object`
// but you can do the binding yourself too to make it work
const push3 = arr.push.bind(arr) // equivalent to `Array.prototype.push.bind(arr)`
const pop3 = arr.pop.bind(arr) // equivalent to `Array.prototype.pop.bind(arr)`
push3(7, 8, 9) // will work
pop3() // will work
// or use this submodule to do the same thing:
import { bind_array_pop, bind_array_push } from "./kitchensink_ts/binder.ts"
const push4 = bind_array_push(arr)
const pop4 = bind_array_pop(arr)
push4(7, 8, 9) // will work
pop4() // will work
Copy

• finally, property accesses are not easily minifiable (although they do get compressed when gzipped). however, if you bind your method calls to a variable, then it will become minifiable, which is somewhat the primary motivation for this submodule.

with full automatic typing, you won't be compensating in any way.
on the side note, it was figuring out the automatic typing that took me almost 16 hours just to write 3 lines of equivalent javascript code for the main 2 factory functions of this submodule.
curse you typescript!