![](\"./docs/img/title.png\")
\r\n\r\n \r\n
\r\n English | 简体中文 \r\n
\r\n\r\n\r\n# ts-chain-core\r\n\r\nThis is a basic library for TypeScript chain programming. It can be used to build anything from simple tools to comprehensive toolkits.\r\n\r\n### Features\r\n\r\n- Enables chain programming with minimal code\r\n- Saves code: tools built using this library can reduce actual code by half or more in some cases\r\n- **💥💥Auto Interface Completion ** Interfaces you write will automatically appear in your code as you type! Below is an actual demonstration (using vscode, no special plugins)\r\n\r\n- **🌈Easy to use** You only need to master three core APIs to create chain interfaces that meet most needs.\r\n- **🚀Compact** The program itself is only `3kb` in size after compression.\r\n\r\n\r\n### Quick Start\r\n\r\n#### Installation\r\n\r\n```shell\r\nnpm i ts-chain-core\r\n```\r\n#### Basic Usage\r\n\r\n```ts\r\nimport { ChainCore } from \"ts-chain-core\";\r\n\r\nChainCore(null)\r\n .setFunction((name: string) => {\r\n console.log(`hello,${name}`);\r\n })\r\n ('🍉')\r\n ('🍍')\r\n ('🥭')\r\n```\r\n\r\n### 🔗Turning Class Methods into Chainable Methods\r\n\r\n```ts\r\nclass Example {\r\n toChain(){\r\n return ChainCore(this).extendFunctionsFromObject(Example)\r\n }\r\n add(a:number,b:number){\r\n console.log(a+b)\r\n }\r\n addOne(a:number){\r\n return (b:number)=>{\r\n console.log(a+b)\r\n }\r\n }\r\n addEnd(a:number,b:number){\r\n return a+b;\r\n }\r\n}\r\n\r\nnew Example().toChain()\r\n .add(3,5) //8\r\n .add(4,7) //11\r\n .addOne(4) \r\n (5) //9\r\n (6) //10\r\n (7) //11\r\n .addEnd(11,10) //chain ended here\r\n .add(42,1) //❌error, chain function break\r\n```\r\n\r\n\r\nWhen extending the library, different chainable methods will be generated based on the return type of the methods.\r\n| Return Types | `undefined / void` | `function` | other types |\r\n| --- | --- | --- | -- |\r\n| modify the `()` operation | No | set function to `()` operation | No |\r\n| terminate the chain | No | No | No |\r\n\r\nBut the `()` operation does not change `()` operation itself regardless of its return type.\r\n\r\n### 🔗Extending Instance Methods\r\n\r\nIn the process of extending methods, you may need to call methods that have already been extended by `ChainCore` or methods that are inherent to `ChainCore`. In such methods, you need to add a reference to `ChainCore` instance in the entry parameters.\r\n`ts-chain-core` provides a method for extending these methods and automatically passing in the `ChainCore` instance when the method is called. We refer to these methods as **instance methods**.\r\n\r\nExample of Extending Methods\r\n\r\n\r\n```ts\r\nChainCore(null).extendFunctionsFromObject({\r\n sayHello: (name: string) => {\r\n console.log(`hello,${name}`);\r\n },\r\n}).extendInstanceFunctions({\r\n /**\r\n * play a scenario\r\n * @param ch passed by `ChainCore` and reference to itself\r\n * @param time \r\n * @param place \r\n * @param to \r\n */\r\n play(ch,time:string,place:string,to:string){\r\n console.log(`This is ${time},${place}`);\r\n ch.sayHello(to)\r\n }\r\n}).play('morning','garden','🍓')\r\n```\r\n\r\nWhen extending `instance methods`, the first entry parameter should be reserved for `ts-chain-core`. It does not need to be annotated with a type, and does not have to be passed in when called.\r\n\r\n#### Callbacks in Extended Methods\r\n\r\nIn extended methods, you may need to access `ChainCore` methods inside callbacks. Below is a different implementation of the previous example:\r\n\r\n```ts\r\nChainCore(null).extendFunctionsFromObject({\r\n sayHello: (name: string) => {\r\n console.log(`hello,${name}`);\r\n },\r\n}).extendInstanceFunctions({\r\n /**\r\n * play a scenario\r\n * @param ch passed by `ChainCore` and reference to itself\r\n * @param fn play anything you wanted in this function\r\n */\r\n play(ch,fn:(ch:CurrentStateChainRef)=>void){\r\n fn.apply(null,[ch]);\r\n }\r\n}).play((ch)=>{\r\n console.log(`This is morning,garden`);\r\n ch.sayHello('🍓')\r\n}) \r\n```\r\nThe first parameter in the callback function should be annotated with the `CurrentStateChainRef` type. When called, the passed-in `ChainCore` instance will automatically receive code hints for previously extended methods.\r\n\r\n`Instance methods` can also have the `()` operation set, and callbacks can use it to access the `ChainCore` instance.\r\n\r\n```ts\r\nChainCore(null).extendFunctionsFromObject({\r\n sayHello: (name: string) => {\r\n console.log(`hello,${name}`);\r\n },\r\n}).extendInstanceFunctions({\r\n play(ch){\r\n return (fn:(ch:CurrentStateChainRef,time:string,place:string,to:string)=>void,time:string,place:string,to:string)=>{\r\n fn.apply(null,[ch,time,place,to]);\r\n }\r\n }\r\n}).play()((ch,time,place,to)=>{\r\n console.log(`This is ${time},${place}`);\r\n ch.sayHello(to)\r\n},'morning','garden','🍓');\r\n```\r\n\r\n**Attention** 📢📢 *It is important to note that the `ChainCore` instance in the callback function is passed in by the extended method itself. You do not need to pass the `ChainCore` instance as the first parameter, but it is convention to annotate the type of the first parameter as `CurrentStateChainRef` so that it is properly recognized as the `ChainCore` type.*\r\n\r\n\r\n\r\n##### 📑Type Remapping\r\n\r\n`ts-chain-core` uses type remapping to achieve automatic type conversions for convenient auto-completion features. `CurrentStateChainRef` is one example of this. More examples will be discussed later.\r\n\r\nHowever, there are limitations to this technique. Firstly, due to restrictions in `TypeScript`, it is not practical to automate type conversions for all parameters. To strike a balance between usability and computational overhead, this feature currently only supports the automatic conversion of the return type and the first four parameters. In the majority of cases, this is sufficient.\r\n\r\nAdditionally, remapping does not support generic mappings. However, ts-chain-core provides a solution for this, which will be discussed later.\r\n\r\n\r\n\r\n##### 🔍Declaring ChainCore Types\r\n\r\nSince `ChainCore` is a complex type, there may be situations where you need to declare the `ChainCore` type with certain methods extended. In most cases, directly writing the `ChainCore` type is not recommended due to its complexity. Instead, it is recommended to use type inference to declare the type.\r\n\r\n```ts\r\n//Declaration Example\r\nfunction chainFactory(){\r\n return ChainCore(null).extendFunctionsFromObject({\r\n sayHello: (name: string) => {\r\n console.log(`hello,${name}`);\r\n },\r\n //some other functions\r\n })\r\n}\r\n\r\ntype MyChainType = ReturnType