defered-branch 1.0.1 → 1.2.0

package/README.md

@@ -1,17 +1,17 @@
 # defered-branch 🚦
 
-A tiny TypeScript/JavaScript library for deferred branching logic.  
-Easily manage conditional execution and fallback handlers in a clean, chainable way!
+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()`.
 
 For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
 
-## Features ✨
+## Highlights ✨
 
-- Chainable API for adding branches
+- Chainable API for registering branches
 - Only the last matched branch is executed
-- Custom handler for unmatched cases
-- TypeScript support
-- Lightweight and dependency-free
+- Immediate `nomatch` handler (runs instantly when no branch matched)
+- Deferred `deferedNomatch` handler (runs when `run()` is invoked)
+- TypeScript declarations included
 
 ## Installation 📦
 
@@ -21,55 +21,89 @@ pnpm add defered-branch
 npm install defered-branch
 ```
 
-## Usage 🚀
+## Export / Import 🚀
+
+The package exports a factory named `deferedBranch` (note the spelling):
+
+```ts
+import { deferedBranch } from 'defered-branch';
+```
+
+## Basic Usage
+
+```ts
+import { deferedBranch } from 'defered-branch';
+
+// register branches - only the last matched branch will run
+const b = deferedBranch()
+  .add(false, () => 'A')
+  .add(true, () => 'B');
+
+console.log(b.run()); // 'B'
+```
+
+## nomatch vs deferedNomatch
+
+There are two ways to handle the case when no branch matches:
+
+- `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.
+
+Examples:
 
 ```ts
-import { deferBranch } from 'defered-branch';
+import { deferedBranch } from 'defered-branch';
+
+// 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
 
-const result = deferBranch()
-  .add(false, () => 'not this')
-  .add(true, () => 'this branch runs!')
-  .nomatch(() => 'no branch matched')
-  .run();
+// deferedNomatch runs when run() is called
+const b2 = deferedBranch()
+  .add(false, () => 'x')
+  .deferedNomatch(() => 'deferred fallback');
 
-console.log(result); // 'this branch runs!'
+console.log(b2.run()); // 'deferred fallback'
 ```
 
 ## API Reference 📚
 
-### `deferBranch(): DeferBranch`
+All functions accept a `Fn` type: `type Fn = (...args: unknown[]) => unknown`.
 
-Creates a new branch handler.
+### `deferedBranch(): DeferBranch`
 
-### `add(condition: boolean, branch: () => any): this`
+Create a new `DeferBranch` instance.
 
-Adds a branch. If `condition` is true, this branch will be set as the one to run.  
-Multiple calls will override the previous matched branch.
+### `add(condition: boolean, branch: Fn): DeferBranch`
 
-### `nomatch(handler: () => any): this`
+Register a branch. If `condition` is true the provided `branch` becomes the current matched branch. Later `add(true, ...)` calls will override the matched branch.
 
-Sets a handler to run if no branch matches.
+Throws `TypeError` if `branch` is not a function.
 
-### `run(): any`
+### `nomatch(handler: Fn): DeferBranch`
 
-Executes the matched branch, or the nomatch handler if none matched.  
-Returns `undefined` if neither is set.
+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.
 
-## Example 🧩
+### `deferedNomatch(handler: Fn): DeferBranch`
 
-```ts
-const branch = deferBranch()
-  .add(false, () => 'A')
-  .add(false, () => 'B')
-  .nomatch(() => 'Fallback!');
+Register a handler to be executed by `run()` if no branch matched. Unlike `nomatch`, this does not run immediately — it defers execution until `run()`.
 
-console.log(branch.run()); // 'Fallback!'
-```
+### `run(): unknown`
+
+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.
+
+## Types & Distribution
+
+- Types are included (`"types": "./dist/index.d.ts"` in package.json).
+- The package entrypoint is an ESM module at `./dist/index.mjs`.
 
 ## Error Handling ⚠️
 
-- Throws `TypeError` if branch or nomatch handler is not a function.
+- `TypeError` is thrown if a non-function is passed as a branch or handler.
 
-## License 📄
+## Author & License
 
-MIT
+- Author: Kasukabe Tsumugi (<futami16237@gmail.com>)
+- License: MIT

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 declare class DeferBranch {
     private _branch;
-    private _nomatchHandler;
+    private _nomatch;
     /**
      * Add a new entry
      * - will **override** the previous matched branch
@@ -11,22 +11,31 @@ declare class DeferBranch {
     add(condition: boolean, branch: Fn): DeferBranch;
     /**
      * When no branch matched, run this handler
+     * - This will be called **instantly** and **ignores later matched branches**
      * @param handler handle the exhausted case
      * @returns this
      */
     nomatch(handler: Fn): DeferBranch;
+    /**
+     * When no branch matched, run this handler
+     * - Will be called when `run()` is called
+     * @param handler handle the exhausted case
+     * @returns this
+     */
+    deferedNomatch(handler: Fn): DeferBranch;
     /**
      * 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
      */
-    run(): unknown;
+    run(...args: unknown[]): unknown;
 }
 /**
  * ## About
  * @package DeferedBranch
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 1.0.1 (Last Update: 2025.09.19 07:33:04.605)
+ * @version 1.2.0 (Last Update: 2025.09.19 08:00:16.406)
  * @license MIT
  * @link https://github.com/baendlorel/defered-branch
  * @description Sometimes we need to judge something with multiple cases, but the main job should be done later. So we have Defered Branch!

package/dist/index.mjs

@@ -1 +1 @@
-class t{t=null;h=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.h=t,this}run(){return this.t?this.t():this.h?this.h():void 0}}const n=()=>new t;export{n as deferedBranch};
+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};

package/package.json

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