atomirx 0.0.7 → 0.1.0

package/src/core/equality.test.ts

@@ -1,392 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  strictEqual,
-  shallowEqual,
-  shallow2Equal,
-  shallow3Equal,
-  deepEqual,
-  resolveEquality,
-  equality,
-  createStableFn,
-  isStableFn,
-  tryStabilize,
-} from "./equality";
-
-describe("equality", () => {
-  describe("strictEqual", () => {
-    it("should return true for same reference", () => {
-      const obj = { a: 1 };
-      expect(strictEqual(obj, obj)).toBe(true);
-    });
-
-    it("should return false for different references with same content", () => {
-      expect(strictEqual({ a: 1 }, { a: 1 })).toBe(false);
-    });
-
-    it("should return true for same primitives", () => {
-      expect(strictEqual(1, 1)).toBe(true);
-      expect(strictEqual("hello", "hello")).toBe(true);
-      expect(strictEqual(true, true)).toBe(true);
-    });
-
-    it("should handle NaN correctly (Object.is behavior)", () => {
-      expect(strictEqual(NaN, NaN)).toBe(true);
-    });
-
-    it("should distinguish +0 and -0", () => {
-      expect(strictEqual(0, -0)).toBe(false);
-    });
-  });
-
-  describe("shallowEqual", () => {
-    it("should return true for same reference", () => {
-      const obj = { a: 1 };
-      expect(shallowEqual(obj, obj)).toBe(true);
-    });
-
-    it("should return true for objects with same keys and values", () => {
-      expect(shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2 })).toBe(true);
-    });
-
-    it("should return false for objects with different keys", () => {
-      expect(shallowEqual({ a: 1 }, { b: 1 })).toBe(false);
-    });
-
-    it("should return false for objects with different values", () => {
-      expect(shallowEqual({ a: 1 }, { a: 2 })).toBe(false);
-    });
-
-    it("should return false for objects with different number of keys", () => {
-      expect(shallowEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false);
-    });
-
-    it("should return true for arrays with same elements", () => {
-      expect(shallowEqual([1, 2, 3], [1, 2, 3])).toBe(true);
-    });
-
-    it("should return false for arrays with different elements", () => {
-      expect(shallowEqual([1, 2, 3], [1, 2, 4])).toBe(false);
-    });
-
-    it("should return false for arrays with different lengths", () => {
-      expect(shallowEqual([1, 2], [1, 2, 3])).toBe(false);
-    });
-
-    it("should return false for nested objects with different references", () => {
-      expect(shallowEqual({ nested: { a: 1 } }, { nested: { a: 1 } })).toBe(
-        false
-      );
-    });
-
-    it("should return true for nested objects with same reference", () => {
-      const nested = { a: 1 };
-      expect(shallowEqual({ nested }, { nested })).toBe(true);
-    });
-
-    it("should return false when comparing object to null", () => {
-      expect(shallowEqual({ a: 1 }, null as any)).toBe(false);
-    });
-
-    it("should return false when comparing object to primitive", () => {
-      expect(shallowEqual({ a: 1 }, 1 as any)).toBe(false);
-    });
-
-    it("should support custom item comparator", () => {
-      const customEqual = (a: unknown, b: unknown) =>
-        JSON.stringify(a) === JSON.stringify(b);
-      expect(
-        shallowEqual({ nested: { a: 1 } }, { nested: { a: 1 } }, customEqual)
-      ).toBe(true);
-    });
-  });
-
-  describe("shallow2Equal", () => {
-    it("should compare 2 levels deep", () => {
-      expect(
-        shallow2Equal({ nested: { a: 1 } }, { nested: { a: 1 } })
-      ).toBe(true);
-    });
-
-    it("should return false for 3 levels deep difference", () => {
-      expect(
-        shallow2Equal(
-          { nested: { deep: { a: 1 } } },
-          { nested: { deep: { a: 1 } } }
-        )
-      ).toBe(false);
-    });
-
-    it("should work with arrays of objects", () => {
-      expect(shallow2Equal([{ id: 1 }], [{ id: 1 }])).toBe(true);
-    });
-  });
-
-  describe("shallow3Equal", () => {
-    it("should compare 3 levels deep", () => {
-      expect(
-        shallow3Equal(
-          { nested: { deep: { a: 1 } } },
-          { nested: { deep: { a: 1 } } }
-        )
-      ).toBe(true);
-    });
-
-    it("should return false for 4 levels deep difference", () => {
-      expect(
-        shallow3Equal(
-          { l1: { l2: { l3: { a: 1 } } } },
-          { l1: { l2: { l3: { a: 1 } } } }
-        )
-      ).toBe(false);
-    });
-  });
-
-  describe("deepEqual", () => {
-    it("should compare deeply nested objects", () => {
-      expect(
-        deepEqual(
-          { a: { b: { c: { d: 1 } } } },
-          { a: { b: { c: { d: 1 } } } }
-        )
-      ).toBe(true);
-    });
-
-    it("should return false for deeply nested differences", () => {
-      expect(
-        deepEqual(
-          { a: { b: { c: { d: 1 } } } },
-          { a: { b: { c: { d: 2 } } } }
-        )
-      ).toBe(false);
-    });
-
-    it("should handle arrays", () => {
-      expect(deepEqual([1, [2, [3]]], [1, [2, [3]]])).toBe(true);
-    });
-
-    it("should handle Date objects", () => {
-      const date = new Date("2024-01-01");
-      expect(deepEqual(date, new Date("2024-01-01"))).toBe(true);
-    });
-  });
-
-  describe("resolveEquality", () => {
-    it("should return strictEqual for undefined", () => {
-      expect(resolveEquality(undefined)).toBe(strictEqual);
-    });
-
-    it("should return strictEqual for 'strict'", () => {
-      expect(resolveEquality("strict")).toBe(strictEqual);
-    });
-
-    it("should return shallowEqual for 'shallow'", () => {
-      expect(resolveEquality("shallow")).toBe(shallowEqual);
-    });
-
-    it("should return shallow2Equal for 'shallow2'", () => {
-      expect(resolveEquality("shallow2")).toBe(shallow2Equal);
-    });
-
-    it("should return shallow3Equal for 'shallow3'", () => {
-      expect(resolveEquality("shallow3")).toBe(shallow3Equal);
-    });
-
-    it("should return deepEqual for 'deep'", () => {
-      expect(resolveEquality("deep")).toBe(deepEqual);
-    });
-
-    it("should return custom function as-is", () => {
-      const customFn = (a: number, b: number) => a === b;
-      expect(resolveEquality(customFn)).toBe(customFn);
-    });
-  });
-
-  describe("equality helper", () => {
-    it("should be an alias for resolveEquality with shorthand", () => {
-      expect(equality("strict")).toBe(strictEqual);
-      expect(equality("shallow")).toBe(shallowEqual);
-      expect(equality("deep")).toBe(deepEqual);
-    });
-  });
-});
-
-describe("StableFn", () => {
-  describe("createStableFn", () => {
-    it("should create a callable wrapper", () => {
-      const fn = (x: number) => x * 2;
-      const stable = createStableFn(fn);
-
-      expect(stable(5)).toBe(10);
-    });
-
-    it("should preserve original function via getOriginal", () => {
-      const fn = (x: number) => x * 2;
-      const stable = createStableFn(fn);
-
-      expect(stable.getOriginal()).toBe(fn);
-    });
-
-    it("should return current function via getCurrent", () => {
-      const fn = (x: number) => x * 2;
-      const stable = createStableFn(fn);
-
-      expect(stable.getCurrent()).toBe(fn);
-    });
-
-    it("should allow updating current function via setCurrent", () => {
-      const fn1 = (x: number) => x * 2;
-      const fn2 = (x: number) => x * 3;
-      const stable = createStableFn(fn1);
-
-      stable.setCurrent(fn2);
-
-      expect(stable(5)).toBe(15);
-      expect(stable.getCurrent()).toBe(fn2);
-      expect(stable.getOriginal()).toBe(fn1);
-    });
-  });
-
-  describe("isStableFn", () => {
-    it("should return true for StableFn", () => {
-      const stable = createStableFn(() => 42);
-      expect(isStableFn(stable)).toBe(true);
-    });
-
-    it("should return false for regular function", () => {
-      expect(isStableFn(() => 42)).toBe(false);
-    });
-
-    it("should return false for non-function", () => {
-      expect(isStableFn({ a: 1 })).toBe(false);
-      expect(isStableFn(42)).toBe(false);
-      expect(isStableFn("string")).toBe(false);
-    });
-
-    it("should return false for function with partial StableFn interface", () => {
-      const partial = Object.assign(() => 42, { getOriginal: () => {} });
-      expect(isStableFn(partial)).toBe(false);
-    });
-  });
-});
-
-describe("tryStabilize", () => {
-  describe("first call (no previous value)", () => {
-    it("should return value as-is for non-function", () => {
-      const [result, wasStable] = tryStabilize(undefined, 42, strictEqual);
-      expect(result).toBe(42);
-      expect(wasStable).toBe(false);
-    });
-
-    it("should wrap function in StableFn", () => {
-      const fn = () => 42;
-      const [result, wasStable] = tryStabilize(undefined, fn, strictEqual);
-
-      expect(isStableFn(result)).toBe(true);
-      expect(result()).toBe(42);
-      expect(wasStable).toBe(false);
-    });
-  });
-
-  describe("subsequent calls with functions", () => {
-    it("should update existing StableFn and return stable", () => {
-      const fn1 = () => 1;
-      const fn2 = () => 2;
-
-      const [stable1] = tryStabilize(undefined, fn1, strictEqual);
-      const [stable2, wasStable] = tryStabilize(
-        { value: stable1 },
-        fn2,
-        strictEqual
-      );
-
-      expect(stable2).toBe(stable1); // Same reference
-      expect(stable2()).toBe(2); // But calls new function
-      expect(wasStable).toBe(true);
-    });
-
-    it("should create new StableFn if previous was not StableFn", () => {
-      const fn = () => 42;
-      const [result, wasStable] = tryStabilize(
-        { value: "not a stable fn" as any },
-        fn,
-        strictEqual
-      );
-
-      expect(isStableFn(result)).toBe(true);
-      expect(wasStable).toBe(false);
-    });
-  });
-
-  describe("Date handling", () => {
-    it("should return previous Date if timestamps match", () => {
-      const date1 = new Date("2024-01-01");
-      const date2 = new Date("2024-01-01");
-
-      const [result, wasStable] = tryStabilize(
-        { value: date1 },
-        date2,
-        strictEqual
-      );
-
-      expect(result).toBe(date1);
-      expect(wasStable).toBe(true);
-    });
-
-    it("should return new Date if timestamps differ", () => {
-      const date1 = new Date("2024-01-01");
-      const date2 = new Date("2024-01-02");
-
-      const [result, wasStable] = tryStabilize(
-        { value: date1 },
-        date2,
-        strictEqual
-      );
-
-      expect(result).toBe(date2);
-      expect(wasStable).toBe(false);
-    });
-
-    it("should return new Date if previous was not a Date", () => {
-      const date = new Date("2024-01-01");
-
-      const [result, wasStable] = tryStabilize(
-        { value: "not a date" as any },
-        date,
-        strictEqual
-      );
-
-      expect(result).toBe(date);
-      expect(wasStable).toBe(false);
-    });
-  });
-
-  describe("equality-based stabilization", () => {
-    it("should return previous value if equal", () => {
-      const obj1 = { a: 1 };
-      const obj2 = { a: 1 };
-
-      const [result, wasStable] = tryStabilize(
-        { value: obj1 },
-        obj2,
-        shallowEqual
-      );
-
-      expect(result).toBe(obj1);
-      expect(wasStable).toBe(true);
-    });
-
-    it("should return new value if not equal", () => {
-      const obj1 = { a: 1 };
-      const obj2 = { a: 2 };
-
-      const [result, wasStable] = tryStabilize(
-        { value: obj1 },
-        obj2,
-        shallowEqual
-      );
-
-      expect(result).toBe(obj2);
-      expect(wasStable).toBe(false);
-    });
-  });
-});

package/src/core/equality.ts

@@ -1,182 +0,0 @@
-/**
- * Equality utilities for comparing values.
- */
-
-import type { AnyFunc, Equality, EqualityShorthand } from "./types";
-import isEqual from "lodash/isEqual";
-
-/**
- * Strict equality (Object.is).
- */
-export function strictEqual<T>(a: T, b: T): boolean {
-  return Object.is(a, b);
-}
-
-/**
- * Shallow equality for objects/arrays.
- * Compares by reference for each top-level key/index.
- *
- * @param itemEqual - Optional comparator for each item/value (defaults to Object.is)
- */
-export function shallowEqual<T>(
-  a: T,
-  b: T,
-  itemEqual: (a: unknown, b: unknown) => boolean = Object.is
-): boolean {
-  if (Object.is(a, b)) return true;
-  if (typeof a !== "object" || a === null) return false;
-  if (typeof b !== "object" || b === null) return false;
-
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-
-  if (keysA.length !== keysB.length) return false;
-
-  for (const key of keysA) {
-    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
-    if (!itemEqual((a as any)[key], (b as any)[key])) return false;
-  }
-
-  return true;
-}
-
-/**
- * 2-level shallow equality.
- * Compares keys/length, then shallow compares each item/value.
- *
- * @example
- * [{ id: 1, data: obj }] vs [{ id: 1, data: obj }] // true (same obj ref)
- */
-export function shallow2Equal<T>(a: T, b: T): boolean {
-  return shallowEqual(a, b, shallowEqual);
-}
-
-/**
- * 3-level shallow equality.
- * Compares keys/length, then shallow2 compares each item/value.
- *
- * @example
- * [{ id: 1, nested: { data: obj } }] vs [{ id: 1, nested: { data: obj } }] // true
- */
-export function shallow3Equal<T>(a: T, b: T): boolean {
-  return shallowEqual(a, b, shallow2Equal);
-}
-
-/**
- * Deep equality.
- */
-export const deepEqual = isEqual;
-
-/**
- * Resolve equality strategy to a function.
- */
-export function resolveEquality<T>(
-  e: Equality<T> | undefined
-): (a: T, b: T) => boolean {
-  if (!e || e === "strict") return strictEqual;
-  if (e === "shallow") return shallowEqual;
-  if (e === "shallow2") return shallow2Equal;
-  if (e === "shallow3") return shallow3Equal;
-  if (e === "deep") return deepEqual;
-  return e;
-}
-
-export function equality(shorthand: EqualityShorthand) {
-  return resolveEquality(shorthand);
-}
-
-// =============================================================================
-// Value Stabilization
-// =============================================================================
-
-export type StableFn<TArgs extends any[], TResult> = ((...args: TArgs) => TResult) & {
-  getOriginal: () => (...args: TArgs) => TResult;
-  getCurrent: () => (...args: TArgs) => TResult;
-  setCurrent: (newFn: (...args: TArgs) => TResult) => void;
-};
-
-export function createStableFn<TArgs extends any[], TResult>(
-  fn: (...args: TArgs) => TResult
-): StableFn<TArgs, TResult> {
-  const originalFn = fn;
-  let currentFn = fn;
-  return Object.assign(
-    (...args: TArgs) => {
-      return currentFn(...args);
-    },
-    {
-      getOriginal: () => originalFn,
-      getCurrent: () => currentFn,
-      setCurrent(newFn: (...args: TArgs) => TResult) {
-        currentFn = newFn;
-      },
-    }
-  );
-}
-
-/**
- * Check if a value is a stable function wrapper.
- */
-export function isStableFn<TArgs extends any[], TResult>(
-  value: unknown
-): value is StableFn<TArgs, TResult> {
-  return (
-    typeof value === "function" &&
-    "getOriginal" in value &&
-    "getCurrent" in value &&
-    "setCurrent" in value
-  );
-}
-
-/**
- * Stabilize a value with automatic function wrapper support.
- *
- * - Functions: Creates/updates stable wrapper (reference never changes)
- * - Date objects: Compared by timestamp (uses deepEqual)
- * - Other values: Returns previous if equal per equalityFn
- *
- * @param prev - Previous value container (or undefined for first call)
- * @param next - New value
- * @param equalityFn - Equality function for non-function/non-date values
- * @returns Tuple of [stabilized value, wasStable]
- */
-export function tryStabilize<T>(
-  prev: { value: T } | undefined,
-  next: T,
-  equalityFn: (a: T, b: T) => boolean
-): [T, boolean] {
-  // First time - no previous value
-  if (!prev) {
-    if (typeof next === "function") {
-      return [createStableFn(next as AnyFunc) as T, false];
-    }
-    return [next, false];
-  }
-
-  // Handle functions with stable wrapper pattern
-  if (typeof next === "function") {
-    if (isStableFn(prev.value)) {
-      // Update existing stable wrapper with new function
-      prev.value.setCurrent(next as AnyFunc);
-      return [prev.value as T, true];
-    }
-    // Previous wasn't a stable fn, create new wrapper
-    return [createStableFn(next as AnyFunc) as T, false];
-  }
-
-  if (next && next instanceof Date) {
-    if (prev.value && prev.value instanceof Date) {
-      if (next.getTime() === prev.value.getTime()) {
-        return [prev.value, true];
-      }
-    }
-    return [next, false];
-  }
-
-  // Non-functions: use equality comparison
-  if (equalityFn(prev.value, next)) {
-    return [prev.value, true];
-  }
-
-  return [next, false];
-}

package/src/core/getAtomState.ts

@@ -1,69 +0,0 @@
-import { isDerived } from "./isAtom";
-import { isPromiseLike } from "./isPromiseLike";
-import { trackPromise } from "./promiseCache";
-import { Atom, AtomState, DerivedAtom } from "./types";
-
-/**
- * Returns the current state of an atom as a discriminated union.
- *
- * For any atom (mutable or derived):
- * - If value is not a Promise: returns ready state
- * - If value is a Promise: tracks and returns its state (ready/error/loading)
- *
- * @param atom - The atom to get state from
- * @returns AtomState discriminated union (ready | error | loading)
- *
- * @example
- * ```ts
- * const state = getAtomState(myAtom$);
- *
- * switch (state.status) {
- *   case "ready":
- *     console.log(state.value); // T
- *     break;
- *   case "error":
- *     console.log(state.error);
- *     break;
- *   case "loading":
- *     console.log(state.promise);
- *     break;
- * }
- * ```
- */
-export function getAtomState<T>(atom: Atom<T>): AtomState<Awaited<T>> {
-  if (isDerived(atom)) {
-    return (atom as DerivedAtom<Awaited<T>>).state();
-  }
-  const value = atom.get();
-
-  // 1. Sync value - ready
-  if (!isPromiseLike(value)) {
-    return {
-      status: "ready",
-      value: value as Awaited<T>,
-    };
-  }
-
-  // 2. Promise value - check state via promiseCache
-  const state = trackPromise(value);
-
-  switch (state.status) {
-    case "fulfilled":
-      return {
-        status: "ready",
-        value: state.value as Awaited<T>,
-      };
-
-    case "rejected":
-      return {
-        status: "error",
-        error: state.error,
-      };
-
-    case "pending":
-      return {
-        status: "loading",
-        promise: state.promise as Promise<Awaited<T>>,
-      };
-  }
-}