@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.0

package/src/offline/index.ts

@@ -0,0 +1,67 @@
+// `@carlonicora/nextjs-jsonapi/offline` — the opt-in offline layer (C4).
+// Importing this entry starts nothing: no store is opened, no worker created, no listener added,
+// until the app calls `configureOffline(...)`.
+
+export * from "./types";
+export { configureOffline } from "./configure";
+export {
+  isOfflineConfigured,
+  isOfflineAvailable,
+  isOfflineEnabledOnDevice,
+  refreshOfflineDeviceState,
+  getOfflineConfig,
+  getOfflineStore,
+  forgetOfflineStore,
+  setDeviceStoreOpener,
+  DeviceStoreUnavailableError,
+  OfflineUnavailableError,
+} from "./config";
+export { getOfflineState, subscribeOfflineState, setOfflineState, type OfflineState } from "./state";
+export { useOfflineState, useNeedsConnection } from "./state-hooks";
+export { matchRoute, matchPattern, type RouteMatch } from "./router";
+export { localTransport } from "./local-transport";
+export { writeThrough } from "./write-through";
+export {
+  needsConnectionAnswer,
+  notFoundAnswer,
+  errorAnswer,
+  singleAnswer,
+  orderedListAnswer,
+  resourceListAnswer,
+  mergeResource,
+  resourceFromDocument,
+  includedFor,
+  listAnswer,
+  searchRecords,
+  orderRecords,
+  linksOfKind,
+  linkKindFor,
+  linkKindsOf,
+  SERVER_DEFAULT_ORDER_BY,
+  type ListOptions,
+  type ResourceDocumentData,
+} from "./generic-answers";
+export type { OfflineChangeResolution } from "./sync/models/OfflineChangeSetInterface";
+
+// Device store (Task 5)
+export type * from "./store/DeviceStore";
+export {
+  openDeviceStore,
+  openMemoryDeviceStore,
+  deleteDeviceStore,
+  hasUnsentChanges,
+  onUserSignedIn,
+  isRootLocked,
+} from "./store/lifecycle";
+
+// Sync, sending changes, conflicts, runtime (Task 6)
+export * from "./sync/sync-root";
+export * from "./sync/drain-queue";
+export * from "./sync/conflicts";
+export * from "./sync/runtime";
+
+// Logout (Task 7)
+export { prepareOfflineLogout, finishOfflineLogout } from "./logout";
+
+// Per-device switch (`OfflineConfig.requireOptIn`)
+export { turnOnOffline, turnOffOffline } from "./device-switch";

package/src/offline/local-transport.ts

@@ -0,0 +1,189 @@
+import { getClientApiUrl } from "../client/JsonApiClient";
+import type { ApiData } from "../core/interfaces/ApiData";
+import { getApiUrl } from "../unified/JsonApiRequest";
+import { getOfflineConfig, getOfflineStore } from "./config";
+import {
+  buildGenericRoutes,
+  rootIdForResource,
+  isRootWriteLocked,
+  needsConnectionAnswer,
+  queuePath,
+} from "./generic-answers";
+import { matchRoute } from "./router";
+import { setOfflineState } from "./state";
+import type { DeviceStore } from "./store/DeviceStore";
+import {
+  NeedsConnectionError,
+  type OfflineAnswer,
+  type OfflineMethod,
+  type OfflineRequest,
+  type OfflineRoute,
+} from "./types";
+
+export type LocalTransportRequest = {
+  method: string;
+  url: string;
+  body?: any;
+  files?: unknown;
+};
+
+const METHODS: OfflineMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+function apiBases(): string[] {
+  const bases: string[] = [];
+  for (const read of [getApiUrl, getClientApiUrl]) {
+    try {
+      const base = read();
+      if (base) bases.push(base);
+    } catch {
+      // not configured on this side
+    }
+  }
+  return bases;
+}
+
+/** The path relative to the API base, as `EndpointCreator` built it, and its query. */
+export function splitApiUrl(url: string): { path: string; query: URLSearchParams } {
+  let relative: string | undefined;
+  for (const base of apiBases()) {
+    if (url.startsWith(base)) {
+      relative = url.slice(base.length);
+      break;
+    }
+  }
+  if (relative === undefined) {
+    try {
+      const parsed = new URL(url);
+      relative = `${parsed.pathname}${parsed.search}`;
+    } catch {
+      relative = url;
+    }
+  }
+
+  const [pathPart, ...queryParts] = relative.split("?");
+  return {
+    path: pathPart.replace(/^\/+/, "").replace(/\/+$/, ""),
+    query: new URLSearchParams(queryParts.join("?")),
+  };
+}
+
+function toApiData(answer: OfflineAnswer): ApiData {
+  const ok = answer.status >= 200 && answer.status < 300;
+  return {
+    ok,
+    status: answer.status,
+    statusText: ok ? "OK" : answer.status === 503 ? "Service Unavailable" : "Error",
+    data: answer.body,
+  };
+}
+
+/** The root record a custom write belongs to: a `<root>/:param` capture, a stored record named by a param, or the body. */
+async function rootIdForCustomWrite(
+  store: DeviceStore,
+  pattern: OfflineRequest,
+  params: Record<string, string>,
+  rootSegmentParam: string | undefined,
+): Promise<string | undefined> {
+  const config = getOfflineConfig();
+  if (rootSegmentParam && params[rootSegmentParam]) return params[rootSegmentParam];
+
+  for (const value of Object.values(params)) {
+    for (const typeConfig of config.types) {
+      const stored = await store.getRecord(typeConfig.module.name, value);
+      if (stored?.rootId) return stored.rootId;
+    }
+  }
+  return rootIdForResource(store, config, pattern.body?.data);
+}
+
+async function refreshPendingCount(store: DeviceStore): Promise<void> {
+  const entries = await store.queue();
+  setOfflineState({ pending: entries.filter((entry) => entry.status !== "conflict").length });
+}
+
+/**
+ * Answers a request from the device copy: the app's custom routes first, then the generic ones.
+ * The result has the `ApiData` shape `directFetch` returns, so `translateResponse` and
+ * `rehydrate()` run unchanged.
+ */
+export async function localTransport(request: LocalTransportRequest): Promise<ApiData> {
+  try {
+    const method = request.method.toUpperCase() as OfflineMethod;
+    if (!METHODS.includes(method)) return toApiData(needsConnectionAnswer());
+    if (request.files) return toApiData(needsConnectionAnswer("Uploading files needs a connection"));
+
+    const config = getOfflineConfig();
+    const { path, query } = splitApiUrl(request.url);
+    const offlineRequest: OfflineRequest = { method, path, query, body: request.body, url: request.url };
+
+    const custom = matchRoute(config.routes, method, path);
+    const match = custom ?? matchRoute(buildGenericRoutes(config), method, path);
+    if (!match) return toApiData(needsConnectionAnswer(`${method} ${path} has no offline answer`));
+
+    let store: DeviceStore;
+    try {
+      store = await getOfflineStore();
+    } catch (error) {
+      // The device copy cannot be opened here (another tab holds the file, storage refused,
+      // no signed-in user): only the server can answer.
+      if (error instanceof NeedsConnectionError) return toApiData(needsConnectionAnswer(error.message));
+      console.warn("[offline] the device copy could not be opened", error);
+      return toApiData(needsConnectionAnswer("The device copy is not available in this tab"));
+    }
+    const ctx = { request: offlineRequest, params: match.params, store };
+
+    // The root record of a custom write (a `<root>/:param` capture, a stored record, or the body).
+    const customRootId = async (route: OfflineRoute): Promise<string | undefined> => {
+      const rootIndex = route.pattern.findIndex(
+        (segment) => typeof segment !== "string" && segment.name === config.rootModule.name,
+      );
+      const next = rootIndex >= 0 ? route.pattern[rootIndex + 1] : undefined;
+      const rootParam = typeof next === "string" && next.startsWith(":") ? next.slice(1) : undefined;
+      return rootIdForCustomWrite(store, offlineRequest, match.params, rootParam);
+    };
+
+    if (!custom || !custom.route.queue) {
+      // A custom write that is not queued is refused on a locked root record too (GETs stay allowed).
+      if (custom && method !== "GET") {
+        const rootId = await customRootId(custom.route);
+        if (rootId && isRootWriteLocked(rootId)) {
+          return toApiData(needsConnectionAnswer("The root record is locked"));
+        }
+      }
+      const answer = await match.route.answer(ctx);
+      if (method !== "GET") await refreshPendingCount(store);
+      return toApiData(answer);
+    }
+
+    // A custom write the server must run too: refused on a locked root record, otherwise the answer
+    // updates the device copy and the original request is queued in the same transaction.
+    const rootId = await customRootId(custom.route);
+    if (!rootId) return toApiData(needsConnectionAnswer(`${method} ${path} belongs to no root record on this device`));
+    if (isRootWriteLocked(rootId)) return toApiData(needsConnectionAnswer("The root record is locked"));
+
+    const answer = await store.transaction(async (transactionStore) => {
+      const result = await custom.route.answer({ ...ctx, store: transactionStore });
+      if (result.status >= 200 && result.status < 300) {
+        await transactionStore.enqueue({
+          rootId,
+          method,
+          path: queuePath(ctx),
+          body: request.body,
+          base: null,
+        });
+      }
+      return result;
+    });
+    await refreshPendingCount(store);
+    return toApiData(answer);
+  } catch (error) {
+    if (error instanceof NeedsConnectionError) return toApiData(needsConnectionAnswer(error.message));
+    console.error("[offline] local answer failed", error);
+    return toApiData({
+      status: 500,
+      body: {
+        errors: [{ status: "500", title: "Offline answer failed", detail: String((error as Error)?.message ?? error) }],
+      },
+    });
+  }
+}

package/src/offline/logout.ts

@@ -0,0 +1,41 @@
+import {
+  blockOfflineStore,
+  getOfflineConfig,
+  getOfflineStore,
+  isOfflineConfigured,
+  setOfflineEnabledOnDevice,
+  writeOfflineLastSync,
+} from "./config";
+import { setOfflineState } from "./state";
+import { deleteImagesCaches } from "./sync/artwork-cache";
+import { stopOfflineRuntime } from "./sync/runtime";
+
+/**
+ * How many changes the signed-in user's device still has to send (every queue entry: pending,
+ * sending, in conflict or failed). The app warns before logging out when this is above 0.
+ */
+export async function prepareOfflineLogout(): Promise<{ pending: number }> {
+  if (!isOfflineConfigured()) return { pending: 0 };
+  if (!getOfflineConfig().getUserId()) return { pending: 0 };
+  const store = await getOfflineStore();
+  const entries = await store.queue();
+  return { pending: entries.length };
+}
+
+/**
+ * Deletes the user's device database and the cached artwork images. Call it right before logging
+ * out. The runtime is stopped first and the store blocked until the next sign-in
+ * (`onUserSignedIn`), so a sync still running cannot open, and so recreate, the deleted file.
+ * The device switch (`requireOptIn`) is turned off too: after a logout nothing is downloaded again
+ * until the user turns offline mode back on.
+ */
+export async function finishOfflineLogout(userId: string): Promise<void> {
+  stopOfflineRuntime();
+  blockOfflineStore(userId);
+  const { deleteDeviceStore } = await import("./store/lifecycle");
+  await deleteDeviceStore(userId);
+  await deleteImagesCaches();
+  setOfflineEnabledOnDevice(userId, false);
+  writeOfflineLastSync(userId, null);
+  setOfflineState({ enabled: false, syncProgress: null, lastSyncedAt: null, rootCount: null });
+}

package/src/offline/router.ts

@@ -0,0 +1,41 @@
+import type { OfflineMethod, OfflineRoute, PatternSegment } from "./types";
+
+export type RouteMatch = { route: OfflineRoute; params: Record<string, string> };
+
+function splitPath(path: string): string[] {
+  const withoutQuery = path.split("?")[0].split("#")[0];
+  return withoutQuery.split("/").filter((segment) => segment.length > 0);
+}
+
+/** A Module segment may itself hold slashes ("roots/played"), so each one is expanded. */
+function expandPattern(pattern: PatternSegment[]): string[] {
+  return pattern.flatMap((segment) => splitPath(typeof segment === "string" ? segment : segment.name));
+}
+
+export function matchPattern(pattern: PatternSegment[], path: string): Record<string, string> | null {
+  const expected = expandPattern(pattern);
+  const actual = splitPath(path);
+  if (expected.length !== actual.length) return null;
+
+  const params: Record<string, string> = {};
+  for (let index = 0; index < expected.length; index++) {
+    const segment = expected[index];
+    const value = decodeURIComponent(actual[index]);
+    if (segment.startsWith(":")) {
+      params[segment.slice(1)] = value;
+    } else if (segment !== value) {
+      return null;
+    }
+  }
+  return params;
+}
+
+/** The first route, in the order given, whose method and pattern match. The query string is ignored. */
+export function matchRoute(routes: OfflineRoute[], method: OfflineMethod, path: string): RouteMatch | null {
+  for (const route of routes) {
+    if (route.method !== method) continue;
+    const params = matchPattern(route.pattern, path);
+    if (params) return { route, params };
+  }
+  return null;
+}

package/src/offline/server/__tests__/build-offline-manifest.spec.ts

@@ -0,0 +1,76 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildOfflineManifest } from "../build-offline-manifest";
+
+async function writeBuild(distDir: string, buildId: string | null, files: string[]) {
+  await mkdir(distDir, { recursive: true });
+  if (buildId !== null) await writeFile(path.join(distDir, "BUILD_ID"), `${buildId}\n`);
+  for (const file of files) {
+    const full = path.join(distDir, "static", file);
+    await mkdir(path.dirname(full), { recursive: true });
+    await writeFile(full, "x");
+  }
+}
+
+describe("buildOfflineManifest", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(path.join(tmpdir(), "nja-offline-manifest-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("returns buildId from <distDir>/BUILD_ID and every file under <distDir>/static as /_next/static/...", async () => {
+    const distDir = path.join(root, ".next");
+    await writeBuild(distDir, "abc123", [
+      "chunks/main.js",
+      "css/app.css",
+      "abc123/_buildManifest.js",
+      "media/font.woff2",
+    ]);
+    // Files outside static/ are never listed.
+    await writeFile(path.join(distDir, "server-only.json"), "{}");
+
+    const manifest = await buildOfflineManifest({ distDir });
+
+    expect(manifest.buildId).toBe("abc123");
+    expect([...manifest.assets].sort()).toEqual(
+      [
+        "/_next/static/abc123/_buildManifest.js",
+        "/_next/static/chunks/main.js",
+        "/_next/static/css/app.css",
+        "/_next/static/media/font.woff2",
+      ].sort(),
+    );
+  });
+
+  it("honours a custom distDir", async () => {
+    await writeBuild(path.join(root, ".next"), "default-build", ["chunks/default.js"]);
+    const customDir = path.join(root, ".next-e2e-1");
+    await writeBuild(customDir, "e2e-build", ["chunks/e2e.js"]);
+
+    const manifest = await buildOfflineManifest({ distDir: customDir });
+
+    expect(manifest).toEqual({ buildId: "e2e-build", assets: ["/_next/static/chunks/e2e.js"] });
+  });
+
+  it("next dev (no BUILD_ID): the id comes from the asset list and changes when a chunk changes", async () => {
+    const devDir = path.join(root, ".next", "dev");
+    await writeBuild(devDir, null, ["chunks/a_111.js", "development/_buildManifest.js"]);
+
+    const first = await buildOfflineManifest({ distDir: devDir });
+    const again = await buildOfflineManifest({ distDir: devDir });
+    expect(first.buildId).toMatch(/^dev-[0-9a-f]{16}$/);
+    expect(again.buildId).toBe(first.buildId);
+    expect(first.assets).toEqual(["/_next/static/chunks/a_111.js", "/_next/static/development/_buildManifest.js"]);
+
+    await writeBuild(devDir, null, ["chunks/a_222.js"]);
+    const edited = await buildOfflineManifest({ distDir: devDir });
+    expect(edited.buildId).not.toBe(first.buildId);
+  });
+});

package/src/offline/server/build-offline-manifest.ts

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export type OfflineManifest = { buildId: string; assets: string[] };
+
+async function listFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...(await listFiles(full)));
+    else if (entry.isFile()) files.push(full);
+  }
+  return files;
+}
+
+/**
+ * Describes the running build for the service worker's offline shell precache
+ * (`/offline-manifest.json`): the build id from `<distDir>/BUILD_ID` and every
+ * file under `<distDir>/static`, as the `/_next/static/...` URL Next serves it at.
+ * `next dev` writes no BUILD_ID (its folder is `.next/dev`): the id is then derived from the
+ * asset list, whose chunk names carry content hashes, so an edit gives a new id and the
+ * service worker refreshes the shell.
+ * `distDir` must be the value the app's next.config uses. `extraAssets` are further same-origin
+ * URLs the shell needs with no network (the SQLite files the device worker loads).
+ */
+export async function buildOfflineManifest(params: {
+  distDir: string;
+  extraAssets?: string[];
+}): Promise<OfflineManifest> {
+  const staticDir = path.join(params.distDir, "static");
+  const files = await listFiles(staticDir);
+  const assets = files
+    .map((file) => `/_next/static/${path.relative(staticDir, file).split(path.sep).join("/")}`)
+    .concat(params.extraAssets ?? [])
+    .sort();
+  const buildId = await readBuildId(params.distDir, assets);
+  return { buildId, assets };
+}
+
+async function readBuildId(distDir: string, assets: string[]): Promise<string> {
+  try {
+    return (await readFile(path.join(distDir, "BUILD_ID"), "utf8")).trim();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return `dev-${createHash("sha256").update(assets.join("\n")).digest("hex").slice(0, 16)}`;
+  }
+}

package/src/offline/state-hooks.ts

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from "react";
+import { getOfflineState, SERVER_SNAPSHOT, subscribeOfflineState, type OfflineState } from "./state";
+
+export function useOfflineState(): OfflineState {
+  return useSyncExternalStore(subscribeOfflineState, getOfflineState, () => SERVER_SNAPSHOT);
+}
+
+export function useNeedsConnection(): boolean {
+  return !useOfflineState().online;
+}

package/src/offline/state.ts

@@ -0,0 +1,143 @@
+// Kept free of React: `directFetch` (every entry, server ones included) imports this module.
+// The hooks live in state-hooks.ts, exported only from the `./offline` entry.
+
+export type OfflineState = {
+  online: boolean;
+  pending: number;
+  conflicts: number;
+  draining: boolean;
+  lockedRootIds: string[];
+  /**
+   * False once this browser was found unable to keep the device copy (no secure context, no
+   * private file storage, or the worker reports the OPFS APIs missing). Offline mode is then off
+   * for the rest of the page: `isOfflineConfigured()` answers false and nothing offline runs.
+   */
+  available: boolean;
+  /**
+   * Offline mode is on on this device for the signed-in user. Always true once configured
+   * without `OfflineConfig.requireOptIn`; otherwise the GM's per-device switch.
+   */
+  enabled: boolean;
+  /** The running full sync: root records done out of the total, null when no sync runs. */
+  syncProgress: { done: number; total: number } | null;
+  /** When the last full sync on this device finished (epoch ms), null when never. */
+  lastSyncedAt: number | null;
+  /** How many root records the last full sync kept on this device, null when unknown. */
+  rootCount: number | null;
+};
+
+export const SERVER_SNAPSHOT: OfflineState = {
+  online: true,
+  pending: 0,
+  conflicts: 0,
+  draining: false,
+  lockedRootIds: [],
+  available: true,
+  enabled: false,
+  syncProgress: null,
+  lastSyncedAt: null,
+  rootCount: null,
+};
+
+let _state: OfflineState = { ...SERVER_SNAPSHOT };
+const _listeners = new Set<(s: OfflineState) => void>();
+let _detachBrowserEvents: (() => void) | null = null;
+
+export function getOfflineState(): OfflineState {
+  return _state;
+}
+
+export function subscribeOfflineState(listener: (s: OfflineState) => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+  }
+  return a === b;
+}
+
+// A reconnect attempt: a probe reached the API while the session is offline. The session stays
+// offline (spec § 4: offline "until a sync succeeds") while the drain and the sync run; their
+// reads and the change-set request go to the network meanwhile (`reachesNetworkWhileOffline`).
+// Any network failure (`online: false` set again) ends the attempt.
+let _reconnecting = false;
+const _passThroughUrls = new Set<string>();
+
+/** Whether a reconnect attempt (drain then sync, after a probe reached the API) is running. */
+export function isReconnecting(): boolean {
+  return _reconnecting;
+}
+
+/** Starts or ends a reconnect attempt (the offline runtime). */
+export function setReconnecting(value: boolean): void {
+  _reconnecting = value;
+  if (!value) _passThroughUrls.clear();
+}
+
+/** Lets one write (the drain's change-set request) reach the network during a reconnect attempt. */
+export function allowWhileReconnecting(url: string): () => void {
+  _passThroughUrls.add(url);
+  return () => {
+    _passThroughUrls.delete(url);
+  };
+}
+
+/**
+ * While the session is offline, whether a request still goes to the network: only during a
+ * reconnect attempt, for a GET or a write the attempt let through. Any other write stays local
+ * (queued), so it is sent after the waiting changes, in order.
+ */
+export function reachesNetworkWhileOffline(method: string, url: string): boolean {
+  if (!_reconnecting) return false;
+  return method.toUpperCase() === "GET" || _passThroughUrls.has(url);
+}
+
+/** The sync and the drain may talk to the API: online, or during a reconnect attempt. */
+export function canReachApi(): boolean {
+  return _state.online || _reconnecting;
+}
+
+/** Applies a partial change. Listeners run once, and only when a value actually changed. */
+export function setOfflineState(patch: Partial<OfflineState>): void {
+  if (patch.online === false) setReconnecting(false);
+  const changed = (Object.keys(patch) as (keyof OfflineState)[]).some(
+    (key) => patch[key] !== undefined && !sameValue(patch[key], _state[key]),
+  );
+  if (!changed) return;
+
+  _state = { ..._state, ...patch };
+  for (const listener of [..._listeners]) listener(_state);
+}
+
+/**
+ * Follows the browser's offline event. Called by `configureOffline`, never at import, so an app
+ * that does not opt in gets no listener. The browser's online event alone never brings the
+ * session back online (spec § 4: offline "until a sync succeeds"): the runtime probes the API on
+ * that event and goes online only when the probe reaches it.
+ */
+export function attachBrowserOnlineEvents(): void {
+  if (_detachBrowserEvents || typeof window === "undefined") return;
+
+  if (typeof navigator !== "undefined" && typeof navigator.onLine === "boolean") {
+    setOfflineState({ online: navigator.onLine });
+  }
+
+  const onOffline = () => setOfflineState({ online: false });
+  window.addEventListener("offline", onOffline);
+  _detachBrowserEvents = () => {
+    window.removeEventListener("offline", onOffline);
+  };
+}
+
+/** Test helper: back to the initial state, browser events detached, listeners kept. */
+export function resetOfflineState(): void {
+  _detachBrowserEvents?.();
+  _detachBrowserEvents = null;
+  setReconnecting(false);
+  _state = { ...SERVER_SNAPSHOT };
+}