atomirx 0.0.7 → 0.1.0

package/skills/atomirx/references/hooks.md

@@ -0,0 +1,322 @@
+# Hooks — Creation Tracking & Error Handling
+
+## Overview
+
+| Hook           | Purpose                          | Fires When             |
+| -------------- | -------------------------------- | ---------------------- |
+| `onCreateHook` | Track atom/derived/effect/module | Primitive created      |
+| `onErrorHook`  | Global error handling            | Error in derived/effect|
+| `hook()`       | Create custom hooks              | N/A (factory)          |
+
+## CRITICAL: MUST Use .override()
+
+**NEVER** assign `.current` directly — breaks hook chain.
+
+```typescript
+// ❌ FORBIDDEN
+onCreateHook.current = (info) => { ... };
+
+// ✅ REQUIRED
+onCreateHook.override((prev) => (info) => {
+  prev?.(info);
+  // your code
+});
+
+onErrorHook.override((prev) => (info) => {
+  prev?.(info);
+  // your code
+});
+```
+
+## Hook API
+
+| Method       | Signature               | Description            |
+| ------------ | ----------------------- | ---------------------- |
+| `.current`   | `T \| undefined`        | Read-only value        |
+| `.override()`| `(reducer) => void`     | Set via reducer        |
+| `.reset()`   | `() => void`            | Reset to initial       |
+| `hook.use()` | `(setups[], fn) => T`   | Temporary hooks in fn  |
+
+## onCreateHook
+
+Fires on atom, derived, effect, module creation.
+
+### CreateInfo Types
+
+```typescript
+interface MutableCreateInfo {
+  type: "mutable";
+  key: string | undefined;
+  meta: MutableAtomMeta | undefined;
+  atom: MutableAtom<unknown>;
+}
+
+interface DerivedCreateInfo {
+  type: "derived";
+  key: string | undefined;
+  meta: DerivedAtomMeta | undefined;
+  atom: DerivedAtom<unknown, boolean>;
+}
+
+interface EffectCreateInfo {
+  type: "effect";
+  key: string | undefined;
+  meta: EffectMeta | undefined;
+  effect: Effect;
+}
+
+interface ModuleCreateInfo {
+  type: "module";
+  key: string | undefined;
+  meta: ModuleMeta | undefined;
+  module: unknown;
+}
+```
+
+### Use Cases
+
+#### DevTools Registry
+
+```typescript
+const registry = {
+  atoms: new Map(),
+  derived: new Map(),
+  effects: new Map(),
+  modules: new Map(),
+};
+
+onCreateHook.override((prev) => (info) => {
+  prev?.(info);
+  const key = info.key ?? `anon-${Date.now()}`;
+  switch (info.type) {
+    case "mutable": registry.atoms.set(key, info.atom); break;
+    case "derived": registry.derived.set(key, info.atom); break;
+    case "effect": registry.effects.set(key, info.effect); break;
+    case "module": registry.modules.set(key, info.module); break;
+  }
+});
+
+window.__ATOMIRX_DEVTOOLS__ = registry;
+```
+
+#### Persistence
+
+```typescript
+declare module "atomirx" {
+  interface MutableAtomMeta { persisted?: boolean; }
+}
+
+onCreateHook.override((prev) => (info) => {
+  prev?.(info);
+  if (info.type !== "mutable" || !info.meta?.persisted || !info.key) return;
+
+  const storageKey = `app:${info.key}`;
+
+  if (!info.atom.dirty()) {
+    const stored = localStorage.getItem(storageKey);
+    if (stored) try { info.atom.set(JSON.parse(stored)); } catch {}
+  }
+
+  info.atom.on(() => localStorage.setItem(storageKey, JSON.stringify(info.atom.get())));
+});
+
+// Usage
+const settings$ = atom({ theme: "dark" }, { meta: { key: "user.settings", persisted: true } });
+```
+
+#### Validation
+
+```typescript
+declare module "atomirx" {
+  interface MutableAtomMeta { validate?: (v: unknown) => boolean; }
+}
+
+onCreateHook.override((prev) => (info) => {
+  prev?.(info);
+  if (info.type !== "mutable" || !info.meta?.validate) return;
+
+  const validate = info.meta.validate;
+  const originalSet = info.atom.set.bind(info.atom);
+
+  info.atom.set = (valueOrReducer) => {
+    const next = typeof valueOrReducer === "function"
+      ? (valueOrReducer as Function)(info.atom.get())
+      : valueOrReducer;
+
+    if (!validate(next)) {
+      console.warn(`Validation failed for ${info.key}:`, next);
+      return;
+    }
+    originalSet(valueOrReducer);
+  };
+});
+```
+
+#### Debug Logging
+
+```typescript
+if (process.env.NODE_ENV === "development") {
+  onCreateHook.override((prev) => (info) => {
+    prev?.(info);
+    console.log(`[atomirx] Created ${info.type}: ${info.key ?? "anon"}`);
+  });
+}
+```
+
+## onErrorHook
+
+Fires on derived/effect errors.
+
+```typescript
+interface ErrorInfo {
+  source: CreateInfo;
+  error: unknown;
+}
+```
+
+### Use Cases
+
+#### Sentry
+
+```typescript
+onErrorHook.override((prev) => (info) => {
+  prev?.(info);
+  Sentry.captureException(info.error, {
+    tags: { source_type: info.source.type, source_key: info.source.key ?? "anon" },
+    extra: { meta: info.source.meta },
+  });
+});
+```
+
+#### Console
+
+```typescript
+onErrorHook.override((prev) => (info) => {
+  prev?.(info);
+  console.error(`[atomirx] Error in ${info.source.type}: ${info.source.key ?? "anon"}`, info.error);
+});
+```
+
+#### Toast
+
+```typescript
+onErrorHook.override((prev) => (info) => {
+  prev?.(info);
+  if (info.error instanceof UserFacingError) toast.error(info.error.message);
+});
+```
+
+## Custom Hooks
+
+```typescript
+const debugHook = hook(false);
+debugHook.current; // false
+debugHook.override(() => true);
+debugHook.current; // true
+debugHook.reset();
+debugHook.current; // false
+```
+
+### Temporary Hooks
+
+```typescript
+const loggerHook = hook<(msg: string) => void>();
+
+const result = hook.use(
+  [loggerHook(() => (msg) => console.log("[TEST]", msg))],
+  () => {
+    loggerHook.current?.("Inside hook.use()");
+    return "result";
+  }
+);
+
+loggerHook.current?.("Outside"); // Does nothing
+```
+
+## Testing (IMPORTANT)
+
+### Isolate Tests
+
+```typescript
+describe("MyStore", () => {
+  beforeEach(() => {
+    onCreateHook.reset();
+    onErrorHook.reset();
+  });
+
+  afterEach(() => {
+    onCreateHook.reset();
+    onErrorHook.reset();
+  });
+
+  it("should track created atoms", () => {
+    const created: string[] = [];
+    onCreateHook.override((prev) => (info) => {
+      prev?.(info);
+      if (info.key) created.push(info.key);
+    });
+
+    myStore();
+    expect(created).toContain("myStore.counter");
+  });
+});
+```
+
+### Verify Error Hook
+
+```typescript
+it("should call error hook", async () => {
+  const errors: ErrorInfo[] = [];
+  onErrorHook.override((prev) => (info) => { prev?.(info); errors.push(info); });
+
+  const buggy$ = derived(({ read }) => { throw new Error("test"); }, { meta: { key: "buggy" } });
+
+  try { await buggy$.get(); } catch {}
+
+  expect(errors).toHaveLength(1);
+  expect(errors[0].source.key).toBe("buggy");
+});
+```
+
+## Initialization Order (CRITICAL)
+
+**MUST** set up hooks BEFORE atoms are created:
+
+```typescript
+// src/app/init.ts
+import { onCreateHook, onErrorHook } from "atomirx";
+
+// 1. DevTools
+onCreateHook.override((prev) => (info) => {
+  prev?.(info);
+  window.__ATOMIRX_REGISTRY__?.add(info);
+});
+
+// 2. Error monitoring
+onErrorHook.override((prev) => (info) => {
+  prev?.(info);
+  Sentry.captureException(info.error);
+});
+
+// 3. Persistence
+onCreateHook.override((prev) => (info) => {
+  prev?.(info);
+  if (info.type === "mutable" && info.meta?.persisted) setupPersistence(info);
+});
+
+// src/app/main.tsx
+import "./init"; // Run first
+import { App } from "./App";
+```
+
+## Summary
+
+| Task                  | Hook           | Pattern                             |
+| --------------------- | -------------- | ----------------------------------- |
+| Track creation        | `onCreateHook` | `.override((prev) => (info) => {})` |
+| Global error logging  | `onErrorHook`  | `.override((prev) => (info) => {})` |
+| Persistence           | `onCreateHook` | Check `info.meta?.persisted`        |
+| Validation            | `onCreateHook` | Wrap `info.atom.set()`              |
+| DevTools              | `onCreateHook` | Register in global registry         |
+| Reset all             | Both           | `.reset()` in tests                 |
+| Temporary (tests)     | `hook.use()`   | `hook.use([setup], fn)`             |

package/skills/atomirx/references/pool-patterns.md

@@ -0,0 +1,229 @@
+# Pool Patterns
+
+Pool = collection of atoms indexed by params with automatic GC. Like `atomFamily` but with built-in GC and ScopedAtom safety.
+
+## Features
+
+| Feature         | Description                          |
+| --------------- | ------------------------------------ |
+| Auto GC         | Removed after `gcTime` of inactivity |
+| Promise-aware   | GC pauses while Promise pending      |
+| ScopedAtom      | Prevents stale reference leaks       |
+| Value API       | Public API uses values, not atoms    |
+| Reactive API    | `from(pool, params)` in selectors    |
+
+## Creating
+
+```typescript
+// Object params
+const userPool = pool((params: { id: string }) => fetchUser(params.id), {
+  gcTime: 60_000,
+  meta: { key: "users" },
+});
+
+// Primitive params
+const articlePool = pool((id: string) => fetchArticle(id), {
+  gcTime: 300_000,
+  meta: { key: "articles" },
+});
+
+// With context
+const dataPool = pool((params: { id: string }, ctx) => {
+  const controller = new AbortController();
+  ctx.onCleanup(() => controller.abort());
+  return fetchData(params.id, { signal: controller.signal });
+}, { gcTime: 60_000 });
+```
+
+## Options
+
+```typescript
+interface PoolOptions<P> {
+  gcTime: number;                // Required
+  equals?: Equality<P>;          // Default: "shallow"
+  meta?: { key?: string };
+}
+```
+
+## Public API (Value-based)
+
+```typescript
+const userPool = pool((id: string) => ({ name: "", email: "" }), { gcTime: 60_000 });
+
+userPool.get("user-1");           // Get/create
+userPool.set("user-1", { name: "John", email: "j@e.com" });
+userPool.set("user-1", (p) => ({ ...p, name: "Jane" })); // Reducer
+userPool.has("user-1");           // Check existence
+userPool.remove("user-1");        // Remove
+userPool.clear();                 // Clear all
+userPool.forEach((val, params) => console.log(params, val));
+
+// Subscribe
+const unsub = userPool.onChange((params, value) => console.log("Changed:", params));
+const unsub2 = userPool.onRemove((params, value) => console.log("Removed:", params));
+```
+
+## Reactive API (from())
+
+In `derived`, `effect`, `useSelector`:
+
+```typescript
+// derived
+const userPosts$ = derived(({ read, from }) => {
+  const user$ = from(userPool, "user-1");
+  return read(user$).posts;
+});
+
+// effect
+effect(({ read, from }) => {
+  const user$ = from(userPool, currentUserId);
+  console.log("User:", read(user$));
+});
+
+// useSelector
+const user = useSelector(({ read, from }) => {
+  const user$ = from(userPool, "user-1");
+  return read(user$);
+});
+```
+
+## ScopedAtom (CRITICAL)
+
+ScopedAtom is a temporary wrapper:
+- **ONLY** exists during select context
+- **THROWS** if accessed outside
+- **MUST** use with `read()`, **NEVER** with `.get()`
+
+```typescript
+// ❌ FORBIDDEN
+derived(({ from }) => {
+  const user$ = from(userPool, "user-1");
+  return user$.get(); // THROWS
+});
+
+// ❌ FORBIDDEN
+let cached: ScopedAtom<User>;
+derived(({ from }) => { cached = from(userPool, "user-1"); });
+cached._getAtom(); // THROWS after context ends
+
+// ✅ REQUIRED
+derived(({ read, from }) => {
+  const user$ = from(userPool, "user-1");
+  return read(user$);
+});
+```
+
+## GC Behavior
+
+Timer resets on: creation, value change, access.
+
+GC pauses while Promise pending:
+
+```typescript
+const asyncPool = pool((id: string) => fetchData(id), { gcTime: 5000 });
+asyncPool.get("1"); // Timer starts AFTER Promise resolves
+```
+
+## Params Equality
+
+Default `"shallow"` — order doesn't matter:
+
+```typescript
+const pool1 = pool((p: { a: number; b: number }) => p.a + p.b, { gcTime: 60_000 });
+pool1.get({ a: 1, b: 2 }); // Creates
+pool1.get({ b: 2, a: 1 }); // Same entry
+
+// Custom
+const pool2 = pool(
+  (p: { id: string; version?: number }) => fetchData(p.id, p.version),
+  { gcTime: 60_000, equals: (a, b) => a.id === b.id }
+);
+```
+
+## Common Patterns
+
+### Entity Cache
+
+```typescript
+const userCache = pool(
+  async (id: string) => (await fetch(`/api/users/${id}`)).json(),
+  { gcTime: 300_000, meta: { key: "userCache" } }
+);
+
+const user = useSelector(({ read, from }) => read(from(userCache, userId)));
+```
+
+### Form State per Entity
+
+```typescript
+const formPool = pool(
+  (entityId: string): FormState => ({ values: {}, errors: {}, dirty: false }),
+  { gcTime: 600_000, meta: { key: "forms" } }
+);
+
+formPool.set(entityId, (p) => ({
+  ...p,
+  values: { ...p.values, [field]: value },
+  dirty: true,
+}));
+```
+
+### Optimistic Updates
+
+```typescript
+async function updateUserName(id: string, name: string) {
+  userPool.set(id, (p) => ({ ...p, name })); // Optimistic
+  try {
+    await api.updateUser(id, { name });
+  } catch {
+    userPool.set(id, await fetchUser(id)); // Rollback
+    throw error;
+  }
+}
+```
+
+### Derived from Pool
+
+```typescript
+const currentUser$ = derived(({ read, ready, from }) => {
+  const userId = ready(currentUserId$);
+  const user$ = from(userPool, userId);
+  return read(user$);
+});
+```
+
+### Multiple Pools
+
+```typescript
+const userDashboard$ = derived(({ read, from, all }) => {
+  const userId = "user-1";
+  const user$ = from(userPool, userId);
+  const posts$ = from(postsPool, userId);
+  const [user, posts] = all([user$, posts$]);
+  return { user, posts };
+});
+```
+
+## Pool vs Manual Map
+
+| Feature        | pool()                   | Manual Map              |
+| -------------- | ------------------------ | ----------------------- |
+| GC             | Auto with `gcTime`       | Manual cleanup          |
+| Memory safety  | ScopedAtom prevents leaks| Easy to leak            |
+| Promise-aware  | GC waits for pending     | Manual handling         |
+| Events         | `onChange`, `onRemove`   | Implement manually      |
+| Reactive       | Works with `from()`      | Manual subscriptions    |
+| Testing        | Easy mock via `define()` | Harder isolation        |
+
+## When to Use
+
+✅ **Use pool:**
+- Parameterized state (users, articles, forms)
+- Entries with natural TTL (cache, session)
+- Reactive subscriptions per entry
+- Memory management matters
+
+❌ **NEVER use pool:**
+- Single global atom → use `atom`
+- State doesn't vary by key
+- Entries should NEVER be GC'd → use Map