@carlonicora/nextjs-jsonapi 3.28.1 → 4.0.0

package/src/server/__tests__/request.test.ts

@@ -1,7 +1,23 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const cachedGet = vi.hoisted(() => ({ cachedServerGet: vi.fn() }));
+
+vi.mock("../cachedGet", async () => {
+  const actual = await vi.importActual<typeof import("../cachedGet")>("../cachedGet");
+  return { ...actual, cachedServerGet: cachedGet.cachedServerGet };
+});
+
 import { serverRequest } from "../request";
 
+function okResponse(body: unknown) {
+  return { ok: true, status: 200, statusText: "OK", json: async () => body };
+}
+
 describe("serverRequest", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
   afterEach(() => {
     vi.unstubAllGlobals();
   });
@@ -14,4 +30,83 @@ describe("serverRequest", () => {
     expect(response.ok).toBe(false);
     expect(response.status).toBe(503);
   });
+
+  it("routes a cached GET to cachedServerGet", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const cached = { data: { data: [] }, ok: true, status: 200, statusText: "OK" };
+    cachedGet.cachedServerGet.mockResolvedValue(cached);
+
+    const response = await serverRequest({
+      method: "GET",
+      url: "http://api.test/help",
+      token: "secret-token",
+      cache: "help",
+      companyId: "company-1",
+      language: "en",
+      additionalHeaders: { "x-extra": "1" },
+    });
+
+    expect(response).toEqual(cached);
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(cachedGet.cachedServerGet).toHaveBeenCalledWith({
+      url: "http://api.test/help",
+      cache: "help",
+      companyId: "company-1",
+      language: "en",
+      additionalHeaders: { "x-extra": "1" },
+    });
+    expect(JSON.stringify(cachedGet.cachedServerGet.mock.calls[0])).not.toContain("secret-token");
+  });
+
+  it("sends POST uncached even when cache is set", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(okResponse({ data: {} }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await serverRequest({
+      method: "POST",
+      url: "http://api.test/help",
+      token: "secret-token",
+      cache: "help",
+      body: { a: 1 },
+      language: "en",
+    });
+
+    expect(cachedGet.cachedServerGet).not.toHaveBeenCalled();
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init).not.toHaveProperty("next");
+    expect(init.method).toBe("POST");
+    expect(init.headers.Authorization).toBe("Bearer secret-token");
+  });
+
+  it("sends uncached GET with no next options", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(okResponse({ data: {} }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await serverRequest({ method: "GET", url: "http://api.test/users", token: "secret-token", language: "en" });
+
+    expect(cachedGet.cachedServerGet).not.toHaveBeenCalled();
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init).not.toHaveProperty("next");
+    expect(init.headers.Authorization).toBe("Bearer secret-token");
+  });
+
+  it("reads the status back from the digest", async () => {
+    cachedGet.cachedServerGet.mockRejectedValue({ digest: "HTTP_500" });
+
+    const response = await serverRequest({ method: "GET", url: "http://api.test/help", cache: "help", language: "en" });
+
+    expect(response.ok).toBe(false);
+    expect(response.status).toBe(500);
+    expect(response.data).toBeUndefined();
+  });
+
+  it("falls back to 503 when the digest carries no status", async () => {
+    cachedGet.cachedServerGet.mockRejectedValue(Object.assign(new Error("sanitised"), { digest: "2916868796" }));
+
+    const response = await serverRequest({ method: "GET", url: "http://api.test/help", cache: "help", language: "en" });
+
+    expect(response.ok).toBe(false);
+    expect(response.status).toBe(503);
+  });
 });

package/src/server/cache.ts

@@ -1,15 +1,22 @@
 // Server-only utilities (NOT server actions - these cannot be called from client components)
 
-import { revalidateTag } from "next/cache";
+import { revalidateTag, updateTag } from "next/cache";
 
-export type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
+import type { CacheProfile } from "./cacheProfiles";
+
+export { CACHE_PROFILES, type CacheProfile } from "./cacheProfiles";
 
 /**
  * Revalidate a cache tag to invalidate cached data.
  * Next.js 16+ requires a profile parameter.
  *
+ * With `"max"` the tagged entries are marked stale and served stale-while-revalidate
+ * (a one-year window): the next request still gets the old data while fresh data loads
+ * in the background. It is not an immediate invalidation. A Server Action that must
+ * read its own write uses `updateCacheTag` instead.
+ *
  * @param tag - The cache tag to invalidate
- * @param profile - The cache profile (defaults to "max" for immediate invalidation)
+ * @param profile - The cache profile whose `expire` bounds how long stale data may be served (defaults to "max")
  */
 export async function invalidateCacheTag(tag: string, profile: CacheProfile = "max"): Promise<void> {
   revalidateTag(tag, profile);
@@ -19,10 +26,20 @@ export async function invalidateCacheTag(tag: string, profile: CacheProfile = "m
  * Revalidate multiple cache tags.
  *
  * @param tags - Array of cache tags to invalidate
- * @param profile - The cache profile (defaults to "max" for immediate invalidation)
+ * @param profile - The cache profile, see `invalidateCacheTag` (defaults to "max", stale-while-revalidate)
  */
 export async function invalidateCacheTags(tags: string[], profile: CacheProfile = "max"): Promise<void> {
   for (const tag of tags) {
     revalidateTag(tag, profile);
   }
 }
+
+/**
+ * Expire a cache tag immediately, so the same request reads fresh data (read-your-own-writes).
+ * Wraps `updateTag`, which works in Server Actions only. Route Handlers use `invalidateCacheTag`.
+ *
+ * @param tag - The cache tag to expire
+ */
+export async function updateCacheTag(tag: string): Promise<void> {
+  updateTag(tag);
+}

package/src/server/cacheDigest.ts

@@ -0,0 +1,10 @@
+// Shared by `cachedGet.ts` and its client stub, so `serverRequest` reads the status
+// back the same way whichever one the bundler resolved.
+
+/** Reads the HTTP status from an `HTTP_<status>` digest, or `undefined` when there is none. */
+export function statusFromDigest(error: unknown): number | undefined {
+  const digest = (error as { digest?: unknown } | null | undefined)?.digest;
+  if (typeof digest !== "string") return undefined;
+  const match = /^HTTP_(\d+)$/.exec(digest);
+  return match ? Number(match[1]) : undefined;
+}

package/src/server/cacheProfiles.ts

@@ -0,0 +1,15 @@
+// Plain constants, no `next/cache` import: `cachedGet.ts` reads them, and this file
+// keeps `revalidateTag`/`updateTag` (in `cache.ts`) out of every graph that loads it.
+
+export type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
+
+/** The built-in `cacheLife` profile names. A module `cache` value outside this list is treated as a tag. */
+export const CACHE_PROFILES: readonly CacheProfile[] = [
+  "seconds",
+  "minutes",
+  "hours",
+  "days",
+  "weeks",
+  "max",
+  "default",
+];

package/src/server/cachedGet.stub.ts

@@ -0,0 +1,15 @@
+// What `@carlonicora/nextjs-jsonapi/cached-get` resolves to outside the `react-server`
+// condition (client components, their SSR pass). The shared request code reaches
+// `serverRequest` from client hooks too, and Next rejects `"use cache"` and
+// `cacheLife`/`cacheTag` in those bundles. Nothing there calls the cached path: it
+// only runs on the server, where the real `cachedGet.ts` is resolved instead.
+
+import type { ApiData } from "../core/interfaces/ApiData";
+import type { CachedGetParams } from "./cachedGet";
+
+export { statusFromDigest } from "./cacheDigest";
+export type { CachedGetParams } from "./cachedGet";
+
+export async function cachedServerGet(_params: CachedGetParams): Promise<ApiData> {
+  throw new Error("cachedServerGet is server-only: it was resolved outside the react-server condition");
+}

package/src/server/cachedGet.ts

@@ -0,0 +1,80 @@
+// Server-only utilities (NOT server actions - these cannot be called from client components)
+//
+// Reached through `@carlonicora/nextjs-jsonapi/cached-get` under the `react-server`
+// condition only; every other bundle gets `cachedGet.stub.ts` (see package.json).
+
+import { cacheLife, cacheTag } from "next/cache";
+import { ApiData } from "../core/interfaces/ApiData";
+import { CACHE_PROFILES, CacheProfile } from "./cacheProfiles";
+
+export { statusFromDigest } from "./cacheDigest";
+
+export interface CachedGetParams {
+  url: string;
+  /** A cacheLife profile name, or a tag. */
+  cache: string;
+  language: string;
+  companyId?: string;
+  additionalHeaders?: Record<string, string>;
+}
+
+function httpError(status: number, statusText: string): Error {
+  return Object.assign(new Error(statusText), { status, digest: `HTTP_${status}` });
+}
+
+/**
+ * Token-free cached GET for shared data.
+ *
+ * The arguments are the cache key, so they never carry a token, a cookie value
+ * or a user id. The request is sent without `Authorization`: an endpoint that
+ * needs a token is per-user and must not set `cache`.
+ *
+ * A non-OK response or an unreachable API throws, so Next does not store the
+ * entry. The status travels in `error.digest` as `HTTP_<status>` (503 when the
+ * API is unreachable), because `digest` is the only property that survives
+ * into production. Read it back with `statusFromDigest`.
+ */
+export async function cachedServerGet(params: CachedGetParams): Promise<ApiData> {
+  "use cache";
+
+  if (CACHE_PROFILES.includes(params.cache as CacheProfile)) {
+    cacheLife(params.cache as CacheProfile);
+  } else {
+    cacheTag(params.cache);
+    cacheLife("max");
+  }
+
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    ...params.additionalHeaders,
+    "x-language": params.language,
+  };
+  if (params.companyId) {
+    headers["x-companyid"] = params.companyId;
+  }
+
+  let apiResponse: Response;
+  try {
+    apiResponse = await fetch(params.url, { method: "GET", headers });
+  } catch {
+    throw httpError(503, "Service Unavailable");
+  }
+
+  if (!apiResponse.ok) {
+    throw httpError(apiResponse.status, apiResponse.statusText);
+  }
+
+  let data: any;
+  try {
+    data = await apiResponse.json();
+  } catch {
+    data = undefined;
+  }
+
+  return {
+    data,
+    ok: apiResponse.ok,
+    status: apiResponse.status,
+    statusText: apiResponse.statusText,
+  };
+}

package/src/server/request.ts

@@ -1,6 +1,10 @@
 // Server-only utilities (NOT server actions - these cannot be called from client components)
 
 import { ApiData } from "../core/interfaces/ApiData";
+// Through the package's own export, not "./cachedGet": the `react-server` condition gives
+// server code the real `"use cache"` function and every other bundle a stub. A relative
+// import would put `"use cache"` into the client bundles that reach this module.
+import { cachedServerGet, statusFromDigest } from "@carlonicora/nextjs-jsonapi/cached-get";
 
 export interface ServerRequestParams {
   method: string;
@@ -14,22 +18,37 @@ export interface ServerRequestParams {
   additionalHeaders?: Record<string, string>;
 }
 
-// Map cache configuration names to revalidation times in seconds
-const cacheLifeToSeconds: Record<string, number> = {
-  seconds: 1,
-  minutes: 60,
-  hours: 3600,
-  days: 86400,
-  weeks: 604800,
-  max: 31536000, // 1 year
-  default: 60,
-};
-
 /**
- * Server-side request with Next.js caching support.
- * Uses fetch's native caching options for Next.js compatibility.
+ * Server-side request.
+ *
+ * - A GET with a `cache` value goes through `cachedServerGet`, a token-free `"use cache"`
+ *   function. The token is never sent on that path.
+ * - Everything else (uncached GET, POST, PUT, PATCH, DELETE) is a plain uncached `fetch`
+ *   that sends the token.
  */
 export async function serverRequest(params: ServerRequestParams): Promise<ApiData> {
+  if (params.method === "GET" && params.cache) {
+    try {
+      return await cachedServerGet({
+        url: params.url,
+        cache: params.cache,
+        language: params.language,
+        companyId: params.companyId,
+        additionalHeaders: params.additionalHeaders,
+      });
+    } catch (error) {
+      // The cached function throws on failure so Next does not store it. Convert it back
+      // here, outside the cache scope. In production only `digest` survives the boundary.
+      const status = statusFromDigest(error) ?? 503;
+      return {
+        data: undefined,
+        ok: false,
+        status,
+        statusText: status === 503 ? "Service Unavailable" : "",
+      };
+    }
+  }
+
   const response: ApiData = {
     data: undefined,
     ok: false,
@@ -75,27 +94,9 @@ export async function serverRequest(params: ServerRequestParams): Promise<ApiDat
     additionalHeaders["Content-Type"] = "application/json";
   }
 
-  // Build Next.js fetch caching options
-  const nextOptions: { revalidate?: number; tags?: string[] } = {};
-
-  if (params.cache) {
-    // Check if it's a predefined cache life name
-    if (params.cache in cacheLifeToSeconds) {
-      nextOptions.revalidate = cacheLifeToSeconds[params.cache];
-    } else {
-      // Treat as a cache tag
-      nextOptions.tags = [params.cache];
-      nextOptions.revalidate = 60; // Default revalidation time for tagged caches
-    }
-  } else {
-    // Default to short caching
-    nextOptions.revalidate = 0;
-  }
-
-  const options: RequestInit & { next?: { revalidate?: number; tags?: string[] } } = {
+  const options: RequestInit = {
     method: params.method,
     headers: { Accept: "application/json", ...additionalHeaders },
-    next: nextOptions,
   };
 
   if (requestBody !== undefined) {

package/src/shadcnui/ui/__tests__/sidebar.menu-skeleton.test.tsx

@@ -0,0 +1,50 @@
+import { render } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SidebarMenuSkeleton } from "../sidebar";
+
+function widths(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('[data-sidebar="menu-skeleton-text"]')).map((el) =>
+    el.style.getPropertyValue("--skeleton-width"),
+  );
+}
+
+describe("SidebarMenuSkeleton", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("never calls Math.random, so it can sit inside a prerendered shell", () => {
+    const random = vi.spyOn(Math, "random");
+    render(<SidebarMenuSkeleton showIcon />);
+    expect(random).not.toHaveBeenCalled();
+  });
+
+  it("gives every row a width between 50% and 89%", () => {
+    const { container } = render(
+      <>
+        {Array.from({ length: 8 }, (_, index) => (
+          <SidebarMenuSkeleton key={index} />
+        ))}
+      </>,
+    );
+    const values = widths(container);
+    expect(values).toHaveLength(8);
+    for (const value of values) {
+      const percent = Number(value.replace("%", ""));
+      expect(percent).toBeGreaterThanOrEqual(50);
+      expect(percent).toBeLessThan(90);
+    }
+  });
+
+  it("renders the same widths on every server render of the same tree, so hydration matches", () => {
+    const tree = (
+      <>
+        <SidebarMenuSkeleton />
+        <SidebarMenuSkeleton />
+        <SidebarMenuSkeleton />
+      </>
+    );
+    expect(renderToString(tree)).toEqual(renderToString(tree));
+  });
+});

package/src/shadcnui/ui/__tests__/sidebar.session.test.tsx

@@ -0,0 +1,133 @@
+import { act, render, screen } from "@testing-library/react";
+import * as React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionSnapshot } from "../../../server/ServerSession";
+import { SidebarProvider, useSidebar, useSidebarControls } from "../sidebar";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+function snapshot(overrides: Partial<SessionSnapshot> = {}): SessionSnapshot {
+  return { isLogged: true, isAdministrator: false, sidebarOpen: true, isMobile: false, ...overrides };
+}
+
+function MobileReader() {
+  const { isMobile } = useSidebar();
+  return <p>{isMobile ? "mobile" : "desktop"}</p>;
+}
+
+let setOpenRef: ((open: boolean) => void) | undefined;
+function StateReader() {
+  const { state, setOpen } = useSidebar();
+  setOpenRef = setOpen;
+  return <p data-testid="state">{state}</p>;
+}
+
+describe("SidebarProvider with a session", () => {
+  beforeEach(() => {
+    setOpenRef = undefined;
+    // The legacy useIsMobile path measures the viewport; jsdom has no matchMedia.
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => ({ matches: false, addEventListener: vi.fn(), removeEventListener: vi.fn() })),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("renders children before the session resolves", () => {
+    const pending = new Promise<SessionSnapshot>(() => {});
+    render(
+      <SidebarProvider session={pending}>
+        <p>child</p>
+      </SidebarProvider>,
+    );
+    expect(screen.getByText("child")).toBeInTheDocument();
+  });
+
+  it("useSidebarControls never suspends while the session is pending", () => {
+    const pending = new Promise<SessionSnapshot>(() => {});
+    function ControlsReader() {
+      const { state, toggleSidebar } = useSidebarControls();
+      return <p>{typeof toggleSidebar === "function" ? state : "missing"}</p>;
+    }
+    // No Suspense boundary: a suspension here would throw out of render.
+    render(
+      <SidebarProvider session={pending}>
+        <ControlsReader />
+      </SidebarProvider>,
+    );
+    expect(screen.getByText("expanded")).toBeInTheDocument();
+  });
+
+  it("useSidebar().isMobile suspends in the consumer and resolves", async () => {
+    const session = deferred<SessionSnapshot>();
+    // An async act around the suspending render lets React schedule the retry
+    // when the promise resolves; a plain render() never re-renders the reader.
+    await act(async () => {
+      render(
+        <SidebarProvider session={session.promise}>
+          <React.Suspense fallback="waiting">
+            <MobileReader />
+          </React.Suspense>
+        </SidebarProvider>,
+      );
+    });
+    expect(screen.getByText("waiting")).toBeInTheDocument();
+
+    await act(async () => {
+      session.resolve(snapshot({ isMobile: true, sidebarOpen: true }));
+    });
+
+    expect(screen.getByText("mobile")).toBeInTheDocument();
+  });
+
+  it("applies sidebarOpen from the session once", async () => {
+    const session = deferred<SessionSnapshot>();
+    // useSidebar() unwraps isMobile, so every consumer sits behind a boundary.
+    const ui = (
+      <SidebarProvider session={session.promise}>
+        <React.Suspense fallback="waiting">
+          <StateReader />
+        </React.Suspense>
+      </SidebarProvider>
+    );
+    let rerender!: ReturnType<typeof render>["rerender"];
+    await act(async () => {
+      ({ rerender } = render(ui));
+    });
+    expect(screen.getByText("waiting")).toBeInTheDocument();
+
+    await act(async () => {
+      session.resolve(snapshot({ sidebarOpen: false }));
+    });
+    expect(screen.getByTestId("state").textContent).toBe("collapsed");
+
+    act(() => {
+      setOpenRef!(true);
+    });
+    expect(screen.getByTestId("state").textContent).toBe("expanded");
+
+    rerender(ui);
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(screen.getByTestId("state").textContent).toBe("expanded");
+  });
+
+  it("defaultOpen still works without a session", () => {
+    render(
+      <SidebarProvider defaultOpen={false}>
+        <StateReader />
+      </SidebarProvider>,
+    );
+    expect(screen.getByTestId("state").textContent).toBe("collapsed");
+  });
+});