Add "withContract" utility

Author: paol-imi

src/index.ts

@@ -11,6 +11,7 @@ export {
 export {
   useSource as useSourceWithContract,
   usePureSource as usePureSourceWithContract,
+  withContract,
 } from './withContract/useSource';
 
 export {
@@ -31,6 +32,7 @@ export {
 export {
   useSource as useSourceWithContractClient,
   usePureSource as usePureSourceWithContractClient,
+  withContract as withContractClient,
 } from './withContract/useSource/client';
 
 export {
@@ -51,11 +53,13 @@ export {
 export {
   useSource as useSourceWithContractServer,
   usePureSource as usePureSourceWithContractServer,
+  withContract as withContractServer,
 } from './withContract/useSource/server';
 
 export {
   useSource as useAtomicSourceWithContractServer,
   usePureSource as useAtomicPureSourceWithContractServer,
 } from './withContract/useAtomicSource/server';
 
+export { useFactory, usePureFactory } from './useFactory';
 export { shallowEqual } from './shallowEqual';

src/withContract/useSource/client.ts

@@ -234,3 +234,48 @@ export function usePureSource<Source>(
   // This overload returns [useSnapshot, source].
   return [useSourceSnapshot, source] as const;
 }
+
+/**
+ * Allows to use a global source safely inside any component.
+ *
+ * @param source - the source
+ * @param contract - function to register a callback that is called whenever the source changes
+ * @returns an hook to derive snapshots and the source
+ */
+export function withContract<Source>(
+  source: Source,
+  contract: (source: Source, onChange: () => void) => void
+) {
+  const slice = new Slice();
+  contract(source, slice.update);
+
+  /**
+   * Hook that allows to consume a snapshot of the source.
+   *
+   * @param getSnapshot - function that returns a snapshot of the source
+   * @param getSnapshotDeps - dependency list that defines the "getSnapshot" lifecycle
+   * @returns the snapshot
+   */
+  function useSourceSnapshot<Snapshot>(
+    getSnapshot: (source: Source, currentSnapshot: Snapshot | null) => Snapshot,
+    getSnapshotDeps: DependencyList = []
+  ) {
+    const getSourceSnapshot = useCallback(
+      (currentSnapshot: Snapshot | null) =>
+        getSnapshot(source, currentSnapshot),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      getSnapshotDeps
+    );
+
+    const snapshot = useSnapshot(getSourceSnapshot, slice);
+
+    if (__DEV__) {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      useDebugValue(snapshot);
+    }
+
+    return snapshot;
+  }
+
+  return [useSourceSnapshot, source, slice] as const;
+}

src/withContract/useSource/index.ts

@@ -2,6 +2,6 @@ import * as client from './client';
 import * as server from './server';
 import { isServer } from '../../isServer';
 
-export const [useSource, usePureSource] = !isServer
-  ? [client.useSource, client.usePureSource]
-  : [server.useSource, server.usePureSource];
+export const [useSource, usePureSource, withContract] = !isServer
+  ? [client.useSource, client.usePureSource, client.withContract]
+  : [server.useSource, server.usePureSource, server.withContract];

src/withContract/useSource/server.ts

@@ -20,3 +20,12 @@ export const usePureSource: typeof client.usePureSource = (
     source,
   ] as const;
 };
+
+export const withContract: typeof client.withContract = (source: any) => {
+  return [
+    (getSnapshot: (source: any, snapshot: null) => any) =>
+      getSnapshot(source, null),
+    source,
+    null as any,
+  ] as const;
+};

test/exports.test.ts

@@ -1,6 +1,8 @@
 import * as module from '../src';
 
 it('correctly define the exports', () => {
+  expect(module.useFactory).toBeDefined();
+  expect(module.usePureFactory).toBeDefined();
   expect(module.shallowEqual).toBeDefined();
 
   expect(module.usePureSourceWithContract).toBeDefined();
@@ -15,6 +17,9 @@ it('correctly define the exports', () => {
   expect(module.useSourceWithSubscription).toBeDefined();
   expect(module.useSourceWithSubscriptionClient).toBeDefined();
   expect(module.useSourceWithSubscriptionServer).toBeDefined();
+  expect(module.withContract).toBeDefined();
+  expect(module.withContractClient).toBeDefined();
+  expect(module.withContractServer).toBeDefined();
 
   expect(module.useAtomicPureSourceWithContract).toBeDefined();
   expect(module.useAtomicPureSourceWithContractClient).toBeDefined();

test/utils/values.ts

@@ -45,7 +45,7 @@ export function getValues() {
   return formattedValues;
 }
 
-beforeEach(() => {
+afterEach(() => {
   // Cleans up the history.
   values = [];
 });

test/withContracts/useSource.spec.tsx

@@ -1,8 +1,13 @@
 import { type DependencyList, useEffect } from 'react';
-import { useSource, usePureSource } from '../../src/withContract/useSource';
+import {
+  useSource,
+  usePureSource,
+  withContract,
+} from '../../src/withContract/useSource';
 import {
   useSource as useSourceServer,
   usePureSource as usePureSourceServer,
+  withContract as withContractServer,
 } from '../../src/withContract/useSource/server';
 import { Source } from '../utils/source';
 import { act, create } from '../utils/renderer';
@@ -645,3 +650,178 @@ describe('how usePureSource works', () => {
     ]);
   });
 });
+
+describe('how withContract works', () => {
+  const [useSnapshot, source] = withContract(
+    // Generate the source.
+    new Source(0),
+    // Subscribe to changes.
+    (source, onChange) => source.addChangeListener(onChange)
+  );
+
+  // App component.
+  function App({
+    getSnapshotDeps = undefined as undefined | DependencyList,
+    getSnapshotOffset = 0,
+  }) {
+    // Consume the snapshot.
+    const value = useSnapshot(
+      (source) => source.getValue() + getSnapshotOffset,
+      getSnapshotDeps
+    );
+
+    // Yield render value.
+    yieldValue(`render`, `snapshot(${value})`);
+
+    useEffect(() => {
+      // Value 2 triggers a new update with value 3.
+      if (value === 2) {
+        source.setValue(3);
+      }
+
+      // Yield effect values.
+      yieldValue(`effect`, `source(${source.getValue()}) snapshot(${value})`);
+    });
+
+    return null;
+  }
+
+  beforeEach(() => {
+    source.setValue(0);
+  });
+
+  it('getSnapshot changes every time a dependency changes', () => {
+    const root = create({ strictMode: true });
+
+    // Mounts the App with no dependencies.
+    act(() => root.update(<App getSnapshotOffset={0} getSnapshotDeps={[0]} />));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(0)',
+      'render: snapshot(0)',
+      // First lifecycle.
+      'effect: source(0) snapshot(0)',
+      // Second lifecycle.
+      'effect: source(0) snapshot(0)',
+    ]);
+
+    // Triggers an update.
+    act(() => root.update(<App getSnapshotOffset={1} getSnapshotDeps={[1]} />));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(1)',
+      'render: snapshot(1)',
+      'effect: source(0) snapshot(1)',
+    ]);
+
+    act(() => root.unmount());
+  });
+
+  it('getSnapshot is stable if no getSnapshot dependencies are provided', () => {
+    const root = create({ strictMode: true });
+
+    // Mounts the App with no dependencies.
+    act(() => root.update(<App getSnapshotOffset={0} />));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(0)',
+      'render: snapshot(0)',
+      // First lifecycle.
+      'effect: source(0) snapshot(0)',
+      // Second lifecycle.
+      'effect: source(0) snapshot(0)',
+    ]);
+
+    // Triggers an update.
+    act(() => root.update(<App getSnapshotOffset={1} />));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(0)',
+      'render: snapshot(0)',
+      'effect: source(0) snapshot(0)',
+    ]);
+
+    act(() => root.unmount());
+  });
+
+  it('correctly dispatches snapshot updates', () => {
+    const root = create({ strictMode: true });
+
+    // Mount the App.
+    act(() => root.update(<App getSnapshotOffset={0} />));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(0)',
+      'render: snapshot(0)',
+      // First lifecycle.
+      'effect: source(0) snapshot(0)',
+      // Second lifecycle
+      'effect: source(0) snapshot(0)',
+    ]);
+
+    // Dispatch an update with a new value.
+    act(() => source.setValue(1));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(1)',
+      'render: snapshot(1)',
+      'effect: source(1) snapshot(1)',
+    ]);
+
+    // Dispatch an update with the current value.
+    act(() => source.setValue(1));
+
+    expect(getValues()).toEqual([]);
+
+    // Re-render with no changes.
+    act(() => root.update(<App />));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(1)',
+      'render: snapshot(1)',
+      'effect: source(1) snapshot(1)',
+    ]);
+
+    // Update with the special value 2, The component will trigger a new update
+    // with the value 3 inside an effect.
+    act(() => source.setValue(2));
+
+    expect(getValues()).toEqual([
+      'render: snapshot(2)',
+      'render: snapshot(2)',
+      'effect: source(3) snapshot(2)',
+      'render: snapshot(3)',
+      'render: snapshot(3)',
+      'effect: source(3) snapshot(3)',
+    ]);
+
+    act(() => root.unmount());
+  });
+
+  it('acts correctly during ssr', () => {
+    const [useSnapshot] = withContractServer(
+      // Generate the source.
+      new Source(0),
+      // Subscribe to changes.
+      (source, onChange) => {
+        yieldValue(`never`, `this is never called`);
+        source.addChangeListener(onChange);
+      }
+    );
+
+    const App = () => {
+      const snapshot = useSnapshot(() => null);
+
+      yieldValue(`render`, `snapshot(${snapshot})`);
+      return null;
+    };
+
+    const root = create();
+    // Mounts the App.
+    act(() => root.update(<App />));
+
+    expect(getValues()).toEqual(['render: snapshot(null)']);
+
+    act(() => root.unmount());
+  });
+});