atomirx 0.0.8 → 0.1.1

package/src/core/define.test.ts

@@ -1,343 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { define } from "./define";
-import { onCreateHook } from "./onCreateHook";
-
-describe("define", () => {
-  beforeEach(() => {
-    onCreateHook.reset();
-  });
-
-  afterEach(() => {
-    onCreateHook.reset();
-  });
-
-  describe("basic functionality", () => {
-    it("should create a lazy singleton", () => {
-      const creator = vi.fn(() => ({ value: 42 }));
-      const store = define(creator);
-
-      // Creator not called yet
-      expect(creator).not.toHaveBeenCalled();
-
-      // First access creates instance
-      const instance1 = store();
-      expect(creator).toHaveBeenCalledTimes(1);
-      expect(instance1.value).toBe(42);
-
-      // Second access returns same instance
-      const instance2 = store();
-      expect(creator).toHaveBeenCalledTimes(1);
-      expect(instance2).toBe(instance1);
-    });
-
-    it("should store key from options", () => {
-      const store = define(() => ({}), { key: "myStore" });
-      expect(store.key).toBe("myStore");
-    });
-
-    it("should have undefined key when not provided", () => {
-      const store = define(() => ({}));
-      expect(store.key).toBeUndefined();
-    });
-  });
-
-  describe("isInitialized", () => {
-    it("should return false before first access", () => {
-      const store = define(() => ({ value: 1 }));
-      expect(store.isInitialized()).toBe(false);
-    });
-
-    it("should return true after first access", () => {
-      const store = define(() => ({ value: 1 }));
-      store();
-      expect(store.isInitialized()).toBe(true);
-    });
-  });
-
-  describe("override", () => {
-    it("should allow overriding before initialization", () => {
-      const store = define(() => ({ value: "original" }));
-
-      store.override(() => ({ value: "overridden" }));
-
-      expect(store().value).toBe("overridden");
-    });
-
-    it("should throw if override called after initialization", () => {
-      const store = define(() => ({ value: "original" }));
-
-      // Initialize
-      store();
-
-      expect(() => {
-        store.override(() => ({ value: "overridden" }));
-      }).toThrow(
-        "Cannot override after initialization. Call override() before accessing the service."
-      );
-    });
-
-    it("should provide original factory to override function", () => {
-      const store = define(() => ({ value: 1, extra: false }));
-
-      store.override((original) => ({
-        ...original(),
-        extra: true,
-      }));
-
-      const instance = store();
-      expect(instance.value).toBe(1);
-      expect(instance.extra).toBe(true);
-    });
-
-    it("should allow wrapping original behavior", () => {
-      const store = define(() => ({
-        getValue: () => 10 as number,
-      }));
-
-      store.override((original) => {
-        const base = original();
-        return {
-          getValue: () => base.getValue() * 2,
-        };
-      });
-
-      expect(store().getValue()).toBe(20);
-    });
-  });
-
-  describe("isOverridden", () => {
-    it("should return false when not overridden", () => {
-      const store = define(() => ({}));
-      expect(store.isOverridden()).toBe(false);
-    });
-
-    it("should return true when overridden", () => {
-      const store = define(() => ({}));
-      store.override(() => ({}));
-      expect(store.isOverridden()).toBe(true);
-    });
-
-    it("should return false after reset", () => {
-      const store = define(() => ({}));
-      store.override(() => ({}));
-      store.reset();
-      expect(store.isOverridden()).toBe(false);
-    });
-  });
-
-  describe("reset", () => {
-    it("should clear override and instance", () => {
-      const creator = vi.fn(() => ({ value: "original" }));
-      const store = define(creator);
-
-      store.override(() => ({ value: "overridden" }));
-      expect(store().value).toBe("overridden");
-
-      store.reset();
-
-      // Override cleared, original creator used
-      expect(store().value).toBe("original");
-      expect(store.isOverridden()).toBe(false);
-    });
-
-    it("should call dispose if present", () => {
-      const dispose = vi.fn();
-      const store = define(() => ({
-        value: 1,
-        dispose,
-      }));
-
-      store(); // Initialize
-      store.reset();
-
-      expect(dispose).toHaveBeenCalledTimes(1);
-    });
-
-    it("should allow re-initialization after reset", () => {
-      const creator = vi.fn(() => ({ value: Math.random() }));
-      const store = define(creator);
-
-      const first = store();
-      store.reset();
-      const second = store();
-
-      expect(first).not.toBe(second);
-      expect(creator).toHaveBeenCalledTimes(2);
-    });
-  });
-
-  describe("invalidate", () => {
-    it("should clear instance and allow re-creation", () => {
-      let counter = 0;
-      const store = define(() => ({ id: ++counter }));
-
-      expect(store().id).toBe(1);
-      expect(store().id).toBe(1); // Same instance
-
-      store.invalidate();
-
-      expect(store().id).toBe(2); // New instance
-    });
-
-    it("should call dispose if present", () => {
-      const dispose = vi.fn();
-      const store = define(() => ({
-        value: 1,
-        dispose,
-      }));
-
-      store(); // Initialize
-      store.invalidate();
-
-      expect(dispose).toHaveBeenCalledTimes(1);
-    });
-
-    it("should also clear override", () => {
-      const store = define(() => ({ value: "original" }));
-
-      store.override(() => ({ value: "overridden" }));
-      expect(store().value).toBe("overridden");
-
-      store.invalidate();
-
-      expect(store.isOverridden()).toBe(false);
-      expect(store().value).toBe("original");
-    });
-  });
-
-  describe("dispose handling", () => {
-    it("should not throw if dispose is not a function", () => {
-      const store = define(() => ({
-        value: 1,
-        dispose: "not a function",
-      }));
-
-      store();
-
-      expect(() => store.reset()).not.toThrow();
-    });
-
-    it("should not throw if instance has no dispose", () => {
-      const store = define(() => ({ value: 1 }));
-
-      store();
-
-      expect(() => store.reset()).not.toThrow();
-    });
-
-    it("should handle null instance gracefully", () => {
-      const store = define(() => ({ value: 1 }));
-
-      // Reset without initialization
-      expect(() => store.reset()).not.toThrow();
-    });
-  });
-
-  describe("onCreateHook", () => {
-    it("should call onCreateHook when module is created", () => {
-      const hookFn = vi.fn();
-      onCreateHook.override(() => hookFn);
-
-      const store = define(() => ({ value: 42 }), { key: "testModule" });
-      const instance = store();
-
-      expect(hookFn).toHaveBeenCalledTimes(1);
-      expect(hookFn).toHaveBeenCalledWith({
-        type: "module",
-        key: "testModule",
-        meta: undefined,
-        instance,
-      });
-    });
-
-    it("should call onCreateHook with undefined key when not provided", () => {
-      const hookFn = vi.fn();
-      onCreateHook.override(() => hookFn);
-
-      const store = define(() => ({ value: 42 }));
-      store();
-
-      expect(hookFn).toHaveBeenCalledWith({
-        type: "module",
-        key: undefined,
-        meta: undefined,
-        instance: expect.any(Object),
-      });
-    });
-
-    it("should not throw when onCreateHook is undefined", () => {
-      onCreateHook.reset();
-
-      const store = define(() => ({ value: 42 }));
-      expect(() => store()).not.toThrow();
-    });
-
-    it("should call onCreateHook for overridden module", () => {
-      const hookFn = vi.fn();
-      onCreateHook.override(() => hookFn);
-
-      const store = define(() => ({ value: "original" }));
-      store.override(() => ({ value: "overridden" }));
-      const instance = store();
-
-      expect(hookFn).toHaveBeenCalledWith({
-        type: "module",
-        key: undefined,
-        meta: undefined,
-        instance,
-      });
-    });
-  });
-
-  describe("real-world patterns", () => {
-    it("should work as a service container", () => {
-      const apiService = define(() => ({
-        baseUrl: "https://api.example.com",
-        fetch: (endpoint: string) => `${endpoint}`,
-      }));
-
-      const userService = define(() => ({
-        api: apiService(),
-        getUser: (id: number) => `user-${id}`,
-      }));
-
-      expect(userService().api.baseUrl).toBe("https://api.example.com");
-      expect(userService().getUser(1)).toBe("user-1");
-    });
-
-    it("should support testing with mocks", () => {
-      const apiService = define(() => ({
-        fetch: (url: string) => `real-${url}`,
-      }));
-
-      // In test setup
-      apiService.override(() => ({
-        fetch: vi.fn((url: string) => `mock-${url}`),
-      }));
-
-      expect(apiService().fetch("/users")).toBe("mock-/users");
-
-      // Cleanup
-      apiService.reset();
-      expect(apiService().fetch("/users")).toBe("real-/users");
-    });
-
-    it("should support platform-specific implementations", () => {
-      const storageService = define(() => ({
-        get: (key: string) => `localStorage-${key}`,
-        set: (_key: string, _value: string) => {},
-      }));
-
-      // Simulate mobile platform override
-      const isMobile = true;
-      if (isMobile) {
-        storageService.override(() => ({
-          get: (key: string) => `secureStorage-${key}`,
-          set: (_key: string, _value: string) => {},
-        }));
-      }
-
-      expect(storageService().get("token")).toBe("secureStorage-token");
-    });
-  });
-});

package/src/core/define.ts

@@ -1,243 +0,0 @@
-import { onCreateHook } from "./onCreateHook";
-import { ModuleMeta } from "./types";
-
-/**
- * A factory function that creates a swappable lazy singleton store.
- *
- * @template TModule The type of the store instance
- */
-export interface Define<TModule> {
-  readonly key: string | undefined;
-  /** Get the current service instance (creates lazily on first call) */
-  (): TModule;
-
-  /**
-   * Override the service implementation with a lazy factory.
-   * Useful for testing, platform-specific implementations, or feature flags.
-   * The factory is called lazily on first access after override.
-   *
-   * **IMPORTANT**: Must be called **before** the service is initialized.
-   * Throws an error if called after the service has been accessed.
-   *
-   * @param factory - Factory function that creates the replacement implementation.
-   *                  Receives the original factory as argument for extending.
-   *
-   * @throws {Error} If called after the service has been initialized
-   *
-   * @example Full replacement
-   * ```ts
-   * myService.override(() => ({ value: 'mock' }));
-   * ```
-   *
-   * @example Extend original
-   * ```ts
-   * myService.override((original) => ({
-   *   ...original(),
-   *   extraMethod() { ... }
-   * }));
-   * ```
-   */
-  override(factory: (original: () => TModule) => TModule): void;
-
-  /**
-   * Reset to the original implementation.
-   * Clears any override set via `.override()` and disposes the current instance.
-   * Next access will create a fresh original instance.
-   */
-  reset(): void;
-
-  /**
-   * Invalidate the cached instance. Next call will create a fresh instance.
-   * If the current instance has a `dispose()` method, it will be called before clearing.
-   *
-   * Unlike `reset()` which only clears overrides, `invalidate()` clears everything
-   * so the next access creates a completely fresh instance from the factory.
-   */
-  invalidate(): void;
-
-  /** Returns true if currently using an overridden implementation via `.override()` */
-  isOverridden(): boolean;
-
-  /** Returns true if the lazy instance has been created */
-  isInitialized(): boolean;
-}
-
-export interface DefineOptions {
-  key?: string;
-  meta?: ModuleMeta;
-}
-
-/**
- * Creates a swappable lazy singleton store.
- *
- * Unlike `once()` from lodash, `define()` allows you to:
- * - Override the implementation at runtime with `.override()`
- * - Reset to the original with `.reset()`
- * - Invalidate and recreate fresh with `.invalidate()`
- *
- * This is useful for:
- * - **Testing** - inject mocks without module mocking
- * - **Platform-specific** - mobile vs web implementations
- * - **Feature flags** - swap implementations at runtime
- *
- * @param creator - Factory function that creates the store instance
- * @returns A callable store with `.override()`, `.reset()`, and `.invalidate()` methods
- *
- * @example Basic usage
- * ```ts
- * const counterStore = define(() => {
- *   const [count, setCount] = atom(0);
- *   return {
- *     count,
- *     increment: () => setCount((c) => c + 1),
- *   };
- * });
- *
- * // Normal usage - lazy singleton
- * const store = counterStore();
- * store.increment();
- * ```
- *
- * @example Platform-specific implementation
- * ```ts
- * const storageStore = define(() => ({
- *   get: (key) => localStorage.getItem(key),
- *   set: (key, value) => localStorage.setItem(key, value),
- * }));
- *
- * // On mobile, swap to secure storage BEFORE first access
- * if (isMobile()) {
- *   storageStore.override(() => ({
- *     get: (key) => SecureStore.getItem(key),
- *     set: (key, value) => SecureStore.setItem(key, value),
- *   }));
- * }
- * ```
- *
- * @example Extending original with extra methods
- * ```ts
- * apiStore.override((original) => ({
- *   ...original(),
- *   mockFetch: vi.fn(),
- * }));
- * ```
- *
- * @example Wrapping original behavior
- * ```ts
- * loggerStore.override((original) => {
- *   const base = original();
- *   return {
- *     ...base,
- *     log: (msg) => {
- *       console.log('[DEBUG]', msg);
- *       base.log(msg);
- *     },
- *   };
- * });
- * ```
- *
- * @example Testing with reset (creates fresh instances)
- * ```ts
- * beforeEach(() => {
- *   counterStore.override(() => ({
- *     count: () => 999,
- *     increment: vi.fn(),
- *   }));
- * });
- *
- * afterEach(() => {
- *   counterStore.reset(); // Clears override, next call creates fresh original
- * });
- * ```
- *
- * @example Testing with invalidate (fresh instance each test)
- * ```ts
- * afterEach(() => {
- *   counterStore.invalidate(); // Next call creates fresh instance
- * });
- *
- * it('test 1', () => {
- *   counterStore().increment(); // count = 1
- * });
- *
- * it('test 2', () => {
- *   // Fresh instance, count starts at 0 again
- *   expect(counterStore().count()).toBe(0);
- * });
- * ```
- *
- * @example Store with dispose cleanup
- * ```ts
- * const connectionStore = define(() => {
- *   const connection = createConnection();
- *   return {
- *     query: (sql) => connection.query(sql),
- *     dispose: () => connection.close(), // Called on invalidate()
- *   };
- * });
- *
- * connectionStore.invalidate(); // Closes connection, next call creates new
- * ```
- */
-export function define<T>(
-  creator: () => T,
-  options?: DefineOptions
-): Define<T> {
-  let instance: T | undefined;
-  let overrideFactory: ((original: () => T) => T) | undefined;
-
-  const tryDispose = (target: T | undefined) => {
-    if (
-      target &&
-      typeof target === "object" &&
-      "dispose" in target &&
-      typeof target.dispose === "function"
-    ) {
-      target.dispose();
-    }
-  };
-
-  const clearInstance = () => {
-    tryDispose(instance);
-    instance = undefined;
-  };
-
-  const get = (): T => {
-    if (!instance) {
-      if (overrideFactory) {
-        instance = overrideFactory!(creator);
-      } else {
-        instance = creator();
-      }
-      onCreateHook.current?.({
-        type: "module",
-        key: options?.key,
-        meta: options?.meta,
-        instance,
-      });
-    }
-    return instance;
-  };
-
-  return Object.assign(get, {
-    key: options?.key,
-    override: (factory: (original: () => T) => T) => {
-      if (instance !== undefined) {
-        throw new Error(
-          "Cannot override after initialization. Call override() before accessing the service."
-        );
-      }
-      overrideFactory = factory;
-    },
-    reset: () => {
-      overrideFactory = undefined;
-      clearInstance();
-    },
-    invalidate: () => {
-      overrideFactory = undefined;
-      clearInstance();
-    },
-    isOverridden: () => overrideFactory !== undefined,
-    isInitialized: () => instance !== undefined,
-  });
-}