@servicetitan/react-ioc 38.0.0 → 38.2.0

package/src/__tests__/use-local-stores.test.tsx

@@ -0,0 +1,849 @@
+import '@testing-library/jest-dom';
+import { render, screen, waitFor } from '@testing-library/react';
+import { Component, ErrorInfo, PropsWithChildren, ReactNode, StrictMode } from 'react';
+import { inject, injectable, Provider, Store, useDependencies, useLocalStores } from '..';
+
+@injectable()
+class MinimalStore extends Store {
+    isInitialized = false;
+    isDisposed = false;
+
+    initialize() {
+        this.isInitialized = true;
+    }
+    dispose() {
+        this.isDisposed = true;
+    }
+}
+
+@injectable()
+class StatStore {
+    readonly id = 'stat';
+    counters: Record<string, number> = {};
+
+    testInitialize: (id: string) => void = jest.fn();
+    testDispose: (id: string) => void = jest.fn();
+
+    register(name: string) {
+        if (!this.counters[name]) {
+            this.counters[name] = 0;
+        }
+
+        this.counters[name]++;
+
+        return `${name}-${this.counters[name]}`;
+    }
+}
+
+// inheritable
+@injectable()
+class StoreSimple extends Store {
+    id: string;
+
+    constructor(
+        @inject(StatStore) protected stat: StatStore,
+
+        // nested transitive when not required by a consuming class
+        @inject(MinimalStore) public minimalStore: MinimalStore
+    ) {
+        super();
+        this.id = stat.register('StoreSimple');
+    }
+
+    initialize() {
+        this.stat.testInitialize(this.id);
+    }
+
+    dispose() {
+        this.stat.testDispose(this.id);
+    }
+}
+
+@injectable()
+class StoreOther extends Store {
+    readonly id;
+
+    constructor(@inject(StatStore) private stat: StatStore) {
+        super();
+        this.id = stat.register('StoreOther');
+    }
+
+    initialize() {
+        this.stat.testInitialize(this.id);
+    }
+
+    dispose() {
+        this.stat.testDispose(this.id);
+    }
+}
+
+// 2 dependencies
+@injectable()
+class StoreWithDeps extends Store {
+    readonly id;
+
+    constructor(
+        @inject(StatStore) private stat: StatStore,
+        @inject(StoreSimple) public dep: StoreSimple
+    ) {
+        super();
+        this.id = stat.register('StoreWithDep');
+    }
+
+    initialize() {
+        this.stat.testInitialize(this.id);
+    }
+
+    dispose() {
+        this.stat.testDispose(this.id);
+    }
+}
+
+// A Store whose initialize() never resolves, to prove the hook does not await it.
+@injectable()
+class StoreAsyncNeverResolves extends Store {
+    readonly id;
+
+    constructor(@inject(StatStore) private stat: StatStore) {
+        super();
+        this.id = stat.register('StoreAsync');
+    }
+
+    initialize() {
+        this.stat.testInitialize(this.id);
+        // Never resolves: render must not block on this.
+        return new Promise<void>(() => {});
+    }
+
+    dispose() {
+        this.stat.testDispose(this.id);
+    }
+}
+
+// A Store whose initialize() resolves asynchronously, to drive the isInitialized flag.
+@injectable()
+class StoreAsyncResolves extends Store {
+    readonly id;
+
+    constructor(@inject(StatStore) private stat: StatStore) {
+        super();
+        this.id = stat.register('StoreAsyncResolves');
+    }
+
+    initialize() {
+        this.stat.testInitialize(this.id);
+        return Promise.resolve();
+    }
+
+    dispose() {
+        this.stat.testDispose(this.id);
+    }
+}
+
+// A plain @injectable that does NOT extend Store: no initialize/dispose lifecycle.
+@injectable()
+class PlainService {
+    readonly id;
+
+    constructor(@inject(StatStore) stat: StatStore) {
+        this.id = stat.register('PlainService');
+    }
+}
+
+// A plain @injectable with lifecycle-shaped methods, but NOT a Store subclass.
+@injectable()
+class PlainWithLifecycleMethods {
+    readonly id = 'PlainWithLifecycleMethods';
+
+    initialize = jest.fn();
+    dispose = jest.fn();
+}
+
+// A dependency-free @injectable: resolves from any container, even rootContainer.
+@injectable()
+class StoreNoDeps extends Store {
+    readonly id = 'StoreNoDeps';
+}
+
+// Cross-injection shadowing: needs StoreSimple, exposes it as a public field.
+@injectable()
+class StoreNeedsSimple {
+    readonly id;
+
+    constructor(
+        @inject(StatStore) stat: StatStore,
+        @inject(StoreSimple) public dep: StoreSimple
+    ) {
+        this.id = stat.register('StoreNeedsSimple');
+    }
+}
+
+// Error boundary so we can assert that an unprovided dependency throws on render.
+class Boundary extends Component<
+    PropsWithChildren<{ fallback: ReactNode; onError?: (error: Error) => void }>,
+    { hasError: boolean }
+> {
+    state = { hasError: false };
+
+    static getDerivedStateFromError() {
+        return { hasError: true };
+    }
+
+    componentDidCatch(error: Error, _info: ErrorInfo) {
+        this.props.onError?.(error);
+    }
+
+    render() {
+        return this.state.hasError ? this.props.fallback : this.props.children;
+    }
+}
+
+describe('[react-ioc] useLocalStores', () => {
+    let stat: StatStore;
+    let stores: any[];
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        stat = new StatStore();
+        stores = [StoreSimple];
+    });
+
+    // Captures the instances and initialization flag returned by the hook so tests can assert on them.
+    let captured: any[];
+    let capturedInitialized: boolean;
+
+    const Host = ({ children }: PropsWithChildren) => {
+        const [instances, isInitialized] = useLocalStores(...(stores as [any]));
+        captured = instances;
+        capturedInitialized = isInitialized;
+        return (
+            <div data-testid="host">
+                {captured.map((s, i) => (
+                    <span key={s.id} data-testid={`id-${i}`}>
+                        {s.id}
+                    </span>
+                ))}
+                {children}
+            </div>
+        );
+    };
+
+    const subject = (children?: ReactNode) =>
+        render(
+            <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                <Host>{children}</Host>
+            </Provider>
+        );
+
+    test('returns instances in argument order', () => {
+        stores = [StoreSimple, StoreOther];
+
+        subject();
+
+        expect(captured[0]).toBeInstanceOf(StoreSimple);
+        expect(captured[1]).toBeInstanceOf(StoreOther);
+    });
+
+    test('creates instances synchronously during render', () => {
+        subject();
+
+        // The id is derived from the instance and rendered immediately, not via an effect.
+        expect(screen.getByTestId('id-0')).toHaveTextContent('StoreSimple-1');
+    });
+
+    describe('with a transitive dependency provided by an ancestor Provider', () => {
+        beforeEach(() => (stores = [StoreWithDeps]));
+
+        const subject = () =>
+            render(
+                <Provider
+                    singletons={[{ provide: StatStore, useValue: stat }, StoreSimple, MinimalStore]}
+                >
+                    <Host />
+                </Provider>
+            );
+
+        test('resolves the transitive dependency from the ancestor', () => {
+            subject();
+
+            expect(captured[0].dep).toBeInstanceOf(StoreSimple);
+        });
+    });
+
+    describe('without a required transitive dependency provided above', () => {
+        beforeEach(() => (stores = [StoreWithDeps]));
+
+        const subject = () =>
+            render(
+                <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                    <Boundary fallback={<div>Error</div>}>
+                        <Host />
+                    </Boundary>
+                </Provider>
+            );
+
+        test('throws during resolution', () => {
+            const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+            subject();
+
+            expect(screen.getByText('Error')).toBeInTheDocument();
+
+            errorSpy.mockRestore();
+        });
+    });
+
+    describe('with cross-injected sibling stores in the same call', () => {
+        beforeEach(() => (stores = [StoreSimple, StoreWithDeps]));
+
+        test('shares a single local instance across siblings', () => {
+            subject();
+
+            // StoreWithDep got the same StoreSimple instance returned at index 0.
+            expect(captured[1].dep).toBe(captured[0]);
+        });
+    });
+
+    describe('with a descendant that resolves the same class via useDependencies', () => {
+        let descendantResult: any;
+
+        const Descendant = () => {
+            const [instance] = useDependencies<[StoreSimple]>(StoreSimple);
+            descendantResult = instance;
+            return null;
+        };
+
+        beforeEach(() => {
+            descendantResult = undefined;
+            stores = [StoreSimple];
+        });
+
+        test('does not leak the hook-local instance into context', () => {
+            /*
+             * StoreSimple is provided by an ancestor; the descendant must resolve THAT one,
+             * never the private hook-local instance.
+             */
+            render(
+                <Provider
+                    singletons={[{ provide: StatStore, useValue: stat }, StoreSimple, MinimalStore]}
+                >
+                    <Host>
+                        <Descendant />
+                    </Host>
+                </Provider>
+            );
+
+            expect(descendantResult).not.toBe(captured[0]);
+        });
+    });
+
+    describe('lifecycle', () => {
+        beforeEach(() => (stores = [StoreSimple, StoreOther]));
+
+        test('calls initialize once on mount for each passed store', async () => {
+            subject();
+
+            await waitFor(() => {
+                expect(stat.testInitialize).toHaveBeenCalledWith('StoreSimple-1');
+            });
+            expect(stat.testInitialize).toHaveBeenCalledWith('StoreOther-1');
+        });
+
+        test('nested transitive dependency stores provided from React context are initialized and disposed', async () => {
+            const { unmount } = subject();
+
+            await waitFor(() => {
+                expect(captured[0].minimalStore.isInitialized).toBe(true);
+            });
+
+            unmount();
+
+            expect(captured[0].minimalStore.isDisposed).toBe(true);
+        });
+
+        test('calls dispose on unmount for each passed store', async () => {
+            const { unmount } = subject();
+
+            await waitFor(() => {
+                expect(stat.testInitialize).toHaveBeenCalledWith('StoreSimple-1');
+            });
+
+            unmount();
+
+            expect(stat.testDispose).toHaveBeenCalledWith('StoreSimple-1');
+            expect(stat.testDispose).toHaveBeenCalledWith('StoreOther-1');
+        });
+    });
+
+    describe('on re-render', () => {
+        beforeEach(() => (stores = [StoreSimple]));
+
+        test('does not recreate instances or re-initialize', async () => {
+            const { rerender } = subject();
+
+            await waitFor(() => {
+                expect(stat.testInitialize).toHaveBeenCalledTimes(1);
+            });
+
+            const first = captured[0];
+
+            rerender(
+                <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                    <Host />
+                </Provider>
+            );
+
+            expect(captured[0]).toBe(first);
+            expect(stat.testInitialize).toHaveBeenCalledTimes(1);
+        });
+
+        describe('with a different class list', () => {
+            beforeEach(() => (stores = [StoreSimple]));
+
+            test('ignores the new args and returns the original tuple', () => {
+                const { rerender } = subject();
+
+                const first = captured[0];
+
+                stores = [StoreOther];
+                rerender(
+                    <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                        <Host />
+                    </Provider>
+                );
+
+                expect(captured).toHaveLength(1);
+                expect(captured[0]).toBe(first);
+            });
+        });
+    });
+
+    describe('under StrictMode', () => {
+        beforeEach(() => (stores = [StoreSimple]));
+
+        const subject = () =>
+            render(
+                <StrictMode>
+                    <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                        <Host />
+                    </Provider>
+                </StrictMode>
+            );
+
+        test('re-initializes the SAME instance after the simulated unmount', async () => {
+            subject();
+
+            const { id } = captured[0];
+
+            /*
+             * Strict effects run mount -> cleanup -> mount, so the single retained
+             * instance sees initialize, dispose, initialize. This is the documented
+             * contract: dispose must leave the store re-initializable.
+             */
+            await waitFor(() => {
+                expect(stat.testInitialize).toHaveBeenCalledTimes(2);
+            });
+            expect(stat.testInitialize).toHaveBeenNthCalledWith(1, id);
+            expect(stat.testInitialize).toHaveBeenNthCalledWith(2, id);
+            expect(stat.testDispose).toHaveBeenCalledTimes(1);
+            expect(stat.testDispose).toHaveBeenCalledWith(id);
+        });
+
+        test('runs no lifecycle for the instance discarded by the double render', () => {
+            subject();
+
+            /*
+             * StrictMode's double render constructs an extra instance and discards it
+             * without initialize/dispose — the documented reason store constructors
+             * must be side-effect-free.
+             */
+            expect(stat.counters.StoreSimple).toBe(2);
+            expect(stat.testInitialize).not.toHaveBeenCalledWith('StoreSimple-1');
+            expect(stat.testDispose).not.toHaveBeenCalledWith('StoreSimple-1');
+        });
+    });
+
+    describe('with a collaborator resolved from an ancestor Provider', () => {
+        beforeEach(() => (stores = [StoreWithDeps]));
+
+        const subject = () =>
+            render(
+                <Provider
+                    singletons={[{ provide: StatStore, useValue: stat }, StoreSimple, MinimalStore]}
+                >
+                    <Host />
+                </Provider>
+            );
+
+        test('does not initialize the from-above collaborator', async () => {
+            subject();
+
+            await waitFor(() => {
+                expect(stat.testInitialize).toHaveBeenCalledWith('StoreWithDep-1');
+            });
+            /*
+             * The Provider initialized its own StoreSimple exactly once; the hook must
+             * not initialize the collaborator it resolved from above.
+             */
+            expect(stat.testInitialize).toHaveBeenCalledWith('StoreSimple-1');
+            expect(stat.testInitialize).toHaveBeenCalledTimes(2);
+        });
+
+        test('does not dispose the from-above collaborator', async () => {
+            const { unmount } = subject();
+
+            await waitFor(() => {
+                expect(stat.testInitialize).toHaveBeenCalledWith('StoreWithDep-1');
+            });
+
+            unmount();
+
+            /*
+             * The hook disposes the directly-passed StoreWithDep; the from-above
+             * StoreSimple is disposed only once, by its Provider — never by the hook.
+             */
+            expect(stat.testDispose).toHaveBeenCalledWith('StoreWithDep-1');
+            expect(stat.testDispose).toHaveBeenCalledWith('StoreSimple-1');
+            expect(stat.testDispose).toHaveBeenCalledTimes(2);
+        });
+    });
+
+    describe('with a store whose initialize never resolves', () => {
+        beforeEach(() => (stores = [StoreAsyncNeverResolves]));
+
+        test('renders content synchronously without awaiting init', () => {
+            subject();
+
+            /*
+             * Content is visible immediately, with no loading fallback, even though
+             * initialize() has not resolved.
+             */
+            expect(screen.getByTestId('id-0')).toHaveTextContent('StoreAsync-1');
+        });
+    });
+
+    describe('the returned initialization flag', () => {
+        describe('with a store that has no initialize', () => {
+            beforeEach(() => (stores = [StoreNoDeps]));
+
+            const subject = () => render(<Host />);
+
+            test('is initialized immediately', () => {
+                subject();
+
+                expect(capturedInitialized).toBe(true);
+            });
+        });
+
+        describe('with a store whose initialize completes synchronously', () => {
+            beforeEach(() => (stores = [StoreSimple]));
+
+            test('is initialized after mount', () => {
+                subject();
+
+                expect(capturedInitialized).toBe(true);
+            });
+        });
+
+        describe('with a store whose initialize never resolves', () => {
+            beforeEach(() => (stores = [StoreAsyncNeverResolves]));
+
+            test('stays uninitialized while init is pending', () => {
+                subject();
+
+                expect(capturedInitialized).toBe(false);
+            });
+        });
+
+        describe('with a store whose initialize resolves asynchronously', () => {
+            beforeEach(() => (stores = [StoreAsyncResolves]));
+
+            test('becomes initialized once init resolves', async () => {
+                subject();
+
+                await waitFor(() => expect(capturedInitialized).toBe(true));
+            });
+        });
+    });
+
+    describe('with two independent host invocations', () => {
+        let capturedA: any[];
+        let capturedB: any[];
+
+        const HostA = () => {
+            const [instances] = useLocalStores(StoreSimple);
+            capturedA = instances;
+            return <span data-testid="a">{capturedA[0].id}</span>;
+        };
+
+        const HostB = () => {
+            const [instances] = useLocalStores(StoreSimple);
+            capturedB = instances;
+            return <span data-testid="b">{capturedB[0].id}</span>;
+        };
+
+        beforeEach(() => {
+            capturedA = [];
+            capturedB = [];
+        });
+
+        const subject = () =>
+            render(
+                <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                    <HostA />
+                    <HostB />
+                </Provider>
+            );
+
+        test('gives each invocation its own private instance', () => {
+            subject();
+
+            expect(capturedA[0]).not.toBe(capturedB[0]);
+        });
+    });
+
+    describe('with a plain @injectable that has no Store lifecycle', () => {
+        beforeEach(() => (stores = [PlainService]));
+
+        test('returns the instance', () => {
+            subject();
+
+            expect(captured[0]).toBeInstanceOf(PlainService);
+        });
+
+        test('mounts and unmounts without throwing', () => {
+            const { unmount } = subject();
+
+            expect(() => unmount()).not.toThrow();
+        });
+    });
+
+    describe('with a plain @injectable that has lifecycle-shaped methods', () => {
+        beforeEach(() => (stores = [PlainWithLifecycleMethods]));
+
+        const subject = () => render(<Host />);
+
+        test('does not call initialize, matching Provider', () => {
+            subject();
+
+            // Lifecycle is gated on Store subclasses, not duck-typed methods.
+            expect(captured[0].initialize).not.toHaveBeenCalled();
+        });
+
+        test('does not call dispose on unmount, matching Provider', () => {
+            const { unmount } = subject();
+
+            unmount();
+
+            expect(captured[0].dispose).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('without any Provider above', () => {
+        describe('with a dependency-free store', () => {
+            beforeEach(() => (stores = [StoreNoDeps]));
+
+            const subject = () => render(<Host />);
+
+            test('resolves from the root container', () => {
+                subject();
+
+                expect(captured[0]).toBeInstanceOf(StoreNoDeps);
+            });
+        });
+
+        describe('with a store needing an unprovided dependency', () => {
+            beforeEach(() => (stores = [StoreSimple]));
+
+            const subject = () =>
+                render(
+                    <Boundary fallback={<div>Error</div>}>
+                        <Host />
+                    </Boundary>
+                );
+
+            test('throws during resolution', () => {
+                const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+                subject();
+
+                expect(screen.getByText('Error')).toBeInTheDocument();
+
+                errorSpy.mockRestore();
+            });
+        });
+    });
+
+    describe('with a descendant resolving a class only bound locally by the hook', () => {
+        const Descendant = () => {
+            const [instance] = useDependencies<[StoreSimple]>(StoreSimple);
+            return <span>{instance.id}</span>;
+        };
+
+        beforeEach(() => (stores = [StoreSimple]));
+
+        const subject = () =>
+            render(
+                <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                    <Host>
+                        <Boundary fallback={<div>Descendant Error</div>}>
+                            <Descendant />
+                        </Boundary>
+                    </Host>
+                </Provider>
+            );
+
+        test('throws in the descendant because the binding never leaked', () => {
+            const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+            /*
+             * StatStore is provided so the hook itself succeeds, but StoreSimple is NOT
+             * provided by any ancestor, so the descendant's resolution must throw while
+             * the host still mounts.
+             */
+            subject();
+
+            expect(screen.getByText('Descendant Error')).toBeInTheDocument();
+            expect(screen.getByTestId('host')).toBeInTheDocument();
+
+            errorSpy.mockRestore();
+        });
+    });
+
+    describe('with the same class passed twice in one call', () => {
+        let dupCaptured: any[];
+        let boundaryError: Error | undefined;
+
+        const HostDup = () => {
+            const [instances] = useLocalStores(StoreSimple, StoreSimple);
+            dupCaptured = instances;
+            return <div>{dupCaptured.length}</div>;
+        };
+
+        beforeEach(() => {
+            dupCaptured = [];
+            boundaryError = undefined;
+        });
+
+        const subject = () =>
+            render(
+                <Provider singletons={[{ provide: StatStore, useValue: stat }, MinimalStore]}>
+                    <Boundary
+                        fallback={<div>Error</div>}
+                        onError={error => (boundaryError = error)}
+                    >
+                        <HostDup />
+                    </Boundary>
+                </Provider>
+            );
+
+        test('throws during render with a message naming the duplicate', () => {
+            const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+            subject();
+
+            expect(screen.getByText('Error')).toBeInTheDocument();
+            expect(boundaryError?.message).toBe(
+                'useLocalStores: token listed more than once: StoreSimple. Remove the duplicate entries.'
+            );
+
+            errorSpy.mockRestore();
+        });
+
+        describe('in production mode', () => {
+            let nodeEnv: string | undefined;
+
+            beforeEach(() => {
+                nodeEnv = process.env.NODE_ENV;
+                process.env.NODE_ENV = 'production';
+            });
+
+            afterEach(() => {
+                process.env.NODE_ENV = nodeEnv;
+            });
+
+            test('warns and collapses duplicates onto the same singleton', () => {
+                const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+                subject();
+
+                expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('StoreSimple'));
+                expect(dupCaptured).toHaveLength(2);
+                expect(dupCaptured[0]).toBe(dupCaptured[1]);
+
+                warnSpy.mockRestore();
+            });
+        });
+    });
+
+    describe('with the same class both passed to the hook and provided above', () => {
+        beforeEach(() => (stores = [StoreSimple]));
+
+        const subject = () =>
+            render(
+                <Provider
+                    singletons={[{ provide: StatStore, useValue: stat }, StoreSimple, MinimalStore]}
+                >
+                    <Host>
+                        <Descendant />
+                    </Host>
+                </Provider>
+            );
+
+        let descendantResult: any;
+
+        const Descendant = () => {
+            const [instance] = useDependencies<[StoreSimple]>(StoreSimple);
+            descendantResult = instance;
+            return null;
+        };
+
+        beforeEach(() => (descendantResult = undefined));
+
+        test('shadows the ancestor with a distinct registered id', () => {
+            subject();
+
+            // Two separate StoreSimple instances were created, so their ids differ.
+            expect(captured[0].id).not.toBe(descendantResult.id);
+        });
+    });
+
+    describe('with a cross-injected sibling also provided by an ancestor', () => {
+        let ancestorSimple: any;
+
+        const AncestorResolver = () => {
+            const [instance] = useDependencies<[StoreSimple]>(StoreSimple);
+            ancestorSimple = instance;
+            return null;
+        };
+
+        beforeEach(() => {
+            ancestorSimple = undefined;
+            stores = [StoreNeedsSimple, StoreSimple];
+        });
+
+        const subject = () =>
+            render(
+                <Provider
+                    singletons={[{ provide: StatStore, useValue: stat }, StoreSimple, MinimalStore]}
+                >
+                    <Host />
+                    <AncestorResolver />
+                </Provider>
+            );
+
+        test('injects the local StoreSimple returned by the same call', () => {
+            subject();
+
+            // StoreNeedsSimple got the LOCAL StoreSimple, the one returned at index 1.
+            expect(captured[0].dep).toBe(captured[1]);
+        });
+
+        test('shadows the ancestor StoreSimple rather than reusing it', () => {
+            subject();
+
+            // The ancestor's StoreSimple is a different instance with a distinct id.
+            expect(captured[1].id).not.toBe(ancestorSimple.id);
+        });
+    });
+});