atomirx 0.0.7 → 0.1.0

package/skills/atomirx/references/service-template.md

@@ -0,0 +1,172 @@
+# Service Template
+
+Services = stateless modules. NO atoms. Pure functions only.
+
+## Template
+
+```typescript
+// services/[name]/[name].service.ts
+import { define } from "atomirx";
+
+// ==================== Types ====================
+
+export interface EntityDTO {
+  id: string;
+  name: string;
+  createdAt: string;
+}
+
+export interface CreateEntityInput {
+  name: string;
+}
+
+export interface UpdateEntityInput {
+  name?: string;
+}
+
+export interface EntityService {
+  fetch: (id: string) => Promise<EntityDTO>;
+  list: (params?: { limit?: number; offset?: number }) => Promise<EntityDTO[]>;
+  create: (input: CreateEntityInput) => Promise<EntityDTO>;
+  update: (id: string, input: UpdateEntityInput) => Promise<EntityDTO>;
+  delete: (id: string) => Promise<void>;
+}
+
+// ==================== Service ====================
+
+export const entityService = define((): EntityService => {
+  const BASE_URL = "/api/entities";
+
+  const handleResponse = async <T>(response: Response): Promise<T> => {
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: "Request failed" }));
+      throw new Error(error.message || `HTTP ${response.status}`);
+    }
+    return response.json();
+  };
+
+  return {
+    fetch: async (id) => {
+      const res = await fetch(`${BASE_URL}/${id}`);
+      return handleResponse<EntityDTO>(res);
+    },
+
+    list: async (params = {}) => {
+      const searchParams = new URLSearchParams();
+      if (params.limit) searchParams.set("limit", String(params.limit));
+      if (params.offset) searchParams.set("offset", String(params.offset));
+
+      const url = searchParams.toString() ? `${BASE_URL}?${searchParams}` : BASE_URL;
+      const res = await fetch(url);
+      return handleResponse<EntityDTO[]>(res);
+    },
+
+    create: async (input) => {
+      const res = await fetch(BASE_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      return handleResponse<EntityDTO>(res);
+    },
+
+    update: async (id, input) => {
+      const res = await fetch(`${BASE_URL}/${id}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      return handleResponse<EntityDTO>(res);
+    },
+
+    delete: async (id) => {
+      const res = await fetch(`${BASE_URL}/${id}`, { method: "DELETE" });
+      if (!res.ok) throw new Error(`Failed to delete ${id}`);
+    },
+  };
+});
+```
+
+## Structure
+
+```
+services/
+└── [name]/
+    ├── [name].service.ts  # Service definition
+    └── index.ts           # Export
+```
+
+## Checklist
+
+| Item                  | Required |
+| --------------------- | -------- |
+| Use `define()`        | ✅       |
+| Return type interface | ✅       |
+| Pure functions only   | ✅       |
+| NO atoms              | ✅       |
+| NO side effects       | ✅       |
+| Error handling        | ✅       |
+
+## Naming
+
+| Type    | Pattern              | Example              |
+| ------- | -------------------- | -------------------- |
+| Service | `[name]Service`      | `entityService`      |
+| File    | `[name].service.ts`  | `entity.service.ts`  |
+| Methods | verb-led             | `fetch`, `create`    |
+
+## Platform Override
+
+```typescript
+// services/storage/storage.service.ts
+export interface StorageService {
+  get: (key: string) => Promise<string | null>;
+  set: (key: string, value: string) => Promise<void>;
+  remove: (key: string) => Promise<void>;
+}
+
+export const storageService = define((): StorageService => {
+  throw new Error("StorageService not implemented. Override for platform.");
+});
+
+// services/storage/storage.web.ts
+export const webStorageService = define((): StorageService => ({
+  get: async (key) => localStorage.getItem(key),
+  set: async (key, value) => localStorage.setItem(key, value),
+  remove: async (key) => localStorage.removeItem(key),
+}));
+
+// services/storage/storage.native.ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+export const nativeStorageService = define((): StorageService => ({
+  get: (key) => AsyncStorage.getItem(key),
+  set: (key, value) => AsyncStorage.setItem(key, value),
+  remove: (key) => AsyncStorage.removeItem(key),
+}));
+
+// app/init.ts
+import { storageService } from "@/services/storage/storage.service";
+import { webStorageService } from "@/services/storage/storage.web";
+
+storageService.override(webStorageService);
+```
+
+## Usage in Store
+
+```typescript
+import { entityService } from "@/services/entity/entity.service";
+
+export const entityStore = define(() => {
+  const api = entityService(); // Inject via invocation
+
+  const entities$ = atom<EntityDTO[]>([], { meta: { key: "entity.list" } });
+
+  const loadEntities = async () => {
+    const data = await api.list();
+    entities$.set(data);
+  };
+
+  return { ...readonly({ entities$ }), loadEntities };
+});
+```

package/skills/atomirx/references/store-template.md

@@ -0,0 +1,205 @@
+# Store Template
+
+Stores = stateful modules with atoms. Use `define()`.
+
+## Template
+
+```typescript
+// features/[feature]/stores/[name].store.ts
+import { atom, derived, effect, readonly, batch, define } from "atomirx";
+import { someService } from "@/services/some/some.service";
+
+// ==================== Types ====================
+
+interface EntityState {
+  id: string;
+  name: string;
+  status: "idle" | "loading" | "error";
+}
+
+// ==================== Store ====================
+
+export const entityStore = define(() => {
+  // ---------- Dependencies ----------
+  const api = someService();
+
+  // ---------- State ----------
+  const entities$ = atom<Map<string, EntityState>>(new Map(), {
+    meta: { key: "entity.entities" },
+  });
+
+  const currentId$ = atom<string | undefined>(undefined, {
+    meta: { key: "entity.currentId" },
+  });
+
+  const filter$ = atom("", {
+    meta: { key: "entity.filter" },
+  });
+
+  // ---------- Derived ----------
+  const currentEntity$ = derived(
+    ({ read, ready }) => {
+      const id = ready(currentId$);
+      return read(entities$).get(id) ?? null;
+    },
+    { meta: { key: "entity.current" }, fallback: null }
+  );
+
+  const filteredEntities$ = derived(
+    ({ read }) => {
+      const entities = read(entities$);
+      const filter = read(filter$).toLowerCase();
+      if (!filter) return [...entities.values()];
+      return [...entities.values()].filter((e) =>
+        e.name.toLowerCase().includes(filter)
+      );
+    },
+    { meta: { key: "entity.filtered" } }
+  );
+
+  // ---------- Effects ----------
+  effect(
+    ({ read }) => {
+      const current = read(currentEntity$);
+      if (current) localStorage.setItem("lastEntity", current.id);
+    },
+    { meta: { key: "entity.persistLast" } }
+  );
+
+  // ---------- Actions ----------
+  const setFilter = (value: string) => filter$.set(value);
+
+  const selectEntity = (id: string | undefined) => currentId$.set(id);
+
+  const fetchEntity = async (id: string) => {
+    batch(() => {
+      entities$.set((prev) => {
+        const next = new Map(prev);
+        const existing = next.get(id);
+        next.set(id, { ...(existing ?? { id, name: "" }), status: "loading" });
+        return next;
+      });
+    });
+
+    try {
+      const data = await api.fetch(id);
+      entities$.set((prev) => {
+        const next = new Map(prev);
+        next.set(id, { ...data, status: "idle" });
+        return next;
+      });
+      return data;
+    } catch (error) {
+      entities$.set((prev) => {
+        const next = new Map(prev);
+        const existing = next.get(id);
+        if (existing) next.set(id, { ...existing, status: "error" });
+        return next;
+      });
+      throw error;
+    }
+  };
+
+  const updateEntity = async (id: string, updates: Partial<EntityState>) => {
+    const prev = entities$.get().get(id);
+    if (!prev) throw new Error(`Entity ${id} not found`);
+
+    // Optimistic
+    entities$.set((map) => {
+      const next = new Map(map);
+      next.set(id, { ...prev, ...updates });
+      return next;
+    });
+
+    try {
+      await api.update(id, updates);
+    } catch (error) {
+      // Rollback
+      entities$.set((map) => {
+        const next = new Map(map);
+        next.set(id, prev);
+        return next;
+      });
+      throw error;
+    }
+  };
+
+  const reset = () => {
+    batch(() => {
+      entities$.reset();
+      currentId$.reset();
+      filter$.reset();
+    });
+  };
+
+  // ---------- Return ----------
+  return {
+    // Read-only state
+    ...readonly({ entities$, currentId$, filter$, currentEntity$, filteredEntities$ }),
+
+    // Actions
+    setFilter,
+    selectEntity,
+    fetchEntity,
+    updateEntity,
+    reset,
+  };
+});
+```
+
+## Structure
+
+```
+features/
+└── [feature]/
+    └── stores/
+        ├── [name].store.ts    # Store definition
+        └── index.ts           # Export
+```
+
+## Checklist
+
+| Item                     | Required |
+| ------------------------ | -------- |
+| Use `define()`           | ✅       |
+| `meta.key` on ALL atoms  | ✅       |
+| `meta.key` on derived    | ✅       |
+| `meta.key` on effects    | ✅       |
+| `readonly()` for state   | ✅       |
+| Actions return Promises  | When async |
+| Use `batch()` multi-update | ✅     |
+| Inject services via call | ✅       |
+| Optimistic + rollback    | For UX   |
+
+## Naming
+
+| Type      | Pattern          | Example                |
+| --------- | ---------------- | ---------------------- |
+| Store     | `[name]Store`    | `entityStore`          |
+| File      | `[name].store.ts`| `entity.store.ts`      |
+| Atoms     | `[name]$`        | `entities$`, `filter$` |
+| Derived   | `[computed]$`    | `currentEntity$`       |
+| Actions   | verb-led         | `fetchEntity`, `reset` |
+
+## Usage
+
+```tsx
+function EntityList() {
+  const store = entityStore();
+
+  const entities = useSelector(({ read }) => read(store.filteredEntities$));
+  const stable = useStable({
+    onSelect: (id: string) => store.selectEntity(id),
+  });
+
+  return (
+    <ul>
+      {entities.map((e) => (
+        <li key={e.id} onClick={() => stable.onSelect(e.id)}>
+          {e.name}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```