atomirx 0.0.8 → 0.1.1

package/src/core/hook.test.ts

@@ -1,227 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { hook } from "./hook";
-
-describe("hook", () => {
-  describe("createHook", () => {
-    it("should create a hook with initial value", () => {
-      const myHook = hook(42);
-      expect(myHook.current).toBe(42);
-    });
-
-    it("should create a hook with undefined when no initial value", () => {
-      const myHook = hook<string>();
-      expect(myHook.current).toBeUndefined();
-    });
-
-    it("should create a hook with object value", () => {
-      const obj = { name: "test" };
-      const myHook = hook(obj);
-      expect(myHook.current).toBe(obj);
-    });
-
-    it("should create a hook with function value", () => {
-      const fn = () => 42;
-      const myHook = hook(fn);
-      expect(myHook.current).toBe(fn);
-    });
-  });
-
-  describe("hook.override", () => {
-    it("should override the current value using reducer", () => {
-      const myHook = hook(0);
-      expect(myHook.current).toBe(0);
-
-      myHook.override(() => 100);
-      expect(myHook.current).toBe(100);
-    });
-
-    it("should allow multiple overrides", () => {
-      const myHook = hook("initial");
-      myHook.override(() => "first");
-      expect(myHook.current).toBe("first");
-
-      myHook.override(() => "second");
-      expect(myHook.current).toBe("second");
-    });
-
-    it("should receive previous value in reducer", () => {
-      const myHook = hook(10);
-      myHook.override((prev) => prev + 5);
-      expect(myHook.current).toBe(15);
-
-      myHook.override((prev) => prev * 2);
-      expect(myHook.current).toBe(30);
-    });
-
-    it("should support composing handlers (middleware pattern)", () => {
-      const calls: string[] = [];
-      const myHook = hook<((msg: string) => void) | undefined>(undefined);
-
-      // First handler
-      myHook.override(() => (msg) => calls.push(`first: ${msg}`));
-
-      // Compose with second handler
-      myHook.override((prev) => (msg) => {
-        prev?.(msg);
-        calls.push(`second: ${msg}`);
-      });
-
-      myHook.current?.("hello");
-      expect(calls).toEqual(["first: hello", "second: hello"]);
-    });
-  });
-
-  describe("hook setup/release pattern", () => {
-    it("should create a setup function that returns a release function", () => {
-      const myHook = hook(0);
-      const setup = myHook(() => 10);
-
-      expect(typeof setup).toBe("function");
-
-      const release = setup();
-      expect(typeof release).toBe("function");
-      expect(myHook.current).toBe(10);
-
-      release();
-      expect(myHook.current).toBe(0);
-    });
-
-    it("should support nested setup/release", () => {
-      const myHook = hook(0);
-
-      const setup1 = myHook(() => 1);
-      const release1 = setup1();
-      expect(myHook.current).toBe(1);
-
-      const setup2 = myHook(() => 2);
-      const release2 = setup2();
-      expect(myHook.current).toBe(2);
-
-      release2();
-      expect(myHook.current).toBe(1);
-
-      release1();
-      expect(myHook.current).toBe(0);
-    });
-
-    it("should receive previous value in setup reducer", () => {
-      const myHook = hook(10);
-
-      const setup = myHook((prev) => prev + 5);
-      const release = setup();
-      expect(myHook.current).toBe(15);
-
-      release();
-      expect(myHook.current).toBe(10);
-    });
-  });
-
-  describe("hook.use", () => {
-    it("should temporarily set hook value during function execution", () => {
-      const myHook = hook(0);
-
-      const result = hook.use([myHook(() => 42)], () => {
-        expect(myHook.current).toBe(42);
-        return "done";
-      });
-
-      expect(result).toBe("done");
-      expect(myHook.current).toBe(0);
-    });
-
-    it("should support multiple hooks", () => {
-      const hookA = hook("a");
-      const hookB = hook("b");
-
-      hook.use([hookA(() => "A"), hookB(() => "B")], () => {
-        expect(hookA.current).toBe("A");
-        expect(hookB.current).toBe("B");
-      });
-
-      expect(hookA.current).toBe("a");
-      expect(hookB.current).toBe("b");
-    });
-
-    it("should restore values even if function throws", () => {
-      const myHook = hook(0);
-
-      expect(() => {
-        hook.use([myHook(() => 42)], () => {
-          expect(myHook.current).toBe(42);
-          throw new Error("test error");
-        });
-      }).toThrow("test error");
-
-      expect(myHook.current).toBe(0);
-    });
-
-    it("should support nested hook.use calls", () => {
-      const myHook = hook(0);
-
-      hook.use([myHook(() => 1)], () => {
-        expect(myHook.current).toBe(1);
-
-        hook.use([myHook(() => 2)], () => {
-          expect(myHook.current).toBe(2);
-        });
-
-        expect(myHook.current).toBe(1);
-      });
-
-      expect(myHook.current).toBe(0);
-    });
-
-    it("should release hooks in reverse order", () => {
-      const order: string[] = [];
-      const hookA = hook<string | undefined>();
-      const hookB = hook<string | undefined>();
-
-      // Create custom setups that track release order using override/reset
-      const setupA = () => {
-        hookA.override(() => "A");
-        return () => {
-          order.push("release A");
-          hookA.reset();
-        };
-      };
-
-      const setupB = () => {
-        hookB.override(() => "B");
-        return () => {
-          order.push("release B");
-          hookB.reset();
-        };
-      };
-
-      hook.use([setupA, setupB], () => {
-        expect(hookA.current).toBe("A");
-        expect(hookB.current).toBe("B");
-      });
-
-      expect(order).toEqual(["release B", "release A"]);
-    });
-
-    it("should work with empty setups array", () => {
-      const result = hook.use([], () => "result");
-      expect(result).toBe("result");
-    });
-
-    it("should return the function result", () => {
-      const myHook = hook(0);
-      const result = hook.use([myHook(() => 1)], () => {
-        return { value: myHook.current };
-      });
-      expect(result).toEqual({ value: 1 });
-    });
-
-    it("should support reducer composition in hook.use", () => {
-      const myHook = hook(10);
-
-      hook.use([myHook((prev) => prev + 5)], () => {
-        expect(myHook.current).toBe(15);
-      });
-
-      expect(myHook.current).toBe(10);
-    });
-  });
-});

package/src/core/hook.ts

@@ -1,177 +0,0 @@
-/**
- * A setup function that returns a release function.
- * Called by hook.use() to activate a hook, release restores previous value.
- */
-export type HookSetup = () => VoidFunction;
-
-/**
- * A hook is a callable factory that creates setup functions,
- * with direct access to current value via `.current`.
- *
- * @example
- * ```ts
- * const myHook = hook<string>("default");
- *
- * // Read current value (fast - direct property access)
- * console.log(myHook.current); // "default"
- *
- * // Create a setup function (reducer receives previous value)
- * const setup = myHook(() => "new value");
- *
- * // Use with hook.use()
- * hook.use([myHook(() => "temp")], () => {
- *   console.log(myHook.current); // "temp"
- * });
- * console.log(myHook.current); // "default" (restored)
- *
- * // Compose with previous value
- * myHook.override(prev => {
- *   console.log("Previous:", prev);
- *   return "next";
- * });
- * ```
- */
-export interface Hook<T> {
-  /**
-   * Creates a HookSetup that will set this hook using a reducer.
-   * The reducer receives the previous value and returns the next value.
-   *
-   * @param reducer - Function that receives previous value and returns next value
-   *
-   * @example Set new value (ignore previous)
-   * ```ts
-   * myHook(() => "new value")
-   * ```
-   *
-   * @example Compose with previous
-   * ```ts
-   * myHook(prev => {
-   *   prev?.(); // call previous handler
-   *   return newHandler;
-   * })
-   * ```
-   */
-  (reducer: (prev: T) => T): HookSetup;
-
-  /**
-   * Current value of the hook. Direct property access for fast reads.
-   */
-  readonly current: T;
-
-  /**
-   * Override the current value using a reducer.
-   * The reducer receives the previous value and returns the next value.
-   * Unlike the setup/release pattern, this is an immediate mutation.
-   *
-   * @param reducer - Function that receives previous value and returns next value
-   *
-   * @example Set new value (ignore previous)
-   * ```ts
-   * myHook.override(() => "new value")
-   * ```
-   *
-   * @example Compose with previous (middleware pattern)
-   * ```ts
-   * onCreateHook.override(prev => (info) => {
-   *   prev?.(info);  // call existing handler
-   *   console.log("Created:", info.key);
-   * });
-   * ```
-   */
-  override(reducer: (prev: T) => T): void;
-
-  /**
-   * Reset the hook to its initial value.
-   */
-  reset(): void;
-}
-
-/**
- * Creates a new hook with an initial value.
- *
- * Hooks use the setup/release pattern for performance:
- * - Reads are direct property access (fastest)
- * - Writes use setup/release for proper nesting
- *
- * @param initial - Initial value for the hook
- * @returns A Hook instance
- *
- * @example
- * ```ts
- * // Create a hook
- * const countHook = hook(0);
- *
- * // Read
- * console.log(countHook.current); // 0
- *
- * // Use with hook.use() - reducer receives previous value
- * hook.use([countHook(() => 5)], () => {
- *   console.log(countHook.current); // 5
- * });
- *
- * // Compose with previous (middleware pattern)
- * myHook.override(prev => (info) => {
- *   prev?.(info);  // call existing
- *   newHandler(info);
- * });
- * ```
- */
-function createHook<T>(initial: T): Hook<T>;
-function createHook<T>(): Hook<T | undefined>;
-function createHook<T>(initial?: T): Hook<T | undefined> {
-  // The hook function creates a setup that returns a release
-  const h = Object.assign(
-    (reducer: (prev: T | undefined) => T | undefined): HookSetup => {
-      return () => {
-        const prev = h.current;
-        h.current = reducer(prev);
-        return () => {
-          h.current = prev;
-        };
-      };
-    },
-    {
-      current: initial,
-      // Override method for direct mutation using reducer
-      override: (reducer: (prev: T | undefined) => T | undefined) => {
-        h.current = reducer(h.current);
-      },
-      reset: () => {
-        h.current = initial;
-      },
-    }
-  );
-
-  return h as Hook<T | undefined>;
-}
-
-/**
- * Executes a function with multiple hooks temporarily set.
- *
- * @param setups - Array of HookSetup functions (from hook factories)
- * @param fn - Function to execute with hooks active
- * @returns The return value of fn
- *
- * @example
- * ```ts
- * hook.use([trackHook(myTracker), debugHook(true)], () => {
- *   // hooks active here
- * });
- * ```
- */
-function use<T>(setups: HookSetup[], fn: () => T): T {
-  const releases: VoidFunction[] = [];
-  for (const setup of setups) {
-    releases.push(setup());
-  }
-  try {
-    return fn();
-  } finally {
-    for (const release of releases.reverse()) {
-      release();
-    }
-  }
-}
-
-// Combine into namespace
-export const hook = Object.assign(createHook, { use });

package/src/core/isAtom.ts

@@ -1,27 +0,0 @@
-import { Atom, DerivedAtom, SYMBOL_ATOM, SYMBOL_DERIVED } from "./types";
-
-/**
- * Type guard to check if a value is an Atom.
- */
-export function isAtom<T>(value: unknown): value is Atom<T> {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    SYMBOL_ATOM in value &&
-    (value as Atom<T>)[SYMBOL_ATOM] === true
-  );
-}
-
-/**
- * Type guard to check if a value is a DerivedAtom.
- */
-export function isDerived<T>(
-  value: unknown
-): value is DerivedAtom<T, boolean> {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    SYMBOL_DERIVED in value &&
-    (value as DerivedAtom<T, boolean>)[SYMBOL_DERIVED] === true
-  );
-}

package/src/core/isPromiseLike.test.ts

@@ -1,72 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { isPromiseLike } from "./isPromiseLike";
-
-describe("isPromiseLike", () => {
-  describe("returns true for PromiseLike values", () => {
-    it("should return true for native Promise", () => {
-      expect(isPromiseLike(Promise.resolve(1))).toBe(true);
-    });
-
-    it("should return true for rejected Promise", () => {
-      const rejected = Promise.reject(new Error("test"));
-      rejected.catch(() => {}); // Prevent unhandled rejection
-      expect(isPromiseLike(rejected)).toBe(true);
-    });
-
-    it("should return true for object with then method", () => {
-      const thenable = { then: () => {} };
-      expect(isPromiseLike(thenable)).toBe(true);
-    });
-
-    it("should return true for object with then method that takes callbacks", () => {
-      const thenable = {
-        then: (resolve: (v: number) => void, _reject: (e: Error) => void) => {
-          resolve(42);
-        },
-      };
-      expect(isPromiseLike(thenable)).toBe(true);
-    });
-  });
-
-  describe("returns false for non-PromiseLike values", () => {
-    it("should return false for null", () => {
-      expect(isPromiseLike(null)).toBe(false);
-    });
-
-    it("should return false for undefined", () => {
-      expect(isPromiseLike(undefined)).toBe(false);
-    });
-
-    it("should return false for number", () => {
-      expect(isPromiseLike(42)).toBe(false);
-    });
-
-    it("should return false for string", () => {
-      expect(isPromiseLike("hello")).toBe(false);
-    });
-
-    it("should return false for boolean", () => {
-      expect(isPromiseLike(true)).toBe(false);
-    });
-
-    it("should return false for plain object without then", () => {
-      expect(isPromiseLike({ value: 1 })).toBe(false);
-    });
-
-    it("should return false for array", () => {
-      expect(isPromiseLike([1, 2, 3])).toBe(false);
-    });
-
-    it("should return false for function", () => {
-      expect(isPromiseLike(() => {})).toBe(false);
-    });
-
-    it("should return false for object with non-function then property", () => {
-      expect(isPromiseLike({ then: "not a function" })).toBe(false);
-    });
-
-    it("should return false for object with then as number", () => {
-      expect(isPromiseLike({ then: 123 })).toBe(false);
-    });
-  });
-});

package/src/core/isPromiseLike.ts

@@ -1,16 +0,0 @@
-/**
- * Check if a value is a PromiseLike (has a .then method).
- *
- * @example
- * isPromiseLike(Promise.resolve(1)) // true
- * isPromiseLike({ then: () => {} }) // true
- * isPromiseLike(42) // false
- */
-export function isPromiseLike<T>(value: unknown): value is PromiseLike<T> {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    "then" in value &&
-    typeof (value as any).then === "function"
-  );
-}

package/src/core/onCreateHook.ts

@@ -1,107 +0,0 @@
-import { Effect } from "./effect";
-import { hook } from "./hook";
-import {
-  MutableAtomMeta,
-  DerivedAtomMeta,
-  MutableAtom,
-  DerivedAtom,
-  ModuleMeta,
-  EffectMeta,
-} from "./types";
-
-/**
- * Information provided when a mutable atom is created.
- */
-export interface MutableInfo {
-  /** Discriminator for mutable atoms */
-  type: "mutable";
-  /** Optional key from atom options (for debugging/devtools) */
-  key: string | undefined;
-  /** Optional metadata from atom options */
-  meta: MutableAtomMeta | undefined;
-  /** The created mutable atom instance */
-  instance: MutableAtom<unknown>;
-}
-
-/**
- * Information provided when a derived atom is created.
- */
-export interface DerivedInfo {
-  /** Discriminator for derived atoms */
-  type: "derived";
-  /** Optional key from derived options (for debugging/devtools) */
-  key: string | undefined;
-  /** Optional metadata from derived options */
-  meta: DerivedAtomMeta | undefined;
-  /** The created derived atom instance */
-  instance: DerivedAtom<unknown, boolean>;
-}
-
-/**
- * Information provided when an effect is created.
- */
-export interface EffectInfo {
-  /** Discriminator for effects */
-  type: "effect";
-  /** Optional key from effect options (for debugging/devtools) */
-  key: string | undefined;
-  /** Optional metadata from effect options */
-  meta: EffectMeta | undefined;
-  /** The created effect instance */
-  instance: Effect;
-}
-
-/**
- * Union type for atom/derived/effect creation info.
- */
-export type CreateInfo = MutableInfo | DerivedInfo | EffectInfo;
-
-/**
- * Information provided when a module (via define()) is created.
- */
-export interface ModuleInfo {
-  /** Discriminator for modules */
-  type: "module";
-  /** Optional key from define options (for debugging/devtools) */
-  key: string | undefined;
-  /** Optional metadata from define options */
-  meta: ModuleMeta | undefined;
-  /** The created module instance */
-  instance: unknown;
-}
-
-/**
- * Global hook that fires whenever an atom or module is created.
- *
- * This is useful for:
- * - **DevTools integration** - track all atoms/modules in the app
- * - **Debugging** - log atom creation for troubleshooting
- * - **Testing** - verify expected atoms are created
- *
- * **IMPORTANT**: Always use `.override()` to preserve the hook chain.
- * Direct assignment to `.current` will break existing handlers.
- *
- * @example Basic logging
- * ```ts
- * onCreateHook.override((prev) => (info) => {
- *   prev?.(info); // call existing handlers first
- *   console.log(`Created ${info.type}: ${info.key ?? "anonymous"}`);
- * });
- * ```
- *
- * @example DevTools integration
- * ```ts
- * const registry = new Map();
- *
- * onCreateHook.override((prev) => (info) => {
- *   prev?.(info); // preserve chain
- *   registry.set(info.key, info.instance);
- * });
- * ```
- *
- * @example Reset to default (disable all handlers)
- * ```ts
- * onCreateHook.reset();
- * ```
- */
-export const onCreateHook = hook<(info: CreateInfo | ModuleInfo) => void>();