std-react-bindings 0.0.1

package/src/internal-hooks/use-is-mounted-ref.ts

@@ -0,0 +1,16 @@
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+/** Much lighter weight than useMountBinding  */
+export const useIsMountedRef = (): RefObject<boolean> => {
+  const isMounted = useRef(false);
+  useEffect(() => {
+    isMounted.current = true;
+
+    return () => {
+      isMounted.current = false;
+    };
+  });
+
+  return isMounted;
+};

package/src/internal-utils/__tests__/concat-arrays.test.ts

@@ -0,0 +1,25 @@
+import { concatArrays } from '../array-like';
+
+describe('concatArrays', () => {
+  it('no parameters should return an empty array', () => {
+    expect(concatArrays()).toMatchObject([]);
+  });
+
+  it('array first parameter only should return original array directly', () => {
+    const array = ['hello', 'world'];
+    expect(concatArrays(array)).toBe(array);
+    expect(concatArrays(array)).toMatchObject(array);
+  });
+
+  it('undefined first parameter and array second parameter should return original array directly', () => {
+    const array = ['hello', 'world'];
+    expect(concatArrays(undefined, array)).toBe(array);
+    expect(concatArrays(undefined, array)).toMatchObject(array);
+  });
+
+  it('two arrays should return new array with concatenated elements', () => {
+    const array1 = ['hello', 'world'];
+    const array2 = ['one', 'two'];
+    expect(concatArrays(array1, array2)).toMatchObject(['hello', 'world', 'one', 'two']);
+  });
+});

package/src/internal-utils/__tests__/extract-binding-dependency-values.test.ts

@@ -0,0 +1,73 @@
+import { makeConstBinding } from '../../specialized-bindings/const-binding';
+import { extractBindingDependencyValues } from '../extract-binding-dependency-values';
+
+describe('extractBindingDependencyValues', () => {
+  it('undefined bindings should work', () => {
+    expect(extractBindingDependencyValues({ bindings: undefined, namedBindingsKeys: undefined })).toBeUndefined();
+  });
+
+  it('single bindings should work', () => {
+    expect(
+      extractBindingDependencyValues({
+        bindings: makeConstBinding(3, { id: 'test' }),
+        namedBindingsKeys: undefined
+      })
+    ).toBe(3);
+  });
+
+  it('arrays of bindings should work', () => {
+    const bindings = [makeConstBinding(3, { id: 'test1' }), makeConstBinding('hello', { id: 'test2' })];
+
+    expect(
+      extractBindingDependencyValues({
+        bindings,
+        namedBindingsKeys: undefined
+      })
+    ).toMatchObject([3, 'hello']);
+  });
+
+  it('undefined values in arrays of bindings should work', () => {
+    const bindings = [makeConstBinding(3, { id: 'test1' }), undefined, makeConstBinding('hello', { id: 'test2' })];
+
+    expect(
+      extractBindingDependencyValues({
+        bindings,
+        namedBindingsKeys: undefined
+      })
+    ).toMatchObject([3, undefined, 'hello']);
+  });
+
+  it('binding tuples should work', () => {
+    expect(
+      extractBindingDependencyValues({
+        bindings: [makeConstBinding(3, { id: 'test1' }), makeConstBinding('hello', { id: 'test2' })],
+        namedBindingsKeys: undefined
+      })
+    ).toMatchObject([3, 'hello']);
+  });
+
+  it('named bindings should work', () => {
+    expect(
+      extractBindingDependencyValues({
+        bindings: {
+          one: makeConstBinding(3, { id: 'test1' }),
+          two: makeConstBinding('hello', { id: 'test2' })
+        },
+        namedBindingsKeys: ['one', 'two']
+      })
+    ).toMatchObject({ one: 3, two: 'hello' });
+  });
+
+  it('undefined values in named bindings should work', () => {
+    expect(
+      extractBindingDependencyValues({
+        bindings: {
+          one: makeConstBinding(3, { id: 'test1' }),
+          two: makeConstBinding('hello', { id: 'test2' }),
+          three: undefined
+        },
+        namedBindingsKeys: ['one', 'two', 'three']
+      })
+    ).toMatchObject({ one: 3, two: 'hello', three: undefined });
+  });
+});

package/src/internal-utils/__tests__/normalize-as-array.test.ts

@@ -0,0 +1,17 @@
+import { normalizeAsArray } from '../array-like';
+
+describe('normalizeAsArray', () => {
+  it('undefined should return an array with [undefined]', () => {
+    expect(normalizeAsArray(undefined)).toMatchObject([undefined]);
+  });
+
+  it('a single value should return an array with that value', () => {
+    expect(normalizeAsArray('hello')).toMatchObject(['hello']);
+  });
+
+  it('an array should be returned as-is', () => {
+    const array = ['hello', 'world'];
+    expect(normalizeAsArray(array)).toBe(array);
+    expect(normalizeAsArray(array)).toMatchObject(array);
+  });
+});

package/src/internal-utils/__tests__/normalize-as-optonal-array.test.ts

@@ -0,0 +1,17 @@
+import { normalizeAsOptionalArray } from '../array-like';
+
+describe('normalizeAsOptionalArray', () => {
+  it('undefined should return undefined', () => {
+    expect(normalizeAsOptionalArray(undefined)).toBeUndefined();
+  });
+
+  it('a single value should return an array with that value', () => {
+    expect(normalizeAsOptionalArray('hello')).toMatchObject(['hello']);
+  });
+
+  it('an array should be returned as-is', () => {
+    const array = ['hello', 'world'];
+    expect(normalizeAsOptionalArray(array)).toBe(array);
+    expect(normalizeAsOptionalArray(array)).toMatchObject(array);
+  });
+});

package/src/internal-utils/array-like.ts

@@ -0,0 +1,26 @@
+import type { SingleOrArray } from '../types/array-like';
+
+/** Normalizes a SingleOrArray value as an array */
+export const normalizeAsArray = <T>(value: SingleOrArray<T>) => (Array.isArray(value) ? value : [value]);
+
+/** Normalizes a SingleOrArray value as an array or undefined */
+export const normalizeAsOptionalArray = <T>(value?: SingleOrArray<T>) =>
+  value === undefined ? undefined : Array.isArray(value) ? value : [value];
+
+/**
+ * Returns an array by efficiently concatenating two potential arrays as needed.  If either array is unset / empty, the other array is
+ * returned without copying.  If both arrays are unset / empty, a new empty array is returned.
+ */
+export const concatArrays = <T>(a?: Array<T>, b?: Array<T>): T[] => {
+  const aLength = a?.length ?? 0;
+  const bLength = b?.length ?? 0;
+  if (aLength === 0 && bLength === 0) {
+    return [];
+  } else if (bLength === 0) {
+    return a!;
+  } else if (aLength === 0) {
+    return b!;
+  } else {
+    return [...a!, ...b!];
+  }
+};

package/src/internal-utils/extract-binding-dependency-values.ts

@@ -0,0 +1,36 @@
+import type { BindingDependencies, NamedBindingDependencies } from '../binding/types/binding-dependencies';
+import type { InferBindingValueTypes } from '../binding/types/infer-binding-value-types';
+import { isBinding } from '../binding-utils/type-utils';
+
+export const extractBindingDependencyValues = <DependenciesT extends BindingDependencies>({
+  bindings,
+  namedBindingsKeys
+}: {
+  bindings: DependenciesT | undefined;
+  namedBindingsKeys: string[] | undefined;
+}): InferBindingValueTypes<DependenciesT> => {
+  const isBindingsArray = Array.isArray(bindings);
+  const isNonNamedBindings = isBindingsArray || isBinding(bindings);
+
+  if (isNonNamedBindings) {
+    if (isBindingsArray) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return bindings.map((binding) => binding?.get()) as InferBindingValueTypes<DependenciesT>;
+    } else {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return bindings.get() as InferBindingValueTypes<DependenciesT>;
+    }
+  } else if (namedBindingsKeys !== undefined) {
+    const namedBindingValues: Record<string, any> = {};
+    for (const key of namedBindingsKeys) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      namedBindingValues[key] = (bindings as NamedBindingDependencies)[key]?.get();
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return namedBindingValues as InferBindingValueTypes<DependenciesT>;
+  } else {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return undefined as InferBindingValueTypes<DependenciesT>;
+  }
+};

package/src/internal-utils/get-typed-keys.ts

@@ -0,0 +1,6 @@
+/**
+ * Gets the keys of the specified value in the type that corresponds with that value.
+ *
+ * For example: `{a: 'one', b: 'two'}` returns `['a', 'b']` as `Array<'a' | 'b'>` rather than as `string[]`.
+ */
+export const getTypedKeys = <T extends object>(value: T) => Object.keys(value) as Array<keyof T & string>;

package/src/internal-utils/uid.ts

@@ -0,0 +1,4 @@
+let globalInc = 0;
+
+/** Make an ID that is unique to at least this runtime */
+export const makeUID = () => `id${globalInc++}`;

package/src/limiter/__tests__/use-limiter.test.ts

@@ -0,0 +1,227 @@
+import { jest } from '@jest/globals';
+
+import { runInDom, sleep } from '../../__test_dependency__';
+import { useLimiter } from '../use-limiter';
+
+describe('useLimiter', () => {
+  it('with default settings should run only once enough time is given', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test' });
+
+      onMount(async () => {
+        const callback = jest.fn((_value) => {});
+        limiter.limit(() => callback(0));
+        limiter.limit(() => callback(1));
+        limiter.limit(() => callback(2));
+        limiter.limit(() => callback(3));
+        limiter.limit(() => callback(4));
+
+        await sleep(50); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(1);
+        expect(callback).toHaveBeenLastCalledWith(4);
+      });
+    }));
+
+  it('with limitMSec=50, limitMode=leading should run only once, very shortly after the first call', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitMSec: 50, limitMode: 'leading' });
+
+      onMount(async () => {
+        const callback = jest.fn();
+        limiter.limit(callback);
+        await sleep(0);
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(1);
+      });
+    }));
+
+  it('with limitMSec=50, limitMode=leading-and-trailing should run twice: once very shortly after the first call and once after enough time is given', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitMSec: 50, limitMode: 'leading-and-trailing' });
+
+      onMount(async () => {
+        const callback = jest.fn();
+        limiter.limit(callback);
+        await sleep(0);
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(2);
+      });
+    }));
+
+  it("with cancel on unmount should never run if enough time isn't given", () =>
+    runInDom(({ onMount, onUnmount }) => {
+      const limiter = useLimiter({ id: 'test', cancelOnUnmount: true });
+
+      const callback = jest.fn();
+
+      onMount(() => {
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+      });
+
+      onUnmount(async () => {
+        await sleep(50); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(0);
+      });
+    }));
+
+  it('with limiterType=none should run immediately every time', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitType: 'none' });
+
+      onMount(async () => {
+        const callback = jest.fn();
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+        limiter.limit(callback);
+
+        expect(callback).toHaveBeenCalledTimes(5);
+      });
+    }));
+
+  it('with limitMSec=50, should run only once enough time is given', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitMSec: 50 });
+
+      onMount(async () => {
+        const callback = jest.fn();
+        limiter.limit(callback);
+        await sleep(10);
+        limiter.limit(callback);
+        await sleep(10);
+        limiter.limit(callback);
+        await sleep(10);
+        limiter.limit(callback);
+        await sleep(10);
+        limiter.limit(callback);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        limiter.limit(callback);
+        expect(callback).toHaveBeenCalledTimes(1);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(2);
+      });
+    }));
+
+  it('with limitType=throttle, limitMSec=20, should run every time enough time has elapsed', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitType: 'throttle', limitMSec: 20 });
+
+      onMount(async () => {
+        const callback = jest.fn();
+
+        limiter.limit(callback);
+        expect(callback).toHaveBeenCalledTimes(0);
+        await sleep(10);
+        expect(callback).toHaveBeenCalledTimes(0);
+        limiter.limit(callback);
+        await sleep(10);
+
+        await sleep(0); // giving time for limiter
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        await sleep(10);
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        await sleep(10);
+
+        await sleep(0); // giving time for limiter
+        expect(callback).toHaveBeenCalledTimes(2);
+        limiter.limit(callback);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(3);
+      });
+    }));
+
+  it('with limitType=throttle, limitMSec=20, limitMode=leading should very shortly after the first call and every time enough time has elapsed', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitType: 'throttle', limitMSec: 20, limitMode: 'leading' });
+
+      onMount(async () => {
+        const callback = jest.fn();
+
+        limiter.limit(callback);
+        expect(callback).toHaveBeenCalledTimes(0);
+        await sleep(10);
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        await sleep(10);
+
+        await sleep(0); // giving time for limiter
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        await sleep(10);
+        expect(callback).toHaveBeenCalledTimes(2);
+        limiter.limit(callback);
+        await sleep(10);
+
+        await sleep(0); // giving time for limiter
+        expect(callback).toHaveBeenCalledTimes(2);
+        limiter.limit(callback);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(3);
+      });
+    }));
+
+  it('with limitType=throttle, limitMSec=20, limitMode=leading-and-trailing should very shortly after the first call and every time enough time has elapsed', () =>
+    runInDom(({ onMount }) => {
+      const limiter = useLimiter({ id: 'test', limitType: 'throttle', limitMSec: 20, limitMode: 'leading-and-trailing' });
+
+      onMount(async () => {
+        const callback = jest.fn();
+
+        limiter.limit(callback);
+        expect(callback).toHaveBeenCalledTimes(0);
+        await sleep(10);
+        expect(callback).toHaveBeenCalledTimes(1);
+        limiter.limit(callback);
+        await sleep(10);
+
+        await sleep(0); // giving time for limiter
+        expect(callback).toHaveBeenCalledTimes(2);
+        limiter.limit(callback);
+        await sleep(10);
+        expect(callback).toHaveBeenCalledTimes(2);
+        limiter.limit(callback);
+        await sleep(10);
+
+        await sleep(0); // giving time for limiter
+        expect(callback).toHaveBeenCalledTimes(3);
+        limiter.limit(callback);
+
+        await sleep(200); // giving time for limiter
+
+        expect(callback).toHaveBeenCalledTimes(4);
+      });
+    }));
+});

package/src/limiter/exports.ts

@@ -0,0 +1,4 @@
+export * from './make-limiter';
+export * from './pick-limiter-options';
+export * from './types/exports';
+export * from './use-limiter';

package/src/limiter/internal/LimiterImpl.ts

@@ -0,0 +1,73 @@
+import type { RunQueue, RunQueueEntry } from 'std-client-run-queue';
+import type { DebouncedFunc } from 'lodash';
+import _ from 'lodash';
+
+import type { Limiter } from '../types/Limiter';
+import type { LimiterOptions } from '../types/LimiterOptions';
+import type { LimitMode } from '../types/LimitMode';
+
+const noOp = () => {};
+
+const leadingEdgeModes = new Set<LimitMode>(['leading', 'leading-and-trailing']);
+const trailingEdgeModes = new Set<LimitMode>(['trailing', 'leading-and-trailing']);
+
+export class LimiterImpl implements Limiter {
+  // Limiter Fields
+
+  public readonly queue: RunQueue;
+
+  // Private Fields
+
+  private queueEntry_: RunQueueEntry<void> | undefined;
+  private lodashLimiter_: DebouncedFunc<() => void> | undefined;
+
+  private readonly id_: string;
+  private readonly options_: Required<LimiterOptions>;
+  private runner_ = noOp;
+
+  // Initialization
+
+  constructor(id: string, options: Required<LimiterOptions>) {
+    this.id_ = id;
+    this.queue = options.queue;
+    this.options_ = options;
+  }
+
+  // Limiter Methods
+
+  public cancel() {
+    this.queueEntry_?.cancel();
+    this.queueEntry_ = undefined;
+
+    // Not actually canceling the lodashLimiter because we don't want the limiting state to reset, but changing the runner to a noOp so it
+    // won't do anything
+    this.runner_ = noOp;
+  }
+
+  public limit(run: () => void) {
+    const { limitMode, limitMSec, limitType, priority } = this.options_;
+
+    if (limitType === 'none') {
+      run();
+      return;
+    }
+
+    this.runner_ = run;
+
+    if (this.lodashLimiter_ === undefined) {
+      this.lodashLimiter_ = _[limitType](
+        () => {
+          this.queueEntry_?.cancel();
+          this.queueEntry_ = this.queue!.schedule(priority, this.id_, () => this.runner_());
+        },
+        limitMSec,
+        {
+          leading: leadingEdgeModes.has(limitMode),
+          trailing: trailingEdgeModes.has(limitMode)
+        }
+      );
+    }
+
+    this.lodashLimiter_();
+  }
+}

package/src/limiter/make-limiter.ts

@@ -0,0 +1,20 @@
+import type { RunQueue } from 'std-client-run-queue';
+import { DEFAULT_PRIORITY } from 'std-client-run-queue';
+
+import { LimiterImpl } from './internal/LimiterImpl';
+import type { Limiter } from './types/Limiter';
+import type { LimiterOptions } from './types/LimiterOptions';
+
+export interface MakeLimiterArgs extends Omit<LimiterOptions, 'queue'> {
+  id: string;
+  queue: RunQueue;
+}
+
+export const makeLimiter = ({
+  id,
+  limitType = 'debounce',
+  limitMSec = 0,
+  limitMode = 'trailing',
+  priority = DEFAULT_PRIORITY,
+  queue
+}: MakeLimiterArgs): Limiter => new LimiterImpl(id, { limitMode, limitMSec, limitType, priority, queue });

package/src/limiter/pick-limiter-options.ts

@@ -0,0 +1,9 @@
+import type { LimiterOptions } from './types/LimiterOptions';
+
+export const pickLimiterOptions = (value: LimiterOptions): LimiterOptions => ({
+  limitMode: value.limitMode,
+  limitMSec: value.limitMSec,
+  limitType: value.limitType,
+  priority: value.priority,
+  queue: value.queue
+});

package/src/limiter/types/LimitMode.ts

@@ -0,0 +1,6 @@
+/**
+ * The limiter mode
+ *
+ * @see `LimiterType`
+ */
+export type LimitMode = 'leading' | 'trailing' | 'leading-and-trailing';

package/src/limiter/types/LimitType.ts

@@ -0,0 +1,31 @@
+/**
+ * The method for limiting.
+ *
+ * - `'none'` - No limiting is applied so functions run immediately, every time they're called.  The queue and priority are ignored.
+ * - `'debounce'` - Functions calls are grouped
+ * - `'throttle'` - Functions are called at most once per interval
+ *
+ * _For the following examples, assume each `x` or `-` take 100ms and that the limit interval is 200ms:_
+ *
+ * - _`x` means function call_
+ * - _`-` means nothing happened_
+ *
+ * If a function is called like: `x--xxxx--x`
+ *
+ * **Debouncing**
+ *
+ * With debouncing, calls are grouped as long as repeated calls are requested within the limiting interval.
+ *
+ * - with leading edge debouncing, the function is run like `x--x-----x`
+ * - with trailing edge debouncing, the function is run like `---x------x---x`
+ * - with both leading and trailing edge debouncing, the function is run like `x--x-----xx`
+ *
+ * **Throttling**
+ *
+ * With throttling, calls are run at most once per limiting interval.
+ *
+ * - with leading edge throttling, the function is run like `x--x--x--x`
+ * - with trailing edge throttling, the function is run like `---x--x--x--x`
+ * - with both leading and trailing edge throttling, the function is run like `x--x--x--x--x`
+ */
+export type LimitType = 'none' | 'debounce' | 'throttle';

package/src/limiter/types/Limiter.ts

@@ -0,0 +1,10 @@
+import type { RunQueue } from 'std-client-run-queue';
+
+export interface Limiter {
+  readonly queue: RunQueue;
+
+  /** Cancels any outstanding function calls and scheduled queue entries */
+  readonly cancel: () => void;
+  /** Runs or schedules the specified function.  The specified function replaces any previous function used with this limiter */
+  readonly limit: (run: () => void) => void;
+}

package/src/limiter/types/LimiterOptions.ts

@@ -0,0 +1,38 @@
+import type { RunQueue } from 'std-client-run-queue';
+
+import type { LimitMode } from './LimitMode';
+import type { LimitType } from './LimitType';
+
+export interface LimiterOptions {
+  /**
+   * The limiter mode
+   *
+   * @defaultValue `'trailing'`
+   */
+  limitMode?: LimitMode;
+  /**
+   * The duration to debounce/throttle for
+   *
+   * @defaultValue `0`
+   */
+  limitMSec?: number;
+  /**
+   * The type of limiter
+   *
+   * @defaultValue `'debounce'`
+   */
+  limitType?: LimitType;
+
+  /**
+   * The priority
+   *
+   * @defaultValue `DEFAULT_PRIORITY` (`0`)
+   */
+  priority?: number;
+  /**
+   * The queue
+   *
+   * @defaultValue result of `useDefaultQueue()`
+   */
+  queue?: RunQueue;
+}

package/src/limiter/types/exports.ts

@@ -0,0 +1,4 @@
+export * from './Limiter';
+export * from './LimiterOptions';
+export * from './LimitMode';
+export * from './LimitType';