@pezkuwi/util 14.0.7 → 14.0.11

package/src/logger.spec.ts

@@ -0,0 +1,188 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { Logger } from './types.js';
+
+import { BN } from './bn/index.js';
+import { logger, loggerFormat } from './index.js';
+
+describe('logger', (): void => {
+  const dateMatch = expect.stringMatching(/20[0-9]{2}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}/);
+  const prefixMatch = expect.stringMatching(/TEST:/);
+  let l: Logger;
+  let ln: Logger;
+  let spy: Partial<Console>;
+  let oldEnv: typeof process.env;
+
+  beforeEach((): void => {
+    oldEnv = process.env;
+    process.env['NODE_ENV'] = 'development';
+
+    ln = logger('notDebug');
+
+    process.env['DEBUG'] = 'test';
+
+    l = logger('test');
+
+    spy = {
+      error: jest.fn(),
+      log: jest.fn(),
+      warn: jest.fn()
+    };
+    global.console = spy as Console;
+  });
+
+  afterEach((): void => {
+    process.env = oldEnv;
+    jest.restoreAllMocks();
+  });
+
+  describe('loggerFormat', (): void => {
+    it('returns null as-is', (): void => {
+      expect(loggerFormat(null)).toEqual(null);
+    });
+
+    it('returns undefined as-is', (): void => {
+      expect(loggerFormat(undefined)).toEqual(undefined);
+    });
+  });
+
+  it('logs to console.log with .log', (): void => {
+    l.log('console.log test');
+
+    expect(spy.log).toHaveBeenCalledWith(
+      dateMatch,
+      prefixMatch,
+      expect.stringMatching('console.log test')
+    );
+  });
+
+  it('logs with multiple values', (): void => {
+    l.log('test', 'a', 2, new BN('12345678900987654321'), Buffer.from([0, 1, 2, 3]));
+
+    expect(spy.log).toHaveBeenCalledWith(
+      dateMatch,
+      prefixMatch,
+      expect.stringMatching('test'),
+      expect.stringMatching('a'),
+      2,
+      expect.stringMatching('12345678900987654321'),
+      expect.stringMatching('0x00010203')
+    );
+  });
+
+  it('logs when called with function', (): void => {
+    l.log((): string => 'a function test');
+
+    expect(spy.log).toHaveBeenCalledWith(
+      dateMatch,
+      prefixMatch,
+      expect.stringMatching('a function test')
+    );
+  });
+
+  it('logs to console.error with .error', (): void => {
+    l.error('console.error test');
+
+    expect(spy.error).toHaveBeenCalledWith(
+      dateMatch,
+      prefixMatch,
+      expect.stringMatching('console.error test')
+    );
+  });
+
+  it('logs to console.warn with .warn', (): void => {
+    l.warn('console.warn test');
+
+    expect(spy.warn).toHaveBeenCalledWith(
+      dateMatch,
+      prefixMatch,
+      expect.stringMatching('console.warn test')
+    );
+  });
+
+  it('does debug log when DEBUG specified', (): void => {
+    l.debug('test');
+
+    expect(spy.log).toHaveBeenCalledWith(
+      dateMatch,
+      prefixMatch,
+      expect.stringMatching('test')
+    );
+  });
+
+  it('does debug log when DEBUG partial specified', (): void => {
+    process.env['DEBUG'] = 'test*';
+
+    l = logger('testing');
+    l.debug('test');
+
+    expect(spy.log).toHaveBeenCalledWith(
+      dateMatch,
+      expect.stringMatching(/TESTING:/),
+      expect.stringMatching('test')
+    );
+  });
+
+  it('does not debug log when non-matching DEBUG specified', (): void => {
+    process.env['DEBUG'] = 'blah';
+
+    l = logger('test');
+    l.debug('test');
+
+    expect(spy.log).not.toHaveBeenCalled();
+  });
+
+  it('does debug log when DEBUG=* specified', (): void => {
+    process.env['DEBUG'] = '*';
+
+    l = logger('test');
+    l.debug('test');
+
+    expect(spy.log).toHaveBeenCalled();
+  });
+
+  it('does not debug log when no process.env', (): void => {
+    process.env = undefined as unknown as typeof process.env;
+
+    l = logger('test');
+    l.debug('test');
+
+    expect(spy.log).not.toHaveBeenCalled();
+  });
+
+  it('does not debug log when no DEBUG specified', (): void => {
+    ln.debug('test');
+
+    expect(spy.log).not.toHaveBeenCalled();
+  });
+
+  it('does not debug log when explicitly excluded', (): void => {
+    process.env['DEBUG'] = '*,-test';
+
+    l = logger('test');
+    l.debug('test');
+
+    expect(spy.log).not.toHaveBeenCalled();
+  });
+
+  it('does not debug log when part of exclusion group', (): void => {
+    process.env['DEBUG'] = '*,-test:*';
+
+    l = logger('test:sub');
+    l.debug('test');
+
+    expect(spy.log).not.toHaveBeenCalled();
+  });
+
+  it('does debug log when not part of exclusion groups', (): void => {
+    process.env['DEBUG'] = '*,-test:*,-tes,-a:*';
+
+    l = logger('test');
+    l.debug('test');
+
+    expect(spy.log).toHaveBeenCalled();
+  });
+});

package/src/logger.ts

@@ -0,0 +1,160 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Logger } from './types.js';
+
+import { xglobal } from '@pezkuwi/x-global';
+
+import { formatDate } from './format/formatDate.js';
+import { isBn } from './is/bn.js';
+import { isBuffer } from './is/buffer.js';
+import { isFunction } from './is/function.js';
+import { isObject } from './is/object.js';
+import { isU8a } from './is/u8a.js';
+import { u8aToHex } from './u8a/toHex.js';
+import { u8aToU8a } from './u8a/toU8a.js';
+import { noop } from './noop.js';
+
+type ConsoleType = 'error' | 'log' | 'warn';
+type LogType = ConsoleType | 'debug';
+
+const logTo = {
+  debug: 'log',
+  error: 'error',
+  log: 'log',
+  warn: 'warn'
+} as const;
+
+function formatOther (value: unknown): unknown {
+  if (value && isObject(value) && value.constructor === Object) {
+    const result: Record<string, unknown> = {};
+
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = loggerFormat(v);
+    }
+
+    return result;
+  }
+
+  return value;
+}
+
+export function loggerFormat (value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(loggerFormat);
+  } else if (isBn(value)) {
+    return value.toString();
+  } else if (isU8a(value) || isBuffer(value)) {
+    return u8aToHex(u8aToU8a(value));
+  }
+
+  return formatOther(value);
+}
+
+function formatWithLength (maxLength: number): (v: unknown) => unknown {
+  return (v: unknown): unknown => {
+    if (maxLength <= 0) {
+      return v;
+    }
+
+    const r = `${v as string}`;
+
+    return r.length < maxLength
+      ? v
+      : `${r.substring(0, maxLength)} ...`;
+  };
+}
+
+function apply (log: LogType, type: string, values: unknown[], maxSize = -1): void {
+  if (values.length === 1 && isFunction(values[0])) {
+    const fnResult = values[0]() as unknown;
+
+    return apply(log, type, Array.isArray(fnResult) ? fnResult : [fnResult], maxSize);
+  }
+
+  console[logTo[log]](
+    formatDate(new Date()),
+    type,
+    ...values
+      .map(loggerFormat)
+      .map(formatWithLength(maxSize))
+  );
+}
+
+function isDebugOn (e: string, type: string): boolean {
+  return !!e && (
+    e === '*' ||
+    type === e ||
+    (
+      e.endsWith('*') &&
+      type.startsWith(e.slice(0, -1))
+    )
+  );
+}
+
+function isDebugOff (e: string, type: string): boolean {
+  return !!e && (
+    e.startsWith('-') &&
+    (
+      type === e.slice(1) ||
+      (
+        e.endsWith('*') &&
+        type.startsWith(e.slice(1, -1))
+      )
+    )
+  );
+}
+
+function getDebugFlag (env: readonly string[], type: string): boolean {
+  let flag = false;
+
+  for (const e of env) {
+    if (isDebugOn(e, type)) {
+      flag = true;
+    } else if (isDebugOff(e, type)) {
+      flag = false;
+    }
+  }
+
+  return flag;
+}
+
+function parseEnv (type: string): [boolean, number] {
+  const maxSize = parseInt(xglobal.process?.env?.['DEBUG_MAX'] || '-1', 10);
+
+  return [
+    getDebugFlag((xglobal.process?.env?.['DEBUG'] || '').toLowerCase().split(','), type),
+    isNaN(maxSize)
+      ? -1
+      : maxSize
+  ];
+}
+
+/**
+ * @name Logger
+ * @summary Creates a consistent log interface for messages
+ * @description
+ * Returns a `Logger` that has `.log`, `.error`, `.warn` and `.debug` (controlled with environment `DEBUG=typeA,typeB`) methods. Logging is done with a consistent prefix (type of logger, date) followed by the actual message using the underlying console.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { logger } from '@pezkuwi/util';
+ *
+ * const l = logger('test');
+ * ```
+ */
+export function logger (origin: string): Logger {
+  const type = `${origin.toUpperCase()}:`.padStart(16);
+  const [isDebug, maxSize] = parseEnv(origin.toLowerCase());
+
+  return {
+    debug: isDebug
+      ? (...values: unknown[]) => apply('debug', type, values, maxSize)
+      : noop,
+    error: (...values: unknown[]) => apply('error', type, values),
+    log: (...values: unknown[]) => apply('log', type, values),
+    noop,
+    warn: (...values: unknown[]) => apply('warn', type, values)
+  };
+}

package/src/memoize.spec.ts

@@ -0,0 +1,79 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { memoize } from './index.js';
+
+describe('memoize', (): void => {
+  it('returns actual values', (): void => {
+    const fn = memoize(() => 5);
+
+    expect(fn()).toEqual(5);
+  });
+
+  it('caches executions', (): void => {
+    const spy = jest.fn((a: number, b: number) => a + b);
+    const fn = memoize(spy);
+
+    expect(fn(2, 4)).toEqual(6);
+    expect(fn(2, 4)).toEqual(6);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    expect(fn(4, 2)).toEqual(6);
+
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it('does unmemoize', (): void => {
+    const spy = jest.fn((a: number, b: number) => a + b);
+    const fn = memoize(spy);
+
+    expect(fn(2, 4)).toEqual(6);
+    expect(fn(4, 2)).toEqual(6);
+    expect(spy).toHaveBeenCalledTimes(2);
+
+    fn.unmemoize(2, 4);
+
+    expect(fn(2, 4)).toEqual(6);
+    expect(fn(4, 2)).toEqual(6);
+    expect(spy).toHaveBeenCalledTimes(3);
+  });
+
+  it('manages separate instances', (): void => {
+    let instanceId = 'a';
+    const spy = jest.fn((a: number, b: number) => a + b);
+    const fn = memoize(spy, { getInstanceId: () => instanceId });
+
+    expect(fn(1, 3)).toEqual(4);
+
+    instanceId = 'b';
+
+    expect(fn(1, 3)).toEqual(4);
+    expect(spy).toHaveBeenCalledTimes(2);
+
+    instanceId = 'a';
+
+    expect(fn(1, 3)).toEqual(4);
+    expect(spy).toHaveBeenCalledTimes(2);
+
+    instanceId = 'b';
+    fn.unmemoize(1, 3);
+
+    expect(fn(1, 3)).toEqual(4);
+    expect(spy).toHaveBeenCalledTimes(3);
+
+    instanceId = 'a';
+    fn.unmemoize(1, 3);
+
+    expect(fn(1, 3)).toEqual(4);
+    expect(spy).toHaveBeenCalledTimes(4);
+  });
+
+  it('normalizes BigInt values as well', (): void => {
+    const fn = memoize((a: bigint, b: bigint) => a + b);
+
+    expect(fn(1n, 2n).toString()).toEqual('3');
+  });
+});

package/src/memoize.ts

@@ -0,0 +1,49 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Memoized } from './types.js';
+
+import { stringify } from './stringify.js';
+
+interface Options {
+  getInstanceId?: () => string;
+}
+
+function defaultGetId (): string {
+  return 'none';
+}
+
+/**
+ * @name memoize
+ * @description Memomize the function with a specific instanceId
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function memoize <T, F extends (...args: any[]) => T> (fn: F, { getInstanceId = defaultGetId }: Options = {}): Memoized<F> {
+  const cache: Record<string, Record<string, T>> = {};
+
+  const memoized = (...args: unknown[]): T => {
+    const stringParams = stringify(args);
+    const instanceId = getInstanceId();
+
+    if (!cache[instanceId]) {
+      cache[instanceId] = {};
+    }
+
+    if (cache[instanceId][stringParams] === undefined) {
+      cache[instanceId][stringParams] = fn(...args);
+    }
+
+    return cache[instanceId][stringParams];
+  };
+
+  memoized.unmemoize = (...args: unknown[]): void => {
+    const stringParams = stringify(args);
+    const instanceId = getInstanceId();
+
+    if (cache[instanceId]?.[stringParams] !== undefined) {
+      delete cache[instanceId][stringParams];
+    }
+  };
+
+  return memoized as Memoized<F>;
+}

package/src/mod.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './index.js';

package/src/nextTick.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name nextTick
+ * @description Defer the operation to the queue for evaluation on the next tick
+ */
+export function nextTick (onExec: () => unknown, onError?: (error: Error) => unknown): void {
+  // While Promise.resolve().then(...) would defer to the nextTick, this
+  // actually does not play as nicely in browsers like the setTimeout(...)
+  // approach. So the safer, though less optimal approach is the one taken here
+  setTimeout((): void => {
+    Promise
+      .resolve()
+      .then((): void => {
+        onExec();
+      })
+      .catch((error: Error): void => {
+        if (onError) {
+          onError(error);
+        } else {
+          console.error(error);
+        }
+      });
+  }, 0);
+}

package/src/noop.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * A sharable identity function. Returns the input as-is with no transformation applied.
+ */
+export function identity <T> (value: T): T {
+  return value;
+}
+
+/**
+ * A sharable noop function. As the name suggests, does nothing
+ */
+export function noop (): void {
+  // noop
+}

package/src/number/index.ts

@@ -0,0 +1,9 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Utility methods to convert to and from `number` values
+ */
+
+export { numberToHex } from './toHex.js';
+export { numberToU8a } from './toU8a.js';

package/src/number/toHex.spec.ts

@@ -0,0 +1,44 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { numberToHex } from './index.js';
+
+describe('numberToHex', (): void => {
+  it('converts undefined to 0x00', (): void => {
+    expect(
+      numberToHex()
+    ).toEqual('0x00');
+  });
+
+  it('converts null to 0x00000000 (with bitLength)', (): void => {
+    expect(
+      numberToHex(null, 32)
+    ).toEqual('0x00000000');
+  });
+
+  it('converts Nan to 0x', (): void => {
+    expect(
+      numberToHex(NaN)
+    ).toEqual('0x00');
+  });
+
+  it('converts 0 to 0x00', (): void => {
+    expect(
+      numberToHex(0)
+    ).toEqual('0x00');
+  });
+
+  it('converts number to hex', (): void => {
+    expect(
+      numberToHex(0x1245)
+    ).toEqual('0x1245');
+  });
+
+  it('converts number to hex (specfified bitLength)', (): void => {
+    expect(
+      numberToHex(0x1245, 32)
+    ).toEqual('0x00001245');
+  });
+});

package/src/number/toHex.ts

@@ -0,0 +1,27 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { hexFixLength } from '../hex/fixLength.js';
+
+/**
+ * @name numberToHex
+ * @summary Creates a hex value from a number.
+ * @description
+ * `null`/`undefined`/`NaN` inputs returns an empty `0x` result. `number` input values return the actual bytes value converted to a `hex`. With `bitLength` set, it converts the number to the equivalent size.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { numberToHex } from '@pezkuwi/util';
+ *
+ * numberToHex(0x1234); // => '0x1234'
+ * numberToHex(0x1234, 32); // => 0x00001234
+ * ```
+ */
+export function numberToHex (value?: number | null, bitLength = -1): HexString {
+  const hex = (!value || Number.isNaN(value) ? 0 : value).toString(16);
+
+  return hexFixLength(hex.length % 2 ? `0${hex}` : hex, bitLength, true);
+}

package/src/number/toU8a.spec.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { numberToU8a } from './index.js';
+
+describe('numberToU8a', (): void => {
+  it('converts undefined to empty', (): void => {
+    expect(
+      numberToU8a()
+    ).toEqual(new Uint8Array(1));
+  });
+
+  it('converts null to empty', (): void => {
+    expect(
+      numberToU8a(null)
+    ).toEqual(new Uint8Array(1));
+  });
+
+  it('converts NaN to empty', (): void => {
+    expect(
+      numberToU8a(NaN)
+    ).toEqual(new Uint8Array(1));
+  });
+
+  it('converts 0 to u8a', (): void => {
+    expect(
+      numberToU8a(0)
+    ).toEqual(new Uint8Array([0]));
+  });
+
+  it('converts 0 to u8a (with length)', (): void => {
+    expect(
+      numberToU8a(0, 16)
+    ).toEqual(new Uint8Array([0, 0]));
+  });
+
+  it('converts values to the u8a', (): void => {
+    expect(
+      numberToU8a(0x3456)
+    ).toEqual(new Uint8Array([0x34, 0x56]));
+  });
+
+  it('converts values to the u8a (bitLength)', (): void => {
+    expect(
+      numberToU8a(0x3456, 32)
+    ).toEqual(new Uint8Array([0x00, 0x00, 0x34, 0x56]));
+  });
+});

package/src/number/toU8a.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { hexToU8a } from '../hex/toU8a.js';
+import { numberToHex } from './toHex.js';
+
+/**
+ * @name numberToU8a
+ * @summary Creates a Uint8Array object from a number.
+ * @description
+ * `null`/`undefined`/`NaN` inputs returns an empty `Uint8Array` result. `number` input values return the actual bytes value converted to a `Uint8Array`. With `bitLength`, it converts the value to the equivalent size.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { numberToU8a } from '@pezkuwi/util';
+ *
+ * numberToU8a(0x1234); // => [0x12, 0x34]
+ * ```
+ */
+export function numberToU8a (value?: number | null, bitLength = -1): Uint8Array {
+  return hexToU8a(
+    numberToHex(value, bitLength)
+  );
+}

package/src/object/clear.spec.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { objectClear } from './index.js';
+
+describe('objectClear', (): void => {
+  it('clears an object', (): void => {
+    expect(
+      objectClear({ a: 1, b: 2, c: { d: 3, e: 4 } })
+    ).toEqual({});
+  });
+});