@carlonicora/nextjs-jsonapi 6.12.1 → 6.13.0

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 } });
+  });
+});

package/src/offline/__tests__/device-switch.spec.ts

@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  configureOffline,
+  DeviceStoreUnavailableError,
+  getOfflineStore,
+  isOfflineConfigured,
+  isOfflineEnabledOnDevice,
+  resetOfflineConfig,
+  setDeviceStoreOpener,
+} from "../config";
+import { turnOffOffline, turnOnOffline } from "../device-switch";
+import { getOfflineState, resetOfflineState, setOfflineState } from "../state";
+import type { DeviceStore, QueueEntry } from "../store/DeviceStore";
+import type { OfflineConfig } from "../types";
+
+const lifecycle = vi.hoisted(() => ({ deleteDeviceStore: vi.fn(), hasUnsentChanges: vi.fn() }));
+vi.mock("../store/lifecycle", () => lifecycle);
+const runtime = vi.hoisted(() => ({ stopOfflineRuntime: vi.fn() }));
+vi.mock("../sync/runtime", () => runtime);
+
+const ENABLED_KEY = "nja-offline-enabled:u1";
+const LAST_SYNC_KEY = "nja-offline-last-sync:u1";
+
+function config(overrides: Partial<OfflineConfig> = {}): OfflineConfig {
+  return {
+    getUserId: () => "u1",
+    rootModule: { name: "roots" } as any,
+    types: [],
+    routes: [],
+    listSyncRoots: async () => [],
+    shellPath: () => "/offline-shell",
+    syncIntervalMs: 300000,
+    ...overrides,
+  };
+}
+
+function storeWithQueue(entries: Partial<QueueEntry>[]): DeviceStore {
+  return { queue: vi.fn(async () => entries as QueueEntry[]) } as unknown as DeviceStore;
+}
+
+describe("offline device switch", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    resetOfflineConfig();
+    resetOfflineState();
+    lifecycle.deleteDeviceStore.mockReset().mockResolvedValue(undefined);
+    lifecycle.hasUnsentChanges.mockReset().mockResolvedValue(false);
+    runtime.stopOfflineRuntime.mockReset();
+    vi.stubGlobal("caches", { keys: vi.fn(async () => ["app-images"]), delete: vi.fn(async () => true) });
+  });
+
+  afterEach(() => {
+    resetOfflineConfig();
+    resetOfflineState();
+    localStorage.clear();
+    vi.unstubAllGlobals();
+  });
+
+  it("without requireOptIn offline mode is on, as before", async () => {
+    configureOffline(config());
+    setDeviceStoreOpener(async () => storeWithQueue([]));
+
+    expect(isOfflineEnabledOnDevice("u1")).toBe(true);
+    expect(isOfflineConfigured()).toBe(true);
+    expect(getOfflineState().enabled).toBe(true);
+    await expect(getOfflineStore()).resolves.toBeDefined();
+  });
+
+  it("with requireOptIn and no stored switch, offline mode is off and the store is refused", async () => {
+    configureOffline(config({ requireOptIn: true }));
+    const opener = vi.fn(async () => storeWithQueue([]));
+    setDeviceStoreOpener(opener);
+
+    expect(isOfflineConfigured()).toBe(false);
+    expect(getOfflineState().enabled).toBe(false);
+    await expect(getOfflineStore()).rejects.toBeInstanceOf(DeviceStoreUnavailableError);
+    expect(opener).not.toHaveBeenCalled();
+  });
+
+  it("with requireOptIn and no signed-in user, offline mode is off", () => {
+    configureOffline(config({ requireOptIn: true, getUserId: () => undefined }));
+    expect(isOfflineEnabledOnDevice(undefined)).toBe(false);
+    expect(isOfflineConfigured()).toBe(false);
+  });
+
+  it("reads the stored switch and the last sync time at configure", () => {
+    localStorage.setItem(ENABLED_KEY, "1");
+    localStorage.setItem(LAST_SYNC_KEY, "1761990000000");
+    configureOffline(config({ requireOptIn: true }));
+
+    expect(isOfflineConfigured()).toBe(true);
+    expect(getOfflineState()).toEqual(expect.objectContaining({ enabled: true, lastSyncedAt: 1761990000000 }));
+  });
+
+  it("turnOnOffline stores the switch and sets enabled", async () => {
+    const persist = vi.fn(async () => true);
+    vi.stubGlobal("navigator", { ...navigator, storage: { persist } });
+    configureOffline(config({ requireOptIn: true }));
+
+    await turnOnOffline();
+
+    expect(localStorage.getItem(ENABLED_KEY)).toBe("1");
+    expect(getOfflineState().enabled).toBe(true);
+    expect(isOfflineConfigured()).toBe(true);
+    expect(persist).toHaveBeenCalled();
+  });
+
+  it("turnOnOffline ignores a failing persist request", async () => {
+    const persist = vi.fn(async () => Promise.reject(new Error("no")));
+    vi.stubGlobal("navigator", { ...navigator, storage: { persist } });
+    configureOffline(config({ requireOptIn: true }));
+
+    await expect(turnOnOffline()).resolves.toBeUndefined();
+    expect(getOfflineState().enabled).toBe(true);
+  });
+
+  it("turnOffOffline refuses, changing nothing, while changes wait to be sent", async () => {
+    localStorage.setItem(ENABLED_KEY, "1");
+    configureOffline(config({ requireOptIn: true }));
+    setDeviceStoreOpener(async () => storeWithQueue([{ status: "pending" }, { status: "failed" }]));
+
+    expect(await turnOffOffline()).toEqual({ turnedOff: false, pending: 2 });
+
+    expect(localStorage.getItem(ENABLED_KEY)).toBe("1");
+    expect(getOfflineState().enabled).toBe(true);
+    expect(runtime.stopOfflineRuntime).not.toHaveBeenCalled();
+    expect(lifecycle.deleteDeviceStore).not.toHaveBeenCalled();
+  });
+
+  it("turnOffOffline refuses when the copy is held by another tab and its marker says changes wait", async () => {
+    localStorage.setItem(ENABLED_KEY, "1");
+    configureOffline(config({ requireOptIn: true }));
+    setDeviceStoreOpener(async () => {
+      throw new Error("held by another tab");
+    });
+    lifecycle.hasUnsentChanges.mockResolvedValue(true);
+
+    expect(await turnOffOffline()).toEqual({ turnedOff: false, pending: 1 });
+
+    expect(lifecycle.hasUnsentChanges).toHaveBeenCalledWith("u1");
+    expect(localStorage.getItem(ENABLED_KEY)).toBe("1");
+    expect(lifecycle.deleteDeviceStore).not.toHaveBeenCalled();
+  });
+
+  it("turnOffOffline deletes the device copy and clears the switch and the state", async () => {
+    localStorage.setItem(ENABLED_KEY, "1");
+    localStorage.setItem(LAST_SYNC_KEY, "1761990000000");
+    configureOffline(config({ requireOptIn: true }));
+    const opener = vi.fn(async () => storeWithQueue([]));
+    setDeviceStoreOpener(opener);
+    setOfflineState({ rootCount: 3, syncProgress: { done: 1, total: 3 } });
+
+    expect(await turnOffOffline()).toEqual({ turnedOff: true });
+
+    expect(runtime.stopOfflineRuntime).toHaveBeenCalled();
+    expect(lifecycle.deleteDeviceStore).toHaveBeenCalledWith("u1");
+    expect(caches.delete).toHaveBeenCalledWith("app-images");
+    expect(localStorage.getItem(ENABLED_KEY)).toBeNull();
+    expect(localStorage.getItem(LAST_SYNC_KEY)).toBeNull();
+    expect(getOfflineState()).toEqual(
+      expect.objectContaining({ enabled: false, syncProgress: null, lastSyncedAt: null, rootCount: null }),
+    );
+    expect(isOfflineConfigured()).toBe(false);
+    await expect(getOfflineStore()).rejects.toBeInstanceOf(DeviceStoreUnavailableError);
+    expect(opener).toHaveBeenCalledTimes(1);
+  });
+
+  it("turnOffOffline on a browser that cannot keep the copy only clears the switch and the state", async () => {
+    localStorage.setItem(ENABLED_KEY, "1");
+    configureOffline(config({ requireOptIn: true }));
+    setOfflineState({ available: false });
+
+    expect(await turnOffOffline()).toEqual({ turnedOff: true });
+
+    expect(lifecycle.deleteDeviceStore).not.toHaveBeenCalled();
+    expect(localStorage.getItem(ENABLED_KEY)).toBeNull();
+    expect(getOfflineState().enabled).toBe(false);
+  });
+});