ts-data-forge 6.2.1 → 6.3.0

package/src/functional/ternary-result/impl/ternary-result-flat-map.mts

@@ -23,7 +23,10 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  *   parse,
  * );
  *
- * const errPassthrough = TernaryResult.flatMap(TernaryResult.err('oops'), parse);
+ * const errPassthrough = TernaryResult.flatMap(
+ *   TernaryResult.err('oops'),
+ *   parse,
+ * );
  *
  * assert.deepStrictEqual(doubled, TernaryResult.ok(6));
  *

package/src/functional/ternary-result/impl/ternary-result-is-warn.mts

@@ -7,11 +7,10 @@ import { type NarrowToWarn } from './types.mjs';
  * @example
  *
  * ```ts
- * const maybeWarn = TernaryResult.warn('value', 'check logs') as TernaryResult<
- *   string,
- *   string,
- *   string
- * >;
+ * const maybeWarn = TernaryResult.warn(
+ *   'value',
+ *   'check logs',
+ * ) as TernaryResult<string, string, string>;
  *
  * if (TernaryResult.isWarn(maybeWarn)) {
  *   assert.strictEqual(maybeWarn.value, 'value');

package/src/functional/ternary-result/impl/ternary-result-map-warn.mts

@@ -10,7 +10,10 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  * ```ts
  * const warnValue = TernaryResult.warn(2, 'slow');
  *
- * const mappedWarn = TernaryResult.mapWarn(warnValue, (warning) => `${warning}!`);
+ * const mappedWarn = TernaryResult.mapWarn(
+ *   warnValue,
+ *   (warning) => `${warning}!`,
+ * );
  *
  * const okPassthrough = TernaryResult.mapWarn(
  *   TernaryResult.ok(3),

package/src/functional/ternary-result/impl/ternary-result-to-optional.mts

@@ -15,7 +15,10 @@ import { type UnwrapOk } from './types.mjs';
  *
  * assert.deepStrictEqual(TernaryResult.toOptional(okValue), Optional.some(7));
  *
- * assert.deepStrictEqual(TernaryResult.toOptional(warnValue), Optional.some(7));
+ * assert.deepStrictEqual(
+ *   TernaryResult.toOptional(warnValue),
+ *   Optional.some(7),
+ * );
  * ```
  */
 export const toOptional = <R extends UnknownTernaryResult>(

package/src/functional/ternary-result/impl/ternary-result-unwrap-err-or.mts

@@ -9,7 +9,10 @@ import { type UnwrapErr } from './types.mjs';
  * ```ts
  * const okValue = TernaryResult.ok('value');
  *
- * assert.strictEqual(TernaryResult.unwrapErrOr(okValue, 'default'), 'default');
+ * assert.strictEqual(
+ *   TernaryResult.unwrapErrOr(okValue, 'default'),
+ *   'default',
+ * );
  *
  * const unwrapErr = TernaryResult.unwrapErrOr('fallback error');
  *

package/src/functional/ternary-result/impl/ternary-result-unwrap-throw.mts

@@ -13,10 +13,11 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  *
  * assert.strictEqual(TernaryResult.unwrapThrow(okValue), 'ready');
  *
- * assert.throws(
- *   () => TernaryResult.unwrapThrow(TernaryResult.warn('warn', 'warned')),
- *   /Expected Ok/u,
- * );
+ * const throwTest = (): void => {
+ *   TernaryResult.unwrapThrow(TernaryResult.warn('warn', 'warned'));
+ * };
+ *
+ * assert.throws(throwTest, /Expected Ok/u);
  * ```
  */
 export const unwrapThrow = <R extends UnknownTernaryResult>(

package/src/functional/ternary-result/impl/ternary-result-zip.mts

@@ -9,7 +9,10 @@ import { warn } from './ternary-result-warn.mjs';
  * @example
  *
  * ```ts
- * const okPair = TernaryResult.zip(TernaryResult.ok('left'), TernaryResult.ok(1));
+ * const okPair = TernaryResult.zip(
+ *   TernaryResult.ok('left'),
+ *   TernaryResult.ok(1),
+ * );
  *
  * const warnPair = TernaryResult.zip(
  *   TernaryResult.warn('left', 'warn'),

package/src/guard/is-record.mts

@@ -25,7 +25,7 @@ import { isNonNullObject } from './is-non-null-object.mjs';
  * @example
  *
  * ```ts
- * const entries: unknown[] = [{ id: 1 }, ['tuple']];
+ * const entries: unknown[] = [{ id: 1 }, 'str', 0, null];
  *
  * const records = entries.filter(isRecord);
  *

package/src/json/json.mts

@@ -291,11 +291,13 @@ export namespace Json {
    *   );
    *
    *   assert.isTrue(
-   *     formatted.value.indexOf('"mango"') < formatted.value.indexOf('"nested"'),
+   *     formatted.value.indexOf('"mango"') <
+   *       formatted.value.indexOf('"nested"'),
    *   );
    *
    *   assert.isTrue(
-   *     formatted.value.indexOf('"nested"') < formatted.value.indexOf('"zebra"'),
+   *     formatted.value.indexOf('"nested"') <
+   *       formatted.value.indexOf('"zebra"'),
    *   );
    * }
    * ```

package/src/others/debounce-function.mts

@@ -0,0 +1,23 @@
+/**
+ * Creates a debounced function that delays invoking `func` until after `waitMilliseconds`
+ * have elapsed since the last time the debounced function was invoked.
+ *
+ * @template F The type of the function to debounce.
+ * @param func The function to debounce.
+ * @param waitMilliseconds The number of milliseconds to delay.
+ * @returns The new debounced function.
+ */
+export const debounce = <Args extends readonly unknown[]>(
+  func: (...args: Args) => void,
+  waitMilliseconds: number,
+): ((...args: Args) => void) => {
+  let mut_timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  return (...args: Args): void => {
+    clearTimeout(mut_timeoutId);
+
+    mut_timeoutId = setTimeout(() => {
+      func(...args);
+    }, waitMilliseconds);
+  };
+};

package/src/others/debounce-function.test.mts

@@ -0,0 +1,81 @@
+/* eslint-disable vitest/no-restricted-vi-methods */
+
+import { debounce } from './debounce-function.mjs';
+
+describe(debounce, () => {
+  // eslint-disable-next-line vitest/no-hooks
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  // eslint-disable-next-line vitest/no-hooks
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('should delay the execution of the function', () => {
+    const func = vi.fn();
+
+    // eslint-disable-next-line @typescript-eslint/strict-void-return
+    const debouncedFunc = debounce(func, 100);
+
+    debouncedFunc();
+
+    expect(func).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(50);
+
+    expect(func).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(50);
+
+    expect(func).toHaveBeenCalledOnce();
+  });
+
+  test('should only execute the function once after multiple rapid calls', () => {
+    const func = vi.fn();
+
+    // eslint-disable-next-line @typescript-eslint/strict-void-return
+    const debouncedFunc = debounce(func, 100);
+
+    debouncedFunc();
+
+    debouncedFunc();
+
+    debouncedFunc();
+
+    expect(func).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+
+    expect(func).toHaveBeenCalledOnce();
+  });
+
+  test('should pass the arguments to the original function', () => {
+    const func = vi.fn((_a: number, _b: string) => {});
+
+    const debouncedFunc = debounce(func, 100);
+
+    debouncedFunc(1, 'test');
+
+    vi.advanceTimersByTime(100);
+
+    expect(func).toHaveBeenCalledWith(1, 'test');
+  });
+
+  test('should use the latest arguments from the last call', () => {
+    const func = vi.fn((_a: number, _b: string) => {});
+
+    const debouncedFunc = debounce(func, 100);
+
+    debouncedFunc(1, 'a');
+
+    debouncedFunc(2, 'b');
+
+    debouncedFunc(3, 'c');
+
+    vi.advanceTimersByTime(100);
+
+    expect(func).toHaveBeenCalledExactlyOnceWith(3, 'c');
+  });
+});

package/src/others/index.mts

@@ -1,5 +1,6 @@
 export * from './cast-mutable.mjs';
 export * from './cast-readonly.mjs';
+export * from './debounce-function.mjs';
 export * from './if-then.mjs';
 export * from './map-nullable.mjs';
 export * from './memoize-function.mjs';