feat: add @script-development/fs-adapter-store package

Reactive adapter-store pattern with domain state management,
CRUD resource adapters, caching, and localStorage persistence.
Uses reactive getter pattern for existing resources.

Generic New<T> defaults to Omit<T, 'id'> — territories override.
No case conversion — middleware handles snake/camel transformation.

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

Author: Goosterhof

package-lock.json

@@ -0,0 +1,56 @@
+{
+  "name": "@script-development/fs-adapter-store",
+  "version": "0.1.0",
+  "description": "Reactive adapter-store pattern with domain state management and CRUD resource adapters",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/script-development/fs-packages.git",
+    "directory": "packages/adapter-store"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint:pkg": "publint && attw --pack",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@script-development/fs-helpers": "^0.1.0",
+    "@script-development/fs-http": "^0.1.0",
+    "@script-development/fs-loading": "^0.1.0",
+    "@script-development/fs-storage": "^0.1.0",
+    "jsdom": "^29.0.1",
+    "vue": "^3.5.0"
+  },
+  "peerDependencies": {
+    "@script-development/fs-helpers": "^0.1.0",
+    "@script-development/fs-http": "^0.1.0",
+    "@script-development/fs-loading": "^0.1.0",
+    "@script-development/fs-storage": "^0.1.0",
+    "vue": "^3.5.0"
+  }
+}

packages/adapter-store/package.json

@@ -0,0 +1,91 @@
+import type {
+  Adapted,
+  AdapterStoreConfig,
+  AdapterStoreModule,
+  Item,
+  NewAdapted,
+  StoreModuleForAdapter,
+} from "./types";
+import type { ComputedRef, Ref } from "vue";
+
+import { computed, ref } from "vue";
+
+import { EntryNotFoundError } from "./errors";
+
+export const createAdapterStoreModule = <
+  T extends Item,
+  E extends Adapted<T, object> = Adapted<T>,
+  N extends NewAdapted<T, object> = NewAdapted<T>,
+>(
+  config: AdapterStoreConfig<T, E, N>,
+): StoreModuleForAdapter<T, E, N> => {
+  const { domainName, adapter, httpService, storageService, loadingService } = config;
+
+  const storedItems = storageService.get<{ [id: number]: T }>(domainName, {});
+  const frozenStoredItems = Object.fromEntries(
+    Object.entries(storedItems).map(([id, item]) => [id, Object.freeze(item)]),
+  ) as { [id: number]: Readonly<T> };
+
+  const state: Ref<{ [id: number]: Readonly<T> }> = ref(frozenStoredItems);
+
+  const adaptedCache = new Map<number, E>();
+  const getByIdComputedCache = new Map<number, ComputedRef<E | undefined>>();
+
+  const getAdapted = (item: Readonly<T>): E => {
+    const cached = adaptedCache.get(item.id);
+    if (cached) {
+      return cached;
+    }
+    const adapted = adapter(storeModule, () => state.value[item.id] as T);
+    adaptedCache.set(item.id, adapted);
+    return adapted;
+  };
+
+  const setById = (item: T): void => {
+    state.value = { ...state.value, [item.id]: Object.freeze(item) };
+    storageService.put(domainName, state.value);
+  };
+
+  const deleteById = (id: number): void => {
+    state.value = Object.fromEntries(
+      Object.entries(state.value).filter(([key]) => Number(key) !== id),
+    ) as { [id: number]: Readonly<T> };
+    storageService.put(domainName, state.value);
+    adaptedCache.delete(id);
+    getByIdComputedCache.delete(id);
+  };
+
+  const storeModule: AdapterStoreModule<T> = { setById, deleteById };
+
+  const getById = (id: number): ComputedRef<E | undefined> => {
+    const cached = getByIdComputedCache.get(id);
+    if (cached) {
+      return cached;
+    }
+    const computedRef = computed(() => (state.value[id] ? getAdapted(state.value[id]) : undefined));
+    getByIdComputedCache.set(id, computedRef);
+    return computedRef;
+  };
+
+  return {
+    getAll: computed(() => Object.values(state.value).map((item) => getAdapted(item))),
+    getById,
+    getOrFailById: async (id: number) => {
+      await loadingService.ensureLoadingFinished();
+      const item = getById(id).value;
+      if (!item) throw new EntryNotFoundError(domainName, id);
+      return item;
+    },
+    generateNew: () => adapter(storeModule),
+    retrieveAll: async () => {
+      const { data } = await httpService.getRequest<T[]>(domainName);
+      state.value = data.reduce<{ [id: number]: Readonly<T> }>((acc, item) => {
+        acc[item.id] = Object.freeze(item);
+        return acc;
+      }, {});
+      storageService.put(domainName, state.value);
+      adaptedCache.clear();
+      getByIdComputedCache.clear();
+    },
+  };
+};

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

@@ -0,0 +1,13 @@
+export class EntryNotFoundError extends Error {
+  constructor(domainName: string, id: number) {
+    super(`${domainName} with id ${id} not found`);
+    this.name = "EntryNotFoundError";
+  }
+}
+
+export class MissingResponseDataError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MissingResponseDataError";
+  }
+}

packages/adapter-store/src/errors.ts

@@ -0,0 +1,13 @@
+export { createAdapterStoreModule } from "./adapter-store";
+export { resourceAdapter } from "./resource-adapter";
+export { EntryNotFoundError, MissingResponseDataError } from "./errors";
+export type {
+  Item,
+  DefaultNew,
+  Adapted,
+  NewAdapted,
+  Adapter,
+  AdapterStoreModule,
+  AdapterStoreConfig,
+  StoreModuleForAdapter,
+} from "./types";

packages/adapter-store/src/index.ts

@@ -0,0 +1,145 @@
+import type { HttpService } from "@script-development/fs-http";
+import type { Writable } from "@script-development/fs-helpers";
+import type { Ref } from "vue";
+
+import type { Adapted, AdapterStoreModule, Item, NewAdapted } from "./types";
+
+import { deepCopy } from "@script-development/fs-helpers";
+import { ref } from "vue";
+
+import { MissingResponseDataError } from "./errors";
+
+type ResourceHttpService = Pick<
+  HttpService,
+  "postRequest" | "putRequest" | "patchRequest" | "deleteRequest"
+>;
+
+interface AdapterRepository<T extends Item, N> {
+  create: (newItem: N) => Promise<T>;
+  update: (id: number, updatedItem: N | T) => Promise<T>;
+  patch: (id: number, partialItem: Partial<N>) => Promise<T>;
+  delete: (id: number) => Promise<void>;
+}
+
+const adapterRepositoryFactory = <T extends Item, N>(
+  domainName: string,
+  { setById, deleteById }: AdapterStoreModule<T>,
+  httpService: ResourceHttpService,
+): AdapterRepository<T, N> => {
+  const dataHandler = (data: T | undefined, actionType: "create" | "update" | "patch"): T => {
+    if (!data) {
+      throw new MissingResponseDataError(
+        `${actionType} route for ${domainName} returned no model in response to put in store.`,
+      );
+    }
+
+    setById(data);
+
+    return data;
+  };
+
+  return {
+    create: async (newItem: N) => {
+      const { data } = await httpService.postRequest<T>(domainName, newItem);
+      return dataHandler(data, "create");
+    },
+    update: async (id: number, updatedItem: N | T) => {
+      const { data } = await httpService.putRequest<T>(`${domainName}/${id}`, updatedItem);
+      return dataHandler(data, "update");
+    },
+    patch: async (id: number, partialItem: Partial<N>) => {
+      const { data } = await httpService.patchRequest<T>(`${domainName}/${id}`, partialItem);
+      return dataHandler(data, "patch");
+    },
+    delete: async (id: number) => {
+      await httpService.deleteRequest<void>(`${domainName}/${id}`);
+      deleteById(id);
+    },
+  };
+};
+
+/**
+ * Resource adapter factory — wraps a domain resource with mutable state and CRUD methods.
+ *
+ * Overloaded:
+ * - With resourceGetter `() => T`: creates an Adapted (existing resource with update/patch/delete)
+ * - Without: creates a NewAdapted (new resource with create)
+ */
+export function resourceAdapter<T extends Item, N extends object = Omit<T, "id">>(
+  resourceGetter: () => T,
+  domainName: string,
+  storeModule: AdapterStoreModule<T>,
+  httpService: ResourceHttpService,
+): Adapted<T, N>;
+export function resourceAdapter<T extends Item, N extends object = Omit<T, "id">>(
+  resource: N,
+  domainName: string,
+  storeModule: AdapterStoreModule<T>,
+  httpService: ResourceHttpService,
+): NewAdapted<T, N>;
+export function resourceAdapter<T extends Item, N extends object = Omit<T, "id">>(
+  resource: (() => T) | N,
+  domainName: string,
+  storeModule: AdapterStoreModule<T>,
+  httpService: ResourceHttpService,
+): Adapted<T, N> | NewAdapted<T, N> {
+  const repository = adapterRepositoryFactory<T, N>(domainName, storeModule, httpService);
+
+  if (typeof resource === "function") {
+    const resourceGetter = resource as () => T;
+    const mutable = ref(deepCopy(resourceGetter())) as Ref<Writable<T>>;
+
+    const adapted = {} as Adapted<T, N>;
+    const source = resourceGetter();
+
+    for (const key of Object.keys(source)) {
+      Object.defineProperty(adapted, key, {
+        get: () => resourceGetter()[key as keyof T],
+        enumerable: true,
+        configurable: true,
+      });
+    }
+
+    Object.defineProperty(adapted, "mutable", {
+      value: mutable,
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    Object.defineProperty(adapted, "reset", {
+      value: () => (mutable.value = deepCopy(resourceGetter())),
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    Object.defineProperty(adapted, "update", {
+      value: () => repository.update(resourceGetter().id, mutable.value as N | T),
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    Object.defineProperty(adapted, "patch", {
+      value: (partialItem: Partial<N>) => repository.patch(resourceGetter().id, partialItem),
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    Object.defineProperty(adapted, "delete", {
+      value: () => repository.delete(resourceGetter().id),
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+
+    return adapted;
+  }
+
+  const mutable = ref(deepCopy(resource)) as Ref<Writable<N>>;
+
+  return {
+    ...Object.freeze(resource as object),
+    mutable,
+    reset: () => (mutable.value = deepCopy(resource)),
+    create: () => repository.create(mutable.value as N),
+  } as unknown as NewAdapted<T, N>;
+}