@htlkg/data 0.0.2 → 0.0.9

package/dist/stores/index.d.ts

@@ -0,0 +1,106 @@
+import { WritableAtom } from 'nanostores';
+
+/**
+ * Store Factory
+ *
+ * Creates request-scoped nanostores for sharing data across Vue islands
+ * without props. Works with @inox-tools/request-nanostores for Astro integration.
+ */
+
+/**
+ * Type for the shared function from @it-astro:request-nanostores
+ */
+type SharedFn = <T>(key: string, atomFactory: WritableAtom<T>) => WritableAtom<T>;
+/**
+ * Configuration for a resource store
+ */
+interface StoreConfig {
+    /** Resource name (e.g., 'accounts', 'users') */
+    name: string;
+    /** Related resources to create stores for (e.g., ['brands', 'products']) */
+    relations?: string[];
+}
+/**
+ * Result type for created stores
+ */
+type ResourceStores<T, TRelations extends string = never> = {
+    /** Main resource store */
+    $data: WritableAtom<readonly T[]>;
+} & {
+    [K in TRelations as `$${K}`]: WritableAtom<readonly any[]>;
+};
+/**
+ * Creates request-scoped stores for a resource and its relations.
+ *
+ * This factory is designed to work with Astro's request-nanostores integration,
+ * providing request-isolated state that syncs from server to client.
+ *
+ * @param shared - The shared function from @it-astro:request-nanostores
+ * @param config - Store configuration
+ * @returns Object containing the main store and relation stores
+ *
+ * @example
+ * ```typescript
+ * // In your store file (e.g., stores/accounts.ts)
+ * import { shared } from '@it-astro:request-nanostores';
+ * import { createResourceStores } from '@htlkg/data/stores';
+ *
+ * export const accountStores = createResourceStores(shared, {
+ *   name: 'accounts',
+ *   relations: ['brands'],
+ * });
+ *
+ * // This creates:
+ * // - accountStores.$data (WritableAtom<any[]>) - main accounts store
+ * // - accountStores.$brands (WritableAtom<any[]>) - related brands store
+ *
+ * // For cleaner exports:
+ * export const $accounts = accountStores.$data;
+ * export const $accountsBrands = accountStores.$brands;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With typed stores
+ * interface Account { id: number; name: string; }
+ * interface Brand { id: number; name: string; }
+ *
+ * export const { $data: $accounts, $brands } = createResourceStores<Account, 'brands'>(
+ *   shared,
+ *   { name: 'accounts', relations: ['brands'] }
+ * );
+ * ```
+ */
+declare function createResourceStores<T = any, TRelations extends string = never>(shared: SharedFn, config: StoreConfig & {
+    relations?: TRelations[];
+}): ResourceStores<T, TRelations>;
+/**
+ * Creates a simple single store (non-factory version for simpler use cases)
+ *
+ * @example
+ * ```typescript
+ * import { shared } from '@it-astro:request-nanostores';
+ * import { createStore } from '@htlkg/data/stores';
+ *
+ * export const $currentUser = createStore<User>(shared, 'currentUser');
+ * ```
+ */
+declare function createStore<T>(shared: SharedFn, name: string, defaultValue?: T[]): WritableAtom<readonly T[]>;
+/**
+ * Creates a single-value store (for non-array values like current user)
+ *
+ * @example
+ * ```typescript
+ * import { shared } from '@it-astro:request-nanostores';
+ * import { createSingleStore } from '@htlkg/data/stores';
+ *
+ * export const $currentUser = createSingleStore<User | null>(shared, 'currentUser', null);
+ * ```
+ */
+declare function createSingleStore<T>(shared: SharedFn, name: string, defaultValue: T): WritableAtom<T>;
+/**
+ * Helper to create typed store with proper inference
+ */
+type InferStoreType<TStore extends WritableAtom<any>> = TStore extends WritableAtom<infer T> ? T : never;
+
+export { type InferStoreType, type ResourceStores, type StoreConfig, createResourceStores, createSingleStore, createStore };

package/dist/stores/index.js

@@ -0,0 +1,108 @@
+// ../../node_modules/.pnpm/nanostores@1.1.0/node_modules/nanostores/clean-stores/index.js
+var clean = /* @__PURE__ */ Symbol("clean");
+
+// ../../node_modules/.pnpm/nanostores@1.1.0/node_modules/nanostores/atom/index.js
+var listenerQueue = [];
+var lqIndex = 0;
+var QUEUE_ITEMS_PER_LISTENER = 4;
+var epoch = 0;
+var atom = /* @__NO_SIDE_EFFECTS__ */ (initialValue) => {
+  let listeners = [];
+  let $atom = {
+    get() {
+      if (!$atom.lc) {
+        $atom.listen(() => {
+        })();
+      }
+      return $atom.value;
+    },
+    lc: 0,
+    listen(listener) {
+      $atom.lc = listeners.push(listener);
+      return () => {
+        for (let i = lqIndex + QUEUE_ITEMS_PER_LISTENER; i < listenerQueue.length; ) {
+          if (listenerQueue[i] === listener) {
+            listenerQueue.splice(i, QUEUE_ITEMS_PER_LISTENER);
+          } else {
+            i += QUEUE_ITEMS_PER_LISTENER;
+          }
+        }
+        let index = listeners.indexOf(listener);
+        if (~index) {
+          listeners.splice(index, 1);
+          if (!--$atom.lc) $atom.off();
+        }
+      };
+    },
+    notify(oldValue, changedKey) {
+      epoch++;
+      let runListenerQueue = !listenerQueue.length;
+      for (let listener of listeners) {
+        listenerQueue.push(listener, $atom.value, oldValue, changedKey);
+      }
+      if (runListenerQueue) {
+        for (lqIndex = 0; lqIndex < listenerQueue.length; lqIndex += QUEUE_ITEMS_PER_LISTENER) {
+          listenerQueue[lqIndex](
+            listenerQueue[lqIndex + 1],
+            listenerQueue[lqIndex + 2],
+            listenerQueue[lqIndex + 3]
+          );
+        }
+        listenerQueue.length = 0;
+      }
+    },
+    /* It will be called on last listener unsubscribing.
+       We will redefine it in onMount and onStop. */
+    off() {
+    },
+    set(newValue) {
+      let oldValue = $atom.value;
+      if (oldValue !== newValue) {
+        $atom.value = newValue;
+        $atom.notify(oldValue);
+      }
+    },
+    subscribe(listener) {
+      let unbind = $atom.listen(listener);
+      listener($atom.value);
+      return unbind;
+    },
+    value: initialValue
+  };
+  if (process.env.NODE_ENV !== "production") {
+    $atom[clean] = () => {
+      listeners = [];
+      $atom.lc = 0;
+      $atom.off();
+    };
+  }
+  return $atom;
+};
+
+// src/stores/createStores.ts
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function createResourceStores(shared, config) {
+  const { name, relations = [] } = config;
+  const stores = {};
+  stores.$data = shared(name, atom([]));
+  for (const relation of relations) {
+    const storeKey = `$${relation}`;
+    const sharedKey = `${name}${capitalize(relation)}`;
+    stores[storeKey] = shared(sharedKey, atom([]));
+  }
+  return stores;
+}
+function createStore(shared, name, defaultValue = []) {
+  return shared(name, atom(defaultValue));
+}
+function createSingleStore(shared, name, defaultValue) {
+  return shared(name, atom(defaultValue));
+}
+export {
+  createResourceStores,
+  createSingleStore,
+  createStore
+};
+//# sourceMappingURL=index.js.map

package/dist/stores/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../node_modules/.pnpm/nanostores@1.1.0/node_modules/nanostores/clean-stores/index.js","../../../../node_modules/.pnpm/nanostores@1.1.0/node_modules/nanostores/atom/index.js","../../src/stores/createStores.ts"],"sourcesContent":["import { cleanTasks } from '../task/index.js'\n\nexport let clean = Symbol('clean')\n\nexport let cleanStores = (...stores) => {\n  if (process.env.NODE_ENV === 'production') {\n    throw new Error(\n      'cleanStores() can be used only during development or tests'\n    )\n  }\n  cleanTasks()\n  for (let $store of stores) {\n    if ($store) {\n      if ($store.mocked) delete $store.mocked\n      if ($store[clean]) $store[clean]()\n    }\n  }\n}\n","import { clean } from '../clean-stores/index.js'\n\nlet listenerQueue = []\nlet lqIndex = 0\nconst QUEUE_ITEMS_PER_LISTENER = 4\nexport let epoch = 0\n\n/* @__NO_SIDE_EFFECTS__ */\nexport const atom = initialValue => {\n  let listeners = []\n  let $atom = {\n    get() {\n      if (!$atom.lc) {\n        $atom.listen(() => {})()\n      }\n      return $atom.value\n    },\n    lc: 0,\n    listen(listener) {\n      $atom.lc = listeners.push(listener)\n\n      return () => {\n        for (\n          let i = lqIndex + QUEUE_ITEMS_PER_LISTENER;\n          i < listenerQueue.length;\n\n        ) {\n          if (listenerQueue[i] === listener) {\n            listenerQueue.splice(i, QUEUE_ITEMS_PER_LISTENER)\n          } else {\n            i += QUEUE_ITEMS_PER_LISTENER\n          }\n        }\n\n        let index = listeners.indexOf(listener)\n        if (~index) {\n          listeners.splice(index, 1)\n          if (!--$atom.lc) $atom.off()\n        }\n      }\n    },\n    notify(oldValue, changedKey) {\n      epoch++\n      let runListenerQueue = !listenerQueue.length\n      for (let listener of listeners) {\n        listenerQueue.push(listener, $atom.value, oldValue, changedKey)\n      }\n\n      if (runListenerQueue) {\n        for (\n          lqIndex = 0;\n          lqIndex < listenerQueue.length;\n          lqIndex += QUEUE_ITEMS_PER_LISTENER\n        ) {\n          listenerQueue[lqIndex](\n            listenerQueue[lqIndex + 1],\n            listenerQueue[lqIndex + 2],\n            listenerQueue[lqIndex + 3]\n          )\n        }\n        listenerQueue.length = 0\n      }\n    },\n    /* It will be called on last listener unsubscribing.\n       We will redefine it in onMount and onStop. */\n    off() {},\n    set(newValue) {\n      let oldValue = $atom.value\n      if (oldValue !== newValue) {\n        $atom.value = newValue\n        $atom.notify(oldValue)\n      }\n    },\n    subscribe(listener) {\n      let unbind = $atom.listen(listener)\n      listener($atom.value)\n      return unbind\n    },\n    value: initialValue\n  }\n\n  if (process.env.NODE_ENV !== 'production') {\n    $atom[clean] = () => {\n      listeners = []\n      $atom.lc = 0\n      $atom.off()\n    }\n  }\n\n  return $atom\n}\n\nexport const readonlyType = store => store\n","/**\n * Store Factory\n *\n * Creates request-scoped nanostores for sharing data across Vue islands\n * without props. Works with @inox-tools/request-nanostores for Astro integration.\n */\n\nimport { atom, type WritableAtom } from \"nanostores\";\n\n/**\n * Type for the shared function from @it-astro:request-nanostores\n */\ntype SharedFn = <T>(key: string, atomFactory: WritableAtom<T>) => WritableAtom<T>;\n\n/**\n * Configuration for a resource store\n */\nexport interface StoreConfig {\n\t/** Resource name (e.g., 'accounts', 'users') */\n\tname: string;\n\t/** Related resources to create stores for (e.g., ['brands', 'products']) */\n\trelations?: string[];\n}\n\n/**\n * Result type for created stores\n */\nexport type ResourceStores<T, TRelations extends string = never> = {\n\t/** Main resource store */\n\t$data: WritableAtom<readonly T[]>;\n} & {\n\t[K in TRelations as `$${K}`]: WritableAtom<readonly any[]>;\n};\n\n/**\n * Capitalize first letter of a string\n */\nfunction capitalize(str: string): string {\n\treturn str.charAt(0).toUpperCase() + str.slice(1);\n}\n\n/**\n * Creates request-scoped stores for a resource and its relations.\n *\n * This factory is designed to work with Astro's request-nanostores integration,\n * providing request-isolated state that syncs from server to client.\n *\n * @param shared - The shared function from @it-astro:request-nanostores\n * @param config - Store configuration\n * @returns Object containing the main store and relation stores\n *\n * @example\n * ```typescript\n * // In your store file (e.g., stores/accounts.ts)\n * import { shared } from '@it-astro:request-nanostores';\n * import { createResourceStores } from '@htlkg/data/stores';\n *\n * export const accountStores = createResourceStores(shared, {\n *   name: 'accounts',\n *   relations: ['brands'],\n * });\n *\n * // This creates:\n * // - accountStores.$data (WritableAtom<any[]>) - main accounts store\n * // - accountStores.$brands (WritableAtom<any[]>) - related brands store\n *\n * // For cleaner exports:\n * export const $accounts = accountStores.$data;\n * export const $accountsBrands = accountStores.$brands;\n * ```\n *\n * @example\n * ```typescript\n * // With typed stores\n * interface Account { id: number; name: string; }\n * interface Brand { id: number; name: string; }\n *\n * export const { $data: $accounts, $brands } = createResourceStores<Account, 'brands'>(\n *   shared,\n *   { name: 'accounts', relations: ['brands'] }\n * );\n * ```\n */\nexport function createResourceStores<T = any, TRelations extends string = never>(\n\tshared: SharedFn,\n\tconfig: StoreConfig & { relations?: TRelations[] },\n): ResourceStores<T, TRelations> {\n\tconst { name, relations = [] } = config;\n\n\tconst stores: Record<string, any> = {};\n\n\t// Main resource store\n\tstores.$data = shared(name, atom<T[]>([]));\n\n\t// Relation stores\n\tfor (const relation of relations) {\n\t\tconst storeKey = `$${relation}`;\n\t\tconst sharedKey = `${name}${capitalize(relation)}`;\n\t\tstores[storeKey] = shared(sharedKey, atom<any[]>([]));\n\t}\n\n\treturn stores as ResourceStores<T, TRelations>;\n}\n\n/**\n * Creates a simple single store (non-factory version for simpler use cases)\n *\n * @example\n * ```typescript\n * import { shared } from '@it-astro:request-nanostores';\n * import { createStore } from '@htlkg/data/stores';\n *\n * export const $currentUser = createStore<User>(shared, 'currentUser');\n * ```\n */\nexport function createStore<T>(\n\tshared: SharedFn,\n\tname: string,\n\tdefaultValue: T[] = [],\n): WritableAtom<readonly T[]> {\n\treturn shared(name, atom<T[]>(defaultValue));\n}\n\n/**\n * Creates a single-value store (for non-array values like current user)\n *\n * @example\n * ```typescript\n * import { shared } from '@it-astro:request-nanostores';\n * import { createSingleStore } from '@htlkg/data/stores';\n *\n * export const $currentUser = createSingleStore<User | null>(shared, 'currentUser', null);\n * ```\n */\nexport function createSingleStore<T>(\n\tshared: SharedFn,\n\tname: string,\n\tdefaultValue: T,\n): WritableAtom<T> {\n\treturn shared(name, atom<T>(defaultValue));\n}\n\n/**\n * Helper to create typed store with proper inference\n */\nexport type InferStoreType<TStore extends WritableAtom<any>> = TStore extends WritableAtom<infer T>\n\t? T\n\t: never;\n"],"mappings":";AAEO,IAAI,QAAQ,uBAAO,OAAO;;;ACAjC,IAAI,gBAAgB,CAAC;AACrB,IAAI,UAAU;AACd,IAAM,2BAA2B;AAC1B,IAAI,QAAQ;AAGZ,IAAM,kCAAO,kBAAgB;AAClC,MAAI,YAAY,CAAC;AACjB,MAAI,QAAQ;AAAA,IACV,MAAM;AACJ,UAAI,CAAC,MAAM,IAAI;AACb,cAAM,OAAO,MAAM;AAAA,QAAC,CAAC,EAAE;AAAA,MACzB;AACA,aAAO,MAAM;AAAA,IACf;AAAA,IACA,IAAI;AAAA,IACJ,OAAO,UAAU;AACf,YAAM,KAAK,UAAU,KAAK,QAAQ;AAElC,aAAO,MAAM;AACX,iBACM,IAAI,UAAU,0BAClB,IAAI,cAAc,UAElB;AACA,cAAI,cAAc,CAAC,MAAM,UAAU;AACjC,0BAAc,OAAO,GAAG,wBAAwB;AAAA,UAClD,OAAO;AACL,iBAAK;AAAA,UACP;AAAA,QACF;AAEA,YAAI,QAAQ,UAAU,QAAQ,QAAQ;AACtC,YAAI,CAAC,OAAO;AACV,oBAAU,OAAO,OAAO,CAAC;AACzB,cAAI,CAAC,EAAE,MAAM,GAAI,OAAM,IAAI;AAAA,QAC7B;AAAA,MACF;AAAA,IACF;AAAA,IACA,OAAO,UAAU,YAAY;AAC3B;AACA,UAAI,mBAAmB,CAAC,cAAc;AACtC,eAAS,YAAY,WAAW;AAC9B,sBAAc,KAAK,UAAU,MAAM,OAAO,UAAU,UAAU;AAAA,MAChE;AAEA,UAAI,kBAAkB;AACpB,aACE,UAAU,GACV,UAAU,cAAc,QACxB,WAAW,0BACX;AACA,wBAAc,OAAO;AAAA,YACnB,cAAc,UAAU,CAAC;AAAA,YACzB,cAAc,UAAU,CAAC;AAAA,YACzB,cAAc,UAAU,CAAC;AAAA,UAC3B;AAAA,QACF;AACA,sBAAc,SAAS;AAAA,MACzB;AAAA,IACF;AAAA;AAAA;AAAA,IAGA,MAAM;AAAA,IAAC;AAAA,IACP,IAAI,UAAU;AACZ,UAAI,WAAW,MAAM;AACrB,UAAI,aAAa,UAAU;AACzB,cAAM,QAAQ;AACd,cAAM,OAAO,QAAQ;AAAA,MACvB;AAAA,IACF;AAAA,IACA,UAAU,UAAU;AAClB,UAAI,SAAS,MAAM,OAAO,QAAQ;AAClC,eAAS,MAAM,KAAK;AACpB,aAAO;AAAA,IACT;AAAA,IACA,OAAO;AAAA,EACT;AAEA,MAAI,QAAQ,IAAI,aAAa,cAAc;AACzC,UAAM,KAAK,IAAI,MAAM;AACnB,kBAAY,CAAC;AACb,YAAM,KAAK;AACX,YAAM,IAAI;AAAA,IACZ;AAAA,EACF;AAEA,SAAO;AACT;;;ACrDA,SAAS,WAAW,KAAqB;AACxC,SAAO,IAAI,OAAO,CAAC,EAAE,YAAY,IAAI,IAAI,MAAM,CAAC;AACjD;AA4CO,SAAS,qBACf,QACA,QACgC;AAChC,QAAM,EAAE,MAAM,YAAY,CAAC,EAAE,IAAI;AAEjC,QAAM,SAA8B,CAAC;AAGrC,SAAO,QAAQ,OAAO,MAAM,KAAU,CAAC,CAAC,CAAC;AAGzC,aAAW,YAAY,WAAW;AACjC,UAAM,WAAW,IAAI,QAAQ;AAC7B,UAAM,YAAY,GAAG,IAAI,GAAG,WAAW,QAAQ,CAAC;AAChD,WAAO,QAAQ,IAAI,OAAO,WAAW,KAAY,CAAC,CAAC,CAAC;AAAA,EACrD;AAEA,SAAO;AACR;AAaO,SAAS,YACf,QACA,MACA,eAAoB,CAAC,GACQ;AAC7B,SAAO,OAAO,MAAM,KAAU,YAAY,CAAC;AAC5C;AAaO,SAAS,kBACf,QACA,MACA,cACkB;AAClB,SAAO,OAAO,MAAM,KAAQ,YAAY,CAAC;AAC1C;","names":[]}

package/package.json

@@ -1,38 +1,65 @@
 {
-  "name": "@htlkg/data",
-  "version": "0.0.2",
-  "type": "module",
-  "exports": {
-    ".": "./dist/index.js",
-    "./client": "./dist/client/index.js",
-    "./queries": "./dist/queries/index.js",
-    "./mutations": "./dist/mutations/index.js",
-    "./hooks": "./dist/hooks/index.js",
-    "./content-collections": "./dist/content-collections/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "@aws-amplify/api": "^6.0.0",
-    "vue": "^3.5.22",
-    "zod": "^3.22.0",
-    "@htlkg/core": "0.0.2"
-  },
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "devDependencies": {
-    "astro": "^5.14.7",
-    "aws-amplify": "^6.15.7",
-    "tsup": "^8.0.0",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  }
-}
+	"name": "@htlkg/data",
+	"version": "0.0.9",
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./client": {
+			"import": "./dist/client/index.js",
+			"types": "./dist/client/index.d.ts"
+		},
+		"./queries": {
+			"import": "./dist/queries/index.js",
+			"types": "./dist/queries/index.d.ts"
+		},
+		"./mutations": {
+			"import": "./dist/mutations/index.js",
+			"types": "./dist/mutations/index.d.ts"
+		},
+		"./hooks": {
+			"import": "./dist/hooks/index.js",
+			"types": "./dist/hooks/index.d.ts"
+		},
+		"./stores": {
+			"import": "./dist/stores/index.js",
+			"types": "./dist/stores/index.d.ts"
+		},
+		"./content-collections": {
+			"import": "./dist/content-collections/index.js",
+			"types": "./dist/content-collections/index.d.ts"
+		}
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"prepublishOnly": "pnpm build",
+		"version:patch": "pnpm version patch --no-git-tag-version",
+		"version:minor": "pnpm version minor --no-git-tag-version",
+		"version:major": "pnpm version major --no-git-tag-version"
+	},
+	"dependencies": {
+		"@aws-amplify/api": "^6.0.0",
+		"@htlkg/core": "^0.0.9",
+		"vue": "^3.5.22",
+		"zod": "^3.22.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"astro": "^5.14.7",
+		"aws-amplify": "^6.15.7",
+		"tsup": "^8.0.0",
+		"typescript": "^5.9.2",
+		"vitest": "^3.2.4"
+	}
+}

package/src/client/__tests__/server.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { generateServerClientUsingCookies } from '../server';
+import type { ResourcesConfig } from 'aws-amplify';
+
+// Mock dependencies
+vi.mock('@htlkg/core/amplify-astro-adapter', () => ({
+	createRunWithAmplifyServerContext: vi.fn(() => vi.fn()),
+	createLogger: vi.fn(() => ({
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	})),
+}));
+
+vi.mock('aws-amplify/adapter-core/internals', () => ({
+	getAmplifyServerContext: vi.fn(),
+}));
+
+vi.mock('aws-amplify/api/internals', () => ({
+	generateClientWithAmplifyInstance: vi.fn(() => ({
+		graphql: vi.fn(),
+		models: {},
+	})),
+}));
+
+const mockAmplifyConfig: ResourcesConfig = {
+	Auth: {
+		Cognito: {
+			identityPoolId: '123',
+			userPoolId: 'abc',
+			userPoolClientId: 'def',
+		},
+	},
+	API: {
+		GraphQL: {
+			defaultAuthMode: 'apiKey',
+			apiKey: 'FAKE-KEY',
+			endpoint: 'https://localhost/graphql',
+			region: 'local-host',
+		},
+	},
+};
+
+describe('generateServerClientUsingCookies', () => {
+	const mockCookies = {
+		get: vi.fn(),
+		set: vi.fn(),
+		delete: vi.fn(),
+	};
+
+	const mockRequest = new Request('https://example.com');
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('should create a client with the provided config', () => {
+		const client = generateServerClientUsingCookies({
+			config: mockAmplifyConfig,
+			cookies: mockCookies as any,
+			request: mockRequest,
+		});
+
+		expect(client).toBeDefined();
+		expect(client.graphql).toBeDefined();
+	});
+
+	it('should accept authMode option', () => {
+		const client = generateServerClientUsingCookies({
+			config: mockAmplifyConfig,
+			cookies: mockCookies as any,
+			request: mockRequest,
+			authMode: 'userPool',
+		});
+
+		expect(client).toBeDefined();
+	});
+
+	it('should accept apiKey option', () => {
+		const client = generateServerClientUsingCookies({
+			config: mockAmplifyConfig,
+			cookies: mockCookies as any,
+			request: mockRequest,
+			authMode: 'apiKey',
+			apiKey: 'custom-api-key',
+		});
+
+		expect(client).toBeDefined();
+	});
+
+	it('should accept headers option', () => {
+		const customHeaders = {
+			'X-Custom-Header': 'value',
+		};
+
+		const client = generateServerClientUsingCookies({
+			config: mockAmplifyConfig,
+			cookies: mockCookies as any,
+			request: mockRequest,
+			headers: customHeaders,
+		});
+
+		expect(client).toBeDefined();
+	});
+});

package/src/client/client.md

@@ -0,0 +1,91 @@
+# Client Module
+
+GraphQL client generation for client-side and server-side data fetching.
+
+## Installation
+
+```typescript
+import { 
+  generateClient,
+  generateServerClient,
+  getSharedClient,
+  resetSharedClient,
+} from '@htlkg/data/client';
+```
+
+## Client-Side
+
+### getSharedClient
+
+Singleton client for client-side fetching. Avoids creating multiple instances.
+
+```typescript
+import { getSharedClient } from '@htlkg/data/client';
+import type { Schema } from '@backend/data/resource';
+
+const client = getSharedClient<Schema>();
+const { data } = await client.models.Account.list();
+```
+
+### generateClient
+
+Create a new client instance. Use in component setup or after hydration.
+
+```typescript
+import { generateClient } from '@htlkg/data/client';
+
+const client = generateClient<Schema>();
+const { data: brands } = await client.models.Brand.list();
+```
+
+### resetSharedClient
+
+Reset the singleton (useful for auth state changes or testing).
+
+```typescript
+import { resetSharedClient } from '@htlkg/data/client';
+
+// After logout
+resetSharedClient();
+```
+
+## Server-Side
+
+### generateServerClient
+
+Create a server-side client for SSR. Must be called inside `runWithAmplifyServerContext`.
+
+```typescript
+import { generateServerClient } from '@htlkg/data/client';
+import { createRunWithAmplifyServerContext } from '@htlkg/core/amplify-astro-adapter';
+
+const runWithAmplifyServerContext = createRunWithAmplifyServerContext({ 
+  config: amplifyConfig 
+});
+
+const result = await runWithAmplifyServerContext({
+  astroServerContext: {
+    cookies: Astro.cookies,
+    request: Astro.request,
+  },
+  operation: async (contextSpec) => {
+    const client = generateServerClient<Schema>();
+    return await client.models.User.list();
+  },
+});
+```
+
+## Auth Modes
+
+| Mode | Description |
+|------|-------------|
+| `userPool` | Uses JWT from cookies (default) |
+| `apiKey` | Uses API key for public requests |
+
+```typescript
+// Authenticated request
+const client = generateServerClient<Schema>({ authMode: 'userPool' });
+
+// Public request
+const client = generateServerClient<Schema>({ authMode: 'apiKey' });
+```