std-react-bindings 0.0.1

package/src/__test_dependency__/run-in-dom.tsx

@@ -0,0 +1,46 @@
+/* istanbul ignore file */
+
+import { jest } from '@jest/globals';
+import { render } from '@testing-library/react';
+import type { ComponentType, ReactNode } from 'react';
+import React from 'react';
+
+type OnMountHandler = (rootElement: HTMLElement) => void | Promise<void>;
+type OnUnmountHandler = () => void | Promise<void>;
+
+interface Props {
+  onMount: (handler: OnMountHandler) => void;
+  onUnmount: (handler: OnUnmountHandler) => void;
+}
+
+export const runInDom = async <T = ReactNode | void,>(useFunc: (props: Props) => T) => {
+  const onMountHandlers: OnMountHandler[] = [];
+  let registerOnMount: ((handler: OnMountHandler) => void) | undefined = (handler: OnMountHandler) => {
+    onMountHandlers.push(handler);
+  };
+
+  const onUnmountHandlers: OnUnmountHandler[] = [];
+  let registerOnUnmount: ((handler: OnUnmountHandler) => void) | undefined = (handler: OnUnmountHandler) => {
+    onUnmountHandlers.push(handler);
+  };
+
+  const Component = jest.fn((props: Props) => useFunc(props) ?? null) as ComponentType<Props>;
+
+  const root = render(<Component onMount={registerOnMount} onUnmount={registerOnUnmount} />);
+  registerOnMount = undefined;
+  registerOnUnmount = undefined;
+
+  expect(Component).toHaveBeenCalled();
+
+  for (const onMountHandler of onMountHandlers) {
+    await onMountHandler(root.baseElement);
+  }
+  onMountHandlers.length = 0;
+
+  root.unmount();
+
+  for (const onUnmountHandler of onUnmountHandlers) {
+    await onUnmountHandler();
+  }
+  onUnmountHandlers.length = 0;
+};

package/src/__test_dependency__/sleep.ts

@@ -0,0 +1,3 @@
+/* istanbul ignore file */
+
+export const sleep = async (durationMSec: number) => new Promise((resolve) => setTimeout(resolve, durationMSec));

package/src/bc/bc.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+
+import type { BindingDependencies } from '../binding/types/binding-dependencies';
+import type { BindingsConsumerRenderCallback } from '../components/BindingsConsumer';
+import { BindingsConsumer } from '../components/BindingsConsumer';
+
+/** Returns a BindingsConsumer JSX Element.  This is useful as a shorthand especially when passing BindingsConsumers as props of other
+ * components */
+export const BC = <DependenciesT extends BindingDependencies>(
+  bindings: DependenciesT,
+  children: BindingsConsumerRenderCallback<DependenciesT>
+) => <BindingsConsumer bindings={bindings}>{children}</BindingsConsumer>;

package/src/bc/exports.ts

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

package/src/binding/__tests__/make-binding.test.ts

@@ -0,0 +1,25 @@
+import { makeBinding } from '../make-binding';
+
+describe('makeBinding', () => {
+  it('basic use should work', () => {
+    const b = makeBinding(() => 0, { id: 'test' });
+    expect(b.get()).toBe(0);
+  });
+
+  it('added fields should work', () => {
+    const b = makeBinding(() => 0, {
+      id: 'test',
+      addFields: (b) => ({
+        isEven: () => b.get() % 2 === 0,
+        isOdd: () => b.get() % 2 === 1
+      })
+    });
+    expect(b.get()).toBe(0);
+    expect(b.isEven()).toBeTruthy();
+    expect(b.isOdd()).toBeFalsy();
+
+    b.set(1);
+    expect(b.isEven()).toBeFalsy();
+    expect(b.isOdd()).toBeTruthy();
+  });
+});

package/src/binding/__tests__/use-binding.test.tsx

@@ -0,0 +1,54 @@
+import { jest } from '@jest/globals';
+import { act, waitFor } from '@testing-library/react';
+import type { ComponentType } from 'react';
+import React, { useState } from 'react';
+
+import { runInDom } from '../../__test_dependency__';
+import { useBinding } from '../use-binding';
+
+describe('useBinding', () => {
+  it('basic use should work', () =>
+    runInDom(({ onMount }) => {
+      const MyComponent: ComponentType = jest.fn(() => {
+        const b = useBinding(() => 0, { id: 'test' });
+        return <>{b.get()}</>;
+      });
+
+      onMount(() => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+      });
+
+      return <MyComponent />;
+    }));
+
+  it('deps use should work', () =>
+    runInDom(({ onMount }) => {
+      let stateSetter: (value: number) => void;
+      let instanceNumber = 0;
+
+      const MyComponent: ComponentType = jest.fn(() => {
+        const [state, setState] = useState(0);
+        stateSetter = setState;
+
+        const b = useBinding(() => instanceNumber++, { id: 'test', deps: [state] });
+        return <>{b.get()}</>;
+      });
+
+      onMount(async () => {
+        expect(MyComponent).toHaveBeenCalledTimes(1);
+        expect(instanceNumber).toBe(1);
+
+        act(() => stateSetter(1));
+        await waitFor(() => expect(instanceNumber).toBe(2));
+
+        expect(MyComponent).toHaveBeenCalledTimes(2);
+
+        act(() => stateSetter(1)); // same state value again
+        await waitFor(() => expect(MyComponent).toHaveBeenCalledTimes(3));
+
+        expect(instanceNumber).toBe(2);
+      });
+
+      return <MyComponent />;
+    }));
+});

package/src/binding/exports.ts

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

package/src/binding/internal/DoubleLinkedList/__tests__/double-linked-list.test.ts

@@ -0,0 +1,134 @@
+import { DoubleLinkedList } from '..';
+
+describe('DoubleLinkedList', () => {
+  it('initializing with values should work', () => {
+    const list = new DoubleLinkedList<number>(1, 2, 3);
+    list.append(4);
+    list.append(5);
+    const node3 = list.append(6);
+    expect(list.getLength()).toEqual(6);
+    expect(list.getHead()?.value).toEqual(1);
+    expect(list.getTail()).toBe(node3);
+  });
+
+  it('appending should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node1 = list.append(1);
+    const node2 = list.append(2);
+    const node3 = list.append(3);
+    expect(list.getLength()).toEqual(3);
+    expect(list.getHead()).toBe(node1);
+    expect(list.getTail()).toBe(node3);
+    expect(node1.previousNode).toBeUndefined();
+    expect(node2.previousNode).toBe(node1);
+    expect(node3.previousNode).toBe(node2);
+    expect(node1.nextNode).toBe(node2);
+    expect(node2.nextNode).toBe(node3);
+    expect(node3.nextNode).toBeUndefined();
+  });
+
+  it('prepending should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node3 = list.prepend(3);
+    const node2 = list.prepend(2);
+    const node1 = list.prepend(1);
+    expect(list.getLength()).toEqual(3);
+    expect(list.getHead()).toBe(node1);
+    expect(list.getTail()).toBe(node3);
+    expect(node1.previousNode).toBeUndefined();
+    expect(node2.previousNode).toBe(node1);
+    expect(node3.previousNode).toBe(node2);
+    expect(node1.nextNode).toBe(node2);
+    expect(node2.nextNode).toBe(node3);
+    expect(node3.nextNode).toBeUndefined();
+  });
+
+  it('remove head should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node1 = list.append(1);
+    const node2 = list.append(2);
+    const node3 = list.append(3);
+    list.remove(node1);
+    expect(list.getLength()).toEqual(2);
+    expect(list.getHead()).toBe(node2);
+    expect(list.getTail()).toBe(node3);
+    expect(node1.previousNode).toBeUndefined();
+    expect(node2.previousNode).toBeUndefined();
+    expect(node3.previousNode).toBe(node2);
+    expect(node1.nextNode).toBeUndefined();
+    expect(node2.nextNode).toBe(node3);
+    expect(node3.nextNode).toBeUndefined();
+  });
+
+  it('remove tail should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node1 = list.append(1);
+    const node2 = list.append(2);
+    const node3 = list.append(3);
+    list.remove(node3);
+    expect(list.getLength()).toEqual(2);
+    expect(list.getHead()).toBe(node1);
+    expect(list.getTail()).toBe(node2);
+    expect(node1.previousNode).toBeUndefined();
+    expect(node2.previousNode).toBe(node1);
+    expect(node3.previousNode).toBeUndefined();
+    expect(node1.nextNode).toBe(node2);
+    expect(node2.nextNode).toBeUndefined();
+    expect(node3.nextNode).toBeUndefined();
+  });
+
+  it('remove middle should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node1 = list.append(1);
+    const node2 = list.append(2);
+    const node3 = list.append(3);
+    list.remove(node2);
+    expect(list.getLength()).toEqual(2);
+    expect(list.getHead()).toBe(node1);
+    expect(list.getTail()).toBe(node3);
+    expect(node1.previousNode).toBeUndefined();
+    expect(node2.previousNode).toBeUndefined();
+    expect(node3.previousNode).toBe(node1);
+    expect(node1.nextNode).toBe(node3);
+    expect(node2.nextNode).toBeUndefined();
+    expect(node3.nextNode).toBeUndefined();
+  });
+
+  it('remove all should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node1 = list.append(1);
+    const node2 = list.append(2);
+    const node3 = list.append(3);
+    list.remove(node2);
+    list.remove(node3);
+    list.remove(node1);
+    expect(list.getLength()).toEqual(0);
+    expect(list.getHead()).toBeUndefined();
+    expect(list.getTail()).toBeUndefined();
+  });
+
+  it('removing a node twice should work', () => {
+    const list = new DoubleLinkedList<number>();
+    const node1 = list.append(1);
+    const node2 = list.append(2);
+    const node3 = list.append(3);
+    list.remove(node2);
+    list.remove(node2);
+    list.remove(node3);
+    list.remove(node1);
+    expect(list.getLength()).toEqual(0);
+    expect(list.getHead()).toBeUndefined();
+    expect(list.getTail()).toBeUndefined();
+  });
+
+  it('clear should work', () => {
+    const list = new DoubleLinkedList<number>();
+    list.append(1);
+    list.append(2);
+    list.append(3);
+    list.clear();
+    expect(list.getLength()).toEqual(0);
+    expect(list.getHead()).toBeUndefined();
+    expect(list.getTail()).toBeUndefined();
+  });
+});

package/src/binding/internal/DoubleLinkedList/index.ts

@@ -0,0 +1,128 @@
+export class DoubleLinkedList<ItemT> {
+  /** This is set to `undefined` on any list mutations and rebuilt when `toArray` is called if needed */
+  private allValues: Readonly<ItemT[]> | undefined;
+
+  private firstNode: DoubleLinkedListNode<ItemT> | undefined;
+  private lastNode: DoubleLinkedListNode<ItemT> | undefined;
+  private length = 0;
+
+  public constructor(...items: ItemT[]) {
+    for (const item of items) {
+      this.append(item);
+    }
+  }
+
+  public readonly getLength = () => this.length;
+  public readonly isEmpty = () => this.firstNode === undefined;
+
+  public readonly append = (item: ItemT): Readonly<DoubleLinkedListNode<ItemT>> => {
+    const newNode = new DoubleLinkedListNode<ItemT>(this, item);
+
+    if (this.firstNode === undefined) {
+      this.firstNode = newNode;
+      this.lastNode = newNode;
+    } else {
+      newNode.previousNode = this.lastNode;
+      this.lastNode!.nextNode = newNode;
+      this.lastNode = newNode;
+    }
+
+    this.allValues = undefined;
+    this.length += 1;
+
+    return newNode;
+  };
+
+  public readonly prepend = (item: ItemT): Readonly<DoubleLinkedListNode<ItemT>> => {
+    const newNode = new DoubleLinkedListNode<ItemT>(this, item);
+
+    if (this.firstNode === undefined) {
+      this.firstNode = newNode;
+      this.lastNode = newNode;
+    } else {
+      newNode.nextNode = this.firstNode;
+      this.firstNode!.previousNode = newNode;
+      this.firstNode = newNode;
+    }
+
+    this.allValues = undefined;
+    this.length += 1;
+
+    return newNode;
+  };
+
+  public readonly clear = () => {
+    while (this.firstNode !== undefined) {
+      this.remove(this.firstNode);
+    }
+  };
+
+  public readonly getHead = (): Readonly<DoubleLinkedListNode<ItemT>> | undefined => this.firstNode;
+  public readonly getTail = (): Readonly<DoubleLinkedListNode<ItemT>> | undefined => this.lastNode;
+
+  public readonly toArray = (): Readonly<ItemT[]> => {
+    if (this.allValues !== undefined) {
+      return this.allValues;
+    }
+
+    const output: ItemT[] = [];
+    let cursor = this.firstNode;
+    while (cursor !== undefined) {
+      output.push(cursor.value);
+      cursor = cursor.nextNode;
+    }
+
+    this.allValues = Object.freeze(output);
+
+    return output;
+  };
+
+  public readonly remove = (node: DoubleLinkedListNode<ItemT>) => {
+    if (node.list !== this) {
+      return false; // Nothing to do -- wrong list
+    }
+
+    if (node === this.firstNode) {
+      // Removing head
+
+      this.firstNode = node.nextNode;
+      if (this.firstNode !== undefined) {
+        this.firstNode.previousNode = undefined;
+      } else {
+        this.lastNode = undefined;
+      }
+    } else if (node === this.lastNode) {
+      // Removing tail
+
+      this.lastNode = node.previousNode;
+      if (this.lastNode !== undefined) {
+        this.lastNode.nextNode = undefined;
+      } else {
+        this.firstNode = undefined;
+      }
+    } else {
+      // Removing middle
+
+      node.previousNode!.nextNode = node.nextNode;
+      node.nextNode!.previousNode = node.previousNode;
+    }
+
+    node.previousNode = undefined;
+    node.nextNode = undefined;
+    node.list = undefined;
+
+    this.allValues = undefined;
+    this.length -= 1;
+
+    return true;
+  };
+}
+
+export class DoubleLinkedListNode<ItemT> {
+  constructor(
+    public list: DoubleLinkedList<ItemT> | undefined,
+    public readonly value: ItemT,
+    public previousNode?: DoubleLinkedListNode<ItemT>,
+    public nextNode?: DoubleLinkedListNode<ItemT>
+  ) {}
+}

package/src/binding/internal/__tests__/custom-value-comparison.test.ts

@@ -0,0 +1,31 @@
+import { jest } from '@jest/globals';
+
+import { BindingImpl } from '../binding-impl';
+
+describe('BindingImpl', () => {
+  describe('with custom value comparison', () => {
+    const changeListener = jest.fn();
+
+    beforeEach(() => {
+      changeListener.mockReset();
+    });
+
+    it('getting after setting a new value should return new value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test', detectChanges: true, areEqual: (a, b) => a % 2 === b % 2 });
+      b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+    });
+
+    it('getting after setting a different but "equivalent" value should return the original value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test', detectChanges: true, areEqual: (a, b) => a % 2 === b % 2 });
+      b.addChangeListener(changeListener);
+
+      b.set(2);
+      expect(changeListener).not.toHaveBeenCalled();
+      expect(b.get()).toEqual(0);
+    });
+  });
+});

package/src/binding/internal/__tests__/default-settings.test.ts

@@ -0,0 +1,92 @@
+import { jest } from '@jest/globals';
+
+import { BindingImpl } from '../binding-impl';
+
+describe('BindingImpl', () => {
+  describe('with default settings', () => {
+    const changeListener = jest.fn();
+
+    beforeEach(() => {
+      changeListener.mockReset();
+    });
+
+    it('getting unmodified should return initial value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      expect(b.get()).toEqual(0);
+
+      expect(changeListener).not.toHaveBeenCalled();
+    });
+
+    it('getting after setting should return new value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+    });
+
+    it('setting after disconnecting change listener should not trigger the change listener', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      const removeChangeListener = b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+
+      removeChangeListener();
+      b.set(2);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(2);
+    });
+
+    it('removing a change listener twice should work', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      const removeChangeListener = b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+
+      removeChangeListener();
+      removeChangeListener();
+      b.set(2);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(2);
+    });
+
+    it('setting unmodified should set modified state', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      expect(b.isModified()).toBeFalsy();
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeTruthy();
+    });
+
+    it('manually setting the modified state should work', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+
+      expect(b.isModified()).toBeFalsy();
+      b.set(1);
+      expect(b.isModified()).toBeTruthy();
+      b.setIsModified(false);
+      expect(b.isModified()).toBeFalsy();
+    });
+
+    it('manually setting the modified state to the same value it already is should do nothing', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+
+      expect(b.isModified()).toBeFalsy();
+      b.set(1);
+      expect(b.isModified()).toBeTruthy();
+      b.setIsModified(false);
+      expect(b.isModified()).toBeFalsy();
+      b.setIsModified(false);
+      expect(b.isModified()).toBeFalsy();
+    });
+  });
+});

package/src/binding/internal/__tests__/default-value-comparison.test.ts

@@ -0,0 +1,55 @@
+import { jest } from '@jest/globals';
+
+import { BindingImpl } from '../binding-impl';
+
+describe('BindingImpl', () => {
+  describe('with default value comparison', () => {
+    const changeListener = jest.fn();
+
+    beforeEach(() => {
+      changeListener.mockReset();
+    });
+
+    describe('with simple types', () => {
+      it('getting after setting a new value should return new value', () => {
+        const b = new BindingImpl(() => 0, { id: 'test', detectChanges: true });
+        b.addChangeListener(changeListener);
+
+        b.set(1);
+        expect(changeListener).toHaveBeenCalledTimes(1);
+        expect(b.get()).toEqual(1);
+      });
+
+      it('getting after setting an equivalent value should return the original value', () => {
+        const b = new BindingImpl(() => 0, { id: 'test', detectChanges: true });
+        b.addChangeListener(changeListener);
+
+        b.set(0);
+        expect(changeListener).not.toHaveBeenCalled();
+        expect(b.get()).toEqual(0);
+      });
+    });
+
+    describe('with complex types', () => {
+      it('getting after setting a new value should return new value', () => {
+        const b = new BindingImpl(() => ({ x: 0 }), { id: 'test', detectChanges: true });
+        b.addChangeListener(changeListener);
+
+        b.set({ x: 1 });
+        expect(changeListener).toHaveBeenCalledTimes(1);
+        expect(b.get()).toMatchObject({ x: 1 });
+      });
+
+      it('getting after setting an equivalent value should return the original value', () => {
+        const originalInstance = { x: 0 };
+        const b = new BindingImpl(() => originalInstance, { id: 'test', detectChanges: true });
+        b.addChangeListener(changeListener);
+
+        b.set({ x: 0 });
+        expect(changeListener).not.toHaveBeenCalled();
+        expect(b.get()).toMatchObject({ x: 0 });
+        expect(b.get()).toBe(originalInstance);
+      });
+    });
+  });
+});