defered-branch 2.1.2 → 2.2.0

package/README.md

@@ -1,18 +1,16 @@
 # Defered Branch 🌿
 
-For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
-
-> Sometimes we need to judge something with multiple cases, but the main job should be done later. So we have Defered Branch! ✨
+A lightweight library providing a if-else like branch, but with deferred execution. You can evaluate conditions now and execute the matched branch later.
 
-A TypeScript/JavaScript library that provides elegant deferred conditional branching with two powerful variants: **defered-branch** for immediate execution and **defered-branch-dynamic** for reusable logic patterns.
+For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
 
 ## 🚀 Features
 
-- 🎯 **Two Execution Models**: Choose between immediate execution or dynamic reusable logic
-- 🔒 **Type Safe**: Full TypeScript support with proper type inference
+- 🎯 **Four Execution Patterns**: Single/all-match × immediate/dynamic logic
+- 🔒 **Type Safe**: Full TypeScript support with type inference
 - 🪶 **Lightweight**: Zero dependencies, minimal footprint
-- 🧩 **Flexible**: Works with any function signature and return types
-- 📦 **Type Annotation**: Full type annotation supported for the exported functions. You can customize handler's type of branch/condition/nomatch.
+- 🧩 **Flexible**: Works with any function signature
+- 📦 **Generic**: Customizable branch, condition, and nomatch handler types
 
 ## 📦 Installation
 
@@ -22,51 +20,35 @@ npm install defered-branch
 pnpm add defered-branch
 ```
 
-## 🌟 When to Use Which?
+## 🌟 API Overview
 
-### `deferedBranch` - One-time Immediate Execution 🏃‍♂️
+### `deferedBranch` - Single-Match Immediate 🏃‍♂️
 
-Perfect for scenarios where you need to evaluate conditions **once** and execute immediately:
+Evaluate conditions once, execute first match immediately.
 
-- One-time conditional flows
-- Static condition evaluation
+**Use cases:** One-time conditional flows, static condition evaluation
 
-### `deferedBranchDynamic` - Reusable Logic Patterns 🔄
+### `deferedBranchDynamic` - Single-Match Reusable 🔄
 
-Ideal when you need to **reuse** the same branching logic multiple times with different inputs:
+Reusable branching logic, execute first match dynamically.
 
-- Event handlers with varying states
-- Repeated conditional logic with dynamic data
-- State-dependent operations that change over time
+**Use cases:** Event handlers with varying states, repeated conditional logic
 
-## 📚 Usage Examples
+### `deferedBranchAll` - Multi-Match Immediate 🎯
 
-### Basic deferedBranch Usage
+Evaluate conditions once, execute all matches immediately.
 
-```typescript
-import { deferedBranch } from 'defered-branch';
+**Use cases:** Notification systems, validation rules, multiple event listeners
 
-// Steps to use:
-// 1. Create instance
-const branch = deferedBranch();
-
-// 2. Add conditional branches
-branch
-  .add(user.role === 'admin', () => 'Access granted to admin panel')
-  .add(user.role === 'user', () => 'Access granted to user dashboard')
-  .add(user.role === 'guest', () => 'Limited access granted');
+### `deferedBranchAllDynamic` - Multi-Match Reusable 🌊
 
-// 3. Handle no-match case (optional)
-branch.nomatch(() => 'Access denied');
+Reusable branching logic, execute all matches dynamically.
 
-// some other logic... like validate other arguments
+**Use cases:** Plugin systems, middleware chains, observer patterns
 
-// 4. Execute and get result
-const result = branch.run();
-console.log(result); // Output based on user.role
-```
+## 📚 Usage Examples
 
-### Advanced deferedBranch with Parameters
+### Basic `deferedBranch`
 
 ```typescript
 const calculator = deferedBranch<(a: number, b: number) => number>();
@@ -82,7 +64,7 @@ calculator
 const result = calculator.run(10, 5); // Returns calculated result
 ```
 
-### deferedBranchDynamic for Reusable Logic
+### Reusable Logic with `deferedBranchDynamic`
 
 ```typescript
 import { deferedBranchDynamic } from 'defered-branch';
@@ -118,7 +100,17 @@ statusHandler.predicate(); // Re-evaluates with new status
 statusHandler.run('Status updated');
 ```
 
-### Real-world Example: Theme Switching
+### deferedBranchAll for Multi-Match Execution
+
+_Same as deferedBranch_
+
+### deferedBranchAllDynamic
+
+_Same as deferedBranchDynamic_
+
+### Real-world Example
+
+#### Theme Switching
 
 ```typescript
 const themeHandler = deferedBranchDynamic<() => void>();
@@ -156,6 +148,41 @@ function onConfigChange() {
 }
 ```
 
+#### `h` function
+
+[This is a simplied example from package **KT.js**](https://www.npmjs.com/package/kt.js)
+
+In this section, we can see that element creation separates judgement and dealing of `attr` and `content`. With out this package, we should judge 2 times and the code would be too long for one .ts file.
+
+```typescript
+const attrBranch = deferedBranchDynamic<BranchFn, NoMatchFn, PredicateFn>()
+  .add((_, attr) => typeof attr === 'string', attrIsString)
+  .add((_, attr) => typeof attr === 'object' && attr !== null, attrIsObject)
+  .nomatch(invalidAttrHandler);
+const contentBranch = __Same_As_AttrBranch__;
+
+function h<T extends HTMLTag>(
+  tag: T,
+  attr: RawAttribute = '',
+  content: RawContent = ''
+): HTMLElement<T> {
+  if (typeof tag !== 'string') {
+    throw new TypeError('[__NAME__:h] tagName must be a string.');
+  }
+  attrBranch.predicate(null, attr);
+  contentBranch.predicate(null, content);
+
+  // create element
+  const el = document.createElement(tag) as HTMLElement<T>;
+  // ... some element enhancement logic ...
+
+  attrBranch.run(element, attr);
+  contentBranch.run(element, content);
+
+  // ... other logic ...
+}
+```
+
 ## 🔧 API Reference
 
 ### deferedBranch()
@@ -199,9 +226,28 @@ Creates a new dynamic deferred branch instance for reusable logic patterns.
 - Sets a fallback handler for when no predicates match
 - Executes during `.predicate()` evaluation
 
+##### `.predicate(...args): void`
+
+- Evaluates all conditions to find the first match
+- Call this before `.run()` to update the matched branch
+- Essential for dynamic behavior
+
+##### `.run(...args): any`
+
+- Executes the currently matched branch
+- Returns the function's return value or `undefined`
+
+### deferedBranchAll()
+
+_Same as deferedBranch_
+
+### deferedBranchAllDynamic()
+
+_Same as deferedBranchDynamic_
+
 ## 🧾 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.
+The factory functions `deferedBranch`, `deferedBranchDynamic`, `deferedBranchAll`, and `deferedBranchAllDynamic` 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`:
 
@@ -256,17 +302,6 @@ calc.predicate();
 const result = calc.run(2, 3); // typed as number | undefined
 ```
 
-##### `.predicate(...args): void`
-
-- Evaluates all conditions to find the first match
-- Call this before `.run()` to update the matched branch
-- Essential for dynamic behavior
-
-##### `.run(...args): any`
-
-- Executes the currently matched branch
-- Returns the function's return value or `undefined`
-
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details.
@@ -275,6 +310,10 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 Contributions are welcome! Please feel free to submit issues and pull requests.
 
+## 🦋 Trivia
+
+[**KT.js**](https://www.npmjs.com/package/kt.js) is the reason of this package's birth. It uses `deferedBranchDynamic` internally to handle attribute and content processing in a clean, reusable way.
+
 ---
 
 Made with ❤️ by [Kasukabe Tsumugi](https://github.com/baendlorel) (´｡• ᵕ •｡`) ♡

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-declare class DeferBranch<BranchFn extends AnyFn, NoMatchFn extends AnyFn> {
+declare class DeferedBranch<BranchFn extends AnyFn, NoMatchFn extends AnyFn> {
     private _branch;
-    private _nomatch;
     /**
      * Add a new entry
      * - **First truthy first served**.
@@ -15,19 +14,16 @@ declare class DeferBranch<BranchFn extends AnyFn, NoMatchFn extends AnyFn> {
      * @param handler handle the exhausted case
      * @returns this
      */
-    nomatch(handler: AnyFn): this;
+    nomatch(handler: NoMatchFn): this;
     /**
-     * If some branch matched, return its returnValue
-     * - if no branch matched, return the nomatch handler's returnValue
-     * - if no branch matched and no nomatch handler, return undefined
-     *
-     * > Note: Although args are for the matched branch, they will also be passed to nomatch handler
+     * Execute the first matched branch in order of addition
      * @param args arguments to pass to the matched branch or nomatch handler
+     * @returns the return value of the matched branch or void
      */
-    run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | ReturnType<NoMatchFn> | undefined;
+    run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | void;
 }
 
-declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>> {
+declare class DeferedBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>> {
     /**
      * & Compress conditions and branches into a single array since they are paired
      */
@@ -53,12 +49,69 @@ declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn
      */
     predicate(...args: Parameters<ConditionFn>): void;
     /**
-     * If some branch matched, return its returnValue
+     * Execute the first matched branch in order of addition
      * @param args arguments to pass to the matched branch
+     * @returns the return value of the matched branch or void
+     */
+    run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | undefined;
+}
+
+declare class DeferedBranchAllDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>> {
+    /**
+     * & Compress conditions and branches into a single array since they are paired
+     */
+    private _condranches;
+    private _branches;
+    private _nomatch;
+    /**
+     * Add a new entry
+     * - **All truthy branches will be executed**.
+     * @param condition the condition to match
+     * @param branch the branch to run when matched
+     * @returns this
+     */
+    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): this;
+    /**
+     * Run the conditions to find all matched branches
+     */
+    predicate(...args: Parameters<ConditionFn>): void;
+    /**
+     * Execute all matched branches in order of addition
+     * @param args arguments to pass to the matched branches
      */
     run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | undefined;
 }
 
+declare class DeferedBranchAll<BranchFn extends AnyFn, NoMatchFn extends AnyFn> {
+    private _branches;
+    /**
+     * Add a new entry
+     * - **All truthy branches will be executed**.
+     * @param condition the condition to match
+     * @param branch the branch to run when matched
+     * @returns this
+     */
+    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: NoMatchFn): this;
+    /**
+     * Execute all matched branches in order of addition
+     * @param args arguments to pass to the matched branch or nomatch handler
+     */
+    run(...args: Parameters<BranchFn>): void;
+}
+
 /**
  * ## Steps to use
  * 1. const a = deferedBranch()
@@ -85,14 +138,14 @@ declare class DeferBranchDynamic<BranchFn extends AnyFn, NoMatchFn extends AnyFn
  * ## About
  * @package DeferedBranch
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 2.1.2 (Last Update: 2025.09.21 09:09:48.701)
+ * @version 2.2.0 (Last Update: 2025.09.21 16:49:49.136)
  * @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: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn>() => DeferBranch<BranchFn, NoMatchFn>;
+declare const deferedBranch: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn>() => DeferedBranch<BranchFn, NoMatchFn>;
 /**
  * ## Steps to use
  * 1. const a = deferedBranchDynamic()
@@ -126,16 +179,91 @@ declare const deferedBranch: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends
  * ## About
  * @package DeferedBranch
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 2.1.2 (Last Update: 2025.09.21 09:09:48.701)
+ * @version 2.2.0 (Last Update: 2025.09.21 16:49:49.136)
+ * @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: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>>() => DeferedBranchDynamic<BranchFn, NoMatchFn, ConditionFn>;
+/**
+ * ## Steps to use
+ * 1. const a = deferedBranchAll()
+ * 2. add branches by a.add(condition, branch)
+ * 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 all matched branches by a.run();
+ *
+ * ## Type Annotation (optional)
+ * ```ts
+ *   type BranchFn = (a: number) => void;
+ *   type NoMatchFn = () => void;
+ *   const a = deferedBranchAll<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.2.0 (Last Update: 2025.09.21 16:49:49.136)
+ * @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 deferedBranchAll: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn>() => DeferedBranchAll<BranchFn, NoMatchFn>;
+/**
+ * ## Steps to use
+ * 1. const a = deferedBranchAllDynamic()
+ * 2. add branches by a.add(condition, branch)
+ * 3. add nomatch handler by a.nomatch(handler)
+ * 4. call a.predicate(...) to find all matched branches
+ * 5. ...run some other logic
+ * 6. run all matched branches 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 = deferedBranchAllDynamic<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.2.0 (Last Update: 2025.09.21 16:49:49.136)
  * @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: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>>() => DeferBranchDynamic<BranchFn, NoMatchFn, ConditionFn>;
+declare const deferedBranchAllDynamic: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>>() => DeferedBranchAllDynamic<BranchFn, NoMatchFn, ConditionFn>;
 
-export { deferedBranch, deferedBranchDynamic };
+export { deferedBranch, deferedBranchAll, deferedBranchAllDynamic, deferedBranchDynamic };
 
 // # from: src/global.d.ts
 type AnyFn = (...args: any[]) => any;

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

package/package.json

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