@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.0

package/src/contexts/__tests__/SocketContext.session.spec.tsx

@@ -1,9 +1,9 @@
 import { act, render, screen } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { SessionSnapshot } from "../../server/ServerSession";
 
 const { useSocketMock } = vi.hoisted(() => ({
-  useSocketMock: vi.fn((_options: { token?: string }) => ({
+  useSocketMock: vi.fn((_options: { token?: string; paused?: boolean }) => ({
     socket: null,
     isConnected: false,
     messages: [],
@@ -18,6 +18,9 @@ const { useSocketMock } = vi.hoisted(() => ({
 
 vi.mock("../../hooks/useSocket", () => ({ useSocket: useSocketMock }));
 
+import { configureOffline, resetOfflineConfig } from "../../offline/config";
+import { resetOfflineState, setOfflineState } from "../../offline/state";
+import type { OfflineConfig } from "../../offline/types";
 import { SocketProvider } from "../SocketContext";
 
 function deferred<T>() {
@@ -49,7 +52,7 @@ describe("SocketProvider with a session", () => {
       </SocketProvider>,
     );
     expect(screen.getByText("child")).toBeInTheDocument();
-    expect(useSocketMock).toHaveBeenLastCalledWith({ token: undefined });
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: undefined, paused: false });
   });
 
   it("connects with the token once the session resolves", async () => {
@@ -63,7 +66,7 @@ describe("SocketProvider with a session", () => {
       pending.resolve(snapshot("t1"));
       await pending.promise;
     });
-    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t1" });
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t1", paused: false });
   });
 
   it("still accepts a plain token", () => {
@@ -72,6 +75,50 @@ describe("SocketProvider with a session", () => {
         <span>child</span>
       </SocketProvider>,
     );
-    expect(useSocketMock.mock.calls[0][0]).toEqual({ token: "t2" });
+    expect(useSocketMock.mock.calls[0][0]).toEqual({ token: "t2", paused: false });
+  });
+});
+
+describe("SocketProvider and offline mode", () => {
+  const offlineConfig = {
+    getUserId: () => "u1",
+    rootModule: { name: "roots" },
+    types: [],
+    routes: [],
+    listSyncRoots: async () => [],
+    shellPath: () => "/offline-shell",
+    syncIntervalMs: 300000,
+  } as unknown as OfflineConfig;
+
+  afterEach(() => {
+    resetOfflineConfig();
+    resetOfflineState();
+  });
+
+  it("with offline mode configured, pauses the socket while the session is offline and resumes it when back online", () => {
+    configureOffline(offlineConfig);
+    setOfflineState({ online: true });
+    render(
+      <SocketProvider token="t3">
+        <span>child</span>
+      </SocketProvider>,
+    );
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t3", paused: false });
+
+    act(() => setOfflineState({ online: false }));
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t3", paused: true });
+
+    act(() => setOfflineState({ online: true }));
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t3", paused: false });
+  });
+
+  it("without offline mode configured, never pauses the socket", () => {
+    setOfflineState({ online: false });
+    render(
+      <SocketProvider token="t4">
+        <span>child</span>
+      </SocketProvider>,
+    );
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t4", paused: false });
   });
 });

package/src/core/factories/RehydrationFactory.ts

@@ -3,6 +3,30 @@ import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInt
 import { JsonApiHydratedDataInterface } from "../interfaces/JsonApiHydratedDataInterface";
 import { DataClassRegistry } from "../registry/DataClassRegistry";
 
+/**
+ * The resources being rehydrated right now, along the current chain of relationships. A resource
+ * met again inside its own chain (A's relationship leads to B, B's back to A) is a circle in the
+ * `included` data: following it would recurse until the stack overflows, so it is skipped there.
+ */
+const inProgress = new Set<string>();
+
+const keyOf = (data: JsonApiHydratedDataInterface): string | undefined => {
+  const resource = data?.jsonApi;
+  return resource?.type && resource?.id ? `${resource.type}:${resource.id}` : undefined;
+};
+
+function guarded<T>(data: JsonApiHydratedDataInterface, run: () => T): T {
+  const key = keyOf(data);
+  if (!key) return run();
+  if (inProgress.has(key)) return undefined as T;
+  inProgress.add(key);
+  try {
+    return run();
+  } finally {
+    inProgress.delete(key);
+  }
+}
+
 export class RehydrationFactory {
   public static rehydrate<T extends ApiDataInterface>(
     classKey: ApiRequestDataTypeInterface,
@@ -10,8 +34,7 @@ export class RehydrationFactory {
   ): T {
     const factoryClass = DataClassRegistry.get(classKey);
 
-    const instance = new factoryClass();
-    return instance.rehydrate(data) as T;
+    return guarded(data, () => new factoryClass().rehydrate(data) as T);
   }
 
   public static rehydrateList<T extends ApiDataInterface>(
@@ -20,11 +43,8 @@ export class RehydrationFactory {
   ): T[] {
     const factoryClass = DataClassRegistry.get(classKey);
 
-    const response = data.map((item: JsonApiHydratedDataInterface) => {
-      const instance = new factoryClass();
-      return instance.rehydrate(item) as T;
-    });
-
-    return response;
+    return data.map((item: JsonApiHydratedDataInterface) =>
+      guarded(item, () => new factoryClass().rehydrate(item) as T),
+    );
   }
 }

package/src/core/factories/__tests__/RehydrationFactory.spec.ts

@@ -149,4 +149,37 @@ describe("RehydrationFactory", () => {
       expect(results[0]).not.toBe(results[1]);
     });
   });
+
+  describe("circular included data", () => {
+    // A model that reads its "other" relationship from included, as AbstractApiData models do.
+    class Linked implements Partial<ApiDataInterface> {
+      id = "";
+      other?: Linked;
+      rehydrate(data: JsonApiHydratedDataInterface) {
+        this.id = data.jsonApi.id;
+        const ref = data.jsonApi.relationships?.other?.data;
+        const target = ref && data.included.find((item: any) => item.type === ref.type && item.id === ref.id);
+        if (target)
+          this.other = RehydrationFactory.rehydrate(linkedModule as any, { jsonApi: target, included: data.included });
+        return this;
+      }
+    }
+    const linkedModule = { name: "linked", model: Linked };
+
+    it("a relationship that leads back to a resource already being rehydrated is skipped, not followed forever", () => {
+      DataClassRegistry.registerObjectClass(linkedModule as any, Linked as any);
+      const a = { type: "linked", id: "a", relationships: { other: { data: { type: "linked", id: "b" } } } };
+      const b = { type: "linked", id: "b", relationships: { other: { data: { type: "linked", id: "a" } } } };
+
+      const result = RehydrationFactory.rehydrate<any>(linkedModule as any, { jsonApi: a, included: [a, b] });
+
+      expect(result.id).toBe("a");
+      expect(result.other.id).toBe("b");
+      expect(result.other.other).toBeUndefined();
+      // The guard is per chain: the same resource rehydrates again in a new call.
+      expect(RehydrationFactory.rehydrate<any>(linkedModule as any, { jsonApi: b, included: [a, b] }).other.id).toBe(
+        "a",
+      );
+    });
+  });
 });

package/src/core/index.ts

@@ -131,6 +131,9 @@ export * from "../features/referral/referral.module";
 export * from "../features/referral/referral-stats.module";
 export * from "../features/referral/referral-admin.modules";
 export * from "../features/referral/interfaces/referral-admin.interface";
+// Offline mode models and their module bundle (opt-in): exported from core so a
+// bootstrapper can spread offlineModules without loading the ./offline entry.
+export * from "../offline/sync/models";
 // Administrative token-usage reporting modules. Exported from core (not only
 // from the client-marked ./tokenusage barrel) so a consuming app can register
 // them in its bootstrapper without pulling the feature's client bundle —

package/src/core/interfaces/ApiData.ts

@@ -5,4 +5,6 @@ export type ApiData = {
   statusText: string;
   token?: string;
   refreshToken?: string;
+  /** Set by `directFetch` when the API could not be reached at all (the 503 it reports). */
+  networkError?: boolean;
 };

package/src/core/registry/ModuleRegistry.ts

@@ -107,6 +107,9 @@ export interface FoundationModuleDefinitions {
   AnalyticsPageView: ModuleWithPermissions;
   // Account deletion (opt-in: registered only by apps that enable it)
   AccountDeletion: ModuleWithPermissions;
+  // Offline mode (opt-in: registered by apps that spread offlineModules)
+  OfflineChangeSet: ModuleWithPermissions;
+  RootSync: ModuleWithPermissions;
 }
 
 // App-specific modules - apps will augment this interface ONLY

package/src/features/auth/components/forms/Logout.tsx

@@ -12,13 +12,20 @@ interface LogoutProps {
    * library's own `user` key is always cleared and does not need listing.
    */
   storageKeys?: string[];
+  /**
+   * Awaited before anything is cleared (offline mode: warn about changes that
+   * were not sent, then drop the device copy). Returning `false` cancels the
+   * logout: storage, cookies and the current page are left as they are.
+   */
+  beforeLogout?: () => Promise<boolean>;
 }
 
-export function Logout({ storageKeys }: LogoutProps) {
+export function Logout({ storageKeys, beforeLogout }: LogoutProps) {
   const generateUrl = usePageUrlGenerator();
 
   useEffect(() => {
     const logOut = async () => {
+      if (beforeLogout && !(await beforeLogout())) return;
       // `CurrentUserProvider` persists the user in localStorage, so clearing the
       // cookies alone leaves the client believing the session is still alive:
       // the server renders as anonymous while every `useCurrentUserContext()`

package/src/features/auth/components/forms/__tests__/Logout.spec.tsx

@@ -120,4 +120,66 @@ describe("Logout", () => {
       });
     });
   });
+
+  // Offline mode: the app may hold unsent changes on the device, so it gets a
+  // chance to warn (or cancel) before anything is cleared.
+  describe("Scenario: beforeLogout hook", () => {
+    it("awaits beforeLogout and stops when it returns false", async () => {
+      let resolveHook: (value: boolean) => void = () => {};
+      const beforeLogout = vi.fn(
+        () =>
+          new Promise<boolean>((resolve) => {
+            resolveHook = resolve;
+          }),
+      );
+
+      render(<Logout beforeLogout={beforeLogout} />);
+
+      await waitFor(() => {
+        expect(beforeLogout).toHaveBeenCalledTimes(1);
+      });
+      expect(clearClientStorage).not.toHaveBeenCalled();
+      expect(AuthService.logout).not.toHaveBeenCalled();
+
+      resolveHook(false);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(clearClientStorage).not.toHaveBeenCalled();
+      expect(AuthService.logout).not.toHaveBeenCalled();
+      expect(windowLocationHref).toBe("");
+    });
+
+    it("clears storage and logs out when it returns true or is absent", async () => {
+      const callOrder: string[] = [];
+      const beforeLogout = vi.fn(async () => {
+        callOrder.push("beforeLogout");
+        return true;
+      });
+      vi.mocked(clearClientStorage).mockImplementation(() => {
+        callOrder.push("clearClientStorage");
+      });
+      vi.mocked(AuthService.logout).mockImplementation(async () => {
+        callOrder.push("AuthService.logout");
+      });
+
+      const { unmount } = render(<Logout beforeLogout={beforeLogout} storageKeys={["person"]} />);
+
+      await waitFor(() => {
+        expect(windowLocationHref).toBe("/");
+      });
+      expect(callOrder).toEqual(["beforeLogout", "clearClientStorage", "AuthService.logout"]);
+      expect(clearClientStorage).toHaveBeenCalledWith([CURRENT_USER_STORAGE_KEY, "person"]);
+      unmount();
+
+      vi.clearAllMocks();
+      windowLocationHref = "";
+      render(<Logout />);
+
+      await waitFor(() => {
+        expect(windowLocationHref).toBe("/");
+      });
+      expect(clearClientStorage).toHaveBeenCalledWith([CURRENT_USER_STORAGE_KEY]);
+      expect(AuthService.logout).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/hooks/__tests__/useSocket.pause.spec.ts

@@ -0,0 +1,39 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+const { io, fakeSocket } = vi.hoisted(() => {
+  const fakeSocket = {
+    id: undefined,
+    connected: true,
+    on: vi.fn(),
+    off: vi.fn(),
+    emit: vi.fn(),
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    removeAllListeners: vi.fn(),
+  };
+  return { fakeSocket, io: vi.fn(() => fakeSocket) };
+});
+vi.mock("socket.io-client", () => ({ default: io }));
+
+import { useSocket } from "../useSocket";
+
+describe("useSocket pause (offline mode)", () => {
+  it("disconnects while paused and connects the same socket again when resumed", () => {
+    const { rerender } = renderHook(({ paused }) => useSocket({ token: "t1", paused }), {
+      initialProps: { paused: false },
+    });
+    expect(io).toHaveBeenCalledTimes(1);
+    expect(fakeSocket.disconnect).not.toHaveBeenCalled();
+
+    rerender({ paused: true });
+    expect(fakeSocket.disconnect).toHaveBeenCalledTimes(1);
+    rerender({ paused: true });
+    expect(fakeSocket.disconnect).toHaveBeenCalledTimes(1);
+    expect(fakeSocket.connect).not.toHaveBeenCalled();
+
+    rerender({ paused: false });
+    expect(fakeSocket.connect).toHaveBeenCalledTimes(1);
+    expect(io).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useSocket.ts

@@ -10,6 +10,8 @@ type Socket = ReturnType<typeof io>;
 
 interface UseSocketOptions {
   token: string;
+  /** While true the socket is disconnected (no reconnect attempts); false connects it again. */
+  paused?: boolean;
 }
 
 interface SocketLike {
@@ -31,7 +33,7 @@ interface UseSocketReturn {
   clearSocketNotifications: () => void;
 }
 
-export function useSocket({ token }: UseSocketOptions): UseSocketReturn {
+export function useSocket({ token, paused = false }: UseSocketOptions): UseSocketReturn {
   const _errorCount = useRef(0);
   const shouldConnect = useRef(true);
 
@@ -168,6 +170,23 @@ export function useSocket({ token }: UseSocketOptions): UseSocketReturn {
     };
   }, [token]);
 
+  // Paused (offline mode, the session is offline): a manual disconnect stops socket.io retrying;
+  // resuming connects the same socket again.
+  const pausedSocket = useRef<Socket | null>(null);
+  useEffect(() => {
+    const current = socketRef.current;
+    if (!current) return;
+    if (paused) {
+      if (pausedSocket.current !== current) {
+        current.disconnect();
+        pausedSocket.current = current;
+      }
+    } else if (pausedSocket.current === current) {
+      pausedSocket.current = null;
+      current.connect();
+    }
+  }, [paused, socket]);
+
   const sendMessage = (event: string, data: any) => {
     if (socketRef.current && isConnected) {
       socketRef.current.emit(event, data);

package/src/offline/__tests__/answer-builders.spec.ts

@@ -0,0 +1,176 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import * as offline from "../index";
+import {
+  errorAnswer,
+  mergeResource,
+  orderedListAnswer,
+  resourceFromDocument,
+  resourceListAnswer,
+  singleAnswer,
+} from "../generic-answers";
+import type { DeviceStore } from "../store/DeviceStore";
+import { configureOffline, resetOfflineConfig } from "../config";
+import { offlineConfig, seededStore } from "./offline-fixtures";
+
+describe("answer builders", () => {
+  let store: DeviceStore;
+
+  beforeEach(async () => {
+    store = await seededStore();
+  });
+
+  it("the ./offline entry exports the builders an app's custom answers use", () => {
+    for (const builder of [
+      singleAnswer,
+      errorAnswer,
+      orderedListAnswer,
+      resourceListAnswer,
+      mergeResource,
+      resourceFromDocument,
+    ]) {
+      expect(typeof builder).toBe("function");
+    }
+    expect(offline.singleAnswer).toBe(singleAnswer);
+    expect(offline.errorAnswer).toBe(errorAnswer);
+    expect(offline.orderedListAnswer).toBe(orderedListAnswer);
+    expect(offline.resourceListAnswer).toBe(resourceListAnswer);
+    expect(offline.mergeResource).toBe(mergeResource);
+    expect(offline.resourceFromDocument).toBe(resourceFromDocument);
+  });
+
+  it("errorAnswer answers a JSON:API errors document with that status", () => {
+    expect(errorAnswer(409, "Conflict", "Already taken")).toEqual({
+      status: 409,
+      body: { errors: [{ status: "409", title: "Conflict", detail: "Already taken" }] },
+    });
+  });
+
+  it("singleAnswer answers the stored resource with its included records", async () => {
+    const record = (await store.getRecord("npcs", "n1"))!;
+    const result = await singleAnswer(store, record, 201);
+    expect(result.status).toBe(201);
+    expect(result.body.data).toEqual(record.resource);
+    expect(Array.isArray(result.body.included)).toBe(true);
+  });
+
+  it("included records keep their relationships whole: a root record keeps its owner even when the owner is also linked to the record", async () => {
+    const put = (type: string, id: string, relationships: Record<string, any>) =>
+      store.putRecord({
+        type,
+        id,
+        rootId: "C",
+        resource: { type, id, attributes: {}, relationships },
+        updatedAt: null,
+      });
+    // The npc points at its root record and at the user; the root record points back at the npc and at the user.
+    await put("npcs", "cy-npc", {
+      root: { data: { type: "roots", id: "cy-camp" } },
+      author: { data: { type: "users", id: "cy-user" } },
+    });
+    await put("roots", "cy-camp", {
+      owner: { data: { type: "users", id: "cy-user" } },
+      npcs: { data: [{ type: "npcs", id: "cy-npc" }] },
+    });
+    await put("users", "cy-user", { company: { data: { type: "companies", id: "cy-co" } } });
+    await put("companies", "cy-co", { owner: { data: { type: "users", id: "cy-user" } } });
+
+    const record = (await store.getRecord("npcs", "cy-npc"))!;
+    const included = (await singleAnswer(store, record)).body.included as any[];
+    const byKey = new Map(included.map((resource) => [`${resource.type}:${resource.id}`, resource]));
+
+    expect(byKey.get("roots:cy-camp").relationships.owner.data).toEqual({ type: "users", id: "cy-user" });
+    expect(byKey.get("roots:cy-camp").relationships.npcs.data).toEqual([{ type: "npcs", id: "cy-npc" }]);
+    expect(byKey.get("companies:cy-co").relationships.owner.data).toEqual({ type: "users", id: "cy-user" });
+  });
+
+  it("a relationship to the signed-in user (a root record's owner) resolves from the stored sign-in, though users are not on the device", async () => {
+    configureOffline(offlineConfig());
+    localStorage.setItem(
+      "user",
+      JSON.stringify({
+        jsonApi: {
+          type: "users",
+          id: "u1",
+          attributes: { name: "Carlo" },
+          relationships: { company: { data: { type: "companies", id: "co" } } },
+        },
+      }),
+    );
+    try {
+      await store.putRecord({
+        type: "roots",
+        id: "own-camp",
+        rootId: "own-camp",
+        resource: {
+          type: "roots",
+          id: "own-camp",
+          attributes: {},
+          relationships: { owner: { data: { type: "users", id: "u1" } } },
+        },
+        updatedAt: null,
+      });
+      await store.putRecord({
+        type: "npcs",
+        id: "own-npc",
+        rootId: "own-camp",
+        resource: {
+          type: "npcs",
+          id: "own-npc",
+          attributes: {},
+          relationships: { root: { data: { type: "roots", id: "own-camp" } } },
+        },
+        updatedAt: null,
+      });
+
+      const included = (await singleAnswer(store, (await store.getRecord("npcs", "own-npc"))!)).body.included as any[];
+      const owner = included.find((resource) => resource.type === "users");
+      // Only the signed-in user, with no relationships of its own.
+      expect(owner).toEqual({ type: "users", id: "u1", attributes: { name: "Carlo" }, meta: undefined });
+    } finally {
+      localStorage.removeItem("user");
+      resetOfflineConfig();
+    }
+  });
+
+  it("orderedListAnswer answers the records in the given order, in one page", async () => {
+    const records = await store.listRecords({ type: "npcs" });
+    const reversed = [...records].reverse();
+    const result = await orderedListAnswer(store, reversed);
+    expect(result.status).toBe(200);
+    expect(result.body.data.map((resource: { id: string }) => resource.id)).toEqual(
+      reversed.map((record) => record.id),
+    );
+    expect(result.body.meta).toEqual({ total: reversed.length });
+  });
+
+  it("resourceListAnswer answers resources the device computed, as they are, with nothing included", () => {
+    const resources = [{ type: "searches", id: "a", attributes: { name: "A" } }];
+    expect(resourceListAnswer(resources)).toEqual({ status: 200, body: { data: resources, included: [] } });
+  });
+
+  it("mergeResource writes a document's attributes, relationships and meta over the resource", () => {
+    const before = {
+      type: "npcs",
+      id: "n1",
+      attributes: { name: "Old", age: 3 },
+      relationships: { faction: { data: { type: "factions", id: "f1" } } },
+      meta: { a: 1 },
+    };
+    expect(mergeResource(before, { type: "npcs", id: "n1" }, { attributes: { name: "New" }, meta: { b: 2 } })).toEqual({
+      type: "npcs",
+      id: "n1",
+      attributes: { name: "New", age: 3 },
+      relationships: { faction: { data: { type: "factions", id: "f1" } } },
+      meta: { a: 1, b: 2 },
+    });
+  });
+
+  it("resourceFromDocument keeps the document's attributes, relationships and meta under the given identity", () => {
+    expect(
+      resourceFromDocument(
+        { data: { type: "npcs", id: "x", attributes: { name: "A" }, meta: { m: 1 } } },
+        { type: "npcs", id: "n9" },
+      ),
+    ).toEqual({ type: "npcs", id: "n9", attributes: { name: "A" }, meta: { m: 1 } });
+  });
+});