atomirx 0.0.8 → 0.1.1

package/bin/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, cpSync, readdirSync, statSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const COMMANDS = {
+  "add-skill": addSkill,
+  help: showHelp,
+};
+
+function showHelp() {
+  console.log(`
+atomirx CLI
+
+Usage:
+  npx atomirx <command>
+
+Commands:
+  add-skill    Install atomirx Cursor skills to your project
+  help         Show this help message
+
+Examples:
+  npx atomirx add-skill
+`);
+}
+
+function addSkill() {
+  const sourceDir = join(__dirname, "..", "skills", "atomirx");
+  const targetDir = join(process.cwd(), ".cursor", "skills", "atomirx");
+
+  // Check if source skills exist
+  if (!existsSync(sourceDir)) {
+    console.error("❌ Skills not found in package. This may be a packaging issue.");
+    process.exit(1);
+  }
+
+  // Check if target already exists
+  if (existsSync(targetDir)) {
+    console.log("⚠️  Skills already exist at .cursor/skills/atomirx");
+    console.log("   To reinstall, remove the directory first and run again.");
+    return;
+  }
+
+  // Create target directory
+  mkdirSync(targetDir, { recursive: true });
+
+  // Copy skills recursively
+  copyRecursive(sourceDir, targetDir);
+
+  console.log("✅ atomirx skills installed to .cursor/skills/atomirx");
+  console.log("");
+  console.log("The skill includes:");
+  console.log("  - SKILL.md - Main skill guide");
+  console.log("  - references/ - Detailed pattern documentation");
+  console.log("");
+  console.log("Your AI assistant will now have access to atomirx best practices!");
+}
+
+function copyRecursive(source, target) {
+  const entries = readdirSync(source);
+
+  for (const entry of entries) {
+    const sourcePath = join(source, entry);
+    const targetPath = join(target, entry);
+    const stat = statSync(sourcePath);
+
+    if (stat.isDirectory()) {
+      mkdirSync(targetPath, { recursive: true });
+      copyRecursive(sourcePath, targetPath);
+    } else {
+      cpSync(sourcePath, targetPath);
+    }
+  }
+}
+
+// Main
+const command = process.argv[2] || "help";
+const handler = COMMANDS[command];
+
+if (handler) {
+  handler();
+} else {
+  console.error(`Unknown command: ${command}`);
+  showHelp();
+  process.exit(1);
+}

package/dist/core/derived.d.ts

@@ -1,7 +1,7 @@
 import { CreateInfo } from './onCreateHook';
 import { ReactiveSelector, SelectContext } from './select';
 import { DerivedAtom, DerivedOptions } from './types';
-import { WithReadySelectContext } from './withReady';
+import { WithReadyContext } from './withReady';
 /**
  * Internal options for derived atoms.
  * These are not part of the public API.
@@ -21,7 +21,7 @@ export interface DerivedInternalOptions {
  * Currently identical to `SelectContext`, but defined separately to allow
  * future derived-specific extensions without breaking changes.
  */
-export interface DerivedContext extends SelectContext, WithReadySelectContext {
+export interface DerivedContext extends SelectContext, WithReadyContext {
 }
 /**
  * Creates a derived (computed) atom from source atom(s).

package/dist/core/effect.d.ts

@@ -1,11 +1,12 @@
 import { ReactiveSelector, SelectContext } from './select';
 import { EffectMeta, EffectOptions } from './types';
-import { WithReadySelectContext } from './withReady';
+import { WithAbortContext } from './withAbort';
+import { WithReadyContext } from './withReady';
 /**
  * Context object passed to effect functions.
  * Extends `SelectContext` with cleanup utilities.
  */
-export interface EffectContext extends SelectContext, WithReadySelectContext {
+export interface EffectContext extends SelectContext, WithReadyContext, WithAbortContext {
     /**
      * Register a cleanup function that runs before the next execution or on dispose.
      * Multiple cleanup functions can be registered; they run in FIFO order.

package/dist/core/onCreateHook.d.ts

@@ -1,5 +1,5 @@
 import { Effect } from './effect';
-import { MutableAtomMeta, DerivedAtomMeta, MutableAtom, DerivedAtom, ModuleMeta, EffectMeta } from './types';
+import { MutableAtomMeta, DerivedAtomMeta, MutableAtom, DerivedAtom, ModuleMeta, EffectMeta, PoolMeta, Pool } from './types';
 /**
  * Information provided when a mutable atom is created.
  */
@@ -42,7 +42,7 @@ export interface EffectInfo {
 /**
  * Union type for atom/derived/effect creation info.
  */
-export type CreateInfo = MutableInfo | DerivedInfo | EffectInfo;
+export type CreateInfo = MutableInfo | DerivedInfo | EffectInfo | PoolInfo;
 /**
  * Information provided when a module (via define()) is created.
  */
@@ -56,6 +56,19 @@ export interface ModuleInfo {
     /** The created module instance */
     instance: unknown;
 }
+/**
+ * Information provided when a pool is created.
+ */
+export interface PoolInfo {
+    /** Discriminator for pools */
+    type: "pool";
+    /** Optional key from pool options (for debugging/devtools) */
+    key: string | undefined;
+    /** Optional metadata from pool options */
+    meta: PoolMeta | undefined;
+    /** The created pool instance */
+    instance: Pool<any, any>;
+}
 /**
  * Global hook that fires whenever an atom or module is created.
  *

package/dist/core/onErrorHook.d.ts

@@ -4,7 +4,10 @@ import { CreateInfo } from './onCreateHook';
  */
 export interface ErrorInfo {
     /** The source that produced the error (atom, derived, or effect) */
-    source: CreateInfo;
+    source: CreateInfo | {
+        type: string;
+        key?: string;
+    };
     /** The error that was thrown */
     error: unknown;
 }

package/dist/core/pool.d.ts

@@ -0,0 +1,78 @@
+import { AtomContext } from './atom';
+import { Pool, PoolOptions } from './types';
+/**
+ * Creates a pool - a collection of atoms indexed by params with automatic GC.
+ *
+ * A pool is similar to atomFamily in Jotai/Recoil, but with:
+ * - Automatic garbage collection based on `gcTime`
+ * - ScopedAtom pattern to prevent memory leaks from stale references
+ * - Promise-aware GC (never GC while value is a pending Promise)
+ * - GC timer resets on create, value change, and access
+ *
+ * ## Public API (Value-based)
+ *
+ * The public API works with values, not atoms:
+ * - `get(params)` - Get current value
+ * - `set(params, value)` - Set value
+ * - `has(params)` - Check if entry exists
+ * - `remove(params)` - Remove entry
+ * - `clear()` - Remove all entries
+ * - `forEach(cb)` - Iterate entries
+ * - `on(cb)` - Subscribe to pool events (create, change, remove)
+ *
+ * ## Reactive Context (via SelectContext.from())
+ *
+ * In derived/effect/useSelector, use `from(pool, params)` to get a ScopedAtom:
+ * ```ts
+ * derived(({ read, from }) => {
+ *   const user$ = from(userPool, "user-1");
+ *   return read(user$);
+ * });
+ * ```
+ *
+ * The ScopedAtom is automatically disposed after the computation,
+ * preventing memory leaks from stale atom references.
+ *
+ * @template P - The type of params used to index entries
+ * @template T - The type of value stored in each entry
+ * @param init - Factory function that creates initial value for params
+ * @param options - Pool configuration
+ * @returns A Pool instance
+ *
+ * @example Basic usage
+ * ```ts
+ * const userPool = pool(
+ *   (id: string) => ({ name: "", email: "" }),
+ *   { gcTime: 60_000 }
+ * );
+ *
+ * // Get/set values
+ * userPool.set("user-1", { name: "John", email: "john@example.com" });
+ * const user = userPool.get("user-1");
+ *
+ * // In reactive context
+ * derived(({ read, from }) => {
+ *   const user$ = from(userPool, "user-1");
+ *   return read(user$);
+ * });
+ * ```
+ *
+ * @example Async values
+ * ```ts
+ * const dataPool = pool(
+ *   (id: string) => fetchData(id), // Returns Promise
+ *   { gcTime: 300_000 }
+ * );
+ *
+ * // GC is paused while Promise is pending
+ * // After resolve/reject, GC timer starts
+ * ```
+ */
+export declare function pool<T, P = unknown>(init: (() => T) | ((params: P, context: AtomContext) => T), options: PoolOptions<P>): Pool<P, T>;
+/**
+ * Type guard to check if a value is a Pool.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Pool instance
+ */
+export declare function isPool<P = unknown, T = unknown>(value: unknown): value is Pool<P, T>;

package/dist/core/pool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/select-boolean.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/select-pool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/select.d.ts

@@ -1,4 +1,4 @@
-import { Atom, AtomValue, KeyedResult, Pipeable, SelectStateResult, SettledResult } from './types';
+import { Atom, AtomValue, KeyedResult, Pipeable, Pool, ScopedAtom, SelectStateResult, SettledResult } from './types';
 /**
  * Result of a select computation.
  *
@@ -11,14 +11,36 @@ export interface SelectResult<T> {
     error: unknown;
     /** Promise thrown during computation - indicates loading state */
     promise: PromiseLike<unknown> | undefined;
-    /** Set of atoms that were accessed during computation */
+    /**
+     * Set of atoms that were accessed during computation.
+     * @deprecated Use _atomDeps instead. Kept for backward compatibility.
+     */
     dependencies: Set<Atom<unknown>>;
+    /**
+     * Set of atoms that were accessed during computation.
+     * @internal
+     */
+    _atomDeps: Set<Atom<unknown>>;
+    /**
+     * Map of pools to their accessed params.
+     * @internal
+     */
+    _poolDeps: Map<Pool<any, any>, Set<any>>;
 }
 /**
  * Result type for safe() - error-first tuple.
  * Either [undefined, T] for success or [unknown, undefined] for error.
  */
 export type SafeResult<T> = [error: undefined, result: T] | [error: unknown, result: undefined];
+/**
+ * Condition input type for and()/or() operators.
+ *
+ * Supports three forms:
+ * - `boolean` - Static value, no subscription
+ * - `Atom<unknown>` - Always read and subscribed
+ * - `() => boolean | Atom<unknown>` - Lazy evaluation, only called if needed
+ */
+export type Condition = boolean | Atom<unknown> | (() => boolean | Atom<unknown>);
 /**
  * Context object passed to selector functions.
  * Provides utilities for reading atoms and handling async operations.
@@ -37,6 +59,33 @@ export interface SelectContext extends Pipeable {
      * @returns The atom's current value (Awaited<T>)
      */
     read<T>(atom: Atom<T>): Awaited<T>;
+    /**
+     * Get a ScopedAtom from a pool for the given params.
+     * The ScopedAtom is only valid during this select() execution.
+     *
+     * When the pool entry is removed (GC or manual), the computation
+     * will automatically re-run to get the new atom.
+     *
+     * @param pool - The pool to get atom from
+     * @param params - The params to look up
+     * @returns A ScopedAtom wrapping the pool entry's atom
+     *
+     * @example
+     * ```ts
+     * derived(({ read, from }) => {
+     *   const user$ = from(userPool, "user-1");
+     *   return read(user$);
+     * });
+     * ```
+     */
+    from<P, T>(pool: Pool<P, T>, params: P): ScopedAtom<T>;
+    /**
+     * Track an atom as a dependency without reading its value.
+     * Useful when you need to subscribe to changes but already have the value.
+     *
+     * @param atom - The atom to track (can be ScopedAtom)
+     */
+    track(atom: Atom<unknown>): void;
     /**
      * Wait for all atoms to resolve (like Promise.all).
      * Array-based - pass atoms as an array.
@@ -205,11 +254,195 @@ export interface SelectContext extends Pipeable {
      * ```
      */
     state<T>(selector: () => T): SelectStateResult<T>;
+    /**
+     * Logical AND - returns true if ALL conditions are truthy.
+     * Short-circuits on first falsy value (lazy conditions after that are not evaluated).
+     *
+     * ## Condition Types
+     *
+     * - `boolean` - Static value, no subscription
+     * - `Atom<T>` - Always read and subscribed
+     * - `() => boolean | Atom<T>` - Lazy, only called if previous conditions are truthy
+     *
+     * ## Evaluation Flow
+     *
+     * ```
+     * and([a, b, () => c, () => d])
+     *      │
+     *      ▼
+     *   a truthy? ─No──→ return false
+     *      │Yes
+     *      ▼
+     *   b truthy? ─No──→ return false
+     *      │Yes
+     *      ▼
+     *   call () => c
+     *   c truthy? ─No──→ return false
+     *      │Yes
+     *      ▼
+     *   call () => d
+     *   d truthy? ─No──→ return false
+     *      │Yes
+     *      ▼
+     *   return true
+     * ```
+     *
+     * @param conditions - Array of conditions (booleans, atoms, or lazy functions)
+     * @returns true if all conditions are truthy, false otherwise
+     *
+     * @example
+     * ```ts
+     * // Simple: all atoms must be truthy
+     * const canAccess = and([isLoggedIn$, hasPermission$]);
+     *
+     * // With static value
+     * const canEdit = and([FEATURE_ENABLED, isLoggedIn$, hasEditRole$]);
+     *
+     * // With lazy evaluation (only check permission if logged in)
+     * const canDelete = and([
+     *   isLoggedIn$,
+     *   () => hasDeletePermission$,  // Only read if logged in
+     * ]);
+     *
+     * // Nested: (A && B) || C
+     * const result = or([and([a$, b$]), c$]);
+     * ```
+     */
+    and(conditions: Condition[]): boolean;
+    /**
+     * Logical OR - returns true if ANY condition is truthy.
+     * Short-circuits on first truthy value (lazy conditions after that are not evaluated).
+     *
+     * ## Condition Types
+     *
+     * - `boolean` - Static value, no subscription
+     * - `Atom<T>` - Always read and subscribed
+     * - `() => boolean | Atom<T>` - Lazy, only called if previous conditions are falsy
+     *
+     * ## Evaluation Flow
+     *
+     * ```
+     * or([a, b, () => c, () => d])
+     *     │
+     *     ▼
+     *  a truthy? ─Yes─→ return true
+     *     │No
+     *     ▼
+     *  b truthy? ─Yes─→ return true
+     *     │No
+     *     ▼
+     *  call () => c
+     *  c truthy? ─Yes─→ return true
+     *     │No
+     *     ▼
+     *  call () => d
+     *  d truthy? ─Yes─→ return true
+     *     │No
+     *     ▼
+     *  return false
+     * ```
+     *
+     * @param conditions - Array of conditions (booleans, atoms, or lazy functions)
+     * @returns true if any condition is truthy, false otherwise
+     *
+     * @example
+     * ```ts
+     * // Simple: any atom truthy
+     * const hasData = or([cacheData$, apiData$]);
+     *
+     * // With lazy fallback chain
+     * const data = or([
+     *   () => primaryData$,   // Try primary first
+     *   () => fallbackData$,  // Only if primary is falsy
+     * ]);
+     *
+     * // Nested: A || (B && C)
+     * const result = or([a$, and([b$, c$])]);
+     * ```
+     */
+    or(conditions: Condition[]): boolean;
+    /**
+     * Read atoms or execute functions without tracking dependencies.
+     * Useful when you need to read a value but don't want to re-compute when it changes.
+     *
+     * Supports two forms:
+     * - `untrack(atom$)` - Read atom value without tracking
+     * - `untrack(() => expr)` - Execute function without tracking any reads inside
+     *
+     * ## Flow Diagram
+     *
+     * ```
+     * untrack(input)
+     *       │
+     *       ▼
+     *   Is input an Atom?
+     *       │
+     *   ┌───┴───┐
+     *   │Yes    │No (function)
+     *   ▼       ▼
+     *  Read    Set isUntracking = true
+     *  without  │
+     *  tracking ▼
+     *   │      Execute fn()
+     *   │       │
+     *   │       ▼
+     *   │      Set isUntracking = false
+     *   │       │
+     *   └───────┴──→ Return value
+     * ```
+     *
+     * @param atom - Atom to read without tracking
+     * @returns The atom's current value
+     *
+     * @example
+     * ```ts
+     * const combined$ = derived(({ read, untrack }) => {
+     *   const count = read(count$);           // Tracks count$
+     *   const doubled = untrack(doubled$);    // Does NOT track doubled$
+     *   return count + doubled;
+     * });
+     * ```
+     */
+    untrack<T>(atom: Atom<T>): Awaited<T>;
+    /**
+     * Execute a function without tracking any atom reads inside.
+     *
+     * @param fn - Function to execute without tracking
+     * @returns The function's return value
+     *
+     * @example
+     * ```ts
+     * const combined$ = derived(({ read, untrack }) => {
+     *   const count = read(count$);           // Tracks count$
+     *   const tripled = untrack(() => {
+     *     // None of these reads are tracked
+     *     return read(a$) + read(b$) + read(c$);
+     *   });
+     *   return count + tripled;
+     * });
+     * ```
+     */
+    untrack<T>(fn: () => T): T;
 }
 /**
  * Selector function type for context-based API.
  */
 export type ReactiveSelector<T, C extends SelectContext = SelectContext> = (context: C) => T;
+/**
+ * Output of select() - includes result and startTracking function.
+ */
+export interface SelectOutput<T> {
+    /** The computation result */
+    result: SelectResult<T>;
+    /**
+     * Start tracking dependencies and subscribe to changes.
+     * Call this after computation to set up subscriptions.
+     *
+     * @param onNotify - Callback to invoke when any dependency changes
+     * @returns Cleanup function to unsubscribe all
+     */
+    startTracking(onNotify: VoidFunction): VoidFunction;
+}
 /**
  * Custom error for when all atoms in `any()` are rejected.
  */
@@ -217,114 +450,73 @@ export declare class AllAtomsRejectedError extends Error {
     readonly errors: unknown[];
     constructor(errors: unknown[], message?: string);
 }
+/**
+ * Type guard to check if a value is a ScopedAtom.
+ */
+export declare function isScopedAtom<T = unknown>(value: unknown): value is ScopedAtom<T>;
+/**
+ * Type guard to check if a value is a Pool.
+ */
+export declare function isPool<P = unknown, T = unknown>(value: unknown): value is Pool<P, T>;
 /**
  * Selects/computes a value from atom(s) with dependency tracking.
  *
  * This is the core computation logic used by `derived()`. It:
- * 1. Creates a context with `read`, `all`, `any`, `race`, `settled`, `safe` utilities
- * 2. Tracks which atoms are accessed during computation
- * 3. Returns a result with value/error/promise and dependencies
+ * 1. Creates a context with `read`, `from`, `all`, `any`, `race`, `settled`, `safe` utilities
+ * 2. Tracks which atoms and pools are accessed during computation
+ * 3. Returns a result with value/error/promise and a startTracking function
  *
- * All context methods use `getAtomState()` internally.
- *
- * ## IMPORTANT: Selector Must Return Synchronous Value
- *
- * **The selector function MUST NOT return a Promise or PromiseLike value.**
- *
- * If your selector returns a Promise, it will throw an error. This is because:
- * - `select()` is designed for synchronous derivation from atoms
- * - Async atoms should be created using `atom(Promise)` directly
- * - Use `read()` to read async atoms - it handles Suspense-style loading
+ * ## New API
  *
  * ```ts
- * // ❌ WRONG - Don't return a Promise from selector
- * select(({ get }) => fetch('/api/data'));
- *
- * // ✅ CORRECT - Create async atom and read with read()
- * const data$ = atom(fetch('/api/data').then(r => r.json()));
- * select(({ read }) => read(data$)); // Suspends until resolved
+ * const { result, startTracking } = select(fn, prevResult);
+ * const cleanup = startTracking(onNotify);
  * ```
  *
- * ## IMPORTANT: Do NOT Use try/catch - Use safe() Instead
+ * The `startTracking` function sets up subscriptions to all dependencies
+ * (atoms and pool entries) and returns a cleanup function.
  *
- * **Never wrap `read()` calls in try/catch blocks.** The `read()` function throws
- * Promises when atoms are loading (Suspense pattern). A try/catch will catch
- * these Promises and break the Suspense mechanism.
+ * ## Pool Support via from()
  *
+ * Use `from(pool, params)` to get a ScopedAtom from a pool:
  * ```ts
- * // ❌ WRONG - Catches Suspense Promise, breaks loading state
- * select(({ read }) => {
- *   try {
- *     return read(asyncAtom$);
- *   } catch (e) {
- *     return 'fallback'; // This catches BOTH errors AND loading promises!
- *   }
- * });
- *
- * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
- * select(({ read, safe }) => {
- *   const [err, data] = safe(() => {
- *     const raw = read(asyncAtom$);    // Can throw Promise (Suspense)
- *     return JSON.parse(raw);          // Can throw Error
- *   });
- *
- *   if (err) return { error: err.message };
- *   return { data };
+ * const { result } = select(({ read, from }) => {
+ *   const user$ = from(userPool, "user-1");
+ *   return read(user$);
  * });
  * ```
  *
- * The `safe()` utility:
- * - **Catches errors** and returns `[error, undefined]`
- * - **Re-throws Promises** to preserve Suspense behavior
- * - Returns `[undefined, result]` on success
- *
- * ## IMPORTANT: SelectContext Methods Are Synchronous Only
+ * ScopedAtoms are automatically disposed after select() completes,
+ * preventing memory leaks from stale atom references.
  *
- * **All context methods (`read`, `all`, `race`, `any`, `settled`, `safe`) must be
- * called synchronously during selector execution.** They cannot be used in async
- * callbacks like `setTimeout`, `Promise.then`, or event handlers.
+ * ## IMPORTANT: Selector Must Return Synchronous Value
  *
- * ```ts
- * // ❌ WRONG - Calling read() in async callback
- * select(({ read }) => {
- *   setTimeout(() => {
- *     read(atom$); // Error: called outside selection context
- *   }, 100);
- *   return 'value';
- * });
+ * **The selector function MUST NOT return a Promise or PromiseLike value.**
  *
- * // ❌ WRONG - Storing read() for later use
- * let savedRead;
- * select(({ read }) => {
- *   savedRead = read; // Don't do this!
- *   return read(atom$);
- * });
- * savedRead(atom$); // Error: called outside selection context
+ * ## IMPORTANT: Do NOT Use try/catch - Use safe() Instead
  *
- * // ✅ CORRECT - For async access, use atom.get() directly
- * effect(({ read }) => {
- *   const config = read(config$);
- *   setTimeout(async () => {
- *     // Use atom.get() for async access
- *     const data = await asyncAtom$.get();
- *     console.log(data);
- *   }, 100);
- * });
- * ```
+ * **Never wrap `read()` calls in try/catch blocks.** Use `safe()` instead.
  *
  * @template T - The type of the computed value
  * @param fn - Context-based selector function (must return sync value)
- * @returns SelectResult with value, error, promise, and dependencies
- * @throws Error if selector returns a Promise or PromiseLike
- * @throws Error if context methods are called outside selection context
+ * @param prevResult - Previous result for diff-based subscription updates
+ * @returns SelectOutput with result and startTracking function
  *
  * @example
  * ```ts
- * select(({ read, all }) => {
- *   const user = read(user$);
- *   const [posts, comments] = all([posts$, comments$]);
- *   return { user, posts, comments };
- * });
+ * // Basic usage
+ * const { result, startTracking } = select(({ read }) => {
+ *   return read(count$) * 2;
+ * }, null);
+ *
+ * // With pool
+ * const { result, startTracking } = select(({ read, from }) => {
+ *   const user$ = from(userPool, userId);
+ *   return read(user$);
+ * }, prevResult);
+ *
+ * // Start tracking dependencies
+ * const cleanup = startTracking(() => recompute());
  * ```
  */
-export declare function select<T>(fn: ReactiveSelector<T>): SelectResult<T>;
+export declare function select<T>(fn: ReactiveSelector<T>, _prevResult?: SelectResult<T> | null): SelectOutput<T>;