defered-branch 1.2.2 → 2.1.0

package/README.md

@@ -1,111 +1,280 @@
-# defered-branch 🚦
-
-A tiny TypeScript/JavaScript utility for deferred branching logic.  
-It provides a small, chainable API to register conditional branches and two kinds of "no-match" handlers: one that runs immediately when no branch was matched, and another that runs later when you call `run()`.
+# Defered Branch 🌿
 
 For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
 
-## Highlights ✨
+> Sometimes we need to judge something with multiple cases, but the main job should be done later. So we have Defered Branch! ✨
+
+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.
+
+## 🚀 Features
 
-- Chainable API for registering branches
-- Only the last matched branch is executed
-- Immediate `nomatch` handler (runs instantly when no branch matched)
-- Deferred `deferedNomatch` handler (runs when `run()` is invoked)
-- TypeScript declarations included
+- 🎯 **Two Execution Models**: Choose between immediate execution or dynamic reusable logic
+- 🔒 **Type Safe**: Full TypeScript support with proper 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.
 
-## Installation 📦
+## 📦 Installation
 
 ```bash
-pnpm add defered-branch
-# or
 npm install defered-branch
+# or
+pnpm add defered-branch
 ```
 
-## Export / Import 🚀
+## 🌟 When to Use Which?
+
+### `deferedBranch` - One-time Immediate Execution 🏃‍♂️
+
+Perfect for scenarios where you need to evaluate conditions **once** and execute immediately:
+
+- One-time conditional flows
+- Static condition evaluation
 
-The package exports a factory named `deferedBranch` (note the spelling):
+### `deferedBranchDynamic` - Reusable Logic Patterns 🔄
 
-```ts
+Ideal when you need to **reuse** the same branching logic multiple times with different inputs:
+
+- Event handlers with varying states
+- Repeated conditional logic with dynamic data
+- State-dependent operations that change over time
+
+## 📚 Usage Examples
+
+### Basic deferedBranch Usage
+
+```typescript
 import { deferedBranch } from 'defered-branch';
+
+// 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');
+
+// 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
 ```
 
-## Basic Usage
+### Advanced deferedBranch with Parameters
 
-```ts
-import { deferedBranch } from 'defered-branch';
+```typescript
+const calculator = deferedBranch<(a: number, b: number) => number>();
 
-// register branches - only the last matched branch will run
-const b = deferedBranch()
-  .add(false, () => 'A')
-  .add(true, () => 'B');
+calculator
+  .add(operation === 'add', (a, b) => a + b)
+  .add(operation === 'multiply', (a, b) => a * b)
+  .add(operation === 'divide', (a, b) => a / b)
+  .nomatch(() => {
+    throw new Error('Unknown operation');
+  });
 
-console.log(b.run()); // 'B'
+const result = calculator.run(10, 5); // Returns calculated result
 ```
 
-## nomatch vs deferedNomatch
+### deferedBranchDynamic for Reusable Logic
+
+```typescript
+import { deferedBranchDynamic } from 'defered-branch';
+
+// Steps to use:
+// 1. Create instance
+const statusHandler = deferedBranchDynamic<(message: string) => void>();
+
+// 2. Add predicate-based branches
+statusHandler
+  .add(
+    () => server.status === 'online',
+    (msg) => logger.info(`✅ ${msg}`)
+  )
+  .add(
+    () => server.status === 'maintenance',
+    (msg) => logger.warn(`⚠️ ${msg}`)
+  )
+  .add(
+    () => server.status === 'offline',
+    (msg) => logger.error(`❌ ${msg}`)
+  );
+
+// 3. Add fallback handler
+statusHandler.nomatch((msg) => logger.debug(`🤔 Unknown status: ${msg}`));
+
+// 4. Use repeatedly with different conditions
+statusHandler.predicate(); // Evaluates current server.status
+statusHandler.run('Server health check completed');
+
+// Later, when server.status changes...
+statusHandler.predicate(); // Re-evaluates with new status
+statusHandler.run('Status updated');
+```
 
-There are two ways to handle the case when no branch matches:
+### Real-world Example: Theme Switching
+
+```typescript
+const themeHandler = deferedBranchDynamic<() => void>();
+
+themeHandler
+  .add(
+    () => preferences.theme === 'dark',
+    () => applyDarkTheme()
+  )
+  .add(
+    () => preferences.theme === 'light',
+    () => applyLightTheme()
+  )
+  .add(
+    () => preferences.theme === 'auto',
+    () => applySystemTheme()
+  )
+  .nomatch(() => {
+    // usually handles parameter validations
+    throw new TypeError('Invalid theme preference');
+  });
+
+// Reuse whenever preferences change
+function onConfigChange() {
+  themeHandler.predicate();
+  xxxHandler.predicate();
+  yyyHandler.predicate();
+
+  // some other logic...create some objects..
+  // some other logic...run some funtions...
+
+  themeHandler.run();
+  xxxHandler.run();
+  yyyHandler.run();
+}
+```
 
-- `nomatch(handler: Fn)` — runs the handler immediately if no branch has been matched yet. Note: if `nomatch` runs the handler immediately, later calls to `add(true, ...)` will not retroactively affect that call.
-- `deferedNomatch(handler: Fn)` — registers a handler that will be executed when `run()` is called and no branch matched.
+## 🔧 API Reference
 
-Examples:
+### deferedBranch()
 
-```ts
-import { deferedBranch } from 'defered-branch';
+Creates a new deferred branch instance for immediate execution scenarios.
 
-// nomatch runs immediately when invoked if no branch matched
-deferedBranch()
-  .add(false, () => 'x')
-  .nomatch(() => console.log('immediate nomatch')) // prints now
-  .add(true, () => console.log('will not be printed')); // ignored for the already-called nomatch
+#### Methods
 
-// deferedNomatch runs when run() is called
-const b2 = deferedBranch()
-  .add(false, () => 'x')
-  .deferedNomatch(() => 'deferred fallback');
+##### `.add(condition: boolean, branch: Function): DeferBranch`
 
-console.log(b2.run()); // 'deferred fallback'
-```
+- Adds a conditional branch that executes if condition is `true`
+- First-match wins: the first truthy branch will be selected; later entries are ignored
+- Returns the instance for chaining
+
+##### `.nomatch(handler: Function): DeferBranch`
 
-## API Reference 📚
+- Sets an immediate fallback handler
+- **Executes instantly** if no previous branch matched
+- **Ignores** later matched branches
 
-All functions accept a `Fn` type: `type Fn = (...args: unknown[]) => unknown`.
+##### `.run(...args): any`
 
-### `deferedBranch(): DeferBranch`
+- Executes the matched branch or fallback handler
+- Passes arguments to the executed function
+- Returns the function's return value or `undefined`
 
-Create a new `DeferBranch` instance.
+### deferedBranchDynamic()
 
-### `add(condition: boolean, branch: Fn): DeferBranch`
+Creates a new dynamic deferred branch instance for reusable logic patterns.
 
-Register a branch. If `condition` is true the provided `branch` becomes the current matched branch. Later `add(true, ...)` calls will override the matched branch.
+#### Methods
 
-Throws `TypeError` if `branch` is not a function.
+##### `.add(condition: Predicate, branch: Function): DeferBranchDynamic`
 
-### `nomatch(handler: Fn): DeferBranch`
+- Adds a predicate-based conditional branch
+- `condition` is a function that returns boolean
+- First-match wins: the first truthy branch will be selected; later entries are ignored
 
-If no branch has been matched when this is called, the `handler` is invoked immediately. This is useful for side-effects that should run right away when a branch is absent. Returns the instance for chaining. Throws `TypeError` when `handler` is not a function.
+##### `.nomatch(handler: Function): DeferBranchDynamic`
 
-### `deferedNomatch(handler: Fn): DeferBranch`
+- 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
+```
 
-Register a handler to be executed by `run()` if no branch matched. Unlike `nomatch`, this does not run immediately — it defers execution until `run()`.
+##### `.predicate(...args): void`
 
-### `run(...args: unknown): unknown`
+- Evaluates all conditions to find the first match
+- Call this before `.run()` to update the matched branch
+- Essential for dynamic behavior
 
-Execute the matched branch and return its value. If no branch matched but a `deferedNomatch` handler was set, returns the handler's return value. Returns `undefined` if neither exists.
+##### `.run(...args): any`
 
-`args` will be passed to the matched branch or the `deferedNomatch` handler when they are invoked.
+- Executes the currently matched branch
+- Returns the function's return value or `undefined`
 
-## Types & Distribution
+## 📄 License
 
-- Types are included (`"types": "./dist/index.d.ts"` in package.json).
-- The package entrypoint is an ESM module at `./dist/index.mjs`.
+MIT License - see [LICENSE](LICENSE) file for details.
 
-## Error Handling ⚠️
+## 🤝 Contributing
 
-- `TypeError` is thrown if a non-function is passed as a branch or handler.
+Contributions are welcome! Please feel free to submit issues and pull requests.
 
-## Author & License
+---
 
-- Author: Kasukabe Tsumugi (<futami16237@gmail.com>)
-- License: MIT
+Made with ❤️ by [Kasukabe Tsumugi](https://github.com/baendlorel) (´｡• ᵕ •｡`) ♡

package/dist/index.d.ts

@@ -1,49 +1,134 @@
-declare class DeferBranch {
+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: Fn): DeferBranch;
+    add(condition: boolean, branch: BranchFn): this;
     /**
-     * When no branch matched, run this handler
-     * - This will be called **instantly** and **ignores later matched branches**
+     * 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: Fn): DeferBranch;
+    nomatch(handler: AnyFn): this;
     /**
-     * When no branch matched, run this handler
-     * - Will be called when `run()` is called
+     * 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
+     * @param args arguments to pass to the matched branch or nomatch handler
+     */
+    run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | ReturnType<NoMatchFn> | undefined;
+}
+
+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
+     */
+    private _condranches;
+    private _branch;
+    private _nomatch;
+    /**
+     * Add a new entry
+     * - **First truthy first served**.
+     * @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
      */
-    deferedNomatch(handler: Fn): DeferBranch;
+    nomatch(handler: AnyFn): this;
+    /**
+     * Run the condition to find the first matched branch
+     */
+    predicate(...args: Parameters<BranchFn>): void;
     /**
      * If some branch matched, return its returnValue
-     * - if no branch matched, return the nomatch handler returnValue
-     * - if no branch matched and no nomatch handler, return undefined
-     * @param args arguments to pass to the matched branch or nomatch handler
+     * @param args arguments to pass to the matched branch
      */
-    run(...args: unknown[]): unknown;
+    run(...args: Parameters<BranchFn>): ReturnType<BranchFn> | undefined;
 }
+
+/**
+ * ## Steps to use
+ * 1. const a = deferedBranch()
+ * 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 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);
+ *
+ *   a.run(); // input args are restricted to Parameters<BranchFn>
+ * ```
+ *
+ * ## About
+ * @package DeferedBranch
+ * @author Kasukabe Tsumugi <futami16237@gmail.com>
+ * @version 2.1.0 (Last Update: 2025.09.21 08:03:55.124)
+ * @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>;
 /**
+ * ## Steps to use
+ * 1. const a = deferedBranchDynamic()
+ * 2. add branches by a.add(condition, branch)
+ * 3. add nomatch handler by a.nomatch(handler)
+ * 4. call a.predicate(...) to find the matched branch
+ * 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 statisfies ConditionFn, secondFn satisfies BranchFn);
+ *   a.nomatch(thirdFn satisfies NoMatchFn);
+ *
+ *   a.run(); // input args are restricted to Parameters<BranchFn>
+ * ```
+ *
  * ## About
  * @package DeferedBranch
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 1.2.2 (Last Update: 2025.09.19 08:09:05.967)
+ * @version 2.1.0 (Last Update: 2025.09.21 08:03:55.124)
  * @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;
+declare const deferedBranchDynamic: <BranchFn extends AnyFn = AnyFn, NoMatchFn extends AnyFn = AnyFn, ConditionFn extends AnyFn = Predicate<BranchFn>>() => DeferBranchDynamic<BranchFn, NoMatchFn, ConditionFn>;
 
-export { deferedBranch };
+export { deferedBranch, deferedBranchDynamic };
 
 // # from: src/global.d.ts
-type Fn = (...args: any[]) => any;
+type AnyFn = (...args: any[]) => any;
+type Predicate<Fn extends AnyFn> = (...args: Parameters<Fn>) => boolean;

package/dist/index.mjs

@@ -1 +1 @@
-class t{t=null;o=null;add(t,n){if("function"!=typeof n)throw new TypeError("Branch must be a function");return t&&(this.t=n),this}nomatch(t){if("function"!=typeof t)throw new TypeError("Branch must be a function");return this.t||t(),this}deferedNomatch(t){if("function"!=typeof t)throw new TypeError("Branch must be a function");return this.o=t,this}run(...t){return this.t?this.t(...t):this.o?this.o(...t):void 0}}const n=()=>new t;export{n as deferedBranch};
+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": "1.2.2",
+	"version": "2.1.0",
 	"author": {
 		"name": "Kasukabe Tsumugi",
 		"email": "futami16237@gmail.com"