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

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);
+    });
+});

package/src/ssr-polyfills.test.ts

@@ -0,0 +1,65 @@
+import croct, {Configuration} from '@croct/plug';
+import {croct as croctPolyfill, isSsr} from './ssr-polyfills';
+import spyOn = jest.spyOn;
+
+describe('Croct polyfill (CSR)', () => {
+    beforeAll(() => {
+        jest.clearAllMocks();
+    });
+
+    const config: Configuration = {appId: '00000000-0000-0000-0000-000000000000'};
+
+    it('should delay unplugging to avoid reconnections', async () => {
+        jest.useFakeTimers();
+
+        const unplug = spyOn(croct, 'unplug');
+
+        const plug = spyOn(croct, 'plug');
+
+        croctPolyfill.plug(config);
+
+        expect(plug).toHaveBeenCalledTimes(1);
+
+        // First attempt: cancelling
+
+        const firstAttempt = croctPolyfill.unplug();
+
+        expect(unplug).not.toHaveBeenCalled();
+
+        croctPolyfill.plug(config);
+
+        jest.runOnlyPendingTimers();
+
+        await expect(firstAttempt).rejects.toThrow('Unplug cancelled.');
+
+        expect(unplug).not.toHaveBeenCalled();
+
+        // Second attempt: failing
+
+        unplug.mockRejectedValueOnce(new Error('Unplug failed.'));
+
+        const secondAttempt = croct.unplug();
+
+        jest.runOnlyPendingTimers();
+
+        await expect(secondAttempt).rejects.toThrow('Unplug failed.');
+
+        // Third attempt: succeeding
+
+        unplug.mockResolvedValueOnce();
+
+        const thirdAttempt = croct.unplug();
+
+        jest.runOnlyPendingTimers();
+
+        await expect(thirdAttempt).resolves.toBeUndefined();
+
+        expect(unplug).toHaveBeenCalledTimes(2);
+    });
+});
+
+describe('isSsr', () => {
+    it('should always return false', () => {
+        expect(isSsr()).toBe(false);
+    });
+});

package/src/ssr-polyfills.ts

@@ -0,0 +1,68 @@
+import csrPlug, {Plug} from '@croct/plug';
+
+export function isSsr(): boolean {
+    return typeof window === 'undefined'
+        || typeof window.document === 'undefined'
+        || typeof window.document.createElement === 'undefined';
+}
+
+export const croct: Plug = !isSsr()
+    ? (function factory(): Plug {
+        let timeoutId: ReturnType<typeof setTimeout>|null = null;
+        let resolveCallback: () => void;
+        let rejectCallback: (reason: any) => void;
+
+        return new Proxy(csrPlug, {
+            get: function getProperty(target, property: keyof Plug): any {
+                switch (property) {
+                    case 'plug':
+                        if (timeoutId !== null) {
+                            clearTimeout(timeoutId);
+                            timeoutId = null;
+                            rejectCallback?.(new Error('Unplug cancelled.'));
+                        }
+
+                        break;
+
+                    case 'unplug':
+                        return () => {
+                            // Delay unplugging to avoid reconnections between remounts (e.g. strict mode).
+                            // It can be problematic when aiming to replug the SDK with a different configuration.
+                            // However, since it is an unusual use case and there is a log message to warn about
+                            // the plugin being already plugged, the trade-off is worth it.
+                            timeoutId = setTimeout(() => target.unplug().then(resolveCallback, rejectCallback), 100);
+
+                            return new Promise<void>((resolve, reject) => {
+                                resolveCallback = resolve;
+                                rejectCallback = reject;
+                            });
+                        };
+                }
+
+                return target[property];
+            },
+        });
+    }())
+    : new Proxy(csrPlug, {
+        get: function getProperty(_, property: keyof Plug): any {
+            switch (property) {
+                case 'initialized':
+                    return false;
+
+                case 'plug':
+                    return () => {
+                        // no-op
+                    };
+
+                case 'unplug':
+                    return () => Promise.resolve();
+
+                default:
+                    throw new Error(
+                        `Property croct.${String(property)} is not supported on server-side (SSR). `
+                        + 'Consider refactoring  the logic as a side-effect (useEffect) or a client-side callback '
+                        + '(onClick, onChange, etc).',
+                    );
+            }
+        },
+    });

package/ssr-polyfills.js.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-polyfills.js","sourceRoot":"","sources":["../src/ssr-polyfills.ts"],"names":[],"mappings":";;;;;;AAAA,uDAA0C;AAE1C,SAAgB,KAAK;IACjB,OAAO,OAAO,MAAM,KAAK,WAAW;WAC7B,OAAO,MAAM,CAAC,QAAQ,KAAK,WAAW;WACtC,OAAO,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK,WAAW,CAAC;AAChE,CAAC;AAJD,sBAIC;AAEY,QAAA,KAAK,GAAS,CAAC,KAAK,EAAE;IAC/B,CAAC,CAAC,CAAC,SAAS,OAAO;QACf,IAAI,SAAS,GAAuC,IAAI,CAAC;QACzD,IAAI,eAA2B,CAAC;QAChC,IAAI,cAAqC,CAAC;QAE1C,OAAO,IAAI,KAAK,CAAC,cAAO,EAAE;YACtB,GAAG,EAAE,SAAS,WAAW,CAAC,MAAM,EAAE,QAAoB;gBAClD,QAAQ,QAAQ,EAAE;oBACd,KAAK,MAAM;wBACP,IAAI,SAAS,KAAK,IAAI,EAAE;4BACpB,YAAY,CAAC,SAAS,CAAC,CAAC;4BACxB,SAAS,GAAG,IAAI,CAAC;4BACjB,cAAc,aAAd,cAAc,uBAAd,cAAc,CAAG,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;yBACpD;wBAED,MAAM;oBAEV,KAAK,QAAQ;wBACT,OAAO,GAAG,EAAE;4BACR,+EAA+E;4BAC/E,sFAAsF;4BACtF,oFAAoF;4BACpF,+DAA+D;4BAC/D,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,CAAC;4BAEzF,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gCACzC,eAAe,GAAG,OAAO,CAAC;gCAC1B,cAAc,GAAG,MAAM,CAAC;4BAC5B,CAAC,CAAC,CAAC;wBACP,CAAC,CAAC;iBACT;gBAED,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,CAAC;SACJ,CAAC,CAAC;IACP,CAAC,EAAE,CAAC;IACJ,CAAC,CAAC,IAAI,KAAK,CAAC,cAAO,EAAE;QACjB,GAAG,EAAE,SAAS,WAAW,CAAC,CAAC,EAAE,QAAoB;YAC7C,QAAQ,QAAQ,EAAE;gBACd,KAAK,aAAa;oBACd,OAAO,KAAK,CAAC;gBAEjB,KAAK,MAAM;oBACP,OAAO,GAAG,EAAE;wBACR,QAAQ;oBACZ,CAAC,CAAC;gBAEN,KAAK,QAAQ;oBACT,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBAEnC;oBACI,MAAM,IAAI,KAAK,CACX,kBAAkB,MAAM,CAAC,QAAQ,CAAC,0CAA0C;0BAC1E,yFAAyF;0BACzF,2BAA2B,CAChC,CAAC;aACT;QACL,CAAC;KACJ,CAAC,CAAC"}
+{"version":3,"file":"ssr-polyfills.js","sourceRoot":"","sources":["src/ssr-polyfills.ts"],"names":[],"mappings":";;;;;;AAAA,uDAA0C;AAE1C,SAAgB,KAAK;IACjB,OAAO,OAAO,MAAM,KAAK,WAAW;WAC7B,OAAO,MAAM,CAAC,QAAQ,KAAK,WAAW;WACtC,OAAO,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK,WAAW,CAAC;AAChE,CAAC;AAJD,sBAIC;AAEY,QAAA,KAAK,GAAS,CAAC,KAAK,EAAE;IAC/B,CAAC,CAAC,CAAC,SAAS,OAAO;QACf,IAAI,SAAS,GAAuC,IAAI,CAAC;QACzD,IAAI,eAA2B,CAAC;QAChC,IAAI,cAAqC,CAAC;QAE1C,OAAO,IAAI,KAAK,CAAC,cAAO,EAAE;YACtB,GAAG,EAAE,SAAS,WAAW,CAAC,MAAM,EAAE,QAAoB;gBAClD,QAAQ,QAAQ,EAAE;oBACd,KAAK,MAAM;wBACP,IAAI,SAAS,KAAK,IAAI,EAAE;4BACpB,YAAY,CAAC,SAAS,CAAC,CAAC;4BACxB,SAAS,GAAG,IAAI,CAAC;4BACjB,cAAc,aAAd,cAAc,uBAAd,cAAc,CAAG,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;yBACpD;wBAED,MAAM;oBAEV,KAAK,QAAQ;wBACT,OAAO,GAAG,EAAE;4BACR,+EAA+E;4BAC/E,sFAAsF;4BACtF,oFAAoF;4BACpF,+DAA+D;4BAC/D,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,CAAC;4BAEzF,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gCACzC,eAAe,GAAG,OAAO,CAAC;gCAC1B,cAAc,GAAG,MAAM,CAAC;4BAC5B,CAAC,CAAC,CAAC;wBACP,CAAC,CAAC;iBACT;gBAED,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,CAAC;SACJ,CAAC,CAAC;IACP,CAAC,EAAE,CAAC;IACJ,CAAC,CAAC,IAAI,KAAK,CAAC,cAAO,EAAE;QACjB,GAAG,EAAE,SAAS,WAAW,CAAC,CAAC,EAAE,QAAoB;YAC7C,QAAQ,QAAQ,EAAE;gBACd,KAAK,aAAa;oBACd,OAAO,KAAK,CAAC;gBAEjB,KAAK,MAAM;oBACP,OAAO,GAAG,EAAE;wBACR,QAAQ;oBACZ,CAAC,CAAC;gBAEN,KAAK,QAAQ;oBACT,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBAEnC;oBACI,MAAM,IAAI,KAAK,CACX,kBAAkB,MAAM,CAAC,QAAQ,CAAC,0CAA0C;0BAC1E,yFAAyF;0BACzF,2BAA2B,CAChC,CAAC;aACT;QACL,CAAC;KACJ,CAAC,CAAC"}