neverpanic 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/index.d.ts

@@ -5,6 +5,29 @@ export type Result<T = unknown, E = unknown> = {
     success: false;
     error: E;
 };
+/**
+ * Create a typesafe instance of neverpanic.
+ *
+ * @returns An instance of neverpanic that conforms to the types specified in the generic arguments.
+ *
+ * @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);
+ * }
+ */
 export declare const createNeverpanic: <D = unknown, E = unknown>() => {
     ok: <const T extends D>(data: T) => Result<T, never>;
     err: <const T extends E>(error: T) => Result<never, T>;

package/dist/index.js

@@ -1,3 +1,26 @@
+/**
+ * Create a typesafe instance of neverpanic.
+ *
+ * @returns An instance of neverpanic that conforms to the types specified in the generic arguments.
+ *
+ * @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);
+ * }
+ */
 export const createNeverpanic = () => {
     const ok = (data) => ({
         success: true,
@@ -7,6 +30,31 @@ export const createNeverpanic = () => {
         success: false,
         error,
     });
+    /**
+     * 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);
+     * }
+     */
     const safeFn = (cb, eh) => (...args) => {
         try {
             const result = cb(...args);
@@ -18,6 +66,21 @@ export const createNeverpanic = () => {
             return eh(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)
+     * }
+     */
     const fromUnsafe = (cb, eh) => {
         try {
             const result = cb();
@@ -29,6 +92,22 @@ export const createNeverpanic = () => {
             return eh(e);
         }
     };
+    /**
+     * Convert a list of results into a single result.
+     *
+     * @param results - A list of Results.
+     * @returns A single result containing the data / errors of the input results.
+     *
+     * @example
+     * const findUserResults = userIds.map((userId) =>
+     *   n.fromUnsafe(
+     *     () => db.findUser(userId),
+     *     () => "FAILED_TO_FIND_USER" as const,
+     *   ),
+     * );
+     *
+     * const result = n.resultsToResult(findUserResults)
+     */
     const resultsToResult = (results) => {
         const errors = results.filter((result) => !result.success);
         if (errors.length)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neverpanic",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "repository": {
     "url": "https://github.com/bgrcs/neverpanic"
   },