als-smart-promise v4.3.0
als-smart-promise
Description
SmartPromise is a versatile utility for managing chains of asynchronous or synchronous functions. Its features include:
- Sequential execution of functions in a defined order.
- Global (static) chain shared across all instances.
- Instance-level chains for specific tasks.
- Flexible control with
once
andlast
flags. - Timeout support to limit execution time.
- Linking chains to create complex hierarchies of execution.
- Flow control with
next
,resolve
, andreject
. - Sync/Async support Automatically detects whether the chain contains asynchronous functions and switches between synchronous and asynchronous execution.
SmartPromise is ideal for orchestrating tasks with predictable flow, combining global and instance-specific logic, and handling edge cases like timeouts or early resolution.
Installation
Install via npm:
npm install smart-promise
Basic Usage
Example: Sequential Execution
The execute method dynamically determines whether the chain contains asynchronous functions and executes them accordingly. If all functions are synchronous, it will return the result immediately; otherwise, it returns a Promise.
const SmartPromise = require('als-smart-promise');
const name = 'some', timeout = null;
const chain = new SmartPromise(timeout,name);
chain.use(({ next }) => {
console.log('Step 1');
next();
});
chain.use(({ next }) => {
console.log('Step 2');
next();
});
chain.execute() // Automatically handles synchronous execution
Output:
Step 1
Step 2
Chain completed
Example: Resolving the Chain
const chain = new SmartPromise();
chain.use(({ next }) => {
console.log('Before resolving');
next('Final Result');
});
chain.use(async ({ resolve, result }) => {
console.log('This won’t run because the chain was resolved:', result);
resolve();
});
// Even if synchronous, the chain will resolve correctly with the final result.
chain.execute().then((result) => {
console.log('Resolved with:', result);
});
Output:
Before resolving
Resolved with: Final Result
Advanced Usage
Global (Static) Chain
Static functions are added with SmartPromise.use()
and apply to all instances:
SmartPromise.use(({ next }) => {
console.log('Global function');
next();
});
const chain = new SmartPromise();
chain.use(({ next }) => {
console.log('Instance function');
next();
});
chain.execute().then(() => {
console.log('Done');
});
Output:
Global function
Instance function
Done
Using last
Functions marked as last
run after all others:
const chain = new SmartPromise();
chain.use(({ next }) => {
console.log('Step 1');
next();
});
chain.use(({ next }) => {
console.log('Step 3 (last)');
next();
}, { last: true });
chain.use(({ next }) => {
console.log('Step 2');
next();
});
chain.execute();
Output:
Step 1
Step 2
Step 3 (last)
Timeout Handling
const chain = new SmartPromise(100);
chain.use(async ({ next }) => {
await new Promise((r) => setTimeout(r, 200)); // Simulate delay
next();
});
chain.execute()
.then(() => {
console.log('Completed in time');
})
.catch((err) => {
console.error(err.message); // "Promise timeout 100"
});
Linking Chains
Chains can link other chains, combining their logic:
const chain1 = new SmartPromise();
const chain2 = new SmartPromise();
chain1.use(({ next }) => {
console.log('Chain 1 - Step 1');
next();
});
chain2.use(({ next }) => {
console.log('Chain 2 - Step 1');
next();
});
chain1.link(chain2);
chain1.execute().then(() => {
console.log('Both chains executed');
});
Output:
Chain 1 - Step 1
Chain 2 - Step 1
Both chains executed
Resolving in Linked Chains
const chain1 = new SmartPromise();
const chain2 = new SmartPromise();
chain1.use(({ next }) => {
console.log('Chain 1 - Before resolve');
next('Final Result');
});
chain2.use(({ resolve }) => {
console.log('Chain 2 - Won’t run');
resolve();
});
chain1.link(chain2);
chain1.execute().then((result) => {
console.log('Resolved with:', result);
});
Output:
Chain 1 - Before resolve
Resolved with: Final Result
API Reference
class SmartPromise
Creates an instance of SmartPromise.
- Parameters:
timeout
(optional): Time in milliseconds to reject the chain if not completed.name
(optional): addede as this.name and will appear as part of context
SmartPromise.chain
(static)
Global shared chain of functions. Functions here are executed before instance-level functions.
SmartPromise.use(fn, options = {})
(static)
Adds a function to the global chain.
- Parameters:
fn
: A function with signature({ next, resolve, reject, result }, ...args)
.options
:once
: Removes the function after the first execution.last
: Executes the function after all others.
use(fn, options = {})
Adds a function to the instance’s chain.
link(chain)
Links another SmartPromise
chain.
- Parameters:
chain
: AnotherSmartPromise
instance to link.
execute(...args)
Executes all functions in the chain. If the chain contains only synchronous functions, it returns the result directly. Otherwise, it returns a Promise.
Returns: A result or
Promise
that resolves with the final result.Example:
const chain = new SmartPromise();
chain.use(async ({ resolve }) => resolve('Done!'));
chain.execute().then(console.log); // "Done!"
delete(fn)
Removes a function from the instance and global chains.