atomirx 0.0.7 → 0.1.0

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

@@ -0,0 +1,188 @@
+# Async Patterns
+
+## Summary
+
+| Utility     | Input           | Output                 | Behavior                   |
+| ----------- | --------------- | ---------------------- | -------------------------- |
+| `all()`     | Array of atoms  | Array of values        | Waits for all              |
+| `any()`     | Record of atoms | `{ key, value }`       | First to resolve           |
+| `race()`    | Record of atoms | `{ key, value }`       | First to settle            |
+| `settled()` | Array of atoms  | Array of SettledResult | Waits for all settled      |
+| `and()`     | Array of conds  | boolean                | AND with short-circuit     |
+| `or()`      | Array of conds  | boolean                | OR with short-circuit      |
+
+## all() — Promise.all
+
+Waits for ALL atoms. Returns array.
+
+```typescript
+const dashboard$ = derived(({ all }) => {
+  const [user, posts, comments] = all([user$, posts$, comments$]);
+  return { user, posts, comments };
+});
+```
+
+**Use when:** Need all data before rendering.
+
+## any() — Promise.any
+
+Returns first resolved. Uses object for key identification.
+
+```typescript
+const data$ = derived(({ any }) => {
+  const result = any({ primary: primaryApi$, fallback: fallbackApi$ });
+  // result: { key: "primary" | "fallback", value: T }
+  return result.value;
+});
+```
+
+**Use when:** Multiple redundant sources, want fastest.
+
+## race() — Promise.race
+
+Returns first settled (ready OR error). Uses object.
+
+```typescript
+const data$ = derived(({ race }) => {
+  const result = race({ cache: cache$, api: api$ });
+  return result.value;
+});
+```
+
+**Use when:** Show whatever resolves first.
+
+## settled() — Promise.allSettled
+
+Returns status for each. Waits until all settled.
+
+```typescript
+const results$ = derived(({ settled }) => {
+  const [userResult, postsResult] = settled([user$, posts$]);
+  return {
+    user: userResult.status === "ready" ? userResult.value : null,
+    posts: postsResult.status === "ready" ? postsResult.value : [],
+    hasErrors: userResult.status === "error" || postsResult.status === "error",
+  };
+});
+```
+
+**Use when:** Handle partial failures gracefully.
+
+### SettledResult Type
+
+```typescript
+type SettledResult<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown };
+```
+
+## state() — No Throwing
+
+Get state without Suspense.
+
+```typescript
+const data$ = derived(({ state }) => {
+  const userState = state(user$);
+  if (userState.status === "loading") return { loading: true };
+  if (userState.status === "error") return { error: userState.error };
+  return { user: userState.value };
+});
+```
+
+### AtomState Type
+
+```typescript
+type AtomState<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown }
+  | { status: "loading"; promise: Promise<T> };
+```
+
+## Combining Patterns
+
+### Graceful Degradation
+
+```typescript
+const dashboard$ = derived(({ read, settled }) => {
+  const user = read(user$); // Required
+
+  const [analyticsResult, notificationsResult] = settled([analytics$, notifications$]);
+
+  return {
+    user,
+    analytics: analyticsResult.status === "ready" ? analyticsResult.value : null,
+    notifications: notificationsResult.status === "ready" ? notificationsResult.value : [],
+    warnings: [analyticsResult, notificationsResult]
+      .filter((r) => r.status === "error")
+      .map((r) => r.error),
+  };
+});
+```
+
+### Cache-First
+
+```typescript
+const article$ = derived(({ race }) => {
+  const result = race({ cache: cachedArticle$, network: fetchedArticle$ });
+  console.log(`From: ${result.key}`);
+  return result.value;
+});
+```
+
+### Parallel Loading
+
+```typescript
+const [user, posts, comments] = useSelector(({ all }) =>
+  all([user$, posts$, comments$])
+);
+```
+
+## and() — Logical AND
+
+Short-circuit. Returns true if ALL truthy.
+
+```typescript
+const canEdit$ = derived(({ and }) => and([isLoggedIn$, hasPermission$]));
+
+// Lazy evaluation
+const canDelete$ = derived(({ and }) => and([
+  isLoggedIn$,
+  () => hasDeletePermission$, // Only if logged in
+]));
+```
+
+### Condition Types
+
+```typescript
+type Condition =
+  | boolean              // Static
+  | Atom<unknown>        // Always read
+  | (() => boolean | Atom<unknown>); // Lazy
+```
+
+## or() — Logical OR
+
+Short-circuit. Returns true if ANY truthy.
+
+```typescript
+const hasData$ = derived(({ or }) => or([cacheData$, apiData$]));
+
+// Lazy fallback
+const data$ = derived(({ or }) => or([
+  () => primaryData$,
+  () => fallbackData$,
+]));
+```
+
+## Boolean + Async
+
+```typescript
+// (A && B) || C
+const result$ = derived(({ or, and }) => or([and([a$, b$]), c$]));
+
+// Guard expensive ops
+const data$ = derived(({ and, read }) => {
+  if (!and([isLoggedIn$, hasPermission$])) return null;
+  return read(expensiveData$);
+});
+```

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

@@ -0,0 +1,238 @@
+# Atom Patterns
+
+## Overview
+
+```typescript
+const count$ = atom(0);
+const user$ = atom<User | null>(null, { meta: { key: "auth.user" } });
+const data$ = atom(() => expensiveInit());
+```
+
+## Core API
+
+| Method       | Signature                  | Description              |
+| ------------ | -------------------------- | ------------------------ |
+| `get()`      | `() => T`                  | Get current value        |
+| `set()`      | `(value \| reducer)`       | Update value             |
+| `reset()`    | `() => void`               | Reset to initial         |
+| `dirty()`    | `() => boolean`            | Changed since init/reset |
+| `on()`       | `(listener) => unsub`      | Subscribe to changes     |
+| `_dispose()` | `() => void`               | Cleanup (used by pool)   |
+
+## Lazy Initialization
+
+```typescript
+const config$ = atom(() => parseExpensiveConfig());
+
+// reset() re-runs initializer
+const timestamp$ = atom(() => Date.now());
+timestamp$.reset(); // New timestamp
+
+// Store function as value
+const callback$ = atom(() => () => console.log("hello"));
+```
+
+## Dirty Tracking
+
+```typescript
+const form$ = atom({ name: "", email: "" }, { meta: { key: "form" } });
+
+form$.dirty(); // false
+form$.set({ name: "John", email: "" });
+form$.dirty(); // true
+form$.reset();
+form$.dirty(); // false
+```
+
+```tsx
+function FormButtons() {
+  const isDirty = useSelector(() => form$.dirty());
+  return (
+    <div>
+      <button disabled={!isDirty}>Save</button>
+      <button onClick={() => form$.reset()}>Reset</button>
+    </div>
+  );
+}
+```
+
+## AtomContext — Signal & Cleanup
+
+Lazy initializer receives context:
+
+```typescript
+interface AtomContext {
+  signal: AbortSignal;           // Aborted on set()/reset()
+  onCleanup(fn: VoidFunction): void; // Runs on value change
+}
+```
+
+### Abort Signal
+
+```typescript
+const data$ = atom((ctx) => {
+  const controller = new AbortController();
+  ctx.signal.addEventListener("abort", () => controller.abort());
+  return fetch("/api/data", { signal: controller.signal });
+});
+
+data$.set(fetch("/api/data/new")); // Previous fetch aborted
+```
+
+### Cleanup
+
+```typescript
+const subscription$ = atom((ctx) => {
+  const sub = websocket.subscribe("channel");
+  ctx.onCleanup(() => sub.unsubscribe());
+  return sub;
+});
+
+subscription$.reset(); // Unsubscribes, creates new
+```
+
+### Combined
+
+```typescript
+const realtime$ = atom((ctx) => {
+  const socket = new WebSocket("wss://api.example.com");
+  ctx.onCleanup(() => socket.close());
+  fetchInitialData({ signal: ctx.signal });
+  return socket;
+});
+```
+
+## Equality Options
+
+```typescript
+// Default: strict (Object.is)
+const count$ = atom(0);
+
+// Shallow
+const user$ = atom({ name: "", email: "" }, { equals: "shallow" });
+user$.set((prev) => ({ ...prev })); // No notification
+
+// Deep
+const config$ = atom({ nested: { value: 1 } }, { equals: "deep" });
+
+// Custom
+const data$ = atom(
+  { id: 1, timestamp: Date.now() },
+  { equals: (a, b) => a.id === b.id }
+);
+```
+
+| Shorthand    | Description                  |
+| ------------ | ---------------------------- |
+| `"strict"`   | Object.is (default, fastest) |
+| `"shallow"`  | Compare keys with Object.is  |
+| `"shallow2"` | 2 levels deep                |
+| `"shallow3"` | 3 levels deep                |
+| `"deep"`     | Full recursive (slowest)     |
+
+## readonly() (REQUIRED)
+
+**MUST** expose atoms as read-only:
+
+```typescript
+const myModule = define(() => {
+  const count$ = atom(0, { meta: { key: "counter" } });
+
+  return {
+    count$: readonly(count$), // Consumers can't set()
+    increment: () => count$.set((p) => p + 1),
+  };
+});
+
+// Usage
+const { count$, increment } = myModule();
+count$.get();   // ✅ OK
+count$.set(5);  // ❌ TypeScript error
+increment();    // ✅ Use action
+```
+
+Multiple atoms:
+
+```typescript
+return { ...readonly({ count$, name$ }), setName: (n) => name$.set(n) };
+```
+
+## Async Values
+
+Atom stores Promises as-is:
+
+```typescript
+const posts$ = atom(fetchPosts());
+posts$.get(); // Promise<Post[]>
+posts$.set(fetchPosts()); // Store new Promise
+
+// With lazy init
+const lazyPosts$ = atom(() => fetchPosts());
+lazyPosts$.reset(); // Refetches
+```
+
+**Note:** Use `derived()` with `read()` for automatic Promise unwrapping and Suspense.
+
+## Plugin System (.use())
+
+```typescript
+const count$ = atom(0)
+  .use((src) => ({ ...src, double: () => src.get() * 2 }))
+  .use((src) => ({ ...src, triple: () => src.get() * 3 }));
+
+count$.double(); // 0
+count$.triple(); // 0
+```
+
+## Common Patterns
+
+### Form State
+
+```typescript
+const form$ = atom<FormState>(
+  { values: {}, errors: {}, touched: {} },
+  { meta: { key: "contactForm" }, equals: "shallow" }
+);
+
+const setField = (name: string, value: string) => {
+  form$.set((p) => ({
+    ...p,
+    values: { ...p.values, [name]: value },
+    touched: { ...p.touched, [name]: true },
+  }));
+};
+```
+
+### Cache with Expiration
+
+```typescript
+const cache$ = atom((ctx) => {
+  const data = new Map<string, unknown>();
+  const timeout = setTimeout(() => data.clear(), 300_000);
+  ctx.onCleanup(() => clearTimeout(timeout));
+  return data;
+});
+```
+
+### WebSocket
+
+```typescript
+const ws$ = atom((ctx) => {
+  const socket = new WebSocket("wss://api.example.com");
+  socket.onopen = () => console.log("Connected");
+  ctx.onCleanup(() => socket.close());
+  return socket;
+});
+
+ws$.reset(); // Closes old, creates new
+```
+
+## When to Use
+
+| Use Case                | MutableAtom | Derived |
+| ----------------------- | ----------- | ------- |
+| User input/form state   | ✅          | ❌      |
+| API response storage    | ✅          | ❌      |
+| Computed from atoms     | ❌          | ✅      |
+| Transformed async data  | ❌          | ✅      |
+| Cached calculations     | ❌          | ✅      |

package/skills/atomirx/references/deferred-loading.md

@@ -0,0 +1,191 @@
+# Deferred Loading with ready()
+
+## The Problem
+
+When atom value is `undefined`/`null` during initialization:
+
+```typescript
+// ❌ Problem: id starts undefined
+const currentUserId$ = atom<string | undefined>(undefined);
+
+const userProfile$ = derived(({ read, from }) => {
+  const userId = read(currentUserId$); // undefined initially
+  const user$ = from(userPool, userId); // Error: can't create entry
+  return read(user$);
+});
+```
+
+## Solution: ready()
+
+`ready()` returns `never` when value is `undefined`/`null`, blocking computation until value exists:
+
+```typescript
+// ✅ Correct
+const userProfile$ = derived(({ read, ready, from }) => {
+  const userId = ready(currentUserId$); // Blocks until truthy
+  const user$ = from(userPool, userId);
+  return read(user$);
+});
+```
+
+## How It Works
+
+| Input                         | Output          |
+| ----------------------------- | --------------- |
+| `ready(atom<T \| undefined>)` | `T` when truthy |
+| Value is `undefined`/`null`   | Returns `never` |
+| Value is truthy               | Returns `T`     |
+
+```typescript
+const id$ = atom<string | undefined>(undefined);
+
+derived(({ ready }) => {
+  const id = ready(id$);
+  //    ^? string (not string | undefined)
+  return fetchUser(id);
+});
+```
+
+## Behavior
+
+```typescript
+const userId$ = atom<string | undefined>(undefined);
+
+const profile$ = derived(({ read, ready, from }) => {
+  const userId = ready(userId$);
+  const user$ = from(userPool, userId);
+  return read(user$);
+});
+
+// Initially:
+profile$.get(); // Promise never resolves (blocked)
+profile$.staleValue; // fallback if set, else undefined
+
+// After:
+userId$.set("user-123");
+await profile$.get(); // { name: "John", ... }
+```
+
+## Use Cases
+
+### Pool with Optional Params
+
+```typescript
+const currentEntityId$ = atom<string | undefined>(undefined);
+
+const entityDetails$ = derived(({ read, ready, from }) => {
+  const id = ready(currentEntityId$);
+  const entity$ = from(entityPool, id);
+  return read(entity$);
+}, { fallback: null });
+```
+
+### Dependent Computation
+
+```typescript
+const config$ = atom<Config | null>(null);
+const apiUrl$ = atom<string | undefined>(undefined);
+
+const data$ = derived(({ read, ready }) => {
+  const config = ready(config$);
+  const url = ready(apiUrl$);
+  return read(atom(() => fetch(`${url}/data?version=${config.version}`)));
+});
+```
+
+### Conditional UI
+
+```typescript
+function UserDashboard() {
+  const user = useSelector(({ read, ready }) => {
+    return ready(currentUser$);
+  });
+
+  return <Dashboard user={user} />;
+}
+
+// With state() fallback
+function UserCard() {
+  const result = useSelector(({ state }) => state(currentUser$));
+
+  if (result.status === "loading") return <Skeleton />;
+  if (result.status === "error") return <Error />;
+  if (!result.value) return <LoginPrompt />;
+  return <Card user={result.value} />;
+}
+```
+
+### Effect with Guard
+
+```typescript
+effect(({ read, ready }) => {
+  const userId = ready(currentUserId$);
+  analytics.identify(userId);
+}, { meta: { key: "analytics.identify" } });
+```
+
+### Multi-ready
+
+```typescript
+const report$ = derived(({ read, ready, from }) => {
+  const userId = ready(currentUserId$);
+  const projectId = ready(currentProjectId$);
+  const teamId = ready(currentTeamId$);
+
+  const user$ = from(userPool, userId);
+  const project$ = from(projectPool, projectId);
+  const team$ = from(teamPool, teamId);
+
+  const [user, project, team] = [read(user$), read(project$), read(team$)];
+  return { user, project, team };
+});
+```
+
+## ready() vs Manual Check
+
+```typescript
+// ❌ Verbose, TypeScript still sees string | undefined
+const profile$ = derived(({ read }) => {
+  const id = read(currentUserId$);
+  if (!id) return null;
+  return read(from(userPool, id)); // Type: still string | undefined
+});
+
+// ✅ Concise, TypeScript narrows to string
+const profile$ = derived(({ ready, read, from }) => {
+  const id = ready(currentUserId$);
+  //    ^? string
+  return read(from(userPool, id));
+});
+```
+
+## With Suspense
+
+```tsx
+function EntityPage() {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <EntityDetails />
+    </Suspense>
+  );
+}
+
+function EntityDetails() {
+  const entity = useSelector(({ read, ready, from }) => {
+    const id = ready(currentEntityId$); // Suspends until ID set
+    return read(from(entityPool, id));
+  });
+
+  return <Details entity={entity} />;
+}
+```
+
+## Summary
+
+| Scenario                        | Solution                    |
+| ------------------------------- | --------------------------- |
+| Pool with optional params       | `ready(params$)` + `from()` |
+| Dependent chains                | `ready()` per dependency    |
+| Wait for auth state             | `ready(currentUser$)`       |
+| Multi-value gate                | Multiple `ready()` calls    |
+| Type narrowing                  | `ready()` removes `null`    |