defered-branch 2.0.0 → 2.1.1

package/README.md

@@ -12,7 +12,7 @@ A TypeScript/JavaScript library that provides elegant deferred conditional branc
 - 🔒 **Type Safe**: Full TypeScript support with proper type inference
 - 🪶 **Lightweight**: Zero dependencies, minimal footprint
 - 🧩 **Flexible**: Works with any function signature and return types
-- 📦 **ESM Ready**: Modern module system support
+- 📦 **Type Annotation**: Full type annotation supported for the exported functions. You can customize handler's type of branch/condition/nomatch.
 
 ## 📦 Installation
 
@@ -59,6 +59,8 @@ branch
 // 3. Handle no-match case (optional)
 branch.nomatch(() => 'Access denied');
 
+// some other logic... like validate other arguments
+
 // 4. Execute and get result
 const result = branch.run();
 console.log(result); // Output based on user.role
@@ -165,7 +167,7 @@ Creates a new deferred branch instance for immediate execution scenarios.
 ##### `.add(condition: boolean, branch: Function): DeferBranch`
 
 - Adds a conditional branch that executes if condition is `true`
-- **Overrides** previous matched branches
+- First-match wins: the first truthy branch will be selected; later entries are ignored
 - Returns the instance for chaining
 
 ##### `.nomatch(handler: Function): DeferBranch`
@@ -190,13 +192,70 @@ Creates a new dynamic deferred branch instance for reusable logic patterns.
 
 - Adds a predicate-based conditional branch
 - `condition` is a function that returns boolean
-- **Overrides** previous matched branches
+- First-match wins: the first truthy branch will be selected; later entries are ignored
 
 ##### `.nomatch(handler: Function): DeferBranchDynamic`
 
 - Sets a fallback handler for when no predicates match
 - Executes during `.predicate()` evaluation
 
+## 🧾 Type Annotation
+
+The factory functions `deferedBranch` and `deferedBranchDynamic` are generic helpers. You can provide explicit type parameters to describe the branch function signature and the optional `nomatch` handler.
+
+Below is an example using `deferedBranch`:
+
+```typescript
+import { deferedBranch } from 'defered-branch';
+
+// Here we declare that branches accept a message (string) and return void.
+// The factory signature is: deferedBranch<BranchFn, NoMatchFn>()
+const handler = deferedBranch<(msg: string) => void, () => void>();
+
+handler
+  .add(
+    process.env.STATUS === 'ok',
+    (msg) => console.log('OK:', msg) // this is restricted by `(msg: string) => void`
+  )
+  .add(
+    process.env.STATUS === 'warn',
+    (msg) => console.warn('WARN:', msg) // this is restricted by `(msg: string) => void`
+  )
+  .nomatch(
+    () => console.debug('unknown') // this is restricted by `() => void`
+  );
+
+handler.run('hello world'); // input args for `run` are restricted by `(msg: string) => void`
+```
+
+Notes:
+
+- If you omit generic parameters TypeScript will fall back to `AnyFn` and inference is weaker.
+- `BranchFn` defines the parameter types that `.run(...)` accepts and what each branch receives.
+- `NoMatchFn` defines the signature of the `nomatch`/`deferedNomatch` handler.
+
+Example: calculator with typed branches
+
+```typescript
+const calc = deferedBranchDynamic<(a: number, b: number) => number, () => never>();
+
+calc
+  .add(
+    () => operation === 'add',
+    (a, b) => a + b
+  )
+  .add(
+    () => operation === 'mul',
+    (a, b) => a * b
+  )
+  .nomatch(() => {
+    throw new Error('unknown operation');
+  });
+
+calc.predicate();
+const result = calc.run(2, 3); // typed as number | undefined
+```
+
 ##### `.predicate(...args): void`
 
 - Evaluates all conditions to find the first match

package/dist/index.d.ts

@@ -1,21 +1,21 @@
-declare class DeferBranch<BranchFn extends AnyFn, NoMatchFn extends AnyFn = AnyFn> {
+declare class DeferBranch<BranchFn extends AnyFn, NoMatchFn extends AnyFn> {
     private _branch;
     private _nomatch;
     /**
      * Add a new entry
-     * - will **override** the previous matched branch
+     * - **First truthy first served**.
      * @param condition the condition to match
      * @param branch the branch to run when matched
      * @returns this
      */
-    add(condition: boolean, branch: BranchFn): DeferBranch<BranchFn>;
+    add(condition: boolean, branch: BranchFn): this;
     /**
      * Register a handler to be called when no branch matched
      * - This will be called **instantly and ignores later matched branches**
      * @param handler handle the exhausted case
      * @returns this
      */
-    nomatch(handler: AnyFn): DeferBranch<BranchFn>;
+    nomatch(handler: AnyFn): this;
     /**
      * If some branch matched, return its returnValue
      * - if no branch matched, return the nomatch handler's returnValue
@@ -27,7 +27,7 @@ declare class DeferBranch<BranchFn extends AnyFn, NoMatchFn extends AnyFn = AnyF
     run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | ReturnType<NoMatchFn> | undefined;
 }
 
-declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn = AnyFn> {
+declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>> {
     /**
      * & Compress conditions and branches into a single array since they are paired
      */
@@ -36,18 +36,18 @@ declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn
     private _nomatch;
     /**
      * Add a new entry
-     * - will **override** the previous matched branch
+     * - **First truthy first served**.
      * @param condition the condition to match
      * @param branch the branch to run when matched
      * @returns this
      */
-    add(condition: Predicate<BranchFn>, branch: BranchFn): DeferBranchDynamic<BranchFn, NoMatchFn>;
+    add(condition: ConditionFn, branch: BranchFn): this;
     /**
      * When calling `this.predicate` and no branch matched, run this handler
      * @param handler handle the exhausted case
      * @returns this
      */
-    nomatch(handler: AnyFn): DeferBranchDynamic<BranchFn, NoMatchFn>;
+    nomatch(handler: AnyFn): this;
     /**
      * Run the condition to find the first matched branch
      */
@@ -63,20 +63,36 @@ declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn
  * ## Steps to use
  * 1. const a = deferedBranch()
  * 2. add branches by a.add(condition, branch)
- * 3. add defered nomatch handler, or add and run at the same time by a.nomatch(handler)
- * 4. run this branch by a.run();
+ * 3. (optional) add defered nomatch handler, or add and run at the same time by a.nomatch(handler)
+ * 4. ...run some other logic
+ * 5. run this branch by a.run();
+ *
+ * ## Type Annotation (optional)
+ * ```ts
+ *   type BranchFn = (a: number) => void;
+ *   type NoMatchFn = () => void;
+ *   const a = deferedBranch<BranchFn, NoMatchFn>();
+ *
+ *   // then we have restrictions:
+ *   a.add(true, someFn satisfies BranchFn);
+ *   a.nomatch(otherFn satisfies NoMatchFn);
+ *
+ *   // some other logic
+ *
+ *   a.run(...args); // input args are restricted to Parameters<BranchFn>
+ * ```
  *
  * ## About
  * @package DeferedBranch
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 2.0.0 (Last Update: 2025.09.20 21:23:15.798)
+ * @version 2.1.1 (Last Update: 2025.09.21 09:04:58.051)
  * @license MIT
  * @link https://github.com/baendlorel/defered-branch
  * @link https://baendlorel.github.io/ Welcome to my site!
  * @description Sometimes we need to judge something with multiple cases, but the main job should be done later. So we have Defered Branch!
  * @copyright Copyright (c) 2025 Kasukabe Tsumugi. All rights reserved.
  */
-declare const deferedBranch: () => DeferBranch<AnyFn, AnyFn>;
+declare const deferedBranch: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn>() => DeferBranch<BranchFn, NoMatchFn>;
 /**
  * ## Steps to use
  * 1. const a = deferedBranchDynamic()
@@ -86,17 +102,38 @@ declare const deferedBranch: () => DeferBranch<AnyFn, AnyFn>;
  * 5. ...run some other logic
  * 6. run this branch by a.run();
  *
+ * ## Type Annotation (optional)
+ * ```ts
+ *   type BranchFn = (a: number) => void;
+ *   type NoMatchFn = () => void;
+ *   // optional, you can customize the condition function type
+ *   type ConditionFn = Predicate<BranchFn>;
+ *   const a = deferedBranch<BranchFn, NoMatchFn, ConditionFn>();
+ *
+ *   // then we have restrictions:
+ *   a.add(someFn satisfies ConditionFn, secondFn satisfies BranchFn);
+ *   a.nomatch(thirdFn satisfies NoMatchFn);
+ *
+ *   // some other logic
+ *
+ *   a.predicate(...args);
+ *
+ *   // some other logic
+ *
+ *   a.run(...args); // input args are restricted to Parameters<BranchFn>
+ * ```
+ *
  * ## About
  * @package DeferedBranch
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 2.0.0 (Last Update: 2025.09.20 21:23:15.798)
+ * @version 2.1.1 (Last Update: 2025.09.21 09:04:58.051)
  * @license MIT
  * @link https://github.com/baendlorel/defered-branch
  * @link https://baendlorel.github.io/ Welcome to my site!
  * @description Sometimes we need to judge something with multiple cases, but the main job should be done later. So we have Defered Branch!
  * @copyright Copyright (c) 2025 Kasukabe Tsumugi. All rights reserved.
  */
-declare const deferedBranchDynamic: () => DeferBranchDynamic<AnyFn, AnyFn>;
+declare const deferedBranchDynamic: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>>() => DeferBranchDynamic<BranchFn, NoMatchFn, ConditionFn>;
 
 export { deferedBranch, deferedBranchDynamic };
 

package/dist/index.mjs

@@ -1 +1 @@
-class n{t=null;h=null;add(n,t){if("function"!=typeof t)throw new TypeError("DeferBranch: branch must be a function");return n&&(this.t=t),this}nomatch(n){if("function"!=typeof n)throw new TypeError("DeferBranch: branch must be a function");return this.t||n(),this}run(...n){return this.t?this.t.apply(null,n):this.h?this.h.apply(null,n):void 0}}class t{i=[];t=null;h=null;add(n,t){if("function"!=typeof n)throw new TypeError("DeferBranch: condition must be a function");if("function"!=typeof t)throw new TypeError("DeferBranch: branch must be a function");return this.i.push(n,t),this}nomatch(n){if("function"!=typeof n)throw new TypeError("DeferBranch: handler must be a function");return this.h=n,this}predicate(...n){const t=this.i.length;for(let n=0;n<t;n+=2)if(this.i[n]())return void(this.t=this.i[n+1]);this.h?.apply(this,n)}run(...n){return this.t?.apply(this,n)}}const r=()=>new n,e=()=>new t;export{r as deferedBranch,e as deferedBranchDynamic};
+class n{t=null;h=null;add(n,t){if("function"!=typeof t)throw new TypeError("DeferBranch: branch must be a function");return n&&!this.t&&(this.t=t),this}nomatch(n){if("function"!=typeof n)throw new TypeError("DeferBranch: branch must be a function");return this.t||n(),this}run(...n){return this.t?this.t.apply(null,n):this.h?this.h.apply(null,n):void 0}}class t{i=[];t=null;h=null;add(n,t){if("function"!=typeof n)throw new TypeError("DeferBranch: condition must be a function");if("function"!=typeof t)throw new TypeError("DeferBranch: branch must be a function");return this.i.push(n,t),this}nomatch(n){if("function"!=typeof n)throw new TypeError("DeferBranch: handler must be a function");return this.h=n,this}predicate(...n){const t=this.i.length;for(let n=0;n<t;n+=2)if(this.i[n]())return void(this.t=this.i[n+1]);this.h?.apply(this,n)}run(...n){return this.t?.apply(this,n)}}const r=()=>new n,e=()=>new t;export{r as deferedBranch,e as deferedBranchDynamic};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "defered-branch",
-	"version": "2.0.0",
+	"version": "2.1.1",
 	"author": {
 		"name": "Kasukabe Tsumugi",
 		"email": "futami16237@gmail.com"