@zokugun/xtry 0.4.0 → 0.5.0

package/README.md

@@ -9,8 +9,8 @@
 
 Simple `try/catch` wrappers that always return a `Result` discriminated union, plus ready-made helpers (`ok`, `err`) for predictable control flow.
 
-Why xtry?
----------
+Why `@zokugun/xtry`?
+--------------------
 
 - Turn any sync or async function into an explicit `Result` object with zero dependencies.
 - Strong TypeScript types guide your control flow (`fails` and tagged errors).
@@ -27,9 +27,9 @@ Quick Start
 -----------
 
 ```typescript
-import { xatry } from '@zokugun/xtry'
+import { xtry } from '@zokugun/xtry'
 
-const userResult = await xatry(fetchUserFromApi());
+const userResult = await xtry(fetchUserFromApi());
 
 if(userResult.fails) {
     console.error(userResult.error);
@@ -43,18 +43,18 @@ Advanced Example
 ----------------
 
 ```typescript
-import { err, type Result, xatry, xtry } from '@zokugun/xtry'
+import { err, type Result, xtry } from '@zokugun/xtry'
 
 export type FoobarError = { type: 'FOOBAR'; message: string };
 
 async function foobar(): Result<number, FoobarError> {
-    const result = await xatry(fetchUserFromApi());
+    const result = await xtry(fetchUserFromApi());
 
     if(fails) {
         return err({ type: 'FOOBAR', message: 'The promise has failed...' });
     }
 
-    return try(() => calculateAge(result.value));
+    return xtry(() => calculateAge(result.value));
 }
 
 async function main() {
@@ -113,6 +113,11 @@ function add(_x: string, _y: number): Result<number, MyError> {
 }
 ```
 
+Tips
+----
+
+- Narrow on `fails` first, then use other flags (`success`, custom `miscue` or `value`) for the happy-path branching.
+
 API reference
 -------------
 
@@ -123,20 +128,32 @@ type Success<T> = { fails: false; value: T; error: undefined };
 type Failure<E> = { fails: true; value: undefined; error: E };
 type Result<T, E> = Success<T> | Failure<E>;
 
-function ok<T>(value: T): Success<T>;
+function ok<T>(value?: T): Success<T>;
 function err<E>(error: E): Failure<E>;
 ```
 
+#### Pre-built `ok` constants
+
+To minimize allocations when returning the same `Success` shape, you can reuse the exported frozen helpers:
+
+| Constant   | Wrapped value | Type             | Typical usage                                       |
+| ---------- | ------------- | ---------------- | --------------------------------------------------- |
+| `OK`       | `ok()`        | `Success<void>`  | Generic void success (e.g., cleanup, notifications) |
+| `OK_NULL`  | `ok(null)`    | `Success<null>`  | APIs that explicitly signal "nothing" with `null`   |
+| `OK_TRUE`  | `ok(true)`    | `Success<true>`  | Flag-style functions (`enable()` / `disable()`)     |
+| `OK_FALSE` | `ok(false)`   | `Success<false>` | Guard checks that succeed with `false`              |
+
 ### Try helpers
 
-```typescript
-function xtry<T, E>(func: () => Exclude<T, Promise<unknown>>, handler?: (error: unknown) => void | E): Result<T, E>;
-function xatry<T, E>(func: (() => Exclude<T, Promise<unknown>>) | Promise<Exclude<T, Promise<unknown>>>, handler?: (error: unknown) => void | E): Promise<Result<T, E>>;
+```
+function xtry<T, E>(func: (() => MaybePromise<T>) | Promise<T>, handler?: (error: unknown) => void | E): MaybePromise<Result<T, E>>;
+function xtrySync<T, E>(func: () => Exclude<T, Promise<unknown>>, handler?: (error: unknown) => void | E): Result<T, E>;
+function xtryAsync<T, E>(func: (() => Promise<T>) | Promise<T>, handler?: (error: unknown) => void | E): Promise<Result<T, E>>;
 
 function stringifyError(error: unknown): string;
 ```
 
-Both helpers:
+`xtry` inspects the supplied value: if it is or returns a promise you get a `Promise<Result<…>>`, otherwise you get a plain `Result`. Use `xtrySync`/`xtryAsync` when you need to force a specific flavor (tree shaking, stricter contracts, etc.). All helpers:
 
 - execute the supplied function and capture thrown values;
 - call the optional `handler` before turning that value into `err(error)`;
@@ -151,17 +168,61 @@ type YResult<T, E, M> = Failure<E> | YSuccess<T> | YFailure<M>;
 
 function yok<T>(value: T): YSuccess<T>;
 function yerr<M>(type: M): YFailure<M>;
-function yress<T, E>(result: Result<T, E>): Failure<E> | YSuccess<T>;
-function yresa<T, E>(promise: Promise<Result<T, E>>): Promise<Failure<E> | YSuccess<T>>;
+function yres<T, E>(result: MaybePromise<Result<T, E>>): MaybePromise<Failure<E> | YSuccess<T>>;
+function yresSync<T, E>(result: Result<T, E>): Failure<E> | YSuccess<T>;
+function yresAsync<T, E>(promise: Promise<Result<T, E>>): Promise<Failure<E> | YSuccess<T>>;
 function yep<T>(result: Success<T>): YSuccess<T>;
 ```
 
 These helpers are useful when you need to separate soft rejections (`success: false`) from hard failures (`fails: true`).
 
-Tips
-----
+### Defer helpers
+
+```typescript
+type DeferSync<E> = (result?: Result<unknown, E>) => Result<unknown, E> | Success<void>;
+type DeferAsync<E> = (result?: Result<unknown, E>) => Promise<Result<unknown, E> | Success<void>>;
+
+function xdefer<E>(callback: () => Result<unknown, E> | Promise<Result<unknown, E>>): DeferSync<E> | DeferAsync<E>;
+function xdeferSync<E>(callback: () => Result<unknown, E>): DeferSync<E>;
+function xdeferAsync<E>(callback: (() => Promise<Result<unknown, E>>) | Promise<Result<unknown, E>>): DeferAsync<E>;
+```
+
+Use these helpers to express "finally" logic that can also fail while preserving the original result when needed:
+
+```typescript
+import { stringifyError, xdefer, xtry } from '@zokugun/xtry/async'
+
+function test(): Result<void, string> {
+    const closeConnection = xdefer(xtry(connection.close()));
+
+    const queryResult = await xtry(connection.query('SELECT 1'));
+
+    if(queryResult.fails) {
+        return closeConnection(err(stringifyError(queryResult.error)))
+    }
+
+    ...
+
+    return closeConnection();
+}
+```
+
+- `xdefer` inspects the callback result: if it fails, it becomes the returned error unless the main result already failed.
+- Passing a promise (or async factory) makes the defer helper async-aware; `xdeferSync`/`xdeferAsync` let you pin the behavior explicitly for bundlers.
+- Calling the returned function with no arguments just runs the deferred work and yields `ok()`.
+
+Module entry points
+-------------------
+
+Choose the entry point that matches your environment and naming preferences:
+
+| Import path           | Description                 | `xtry` name                     | `xdefer` name                         | Extra alias                     |
+| --------------------- | --------------------------- | ------------------------------- | ------------------------------------- | ------------------------------- |
+| `@zokugun/xtry`       | Both sync, async and hybrid | `xtry`, `xtryAsync`, `xtrySync` | `xdefer`, `xdeferAsync`, `xdeferSync` | `yres`, `yresAsync`, `yresSync` |
+| `@zokugun/xtry/async` | Async-only                 | `xtryAsync` as `xtry`           | `xdeferAsync` as `xdefer`             | `yresAsync`  as `yres`          |
+| `@zokugun/xtry/sync`  | Synchronous-only            | `xtrySync` as `xtry`            | `xdeferSync` as `xdefer`              | `yresSync` as `yres`            |
 
-- Narrow on `fails` first, then use other flags (`success`, custom `type` or `value`) for the happy-path branching.
+All modules share the same `Result`, `Partial`, and `stringifyError` exports, so you can swap entry points without refactoring types.
 
 Donations
 ---------

package/lib/async.d.ts

@@ -0,0 +1,7 @@
+export { xdeferAsync as xdefer } from './defer.js';
+export type { YResult, YSuccess, YFailure } from './partial.js';
+export { yok, yerr, yresAsync as yres, yep, YOK, YOK_NULL, YOK_TRUE, YOK_FALSE } from './partial.js';
+export type { Success, Failure, Result } from './result.js';
+export { ok, err, OK, OK_NULL, OK_TRUE, OK_FALSE } from './result.js';
+export { stringifyError } from './stringify-error.js';
+export { xtryAsync as xtry } from './try.js';

package/lib/async.js

@@ -0,0 +1,5 @@
+export { xdeferAsync as xdefer } from './defer.js';
+export { yok, yerr, yresAsync as yres, yep, YOK, YOK_NULL, YOK_TRUE, YOK_FALSE } from './partial.js';
+export { ok, err, OK, OK_NULL, OK_TRUE, OK_FALSE } from './result.js';
+export { stringifyError } from './stringify-error.js';
+export { xtryAsync as xtry } from './try.js';

package/lib/defer.d.ts

@@ -0,0 +1,16 @@
+import { type Result, type Success } from './result.js';
+import { type NonPromiseCallback, type PromiseCallback } from './utils/types.js';
+type DeferAsync<E> = {
+    (): Promise<Success<void>>;
+    (result: UnknownResult<E>): Promise<UnknownResult<E>>;
+};
+type DeferSync<E> = {
+    (): Success<void>;
+    (result: UnknownResult<E>): UnknownResult<E>;
+};
+type UnknownResult<E> = Result<unknown, E>;
+export declare function xdefer<E>(callback: NonPromiseCallback<UnknownResult<E>>): DeferSync<E>;
+export declare function xdefer<E>(callback: PromiseCallback<UnknownResult<E>>): DeferAsync<E>;
+export declare function xdeferAsync<E>(callback: PromiseCallback<UnknownResult<E>>): DeferAsync<E>;
+export declare function xdeferSync<E>(callback: NonPromiseCallback<UnknownResult<E>>): DeferSync<E>;
+export {};

package/lib/defer.js

@@ -0,0 +1,45 @@
+import { ok } from './result.js';
+import { isPromiseLike } from './utils/is-promise-like.js';
+export function xdefer(callback) {
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    return ((result) => {
+        const finalize = (deferResult) => {
+            if (deferResult.fails) {
+                if (result?.fails) {
+                    return result;
+                }
+                return deferResult;
+            }
+            return result ?? ok();
+        };
+        const deferredValue = callback instanceof Function ? callback() : callback;
+        if (isPromiseLike(deferredValue)) {
+            return Promise.resolve(deferredValue).then(finalize);
+        }
+        return finalize(deferredValue);
+    });
+}
+export function xdeferAsync(callback) {
+    return (async (result) => {
+        const deferResult = await (callback instanceof Promise ? callback : callback());
+        if (deferResult.fails) {
+            if (result?.fails) {
+                return result;
+            }
+            return deferResult;
+        }
+        return result ?? ok();
+    });
+}
+export function xdeferSync(callback) {
+    return ((result) => {
+        const deferResult = callback();
+        if (deferResult.fails) {
+            if (result?.fails) {
+                return result;
+            }
+            return deferResult;
+        }
+        return result ?? ok();
+    });
+}

package/lib/index.d.ts

@@ -1,4 +1,7 @@
-export * from './partial.js';
-export * from './result.js';
-export * from './stringify-error.js';
-export * from './try.js';
+export { xdefer, xdeferAsync, xdeferSync } from './defer.js';
+export type { YResult, YSuccess, YFailure } from './partial.js';
+export { yok, yerr, yres, yresAsync, yresSync, yep, YOK, YOK_NULL, YOK_TRUE, YOK_FALSE } from './partial.js';
+export type { Success, Failure, Result } from './result.js';
+export { ok, err, OK, OK_NULL, OK_TRUE, OK_FALSE } from './result.js';
+export { stringifyError } from './stringify-error.js';
+export { xtry, xtryAsync, xtrySync } from './try.js';

package/lib/index.js

@@ -1,4 +1,5 @@
-export * from './partial.js';
-export * from './result.js';
-export * from './stringify-error.js';
-export * from './try.js';
+export { xdefer, xdeferAsync, xdeferSync } from './defer.js';
+export { yok, yerr, yres, yresAsync, yresSync, yep, YOK, YOK_NULL, YOK_TRUE, YOK_FALSE } from './partial.js';
+export { ok, err, OK, OK_NULL, OK_TRUE, OK_FALSE } from './result.js';
+export { stringifyError } from './stringify-error.js';
+export { xtry, xtryAsync, xtrySync } from './try.js';

package/lib/partial.d.ts

@@ -1,4 +1,5 @@
 import { type Result, type Failure, type Success } from './result.js';
+import { type NotPromise } from './utils/types.js';
 export type YResult<T, E, M> = Failure<E> | YSuccess<T> | YFailure<M>;
 export type YSuccess<T> = Success<T> & {
     success: true;
@@ -10,8 +11,17 @@ export type YFailure<M> = {
     value: undefined;
     error: undefined;
 };
+export declare function yok(): YSuccess<void>;
 export declare function yok<T>(value: T): YSuccess<T>;
 export declare function yerr<M>(miscue: M): YFailure<M>;
-export declare function yress<T, E>(result: Result<T, E>): Failure<E> | YSuccess<T>;
-export declare function yresa<T, E>(promise: Promise<Result<T, E>>): Promise<Failure<E> | YSuccess<T>>;
+type YRResult<T, E> = Failure<E> | YSuccess<T>;
+export declare function yres<T, E>(result: NotPromise<Result<T, E>>): YRResult<T, E>;
+export declare function yres<T, E>(result: Promise<Result<T, E>>): Promise<YRResult<T, E>>;
+export declare function yresSync<T, E>(result: NotPromise<Result<T, E>>): YRResult<T, E>;
+export declare function yresAsync<T, E>(promise: Promise<Result<T, E>>): Promise<YRResult<T, E>>;
 export declare function yep<T>(result: Success<T>): YSuccess<T>;
+export declare const YOK: Readonly<YSuccess<void>>;
+export declare const YOK_NULL: Readonly<YSuccess<null>>;
+export declare const YOK_TRUE: Readonly<YSuccess<boolean>>;
+export declare const YOK_FALSE: Readonly<YSuccess<boolean>>;
+export {};

package/lib/partial.js

@@ -1,8 +1,9 @@
+import { isPromiseLike } from './utils/is-promise-like.js';
 export function yok(value) {
     return {
         fails: false,
         success: true,
-        value,
+        value: value,
         error: undefined,
     };
 }
@@ -15,14 +16,20 @@ export function yerr(miscue) {
         error: undefined,
     };
 }
-export function yress(result) {
+export function yres(result) {
+    if (isPromiseLike(result)) {
+        return result.then(yresSync);
+    }
+    return yresSync(result);
+}
+export function yresSync(result) {
     if (result.fails) {
         return result;
     }
     return yep(result);
 }
-export async function yresa(promise) {
-    return promise.then(yress);
+export async function yresAsync(promise) {
+    return promise.then(yresSync);
 }
 export function yep(result) {
     return {
@@ -30,3 +37,7 @@ export function yep(result) {
         success: true,
     };
 }
+export const YOK = Object.freeze(yok());
+export const YOK_NULL = Object.freeze(yok(null));
+export const YOK_TRUE = Object.freeze(yok(true));
+export const YOK_FALSE = Object.freeze(yok(false));

package/lib/result.d.ts

@@ -9,5 +9,10 @@ export type Failure<E> = {
     error: E;
 };
 export type Result<T, E> = Success<T> | Failure<E>;
+export declare function ok(): Success<void>;
 export declare function ok<T>(value: T): Success<T>;
 export declare function err<E>(error: E): Failure<E>;
+export declare const OK: Readonly<Success<void>>;
+export declare const OK_NULL: Readonly<Success<null>>;
+export declare const OK_TRUE: Readonly<Success<boolean>>;
+export declare const OK_FALSE: Readonly<Success<boolean>>;

package/lib/result.js

@@ -1,7 +1,7 @@
 export function ok(value) {
     return {
         fails: false,
-        value,
+        value: value,
         error: undefined,
     };
 }
@@ -12,3 +12,7 @@ export function err(error) {
         error,
     };
 }
+export const OK = Object.freeze(ok());
+export const OK_NULL = Object.freeze(ok(null));
+export const OK_TRUE = Object.freeze(ok(true));
+export const OK_FALSE = Object.freeze(ok(false));

package/lib/sync.d.ts

@@ -0,0 +1,7 @@
+export { xdeferSync as xdefer } from './defer.js';
+export type { YResult, YSuccess, YFailure } from './partial.js';
+export { yok, yerr, yresSync as yres, yep, YOK, YOK_NULL, YOK_TRUE, YOK_FALSE } from './partial.js';
+export type { Success, Failure, Result } from './result.js';
+export { ok, err, OK, OK_NULL, OK_TRUE, OK_FALSE } from './result.js';
+export { stringifyError } from './stringify-error.js';
+export { xtrySync as xtry } from './try.js';

package/lib/sync.js

@@ -0,0 +1,5 @@
+export { xdeferSync as xdefer } from './defer.js';
+export { yok, yerr, yresSync as yres, yep, YOK, YOK_NULL, YOK_TRUE, YOK_FALSE } from './partial.js';
+export { ok, err, OK, OK_NULL, OK_TRUE, OK_FALSE } from './result.js';
+export { stringifyError } from './stringify-error.js';
+export { xtrySync as xtry } from './try.js';

package/lib/try.d.ts

@@ -1,3 +1,9 @@
 import { type Result } from './result.js';
-export declare function xtry<T, E = unknown>(func: () => Exclude<T, Promise<unknown>>, handler?: (error: unknown) => E | undefined): E extends void ? Result<T, unknown> : Result<T, E>;
-export declare function xatry<T, E = unknown>(func: (() => Exclude<T, Promise<unknown>>) | Promise<Exclude<T, Promise<unknown>>>, handler?: (error: unknown) => E | undefined): Promise<E extends void ? Result<T, unknown> : Result<T, E>>;
+import { type NonPromiseCallback, type PromiseCallback } from './utils/types.js';
+type ErrorHandler<T> = (error: unknown) => T | undefined;
+type VoidableResult<T, E> = E extends void ? Result<T, unknown> : Result<T, E>;
+export declare function xtry<T, E = unknown>(func: NonPromiseCallback<T>, handler?: ErrorHandler<E>): VoidableResult<T, E>;
+export declare function xtry<T, E = unknown>(func: PromiseCallback<T>, handler?: ErrorHandler<E>): Promise<VoidableResult<T, E>>;
+export declare function xtrySync<T, E = unknown>(func: NonPromiseCallback<T>, handler?: ErrorHandler<E>): VoidableResult<T, E>;
+export declare function xtryAsync<T, E = unknown>(func: PromiseCallback<T>, handler?: ErrorHandler<E>): Promise<VoidableResult<T, E>>;
+export {};

package/lib/try.js

@@ -1,5 +1,33 @@
 import { err, ok } from './result.js';
+import { isPromiseLike } from './utils/is-promise-like.js';
 export function xtry(func, handler) {
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    const run = func instanceof Function ? func : () => func;
+    const handleError = (error) => {
+        if (handler) {
+            const newError = handler(error);
+            if (newError !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                return err(newError);
+            }
+        }
+        return err(error);
+    };
+    const handleSuccess = (value) => ok(value);
+    try {
+        const value = run();
+        if (isPromiseLike(value)) {
+            return Promise.resolve(value).then(handleSuccess, handleError);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return ok(value);
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return handleError(error);
+    }
+}
+export function xtrySync(func, handler) {
     try {
         const value = func();
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return
@@ -17,7 +45,7 @@ export function xtry(func, handler) {
         return err(error);
     }
 }
-export async function xatry(func, handler) {
+export async function xtryAsync(func, handler) {
     try {
         const value = await (func instanceof Promise ? func : Promise.resolve().then(func));
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return

package/lib/utils/is-promise-like.d.ts

@@ -0,0 +1,3 @@
+type MaybePromise<T> = T | PromiseLike<T>;
+export declare function isPromiseLike<T>(value: MaybePromise<T>): value is PromiseLike<T>;
+export {};

package/lib/utils/is-promise-like.js

@@ -0,0 +1,3 @@
+export function isPromiseLike(value) {
+    return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}

package/lib/utils/types.d.ts

@@ -0,0 +1,5 @@
+export type NotPromise<T> = Exclude<T, Promise<unknown>>;
+export type NonPromiseCallback<T> = () => NotPromise<T>;
+export type PromiseCallback<T> = (() => Promise<T>) | Promise<T>;
+export type Callback<T> = NonPromiseCallback<T> | PromiseCallback<T>;
+export type MaybePromise<T> = T | Promise<T>;

package/lib/utils/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@zokugun/xtry",
 	"description": "simple try/catch wrapper returning Result",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"author": {
 		"name": "Baptiste Augrain",
 		"email": "daiyam@zokugun.org"
@@ -16,41 +16,40 @@
 		"url": "https://github.com/zokugun/node-xtry/issues"
 	},
 	"type": "module",
+	"exports": {
+		".": "./lib/index.js",
+		"./async": "./lib/async.js",
+		"./sync": "./lib/sync.js"
+	},
 	"main": "lib/index.js",
 	"scripts": {
 		"commit": "cz",
 		"compile": "tsc -p src",
 		"lint": "xo",
+		"lint:fix": "xo --fix",
 		"prepare": "husky; fixpack || true",
 		"prepublishOnly": "npm run compile",
 		"release": "release-it",
-		"test": "tsc -p test && mocha",
-		"test:dev": "mocha",
-		"test:watch": "tsc-watch -p test --onSuccess 'mocha'",
-		"watch:src": "tsc -watch -p src",
-		"watch:test": "tsc-watch -p test"
+		"test": "vitest run",
+		"watch:source": "tsc-watch -p src",
+		"watch:test": "vitest"
 	},
 	"dependencies": {},
 	"devDependencies": {
 		"@commitlint/cli": "^19.7.1",
 		"@commitlint/config-conventional": "^19.7.1",
-		"@types/chai": "^5.0.1",
 		"@types/fs-extra": "^11.0.4",
-		"@types/mocha": "^10.0.10",
 		"@types/node": "^20.14.8",
-		"chai": "^5.2.0",
 		"commitizen": "^4.3.1",
-		"eslint-plugin-chai-friendly": "^1.0.1",
 		"fixpack": "^4.0.0",
-		"fs-extra": "^11.3.0",
-		"globby": "^14.1.0",
+		"fs-extra": "^11.3.3",
+		"globby": "^16.1.0",
 		"husky": "^9.1.7",
-		"lint-staged": "^15.4.3",
-		"mocha": "^11.1.0",
+		"lint-staged": "^16.1.4",
 		"release-it": "^18.1.2",
-		"source-map-support": "^0.5.21",
 		"tsc-watch": "^6.3.0",
 		"typescript": "^5.7.3",
+		"vitest": "^4.0.16",
 		"xo": "0.60.0"
 	},
 	"keywords": [