@gorgonjs/gorgon 1.6.0 → 1.6.1

package/README.md

@@ -1,7 +1,7 @@
 # Gorgon
 ![coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)
 ![size](https://img.shields.io/badge/size-5.71KB-brightgreen)
-![version](https://img.shields.io/badge/version-1.6.0-blue)
+![version](https://img.shields.io/badge/version-1.6.1-blue)
 ![license](https://img.shields.io/badge/license-MIT-blue)
 
 A typescript async based caching library for node or the browser.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gorgonjs/gorgon",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "A simple caching library for async functions",
   "homepage": "https://gorgonjs.dev",
   "main": "./dist/index.umd.js",
@@ -29,11 +29,17 @@
     "type": "git",
     "url": "git@github.com:mikevalstar/gorgon.git"
   },
+  "files": [
+    "dist",
+    "skills",
+    "!skills/_artifacts"
+  ],
   "keywords": [
     "cache",
     "promise",
     "async",
-    "typescript"
+    "typescript",
+    "tanstack-intent"
   ],
   "author": "Mike Valstar <mike@valstar.dev>",
   "license": "MIT",
@@ -50,7 +56,8 @@
     "typescript": "^5.1.6",
     "vite": "^4.4.4",
     "vite-plugin-dts": "^3.3.0",
-    "vitest": "^0.33.0"
+    "vitest": "^0.33.0",
+    "@tanstack/intent": "^0.0.23"
   },
   "jest": {
     "collectCoverage": true,

package/skills/core/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: core
+description: >
+  Core caching with @gorgonjs/gorgon: Gorgon.get, Gorgon.put, Gorgon.clear
+  (with wildcards), Gorgon.overwrite, expiry policies, cache key naming,
+  concurrency deduplication, hooks, settings, custom storage providers via
+  IGorgonCacheProvider, @gorgonjs/file-provider for disk persistence, and
+  @gorgonjs/clearlink for distributed cache invalidation via WebSocket.
+  Use when caching API calls, database queries, or any async operation in
+  TypeScript/JavaScript.
+type: core
+library: gorgon
+library_version: "1.6.0"
+sources:
+  - "mikevalstar/gorgon:library/index.ts"
+  - "mikevalstar/gorgon:gorgonjs.dev/src/pages/docs/usage/get.md"
+  - "mikevalstar/gorgon:gorgonjs.dev/src/pages/docs/usage/policies.md"
+  - "mikevalstar/gorgon:gorgonjs.dev/src/pages/docs/concurrency.md"
+  - "mikevalstar/gorgon:gorgonjs.dev/src/pages/docs/custom-storage.md"
+---
+
+# Gorgon.js — Core Caching
+
+Gorgon is a lightweight (~4kb, ~1.3kb gzipped) TypeScript caching library for async functions. It works in Node.js and browsers. Its key feature is automatic concurrency protection — multiple simultaneous requests for the same cache key are deduplicated, with all callers sharing the same result. Errors are never cached.
+
+## Setup
+
+```typescript
+import Gorgon from '@gorgonjs/gorgon';
+
+const user = await Gorgon.get(`user/${id}`, async () => {
+  const res = await fetch(`/api/users/${id}`);
+  return res.json();
+}, 60 * 1000); // cache for 1 minute
+```
+
+For React usage, see `react/SKILL.md`.
+
+## Core Patterns
+
+### Cache an async function with typed return
+
+```typescript
+import Gorgon from '@gorgonjs/gorgon';
+
+interface User { id: number; name: string; email: string; }
+
+const getUser = (id: number): Promise<User> =>
+  Gorgon.get(`user/${id}`, async () => {
+    const res = await fetch(`/api/users/${id}`);
+    return res.json();
+  }, 60 * 1000);
+```
+
+The return type flows through — `getUser` returns `Promise<User>` with full type safety.
+
+### Cache key naming for wildcard invalidation
+
+Use the format `type/id/sub-id` so you can clear groups with wildcards:
+
+```typescript
+await Gorgon.get(`user/${id}/profile`, fetchProfile, 60000);
+await Gorgon.get(`user/${id}/posts`, fetchPosts, 60000);
+await Gorgon.get(`user/${id}/settings`, fetchSettings, 60000);
+
+// Clear everything for a user at once
+Gorgon.clear(`user/${id}/*`);
+```
+
+### Directly insert or force-refresh cached data
+
+```typescript
+// Insert a value directly
+await Gorgon.put(`user/${id}`, userData, 60000);
+
+// Force-refresh (always executes the function, no dedup)
+const updated = await Gorgon.overwrite(`user/${id}`, async () => {
+  return fetch(`/api/users/${id}`).then(r => r.json());
+}, 60000);
+```
+
+### Expiry policies
+
+```typescript
+// Milliseconds from now
+Gorgon.get('key', fn, 60000);
+
+// Specific date
+Gorgon.get('key', fn, new Date('2026-12-31'));
+
+// Cache forever (use with caution — see Common Mistakes)
+Gorgon.get('key', fn, false);
+
+// No policy — cached until manually cleared
+Gorgon.get('key', fn);
+
+// Full policy object — specify provider and expiry
+Gorgon.get('key', fn, { expiry: 60000, provider: 'file' });
+```
+
+### Configure global settings
+
+```typescript
+Gorgon.settings({
+  debug: true,               // log cache hits/misses to console
+  defaultProvider: 'memory', // which storage provider to use
+  retry: 5000                // ms before a "stuck" request retries (default: 5000)
+});
+```
+
+### Hook into cache lifecycle events
+
+```typescript
+Gorgon.addHook('clear', (key, input, output) => {
+  console.log('Cache cleared:', input);
+});
+
+Gorgon.addHook('valueError', (key, input, output) => {
+  console.error('Cache function threw:', output);
+});
+```
+
+Available events: `settings`, `addProvider`, `put`, `clear`, `clearAll`, `overwrite`, `get`, `valueError`.
+
+### Custom storage providers
+
+Implement `IGorgonCacheProvider` for Redis, IndexedDB, localStorage, etc.:
+
+```typescript
+import Gorgon, { IGorgonCacheProvider, GorgonPolicySanitized } from '@gorgonjs/gorgon';
+
+const myProvider: IGorgonCacheProvider = {
+  init: async () => {},
+  get: async (key: string) => { /* return cached value or undefined */ },
+  set: async <R>(key: string, value: R, policy: GorgonPolicySanitized): Promise<R> => {
+    /* store value, policy.expiry is ms or false */
+    return value;
+  },
+  clear: async (key?: string) => { /* clear key or all */ return true; },
+  keys: async () => { /* return all keys */ return []; },
+};
+
+Gorgon.addProvider('my-provider', myProvider);
+Gorgon.settings({ defaultProvider: 'my-provider' });
+```
+
+### File provider — persist cache to disk (server-side)
+
+```typescript
+import Gorgon from '@gorgonjs/gorgon';
+import { FileProvider } from '@gorgonjs/file-provider';
+
+const fileCache = FileProvider('./cache', {
+  createSubfolder: false, // true creates a dated subfolder
+  clearFolder: false       // true clears the directory on init
+});
+Gorgon.addProvider('file', fileCache);
+
+const movie = await Gorgon.get(`movie/${id}`, async () => {
+  return fetch(`https://api.example.com/movie/${id}`).then(r => r.json());
+}, { provider: 'file', expiry: false });
+```
+
+File provider uses `JSON.stringify` — only serializable data. For `Date`, `Set`, `Map`, use the `superjson` library.
+
+### ClearLink — sync cache clearing across servers
+
+```typescript
+// Server
+import { server } from '@gorgonjs/clearlink';
+server.init({ port: 8686 });
+
+// Client (on each app instance)
+import Gorgon from '@gorgonjs/gorgon';
+import { client } from '@gorgonjs/clearlink';
+
+client.connect('ws://127.0.0.1:8686');
+client.apply(Gorgon); // hooks into clear and clearAll events
+
+// Now Gorgon.clear() on any instance broadcasts to all others
+```
+
+Only `clear` and `clearAll` are synced (not `put` or auto-expiry). Auto-reconnects after 10 seconds on disconnect.
+
+## Common Mistakes
+
+### CRITICAL Not clearing cache after mutating underlying data
+
+Wrong:
+
+```typescript
+const user = await Gorgon.get(`user/${id}`, () => fetchUser(id), 60000);
+await updateUser(id, newData);
+// Forgot to clear — subsequent reads return stale data
+```
+
+Correct:
+
+```typescript
+const user = await Gorgon.get(`user/${id}`, () => fetchUser(id), 60000);
+await updateUser(id, newData);
+Gorgon.clear(`user/${id}`);
+```
+
+Gorgon does not know when the underlying data changes. Always clear the relevant cache key after any mutation (POST, PUT, DELETE) that affects cached data.
+
+Source: maintainer interview
+
+### CRITICAL Cache keys not specific enough to input parameters
+
+Wrong:
+
+```typescript
+const results = await Gorgon.get('search-results', () =>
+  searchAPI(query, page, filters), 60000);
+```
+
+Correct:
+
+```typescript
+const results = await Gorgon.get(
+  `search/${query}/${page}/${JSON.stringify(filters)}`,
+  () => searchAPI(query, page, filters), 60000);
+```
+
+If the cache key does not include all varying parameters, different requests share the same cached result, returning wrong data silently.
+
+Source: maintainer interview
+
+### HIGH Caching forever without expiry in production
+
+Wrong:
+
+```typescript
+await Gorgon.get('config', fetchConfig, false);
+```
+
+Correct:
+
+```typescript
+await Gorgon.get('config', fetchConfig, 24 * 60 * 60 * 1000); // 1 day
+```
+
+Even rarely-changing data should have an expiry. Permanent caches become stale silently and are hard to debug in production.
+
+Source: maintainer interview
+
+### MEDIUM Aligned cache expiry causing thundering herd
+
+Wrong:
+
+```typescript
+for (const id of popularIds) {
+  await Gorgon.get(`item/${id}`, () => fetchItem(id), 3600000);
+}
+```
+
+Correct:
+
+```typescript
+for (const id of popularIds) {
+  const fuzz = Math.random() * 600000; // up to 10 min variance
+  await Gorgon.get(`item/${id}`, () => fetchItem(id), 3600000 + fuzz);
+}
+```
+
+When many items share the same TTL, they all expire simultaneously causing a burst of requests. Fuzz the expiry to spread cache refreshes over time.
+
+Source: maintainer interview
+
+### HIGH Using a plain Map or global object instead of Gorgon
+
+Wrong:
+
+```typescript
+const cache = new Map();
+async function getUser(id: number) {
+  if (cache.has(id)) return cache.get(id);
+  const user = await fetchUser(id);
+  cache.set(id, user);
+  return user;
+}
+```
+
+Correct:
+
+```typescript
+import Gorgon from '@gorgonjs/gorgon';
+
+const getUser = (id: number) =>
+  Gorgon.get(`user/${id}`, () => fetchUser(id), 60000);
+```
+
+A hand-rolled cache misses concurrency deduplication (10 simultaneous calls hit the API 10 times), has no expiry management, no wildcard clearing, and no type safety on cached returns.
+
+Source: documentation — concurrency
+
+### MEDIUM Wrapping Gorgon.get in custom deduplication logic
+
+Wrong:
+
+```typescript
+const pending = new Map<string, Promise<any>>();
+async function getUser(id: number) {
+  const key = `user/${id}`;
+  if (pending.has(key)) return pending.get(key);
+  const promise = Gorgon.get(key, () => fetchUser(id), 60000);
+  pending.set(key, promise);
+  const result = await promise;
+  pending.delete(key);
+  return result;
+}
+```
+
+Correct:
+
+```typescript
+import Gorgon from '@gorgonjs/gorgon';
+
+const getUser = (id: number) =>
+  Gorgon.get(`user/${id}`, () => fetchUser(id), 60000);
+```
+
+Gorgon already deduplicates concurrent requests for the same key. External dedup is redundant and can introduce bugs with stale promise references.
+
+Source: documentation — concurrency
+
+### HIGH Tension: Cache duration vs data freshness
+
+Longer cache times improve performance but increase risk of stale data. Agents optimizing for performance tend to set very long TTLs without an invalidation strategy; agents optimizing for correctness set very short TTLs, defeating the purpose of caching. Choose a TTL appropriate for the data's change frequency and always pair it with explicit `Gorgon.clear()` calls on mutation.
+
+See also: `react/SKILL.md` § Common Mistakes
+
+## Version
+
+Targets @gorgonjs/gorgon v1.6.0.

package/skills/react/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: react
+description: >
+  React integration for @gorgonjs/gorgon via @gorgonjs/react: useGorgon hook
+  with data/error/loading/refetch state, clearGorgon helper for cache
+  invalidation from components, cache key management tied to component
+  lifecycle, and DIY hook patterns. Use when building React components
+  that need cached async data fetching.
+type: framework
+library: gorgon
+framework: react
+library_version: "1.6.0"
+requires:
+  - core
+sources:
+  - "mikevalstar/gorgon:clients/react/index.ts"
+  - "mikevalstar/gorgon:gorgonjs.dev/src/pages/docs/ui/react.md"
+---
+
+This skill builds on `core/SKILL.md`. Read the core skill first for cache key naming, policies, and clearing patterns.
+
+# Gorgon.js — React
+
+## Setup
+
+```bash
+npm install @gorgonjs/react @gorgonjs/gorgon
+```
+
+```typescript
+import { useGorgon, clearGorgon } from '@gorgonjs/react';
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data, error, loading, refetch } = useGorgon(
+    `user/${userId}`,
+    () => fetch(`/api/users/${userId}`).then(r => r.json()),
+    60 * 1000
+  );
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+## Hooks and Components
+
+### useGorgon hook
+
+```typescript
+const { data, error, loading, refetch } = useGorgon<R>(
+  key: string,
+  asyncFunc: () => Promise<R>,
+  policy?: GorgonPolicyInput,
+  options?: { debug?: boolean }
+);
+```
+
+Returns:
+- `data: R | null` — resolved data, null while loading
+- `error: Error | null` — error if the async function threw
+- `loading: boolean` — true while fetching
+- `refetch(opts?: { clearKey?: string }): void` — clears cache key and re-fetches
+
+The hook re-fetches when `key` changes. Include all dynamic parameters in the key.
+
+### clearGorgon helper
+
+```typescript
+import { clearGorgon } from '@gorgonjs/react';
+
+clearGorgon('user/*');  // clear keys matching pattern
+clearGorgon();          // clear all cached data
+```
+
+### Refetch with wildcard clearing
+
+```typescript
+const { data, refetch } = useGorgon(
+  `user/${userId}`,
+  () => fetchUser(userId),
+  60000
+);
+
+// Clear just this key and re-fetch
+const handleRefresh = () => refetch();
+
+// Clear all user keys and re-fetch this one
+const handleClearAll = () => refetch({ clearKey: 'user/*' });
+```
+
+## React-Specific Patterns
+
+### Typed data fetching in components
+
+```typescript
+import { useGorgon } from '@gorgonjs/react';
+
+interface Todo { id: number; title: string; completed: boolean; }
+
+function TodoItem({ id }: { id: number }) {
+  const { data, loading } = useGorgon<Todo>(
+    `todo/${id}`,
+    () => fetch(`/api/todos/${id}`).then(r => r.json()),
+    30000
+  );
+
+  if (loading || !data) return <span>Loading...</span>;
+  return <span>{data.title}</span>;
+}
+```
+
+### Invalidate on mutation
+
+```typescript
+function EditUser({ userId }: { userId: string }) {
+  const { data, refetch } = useGorgon(
+    `user/${userId}`,
+    () => fetchUser(userId),
+    60000
+  );
+
+  const handleSave = async (formData: UserUpdate) => {
+    await updateUser(userId, formData);
+    refetch(); // clears cache and re-renders with fresh data
+  };
+
+  return <UserForm data={data} onSave={handleSave} />;
+}
+```
+
+### DIY minimal hook (without @gorgonjs/react)
+
+```typescript
+import { useState, useEffect } from 'react';
+import Gorgon, { GorgonPolicyInput } from '@gorgonjs/gorgon';
+
+function useGorgon<R>(
+  key: string,
+  asyncFunc: () => Promise<R>,
+  policy?: GorgonPolicyInput
+): R | null {
+  const [data, setData] = useState<R | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+    Gorgon.get(key, asyncFunc, policy)
+      .then(result => { if (mounted) setData(result); })
+      .catch(err => console.error('Gorgon error', err));
+    return () => { mounted = false; };
+  }, [key]);
+
+  return data;
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Not including all dynamic params in the cache key
+
+Wrong:
+
+```typescript
+const { data } = useGorgon('user-profile', () => fetchUser(userId), 60000);
+```
+
+Correct:
+
+```typescript
+const { data } = useGorgon(`user/${userId}`, () => fetchUser(userId), 60000);
+```
+
+`useGorgon` re-fetches when the key changes. If dynamic parameters are not in the key, changing `userId` returns stale data from the previous user.
+
+Source: documentation — react
+
+### HIGH Using Gorgon.clear directly instead of refetch
+
+Wrong:
+
+```typescript
+const { data } = useGorgon('user/1', fetchUser, 60000);
+const handleUpdate = async () => {
+  await updateUser(1, newData);
+  Gorgon.clear('user/1'); // cache is cleared but component doesn't re-render
+};
+```
+
+Correct:
+
+```typescript
+const { data, refetch } = useGorgon('user/1', fetchUser, 60000);
+const handleUpdate = async () => {
+  await updateUser(1, newData);
+  refetch(); // clears cache AND triggers re-render
+};
+```
+
+`Gorgon.clear()` removes the cached value but does not trigger a React re-render. Use `refetch()` from the hook to clear and re-fetch in one step.
+
+Source: documentation — react
+
+### HIGH Missing cleanup in DIY hooks
+
+Wrong:
+
+```typescript
+useEffect(() => {
+  Gorgon.get(key, asyncFunc, policy).then(setData);
+}, [key]);
+```
+
+Correct:
+
+```typescript
+useEffect(() => {
+  let mounted = true;
+  Gorgon.get(key, asyncFunc, policy)
+    .then(result => { if (mounted) setData(result); });
+  return () => { mounted = false; };
+}, [key]);
+```
+
+Without the mounted guard, setting state after unmount causes React warnings and potential bugs with rapid navigation.
+
+Source: documentation — react
+
+### HIGH Tension: Cache duration vs data freshness
+
+When using `useGorgon`, the same tension from core caching applies in the UI: long TTLs show stale data to users, short TTLs cause excessive re-fetching and loading spinners. Pair appropriate TTLs with explicit `refetch()` calls on user-initiated mutations.
+
+See also: `core/SKILL.md` § Common Mistakes
+
+## Version
+
+Targets @gorgonjs/react with @gorgonjs/gorgon v1.6.0.