Replace applyServer* methods with broadcast subscription contract

Addresses review feedback: exposing applyServerUpdate/applyServerDelete
as public store methods leaked a mutation surface that invited misuse
as an HTTP-bypass shortcut.

Drops both public methods. Adds an optional `broadcast` config slot
accepting an AdapterStoreBroadcast<T> contract. The store calls
`broadcast.subscribe({ onUpdate, onDelete })` exactly once at
construction, routing incoming events directly into the internal
setById/deleteById. Consumers never see the mutation handlers — they
can only bind a broadcast source at store creation time.

Channel lifecycle (join/leave per component) stays in the consuming
app; the broadcast contract is the narrow bridge between that layer
and the store.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jasperboerhof

packages/adapter-store/src/adapter-store.ts

@@ -19,7 +19,7 @@ export const createAdapterStoreModule = <
 >(
   config: AdapterStoreConfig<T, E, N>,
 ): StoreModuleForAdapter<T, E, N> => {
-  const { domainName, adapter, httpService, storageService, loadingService } = config;
+  const { domainName, adapter, httpService, storageService, loadingService, broadcast } = config;
 
   const storedItems = storageService.get<{ [id: number]: T }>(domainName, {});
   const frozenStoredItems = Object.fromEntries(
@@ -60,6 +60,8 @@ export const createAdapterStoreModule = <
 
   const storeModule: AdapterStoreModule<T> = { setById, deleteById };
 
+  broadcast?.subscribe({ onUpdate: setById, onDelete: deleteById });
+
   const getById = (id: number): ComputedRef<E | undefined> => {
     const cached = getByIdComputedCache.get(id);
     if (cached) {
@@ -94,7 +96,5 @@ export const createAdapterStoreModule = <
       adaptedCache.clear();
       getByIdComputedCache.clear();
     },
-    applyServerUpdate: setById,
-    applyServerDelete: deleteById,
   };
 };

packages/adapter-store/src/types.ts

@@ -55,6 +55,20 @@ export type Adapter<
   (storeModule: AdapterStoreModule<T>, resourceGetter: () => T): E;
 };
 
+/**
+ * Contract for binding server-initiated events (e.g. WebSocket broadcasts)
+ * to an adapter-store. The store calls `subscribe` once at construction and
+ * routes incoming events straight into its internal mutation path. The
+ * handlers are never exposed on the public store API, so consumers cannot
+ * acquire them to bypass HTTP.
+ */
+export type AdapterStoreBroadcast<T extends Item> = {
+  subscribe: (handlers: {
+    onUpdate: (item: T) => void;
+    onDelete: (id: number) => void;
+  }) => () => void;
+};
+
 /** Configuration for createAdapterStoreModule. */
 export type AdapterStoreConfig<
   T extends Item,
@@ -66,6 +80,7 @@ export type AdapterStoreConfig<
   httpService: Pick<HttpService, "getRequest">;
   storageService: Pick<StorageService, "get" | "put">;
   loadingService: Pick<LoadingService, "ensureLoadingFinished">;
+  broadcast?: AdapterStoreBroadcast<T>;
 };
 
 /** Public API of a store module. */
@@ -80,14 +95,4 @@ export type StoreModuleForAdapter<
   generateNew: () => N;
   retrieveById: (id: number) => Promise<void>;
   retrieveAll: () => Promise<void>;
-  /**
-   * Apply an externally-sourced item to the store (e.g. a WebSocket broadcast
-   * pushed by another client). Replaces the item by id without triggering HTTP.
-   */
-  applyServerUpdate: (item: T) => void;
-  /**
-   * Apply an externally-sourced deletion to the store (e.g. a WebSocket broadcast
-   * pushed by another client). Removes the item by id without triggering HTTP.
-   */
-  applyServerDelete: (id: number) => void;
 };

packages/adapter-store/tests/adapter-store.spec.ts

@@ -5,6 +5,7 @@ import type { LoadingService } from "@script-development/fs-loading";
 import type {
   Adapted,
   Adapter,
+  AdapterStoreBroadcast,
   AdapterStoreConfig,
   AdapterStoreModule,
   Item,
@@ -823,25 +824,82 @@ describe("createAdapterStoreModule", () => {
     });
   });
 
-  describe("applyServerUpdate", () => {
-    it("should insert an externally-sourced item into the store without calling http", () => {
+  describe("broadcast integration", () => {
+    const captureBroadcast = (): {
+      broadcast: AdapterStoreBroadcast<TestItem>;
+      subscribe: ReturnType<typeof vi.fn>;
+      unsubscribe: ReturnType<typeof vi.fn>;
+      getHandlers: () => {
+        onUpdate: (item: TestItem) => void;
+        onDelete: (id: number) => void;
+      };
+    } => {
+      let handlers: {
+        onUpdate: (item: TestItem) => void;
+        onDelete: (id: number) => void;
+      } | null = null;
+      const unsubscribe = vi.fn();
+      const subscribe = vi.fn((h: typeof handlers) => {
+        handlers = h;
+        return unsubscribe;
+      });
+      return {
+        broadcast: { subscribe } as AdapterStoreBroadcast<TestItem>,
+        subscribe,
+        unsubscribe,
+        getHandlers: () => {
+          if (!handlers) throw new Error("subscribe was not called");
+          return handlers;
+        },
+      };
+    };
+
+    it("should call subscribe exactly once at construction with onUpdate and onDelete", () => {
       // Arrange
       const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
       const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
       const loadingService: TestLoadingService = {
         ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const config: AdapterStoreConfig<TestItem, TestAdapted, TestNewAdapted> = {
+      const { broadcast, subscribe } = captureBroadcast();
+
+      // Act
+      createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
         domainName: "test-items",
         adapter: createTestAdapter,
         httpService,
         storageService,
         loadingService,
+        broadcast,
+      });
+
+      // Assert
+      expect(subscribe).toHaveBeenCalledTimes(1);
+      expect(subscribe).toHaveBeenCalledWith({
+        onUpdate: expect.any(Function) as unknown,
+        onDelete: expect.any(Function) as unknown,
+      });
+    });
+
+    it("should apply onUpdate events to the store without calling http", () => {
+      // Arrange
+      const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
+      const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
+      const loadingService: TestLoadingService = {
+        ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const store = createAdapterStoreModule(config);
+      const { broadcast, getHandlers } = captureBroadcast();
+      const store = createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
+        domainName: "test-items",
+        adapter: createTestAdapter,
+        httpService,
+        storageService,
+        loadingService,
+        broadcast,
+      });
 
       // Act
-      store.applyServerUpdate({
+      getHandlers().onUpdate({
         id: 9,
         name: "Pushed Item",
         createdAt: "2024-01-01T00:00:00Z",
@@ -853,22 +911,23 @@ describe("createAdapterStoreModule", () => {
       expect(httpService.getRequest).not.toHaveBeenCalled();
     });
 
-    it("should replace an existing item and refresh its adapted view", () => {
+    it("should replace existing items and refresh adapted views via onUpdate", () => {
       // Arrange
       const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
       const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
       const loadingService: TestLoadingService = {
         ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const config: AdapterStoreConfig<TestItem, TestAdapted, TestNewAdapted> = {
+      const { broadcast, getHandlers } = captureBroadcast();
+      const store = createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
         domainName: "test-items",
         adapter: createTestAdapter,
         httpService,
         storageService,
         loadingService,
-      };
-      const store = createAdapterStoreModule(config);
-      store.applyServerUpdate({
+        broadcast,
+      });
+      getHandlers().onUpdate({
         id: 1,
         name: "Original",
         createdAt: "2024-01-01T00:00:00Z",
@@ -877,7 +936,7 @@ describe("createAdapterStoreModule", () => {
       expect(store.getById(1).value?.name).toBe("Original");
 
       // Act
-      store.applyServerUpdate({
+      getHandlers().onUpdate({
         id: 1,
         name: "Updated",
         createdAt: "2024-01-01T00:00:00Z",
@@ -888,24 +947,25 @@ describe("createAdapterStoreModule", () => {
       expect(store.getById(1).value?.name).toBe("Updated");
     });
 
-    it("should persist to storage service", () => {
+    it("should persist onUpdate events to storage", () => {
       // Arrange
       const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
       const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
       const loadingService: TestLoadingService = {
         ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const config: AdapterStoreConfig<TestItem, TestAdapted, TestNewAdapted> = {
+      const { broadcast, getHandlers } = captureBroadcast();
+      createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
         domainName: "test-items",
         adapter: createTestAdapter,
         httpService,
         storageService,
         loadingService,
-      };
-      const store = createAdapterStoreModule(config);
+        broadcast,
+      });
 
       // Act
-      store.applyServerUpdate({
+      getHandlers().onUpdate({
         id: 4,
         name: "Item 4",
         createdAt: "2024-01-01T00:00:00Z",
@@ -918,25 +978,24 @@ describe("createAdapterStoreModule", () => {
         expect.objectContaining({ 4: expect.any(Object) as unknown }),
       );
     });
-  });
 
-  describe("applyServerDelete", () => {
-    it("should remove an item from the store without calling http", () => {
+    it("should apply onDelete events to the store without calling http", () => {
       // Arrange
       const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
       const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
       const loadingService: TestLoadingService = {
         ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const config: AdapterStoreConfig<TestItem, TestAdapted, TestNewAdapted> = {
+      const { broadcast, getHandlers } = captureBroadcast();
+      const store = createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
         domainName: "test-items",
         adapter: createTestAdapter,
         httpService,
         storageService,
         loadingService,
-      };
-      const store = createAdapterStoreModule(config);
-      store.applyServerUpdate({
+        broadcast,
+      });
+      getHandlers().onUpdate({
         id: 5,
         name: "Doomed",
         createdAt: "2024-01-01T00:00:00Z",
@@ -945,50 +1004,52 @@ describe("createAdapterStoreModule", () => {
       expect(store.getById(5).value).toBeDefined();
 
       // Act
-      store.applyServerDelete(5);
+      getHandlers().onDelete(5);
 
       // Assert
       expect(store.getById(5).value).toBeUndefined();
       expect(httpService.getRequest).not.toHaveBeenCalled();
     });
 
-    it("should be a no-op when the id is not in the store", () => {
+    it("should be a no-op when onDelete is fired for an unknown id", () => {
       // Arrange
       const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
       const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
       const loadingService: TestLoadingService = {
         ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const config: AdapterStoreConfig<TestItem, TestAdapted, TestNewAdapted> = {
+      const { broadcast, getHandlers } = captureBroadcast();
+      const store = createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
         domainName: "test-items",
         adapter: createTestAdapter,
         httpService,
         storageService,
         loadingService,
-      };
-      const store = createAdapterStoreModule(config);
+        broadcast,
+      });
 
       // Act & Assert
-      expect(() => store.applyServerDelete(404)).not.toThrow();
+      expect(() => getHandlers().onDelete(404)).not.toThrow();
       expect(store.getAll.value).toHaveLength(0);
     });
 
-    it("should persist the updated state to storage service", () => {
+    it("should persist onDelete events to storage", () => {
       // Arrange
       const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
       const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
       const loadingService: TestLoadingService = {
         ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
       };
-      const config: AdapterStoreConfig<TestItem, TestAdapted, TestNewAdapted> = {
+      const { broadcast, getHandlers } = captureBroadcast();
+      createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
         domainName: "test-items",
         adapter: createTestAdapter,
         httpService,
         storageService,
         loadingService,
-      };
-      const store = createAdapterStoreModule(config);
-      store.applyServerUpdate({
+        broadcast,
+      });
+      getHandlers().onUpdate({
         id: 6,
         name: "Item 6",
         createdAt: "2024-01-01T00:00:00Z",
@@ -997,14 +1058,34 @@ describe("createAdapterStoreModule", () => {
       vi.mocked(storageService.put).mockClear();
 
       // Act
-      store.applyServerDelete(6);
+      getHandlers().onDelete(6);
 
       // Assert
       expect(storageService.put).toHaveBeenCalledWith(
         "test-items",
         expect.not.objectContaining({ 6: expect.anything() }),
       );
     });
+
+    it("should not attempt to subscribe when broadcast is omitted", () => {
+      // Arrange
+      const httpService: Pick<HttpService, "getRequest"> = { getRequest: vi.fn() };
+      const storageService: TestStorageService = { put: vi.fn(), get: vi.fn().mockReturnValue({}) };
+      const loadingService: TestLoadingService = {
+        ensureLoadingFinished: vi.fn().mockResolvedValue(undefined),
+      };
+
+      // Act & Assert
+      expect(() =>
+        createAdapterStoreModule<TestItem, TestAdapted, TestNewAdapted>({
+          domainName: "test-items",
+          adapter: createTestAdapter,
+          httpService,
+          storageService,
+          loadingService,
+        }),
+      ).not.toThrow();
+    });
   });
 
   describe("localStorage persistence", () => {