@croct/plug-react 0.4.2 → 0.5.0-next.2

package/src/hooks/useContent.ts

@@ -0,0 +1,69 @@
+import {SlotContent, VersionedSlotId, VersionedSlotMap} from '@croct/plug/slot';
+import {JsonObject} from '@croct/plug/sdk/json';
+import {FetchOptions} from '@croct/plug/plug';
+import {useLoader} from './useLoader';
+import {useCroct} from './useCroct';
+import {isSsr} from '../ssr-polyfills';
+
+export type UseContentOptions<I, F> = FetchOptions & {
+    fallback?: F,
+    initial?: I,
+    cacheKey?: string,
+    expiration?: number,
+};
+
+function useCsrContent<I, F>(
+    id: VersionedSlotId,
+    options: UseContentOptions<I, F> = {},
+): SlotContent<VersionedSlotId> | I | F {
+    const {fallback, initial, cacheKey, expiration, ...fetchOptions} = options;
+    const croct = useCroct();
+
+    return useLoader({
+        cacheKey: `useContent:${cacheKey ?? ''}:${id}`,
+        loader: () => croct.fetch(id, fetchOptions).then(({content}) => content),
+        initial: initial,
+        fallback: fallback,
+        expiration: expiration,
+    });
+}
+
+function useSsrContent<I, F>(
+    _: VersionedSlotId,
+    {initial}: UseContentOptions<I, F> = {},
+): SlotContent<VersionedSlotId> | I | F {
+    if (initial === undefined) {
+        throw new Error('The initial value is required for server-side rendering (SSR).');
+    }
+
+    return initial;
+}
+
+type UseContentHook = {
+    <P extends JsonObject, I = P, F = P>(
+        id: keyof VersionedSlotMap extends never ? string : never,
+        options?: UseContentOptions<I, F>
+    ): P | I | F,
+
+    <S extends VersionedSlotId>(
+        id: S,
+        options?: UseContentOptions<never, never>
+    ): SlotContent<S>,
+
+    <I, S extends VersionedSlotId>(
+        id: S,
+        options?: UseContentOptions<I, never>
+    ): SlotContent<S> | I,
+
+    <F, S extends VersionedSlotId>(
+        id: S,
+        options?: UseContentOptions<never, F>
+    ): SlotContent<S> | F,
+
+    <I, F, S extends VersionedSlotId>(
+        id: S,
+        options?: UseContentOptions<I, F>
+    ): SlotContent<S> | I | F,
+};
+
+export const useContent: UseContentHook = isSsr() ? useSsrContent : useCsrContent;

package/src/hooks/useCroct.ts

@@ -0,0 +1,13 @@
+import {Plug} from '@croct/plug';
+import {useContext} from 'react';
+import {CroctContext} from '../CroctProvider';
+
+export function useCroct(): Plug {
+    const context = useContext(CroctContext);
+
+    if (context === null) {
+        throw new Error('useCroct() can only be used in the context of a <CroctProvider> component.');
+    }
+
+    return context.plug;
+}

package/src/hooks/useEvaluation.ssr.test.ts

@@ -0,0 +1,23 @@
+import {renderHook} from '@testing-library/react';
+import {useEvaluation} from './useEvaluation';
+
+jest.mock(
+    '../ssr-polyfills',
+    () => ({
+        __esModule: true,
+        isSsr: (): boolean => true,
+    }),
+);
+
+describe('useEvaluation (SSR)', () => {
+    it('should render the initial value on the server-side', () => {
+        const {result} = renderHook(() => useEvaluation('location', {initial: 'foo'}));
+
+        expect(result.current).toBe('foo');
+    });
+
+    it('should require an initial value for server-side rending', () => {
+        expect(() => useEvaluation('location'))
+            .toThrow(new Error('The initial value is required for server-side rendering (SSR).'));
+    });
+});

package/src/hooks/useEvaluation.test.ts

@@ -0,0 +1,92 @@
+import {renderHook} from '@testing-library/react';
+import {EvaluationOptions} from '@croct/sdk/facade/evaluatorFacade';
+import {Plug} from '@croct/plug';
+import {useEvaluation} from './useEvaluation';
+import {useCroct} from './useCroct';
+import {useLoader} from './useLoader';
+
+jest.mock(
+    './useCroct',
+    () => ({
+        useCroct: jest.fn(),
+    }),
+);
+
+jest.mock(
+    './useLoader',
+    () => ({
+        useLoader: jest.fn(),
+    }),
+);
+
+describe('useEvaluation', () => {
+    beforeEach(() => {
+        jest.resetModules();
+        jest.resetAllMocks();
+    });
+
+    it('should evaluate a query', () => {
+        const evaluationOptions: EvaluationOptions = {
+            timeout: 100,
+            attributes: {
+                foo: 'bar',
+            },
+        };
+
+        const evaluate: Plug['evaluate'] = jest.fn();
+
+        jest.mocked(useCroct).mockReturnValue({evaluate: evaluate} as Plug);
+        jest.mocked(useLoader).mockReturnValue('foo');
+
+        const query = 'location';
+
+        const {result} = renderHook(
+            () => useEvaluation(query, {
+                ...evaluationOptions,
+                cacheKey: 'unique',
+                fallback: 'error',
+                expiration: 50,
+            }),
+        );
+
+        expect(useCroct).toHaveBeenCalled();
+        expect(useLoader).toHaveBeenCalledWith({
+            cacheKey: 'useEvaluation:unique:location:{"foo":"bar"}',
+            fallback: 'error',
+            expiration: 50,
+            loader: expect.any(Function),
+        });
+
+        jest.mocked(useLoader)
+            .mock
+            .calls[0][0]
+            .loader();
+
+        expect(evaluate).toHaveBeenCalledWith(query, evaluationOptions);
+
+        expect(result.current).toBe('foo');
+    });
+
+    it('should remove undefined evaluation options', () => {
+        const evaluationOptions: EvaluationOptions = {
+            timeout: undefined,
+            attributes: undefined,
+        };
+
+        const evaluate: Plug['evaluate'] = jest.fn();
+
+        jest.mocked(useCroct).mockReturnValue({evaluate: evaluate} as Plug);
+        jest.mocked(useLoader).mockReturnValue('foo');
+
+        const query = 'location';
+
+        renderHook(() => useEvaluation(query, evaluationOptions));
+
+        jest.mocked(useLoader)
+            .mock
+            .calls[0][0]
+            .loader();
+
+        expect(evaluate).toHaveBeenCalledWith(query, {});
+    });
+});

package/src/hooks/useEvaluation.ts

@@ -0,0 +1,58 @@
+import {JsonValue} from '@croct/plug/sdk/json';
+import {EvaluationOptions} from '@croct/sdk/facade/evaluatorFacade';
+import {useLoader} from './useLoader';
+import {useCroct} from './useCroct';
+import {isSsr} from '../ssr-polyfills';
+
+function cleanEvaluationOptions(options: EvaluationOptions): EvaluationOptions {
+    const result: EvaluationOptions = {};
+
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+
+    return result;
+}
+
+export type UseEvaluationOptions<I, F> = EvaluationOptions & {
+    initial?: I,
+    fallback?: F,
+    cacheKey?: string,
+    expiration?: number,
+};
+
+type UseEvaluationHook = <T extends JsonValue, I = T, F = T>(
+    query: string,
+    options?: UseEvaluationOptions<I, F>,
+) => T | I | F;
+
+function useCsrEvaluation<T = JsonValue, I = T, F = T>(
+    query: string,
+    options: UseEvaluationOptions<I, F> = {},
+): T | I | F {
+    const {cacheKey, fallback, initial, expiration, ...evaluationOptions} = options;
+    const croct = useCroct();
+
+    return useLoader<T | I | F>({
+        cacheKey: `useEvaluation:${cacheKey ?? ''}:${query}:${JSON.stringify(options.attributes ?? '')}`,
+        loader: () => croct.evaluate<T & JsonValue>(query, cleanEvaluationOptions(evaluationOptions)),
+        initial: initial,
+        fallback: fallback,
+        expiration: expiration,
+    });
+}
+
+function useSsrEvaluation<T = JsonValue, I = T, F = T>(
+    _: string,
+    {initial}: UseEvaluationOptions<I, F> = {},
+): T | I | F {
+    if (initial === undefined) {
+        throw new Error('The initial value is required for server-side rendering (SSR).');
+    }
+
+    return initial;
+}
+
+export const useEvaluation: UseEvaluationHook = isSsr() ? useSsrEvaluation : useCsrEvaluation;

package/src/hooks/useLoader.test.ts

@@ -0,0 +1,320 @@
+import {act, renderHook, waitFor} from '@testing-library/react';
+import {useLoader} from './useLoader';
+
+describe('useLoader', () => {
+    const cacheKey = {
+        index: 0,
+        next: function next(): string {
+            this.index++;
+
+            return this.current();
+        },
+        current: function current(): string {
+            return `key-${this.index}`;
+        },
+    };
+
+    beforeEach(() => {
+        cacheKey.next();
+    });
+
+    afterEach(() => {
+        jest.clearAllTimers();
+        jest.resetAllMocks();
+    });
+
+    // Needed to use fake timers and promises:
+    // https://github.com/testing-library/react-testing-library/issues/244#issuecomment-449461804
+    function flushPromises(): Promise<void> {
+        return Promise.resolve();
+    }
+
+    it('should return the load the value and cache on success', async () => {
+        const loader = jest.fn().mockResolvedValue('foo');
+
+        const {result, rerender} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                loader: loader,
+            }),
+        );
+
+        rerender();
+
+        await waitFor(() => expect(result.current).toBe('foo'));
+
+        expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it('should load the value and cache on error', async () => {
+        const error = new Error('fail');
+        const loader = jest.fn().mockRejectedValue(error);
+
+        const {result, rerender} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                fallback: error,
+                loader: loader,
+            }),
+        );
+
+        rerender();
+
+        await waitFor(() => expect(result.current).toBe(error));
+
+        expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it('should reload the value on error', async () => {
+        const content = {foo: 'qux'};
+
+        const loader = jest.fn()
+            .mockImplementationOnce(() => {
+                throw new Error('fail');
+            })
+            .mockImplementationOnce(() => Promise.resolve(content));
+
+        const {result, rerender} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                initial: {},
+                loader: loader,
+            }),
+        );
+
+        await act(flushPromises);
+
+        rerender();
+
+        await waitFor(() => expect(result.current).toBe(content));
+
+        expect(loader).toHaveBeenCalledTimes(2);
+    });
+
+    it('should return the initial state on the initial render', async () => {
+        const loader = jest.fn(() => Promise.resolve('loaded'));
+
+        const {result} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                initial: 'loading',
+                loader: loader,
+            }),
+        );
+
+        expect(result.current).toBe('loading');
+
+        await waitFor(() => expect(result.current).toBe('loaded'));
+    });
+
+    it('should update the initial state with the fallback state on error', async () => {
+        const loader = jest.fn().mockRejectedValue(new Error('fail'));
+
+        const {result} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                initial: 'loading',
+                fallback: 'error',
+                loader: loader,
+            }),
+        );
+
+        expect(result.current).toBe('loading');
+
+        await waitFor(() => expect(result.current).toBe('error'));
+    });
+
+    it('should return the fallback state on error', async () => {
+        const loader = jest.fn().mockRejectedValue(new Error('fail'));
+
+        const {result} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                fallback: 'foo',
+                loader: loader,
+            }),
+        );
+
+        await waitFor(() => expect(result.current).toBe('foo'));
+
+        expect(loader).toHaveBeenCalled();
+    });
+
+    it('should extend the cache expiration on every render', async () => {
+        jest.useFakeTimers();
+
+        const loader = jest.fn().mockResolvedValue('foo');
+
+        const {rerender, unmount} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                loader: loader,
+                expiration: 15,
+            }),
+        );
+
+        await act(flushPromises);
+
+        jest.advanceTimersByTime(14);
+
+        rerender();
+
+        jest.advanceTimersByTime(14);
+
+        rerender();
+
+        expect(loader).toHaveBeenCalledTimes(1);
+
+        jest.advanceTimersByTime(15);
+
+        unmount();
+
+        renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                loader: loader,
+                expiration: 15,
+            }),
+        );
+
+        await act(flushPromises);
+
+        expect(loader).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not expire the cache when the expiration is negative', async () => {
+        jest.useFakeTimers();
+
+        const loader = jest.fn(
+            () => new Promise(resolve => {
+                setTimeout(() => resolve('foo'), 10);
+            }),
+        );
+
+        const {rerender} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                loader: loader,
+                expiration: -1,
+            }),
+        );
+
+        jest.advanceTimersByTime(10);
+
+        await act(flushPromises);
+
+        // First rerender
+        rerender();
+
+        // Second rerender
+        rerender();
+
+        expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it.each<[number, number|undefined]>(
+        [
+            // [Expected elapsed time, Expiration]
+            [60_000, undefined],
+            [15_000, 15_000],
+        ],
+    )('should cache the values for %d milliseconds', async (step, expiration) => {
+        jest.useFakeTimers();
+
+        const delay = 10;
+        const loader = jest.fn(
+            () => new Promise(resolve => {
+                setTimeout(() => resolve('foo'), delay);
+            }),
+        );
+
+        const {result: firstTime} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                expiration: expiration,
+                loader: loader,
+            }),
+        );
+
+        jest.advanceTimersByTime(delay);
+
+        await act(flushPromises);
+
+        await waitFor(() => expect(firstTime.current).toBe('foo'));
+
+        const {result: secondTime} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                expiration: expiration,
+                loader: loader,
+            }),
+        );
+
+        expect(secondTime.current).toBe('foo');
+
+        expect(loader).toHaveBeenCalledTimes(1);
+
+        jest.advanceTimersByTime(step);
+
+        const {result: thirdTime} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                expiration: expiration,
+                loader: loader,
+            }),
+        );
+
+        jest.advanceTimersByTime(delay);
+
+        await act(flushPromises);
+
+        await waitFor(() => expect(thirdTime.current).toBe('foo'));
+
+        expect(loader).toHaveBeenCalledTimes(2);
+    });
+
+    it('should dispose the cache on unmount', async () => {
+        jest.useFakeTimers();
+
+        const delay = 10;
+        const loader = jest.fn(
+            () => new Promise(resolve => {
+                setTimeout(() => resolve('foo'), delay);
+            }),
+        );
+
+        const {unmount} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                expiration: 5,
+                loader: loader,
+            }),
+        );
+
+        jest.advanceTimersByTime(delay);
+
+        await act(flushPromises);
+
+        unmount();
+
+        jest.advanceTimersByTime(5);
+
+        await act(flushPromises);
+
+        const {result: secondTime} = renderHook(
+            () => useLoader({
+                cacheKey: cacheKey.current(),
+                expiration: 5,
+                loader: loader,
+            }),
+        );
+
+        jest.advanceTimersByTime(delay);
+
+        await act(flushPromises);
+
+        expect(loader).toHaveBeenCalledTimes(2);
+
+        await waitFor(() => expect(secondTime.current).toBe('foo'));
+    });
+});

package/src/hooks/useLoader.ts

@@ -0,0 +1,50 @@
+import {useEffect, useRef, useState} from 'react';
+import {Cache, EntryOptions} from './Cache';
+
+const cache = new Cache(60 * 1000);
+
+export type CacheOptions<R> = EntryOptions<R> & {
+    initial?: R,
+};
+
+export function useLoader<R>({initial, ...options}: CacheOptions<R>): R {
+    const loadedValue: R|undefined = cache.get<R>(options.cacheKey)?.result;
+    const [value, setValue] = useState(loadedValue !== undefined ? loadedValue : initial);
+    const mountedRef = useRef(true);
+    const optionsRef = useRef(initial !== undefined ? options : undefined);
+
+    useEffect(
+        () => {
+            if (optionsRef.current !== undefined) {
+                try {
+                    setValue(cache.load(optionsRef.current));
+                } catch (result: unknown) {
+                    if (result instanceof Promise) {
+                        result.then((resolvedValue: R) => {
+                            if (mountedRef.current) {
+                                setValue(resolvedValue);
+                            }
+                        });
+
+                        return;
+                    }
+
+                    setValue(undefined);
+
+                    return;
+                }
+            }
+
+            return () => {
+                mountedRef.current = false;
+            };
+        },
+        [],
+    );
+
+    if (value === undefined) {
+        return cache.load(options);
+    }
+
+    return value;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from '@croct/plug/sdk/json';
+export * from '@croct/plug/slot';
+export * from './CroctProvider';
+export * from './hooks';
+export * from './components';

package/src/react-app-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="react-scripts" />

package/src/ssr-polyfills.ssr.test.ts

@@ -0,0 +1,46 @@
+/*
+ * @jest-environment node
+ */
+import croct from '@croct/plug';
+import {croct as croctPolyfill, isSsr} from './ssr-polyfills';
+
+jest.mock(
+    '@croct/plug',
+    () => ({
+        plug: jest.fn(),
+        unplug: jest.fn(),
+    }),
+);
+
+describe('Croct polyfill (SSR)', () => {
+    it('should not plug', () => {
+        croctPolyfill.plug({appId: '00000000-0000-0000-0000-000000000000'});
+
+        expect(croct.plug).not.toHaveBeenCalled();
+    });
+
+    it('should not unplug', async () => {
+        await expect(croctPolyfill.unplug()).resolves.toBeUndefined();
+
+        expect(croct.unplug).not.toHaveBeenCalled();
+    });
+
+    it('should not initialize', () => {
+        expect(croctPolyfill.initialized).toBe(false);
+
+        croctPolyfill.plug({appId: '00000000-0000-0000-0000-000000000000'});
+
+        expect(croctPolyfill.initialized).toBe(false);
+    });
+
+    it('should not allow accessing properties other than plug or unplug', () => {
+        expect(() => croctPolyfill.user)
+            .toThrow('Property croct.user is not supported on server-side (SSR).');
+    });
+});
+
+describe('isSsr', () => {
+    it('should always return true', () => {
+        expect(isSsr()).toBe(true);
+    });
+});