atomirx 0.0.8 → 0.1.1

package/skills/atomirx/references/rules.md

@@ -0,0 +1,407 @@
+# Rules & Best Practices
+
+## Service vs Store (CRITICAL)
+
+**All state/logic MUST use `define()`. Services = stateless. Stores = atoms.**
+
+| Type        | Purpose        | Variable      | File              | Contains                |
+| ----------- | -------------- | ------------- | ----------------- | ----------------------- |
+| **Service** | Stateless I/O  | `authService` | `auth.service.ts` | Pure functions          |
+| **Store**   | Reactive state | `authStore`   | `auth.store.ts`   | Atoms, derived, effects |
+
+### Service
+
+```typescript
+export const authService = define(
+  (): AuthService => ({
+    checkSupport: async () => {
+      /* WebAuthn API */
+    },
+    register: async (opts) => {
+      /* credential creation */
+    },
+    authenticate: async (opts) => {
+      /* credential assertion */
+    },
+  })
+);
+```
+
+### Store
+
+```typescript
+import { authService } from "@/services/auth/auth.service";
+
+export const authStore = define(() => {
+  const auth = authService(); // Inject via invocation
+
+  const user$ = atom<User | null>(null, { meta: { key: "auth.user" } });
+  const isAuthenticated$ = derived(({ read }) => read(user$) !== null, {
+    meta: { key: "auth.isAuthenticated" },
+  });
+
+  return {
+    ...readonly({ user$, isAuthenticated$ }),
+    login: async () => {
+      const result = await auth.authenticate({});
+      if (result.success) user$.set(result.user);
+    },
+  };
+});
+```
+
+### FORBIDDEN: Factory Pattern
+
+```typescript
+// ❌ FORBIDDEN
+let instance: AuthService | null = null;
+export function getAuthService(): AuthService {
+  if (!instance) instance = createAuthService();
+  return instance;
+}
+
+import { getAuthService } from "@/services/auth";
+const auth = getAuthService(); // WRONG
+
+// ✅ REQUIRED
+import { authService } from "@/services/auth/auth.service";
+const auth = authService(); // Module invocation
+```
+
+**Detection:** `get*Service()`, `create*Service()`, `*Factory()` → STOP, refactor to `define()`.
+
+| Factory Pattern | Module Pattern (`define()`) |
+| --------------- | --------------------------- |
+| Not mockable    | `service.override(mock)`    |
+| Hidden deps     | Explicit dependencies       |
+| No lazy control | Lazy singleton default      |
+| Breaks DI       | Uses atomirx DI             |
+
+## useSelector Grouping (CRITICAL)
+
+**MUST group multiple reads into single `useSelector`.**
+
+```tsx
+// ✅ DO
+const { count, user, settings } = useSelector(({ read }) => ({
+  count: read(count$),
+  user: read(user$),
+  settings: read(settings$),
+}));
+
+// ❌ DON'T
+const count = useSelector(count$);
+const user = useSelector(user$);
+const settings = useSelector(settings$);
+```
+
+| Multiple Calls      | Single Grouped   |
+| ------------------- | ---------------- |
+| N subscriptions     | 1 subscription   |
+| N checks per change | 1 check          |
+| Scattered values    | Related together |
+
+**Single `useSelector(atom$)` OK when:** only one atom needed.
+
+## useAction with Atom Deps
+
+**Pass atoms to `deps`, use `.get()` inside for auto re-dispatch.**
+
+```tsx
+// ✅ DO
+const load = useAction(
+  async () => {
+    const val1 = atom1$.get();
+    const val2 = await atom2$.get();
+    return val1 + val2;
+  },
+  { deps: [atom1$, atom2$], lazy: false }
+);
+
+// ❌ DON'T
+const { val1, val2 } = useSelector(({ read }) => ({
+  val1: read(atom1$), // Suspends before useAction
+  val2: read(atom2$),
+}));
+const load = useAction(async () => val1 + val2, {
+  deps: [val1, val2],
+  lazy: false,
+});
+```
+
+## define() Isolation (CRITICAL)
+
+**MUST use `define()` for all state/logic.**
+
+```typescript
+// ✅ DO
+export const counterStore = define(() => {
+  const storage = storageService();
+  const count$ = atom(0, { meta: { key: "counter.count" } });
+
+  return {
+    ...readonly({ count$ }),
+    increment: () => count$.set((x) => x + 1),
+    save: () => storage.set("count", count$.get()),
+  };
+});
+
+// ❌ DON'T
+const count$ = atom(0); // Global, not testable
+```
+
+| Benefit         | Description                     |
+| --------------- | ------------------------------- |
+| Testing/Mocking | Override for unit tests         |
+| Lazy init       | Only when first accessed        |
+| DI              | Depend on services/stores       |
+| Environment     | Override per platform           |
+| Encapsulation   | `readonly()` prevents mutations |
+
+### Override Pattern
+
+```typescript
+const storageService = define((): StorageService => {
+  throw new Error("Not implemented");
+});
+
+// Platform implementations
+const webStorage = define(
+  (): StorageService => ({
+    get: (key) => localStorage.getItem(key),
+    set: (key, val) => localStorage.setItem(key, val),
+  })
+);
+
+// Override based on environment
+if (isWeb) storageService.override(webStorage);
+
+// In tests
+storageService.override(() => ({
+  get: jest.fn(),
+  set: jest.fn(),
+}));
+```
+
+## batch() for Multiple Updates
+
+**MUST wrap multiple updates in `batch()`.**
+
+```typescript
+// ✅ DO
+batch(() => {
+  user$.set(newUser);
+  settings$.set(newSettings);
+  lastUpdated$.set(Date.now());
+}); // Single notification
+
+// ❌ DON'T
+user$.set(newUser); // Notification 1
+settings$.set(newSettings); // Notification 2
+lastUpdated$.set(Date.now()); // Notification 3
+```
+
+| Without batch       | With batch       |
+| ------------------- | ---------------- |
+| N notifications     | 1 notification   |
+| Intermediate states | Only final state |
+| UI flicker          | Clean update     |
+
+## Single Effect, Single Workflow (CRITICAL)
+
+**Each effect = ONE workflow. Split multiple workflows.**
+
+```typescript
+// ❌ WRONG
+effect(({ read }) => {
+  const id = read(currentId$);
+  const filter = read(filter$);
+  fetchEntity(id); // Workflow 1
+  localStorage.setItem("filter", filter); // Workflow 2
+  trackPageView(id); // Workflow 3
+});
+
+// ✅ CORRECT
+effect(
+  ({ read }) => {
+    const id = read(currentId$);
+    if (id) fetchEntity(id);
+  },
+  { meta: { key: "fetch.entity" } }
+);
+
+effect(
+  ({ read }) => {
+    localStorage.setItem("filter", read(filter$));
+  },
+  { meta: { key: "persist.filter" } }
+);
+
+effect(
+  ({ read }) => {
+    const id = read(currentId$);
+    if (id) trackPageView(id);
+  },
+  { meta: { key: "analytics.pageView" } }
+);
+```
+
+| Multiple Workflows | Single Workflow      |
+| ------------------ | -------------------- |
+| Hard to trace      | Clear cause → effect |
+| Combined triggers  | Independent          |
+| Hard to test       | Test in isolation    |
+| Hard to disable    | Comment one effect   |
+
+## meta.key (CRITICAL)
+
+**MUST define for ALL atoms, derived, effects.**
+
+```typescript
+// ✅ CORRECT
+const user$ = atom<User | null>(null, { meta: { key: "auth.user" } });
+const isAuth$ = derived(({ read }) => read(user$) !== null, {
+  meta: { key: "auth.isAuthenticated" },
+});
+effect(({ read }) => analytics.identify(read(user$)?.id), {
+  meta: { key: "auth.identifyUser" },
+});
+
+// ❌ WRONG
+const user$ = atom<User | null>(null);
+const isAuth$ = derived(({ read }) => read(user$) !== null);
+```
+
+| Pattern             | Example                |
+| ------------------- | ---------------------- |
+| `store.atomName`    | `auth.user`            |
+| `store.derivedName` | `auth.isAuthenticated` |
+| `store.effectName`  | `sync.autoSave`        |
+
+## Atom Storage
+
+**NEVER store atoms in component scope.**
+
+```typescript
+// ❌ BAD - memory leak
+function Component() {
+  const data$ = useRef(atom(0)).current;
+}
+
+// ✅ GOOD
+const dataStore = define(() => {
+  const data$ = atom(0, { meta: { key: "data" } });
+  return { ...readonly({ data$ }), update: (v) => data$.set(v) };
+});
+```
+
+## Mutation Co-location
+
+**All mutations MUST be in the store that owns the atom.**
+
+```typescript
+// ✅ CORRECT
+const counterStore = define(() => {
+  const count$ = atom(0, { meta: { key: "counter.count" } });
+  return {
+    ...readonly({ count$ }),
+    increment: () => count$.set((p) => p + 1),
+    decrement: () => count$.set((p) => p - 1),
+    reset: () => count$.reset(),
+  };
+});
+
+// ❌ WRONG
+const { count$ } = counterStore();
+count$.set(10); // External mutation
+```
+
+## SelectContext: Sync Only
+
+**All context methods MUST be called synchronously.**
+
+```typescript
+// ❌ WRONG
+derived(({ read }) => {
+  setTimeout(() => read(atom$), 100); // Error
+  return "value";
+});
+
+// ✅ CORRECT
+effect(({ read }) => {
+  const config = read(config$);
+  setTimeout(() => {
+    const data = myAtom$.get(); // Use .get() for async
+    console.log(data);
+  }, 100);
+});
+```
+
+## Error Handling: safe() Not try/catch
+
+**NEVER try/catch with read() — breaks Suspense.**
+
+```typescript
+// ❌ WRONG
+derived(({ read }) => {
+  try {
+    return read(asyncAtom$);
+  } catch (e) {
+    return null; // Catches Promise!
+  }
+});
+
+// ✅ CORRECT
+derived(({ read, safe }) => {
+  const [err, value] = safe(() => read(asyncAtom$));
+  if (err) return { error: err.message };
+  return { value };
+});
+```
+
+## Naming Conventions
+
+```typescript
+// All atoms: $ suffix
+const count$ = atom(0);
+const user$ = atom<User | null>(null);
+const productList$ = atom(fetchProducts()); // Async — still just $
+const config$ = atom(loadConfig());
+
+// Derived: $ suffix
+const doubled$ = derived(({ read }) => read(count$) * 2);
+const userName$ = derived(({ read }) => read(user$).name);
+
+// Services: *Service (NO atoms)
+const authService = define((): AuthService => ...);
+
+// Stores: *Store (HAS atoms)
+const authStore = define(() => ...);
+
+// Actions: verb-led
+navigateTo, invalidate, refresh, fetchUser, logout
+```
+
+| Type                 | Suffix    | Example                  |
+| -------------------- | --------- | ------------------------ |
+| Atom (sync or async) | `$`       | `count$`, `productList$` |
+| Derived              | `$`       | `doubled$`, `userName$`  |
+| Pool                 | `Pool`    | `userPool`               |
+| Service              | `Service` | `authService`            |
+| Store                | `Store`   | `authStore`              |
+
+**Why no `Async$`?** Atomirx abstracts async/sync — you don't care in SelectContext (Suspense handles it), and services receive values as parameters.
+
+### File Structure
+
+```
+src/
+├── services/           # Stateless
+│   ├── auth/
+│   │   └── auth.service.ts
+│   └── crypto/
+│       └── crypto.service.ts
+└── stores/             # Stateful
+    ├── auth.store.ts
+    └── todos.store.ts
+```

package/skills/atomirx/references/select-context.md

@@ -0,0 +1,309 @@
+# SelectContext API
+
+SelectContext provides methods for `derived`, `effect`, `useSelector`, and `rx`.
+
+## Methods
+
+| Method          | Returns                    | Description                    |
+| --------------- | -------------------------- | ------------------------------ |
+| `read(atom)`    | `T`                        | Get value, suspends if loading |
+| `ready(atom)`   | `T` (non-nullable)         | Block until truthy             |
+| `state(atom)`   | `AtomState<T>`             | Get state without suspending   |
+| `untrack(atom)` | `T`                        | Read without tracking dep      |
+| `untrack(fn)`   | `T`                        | Execute fn without tracking    |
+| `safe(fn)`      | `[error?, value?]`         | Catch errors, rethrow Promise  |
+| `all(atoms)`    | `T[]`                      | Wait for all                   |
+| `any(record)`   | `{ key, value }`           | First to resolve               |
+| `race(record)`  | `{ key, value }`           | First to settle                |
+| `settled()`     | `SettledResult<T>[]`       | All with status                |
+| `from(pool)`    | `ScopedAtom<T>`            | Get atom from pool             |
+| `track(atom)`   | `void`                     | Track without reading          |
+| `and(conds)`    | `boolean`                  | Logical AND                    |
+| `or(conds)`     | `boolean`                  | Logical OR                     |
+
+## CRITICAL Rules
+
+### Sync Access Only
+
+**All methods MUST be called synchronously:**
+
+```typescript
+// ❌ FORBIDDEN
+derived(({ read }) => {
+  setTimeout(() => read(atom$), 100); // Throws
+  return "value";
+});
+
+// ✅ REQUIRED
+derived(({ read }) => {
+  const value = read(atom$); // Sync call
+  return value;
+});
+```
+
+### read() + Suspense
+
+`read()` suspends (throws Promise) when atom loading:
+
+```tsx
+// Wrap with Suspense
+<Suspense fallback={<Loading />}>
+  <Component />
+</Suspense>
+
+function Component() {
+  const data = useSelector(({ read }) => read(asyncAtom$)); // May suspend
+  return <div>{data}</div>;
+}
+```
+
+### from() Returns ScopedAtom
+
+**MUST use with `read()`, NEVER `.get()`:**
+
+```typescript
+// ❌ FORBIDDEN
+derived(({ from }) => {
+  const user$ = from(userPool, "user-1");
+  return user$.get(); // THROWS
+});
+
+// ✅ REQUIRED
+derived(({ read, from }) => {
+  const user$ = from(userPool, "user-1");
+  return read(user$);
+});
+```
+
+### untrack() — Read Without Tracking
+
+**Read atoms or execute functions without creating dependencies.**
+
+Use `untrack()` when you need a value but don't want re-computation when it changes.
+
+```typescript
+// Form 1: Pass atom directly
+const combined$ = derived(({ read, untrack }) => {
+  const count = read(count$);       // ✅ Tracked — re-computes on change
+  const config = untrack(config$);  // ❌ NOT tracked — no re-compute
+  return count * config.multiplier;
+});
+
+// Form 2: Pass function for multiple reads
+const snapshot$ = derived(({ read, untrack }) => {
+  const liveData = read(liveData$);  // Tracked
+  const snapshot = untrack(() => {
+    // None of these create dependencies
+    return { a: read(a$), b: read(b$), c: read(c$) };
+  });
+  return { liveData, snapshot };
+});
+```
+
+**When to use:**
+
+| Scenario | Use |
+| -------- | --- |
+| Need latest value, re-compute on change | `read()` |
+| Need value once, ignore future changes | `untrack()` |
+| Initial value / config that rarely changes | `untrack()` |
+| Snapshot of multiple atoms | `untrack(() => ...)` |
+
+**Flow Diagram:**
+
+```
+untrack(input)
+      │
+      ▼
+  Is input an Atom?
+      │
+  ┌───┴───┐
+  │Yes    │No (function)
+  ▼       ▼
+ Read    Disable tracking
+ value    │
+ (no      ▼
+ track)  Execute fn()
+  │       │
+  │       ▼
+  │      Re-enable tracking
+  │       │
+  └───────┴──→ Return value
+```
+
+## Type Definitions
+
+```typescript
+interface SelectContext {
+  read<T>(atom: ReadableAtom<T>): T;
+  ready<T>(atom: ReadableAtom<T | undefined | null>): T;
+  state<T>(atom: ReadableAtom<T>): AtomState<T>;
+  untrack<T>(atom: ReadableAtom<T>): T;
+  untrack<T>(fn: () => T): T;
+  safe<T>(fn: () => T): [unknown, undefined] | [undefined, T];
+  all<T extends readonly ReadableAtom<unknown>[]>(atoms: T): MapAtomValues<T>;
+  any<T extends Record<string, ReadableAtom<unknown>>>(atoms: T): { key: keyof T; value: T[keyof T] };
+  race<T extends Record<string, ReadableAtom<unknown>>>(atoms: T): { key: keyof T; value: T[keyof T] };
+  settled<T extends readonly ReadableAtom<unknown>[]>(atoms: T): MapSettledResults<T>;
+  from<P, T>(pool: Pool<P, T>, params: P): ScopedAtom<T>;
+  track(atom: ReadableAtom<unknown>): void;
+  and(conditions: Condition[]): boolean;
+  or(conditions: Condition[]): boolean;
+}
+
+type AtomState<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown }
+  | { status: "loading"; promise: Promise<T> };
+
+type SettledResult<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown };
+
+type Condition = boolean | ReadableAtom<unknown> | (() => boolean | ReadableAtom<unknown>);
+```
+
+## EffectContext
+
+Effects get additional methods:
+
+```typescript
+interface EffectContext extends SelectContext {
+  onCleanup: (fn: VoidFunction) => void;
+  signal: AbortSignal;
+}
+```
+
+## Usage in Primitives
+
+### derived
+
+```typescript
+const doubled$ = derived(({ read }) => read(count$) * 2);
+
+const combined$ = derived(({ all }) => {
+  const [a, b, c] = all([atom1$, atom2$, atom3$]);
+  return a + b + c;
+});
+
+const guarded$ = derived(({ ready, read, from }) => {
+  const id = ready(currentId$);
+  return read(from(userPool, id));
+});
+```
+
+### effect
+
+```typescript
+effect(({ read, onCleanup, signal }) => {
+  const id = read(userId$);
+  
+  fetch(`/api/user/${id}`, { signal })
+    .then(r => r.json())
+    .then(data => userDetails$.set(data))
+    .catch(err => {
+      if (err.name !== "AbortError") console.error(err);
+    });
+
+  const sub = eventBus.subscribe("update", handler);
+  onCleanup(() => sub.unsubscribe());
+}, { meta: { key: "fetch.user" } });
+```
+
+### useSelector
+
+```tsx
+const data = useSelector(({ read, safe }) => {
+  const [err, value] = safe(() => JSON.parse(read(rawJson$)));
+  return err ? { error: err.message } : { data: value };
+});
+```
+
+### rx
+
+```tsx
+{rx(({ read, state }) => {
+  const userState = state(user$);
+  if (userState.status === "loading") return <Skeleton />;
+  if (userState.status === "error") return <ErrorMsg />;
+  return <UserCard user={userState.value} />;
+})}
+```
+
+## use() — Composable Selectors
+
+Split and reuse selection logic with `use()`:
+
+```typescript
+// Reusable selector functions
+const selectProduct = ({ read }: SelectContext) => read(product$);
+const selectUser = ({ read }: SelectContext) => read(user$);
+const selectCart = ({ read, from }: SelectContext) => {
+  const userId = read(userId$);
+  return read(from(cartPool, userId));
+};
+
+// Compose in derived
+const checkout$ = derived(({ use }) => {
+  const product = use(selectProduct);
+  const user = use(selectUser);
+  const cart = use(selectCart);
+  return { product, user, cart };
+});
+
+// Reuse in effect
+effect(({ use }) => {
+  const user = use(selectUser);
+  analytics.identify(user.id);
+});
+
+// Reuse in useSelector
+const { product, user } = useSelector(({ use }) => ({
+  product: use(selectProduct),
+  user: use(selectUser),
+}));
+```
+
+**Benefits:**
+- Reusable selection logic across derived/effect/useSelector
+- Cleaner, more readable selectors
+- Easy to test individual selectors
+- Single source of truth for data access patterns
+
+## .get() vs read()
+
+| Context                     | Use        | Why                          |
+| --------------------------- | ---------- | ---------------------------- |
+| Inside selector callback    | `read()`   | Tracks dependencies          |
+| setTimeout/setInterval      | `.get()`   | Outside reactive context     |
+| Event handlers              | `.get()`   | Outside reactive context     |
+| After await                 | `.get()`   | Context no longer valid      |
+
+```typescript
+effect(({ read }) => {
+  const config = read(config$); // ✅ read() — tracked
+
+  setTimeout(() => {
+    const value = count$.get(); // ✅ .get() — outside context
+    console.log(value);
+  }, 1000);
+});
+
+// In event handler
+const handleClick = () => {
+  const current = count$.get(); // ✅ .get() — not in selector
+  console.log(current);
+};
+```
+
+## Best Practices
+
+1. **Group reads** in useSelector
+2. **Use `safe()`** for error handling (not try/catch)
+3. **Use `ready()`** for optional params
+4. **Use `state()`** when you need loading/error states without Suspense
+5. **Use `all()`** for parallel async atoms
+6. **Use `settled()`** for graceful degradation
+7. **Use `from()`** only with `read()` — never `.get()`
+8. **Use `read()`** inside selectors, `.get()` outside
+9. **Use `untrack()`** when you need a value but don't want re-computation on change