How supermacro/neverthrow works
The neverthrow project is a TypeScript library designed to provide an expressive “Result” type to encode failures without throwing exceptions. It exposes both synchronous (Result) and asynchronous (ResultAsync) APIs, along with a set of utility functions (such as fromThrowable, safeTry, etc.) that allow library consumers to work with error handling in a more controlled, composable way.
Main Library Interface
• At the top level, show a “NeverThrow Library” component that represents the public API.
• That the library is intended for error handling alternatives by wrapping values in Ok/Err constructs.
Synchronous API Components
• A “Result” component (with sub-components “Ok” and “Err”).
• Utility methods like Result.fromThrowable and Result.combine as functions attached to the Result component.
• That the “Result” API encapsulates error and value handling for synchronous use cases.
Asynchronous API Components
• A “ResultAsync” component that wraps asynchronous operations in a thenable object.
• Within that component, list its methods (map, mapErr, unwrapOr, andThen, orElse, match, andTee/orTee variants, asyncAndThrough, and its combine functions).
• Make it clear that ResultAsync is built to mirror the synchronous API but works with Promises, bridging native async behavior.
Internal and Utility Modules
• An “_internals” component (or module) that contains helper modules (error.ts, utils.ts). This is the backbone that supports the implementation of the Result logic.
• Optionally link the Utility functions to both the synchronous and asynchronous components, indicating that these are common helper functions used internally or available for consumers.
Testing and Build Infrastructure
• A note on the supporting configuration files (like package.json, tsconfig.json, Rollup, ESLint, etc.) that assist with linting, testing, and bundling, even though they are not “runtime” components in the library.