@zokugun/xtry 0.1.0 → 0.3.0

package/README.md

@@ -7,75 +7,159 @@
 [![Donation](https://img.shields.io/badge/donate-liberapay-green)](https://liberapay.com/daiyam/donate)
 [![Donation](https://img.shields.io/badge/donate-paypal-green)](https://paypal.me/daiyam99)
 
-Simple `try/catch` wrapper returning Result
+Simple `try/catch` wrappers that always return a `Result` discriminated union, plus ready-made helpers (`ok`, `err`) for predictable control flow.
 
-Getting Started
----------------
+Why xtry?
+---------
 
-With [node](http://nodejs.org) previously installed:
+- 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).
+- Optional failure handlers let you log, meter, or mutate state exactly where the error occurs.
 
-	npm install @zokugun/xtry
+Installation
+------------
 
-Basic Example
--------------
+```bash
+npm install @zokugun/xtry
+```
+
+Quick Start
+-----------
 
 ```typescript
 import { xatry } from '@zokugun/xtry'
 
-const { fails, value, error } = xatry(somePromise);
+const userResult = await xatry(fetchUserFromApi());
+
+if(userResult.fails) {
+    console.error(userResult.error);
+    return;
+}
+
+console.log('User loaded:', userResult.value);
 ```
 
 Advanced Example
 ----------------
 
 ```typescript
-import { err, ok, type Result, xatry, xtry } from '@zokugun/xtry'
+import { err, type Result, xatry, xtry } from '@zokugun/xtry'
 
 export type FoobarError = { type: 'FOOBAR'; message: string };
 
-function foobar(): Result<number, FoobarError> {
-    const { fails, value, error } = xatry(somePromise);
+async function foobar(): Result<number, FoobarError> {
+    const result = await xatry(fetchUserFromApi());
 
-    if (fails) {
+    if(fails) {
         return err({ type: 'FOOBAR', message: 'The promise has failed...' });
     }
 
-    return ok(value);
+    return try(() => calculateAge(result.value));
 }
 
-function main() {
-    const result = foobar();
+async function main() {
+    const result = await foobar();
 
-    if (result.fails) {
+    if(result.fails) {
         console.error(result.error.message);
-        exit(1);
+
+        return;
+    }
+
+    console.log(result.value);
+}
+```
+
+Partial Example
+---------------
+
+`YResult` extends the base `Result` union with a `success` flag so you can distinguish "valid failure" states from true errors.
+
+```typescript
+import { err, ok, yerr, yok, type YResult } from '@zokugun/xtry'
+
+function toNumber(input: string): YResult<number, MyError, 'empty-string'> {
+    if(input.length > 0) {
+        return yerr('empty-string');
+    }
+
+    const floatValue = Number.parseFloat(input);
+
+    if(Number.isNaN(floatValue)) {
+        return err({ type: '#VALUE!' });
+    }
+
+    return yok(floatValue);
+}
+
+function add(_x: string, _y: number): Result<number, MyError> {
+    const x = toNumber(_x);
+    if(x.fails) {
+        return x;
+    }
+    if(!x.success) {
+        return ok(0);
+    }
+
+    const y = toNumber(_y);
+    if(y.fails) {
+        return y;
+    }
+    if(!y.success) {
+        return ok(0);
     }
 
-    console.log(value);
+    return x.value + y.value;
 }
 ```
 
-API
----
+API reference
+-------------
+
+### Result helpers
 
 ```typescript
-type Success<T> = {
-    fails: false;
-    value: T;
-    error: null;
-};
-type Failure<E> = {
-    fails: true;
-    value: null;
-    error: E;
-};
+export type Success<T> = { fails: false; value: T; error: null };
+export type Failure<E> = { fails: true; value: null; error: E };
 export type Result<T, E> = Success<T> | Failure<E>;
-export function xtry<T, E>(func: () => Exclude<T, Promise<unknown>>, handler?: ((error: E) => void)): Result<T, E>;
-export async function xatry<T, E>(func: (() => Exclude<T, Promise<unknown>>) | Promise<Exclude<T, Promise<unknown>>>, handler?: ((error: E) => void)): Promise<Result<T, E>>;
+
 export function ok<T>(value: T): Success<T>;
 export function err<E>(error: E): Failure<E>;
 ```
 
+### Try helpers
+
+```typescript
+export function xtry<T, E>(func: () => Exclude<T, Promise<unknown>>, handler?: (error: unknown) => void | E): Result<T, E>;
+export function xatry<T, E>(func: (() => Exclude<T, Promise<unknown>>) | Promise<Exclude<T, Promise<unknown>>>, handler?: (error: unknown) => void | E): Promise<Result<T, E>>;
+
+export function stringifyError(error: unknown): string;
+```
+
+Both helpers:
+
+- execute the supplied function and capture thrown values;
+- call the optional `handler` before turning that value into `err(error)`;
+- never throw, making the return signature a reliable discriminated union.
+
+### Partial helpers
+
+```typescript
+export type YSuccess<T> = Success<T> & { success: true };
+export type YFailure<S> = { fails: false; success: false; type: S; value: null; error: null };
+export type YResult<T, E, S> = Failure<E> | YSuccess<T> | YFailure<S>;
+
+export function yok<T>(value: T): YSuccess<T>;
+export function yerr<S>(type: S): YFailure<S>;
+```
+
+These helpers are useful when you need to separate soft rejections (`success: false`) from hard failures (`fails: true`).
+
+Tips
+----
+
+- Narrow on `fails` first, then use other flags (`success`, custom `type` or `value`) for the happy-path branching.
+
 Donations
 ---------
 

package/lib/index.d.ts

@@ -1,16 +1,4 @@
-type Success<T> = {
-    fails: false;
-    value: T;
-    error: null;
-};
-type Failure<E> = {
-    fails: true;
-    value: null;
-    error: E;
-};
-export type Result<T, E> = Success<T> | Failure<E>;
-export declare function xtry<T, E>(func: () => Exclude<T, Promise<unknown>>, handler?: ((error: E) => void)): Result<T, E>;
-export declare function xatry<T, E>(func: (() => Exclude<T, Promise<unknown>>) | Promise<Exclude<T, Promise<unknown>>>, handler?: ((error: E) => void)): Promise<Result<T, E>>;
-export declare function ok<T>(value: T): Success<T>;
-export declare function err<E>(error: E): Failure<E>;
-export {};
+export * from './partial.js';
+export * from './result.js';
+export * from './stringify-error.js';
+export * from './try.js';

package/lib/index.js

@@ -1,38 +1,4 @@
-export function xtry(func, handler) {
-    try {
-        const value = func();
-        return ok(value);
-    }
-    catch (error) {
-        if (handler) {
-            handler(error);
-        }
-        return err(error);
-    }
-}
-export async function xatry(func, handler) {
-    try {
-        const value = await (func instanceof Promise ? func : Promise.resolve().then(func));
-        return ok(value);
-    }
-    catch (error) {
-        if (handler) {
-            handler(error);
-        }
-        return err(error);
-    }
-}
-export function ok(value) {
-    return {
-        fails: false,
-        value,
-        error: null,
-    };
-}
-export function err(error) {
-    return {
-        fails: true,
-        value: null,
-        error,
-    };
-}
+export * from './partial.js';
+export * from './result.js';
+export * from './stringify-error.js';
+export * from './try.js';

package/lib/partial.d.ts

@@ -0,0 +1,14 @@
+import { type Failure, type Success } from './result.js';
+export type YResult<T, E, S> = Failure<E> | YSuccess<T> | YFailure<S>;
+export type YSuccess<T> = Success<T> & {
+    success: true;
+};
+export type YFailure<S> = {
+    fails: false;
+    success: false;
+    type: S;
+    value: null;
+    error: null;
+};
+export declare function yok<T>(value: T): YSuccess<T>;
+export declare function yerr<S>(type: S): YFailure<S>;

package/lib/partial.js

@@ -0,0 +1,17 @@
+export function yok(value) {
+    return {
+        fails: false,
+        success: true,
+        value,
+        error: null,
+    };
+}
+export function yerr(type) {
+    return {
+        fails: false,
+        success: false,
+        type,
+        value: null,
+        error: null,
+    };
+}

package/lib/result.d.ts

@@ -0,0 +1,13 @@
+export type Success<T> = {
+    fails: false;
+    value: T;
+    error: null;
+};
+export type Failure<E> = {
+    fails: true;
+    value: null;
+    error: E;
+};
+export type Result<T, E> = Success<T> | Failure<E>;
+export declare function ok<T>(value: T): Success<T>;
+export declare function err<E>(error: E): Failure<E>;

package/lib/result.js

@@ -0,0 +1,14 @@
+export function ok(value) {
+    return {
+        fails: false,
+        value,
+        error: null,
+    };
+}
+export function err(error) {
+    return {
+        fails: true,
+        value: null,
+        error,
+    };
+}

package/lib/stringify-error.d.ts

@@ -0,0 +1 @@
+export declare function stringifyError(error: unknown): string;

package/lib/stringify-error.js

@@ -0,0 +1,18 @@
+export function stringifyError(error) {
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error instanceof Error) {
+        return error.message ?? String(error);
+    }
+    try {
+        const json = JSON.stringify(error);
+        if (typeof json === 'string') {
+            return json;
+        }
+    }
+    catch {
+        // fallthrough
+    }
+    return String(error);
+}

package/lib/try.d.ts

@@ -0,0 +1,3 @@
+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>>;

package/lib/try.js

@@ -0,0 +1,37 @@
+import { err, ok } from './result.js';
+export function xtry(func, handler) {
+    try {
+        const value = func();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return ok(value);
+    }
+    catch (error) {
+        if (handler) {
+            const newError = handler(error);
+            if (newError !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                return err(newError);
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return err(error);
+    }
+}
+export async function xatry(func, handler) {
+    try {
+        const value = await (func instanceof Promise ? func : Promise.resolve().then(func));
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return ok(value);
+    }
+    catch (error) {
+        if (handler) {
+            const newError = handler(error);
+            if (newError !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                return err(newError);
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return err(error);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@zokugun/xtry",
 	"description": "simple try/catch wrapper returning Result",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"author": {
 		"name": "Baptiste Augrain",
 		"email": "daiyam@zokugun.org"

package/lib/test.d.ts

@@ -1,4 +0,0 @@
-export type FoobarError = {
-    type: 'FOOBAR';
-    message: string;
-};

package/lib/test.js

@@ -1,21 +0,0 @@
-import { err, ok, xatry } from './index.js';
-import { exit } from 'node:process';
-import { readFile } from "fs/promises";
-async function readConfigFile() {
-    return readFile("./config.json", "utf-8").then((data) => JSON.parse(data).PORT);
-}
-async function foobar() {
-    const { fails, value } = await xatry(readConfigFile());
-    if (fails) {
-        return err({ type: 'FOOBAR', message: 'The promise has failed...' });
-    }
-    return ok(value);
-}
-async function main() {
-    const { fails, value } = await xatry(foobar);
-    if (fails) {
-        exit(1);
-    }
-    console.log(value);
-}
-main();