neverpanic 0.0.2 → 0.0.4

package/README.md

@@ -1,5 +1,54 @@
 # neverpanic
 
-This is the next generation of error handling in JavaScript. How many times have you gotten out of bed, ready to get on with your day, only to find that you have 1243 Sentry alerts because you forgot to gracefuly handle an exception in your NodeJS backend. The truth is, these are not exceptions, these are panics. Panics not just in your code, but also to your mental health.
+This is the next generation of error handling in JavaScript. How many times have
+you gotten out of bed, ready to get on with your day, only to find that you have
+1243 Sentry alerts because you forgot to gracefuly handle an exception in your
+NodeJS backend. The truth is, these are not exceptions, these are panics. Panics
+not just in your code, but also to your mental health.
 
-Try neverpanic, and live a zen life.
+Try neverpanic, and live a zen life.
+
+## Examples
+
+### safeFn
+
+Create a safe function from an unsafe one:
+
+- Ensures that only a `Result` can be returned
+- Catches and returns any unexpected errors as a `Result`
+
+```ts
+const getUser = n.safeFn(
+    async (id: string) => {
+        const res = await fetch(`https://example.com/users/${id}`);
+        if (!res.ok) return { success: false, error: "FAILED_TO_FETCH" };
+
+        return { success: true, data: await res.json() };
+    },
+    (err) => "FAILED_TO_GET_USER",
+);
+
+const getUserResult = await getUser("some-user-id");
+if (!getUserResult.success) {
+    console.error(getUserResult.error);
+} else {
+    console.log(getUserResult.data);
+}
+```
+
+### fromUnsafe
+
+Runs the provided callback function, catching any thrown errors and returning a
+`Result`
+
+```ts
+const user = await n.fromUnsafe(
+    () => db.findUser("some-user-id"),
+    (err) => "FAILED_T0_FIND_USER",
+);
+if (!user.success) {
+    console.error(user.error);
+} else {
+    console.log(user.data);
+}
+```

package/dist/index.d.ts

@@ -1,13 +1,54 @@
-type Result<T, E = unknown> = {
+export type Result<T = unknown, E = unknown> = {
     success: true;
     data: T;
 } | {
     success: false;
     error: E;
 };
-declare function safeReturn<T, E>(cb: () => Promise<Result<T, E>> | Result<T, E>): Promise<Result<T, E | null>>;
-declare function safeReturn<T, E, H>(cb: () => Promise<Result<T, E>> | Result<T, E>, eh: (err: unknown) => H): Promise<Result<T, E | H>>;
-export declare const o: {
-    safeReturn: typeof safeReturn;
+/**
+ * Create a safe function from an unsafe one.
+ *
+ * @param cb - The async function to wrap.
+ * @param [eh] - Optional fallback error handler.
+ * @returns A new function that returns a typesafe Result.
+ *
+ * @example
+ * const getUser = n.safeFn(
+ *   async (id: string) => {
+ *     const res = await fetch(`https://example.com/users/${id}`);
+ *     if (!res.ok) return { success: false, error: "FAILED_TO_FETCH" };
+ *
+ *     return { success: true, data: await res.json() };
+ *   },
+ *   () => "FAILED_TO_GET_USER"
+ * );
+ *
+ * const getUserResult = await getUser("some-user-id");
+ * if (!getUserResult.success) {
+ *   console.error(getUserResult.error);
+ * } else {
+ *   console.log(getUserResult.data);
+ * }
+ */
+declare function safeFn<T extends Result | Promise<Result>, A extends unknown[], E = null>(cb: (...args: A) => T, eh?: (e: unknown) => E): (...args: A) => T | Result<never, E>;
+/**
+ * Run an unsafe function, handle any errors and return a Result.
+ *
+ * @param cb - The async function to call.
+ * @param [eh] - Optional fallback error handler.
+ * @returns The awaited return value of cb.
+ *
+ * @example
+ * const user = await n.fromUnsafe(() => db.findUser('some-user-id'), () => 'FAILED_T0_FIND_USER')
+ * if (!user.success) {
+ * 	console.error(user.error)
+ * } else {
+ * 	console.log(user.data)
+ * }
+ */
+declare function fromUnsafe<T, E = null, R = T extends Promise<unknown> ? Promise<Result<Awaited<T>, E>> : Result<T, E>>(cb: () => T, eh?: (err: unknown) => E): R;
+export declare const n: {
+    safeFn: typeof safeFn;
+    fromUnsafe: typeof fromUnsafe;
 };
 export {};

package/dist/index.js

@@ -1,61 +1,77 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
+/**
+ * Create a safe function from an unsafe one.
+ *
+ * @param cb - The async function to wrap.
+ * @param [eh] - Optional fallback error handler.
+ * @returns A new function that returns a typesafe Result.
+ *
+ * @example
+ * const getUser = n.safeFn(
+ *   async (id: string) => {
+ *     const res = await fetch(`https://example.com/users/${id}`);
+ *     if (!res.ok) return { success: false, error: "FAILED_TO_FETCH" };
+ *
+ *     return { success: true, data: await res.json() };
+ *   },
+ *   () => "FAILED_TO_GET_USER"
+ * );
+ *
+ * const getUserResult = await getUser("some-user-id");
+ * if (!getUserResult.success) {
+ *   console.error(getUserResult.error);
+ * } else {
+ *   console.log(getUserResult.data);
+ * }
+ */
+function safeFn(cb, eh) {
+    const createErrorResult = (e) => ({
+        success: false,
+        error: eh?.(e) ?? null,
     });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
-    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (g && (g = 0, op[0] && (_ = 0)), _) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.o = void 0;
-function safeReturn(cb, eh) {
-    return __awaiter(this, void 0, void 0, function () {
-        var e_1;
-        var _a;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
-                case 0:
-                    _b.trys.push([0, 2, , 3]);
-                    return [4 /*yield*/, cb()];
-                case 1: return [2 /*return*/, _b.sent()];
-                case 2:
-                    e_1 = _b.sent();
-                    return [2 /*return*/, {
-                            success: false,
-                            error: (_a = eh === null || eh === void 0 ? void 0 : eh(e_1)) !== null && _a !== void 0 ? _a : null,
-                        }];
-                case 3: return [2 /*return*/];
-            }
-        });
+    return (...args) => {
+        try {
+            const result = cb(...args);
+            if (result instanceof Promise)
+                return result.catch(createErrorResult);
+            return result;
+        }
+        catch (e) {
+            return createErrorResult(e);
+        }
+    };
+}
+/**
+ * Run an unsafe function, handle any errors and return a Result.
+ *
+ * @param cb - The async function to call.
+ * @param [eh] - Optional fallback error handler.
+ * @returns The awaited return value of cb.
+ *
+ * @example
+ * const user = await n.fromUnsafe(() => db.findUser('some-user-id'), () => 'FAILED_T0_FIND_USER')
+ * if (!user.success) {
+ * 	console.error(user.error)
+ * } else {
+ * 	console.log(user.data)
+ * }
+ */
+function fromUnsafe(cb, eh) {
+    const createErrorResult = (e) => ({
+        success: false,
+        error: eh?.(e) ?? null,
+    });
+    const createSuccessResult = (data) => ({
+        success: true,
+        data,
     });
+    try {
+        const result = cb();
+        if (result instanceof Promise)
+            return result.then(createSuccessResult).catch(createErrorResult);
+        return createSuccessResult(result);
+    }
+    catch (e) {
+        return createErrorResult(e);
+    }
 }
-exports.o = { safeReturn: safeReturn };
+export const n = { safeFn, fromUnsafe };

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "neverpanic",
   "module": "index.ts",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
+  "repository": {
+    "url": "https://github.com/bgrcs/neverpanic"
+  },
   "scripts": {
-    "build": "tsc index.ts --outdir dist"
+    "build": "tsc",
+    "test": "bun test"
   },
   "files": ["dist"],
   "exports": {
@@ -14,6 +18,6 @@
     "@types/bun": "latest"
   },
   "peerDependencies": {
-    "@typescript/native-preview": "latest"
+    "typescript": "5"
   }
 }