@ayonli/jsext
Version:
A JavaScript extension package for building strong and modern applications.
149 lines (147 loc) • 4.45 kB
TypeScript
/**
* Calls a function safely and return errors when captured.
*
* NOTE: Since v1.5.0, this module will convert the error to an instance of
* `Error` if it's not one already.
*
* NOTE: This module, inspired by Golang, is not well-designed, take a look at
* the [result](https://jsr.io/@ayonli/jsext/doc/result/~) module for a better
* alternative.
* @module
*/
export type TryResult<E extends Error, T> = [E, undefined] | [null, T];
/**
* Invokes an async generator function and renders its yield value and result in
* an `[err, val]` tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
*
* const iter = _try(async function* () {
* // do something that may fail
* });
*
* for await (const [err, val] of iter) {
* if (err) {
* console.error("something went wrong:", err);
* } else {
* console.log("current value:", val);
* }
* }
* ```
*/
export default function _try<E extends Error = Error, T = any, A extends any[] = any[], TReturn = any, TNext = unknown>(fn: (...args: A) => AsyncGenerator<T, TReturn, TNext>, ...args: A): AsyncGenerator<TryResult<E, T>, [E, TReturn], TNext>;
/**
* Invokes a generator function and renders its yield value and result in an
* `[err, val]` tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
*
* const iter = _try(function* () {
* // do something that may fail
* });
*
* for (const [err, val] of iter) {
* if (err) {
* console.error("something went wrong:", err);
* } else {
* console.log("current value:", val);
* }
* }
* ```
*/
export default function _try<E extends Error = Error, T = any, A extends any[] = any[], TReturn = any, TNext = unknown>(fn: (...args: A) => Generator<T, TReturn, TNext>, ...args: A): Generator<TryResult<E, T>, [E, TReturn], TNext>;
/**
* Invokes an async function and renders its result in an `[err, res]` tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
* import axios from "axios";
*
* let [err, res] = await _try(async () => {
* return await axios.get("https://example.org");
* });
*
* if (err) {
* res = (err as any)["response"];
* }
* ```
*/
export default function _try<E extends Error = Error, R = any, A extends any[] = any[]>(fn: (...args: A) => Promise<R>, ...args: A): Promise<TryResult<E, R>>;
/**
* Invokes a function and renders its result in an `[err, res]` tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
*
* const [err, res] = _try(() => {
* // do something that may fail
* });
* ```
*/
export default function _try<E extends Error = Error, R = any, A extends any[] = any[]>(fn: (...args: A) => R, ...args: A): TryResult<E, R>;
/**
* Resolves an async generator and renders its yield value and result in an
* `[err, val]` tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
*
* async function* gen() {
* // do something that may fail
* }
*
* for await (const [err, val] of _try(gen())) {
* if (err) {
* console.error("something went wrong:", err);
* } else {
* console.log("current value:", val);
* }
* }
* ```
*/
export default function _try<E extends Error = Error, T = any, TReturn = any, TNext = unknown>(gen: AsyncGenerator<T, TReturn, TNext>): AsyncGenerator<TryResult<E, T>, [E, TReturn], TNext>;
/**
* Resolves a generator and renders its yield value and result in an `[err, val]`
* tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
* import { range } from "@ayonli/jsext/number";
*
* const iter = range(1, 10);
*
* for (const [err, val] of _try(iter)) {
* if (err) {
* console.error("something went wrong:", err);
* } else {
* console.log("current value:", val);
* }
* }
* ```
*/
export default function _try<E extends Error = Error, T = any, TReturn = any, TNext = unknown>(gen: Generator<T, TReturn, TNext>): Generator<TryResult<E, T>, [E, TReturn], TNext>;
/**
* Resolves a promise and renders its result in an `[err, res]` tuple.
*
* @example
* ```ts
* import _try from "@ayonli/jsext/try";
* import axios from "axios";
*
* let [err, res] = await _try(axios.get("https://example.org"));
*
* if (err) {
* res = (err as any)["response"];
* }
* ```
*/
export default function _try<E extends Error = Error, R = any>(job: PromiseLike<R>): Promise<TryResult<E, R>>;
export = _try;