std-react-bindings 0.0.1

package/src/binding-utils/__tests__/are-all-bindings-locked.test.ts

@@ -0,0 +1,40 @@
+import { makeBinding } from '../../binding/make-binding';
+import { areAnyBindingsLocked } from '../lock-utils';
+
+describe('areAnyBindingsLocked', () => {
+  it('should return false for no bindings specified', () => {
+    expect(areAnyBindingsLocked([])).toBeFalsy();
+    expect(areAnyBindingsLocked([undefined, undefined])).toBeFalsy();
+  });
+
+  it('should return false for for all unlocked bindings', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    expect(areAnyBindingsLocked([b1, b2])).toBeFalsy();
+  });
+
+  it('should return true if one of two bindings are locked', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    const unlock = b2.lock();
+
+    expect(areAnyBindingsLocked([b1, b2])).toBeTruthy();
+
+    unlock();
+  });
+
+  it('should return true if two of two bindings are locked', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    const unlock1 = b1.lock();
+    const unlock2 = b2.lock();
+
+    expect(areAnyBindingsLocked([b1, b2])).toBeTruthy();
+
+    unlock1();
+    unlock2();
+  });
+});

package/src/binding-utils/__tests__/are-any-bindings-modified.test.ts

@@ -0,0 +1,35 @@
+import { makeBinding } from '../../binding/make-binding';
+import { areAnyBindingsModified } from '../modified-utils';
+
+describe('areAnyBindingsModified', () => {
+  it('should return false for no bindings specified', () => {
+    expect(areAnyBindingsModified([])).toBeFalsy();
+    expect(areAnyBindingsModified([undefined, undefined])).toBeFalsy();
+  });
+
+  it('should return false for for all unmodified bindings', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    expect(areAnyBindingsModified([b1, b2])).toBeFalsy();
+  });
+
+  it('should return true if one of two bindings are modified', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    b2.set(1);
+
+    expect(areAnyBindingsModified([b1, b2])).toBeTruthy();
+  });
+
+  it('should return true if two of two bindings are modified', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    b1.set(1);
+    b2.set(2);
+
+    expect(areAnyBindingsModified([b1, b2])).toBeTruthy();
+  });
+});

package/src/binding-utils/__tests__/lock-all-bindings.test.ts

@@ -0,0 +1,36 @@
+import { makeBinding } from '../../binding/make-binding';
+import { lockAllBindings } from '../lock-utils';
+
+describe('lockAllBindings', () => {
+  it('should work with no bindings', () => {
+    const unlock1 = lockAllBindings([]);
+    const unlock2 = lockAllBindings([undefined, undefined]);
+
+    unlock2();
+    unlock1();
+  });
+
+  it('should work with bindings', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    const unlock = lockAllBindings([b1, b2]);
+
+    expect(b1.isLocked()).toBeTruthy();
+    expect(b2.isLocked()).toBeTruthy();
+
+    b1.set(1);
+    b2.set(2);
+
+    expect(b1.get()).toBe(0);
+    expect(b2.get()).toBe(0);
+
+    unlock();
+
+    expect(b1.isLocked()).toBeFalsy();
+    expect(b2.isLocked()).toBeFalsy();
+
+    expect(b1.get()).toBe(1);
+    expect(b2.get()).toBe(2);
+  });
+});

package/src/binding-utils/__tests__/lock-bindings-and-do.test.ts

@@ -0,0 +1,52 @@
+import { jest } from '@jest/globals';
+
+import { sleep } from '../../__test_dependency__';
+import { makeBinding } from '../../binding/make-binding';
+import { lockBindingsAndDo } from '../lock-utils';
+
+describe('lockBindingsAndDo', () => {
+  describe('with synchronous callback', () => {
+    it('should work with no bindings', () => {
+      const func = jest.fn();
+      lockBindingsAndDo([undefined, undefined], func);
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+
+    it('should work with bindings', () => {
+      const b1 = makeBinding(() => 0, { id: 'test1' });
+      const b2 = makeBinding(() => 0, { id: 'test2' });
+
+      const func = jest.fn(() => {
+        expect(b1.isLocked()).toBe(true);
+        expect(b2.isLocked()).toBe(true);
+      });
+      lockBindingsAndDo([b1, b2], func);
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('with asynchronous callback', () => {
+    it('should work with no bindings', async () => {
+      const func = jest.fn(async () => {});
+      await lockBindingsAndDo([undefined, undefined], func);
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+
+    it('should work with bindings', async () => {
+      const b1 = makeBinding(() => 0, { id: 'test1' });
+      const b2 = makeBinding(() => 0, { id: 'test2' });
+
+      const func = jest.fn(async () => {
+        expect(b1.isLocked()).toBe(true);
+        expect(b2.isLocked()).toBe(true);
+
+        await sleep(100);
+
+        expect(b1.isLocked()).toBe(true);
+        expect(b2.isLocked()).toBe(true);
+      });
+      await lockBindingsAndDo([b1, b2], func);
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/binding-utils/__tests__/set-all-bindings-modified.test.ts

@@ -0,0 +1,22 @@
+import { makeBinding } from '../../binding/make-binding';
+import { setAllBindingsModified } from '../modified-utils';
+
+describe('setAllBindingsModified', () => {
+  it('should work with no bindings', () => {
+    setAllBindingsModified([], true);
+    setAllBindingsModified([undefined, undefined], true);
+  });
+
+  it('should work with bindings', () => {
+    const b1 = makeBinding(() => 0, { id: 'test1' });
+    const b2 = makeBinding(() => 0, { id: 'test2' });
+
+    expect(b1.isModified()).toBeFalsy();
+    expect(b2.isModified()).toBeFalsy();
+
+    setAllBindingsModified([b1, b2], true);
+
+    expect(b1.isModified()).toBeTruthy();
+    expect(b2.isModified()).toBeTruthy();
+  });
+});

package/src/binding-utils/exports.ts

@@ -0,0 +1,3 @@
+export * from './lock-utils';
+export * from './modified-utils';
+export * from './type-utils';

package/src/binding-utils/internal/__tests__/make-value-then-do.test.ts

@@ -0,0 +1,52 @@
+import { jest } from '@jest/globals';
+
+import { sleep } from '../../../__test_dependency__';
+import { makeValueThenDo } from '../make-value-then-do';
+
+describe('makeValueThenDo', () => {
+  describe('synchronous makeValue functions', () => {
+    it('should result in then function being called synchronously', () => {
+      const thenFunc = jest.fn();
+      makeValueThenDo(() => 1, thenFunc);
+      expect(thenFunc).toHaveBeenLastCalledWith(1);
+    });
+
+    it('that throw should result in then function being called synchronously but without a value', () => {
+      const thenFunc = jest.fn();
+      expect(() => {
+        makeValueThenDo(() => {
+          throw new Error();
+        }, thenFunc);
+      }).toThrow();
+      expect(thenFunc).toHaveBeenLastCalledWith();
+    });
+  });
+
+  describe('asynchronous makeValue functions', () => {
+    it('should result in then function being called asynchronously', async () => {
+      const thenFunc = jest.fn();
+      const promise = makeValueThenDo(async () => {
+        await sleep(100);
+
+        return 1;
+      }, thenFunc);
+      expect(thenFunc).not.toHaveBeenCalled();
+      await promise;
+      expect(thenFunc).toHaveBeenLastCalledWith(1);
+    });
+
+    it('that throw should result in then function being called asynchronously but without a value', async () => {
+      const thenFunc = jest.fn();
+      const promise = expect(
+        makeValueThenDo(async (): Promise<void> => {
+          await sleep(100);
+
+          throw new Error();
+        }, thenFunc)
+      ).rejects.toThrow();
+      expect(thenFunc).not.toHaveBeenCalled();
+      await promise;
+      expect(thenFunc).toHaveBeenLastCalledWith();
+    });
+  });
+});

package/src/binding-utils/internal/make-value-then-do.ts

@@ -0,0 +1,37 @@
+import isPromise from 'is-promise';
+
+/**
+ * Runs a function to make a value and then runs a subsequent function.  The subsequent function is run even if an exception is thrown while
+ * making the value.  This efficiently handles value generation functions that return promises and that don't.
+ */
+export const makeValueThenDo = <T>(makeValue: () => Promise<T> | T, thenDo: (value?: T) => void): Promise<T> | T => {
+  let value: Promise<T> | T;
+  let makeValueSuccess = false;
+  try {
+    value = makeValue();
+    makeValueSuccess = true;
+  } finally {
+    if (!makeValueSuccess) {
+      thenDo();
+    }
+  }
+
+  if (isPromise(value)) {
+    return (async () => {
+      let awaitValueSuccess = false;
+      try {
+        const output = await value;
+        awaitValueSuccess = true;
+        thenDo(output);
+        return output;
+      } finally {
+        if (!awaitValueSuccess) {
+          thenDo();
+        }
+      }
+    })();
+  } else {
+    thenDo(value);
+    return value;
+  }
+};

package/src/binding-utils/lock-utils.ts

@@ -0,0 +1,50 @@
+import type { ReadonlyBinding } from '../binding/types/readonly-binding';
+import { makeValueThenDo } from './internal/make-value-then-do';
+
+/**
+ * Checks if any of the specified bindings have been locked.
+ *
+ * @param bindings - The bindings to check
+ *
+ * @returns `true` if any of the specified bindings are locked, `false` otherwise.
+ */
+export const areAnyBindingsLocked = (bindings: Array<ReadonlyBinding | undefined>) => {
+  for (const binding of bindings) {
+    if (binding?.isLocked() ?? false) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * Locks all the specified bindings and returns a function for unlocking them in reverse order.
+ *
+ * @param bindings - The bindings to be locked
+ *
+ * @returns a function to unlock all of the specified bindings, in reverse order
+ */
+export const lockAllBindings = (bindings: Array<ReadonlyBinding | undefined>) => {
+  const unlockers = bindings.map((binding) => binding?.lock()).reverse();
+
+  return () => {
+    for (const unlock of unlockers) {
+      unlock?.();
+    }
+  };
+};
+
+/**
+ * Locks the specified bindings until the functions result is resolved or rejected
+ *
+ * @param bindings - The bindings to be locked
+ * @param func - The function to run while the bindings are locked
+ *
+ * @returns The result of the specified function
+ */
+export const lockBindingsAndDo = <T>(bindings: Array<ReadonlyBinding | undefined>, func: () => Promise<T> | T): Promise<T> | T => {
+  const unlockAllBindings = lockAllBindings(bindings);
+
+  return makeValueThenDo(func, unlockAllBindings);
+};

package/src/binding-utils/modified-utils.ts

@@ -0,0 +1,31 @@
+import type { Binding } from '../binding/types/binding';
+import type { ReadonlyBinding } from '../binding/types/readonly-binding';
+
+/**
+ * Checks if any of the specified bindings have been modified.
+ *
+ * @param bindings - The bindings to check
+ *
+ * @returns `true` if any of the specified bindings are modified, `false` otherwise
+ */
+export const areAnyBindingsModified = (bindings: Array<ReadonlyBinding | undefined>) => {
+  for (const binding of bindings) {
+    if (binding?.isModified() ?? false) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * Marks all of the specified bindings as having been modified or not.
+ *
+ * @param bindings - The bindings to update
+ * @param newIsModified - The desired modified state for the specified bindings
+ */
+export const setAllBindingsModified = (bindings: Array<Binding | undefined>, newIsModified: boolean) => {
+  for (const binding of bindings) {
+    binding?.setIsModified(newIsModified);
+  }
+};

package/src/binding-utils/type-utils.ts

@@ -0,0 +1,9 @@
+import type { ReadonlyBinding } from '../binding/types/readonly-binding';
+
+/** Checks if the specified value is a binding */
+export const isBinding = (value: any): value is ReadonlyBinding =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  value !== null && typeof value === 'object' && 'isBinding' in value && value.isBinding === true;
+
+/** Returns a readonly binding if the specified value is a binding.  Otherwise, returns undefined */
+export const ifBinding = <T>(value: any): ReadonlyBinding<T> | undefined => (isBinding(value) ? (value as ReadonlyBinding<T>) : undefined);

package/src/components/BindingsConsumer/__tests__/basic-rendering.test.tsx

@@ -0,0 +1,75 @@
+import { jest } from '@jest/globals';
+import { waitFor } from '@testing-library/react';
+import type { ComponentType } from 'react';
+import React from 'react';
+
+import { runInDom } from '../../../__test_dependency__';
+import type { Binding } from '../../../binding/types/binding';
+import { useBinding } from '../../../binding/use-binding';
+import { BindingsConsumer } from '..';
+
+describe('BindingsConsumer', () => {
+  it('should work with undefined bindings', () =>
+    runInDom(({ onMount }) => {
+      const MyComponent: ComponentType = jest.fn(() => (
+        <BindingsConsumer bindings={undefined}>
+          {(values) => {
+            expect(values).toBeUndefined();
+            return <span />;
+          }}
+        </BindingsConsumer>
+      ));
+
+      onMount((rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+
+        expect(rootElement.innerHTML).toBe('<div><span></span></div>');
+      });
+
+      return <MyComponent />;
+    }));
+
+  it('initial render should work', () =>
+    runInDom(({ onMount }) => {
+      const MyComponent: ComponentType = jest.fn(() => {
+        const b = useBinding(() => 0, { id: 'test' });
+
+        return <BindingsConsumer bindings={{ b }}>{({ b }) => <span>{b}</span>}</BindingsConsumer>;
+      });
+
+      onMount((rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+
+        expect(rootElement.innerHTML).toBe('<div><span>0</span></div>');
+      });
+
+      return <MyComponent />;
+    }));
+
+  it('updating should rerender', () =>
+    runInDom(({ onMount }) => {
+      let b: Binding<number>;
+
+      const consumerRenderer = jest.fn(({ b }: { b: number }) => <span>{b}</span>);
+
+      const MyComponent: ComponentType = jest.fn(() => {
+        b = useBinding(() => 0, { id: 'test' });
+
+        return <BindingsConsumer bindings={{ b }}>{consumerRenderer}</BindingsConsumer>;
+      });
+
+      onMount(async (rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(1);
+        expect(rootElement.innerHTML).toBe('<div><span>0</span></div>');
+
+        b.set(1);
+        await waitFor(() => expect(consumerRenderer).toHaveBeenCalledTimes(2));
+
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(rootElement.innerHTML).toBe('<div><span>1</span></div>');
+      });
+
+      return <MyComponent />;
+    }));
+});

package/src/components/BindingsConsumer/__tests__/debounced-rendering.test.tsx

@@ -0,0 +1,93 @@
+import { jest } from '@jest/globals';
+import { waitFor } from '@testing-library/react';
+import type { ComponentType } from 'react';
+import React from 'react';
+
+import { runInDom } from '../../../__test_dependency__';
+import type { Binding } from '../../../binding/types/binding';
+import { useBinding } from '../../../binding/use-binding';
+import { BindingsConsumer } from '..';
+
+describe('BindingsConsumer', () => {
+  it('updating multiple times should rerender but debounced', () =>
+    runInDom(({ onMount }) => {
+      let b: Binding<number>;
+
+      const consumerRenderer = jest.fn(({ b }: { b: number }) => <span>{b}</span>);
+
+      const MyComponent: ComponentType = jest.fn(() => {
+        b = useBinding(() => 0, { id: 'test' });
+
+        return (
+          <BindingsConsumer bindings={{ b }} limitMSec={100}>
+            {consumerRenderer}
+          </BindingsConsumer>
+        );
+      });
+
+      onMount(async (rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(1);
+        expect(rootElement.innerHTML).toBe('<div><span>0</span></div>');
+
+        for (let i = 1; i < 25; i += 1) {
+          b.set(i);
+
+          expect(MyComponent).toHaveBeenCalledTimes(1);
+          expect(consumerRenderer).toHaveBeenCalledTimes(1);
+          expect(rootElement.innerHTML).toBe('<div><span>0</span></div>');
+        }
+
+        await waitFor(() => expect(rootElement.innerHTML).toBe('<div><span>24</span></div>'));
+
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(2);
+      });
+
+      return <MyComponent />;
+    }));
+
+  it('leading-and-trailing debounced rendering should update right away on the first change and then after changes have stopped', () =>
+    runInDom(({ onMount }) => {
+      let b: Binding<number>;
+
+      const consumerRenderer = jest.fn(({ b }: { b: number }) => <span>{b}</span>);
+
+      const MyComponent: ComponentType = jest.fn(() => {
+        b = useBinding(() => 0, { id: 'test' });
+
+        return (
+          <BindingsConsumer bindings={{ b }} limitMode="leading-and-trailing" limitMSec={100}>
+            {consumerRenderer}
+          </BindingsConsumer>
+        );
+      });
+
+      onMount(async (rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(1);
+        expect(rootElement.innerHTML).toBe('<div><span>0</span></div>');
+
+        b.set(1);
+        await waitFor(() => expect(rootElement.innerHTML).toBe('<div><span>1</span></div>'));
+
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(2);
+
+        for (let i = 2; i < 25; i += 1) {
+          b.set(i);
+
+          expect(MyComponent).toHaveBeenCalledTimes(1);
+          expect(consumerRenderer).toHaveBeenCalledTimes(2);
+          expect(rootElement.innerHTML).toBe('<div><span>1</span></div>');
+        }
+
+        await waitFor(() => expect(rootElement.innerHTML).toBe('<div><span>24</span></div>'));
+
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(3);
+      });
+
+      return <MyComponent />;
+    }));
+});

package/src/components/BindingsConsumer/__tests__/multiple-bindings.test.tsx

@@ -0,0 +1,94 @@
+import { jest } from '@jest/globals';
+import { waitFor } from '@testing-library/react';
+import type { ComponentType } from 'react';
+import React from 'react';
+
+import { runInDom } from '../../../__test_dependency__';
+import { useBinding } from '../../../binding/use-binding';
+import { BindingsConsumer } from '..';
+
+describe('BindingsConsumer', () => {
+  it('multiple bindings initial render should work', () =>
+    runInDom(({ onMount }) => {
+      const MyComponent: ComponentType = jest.fn(() => {
+        const b1 = useBinding(() => 0, { id: 'test1' });
+        const b2 = useBinding(() => 0, { id: 'test2' });
+
+        return (
+          <BindingsConsumer bindings={{ b1, b2 }}>
+            {({ b1, b2 }) => (
+              <span>
+                {b1}-{b2}
+              </span>
+            )}
+          </BindingsConsumer>
+        );
+      });
+
+      onMount((rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+
+        expect(rootElement.innerHTML).toBe('<div><span>0-0</span></div>');
+      });
+
+      return <MyComponent />;
+    }));
+
+  it('updating one should rerender', () =>
+    runInDom(({ onMount }) => {
+      const consumerRenderer = jest.fn(({ b1, b2 }: { b1: number; b2: number }) => (
+        <span>
+          {b1}-{b2}
+        </span>
+      ));
+
+      const b1 = useBinding(() => 0, { id: 'test1' });
+      const b2 = useBinding(() => 0, { id: 'test2' });
+
+      const MyComponent: ComponentType = jest.fn(() => <BindingsConsumer bindings={{ b1, b2 }}>{consumerRenderer}</BindingsConsumer>);
+
+      onMount(async (rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(1);
+        expect(rootElement.innerHTML).toBe('<div><span>0-0</span></div>');
+
+        b2.set(1);
+        await waitFor(() => expect(rootElement.innerHTML).toBe('<div><span>0-1</span></div>'));
+
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(2);
+      });
+
+      return <MyComponent />;
+    }));
+
+  it('quickly updating both should rerender, but just once', () =>
+    runInDom(({ onMount }) => {
+      const consumerRenderer = jest.fn(({ b1, b2 }: { b1: number; b2: number }) => (
+        <span>
+          {b1}-{b2}
+        </span>
+      ));
+
+      const b1 = useBinding(() => 0, { id: 'test1' });
+      const b2 = useBinding(() => 0, { id: 'test2' });
+
+      const MyComponent: ComponentType = jest.fn(() => <BindingsConsumer bindings={{ b1, b2 }}>{consumerRenderer}</BindingsConsumer>);
+
+      onMount(async (rootElement) => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(1);
+        expect(rootElement.innerHTML).toBe('<div><span>0-0</span></div>');
+
+        b1.set(1);
+        b2.set(2);
+
+        await waitFor(() => expect(rootElement.innerHTML).toBe('<div><span>1-2</span></div>'));
+
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(consumerRenderer).toHaveBeenCalledTimes(2);
+      });
+
+      return <MyComponent />;
+    }));
+});