🛡️ wait-for-me-js

The high-performance, pre-bundled distribution of wait-for-me-ts. Declarative async error handling for pure JavaScript and production environments.

🏗️ The "Big Three" Derivatives

For 90% of use cases, these pre-configured utilities provide the cleanest syntax.

1. valueOf

Returns the data or false on failure.

• Best for: Standard data fetching where false isn't a valid piece of data.

const user = await valueOf(fetchUser(1), "User not found");
if (!user) return; 
console.log(user.name);

2. isSuccess

Returns a simple boolean.

• Best for: Fire-and-forget actions or simple validation.

if (await isSuccess(db.users.delete(id), { success: "Deleted!" })) {
    notify("User removed");
}

3. toResult

Returns an object: { success: boolean; data: any | null; error: any | null }.

• Best for: APIs that might return false or 0 as valid successful data.

🚦 Understanding STYLES

The returnStyle determines the shape of the output when using createAsyncHandler.

| Style | Success Output | Failure Output | Use Case | | --- | --- | --- | --- | | STYLES.GO_STYLE | [null, T] | [Error, null] | Classic Go-lang pattern. | | STYLES.FALSE_STYLE | T | false | Data-or-False (Shielding logic). | | STYLES.BOOLEAN | true | false | Pure status checks. | | STYLES.ONLY_ERROR | 0 | 1 | Unix-style exit codes. |

⚙️ Advanced Control: createAsyncHandler

🌊 The Waterfall: conditionalHandlerChain

The conditionalHandlerChain follows a "First Match Wins" logic. It iterates through your array of handlers and stops as soon as one ifTrue returns true.

Key Behaviors to Remember:

1. Stop on Match: Once a condition is met, no subsequent handlers in the chain are checked.
2. Shielding the Default: If a handler matches, the defaultHandler is not executed. This is perfect for silencing "expected" errors (like 404s).
3. Fallthrough: If no conditions match, the defaultHandler runs (if defined).

Example: Multi-Stage Handling

const { createAsyncHandler, STYLES } = require('wait-for-me-js');

const safeFetch = createAsyncHandler({
    returnStyle: STYLES.FALSE_STYLE,
    conditionalHandlerChain: [
        {
            ifTrue: (err) => err.code === 404,
            doIt: () => console.warn("Missing: Silently skipping logs.")
        }
    ],
    defaultHandler: (err) => reportToSentry(err)
});

🛠️ Performance & Environment

• Standard Environments: This package is pre-bundled for CJS and ESM.
• TypeScript Source: If you prefer the raw source for Node.js type-stripping, use wait-for-me-ts.

All derivatives use a shared internal Go-style handler to ensure consistent behavior across the suite.