std-react-bindings 0.0.1

package/src/binding/internal/__tests__/locking.test.ts

@@ -0,0 +1,111 @@
+import { jest } from '@jest/globals';
+
+import { BindingImpl } from '../binding-impl';
+
+describe('BindingImpl', () => {
+  describe('with default settings', () => {
+    const changeListener = jest.fn();
+
+    beforeEach(() => {
+      changeListener.mockReset();
+    });
+
+    it('setting locked should do nothing until unlocked, after which it should update value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      const unlock = b.lock();
+      b.set(1);
+      expect(changeListener).not.toHaveBeenCalled();
+      expect(b.isModified()).toBeFalsy();
+      expect(b.get()).toEqual(0);
+      unlock();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(1);
+    });
+
+    it('setting locked twice should do nothing until unlocked, after which it should update with the most recent value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      const unlock = b.lock();
+      b.set(1);
+      expect(changeListener).not.toHaveBeenCalled();
+      expect(b.isModified()).toBeFalsy();
+      expect(b.get()).toEqual(0);
+      b.set(2);
+      expect(changeListener).not.toHaveBeenCalled();
+      expect(b.isModified()).toBeFalsy();
+      expect(b.get()).toEqual(0);
+      unlock();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(2);
+    });
+
+    it('setting locked then resetting should do nothing until unlocked, after which it should reset', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(1);
+
+      const unlock = b.lock();
+      b.set(2);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      b.reset();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+      unlock();
+      expect(changeListener).toHaveBeenCalledTimes(2);
+      expect(b.isModified()).toBeFalsy();
+      expect(b.get()).toEqual(0);
+    });
+
+    it('setting locked then resetting then setting again should do nothing until unlocked, after which it should reset and then update the most recent value', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(1);
+
+      const unlock = b.lock();
+      b.set(2);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      b.reset();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      b.set(3);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+      unlock();
+      expect(changeListener).toHaveBeenCalledTimes(3);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(3);
+    });
+
+    it('unlocking the same lock twice should work', () => {
+      const b = new BindingImpl(() => 0, { id: 'test' });
+      b.addChangeListener(changeListener);
+
+      b.set(1);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(1);
+
+      const unlock = b.lock();
+      b.set(2);
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual(1);
+      unlock();
+      unlock();
+      expect(changeListener).toHaveBeenCalledTimes(2);
+      expect(b.isModified()).toBeTruthy();
+      expect(b.get()).toEqual(2);
+    });
+  });
+});

package/src/binding/internal/__tests__/transformed.test.ts

@@ -0,0 +1,48 @@
+import { jest } from '@jest/globals';
+
+import { BindingImpl } from '../binding-impl';
+
+describe('BindingImpl', () => {
+  describe('with set value transformer', () => {
+    const changeListener = jest.fn();
+
+    beforeEach(() => {
+      changeListener.mockReset();
+    });
+
+    it('getting after setting a new value should return the transformed new value', () => {
+      const b = new BindingImpl(() => 'hello', { id: 'test', setValueTransformer: (v) => v.toLocaleLowerCase() });
+      b.addChangeListener(changeListener);
+
+      b.set('WORLD');
+      expect(b.isModified()).toBeTruthy();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual('world');
+    });
+
+    it('getting after setting a new value using setRaw should return the unmodified new value', () => {
+      const b = new BindingImpl(() => 'hello', { id: 'test', setValueTransformer: (v) => v.toLocaleLowerCase() });
+      b.addChangeListener(changeListener);
+
+      b.setRaw('WORLD');
+      expect(b.isModified()).toBeFalsy();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.get()).toEqual('WORLD');
+    });
+
+    it('setting locked using setRaw should do nothing until unlocked, after which it should update value without transformation', () => {
+      const b = new BindingImpl(() => 'hello', { id: 'test', setValueTransformer: (v) => v.toLocaleLowerCase() });
+      b.addChangeListener(changeListener);
+
+      const unlock = b.lock();
+      b.setRaw('WORLD');
+      expect(changeListener).not.toHaveBeenCalled();
+      expect(b.isModified()).toBeFalsy();
+      expect(b.get()).toEqual('hello');
+      unlock();
+      expect(changeListener).toHaveBeenCalledTimes(1);
+      expect(b.isModified()).toBeFalsy();
+      expect(b.get()).toEqual('WORLD');
+    });
+  });
+});

package/src/binding/internal/binding-impl.ts

@@ -0,0 +1,253 @@
+import { areEqual as globalAreEqual } from '../../config/are-equal';
+import { getLogger, isSpecialLoggingEnabledFor } from '../../config/logging';
+import { getStatsHandler } from '../../config/stats-handler';
+import { makeUID } from '../../internal-utils/uid';
+import type { Binding } from '../types/binding';
+import type { BindingConstructorArgs } from '../types/binding-args';
+import type { BindingInitializer } from '../types/binding-initializer';
+import type { ChangeListener } from '../types/change-listener';
+import type { SetValueTransformer } from '../types/set-value-transformer';
+import { LOCK_DURATION_WARNING_INTERVAL_MSEC } from './consts';
+import type { DoubleLinkedListNode } from './DoubleLinkedList';
+import { DoubleLinkedList } from './DoubleLinkedList';
+
+/** A pending update on a binding */
+type PendingUpdate<GetType = any> =
+  | { type: 'set-raw'; value: GetType }
+  | { type: 'set'; value: GetType }
+  | { type: 'reset'; value?: undefined };
+
+/** The standard implementation of a read-write binding */
+export class BindingImpl<GetType = any> implements Binding<GetType> {
+  // Public Fields
+
+  public readonly isBinding = true;
+  public readonly id: string;
+  public readonly uid = makeUID();
+
+  public readonly setValueTransformer: SetValueTransformer<GetType> | undefined;
+
+  // Private Fields
+
+  /** The stored value of the binding */
+  private value_: GetType;
+
+  /** An ID updated every time the value is changed.  This value is unique to this runtime. */
+  private changeUid_ = this.uid; // Using the binding's uid as the initial change ID for convenience
+  /** Registered change listeners */
+  private onChangeListeners_?: DoubleLinkedList<ChangeListener>;
+
+  /**
+   * A flag indicating whether or not this binding was modified.  This is initially `false` when the binding is created and set to `true`
+   * when `set` is called (even if the underlying value doesn't actually change).
+   *
+   * This can also be set manually using `setIsModified`.
+   */
+  private isModified_ = false;
+
+  /** This binding is considered to be locked if `> 0` */
+  private lockedCount_ = 0;
+  /**
+   * We keep track of the most-recent mutating call made while this binding is locked.  When it becomes unlocked, we apply the requested
+   * change.
+   */
+  private pending_: PendingUpdate<GetType> | undefined = undefined;
+  /**
+   * In addition to tracking the most-recent mutating call made while this binding is locked, we also track if any of those mutating calls
+   * were resets.  If they were, when this binding becomes unlocked, we first reset and then apply the pending update.
+   */
+  private hasPendingReset_ = false;
+
+  /** The value equality checker function */
+  private areEqual_?: (a: GetType, b: GetType) => boolean;
+  /** If `true`, `areEqual_` (or the default) is used to determine if the value has changed */
+  private detectChanges_: boolean;
+
+  /** The initializer function, which can be used to reset the binding */
+  private initializer_: BindingInitializer<GetType>;
+
+  /**
+   * @param initializer - A function called to initialize this binding's value, which can also be called to reset its value.
+   * @param args - Additional arguments for configuring this binding.
+   */
+  constructor(initializer: BindingInitializer<GetType>, args: BindingConstructorArgs<GetType>) {
+    const theInitialValue = initializer(false);
+
+    this.id = args.id;
+    this.value_ = theInitialValue;
+
+    this.setValueTransformer = args.setValueTransformer;
+
+    this.initializer_ = initializer;
+
+    this.areEqual_ = args.areEqual;
+    this.detectChanges_ = args.detectChanges ?? false;
+  }
+
+  // Getters
+
+  public readonly get = () => this.value_;
+
+  public readonly getChangeUid = () => this.changeUid_;
+
+  // Setters
+
+  public readonly reset = () => {
+    if (this.lockedCount_ > 0) {
+      getLogger().debug?.(
+        `Attempted to change locked binding ${this.id}.  The most recently set value will be restored once this binding is unlocked`
+      );
+      this.pending_ = { type: 'reset' };
+      this.hasPendingReset_ = true;
+
+      return;
+    }
+
+    this.setRaw(this.initializer_(true));
+    this.setIsModified(false);
+  };
+
+  public readonly setRaw = (newValue: GetType) => {
+    if (this.lockedCount_ > 0) {
+      getLogger().debug?.(
+        `Attempted to change locked binding ${this.id}.  The most recently set value will be restored once this binding is unlocked`
+      );
+      this.pending_ = { type: 'set-raw', value: newValue };
+      return;
+    }
+
+    if (this.detectChanges_) {
+      const shouldChangeValue = !(this.areEqual_ ?? globalAreEqual)(this.value_, newValue);
+      if (!shouldChangeValue) {
+        return; // No change
+      }
+    }
+
+    const startMSec = performance.now();
+
+    this.value_ = newValue;
+    this.changeUid_ = makeUID();
+
+    const numListeners = this.triggerChangeListeners();
+
+    getStatsHandler().trackBindingDidSetRaw?.({
+      binding: this,
+      durationMSec: performance.now() - startMSec,
+      numListeners
+    });
+  };
+
+  public readonly set = (newValue: GetType) => {
+    if (this.lockedCount_ > 0) {
+      getLogger().debug?.(
+        `Attempted to change locked binding ${this.id}.  The most recently set value will be restored once this binding is unlocked`
+      );
+      this.pending_ = { type: 'set', value: newValue };
+      return;
+    }
+
+    this.isModified_ = true;
+    this.setRaw(this.setValueTransformer !== undefined ? this.setValueTransformer(newValue, this) : newValue);
+  };
+
+  // Modified
+
+  public readonly isModified = () => this.isModified_;
+
+  public readonly setIsModified = (newIsModified: boolean) => {
+    this.isModified_ = newIsModified;
+  };
+
+  // Locked
+
+  public readonly isLocked = () => this.lockedCount_ > 0;
+
+  public readonly lock = () => {
+    this.lockedCount_ += 1;
+
+    const shouldLogBindingLockDurationWarnings = isSpecialLoggingEnabledFor('binding-lock-duration-warnings');
+    const warningTimeout: ReturnType<typeof setTimeout> | undefined = shouldLogBindingLockDurationWarnings
+      ? setTimeout(() => {
+          getLogger().debug?.(
+            `A lock for binding ${this.id} wasn't released after more than ${LOCK_DURATION_WARNING_INTERVAL_MSEC / 1000} seconds`
+          );
+        }, LOCK_DURATION_WARNING_INTERVAL_MSEC)
+      : undefined;
+
+    let wasUnlocked = false;
+    return () => {
+      if (wasUnlocked) {
+        getLogger().debug?.(`A lock for binding ${this.id} was released more than once`);
+        return;
+      }
+      wasUnlocked = true;
+
+      if (warningTimeout !== undefined) {
+        clearTimeout(warningTimeout);
+      }
+
+      this.lockedCount_ -= 1;
+
+      // Restoring any pending values that were set while locked (mostly for bindings with memories)
+      if (this.lockedCount_ === 0 && this.pending_ !== undefined) {
+        const hasPendingReset = this.hasPendingReset_;
+        this.hasPendingReset_ = false;
+
+        const pending = this.pending_;
+        this.pending_ = undefined;
+
+        if (hasPendingReset) {
+          this.reset();
+        }
+
+        switch (pending.type) {
+          case 'set':
+            this.set(pending.value);
+            break;
+          case 'set-raw':
+            this.setRaw(pending.value);
+            break;
+          case 'reset':
+            // Nothing to do here, handled above
+            break;
+        }
+      }
+    };
+  };
+
+  // Change Listener
+
+  public readonly addChangeListener = (listener: ChangeListener) => {
+    getStatsHandler().trackBindingDidAddChangeListener?.({ binding: this });
+
+    if (this.onChangeListeners_ === undefined) {
+      this.onChangeListeners_ = new DoubleLinkedList<ChangeListener>();
+    }
+    let newNode: Readonly<DoubleLinkedListNode<ChangeListener>> | undefined = this.onChangeListeners_.append(listener);
+
+    // Returning function that can be used to remove the same change listener;
+    return () => {
+      if (newNode === undefined) {
+        getLogger().debug?.(`A change listener for binding ${this.id} was removed more than once`);
+        return;
+      }
+
+      getStatsHandler().trackBindingDidRemoveChangeListener?.({ binding: this });
+      this.onChangeListeners_!.remove(newNode);
+      newNode = undefined;
+    };
+  };
+
+  public readonly triggerChangeListeners = () => {
+    if (this.onChangeListeners_ === undefined) {
+      return 0;
+    }
+
+    const listeners = this.onChangeListeners_.toArray();
+    for (const listener of listeners) {
+      listener();
+    }
+
+    return listeners?.length;
+  };
+}

package/src/binding/internal/consts.ts

@@ -0,0 +1,2 @@
+/** The duration after which a warning will be logged if a lock hasn't been released */
+export const LOCK_DURATION_WARNING_INTERVAL_MSEC = 10 * 1000; // 10 seconds

package/src/binding/make-binding.ts

@@ -0,0 +1,26 @@
+import { getStatsHandler } from '../config/stats-handler';
+import { getTypedKeys } from '../internal-utils/get-typed-keys';
+import type { EmptyObject } from '../types/empty';
+import { BindingImpl } from './internal/binding-impl';
+import type { Binding } from './types/binding';
+import type { MakeBindingArgs } from './types/binding-args';
+import type { BindingInitializer } from './types/binding-initializer';
+
+/** Makes a binding without using any React contexts. */
+export const makeBinding = <GetType = any, ExtraFieldsT extends object = EmptyObject>(
+  initialValue: BindingInitializer<GetType>,
+  args: MakeBindingArgs<GetType, ExtraFieldsT>
+): Binding<GetType> & ExtraFieldsT => {
+  const output = new BindingImpl<GetType>(initialValue, args) as unknown as Binding<GetType> & ExtraFieldsT;
+  const extraFields = args.addFields?.(output);
+  if (extraFields !== undefined) {
+    for (const key of getTypedKeys(extraFields)) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      output[key] = extraFields[key] as any;
+    }
+  }
+
+  getStatsHandler().trackDidMakeBinding?.({ binding: output });
+
+  return output;
+};

package/src/binding/types/binding-args.ts

@@ -0,0 +1,49 @@
+import type { DependencyList } from 'react';
+
+import type { EmptyObject } from '../../types/empty';
+import type { Binding } from './binding';
+import type { SetValueTransformer } from './set-value-transformer';
+
+/** Post-initializer arguments used to configure bindings */
+export interface BindingConstructorArgs<GetType = any> {
+  /** A technical, but human-readable ID, which isn't guaranteed to be unique */
+  id: string;
+
+  /**
+   * A transformer function called prior to storing the value when using the `set` method
+   *
+   * @param newValue - The proposed new value
+   * @param thisBinding - The binding being updated
+   *
+   * @returns The transformed value to set the binding to
+   */
+  setValueTransformer?: SetValueTransformer<GetType>;
+
+  /**
+   * If specified, overrides the function used to compare values
+   *
+   * @defaultValue `_.isEqual`, which can be globally overridden using `setAreEqual`
+   */
+  areEqual?: (a: GetType, b: GetType) => boolean;
+  /**
+   * - If `true` – `areEqual` is used to compare the old and new values when `set`/`setRaw` are called.  If the values are equal, the
+   * binding 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 values aren't compared when `set`/`setRaw` are called.  The binding will always be changed and listeners
+   * will always be notified.
+   *
+   * @defaultValue `false`
+   */
+  detectChanges?: boolean;
+}
+
+/** The post-initializer arguments that are passed to `makeBinding` */
+export interface MakeBindingArgs<GetType = any, ExtraFieldsT extends object = EmptyObject> extends BindingConstructorArgs<GetType> {
+  /** Use to support injecting additional fields into bindings */
+  addFields?: (thisBinding: Binding<GetType>) => ExtraFieldsT;
+}
+
+/** The post-initializer arguments that are passed to `useBinding` */
+export interface UseBindingArgs<GetType = any, ExtraFieldsT extends object = EmptyObject> extends MakeBindingArgs<GetType, ExtraFieldsT> {
+  /** Hook dependencies */
+  deps?: DependencyList;
+}

package/src/binding/types/binding-dependencies.ts

@@ -0,0 +1,7 @@
+import type { ReadonlyBinding } from './readonly-binding';
+
+export type BindingArrayDependencies = Array<ReadonlyBinding | undefined>;
+
+export type NamedBindingDependencies = Record<string, ReadonlyBinding | undefined>;
+
+export type BindingDependencies = ReadonlyBinding | BindingArrayDependencies | NamedBindingDependencies | undefined;

package/src/binding/types/binding-initializer.ts

@@ -0,0 +1,2 @@
+/** A function called to initialize a binding's value, which can also be called to reset its value. */
+export type BindingInitializer<GetType> = (isReset: boolean) => GetType;

package/src/binding/types/binding.ts

@@ -0,0 +1,25 @@
+import type { ReadonlyBinding } from './readonly-binding';
+import type { SetValueTransformer } from './set-value-transformer';
+
+/**
+ * A binding is a stored piece of data that notifies registered listeners when changed.
+ *
+ * @see `useBinding`
+ */
+export interface Binding<GetType = any> extends ReadonlyBinding<GetType> {
+  /** Resets the binding back to its initial value and marks the binding as non-modified. */
+  readonly reset: () => void;
+  /** Sets the value, using the result of `setValueTransformer` if set, and then marks the binding as modified. */
+  readonly set: (newValue: GetType) => void;
+  /** Sets the internal value without transforming or marking as changed.  Don't normally use this! */
+  readonly setRaw: (newValue: GetType) => void;
+
+  /** Sets the binding as having been modified or not */
+  readonly setIsModified: (isModified: boolean) => void;
+
+  /** If set, a function to transform the value before it's stored */
+  readonly setValueTransformer?: SetValueTransformer<GetType>;
+
+  /** Forcibly triggers the change listeners.  Don't normally use this! */
+  readonly triggerChangeListeners: () => void;
+}

package/src/binding/types/change-listener.ts

@@ -0,0 +1,5 @@
+/** Called when a change is made */
+export type ChangeListener = () => void;
+
+/** Call to remove a change listener */
+export type ChangeListenerRemover = () => void;

package/src/binding/types/exports.ts

@@ -0,0 +1,11 @@
+export * from './binding';
+export * from './binding-args';
+export * from './binding-dependencies';
+export * from './binding-initializer';
+export * from './change-listener';
+export * from './infer-binding-value-types';
+export * from './infer-bindings-array-value-types';
+export * from './infer-named-binding-value-types';
+export * from './inference';
+export * from './readonly-binding';
+export * from './set-value-transformer';

package/src/binding/types/infer-binding-value-types.ts

@@ -0,0 +1,14 @@
+import type { BindingArrayDependencies, BindingDependencies, NamedBindingDependencies } from './binding-dependencies';
+import type { InferBindingsArrayValueTypes } from './infer-bindings-array-value-types';
+import type { InferNamedBindingsValueTypes } from './infer-named-binding-value-types';
+import type { InferBindingGetType } from './inference';
+import type { ReadonlyBinding } from './readonly-binding';
+
+/** Infers the values of either a single binding, bindings in an array or tuple, or a record with binding values */
+export type InferBindingValueTypes<DependenciesT extends BindingDependencies> = DependenciesT extends ReadonlyBinding
+  ? InferBindingGetType<DependenciesT>
+  : DependenciesT extends NamedBindingDependencies
+  ? InferNamedBindingsValueTypes<DependenciesT>
+  : DependenciesT extends BindingArrayDependencies
+  ? InferBindingsArrayValueTypes<DependenciesT>
+  : Record<string, never>;

package/src/binding/types/infer-bindings-array-value-types.ts

@@ -0,0 +1,12 @@
+import type { BindingArrayDependencies } from './binding-dependencies';
+import type { InferBindingGetType } from './inference';
+import type { ReadonlyBinding } from './readonly-binding';
+
+/** Infers the value types from bindings arrays */
+export type InferBindingsArrayValueTypes<BindingsArrayT extends BindingArrayDependencies> = {
+  [KeyT in keyof BindingsArrayT]: BindingsArrayT[KeyT] extends ReadonlyBinding
+    ? InferBindingGetType<BindingsArrayT[KeyT]>
+    : BindingsArrayT[KeyT] extends ReadonlyBinding | undefined
+    ? InferBindingGetType<BindingsArrayT[KeyT]> | undefined
+    : BindingsArrayT[KeyT];
+};

package/src/binding/types/infer-named-binding-value-types.ts

@@ -0,0 +1,12 @@
+import type { NamedBindingDependencies } from './binding-dependencies';
+import type { InferBindingGetType } from './inference';
+import type { ReadonlyBinding } from './readonly-binding';
+
+/** Infers the value types from named bindings */
+export type InferNamedBindingsValueTypes<NamedBindingsT extends NamedBindingDependencies> = {
+  [KeyT in keyof NamedBindingsT]: NamedBindingsT[KeyT] extends ReadonlyBinding
+    ? InferBindingGetType<NamedBindingsT[KeyT]>
+    : NamedBindingsT[KeyT] extends ReadonlyBinding | undefined
+    ? InferBindingGetType<NamedBindingsT[KeyT]> | undefined
+    : NamedBindingsT[KeyT];
+};

package/src/binding/types/inference.ts

@@ -0,0 +1,4 @@
+import type { ReadonlyBinding } from './readonly-binding';
+
+/** Infers the stored value type from a binding type */
+export type InferBindingGetType<BindingT> = BindingT extends ReadonlyBinding<infer GetType> ? GetType : never;

package/src/binding/types/readonly-binding.ts

@@ -0,0 +1,39 @@
+import type { ChangeListener, ChangeListenerRemover } from './change-listener';
+
+/** The readonly interface for bindings */
+export interface ReadonlyBinding<GetType = any> {
+  /** A marker indicating that this is a binding type */
+  readonly isBinding: true;
+
+  /** A technical, but human-readable ID, which isn't guaranteed to be unique */
+  readonly id: string;
+  /** An ID that's unique to this runtime */
+  readonly uid: string;
+
+  /**
+   * Adds a listener that will be called when this binding changes.
+   *
+   * @see `useBindingEffect` and `BindingsConsumer`
+   *
+   * @returns a function that may be used to remove the added listener.
+   */
+  readonly addChangeListener: (listener: ChangeListener) => ChangeListenerRemover;
+
+  /** @returns the value */
+  readonly get: () => GetType;
+  /** Every time the value is changed, the change uid is updated */
+  readonly getChangeUid: () => string;
+  /** @returns `true` if this binding has been marked as being modified */
+  readonly isModified: () => boolean;
+
+  /** @returns `true` if the binding is locked */
+  readonly isLocked: () => boolean;
+  /**
+   * Increments the lock count and returns a method to decrement it.  A binding is locked if its lock
+   * count is `> 0`.  When a binding is locked, mutating calls (`reset`/`set`/`setRaw`) won't have an immediate effect.  However, if a
+   * mutating call is made on a locked binding, the change will be applied once the binding becomes unlocked.
+   *
+   * @returns a function for decrementing this binding's lock count.
+   */
+  readonly lock: () => () => void;
+}

package/src/binding/types/set-value-transformer.ts

@@ -0,0 +1,11 @@
+import type { ReadonlyBinding } from './readonly-binding';
+
+/**
+ * A transformer function called prior to storing the value when using the `set` method
+ *
+ * @param newValue - The proposed new value
+ * @param thisBinding - The binding being updated
+ *
+ * @returns The transformed value to set the binding to
+ */
+export type SetValueTransformer<GetType> = (newValue: GetType, thisBinding: ReadonlyBinding<GetType>) => GetType;

package/src/binding/use-binding.ts

@@ -0,0 +1,17 @@
+import type { DependencyList } from 'react';
+import { useMemo } from 'react';
+
+import type { EmptyObject } from '../types/empty';
+import { makeBinding } from './make-binding';
+import type { Binding } from './types/binding';
+import type { UseBindingArgs } from './types/binding-args';
+import type { BindingInitializer } from './types/binding-initializer';
+
+const emptyDeps: DependencyList = Object.freeze([]);
+
+/** Makes a binding memo'd using the specified dependencies */
+export const useBinding = <GetType = any, ExtraFieldsT extends object = EmptyObject>(
+  initialValue: BindingInitializer<GetType>,
+  args: UseBindingArgs<GetType, ExtraFieldsT>
+): // eslint-disable-next-line react-hooks/exhaustive-deps
+Binding<GetType> & ExtraFieldsT => useMemo(() => makeBinding<GetType, ExtraFieldsT>(initialValue, args), args.deps ?? emptyDeps);