std-react-bindings 0.0.1

package/src/types/exports.ts

@@ -0,0 +1,2 @@
+export * from './array-like';
+export * from './empty';

package/src/use-binding-effect/__tests__/basic.test.ts

@@ -0,0 +1,70 @@
+import { jest } from '@jest/globals';
+import { waitFor } from '@testing-library/react';
+
+import { runInDom, sleep } from '../../__test_dependency__';
+import type { ReadonlyBinding } from '../../binding/types/readonly-binding';
+import { useBinding } from '../../binding/use-binding';
+import { useBindingEffect } from '../use-binding-effect';
+
+describe('useBindingEffect', () => {
+  it('should work with undefined bindings', () =>
+    runInDom(({ onMount }) => {
+      const callback = jest.fn((values) => {
+        expect(values).toBeUndefined();
+      });
+
+      useBindingEffect(undefined, callback, { triggerOnMount: true });
+
+      onMount(async () => {
+        await waitFor(() => expect(callback).toHaveBeenCalledTimes(1));
+      });
+    }));
+
+  it('with default settings, callback should only run if binding changed while mounted', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }, bindings: { b: ReadonlyBinding<number> }) => {
+        expect(b).toBe(0);
+        expect(bindings.b.get()).toBe(0);
+      });
+
+      useBindingEffect({ b }, callback);
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(0);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('with default settings, callback should be run on mount if bindings changed between render and mount', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }) => {
+        expect(b).toBe(1);
+      });
+
+      useBindingEffect({ b }, callback);
+      b.set(1);
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        b.set(1);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(2);
+      });
+    }));
+});

package/src/use-binding-effect/__tests__/throttled.test.ts

@@ -0,0 +1,106 @@
+import { jest } from '@jest/globals';
+
+import { runInDom, sleep } from '../../__test_dependency__';
+import { useBinding } from '../../binding/use-binding';
+import { useBindingEffect } from '../use-binding-effect';
+
+describe('useBindingEffect', () => {
+  it('trailing throttled effects should be run only when the elapsed interval has been reached', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }) => {
+        expect(b).toBe(0);
+      });
+
+      useBindingEffect({ b }, callback, { limitType: 'throttle', limitMode: 'trailing', limitMSec: 500 });
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(0);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).not.toHaveBeenCalled();
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).not.toHaveBeenCalled();
+
+        await sleep(500); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        b.set(1);
+        b.set(2);
+        b.set(3);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        await sleep(500); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(2);
+      });
+    }));
+
+  it('leading throttled effects should be run on the first change or on the next change after enough time has elapsed', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }) => {
+        expect(b).toBe(0);
+      });
+
+      useBindingEffect({ b }, callback, { limitType: 'throttle', limitMode: 'leading', limitMSec: 500 });
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(0);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        await sleep(500); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        b.set(1);
+
+        await sleep(0); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(2);
+
+        b.set(2);
+        b.set(3);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(2);
+
+        await sleep(50); // giving time for callback (shouldn't run though)
+
+        expect(callback).toHaveBeenCalledTimes(2);
+
+        await sleep(500); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(2);
+      });
+    }));
+});

package/src/use-binding-effect/__tests__/trigger-on-mount.test.tsx

@@ -0,0 +1,125 @@
+import { jest } from '@jest/globals';
+import { waitFor } from '@testing-library/react';
+import React from 'react';
+
+import { runInDom, sleep } from '../../__test_dependency__';
+import { useBinding } from '../../binding/use-binding';
+import { BindingsConsumer } from '../../components/BindingsConsumer';
+import { useBindingEffect } from '../use-binding-effect';
+
+describe('useBindingEffect', () => {
+  it('with triggerOnMount=false, callback should not be run on mount even if bindings changed between render and mount', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }) => {
+        expect(b).toBe(1);
+      });
+
+      useBindingEffect({ b }, callback, { triggerOnMount: false });
+      b.set(1);
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(0);
+
+        b.set(1);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('with triggerOnMount=true, callback should always be made on mount', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b: _b }: { b: number }) => {});
+
+      const refreshValue = useBinding(() => 0, { id: 'refreshValue' });
+      const MyComponent = () => {
+        useBindingEffect({ b }, callback, { triggerOnMount: true });
+
+        return <></>;
+      };
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        b.set(1);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(2);
+
+        refreshValue.set(1);
+        await waitFor(() => expect(callback).toHaveBeenCalledTimes(3));
+      });
+
+      return <BindingsConsumer bindings={refreshValue}>{() => <MyComponent />}</BindingsConsumer>;
+    }));
+
+  it('with triggerOnMount=first, callback should be made only on the first mount', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b: _b }: { b: number }) => {});
+
+      const refreshValue = useBinding(() => 0, { id: 'refreshValue' });
+      const MyComponent = () => {
+        useBindingEffect({ b }, callback, { triggerOnMount: 'first' });
+
+        return <></>;
+      };
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        b.set(1);
+        await waitFor(() => expect(callback).toHaveBeenCalledTimes(2));
+
+        refreshValue.set(1);
+        await expect(waitFor(() => expect(callback).not.toHaveBeenCalledTimes(2))).rejects.toThrow();
+      });
+
+      return <BindingsConsumer bindings={refreshValue}>{() => <MyComponent />}</BindingsConsumer>;
+    }));
+
+  it('with deps, callback should be made only on the first mount or if the dependency values change', () =>
+    runInDom(({ onMount }) => {
+      const callback = jest.fn(() => {});
+
+      const refreshValue = useBinding(() => 0, { id: 'refreshValue' });
+      const MyComponent = ({ value }: { value: number }) => {
+        useBindingEffect(undefined, callback, { deps: [value], limitType: 'none' });
+
+        return <></>;
+      };
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(0);
+
+        refreshValue.set(0);
+        await expect(waitFor(() => expect(callback).not.toHaveBeenCalledTimes(0))).rejects.toThrow();
+
+        refreshValue.set(1);
+        await waitFor(() => expect(callback).toHaveBeenCalledTimes(1));
+
+        refreshValue.set(1);
+        await expect(waitFor(() => expect(callback).not.toHaveBeenCalledTimes(1))).rejects.toThrow();
+
+        refreshValue.set(2);
+        await waitFor(() => expect(callback).toHaveBeenCalledTimes(2));
+      });
+
+      return <BindingsConsumer bindings={refreshValue}>{(refreshValue) => <MyComponent value={refreshValue} />}</BindingsConsumer>;
+    }));
+});

package/src/use-binding-effect/__tests__/value-comparison.test.ts

@@ -0,0 +1,71 @@
+import { jest } from '@jest/globals';
+
+import { runInDom, sleep } from '../../__test_dependency__';
+import { useBinding } from '../../binding/use-binding';
+import { useBindingEffect } from '../use-binding-effect';
+
+describe('useBindingEffect', () => {
+  it('with detectInputChanges=true, callback should only run if binding values really changed, according to areEqual', () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }) => {
+        expect(b).toBe(0);
+      });
+
+      useBindingEffect({ b }, callback, { detectInputChanges: true });
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(0);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(1);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it("with detectChanges=true and makeComparableInputValue=evenness checker, callback should only run if binding's evenness changes", () =>
+    runInDom(({ onMount }) => {
+      const b = useBinding(() => 0, { id: 'test' });
+
+      const callback = jest.fn(({ b }: { b: number }) => {
+        expect(b).toBe(0);
+      });
+
+      useBindingEffect({ b }, callback, { detectInputChanges: true, makeComparableInputValue: () => b.get() % 2 === 0 });
+
+      onMount(async () => {
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(0);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(2);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).not.toHaveBeenCalled();
+
+        b.set(3);
+
+        await sleep(50); // giving time for callback
+
+        expect(callback).toHaveBeenCalledTimes(1);
+      });
+    }));
+});

package/src/use-binding-effect/exports.ts

@@ -0,0 +1,2 @@
+export * from './types/exports';
+export * from './use-binding-effect';

package/src/use-binding-effect/types/exports.ts

@@ -0,0 +1 @@
+export * from './options';

package/src/use-binding-effect/types/options.ts

@@ -0,0 +1,50 @@
+import type { DependencyList } from 'react';
+
+import type { LimiterOptions } from '../../limiter/types/LimiterOptions';
+
+export interface UseBindingEffectOptions extends LimiterOptions {
+  /** A technical but human-readable ID */
+  id?: string;
+
+  /**
+   * On a rerender, deps changes are treated like bindings changes.  That is, if they change between renders, the input change detection
+   * logic is run (using the `areInputValuesEqual`, `detectInputChanges`, and `makeComparableInputValue` values) using the limiter (see
+   * `LimiterOptions`).
+   */
+  deps?: DependencyList;
+
+  /**
+   * If specified, overrides the function used to compare input values
+   *
+   * @defaultValue `_.isEqual`, which can be globally overridden using `setAreEqual`
+   */
+  areInputValuesEqual?: (a: any, b: any) => boolean;
+  /**
+   * - If `true` – `areInputValuesEqual` is used to compare the old and new results of `makeComparableInputValue` when any of the input
+   * bindings or `deps` are changed.  If the values are equal, the transformer won't be run.  If they're unequal, the transformer will be
+   * run.
+   * - If `false` – old and new values aren't compared, the transformer will always be run.
+   *
+   * @defaultValue `false`
+   */
+  detectInputChanges?: boolean;
+  /**
+   * By default, when `detectInputChanges` is true, the input is compared using all specified bindings.  This behavior can be overridden by
+   * providing this function to generate a value that can be compared instead.  This value will be remembered until the next comparison is
+   * needed.  Comparisons are performed using `areInputValuesEqual`
+   *
+   * @defaultValue A function that returns the values of all input bindings (including any additional bindings) and the deps
+   */
+  makeComparableInputValue?: () => any;
+
+  /**
+   * - If `true`, the callback is triggered every time this is mounted in addition to whenever the input bindings change.
+   * - If `false`, the callback is only triggered when the input bindings change.
+   * - If `'first'`, the callback is triggered on the first mount and whenever the input bindings change
+   * - If `'if-input-changed'`, the callback is triggered on mount if the bindings have changed since the last evaluation of the
+   * transformer
+   *
+   * @defaultValue `'if-input-changed'`
+   */
+  triggerOnMount?: boolean | 'first' | 'if-input-changed';
+}

package/src/use-binding-effect/use-binding-effect.ts

@@ -0,0 +1,204 @@
+import { useEffect, useRef } from 'react';
+
+import type { BindingArrayDependencies, BindingDependencies, NamedBindingDependencies } from '../binding/types/binding-dependencies';
+import type { ChangeListenerRemover } from '../binding/types/change-listener';
+import type { InferBindingValueTypes } from '../binding/types/infer-binding-value-types';
+import type { ReadonlyBinding } from '../binding/types/readonly-binding';
+import { isBinding } from '../binding-utils/type-utils';
+import { areEqual } from '../config/are-equal';
+import { normalizeAsArray } from '../internal-utils/array-like';
+import { extractBindingDependencyValues } from '../internal-utils/extract-binding-dependency-values';
+import { getTypedKeys } from '../internal-utils/get-typed-keys';
+import { pickLimiterOptions } from '../limiter/pick-limiter-options';
+import { useLimiter } from '../limiter/use-limiter';
+import type { EmptyObject } from '../types/empty';
+import { useCallbackRef } from '../utility-hooks/use-callback-ref';
+import { useStableValue } from '../utility-hooks/use-stable-value';
+import type { UseBindingEffectOptions } from './types/options';
+
+const emptyDependencies = Object.freeze({} as EmptyObject);
+
+/**
+ * Called when the associated bindings change, depending on the options provided to `useBindingEffect`.
+ *
+ * @param bindingValues - The extracted values of the associated named bindings.  If named bindings aren't used, this will be an empty
+ * object.
+ * @param bindings - The original named bindings if named bindings are used or an empty object otherwise.
+ */
+export type UseBindingEffectCallback<DependenciesT extends BindingDependencies> = (
+  bindingValues: InferBindingValueTypes<DependenciesT>,
+  bindings: DependenciesT
+) => void;
+
+/**
+ * Calls the specified callback function any time any of the specified bindings are changed.
+ *
+ * Most of the time you should use this hook rather than addChangeListener.
+ *
+ * @returns a function that can be called anytime to cancel the most recent limited callback.  This is useful, for example, if the the
+ * callback would have triggered a re-render that we, by other means, know to be unnecessary.
+ */
+export const useBindingEffect = <DependenciesT extends BindingDependencies>(
+  bindings: DependenciesT | undefined,
+  callback: UseBindingEffectCallback<DependenciesT>,
+  options: UseBindingEffectOptions = {}
+): (() => void) => {
+  const {
+    id,
+    deps,
+    areInputValuesEqual = areEqual,
+    detectInputChanges = false,
+    makeComparableInputValue,
+    triggerOnMount = 'if-input-changed'
+  } = options;
+
+  const limiterOptions = pickLimiterOptions(options);
+
+  const isNonNamedBindings = Array.isArray(bindings) || isBinding(bindings);
+  const nonNamedBindings = isNonNamedBindings ? (bindings as ReadonlyBinding | BindingArrayDependencies) : undefined;
+  const namedBindings = isNonNamedBindings ? undefined : (bindings as NamedBindingDependencies);
+  const namedBindingsKeys = namedBindings !== undefined ? getTypedKeys(namedBindings) : undefined;
+  const stableAllBindings = useStableValue(
+    isNonNamedBindings ? normalizeAsArray(nonNamedBindings) : Object.values(namedBindings ?? emptyDependencies)
+  );
+
+  // Doesn't need to be stable since always used in a callback ref
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  const getDependencyValues = () => extractBindingDependencyValues<DependenciesT>({ bindings, namedBindingsKeys });
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  const comparableInputValueMaker = makeComparableInputValue ?? getDependencyValues;
+  const lastComparableInputValue = useRef(
+    detectInputChanges && (triggerOnMount === false || triggerOnMount === 'if-input-changed') ? comparableInputValueMaker() : undefined
+  );
+
+  /** Only used when `detectInputChanges` is `false` and `triggerOnMount` is `'if-input-changed'` */
+  const lastChangeUids = useRef<string | undefined>();
+
+  const limiter = useLimiter({
+    id: id ?? 'use-binding-effect',
+    cancelOnUnmount: true,
+    ...limiterOptions
+  });
+
+  const checkAndUpdateIfInputChanged = useCallbackRef(() => {
+    if (detectInputChanges) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const nextComparableInputValue = comparableInputValueMaker!();
+      if (areInputValuesEqual(lastComparableInputValue.current, nextComparableInputValue)) {
+        return false;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      lastComparableInputValue.current = nextComparableInputValue;
+      return true;
+    } else if (triggerOnMount === 'if-input-changed') {
+      const newChangeUids = makeChangeUidsString(stableAllBindings);
+      if (newChangeUids === lastChangeUids.current) {
+        return false;
+      }
+
+      lastChangeUids.current = newChangeUids;
+      return true;
+    } else {
+      return true;
+    }
+  });
+
+  const isFirstRender = useRef(true);
+  const needsTrigger = useRef(false);
+
+  const triggerCallback = useCallbackRef((needsInputChangeTrackingUpdate: boolean) => {
+    needsTrigger.current = false;
+
+    if (needsInputChangeTrackingUpdate) {
+      // We don't care about the result here -- just want to update the tracking
+      checkAndUpdateIfInputChanged();
+    }
+
+    callback(getDependencyValues(), bindings ?? (emptyDependencies as DependenciesT));
+  });
+
+  const performChecksAndTriggerCallbackIfNeeded = useCallbackRef(() => {
+    if (needsTrigger.current) {
+      triggerCallback(true);
+    } else {
+      const didChange = checkAndUpdateIfInputChanged();
+      if (detectInputChanges && !didChange) {
+        return; // No change
+      }
+
+      triggerCallback(false);
+    }
+  });
+
+  if (isFirstRender.current) {
+    isFirstRender.current = false;
+
+    if (!detectInputChanges && triggerOnMount === 'if-input-changed') {
+      lastChangeUids.current = makeChangeUidsString(stableAllBindings);
+    }
+  }
+
+  useEffect(() => {
+    const addedBindingUids = new Set<string>();
+    const removers: ChangeListenerRemover[] = [];
+    for (const b of stableAllBindings) {
+      if (b !== undefined && !addedBindingUids.has(b.uid)) {
+        // Making sure we only listen for changes once per binding, even if the same binding is listed multiple times
+        addedBindingUids.add(b.uid);
+
+        removers.push(b.addChangeListener(() => limiter.limit(performChecksAndTriggerCallbackIfNeeded)));
+      }
+    }
+
+    return () => {
+      for (const remover of removers) {
+        remover();
+      }
+      removers.length = 0;
+    };
+  }, [limiter, performChecksAndTriggerCallbackIfNeeded, stableAllBindings]);
+
+  const isFirstMount = useRef(true);
+  useEffect(() => {
+    if (
+      needsTrigger.current ||
+      triggerOnMount === true ||
+      (isFirstMount.current && triggerOnMount === 'first') ||
+      (triggerOnMount === 'if-input-changed' && checkAndUpdateIfInputChanged())
+    ) {
+      needsTrigger.current = true;
+      limiter.limit(() => triggerCallback(true));
+    }
+    isFirstMount.current = false;
+  });
+
+  // If the deps changed,
+  const lastDepsValue = useRef(deps);
+  if (!areEqual(lastDepsValue.current, deps)) {
+    lastDepsValue.current = deps;
+
+    needsTrigger.current = true;
+    limiter.limit(() => triggerCallback(true));
+  }
+
+  // If the upcoming callback is canceled, it's assumed we have already dealt with the input in a different way, so we need to update the
+  // tracking info to make sure we don't reprocess the same thing later
+  return () => {
+    limiter.cancel();
+    needsTrigger.current = false;
+    // We don't care about the result here -- just want to update the tracking
+    checkAndUpdateIfInputChanged();
+  };
+};
+
+// Helpers
+
+const makeChangeUidsString = (bindings: Array<ReadonlyBinding | undefined>) => {
+  const array: string[] = [];
+  for (const b of bindings) {
+    array.push(b?.getChangeUid() ?? '');
+  }
+  return array.join(',');
+};