ES6 classes and Advanced Typings

.github/workflows/node.js.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x, 19.x]
+        node-version: [16.x, 18.x, 19.x, 20.x, 21.x, 22.x, 23.x, 24.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:

.gitignore

@@ -36,4 +36,5 @@ jspm_packages
 # Optional REPL history
 .node_repl_history
 
-/dist
+# dist
+dist

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://img.shields.io/github/actions/workflow/status/CGamesPlay/node-callable-instance/node.js.yml?branch=master)](https://github.com/CGamesPlay/node-callable-instance/actions/workflows/node.js.yml) [![Download Size](https://img.shields.io/bundlephobia/min/callable-instance.svg?style=flat)](https://bundlephobia.com/package/callable-instance@latest) [![dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](https://www.npmjs.com/package/callable-instance?activeTab=dependencies) [![npm](https://img.shields.io/npm/v/callable-instance)](https://www.npmjs.com/package/callable-instance) [![npm](https://img.shields.io/npm/dw/callable-instance)](https://www.npmjs.com/package/callable-instance)
 
-This module allows you to create an ES6 class that is callable as a function. The invocation is sent to one of the object's normal prototype methods.
+This module allows you to create an ES6 `class` or regular JS `Object` that is callable as a function.
 
 ## Installation
 
@@ -15,65 +15,177 @@ npm install callable-instance
 In the following example, we will create an `ExampleClass` class. The instances have all of the normal properties and methods, but are actually functions as well.
 
 ```javascript
-import CallableInstance from "callable-instance";
+import Callable from "callable-instance";
 // If you aren't using ES modules, you can use require:
-// var CallableInstance = require("callable-instance");
+// var Callable = require("callable-instance");
 
-class ExampleClass extends CallableInstance {
+class ExampleClass extends Callable {
   constructor() {
-    // CallableInstance accepts the name of the property to use as the callable
-    // method.
-    super("instanceMethod");
+    super();
   }
-
-  instanceMethod() {
-    console.log("instanceMethod called!");
+  [Callable.CALL](arg) {
+    return arg
   }
 }
 
 var test = new ExampleClass();
 // Invoke the method normally
-test.instanceMethod();
-// Call the instance itself, redirects to instanceMethod
+test[Callable.CALL]();
+// Call the instance itself, redirects to [Callable.CALL]
 test();
-// The instance is actually a closure bound to itself and can be used like a
-// normal function.
-test.apply(null, [1, 2, 3]);
+```
+> **_NOTE:_**  Usage of custom method name is also supported.
+
+```javascript
+class ExampleClassWithCustomMethodName extends Callable {
+    constructor(){
+        // in super provide object method`s name which will be used when calling object
+        super('myMethod')
+    }
+    myMethod(arg){
+        return arg
+    }
+}
+```
+
+### Other Usage Variant
+In the next example, we will create `callableObject` using Callable.makeCallable.
+
+```javascript
+import Callable from "callable-instance";
+// makeCallable creates new callable object with all the properties from source object
+const callableObject = Callable.makeCallable({
+  test: "test",
+  [Callable.CALL]() {
+    return this.test;
+  },
+});
+
+// cloning using spread operator + makeCallable. (spread looses call signature so it is important to call makeCallable again)
+const cloned = Callable.makeCallable({...callableObject});
+
+// cloning using Callable.clone (accepts only direct instance of Callable. e.g. made with makeCallable)
+const cloned2 = Callable.clone(callableObject);
+```
+> **_NOTE:_**  Usage of custom method name is also supported.
+```javascript
+import Callable from "callable-instance";
+const callableObject = Callable.makeCallable({
+  test: "test",
+  getTest() {
+    return this.test;
+  },
+}, "getTest"); // second parameter is optional method`s name which will be used when calling object
+
+// but it is important to also provide method name when cloning using spread + makeCallable
+const cloned = Callable.makeCallable({...callableObject}, "getTest");
+
+// Callable.clone does not have this issue
+const cloned2 = Callable.clone(callableObject);
+```
+
+## Typescript
+
+
+`Callable` has full typescript support.
+
+1. **Using interface**
+
+```typescript
+// Callable has 2 generics
+// 1st is for class | interface | function (for extracting type of call signature)
+// 2nd optional generic is for method name (string | symbol | number) which will be used as type of call signature from 1st generic (defaults to Callable.CALL)
+
+interface IExampleClass {
+  // interface type will provide actual type of the function without limits
+  [Callable.CALL](arg: string): string
+}
+// implements is optional but advised https://www.typescriptlang.org/docs/handbook/interfaces.html
+class ExampleClass extends Callable<IExampleClass> implements IExampleClass {
+    constructor(){
+        super()
+    }
+    [Callable.CALL](arg: string){
+        return arg
+    }
+}
 ```
 
-TypeScript is also supported. `CallableInstance` is generic, accepting a tuple of arguments and a return type.
+2. **Using function type**
+```typescript
+class ExampleClass extends Callable<(arg: string) => string> {
+    constructor(){
+        super()
+    }
+    [Callable.CALL](arg: string){
+        return arg
+    }
+}
+```
 
+3. **Using class type**
 ```typescript
-import CallableInstance from "callable-instance";
+// easiest way for typing Callable
+class ExampleClass extends Callable<typeof ExampleClass> {
+    constructor(){
+        super()
+    }
+    [Callable.CALL](arg: string){
+        return arg
+    }
+}
+```
+> **_NOTE:_**  For function overload or generics use Interface or Function variant.
+
+### **Override Call**
 
-class ExampleClass extends CallableInstance<[number], string> {
+Due to typescript limitations module also provides OverrideCall type.
+It can be used to override call signature in child classes.
+
+```typescript
+// Override call has 3 generics but must be written only in one way
+// class Child extends (Parent as OverrideCall<typeof Parent>)<Child, propertyName>
+// 1st generic is Parent
+// 2nd generic is Child. Can be interface | class | function
+// 3rd optional generic is propertyName can be string | symbol | number. defaults to Callable.CALL
+
+// call signature is (() => string)
+class ExampleClass extends Callable<() => string> {
   constructor() {
-    super("instanceMethod");
+    super();
   }
-
-  instanceMethod(input: number): string {
-    return `${input}`;
+  [Callable.CALL]() {
+    return "test";
   }
 }
-```
 
-Note that the types specified may differ from the argument and return value types of the target method; this is an error due to a limitation of TypeScript.
+// overriding call signature to (() => number)
+class ExampleClassChild extends (ExampleClass as OverrideCall<typeof ExampleClass>)<() => number> {
+  constructor(){
+    super();
+  }
 
+  [Callable.CALL](){
+    return 100
+  }
+}
+```
 
-### Inherited Properties
+## Inherited Properties
 
 All instances of CallableMethod are also an instances of [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function), and have all of Function's properties.
 
-Libraries that accept functions will expect that they behave as Function objects do. For example, if you alter the semantics of the `call` or `apply` methods, library code may fail to work with your callable instance. In these cases, you can simply bind the instance method to the callable instance and pass that instead (e.g. `test.instanceMethod.bind(test)`).
+`Callable` behaves exactly like the method specified in constructor but they are not equal. `Callable` just creates an alias to the function. It's `bind`, `apply`, `call` methods behaves exactly like used function's methods. So it is safe to use `call`, `apply` or `bind` on `Callable` directly. `test.call(test2, ...args)` will return `test.instanceMethod.call(test2, ...args)`.
 
-This can also cause problems if your derived class wants to have a `name` or `length` property, which are built-in properties and not configurable by default. You can have your class disable the built-in descriptors of these properties to make them available for your use.
+Libraries that accept functions will expect that they behave as Function objects do. For example, if you alter the semantics of the call or apply methods, library code may fail to work with your callable instance. This can also cause problems if your derived class wants to have a `name` or `length` property, which are built-in properties and not configurable by default. You can have your class disable the built-in descriptors of these properties to make them available for your use.
 
 ```javascript
 var test = new ExampleClass();
+console.log(test.name); // Will print 'ExampleClass' (constructor.name is used by default)
 test.name = "hello!";
-console.log(test.name); // Will print 'instanceMethod'
+console.log(test.name); // Will print 'ExampleClass'
 
-class NameableClass extends CallableInstance {
+class NameableClass extends Callable {
   constructor() {
     super("instanceMethod");
     Object.defineProperty(this, "name", {

lib/index.d.ts

@@ -0,0 +1,78 @@
+declare module "callable-instance" {
+  const CALL: unique symbol;
+  export type SCALL = typeof CALL;
+
+  type BaseProperty = symbol | string | number;
+  type CustomProperty = Exclude<BaseProperty, SCALL>;
+
+  type BaseFunc = (...args: any) => any;
+  type BaseClass = abstract new (...args: any) => any;
+  type BaseInterface = {
+    [k: BaseProperty]: any;
+  };
+
+  type ExtractFuncFromInterface<
+    I extends BaseInterface,
+    P extends BaseProperty
+  > = I[P] extends BaseFunc ? I[P] : never;
+
+  interface CloneFuncFromClass<C extends BaseClass, P extends BaseProperty> {
+    /**
+     * For TS generics and function overload support use interface or function type for Callable
+     */
+    (...args: Parameters<InstanceType<C>[P]>): ReturnType<InstanceType<C>[P]>;
+  }
+  type ExtractFunc<
+    C extends BaseClass | BaseFunc | BaseInterface,
+    P extends BaseProperty
+  > = C extends BaseClass
+    ? CloneFuncFromClass<C, P>
+    : C extends BaseFunc
+    ? C
+    : C extends BaseInterface
+    ? ExtractFuncFromInterface<C, P>
+    : never;
+
+  export interface CallableConstructor {
+    get CALL(): SCALL;
+
+    makeCallable<I extends BaseInterface, P extends CustomProperty>(
+      object: I,
+      property: P
+    ): PickProperties<I> & ExtractFuncFromInterface<I, P>;
+    makeCallable<I extends BaseInterface>(
+      object: I
+    ): PickProperties<I> & ExtractFuncFromInterface<I, SCALL>;
+
+    clone<C extends BaseInterface & BaseFunc>(callableObject: C): C;
+
+    new <
+      C extends BaseClass | BaseFunc | BaseInterface,
+      P extends CustomProperty
+    >(
+      property: P
+    ): ExtractFunc<C, P>;
+
+    new <C extends BaseClass | BaseFunc | BaseInterface>(): ExtractFunc<
+      C,
+      SCALL
+    >;
+  }
+
+  type PickProperties<Obj extends Record<BaseProperty, unknown>> = {
+    [k in keyof Obj]: Obj[k];
+  };
+
+  export type OverrideCall<S extends BaseClass> = {
+    new <
+      C extends BaseClass | BaseFunc | BaseInterface,
+      P extends BaseProperty = SCALL
+    >(
+      ...args: ConstructorParameters<S>
+    ): Omit<PickProperties<InstanceType<S>>, P> & ExtractFunc<C, P>;
+  } & S;
+
+  const Callable: CallableConstructor;
+
+  export default Callable;
+}