atomirx 0.0.8 → 0.1.0

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

@@ -0,0 +1,431 @@
+# Testing Patterns
+
+## Core Principles
+
+1. **Isolate** — Each test gets fresh atoms
+2. **Override** — Use `define().override()` for mocks
+3. **Reset hooks** — Clear between tests
+4. **Test behaviors** — Not internals
+
+## Testing Atoms
+
+### Basic
+
+```typescript
+describe("counterAtom", () => {
+  it("should initialize to 0", () => {
+    const count$ = atom(0, { meta: { key: "test.count" } });
+    expect(count$.get()).toBe(0);
+  });
+
+  it("should update value", () => {
+    const count$ = atom(0);
+    count$.set(5);
+    expect(count$.get()).toBe(5);
+  });
+
+  it("should use reducer", () => {
+    const count$ = atom(0);
+    count$.set((prev) => prev + 1);
+    expect(count$.get()).toBe(1);
+  });
+
+  it("should reset to initial", () => {
+    const count$ = atom(() => 10);
+    count$.set(99);
+    count$.reset();
+    expect(count$.get()).toBe(10);
+  });
+
+  it("should track dirty state", () => {
+    const form$ = atom({ name: "" });
+    expect(form$.dirty()).toBe(false);
+    form$.set({ name: "John" });
+    expect(form$.dirty()).toBe(true);
+    form$.reset();
+    expect(form$.dirty()).toBe(false);
+  });
+});
+```
+
+### Subscriptions
+
+```typescript
+it("should notify on change", () => {
+  const count$ = atom(0);
+  const values: number[] = [];
+  const unsub = count$.on(() => values.push(count$.get()));
+
+  count$.set(1);
+  count$.set(2);
+  expect(values).toEqual([1, 2]);
+
+  unsub();
+  count$.set(3);
+  expect(values).toEqual([1, 2]); // No 3
+});
+```
+
+### Async Atoms
+
+```typescript
+it("should handle async", async () => {
+  const user$ = atom(Promise.resolve({ name: "John" }));
+  const result = await user$.get();
+  expect(result.name).toBe("John");
+});
+
+it("should refetch on reset", async () => {
+  let callCount = 0;
+  const data$ = atom(() => {
+    callCount++;
+    return Promise.resolve(callCount);
+  });
+
+  expect(await data$.get()).toBe(1);
+  data$.reset();
+  expect(await data$.get()).toBe(2);
+});
+```
+
+## Testing Derived
+
+```typescript
+describe("derived", () => {
+  it("should compute from source", async () => {
+    const count$ = atom(5);
+    const doubled$ = derived(({ read }) => read(count$) * 2);
+    expect(await doubled$.get()).toBe(10);
+  });
+
+  it("should update on source change", async () => {
+    const count$ = atom(5);
+    const doubled$ = derived(({ read }) => read(count$) * 2);
+    
+    count$.set(10);
+    expect(await doubled$.get()).toBe(20);
+  });
+
+  it("should combine atoms", async () => {
+    const a$ = atom(1);
+    const b$ = atom(2);
+    const sum$ = derived(({ read }) => read(a$) + read(b$));
+    
+    expect(await sum$.get()).toBe(3);
+    a$.set(10);
+    expect(await sum$.get()).toBe(12);
+  });
+
+  it("should handle async sources", async () => {
+    const user$ = atom(Promise.resolve({ name: "John" }));
+    const greeting$ = derived(({ read }) => `Hello, ${read(user$).name}`);
+    expect(await greeting$.get()).toBe("Hello, John");
+  });
+
+  it("should use fallback during loading", () => {
+    const data$ = derived(({ read }) => read(atom(Promise.resolve(42))), {
+      fallback: 0,
+    });
+    expect(data$.staleValue).toBe(0);
+  });
+});
+```
+
+## Testing Effects
+
+```typescript
+describe("effect", () => {
+  it("should run on creation", () => {
+    const log: number[] = [];
+    const count$ = atom(5);
+    effect(({ read }) => log.push(read(count$)));
+    expect(log).toEqual([5]);
+  });
+
+  it("should run on change", () => {
+    const log: number[] = [];
+    const count$ = atom(0);
+    effect(({ read }) => log.push(read(count$)));
+    
+    count$.set(1);
+    count$.set(2);
+    expect(log).toEqual([0, 1, 2]);
+  });
+
+  it("should cleanup", () => {
+    const cleanups: number[] = [];
+    const count$ = atom(0);
+
+    effect(({ read, onCleanup }) => {
+      const val = read(count$);
+      onCleanup(() => cleanups.push(val));
+    });
+
+    count$.set(1);
+    expect(cleanups).toEqual([0]);
+    count$.set(2);
+    expect(cleanups).toEqual([0, 1]);
+  });
+
+  it("should dispose", () => {
+    const log: number[] = [];
+    const count$ = atom(0);
+    const e = effect(({ read }) => log.push(read(count$)));
+
+    count$.set(1);
+    expect(log).toEqual([0, 1]);
+
+    e.dispose();
+    count$.set(2);
+    expect(log).toEqual([0, 1]); // No 2
+  });
+});
+```
+
+## Testing Stores (define)
+
+### Mocking Services
+
+```typescript
+const authService = define((): AuthService => ({
+  login: async () => ({ success: true, user: { id: "1", name: "Test" } }),
+  logout: async () => {},
+}));
+
+const authStore = define(() => {
+  const auth = authService();
+  const user$ = atom<User | null>(null);
+
+  return {
+    ...readonly({ user$ }),
+    login: async () => {
+      const result = await auth.login();
+      if (result.success) user$.set(result.user);
+    },
+    logout: () => user$.set(null),
+  };
+});
+
+describe("authStore", () => {
+  beforeEach(() => {
+    authService.reset();
+    authStore.reset();
+  });
+
+  it("should login with mock", async () => {
+    authService.override(() => ({
+      login: async () => ({ success: true, user: { id: "mock", name: "Mock" } }),
+      logout: async () => {},
+    }));
+
+    const store = authStore();
+    await store.login();
+    expect(store.user$.get()).toEqual({ id: "mock", name: "Mock" });
+  });
+
+  it("should handle login failure", async () => {
+    authService.override(() => ({
+      login: async () => ({ success: false, error: "Invalid" }),
+      logout: async () => {},
+    }));
+
+    const store = authStore();
+    await store.login();
+    expect(store.user$.get()).toBeNull();
+  });
+});
+```
+
+### Isolation
+
+```typescript
+describe("counterStore", () => {
+  const counterStore = define(() => {
+    const count$ = atom(0);
+    return {
+      ...readonly({ count$ }),
+      increment: () => count$.set((p) => p + 1),
+    };
+  });
+
+  beforeEach(() => counterStore.reset());
+
+  it("test 1", () => {
+    const store = counterStore();
+    store.increment();
+    expect(store.count$.get()).toBe(1);
+  });
+
+  it("test 2 (isolated)", () => {
+    const store = counterStore();
+    expect(store.count$.get()).toBe(0); // Fresh
+  });
+});
+```
+
+## Testing Pools
+
+```typescript
+describe("userPool", () => {
+  const userPool = pool(
+    (id: string) => ({ id, name: `User ${id}`, posts: [] }),
+    { gcTime: 60_000 }
+  );
+
+  afterEach(() => userPool.clear());
+
+  it("should create entries", () => {
+    expect(userPool.has("1")).toBe(false);
+    userPool.get("1");
+    expect(userPool.has("1")).toBe(true);
+  });
+
+  it("should update entries", () => {
+    userPool.get("1");
+    userPool.set("1", (p) => ({ ...p, name: "Updated" }));
+    expect(userPool.get("1").name).toBe("Updated");
+  });
+
+  it("should remove entries", () => {
+    userPool.get("1");
+    userPool.remove("1");
+    expect(userPool.has("1")).toBe(false);
+  });
+
+  it("should work with derived", async () => {
+    userPool.set("1", { id: "1", name: "John", posts: [] });
+
+    const userName$ = derived(({ read, from }) => {
+      const user$ = from(userPool, "1");
+      return read(user$).name;
+    });
+
+    expect(await userName$.get()).toBe("John");
+  });
+});
+```
+
+## Testing Hooks
+
+```typescript
+describe("onCreateHook", () => {
+  beforeEach(() => {
+    onCreateHook.reset();
+    onErrorHook.reset();
+  });
+
+  afterEach(() => {
+    onCreateHook.reset();
+    onErrorHook.reset();
+  });
+
+  it("should track atoms", () => {
+    const created: string[] = [];
+    onCreateHook.override((prev) => (info) => {
+      prev?.(info);
+      if (info.key) created.push(info.key);
+    });
+
+    atom(0, { meta: { key: "test.a" } });
+    atom(0, { meta: { key: "test.b" } });
+
+    expect(created).toContain("test.a");
+    expect(created).toContain("test.b");
+  });
+});
+
+describe("onErrorHook", () => {
+  beforeEach(() => onErrorHook.reset());
+  afterEach(() => onErrorHook.reset());
+
+  it("should capture errors", async () => {
+    const errors: unknown[] = [];
+    onErrorHook.override((prev) => (info) => {
+      prev?.(info);
+      errors.push(info.error);
+    });
+
+    const buggy$ = derived(() => { throw new Error("test"); });
+
+    try { await buggy$.get(); } catch {}
+    expect(errors).toHaveLength(1);
+  });
+});
+```
+
+## Testing React
+
+```tsx
+import { render, screen, act } from "@testing-library/react";
+import { Suspense } from "react";
+
+describe("useSelector", () => {
+  const count$ = atom(0, { meta: { key: "test.count" } });
+
+  beforeEach(() => count$.reset());
+
+  it("should read value", () => {
+    function Counter() {
+      const count = useSelector(count$);
+      return <span data-testid="count">{count}</span>;
+    }
+
+    render(<Counter />);
+    expect(screen.getByTestId("count")).toHaveTextContent("0");
+  });
+
+  it("should update on change", async () => {
+    function Counter() {
+      const count = useSelector(count$);
+      return <span data-testid="count">{count}</span>;
+    }
+
+    render(<Counter />);
+    await act(() => count$.set(5));
+    expect(screen.getByTestId("count")).toHaveTextContent("5");
+  });
+});
+
+describe("rx", () => {
+  it("should render inline", () => {
+    const name$ = atom("John");
+
+    render(
+      <div data-testid="greeting">
+        {rx(({ read }) => <>Hello, {read(name$)}</>)}
+      </div>
+    );
+
+    expect(screen.getByTestId("greeting")).toHaveTextContent("Hello, John");
+  });
+});
+
+describe("useAction", () => {
+  it("should handle async", async () => {
+    function Form() {
+      const submit = useAction(async () => "done");
+      return (
+        <>
+          <button onClick={() => submit()}>Submit</button>
+          <span data-testid="status">{submit.status}</span>
+        </>
+      );
+    }
+
+    render(<Form />);
+    expect(screen.getByTestId("status")).toHaveTextContent("idle");
+  });
+});
+```
+
+## Best Practices
+
+| Practice              | Description                         |
+| --------------------- | ----------------------------------- |
+| `reset()` in beforeEach | Fresh state per test              |
+| `override()` for mocks | Swap implementations               |
+| Test behaviors        | Not implementation details          |
+| Test subscriptions    | Verify reactive updates             |
+| Test cleanup          | Verify resources released           |
+| Use act()             | For React state updates             |
+| Wrap Suspense         | For async atoms in React            |

package/coverage/base.css

@@ -1,224 +0,0 @@
-body, html {
-  margin:0; padding: 0;
-  height: 100%;
-}
-body {
-    font-family: Helvetica Neue, Helvetica, Arial;
-    font-size: 14px;
-    color:#333;
-}
-.small { font-size: 12px; }
-*, *:after, *:before {
-  -webkit-box-sizing:border-box;
-     -moz-box-sizing:border-box;
-          box-sizing:border-box;
-  }
-h1 { font-size: 20px; margin: 0;}
-h2 { font-size: 14px; }
-pre {
-    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
-    margin: 0;
-    padding: 0;
-    -moz-tab-size: 2;
-    -o-tab-size:  2;
-    tab-size: 2;
-}
-a { color:#0074D9; text-decoration:none; }
-a:hover { text-decoration:underline; }
-.strong { font-weight: bold; }
-.space-top1 { padding: 10px 0 0 0; }
-.pad2y { padding: 20px 0; }
-.pad1y { padding: 10px 0; }
-.pad2x { padding: 0 20px; }
-.pad2 { padding: 20px; }
-.pad1 { padding: 10px; }
-.space-left2 { padding-left:55px; }
-.space-right2 { padding-right:20px; }
-.center { text-align:center; }
-.clearfix { display:block; }
-.clearfix:after {
-  content:'';
-  display:block;
-  height:0;
-  clear:both;
-  visibility:hidden;
-  }
-.fl { float: left; }
-@media only screen and (max-width:640px) {
-  .col3 { width:100%; max-width:100%; }
-  .hide-mobile { display:none!important; }
-}
-
-.quiet {
-  color: #7f7f7f;
-  color: rgba(0,0,0,0.5);
-}
-.quiet a { opacity: 0.7; }
-
-.fraction {
-  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
-  font-size: 10px;
-  color: #555;
-  background: #E8E8E8;
-  padding: 4px 5px;
-  border-radius: 3px;
-  vertical-align: middle;
-}
-
-div.path a:link, div.path a:visited { color: #333; }
-table.coverage {
-  border-collapse: collapse;
-  margin: 10px 0 0 0;
-  padding: 0;
-}
-
-table.coverage td {
-  margin: 0;
-  padding: 0;
-  vertical-align: top;
-}
-table.coverage td.line-count {
-    text-align: right;
-    padding: 0 5px 0 20px;
-}
-table.coverage td.line-coverage {
-    text-align: right;
-    padding-right: 10px;
-    min-width:20px;
-}
-
-table.coverage td span.cline-any {
-    display: inline-block;
-    padding: 0 5px;
-    width: 100%;
-}
-.missing-if-branch {
-    display: inline-block;
-    margin-right: 5px;
-    border-radius: 3px;
-    position: relative;
-    padding: 0 4px;
-    background: #333;
-    color: yellow;
-}
-
-.skip-if-branch {
-    display: none;
-    margin-right: 10px;
-    position: relative;
-    padding: 0 4px;
-    background: #ccc;
-    color: white;
-}
-.missing-if-branch .typ, .skip-if-branch .typ {
-    color: inherit !important;
-}
-.coverage-summary {
-  border-collapse: collapse;
-  width: 100%;
-}
-.coverage-summary tr { border-bottom: 1px solid #bbb; }
-.keyline-all { border: 1px solid #ddd; }
-.coverage-summary td, .coverage-summary th { padding: 10px; }
-.coverage-summary tbody { border: 1px solid #bbb; }
-.coverage-summary td { border-right: 1px solid #bbb; }
-.coverage-summary td:last-child { border-right: none; }
-.coverage-summary th {
-  text-align: left;
-  font-weight: normal;
-  white-space: nowrap;
-}
-.coverage-summary th.file { border-right: none !important; }
-.coverage-summary th.pct { }
-.coverage-summary th.pic,
-.coverage-summary th.abs,
-.coverage-summary td.pct,
-.coverage-summary td.abs { text-align: right; }
-.coverage-summary td.file { white-space: nowrap;  }
-.coverage-summary td.pic { min-width: 120px !important;  }
-.coverage-summary tfoot td { }
-
-.coverage-summary .sorter {
-    height: 10px;
-    width: 7px;
-    display: inline-block;
-    margin-left: 0.5em;
-    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
-}
-.coverage-summary .sorted .sorter {
-    background-position: 0 -20px;
-}
-.coverage-summary .sorted-desc .sorter {
-    background-position: 0 -10px;
-}
-.status-line {  height: 10px; }
-/* yellow */
-.cbranch-no { background: yellow !important; color: #111; }
-/* dark red */
-.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
-.low .chart { border:1px solid #C21F39 }
-.highlighted,
-.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
-  background: #C21F39 !important;
-}
-/* medium red */
-.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
-/* light red */
-.low, .cline-no { background:#FCE1E5 }
-/* light green */
-.high, .cline-yes { background:rgb(230,245,208) }
-/* medium green */
-.cstat-yes { background:rgb(161,215,106) }
-/* dark green */
-.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
-.high .chart { border:1px solid rgb(77,146,33) }
-/* dark yellow (gold) */
-.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
-.medium .chart { border:1px solid #f9cd0b; }
-/* light yellow */
-.medium { background: #fff4c2; }
-
-.cstat-skip { background: #ddd; color: #111; }
-.fstat-skip { background: #ddd; color: #111 !important; }
-.cbranch-skip { background: #ddd !important; color: #111; }
-
-span.cline-neutral { background: #eaeaea; }
-
-.coverage-summary td.empty {
-    opacity: .5;
-    padding-top: 4px;
-    padding-bottom: 4px;
-    line-height: 1;
-    color: #888;
-}
-
-.cover-fill, .cover-empty {
-  display:inline-block;
-  height: 12px;
-}
-.chart {
-  line-height: 0;
-}
-.cover-empty {
-    background: white;
-}
-.cover-full {
-    border-right: none !important;
-}
-pre.prettyprint {
-    border: none !important;
-    padding: 0 !important;
-    margin: 0 !important;
-}
-.com { color: #999 !important; }
-.ignore-none { color: #999; font-weight: normal; }
-
-.wrapper {
-  min-height: 100%;
-  height: auto !important;
-  height: 100%;
-  margin: 0 auto -48px;
-}
-.footer, .push {
-  height: 48px;
-}