std-react-bindings 0.0.1

package/src/specialized-bindings/derived-binding/options.ts

@@ -0,0 +1,56 @@
+import type { DependencyList } from 'react';
+
+import type { LimiterOptions } from '../../limiter/types/LimiterOptions';
+
+export interface DerivedBindingOptions<GetT> extends LimiterOptions {
+  /** A technical, but human-readable ID, which isn't guaranteed to be unique */
+  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 `true`
+   */
+  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.  The generated 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 and the deps
+   */
+  makeComparableInputValue?: () => any;
+
+  /**
+   * If specified, overrides the function used to compare output values
+   *
+   * @defaultValue `_.isEqual`, which can be globally overridden using `setAreEqual`
+   */
+  areOutputValuesEqual?: (a: GetT, b: GetT) => boolean;
+  /**
+   * - If `true` – `areOutputValuesEqual` is used to compare the old and new results of the transformer function, each time it's run.  If the
+   * values are equal, the derived binding's value won't be changed.  If they're unequal, the binding value will be changed and listeners
+   * will be notified.
+   * - If `false` – old and new results of the transformer function aren't compared.  The derived binding's value will always be changed each
+   * time the transformer function is run.
+   *
+   * @defaultValue `true`
+   */
+  detectOutputChanges?: boolean;
+}

package/src/specialized-bindings/derived-binding/use-derived-binding.ts

@@ -0,0 +1,77 @@
+import type { BindingDependencies, NamedBindingDependencies } from '../../binding/types/binding-dependencies';
+import type { InferBindingValueTypes } from '../../binding/types/infer-binding-value-types';
+import type { ReadonlyBinding } from '../../binding/types/readonly-binding';
+import { useBinding } from '../../binding/use-binding';
+import { isBinding } from '../../binding-utils/type-utils';
+import { getStatsHandler } from '../../config/stats-handler';
+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 { useBindingEffect } from '../../use-binding-effect/use-binding-effect';
+import { useCallbackRef } from '../../utility-hooks/use-callback-ref';
+import type { DerivedBindingOptions } from './options';
+
+/**
+ * Called to compute the derived value on the initial render and anytime the dependencies change.
+ *
+ * @param bindingValues - The extracted values of the bindings.
+ * @param bindings - The original bindings
+ *
+ * @returns The derived value
+ */
+export type UseDerivedBindingTransformer<GetT, DependenciesT extends BindingDependencies> = (
+  bindingValues: InferBindingValueTypes<DependenciesT>,
+  bindings: DependenciesT
+) => GetT;
+
+/** A derived binding is a binding derived from zero or more other bindings */
+export const useDerivedBinding = <GetT, DependenciesT extends BindingDependencies>(
+  bindings: DependenciesT | undefined,
+  transformer: UseDerivedBindingTransformer<GetT, DependenciesT>,
+  options: DerivedBindingOptions<GetT>
+): ReadonlyBinding<GetT> => {
+  const {
+    id,
+    deps,
+    areInputValuesEqual,
+    detectInputChanges = true,
+    makeComparableInputValue,
+    areOutputValuesEqual,
+    detectOutputChanges = true
+  } = options;
+
+  const limiterOptions = pickLimiterOptions(options);
+
+  const isNonNamedBindings = Array.isArray(bindings) || isBinding(bindings);
+  const namedBindings = isNonNamedBindings ? undefined : (bindings as NamedBindingDependencies);
+  const namedBindingsKeys = namedBindings !== undefined ? getTypedKeys(namedBindings) : undefined;
+
+  // Doesn't need to be stable since Refreshable will always get rendered with the latest anyway
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  const getDependencyValues = () => extractBindingDependencyValues<DependenciesT>({ bindings, namedBindingsKeys });
+
+  const measuredTransformer = useCallbackRef((dependencyValues: InferBindingValueTypes<DependenciesT> = getDependencyValues()) => {
+    const startMSec = performance.now();
+    try {
+      return transformer(dependencyValues, bindings ?? (undefined as any as DependenciesT));
+    } finally {
+      getStatsHandler().trackDerivedBindingTransformerDidRun?.({ id, durationMSec: performance.now() - startMSec });
+    }
+  });
+
+  const internalBinding = useBinding(() => measuredTransformer(), {
+    id,
+    areEqual: areOutputValuesEqual,
+    detectChanges: detectOutputChanges
+  });
+
+  useBindingEffect(bindings, (namedBindingValues) => internalBinding.set(measuredTransformer(namedBindingValues)), {
+    deps,
+    areInputValuesEqual,
+    detectInputChanges,
+    makeComparableInputValue,
+    ...limiterOptions
+  });
+
+  return internalBinding;
+};

package/src/specialized-bindings/exports.ts

@@ -0,0 +1,4 @@
+export * from './const-binding';
+export * from './derived-binding/exports';
+export * from './flattened-binding';
+export * from './transient-derived-binding/exports';

package/src/specialized-bindings/flattened-binding.ts

@@ -0,0 +1,104 @@
+import { useEffect, useRef } from 'react';
+
+import type { BindingDependencies, NamedBindingDependencies } from '../binding/types/binding-dependencies';
+import type { InferBindingValueTypes } from '../binding/types/infer-binding-value-types';
+import type { ReadonlyBinding } from '../binding/types/readonly-binding';
+import { useBinding } from '../binding/use-binding';
+import { isBinding } from '../binding-utils/type-utils';
+import { useIsMountedRef } from '../internal-hooks/use-is-mounted-ref';
+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 { useBindingEffect } from '../use-binding-effect/use-binding-effect';
+import { useStableValue } from '../utility-hooks/use-stable-value';
+import type { DerivedBindingOptions } from './derived-binding/options';
+
+/**
+ * Called to extract the second-level binding on the initial render and anytime the dependencies change.
+ *
+ * @param bindingValues - The extracted values of bindings.
+ * @param bindings - The original bindings.
+ *
+ * @returns The second-level binding (i.e. a binding determined dynamically by executing this function)
+ */
+export type UseFlattenedBindingTransformer<GetT, DependenciesT extends BindingDependencies> = (
+  bindingValues: InferBindingValueTypes<DependenciesT>,
+  bindings: DependenciesT
+) => ReadonlyBinding<GetT>;
+
+/** Use when a binding contains another binding, to listen to the second-level binding if either the first or second levels change */
+export const useFlattenedBinding = <GetT, DependenciesT extends BindingDependencies>(
+  bindings: DependenciesT | undefined,
+  transformer: UseFlattenedBindingTransformer<GetT, DependenciesT>,
+  options: DerivedBindingOptions<GetT>
+): ReadonlyBinding<GetT> => {
+  const {
+    id,
+    deps = [],
+    areInputValuesEqual,
+    detectInputChanges = true,
+    makeComparableInputValue,
+    areOutputValuesEqual,
+    detectOutputChanges = true
+  } = options;
+
+  const limiterOptions = pickLimiterOptions(options);
+
+  const isMounted = useIsMountedRef();
+
+  const isNonNamedBindings = Array.isArray(bindings) || isBinding(bindings);
+  const namedBindings = useStableValue(isNonNamedBindings ? undefined : (bindings as NamedBindingDependencies));
+  const namedBindingsKeys = namedBindings !== undefined ? getTypedKeys(namedBindings) : undefined;
+
+  // Doesn't need to be stable since Refreshable will always get rendered with the latest anyway
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  const getDependencyValues = () => extractBindingDependencyValues<DependenciesT>({ bindings, namedBindingsKeys });
+
+  const internalBinding = useBinding(() => transformer(getDependencyValues(), bindings ?? (undefined as any as DependenciesT)).get(), {
+    id,
+    areEqual: areOutputValuesEqual,
+    detectChanges: detectOutputChanges
+  });
+
+  const secondLevelBindingListenerRemover = useRef<(() => void) | undefined>(undefined);
+
+  useBindingEffect(
+    bindings,
+    (dependencyValues) => {
+      secondLevelBindingListenerRemover.current?.();
+      secondLevelBindingListenerRemover.current = undefined;
+
+      const secondLevelBinding = transformer(dependencyValues, bindings ?? (undefined as any as DependenciesT));
+      internalBinding.set(secondLevelBinding.get());
+
+      if (isMounted.current ?? false) {
+        secondLevelBindingListenerRemover.current = secondLevelBinding.addChangeListener(() => {
+          internalBinding.set(secondLevelBinding.get());
+        });
+      }
+    },
+    {
+      deps,
+      areInputValuesEqual,
+      detectInputChanges,
+      makeComparableInputValue,
+      triggerOnMount: true,
+      ...limiterOptions
+    }
+  );
+
+  useEffect(() => {
+    const secondLevelBinding = transformer(getDependencyValues(), bindings ?? (undefined as any as DependenciesT));
+
+    secondLevelBindingListenerRemover.current = secondLevelBinding.addChangeListener(() => {
+      internalBinding.set(secondLevelBinding.get());
+    });
+
+    return () => {
+      secondLevelBindingListenerRemover.current?.();
+      secondLevelBindingListenerRemover.current = undefined;
+    };
+  });
+
+  return internalBinding;
+};

package/src/specialized-bindings/transient-derived-binding/__tests__/basic.test.ts

@@ -0,0 +1,75 @@
+import { jest } from '@jest/globals';
+
+import { runInDom } from '../../../__test_dependency__';
+import { useBinding } from '../../../binding/use-binding';
+import { makeTransientDerivedBinding } from '../make-transient-derived-binding';
+
+describe('makeTransientDerivedBinding', () => {
+  it('should work with undefined bindings', () =>
+    runInDom(({ onMount }) => {
+      onMount(() => {
+        expect(
+          makeTransientDerivedBinding(
+            undefined,
+            (values) => {
+              expect(values).toBeUndefined();
+              return 1;
+            },
+            { id: 'a' }
+          ).get()
+        ).toBe(1);
+      });
+    }));
+
+  it('initial value should work with named bindings', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+
+      const bTransformer = jest.fn(({ a }: { a: number }) => a + 1);
+
+      onMount(() => {
+        expect(makeTransientDerivedBinding({ a }, bTransformer, { id: 'a' }).get()).toBe(1);
+        expect(bTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('initial value should work with single unnamed bindings', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+
+      const bTransformer = jest.fn(() => a.get() + 1);
+
+      onMount(() => {
+        expect(makeTransientDerivedBinding(a, bTransformer, { id: 'a' }).get()).toBe(1);
+        expect(bTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('initial value should work with array of unnamed bindings', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+
+      const bTransformer = jest.fn(() => a.get() + 1);
+
+      onMount(() => {
+        expect(makeTransientDerivedBinding([a], bTransformer, { id: 'a' }).get()).toBe(1);
+        expect(bTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('updates to dependencies should be propagated asynchronously', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+
+      const bTransformer = jest.fn(({ a }: { a: number }) => a + 1);
+
+      onMount(async () => {
+        expect(makeTransientDerivedBinding({ a }, bTransformer, { id: 'b' }).get()).toBe(1);
+
+        a.set(1);
+
+        expect(makeTransientDerivedBinding({ a }, bTransformer, { id: 'b' }).get()).toBe(2);
+        expect(bTransformer).toHaveBeenCalledTimes(2);
+      });
+    }));
+});

package/src/specialized-bindings/transient-derived-binding/__tests__/derivations-of-derivations.test.ts

@@ -0,0 +1,69 @@
+import { jest } from '@jest/globals';
+
+import { runInDom } from '../../../__test_dependency__';
+import { useBinding } from '../../../binding/use-binding';
+import { makeTransientDerivedBinding } from '../make-transient-derived-binding';
+
+describe('makeTransientDerivedBinding', () => {
+  it('initial value should work with derivations of derivations', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+      const b = makeTransientDerivedBinding({ a }, ({ a }) => a + 1, { id: 'b' });
+      const c = makeTransientDerivedBinding({ b }, ({ b }) => b + 1, { id: 'c' });
+
+      const dTransformer = jest.fn(({ c }: { c: number }) => c + 1);
+      const d = makeTransientDerivedBinding({ c }, dTransformer, { id: 'd' });
+
+      onMount(() => {
+        expect(d.get()).toBe(3);
+        expect(dTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('updates to deepest dependency should be propagated immediately', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+      const b = makeTransientDerivedBinding({ a }, ({ a }) => a + 1, { id: 'b' });
+      const c = makeTransientDerivedBinding({ b }, ({ b }) => b + 1, { id: 'c' });
+
+      const dTransformer = jest.fn(({ c }: { c: number }) => c + 1);
+      const d = makeTransientDerivedBinding({ c }, dTransformer, { id: 'd' });
+
+      onMount(async () => {
+        expect(b.get()).toBe(1);
+        expect(c.get()).toBe(2);
+        expect(d.get()).toBe(3);
+
+        a.set(1);
+
+        expect(b.get()).toBe(2);
+        expect(c.get()).toBe(3);
+        expect(d.get()).toBe(4);
+        expect(dTransformer).toHaveBeenCalledTimes(2);
+      });
+    }));
+
+  it('multiple quick updates to deepest dependency should be propagated immediately', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+      const b = makeTransientDerivedBinding({ a }, ({ a }) => a + 1, { id: 'b' });
+      const c = makeTransientDerivedBinding({ b }, ({ b }) => b + 1, { id: 'c' });
+
+      const dTransformer = jest.fn(({ c }: { c: number }) => c + 1);
+      const d = makeTransientDerivedBinding({ c }, dTransformer, { id: 'd' });
+
+      onMount(async () => {
+        expect(b.get()).toBe(1);
+        expect(c.get()).toBe(2);
+        expect(d.get()).toBe(3);
+
+        a.set(1);
+        a.set(2);
+
+        expect(b.get()).toBe(3);
+        expect(c.get()).toBe(4);
+        expect(d.get()).toBe(5);
+        expect(dTransformer).toHaveBeenCalledTimes(2);
+      });
+    }));
+});

package/src/specialized-bindings/transient-derived-binding/__tests__/multiple-dependencies.test.ts

@@ -0,0 +1,52 @@
+import { jest } from '@jest/globals';
+
+import { runInDom } from '../../../__test_dependency__';
+import { useBinding } from '../../../binding/use-binding';
+import { makeTransientDerivedBinding } from '../make-transient-derived-binding';
+
+describe('makeTransientDerivedBinding', () => {
+  it('initial value should work with multiple dependencies', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+      const b = useBinding(() => 1, { id: 'b' });
+
+      const cTransformer = jest.fn(({ a, b }: { a: number; b: number }) => a + b + 1);
+      const c = makeTransientDerivedBinding({ a, b }, cTransformer, { id: 'c' });
+
+      onMount(() => {
+        expect(c.get()).toBe(2);
+        expect(cTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('updates to one dependency should be propagated immediately', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+      const b = useBinding(() => 1, { id: 'b' });
+
+      const cTransformer = jest.fn(({ a, b }: { a: number; b: number }) => a + b + 1);
+      const c = makeTransientDerivedBinding({ a, b }, cTransformer, { id: 'c' });
+
+      onMount(async () => {
+        a.set(2);
+        expect(c.get()).toBe(4);
+        expect(cTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('quick updates to multiple dependencies should be propagated immediately', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a' });
+      const b = useBinding(() => 1, { id: 'b' });
+
+      const cTransformer = jest.fn(({ a, b }: { a: number; b: number }) => a + b + 1);
+      const c = makeTransientDerivedBinding({ a, b }, cTransformer, { id: 'c' });
+
+      onMount(async () => {
+        a.set(2);
+        b.set(3);
+        expect(c.get()).toBe(6);
+        expect(cTransformer).toHaveBeenCalledTimes(1);
+      });
+    }));
+});

package/src/specialized-bindings/transient-derived-binding/exports.ts

@@ -0,0 +1,3 @@
+export * from './make-transient-derived-binding';
+export * from './types/exports';
+export * from './use-transient-derived-binding';

package/src/specialized-bindings/transient-derived-binding/make-transient-derived-binding.ts

@@ -0,0 +1,63 @@
+import type { BindingArrayDependencies, BindingDependencies, NamedBindingDependencies } from '../../binding/types/binding-dependencies';
+import type { ReadonlyBinding } from '../../binding/types/readonly-binding';
+import { isBinding } from '../../binding-utils/type-utils';
+import { getLogger } from '../../config/logging';
+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 { makeUID } from '../../internal-utils/uid';
+import type { EmptyObject } from '../../types/empty';
+import type { UseDerivedBindingTransformer } from '../derived-binding/use-derived-binding';
+import type { MakeTransientDerivedBindingArgs } from './types/transient-derived-binding-args';
+
+const emptyNamedBindings = Object.freeze({} as EmptyObject);
+
+/**
+ * Similar to `useDerivedBinding` except that this binding doesn't persist any values internally.  The derivative is computed each time the
+ * getter is accessed and listeners are immediately triggered any time any of the dependencies change.
+ *
+ * This is most useful for inline declarations of derivatives that would feel too-heavy to declare elsewhere.
+ */
+export const makeTransientDerivedBinding = <GetT, DependenciesT extends BindingDependencies>(
+  bindings: DependenciesT | undefined,
+  transformer: UseDerivedBindingTransformer<GetT, DependenciesT>,
+  { id }: MakeTransientDerivedBindingArgs = {}
+): ReadonlyBinding<GetT> => {
+  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 allBindings = isNonNamedBindings ? normalizeAsArray(nonNamedBindings) : Object.values(namedBindings ?? emptyNamedBindings);
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  const getDependencyValues = () => extractBindingDependencyValues<DependenciesT>({ bindings, namedBindingsKeys });
+
+  const uid = makeUID();
+
+  return {
+    isBinding: true,
+    id: id ?? uid,
+    uid,
+    addChangeListener: (listener) => {
+      const removers = allBindings.map((b) => b?.addChangeListener(listener));
+
+      let alreadyRemoved = false;
+      return () => {
+        if (alreadyRemoved) {
+          getLogger().debug?.(`A change listener for binding ${id ?? uid} was removed more than once`);
+          return;
+        }
+        alreadyRemoved = true;
+
+        for (const remover of removers) {
+          return remover?.();
+        }
+      };
+    },
+    get: () => transformer(getDependencyValues(), bindings ?? (undefined as any as DependenciesT)),
+    getChangeUid: () => allBindings.map((b) => b?.getChangeUid() ?? '').join('+'),
+    isModified: () => false,
+    isLocked: () => true,
+    lock: () => () => {}
+  };
+};

package/src/specialized-bindings/transient-derived-binding/types/exports.ts

@@ -0,0 +1 @@
+export * from './transient-derived-binding-args';

package/src/specialized-bindings/transient-derived-binding/types/transient-derived-binding-args.ts

@@ -0,0 +1,11 @@
+import type { DependencyList } from 'react';
+
+export interface MakeTransientDerivedBindingArgs {
+  /** A technical, but human-readable ID, which isn't guaranteed to be unique */
+  id?: string;
+}
+
+export interface UseTransientDerivedBindingArgs extends MakeTransientDerivedBindingArgs {
+  /** Hook dependencies */
+  deps?: DependencyList;
+}

package/src/specialized-bindings/transient-derived-binding/use-transient-derived-binding.ts

@@ -0,0 +1,25 @@
+import type { DependencyList } from 'react';
+import { useMemo } from 'react';
+
+import type { BindingDependencies } from '../../binding/types/binding-dependencies';
+import type { ReadonlyBinding } from '../../binding/types/readonly-binding';
+import type { UseDerivedBindingTransformer } from '../derived-binding/use-derived-binding';
+import { makeTransientDerivedBinding } from './make-transient-derived-binding';
+import type { UseTransientDerivedBindingArgs } from './types/transient-derived-binding-args';
+
+const emptyDeps: DependencyList = Object.freeze([]);
+
+/**
+ * Similar to `useDerivedBinding` except that this binding doesn't persist any values internally.  The derivative is computed each time the
+ * getter is accessed and listeners are immediately triggered any time any of the dependencies change.
+ *
+ * This is most useful for cases where bindings need to have up to date values even when unmounted (though this still wont be proactively
+ * triggered when unmounted).
+ */
+export const useTransientDerivedBinding = <GetT, DependenciesT extends BindingDependencies>(
+  bindings: DependenciesT | undefined,
+  transformer: UseDerivedBindingTransformer<GetT, DependenciesT>,
+  args: UseTransientDerivedBindingArgs = {}
+): ReadonlyBinding<GetT> =>
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useMemo(() => makeTransientDerivedBinding<GetT, DependenciesT>(bindings, transformer, args), args.deps ?? emptyDeps);

package/src/synchronization/__tests__/use-bi-dir-binding-sync.test.ts

@@ -0,0 +1,27 @@
+import { waitFor } from '@testing-library/react';
+
+import { runInDom } from '../../__test_dependency__';
+import { useBinding } from '../../binding/use-binding';
+import { useBiDirBindingSync } from '../use-bi-dir-binding-sync';
+
+describe('useBiDirBindingSync', () => {
+  it('should work', () =>
+    runInDom(({ onMount }) => {
+      const a = useBinding(() => 0, { id: 'a', detectChanges: true });
+      const b = useBinding(() => 1, { id: 'b', detectChanges: true });
+
+      useBiDirBindingSync(a, b);
+
+      onMount(async () => {
+        await waitFor(() => expect(b.get()).toBe(0));
+
+        b.set(2);
+
+        await waitFor(() => expect(a.get()).toBe(2));
+
+        a.set(3);
+
+        await waitFor(() => expect(b.get()).toBe(3));
+      });
+    }));
+});

package/src/synchronization/__tests__/use-uni-dir-binding-sync.test.ts

@@ -0,0 +1,23 @@
+import { waitFor } from '@testing-library/react';
+
+import { runInDom } from '../../__test_dependency__';
+import { useBinding } from '../../binding/use-binding';
+import { useUniDirBindingSync } from '../use-uni-dir-binding-sync';
+
+describe('useUniDirBindingSync', () => {
+  it('should work', () =>
+    runInDom(({ onMount }) => {
+      const dest = useBinding(() => 0, { id: 'dest', detectChanges: true });
+      const source = useBinding(() => 1, { id: 'source', detectChanges: true });
+
+      useUniDirBindingSync(source, dest);
+
+      onMount(async () => {
+        await waitFor(() => expect(dest.get()).toBe(1));
+
+        source.set(2);
+
+        await waitFor(() => expect(dest.get()).toBe(2));
+      });
+    }));
+});

package/src/synchronization/exports.ts

@@ -0,0 +1,3 @@
+export * from './types/exports';
+export * from './use-bi-dir-binding-sync';
+export * from './use-uni-dir-binding-sync';

package/src/synchronization/types/exports.ts

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

package/src/synchronization/types/options.ts

@@ -0,0 +1,15 @@
+import type { DependencyList } from 'react';
+
+import type { LimiterOptions } from '../../limiter/types/LimiterOptions';
+
+export interface UseBindingSyncOptions 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;
+}

package/src/synchronization/use-bi-dir-binding-sync.ts

@@ -0,0 +1,14 @@
+import type { Binding } from '../binding/types/binding';
+import { useBindingEffect } from '../use-binding-effect/use-binding-effect';
+import type { UseBindingSyncOptions } from './types/options';
+
+/**
+ * Synchronizes two bindings bidirectionally so that any change in one will also affect the other.
+ *
+ * It's the responsibility of the bindings themselves to make sure this doesn't result in an infinite update.  For example, the bindings
+ * could be configured to use `detectChanges: true`, so that trivial changes doesn't result in triggers.
+ */
+export const useBiDirBindingSync = <T>(a: Binding<T>, b: Binding<T>, options?: UseBindingSyncOptions) => {
+  useBindingEffect(a, (a) => b.set(a), { ...options, triggerOnMount: true });
+  useBindingEffect(b, (b) => a.set(b), { ...options, triggerOnMount: true });
+};

package/src/synchronization/use-uni-dir-binding-sync.ts

@@ -0,0 +1,9 @@
+import type { Binding } from '../binding/types/binding';
+import type { ReadonlyBinding } from '../binding/types/readonly-binding';
+import { useBindingEffect } from '../use-binding-effect/use-binding-effect';
+import type { UseBindingSyncOptions } from './types/options';
+
+/** Synchronizes a source binding into a destination binding */
+export const useUniDirBindingSync = <T>(source: ReadonlyBinding<T>, dest: Binding<T>, options?: UseBindingSyncOptions) => {
+  useBindingEffect(source, (source) => dest.set(source), { ...options, triggerOnMount: true });
+};

package/src/types/array-like.ts

@@ -0,0 +1,2 @@
+/** A single instance or an array of instances */
+export type SingleOrArray<T> = T | T[];

package/src/types/empty.ts

@@ -0,0 +1,2 @@
+/** An empty object */
+export type EmptyObject = Record<string, never>;