Merge pull request #51 from kenn/replace_variants

Add `replaceWithFlash` / `replaceWithToast`

Author: AlemTuzlak

README.md

@@ -239,6 +239,11 @@ export const {
   redirectWithError,
   redirectWithInfo,
   redirectWithWarning,
+  replaceWithToast,
+  replaceWithSuccess,
+  replaceWithError,
+  replaceWithInfo,
+  replaceWithWarning,
   dataWithSuccess,
   dataWithError,
   dataWithInfo,
@@ -248,9 +253,9 @@ export const {
 
 ## Utilities
 
-## Redirect important notice!
+## Redirect/replace important notice!
 
-If you want to use `throw` with any of the `redirectWith...` utilities you need to `await` the function call. This is because `redirectWith...` utilities have to generate a cookie and set it on the headers and if that is not awaited the headers won't be set properly and the redirect won't work.
+If you want to use `throw` with any of the `redirectWith...` or `replaceWith...` utilities you need to `await` the function call. This is because those utilities have to generate a cookie and set it on the headers and if that is not awaited the headers won't be set properly and the redirect won't work.
 
 ### redirectWithToast
 
@@ -318,6 +323,72 @@ export const action = () => {
 };
 ```
 
+### replaceWithToast
+
+Replaces the current entry in the history stack and shows a toast message.
+
+```tsx
+import { replaceWithToast } from "remix-toast";
+
+export const action = () => {
+  return replaceWithToast("/login", {
+    message: "You need to login to access this page",
+    description: "description of toast",
+    type: "error",
+  });
+};
+```
+
+### replaceWithSuccess
+
+Replaces the current entry in the history stack and shows a success toast message.
+
+```tsx
+import { replaceWithSuccess } from "remix-toast";
+
+export const action = () => {
+  return replaceWithSuccess("/login", "You are logged in!");
+  //or with description and message (works for all the other utilities as well)
+  return replaceWithSuccess("/login", { message: "You are logged in!", description: "description of toast" });
+};
+```
+
+### replaceWithError
+
+Replaces the current entry in the history stack and shows an error toast message.
+
+```tsx
+import { replaceWithError } from "remix-toast";
+
+export const action = () => {
+  return replaceWithError("/login", "You need to login to access this page");
+};
+```
+
+### replaceWithInfo
+
+Replaces the current entry in the history stack and shows an info toast message.
+
+```tsx
+import { replaceWithInfo } from "remix-toast";
+
+export const action = () => {
+  return replaceWithInfo("/login", "You need to login to access this page");
+};
+```
+
+### replaceWithWarning
+
+Replaces the current entry in the history stack and shows a warning toast message.
+
+```tsx
+import { replaceWithWarning } from "remix-toast";
+
+export const action = () => {
+  return replaceWithWarning("/login", "You need to login to access this page");
+};
+```
+
 ### dataWithSuccess
 
 Display a success toast message without a redirection.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "remix-toast",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Utility functions for server-side toast notifications",
   "type": "module",
   "main": "./dist/index.cjs",

src/index.test.ts

@@ -0,0 +1,44 @@
+import { createCookieSessionStorage } from "react-router";
+import { createToastUtilsWithCustomSession, getToast, replaceWithSuccess } from "./index";
+
+describe("replaceWith* utilities", () => {
+  it("marks replacements and flashes toast data", async () => {
+    const response = await replaceWithSuccess("/next", "Saved!");
+
+    expect(response.headers.get("Location")).toBe("/next");
+    expect(response.headers.get("X-Remix-Replace")).toBe("true");
+
+    const setCookie = response.headers.get("Set-Cookie");
+    expect(setCookie).toBeTruthy();
+
+    const request = new Request("http://example.com");
+    request.headers.set("Cookie", setCookie?.split(";")[0] ?? "");
+    const { toast } = await getToast(request);
+
+    expect(toast).toEqual({ message: "Saved!", type: "success" });
+  });
+
+  it("uses a provided custom session storage", async () => {
+    const customSession = createCookieSessionStorage({
+      cookie: {
+        name: "custom-toast-session",
+        secrets: ["custom-secret"],
+      },
+    });
+
+    const { replaceWithError, getToast: getToastFromCustomSession } =
+      createToastUtilsWithCustomSession(customSession);
+
+    const response = await replaceWithError("/oops", "Something went wrong");
+    const setCookie = response.headers.get("Set-Cookie");
+
+    expect(setCookie).toContain("custom-toast-session");
+
+    const request = new Request("http://example.com");
+    request.headers.set("Cookie", setCookie?.split(";")[0] ?? "");
+
+    const { toast } = await getToastFromCustomSession(request);
+
+    expect(toast).toEqual({ message: "Something went wrong", type: "error" });
+  });
+});

src/index.ts

@@ -1,4 +1,4 @@
-import { type SessionStorage, createCookieSessionStorage, data as dataFn, redirect } from "react-router";
+import { type SessionStorage, createCookieSessionStorage, data as dataFn, redirect, replace } from "react-router";
 import {
   FLASH_SESSION,
   type FlashSessionValues,
@@ -49,6 +49,18 @@ async function redirectWithFlash(
   });
 }
 
+async function replaceWithFlash(
+  url: string,
+  flash: FlashSessionValues,
+  init?: ResponseInit,
+  customSession?: SessionStorage,
+) {
+  return replace(url, {
+    ...init,
+    headers: await flashMessage(flash, init?.headers, customSession),
+  });
+}
+
 async function dataWithFlash<T>(
   data: T,
   flash: FlashSessionValues,
@@ -90,6 +102,18 @@ const redirectWithToastFactory = ({ type, session }: BaseFactoryType) => {
   };
 };
 
+const replaceWithToastFactory = ({ type, session }: BaseFactoryType) => {
+  return (
+    replaceUrl: string,
+    messageOrToast: string | ToastMessageWithoutType,
+    init?: ResponseInit,
+    customSession?: SessionStorage,
+  ) => {
+    const finalInfo = typeof messageOrToast === "string" ? { message: messageOrToast } : messageOrToast;
+    return replaceWithFlash(replaceUrl, { toast: { ...finalInfo, type } }, init, customSession ?? session);
+  };
+};
+
 /**
  * Helper method used to get the toast data from the current request and purge the flash storage from the session
  * @param request Current request
@@ -134,10 +158,17 @@ export const createToastUtilsWithCustomSession = (session: SessionStorage) => {
     redirectWithToast: (redirectUrl: string, toast: ToastMessage, init?: ResponseInit) => {
       return redirectWithFlash(redirectUrl, { toast }, init, session);
     },
+    replaceWithToast: (replaceUrl: string, toast: ToastMessage, init?: ResponseInit) => {
+      return replaceWithFlash(replaceUrl, { toast }, init, session);
+    },
     redirectWithSuccess: redirectWithToastFactory({ type: "success", session }),
     redirectWithError: redirectWithToastFactory({ type: "error", session }),
     redirectWithInfo: redirectWithToastFactory({ type: "info", session }),
     redirectWithWarning: redirectWithToastFactory({ type: "warning", session }),
+    replaceWithSuccess: replaceWithToastFactory({ type: "success", session }),
+    replaceWithError: replaceWithToastFactory({ type: "error", session }),
+    replaceWithInfo: replaceWithToastFactory({ type: "info", session }),
+    replaceWithWarning: replaceWithToastFactory({ type: "warning", session }),
     getToast: (request: Request) => getToast(request, session),
   };
 };
@@ -211,6 +242,24 @@ export const redirectWithToast = (
   return redirectWithFlash(redirectUrl, { toast }, init, customSession);
 };
 
+/**
+ * Helper method used to replace the current route with a toast notification
+ *
+ * If thrown it needs to be awaited
+ * @param replaceUrl Replace URL
+ * @param toast Toast message and it's type
+ * @param init Additional response options (status code, additional headers etc)
+ * @returns Returns replace response with toast cookie set
+ */
+export const replaceWithToast = (
+  replaceUrl: string,
+  toast: ToastMessage,
+  init?: ResponseInit,
+  customSession?: SessionStorage,
+) => {
+  return replaceWithFlash(replaceUrl, { toast }, init, customSession);
+};
+
 /**
  * Helper method used to redirect the user to a new page with an error toast notification
  *
@@ -222,6 +271,17 @@ export const redirectWithToast = (
  */
 export const redirectWithError = redirectWithToastFactory({ type: "error" });
 
+/**
+ * Helper method used to replace the current route with an error toast notification
+ *
+ * If this method is thrown it needs to be awaited, otherwise it can just be returned
+ * @param replaceUrl Replace url
+ * @param message Message to be shown as info
+ * @param init Additional response options (status code, additional headers etc)
+ * @returns Returns replace response with toast cookie set
+ */
+export const replaceWithError = replaceWithToastFactory({ type: "error" });
+
 /**
  * Helper method used to redirect the user to a new page with a success toast notification
  *
@@ -233,6 +293,17 @@ export const redirectWithError = redirectWithToastFactory({ type: "error" });
  */
 export const redirectWithSuccess = redirectWithToastFactory({ type: "success" });
 
+/**
+ * Helper method used to replace the current route with a success toast notification
+ *
+ * If this method is thrown it needs to be awaited, otherwise it can just be returned
+ * @param replaceUrl Replace url
+ * @param message Message to be shown as info
+ * @param init Additional response options (status code, additional headers etc)
+ * @returns Returns replace response with toast cookie set
+ */
+export const replaceWithSuccess = replaceWithToastFactory({ type: "success" });
+
 /**
  * Helper method used to redirect the user to a new page with a warning toast notification
  *
@@ -244,6 +315,17 @@ export const redirectWithSuccess = redirectWithToastFactory({ type: "success" })
  */
 export const redirectWithWarning = redirectWithToastFactory({ type: "warning" });
 
+/**
+ * Helper method used to replace the current route with a warning toast notification
+ *
+ * If this method is thrown it needs to be awaited, otherwise it can just be returned
+ * @param replaceUrl Replace url
+ * @param message Message to be shown as info
+ * @param init Additional response options (status code, additional headers etc)
+ * @returns Returns replace response with toast cookie set
+ */
+export const replaceWithWarning = replaceWithToastFactory({ type: "warning" });
+
 /**
  * Helper method used to redirect the user to a new page with a info toast notification
  *
@@ -254,3 +336,14 @@ export const redirectWithWarning = redirectWithToastFactory({ type: "warning" })
  * @returns Returns redirect response with toast cookie set
  */
 export const redirectWithInfo = redirectWithToastFactory({ type: "info" });
+
+/**
+ * Helper method used to replace the current route with an info toast notification
+ *
+ * If this method is thrown it needs to be awaited, otherwise it can just be returned
+ * @param replaceUrl Replace url
+ * @param message Message to be shown as info
+ * @param init Additional response options (status code, additional headers etc)
+ * @returns Returns replace response with toast cookie set
+ */
+export const replaceWithInfo = replaceWithToastFactory({ type: "info" });

tsconfig.json

@@ -103,5 +103,13 @@
     // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
     "skipLibCheck": true /* Skip type checking all .d.ts files. */
   },
-  "exclude": ["./bin/**/*.test.ts", "./dist/**/*", "./bin/mocks/**/*", "./*.config.ts", "test-apps/**"]
+  "exclude": [
+    "./bin/**/*.test.ts",
+    "./dist/**/*",
+    "./bin/mocks/**/*",
+    "./*.config.ts",
+    "test-apps/**",
+    "**/*.test.ts",
+    "**/*.test.tsx"
+  ]
 }