@pezkuwi/util 14.0.7 → 14.0.10

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({});
+  });
+});

package/src/object/clear.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name objectClear
+ * @summary Removes all the keys from the input object
+ */
+export function objectClear <T> (value: Record<string, T>): Record<string, T> {
+  const keys = Object.keys(value);
+
+  for (let i = 0, count = keys.length; i < count; i++) {
+    delete value[keys[i]];
+  }
+
+  return value;
+}

package/src/object/copy.spec.ts

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

package/src/object/copy.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { objectSpread } from './spread.js';
+
+/**
+ * @name objectCopy
+ * @summary Creates a shallow clone of the input object
+ */
+export function objectCopy <T extends object> (source: T): T {
+  return objectSpread({}, source);
+}

package/src/object/entries.spec.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { objectEntries } from './index.js';
+
+describe('objectEntries', (): void => {
+  it('extracts all entries', (): void => {
+    const o = { a: 1, b: 2, c: 3 };
+    const entries = objectEntries(o);
+
+    expect(entries).toEqual([['a', 1], ['b', 2], ['c', 3]]);
+
+    for (const [k, v] of entries) {
+      expect(k).toBeDefined();
+      expect(v).toBeDefined();
+    }
+  });
+});

package/src/object/entries.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+type Entries<T> = { [K in keyof T]: [K, T[K]] }[keyof T][];
+
+/**
+ * @name objectEntries
+ * @summary A version of Object.entries that is typed for TS
+ */
+export function objectEntries<T extends object> (obj: T): Entries<T> {
+  return Object.entries(obj) as Entries<T>;
+}

package/src/object/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { objectClear } from './clear.js';
+export { objectCopy } from './copy.js';
+export { objectEntries } from './entries.js';
+export { objectKeys } from './keys.js';
+export { objectProperties, objectProperty } from './property.js';
+export { objectSpread } from './spread.js';
+export { objectValues } from './values.js';

package/src/object/keys.spec.ts

@@ -0,0 +1,19 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { objectKeys } from './index.js';
+
+describe('objectKeys', (): void => {
+  it('extracts all keys', (): void => {
+    const o = { a: 1, b: 2, c: 3 };
+    const keys = objectKeys(o);
+
+    expect(keys).toEqual(['a', 'b', 'c']);
+
+    for (const k of keys) {
+      expect(o[k]).toBeDefined();
+    }
+  });
+});

package/src/object/keys.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name objectKeys
+ * @summary A version of Object.keys that is typed for TS
+ */
+export function objectKeys<T extends object, K extends Extract<keyof T, string>> (value: T): K[] {
+  return Object.keys(value) as K[];
+}

package/src/object/property.spec.ts

@@ -0,0 +1,149 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { perf } from '../test/index.js';
+import { objectProperties, objectProperty } from './index.js';
+
+describe('objectProperty/objectProperties', (): void => {
+  it('sets a property', (): void => {
+    const test: { a?: unknown } = {};
+
+    expect(test.a).toEqual(undefined);
+
+    objectProperty(test, 'a', () => 2);
+
+    expect(Object.prototype.hasOwnProperty.call(test, 'a')).toBe(true);
+    expect('a' in test).toEqual(true);
+    expect(test.a).toEqual(2);
+  });
+
+  it('does not override an existing property (record)', (): void => {
+    const test = { a: 1 };
+
+    expect(test.a).toEqual(1);
+
+    objectProperty(test, 'a', () => 2);
+
+    expect(test.a).toEqual(1);
+  });
+
+  it('does not override an existing property (class)', (): void => {
+    class Test {
+      b = 1;
+
+      get a () {
+        return 1 + 0;
+      }
+    }
+
+    const test = new Test();
+
+    expect(test.a).toEqual(1);
+    expect(test.b).toEqual(1);
+
+    objectProperty(test, 'a', () => 2);
+    objectProperty(test, 'b', () => 2);
+
+    expect(test.a).toEqual(1);
+    expect(test.b).toEqual(1);
+  });
+
+  it('does not override an existing property (inherited)', (): void => {
+    class Parent extends Map<string, unknown> {
+      constructor () {
+        super();
+
+        this.set('a', 1);
+      }
+
+      get a (): unknown {
+        return this.get('a');
+      }
+    }
+
+    class Child extends Parent {
+      constructor () {
+        super();
+
+        this.set('b', 1);
+      }
+
+      get b (): unknown {
+        return this.get('b');
+      }
+    }
+
+    const test = new Child() as unknown as { a: number; b: number; c?: number };
+
+    expect(test.a).toEqual(1);
+    expect(test.b).toEqual(1);
+    expect(test.c).toEqual(undefined);
+
+    objectProperties(test, ['a', 'b', 'c'], () => 2);
+
+    expect(test.a).toEqual(1);
+    expect(test.b).toEqual(1);
+    expect(test.c).toEqual(2);
+  });
+
+  it('works with this used in classes', (): void => {
+    class Test extends Map<string, unknown> {
+      constructor () {
+        super();
+
+        this.set('a', 1);
+
+        objectProperty(this, 'a', (k) => this.get(k));
+      }
+    }
+
+    const test = new Test() as unknown as { a: number };
+
+    expect(test.a).toEqual(1);
+  });
+
+  it('works with this used in classes (multiples)', (): void => {
+    class Test extends Map<string, unknown> {
+      constructor () {
+        super();
+
+        this.set('a', 1);
+        this.set('b', 2);
+
+        objectProperties(this, ['a', 'b'], (k) => this.get(k));
+      }
+    }
+
+    const test = new Test() as unknown as { a: number; b: number };
+
+    expect(test.a).toEqual(1);
+    expect(test.b).toEqual(2);
+  });
+
+  it('calls back with the key name (single)', (): void => {
+    const test: { a?: number } = {};
+    const getter = jest.fn(() => 123);
+
+    objectProperty(test, 'a', getter);
+
+    expect(getter).not.toHaveBeenCalled();
+    expect(test.a).toEqual(123);
+    expect(getter).toHaveBeenCalledWith('a', 0, expect.objectContaining({}));
+  });
+
+  it('calls back with the key name & index (numtiple)', (): void => {
+    const test: { a?: number; b?: number; c?: number } = {};
+    const getter = jest.fn(() => 123);
+
+    objectProperties(test, ['a', 'b', 'c'], getter);
+
+    expect(getter).not.toHaveBeenCalled();
+    expect(test.b).toEqual(123);
+    expect(getter).toHaveBeenCalledWith('b', 1, expect.objectContaining({}));
+  });
+
+  perf('objectProperties (obj)', 50_000, [[]], () => objectProperties({}, ['foo', 'bar', 'baz'], (k) => k));
+  perf('objectProperties (map)', 50_000, [[]], () => objectProperties(new Map(), ['foo', 'bar', 'baz'], (k) => k));
+});

package/src/object/property.ts

@@ -0,0 +1,39 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name objectProperty
+ * @summary Assign a get property on the input object
+ */
+export function objectProperty <S> (that: object, key: string, getter: (key: string, index: number, self: S) => unknown, getName?: (key: string, index: number) => string, index = 0): void {
+  const name = getName
+    ? getName(key, index)
+    : key;
+
+  // There are 3 approaches here -
+  //  - Object.prototype.hasOwnProperty.call(that, key) - this only checks the current class, i.e
+  //    will retuirn false if the property is set in the parent class
+  //  - isUndefined(...) - this may yield a false positive when the property is there, but not set.
+  //    Additionally, on pre-defined getters it may make a call
+  //  - key in that - Does not need to be combined with either of the above and checks the full chain
+  if (!(name in that)) {
+    Object.defineProperty(that, name, {
+      enumerable: true,
+      // Unlike in lazy, we always call into the upper function, i.e. this method
+      // does not cache old values (it is expected to be used for dynamic values)
+      get: function (): unknown {
+        return getter(key, index, this as S);
+      }
+    });
+  }
+}
+
+/**
+ * @name objectProperties
+ * @summary Assign get properties on the input object
+ */
+export function objectProperties <S> (that: object, keys: string[], getter: (key: string, index: number, self: S) => unknown, getName?: (key: string, index: number) => string): void {
+  for (let i = 0, count = keys.length; i < count; i++) {
+    objectProperty(that, keys[i], getter, getName, i);
+  }
+}

package/src/object/spread.spec.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { perf } from '../test/index.js';
+import { objectSpread } from './index.js';
+
+describe('objectSpread', (): void => {
+  it('spreads obj sources', (): void => {
+    expect(
+      objectSpread({}, { a: 1, b: 2, c: 3 }, { d: 4, e: 5, f: 6 })
+    ).toEqual({ a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+  });
+
+  it('spreads map sources', (): void => {
+    expect(
+      objectSpread({}, new Map<string, number>([['a', 1], ['b', 2], ['c', 3]]), new Map<string, number>([['d', 4], ['e', 5], ['f', 6]]))
+    ).toEqual({ a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+  });
+
+  it('spreads an object from multiple sources', (): void => {
+    expect(
+      objectSpread({ a: 1 }, { b: 2 }, { a: 2, c: { d: 3, e: 4 } }, new Map<string, unknown>([['f', 5], ['g', 6], ['h', { i: 7, k: 8 }]]))
+    ).toEqual({ a: 2, b: 2, c: { d: 3, e: 4 }, f: 5, g: 6, h: { i: 7, k: 8 } });
+  });
+
+  it('spreads an object from multiple sources (with null & undefined)', (): void => {
+    expect(
+      objectSpread({ a: 1 }, null, { b: 2 }, undefined, { a: 2, c: { d: 3, e: 4 } })
+    ).toEqual({ a: 2, b: 2, c: { d: 3, e: 4 } });
+  });
+
+  perf('objectSpread (obj)', 350_000, [[{}, { a: 1, b: 2, c: 3 }, { d: 4, e: 5, f: 6 }]], objectSpread);
+  perf('objectSpread (map)', 350_000, [[{}, new Map<string, number>([['a', 1], ['b', 2], ['c', 3]]), new Map<string, number>([['d', 4], ['e', 5], ['f', 6]])]], objectSpread);
+});

package/src/object/spread.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name objectSpread
+ * @summary Concats all sources into the destination
+ * @description Spreads object properties while maintaining object integrity
+ */
+export function objectSpread <T extends object> (dest: object, ...sources: (object | undefined | null)[]): T {
+  const filterProps = new Set(['__proto__', 'constructor', 'prototype']);
+
+  for (let i = 0, count = sources.length; i < count; i++) {
+    const src = sources[i];
+
+    if (src) {
+      if (typeof (src as Map<string, unknown>).entries === 'function') {
+        for (const [key, value] of (src as Map<string, unknown>).entries()) {
+          if (!filterProps.has(key)) {
+            (dest as Record<string, unknown>)[key] = value;
+          }
+        }
+      } else {
+        // Create a clean copy of the source object
+        const sanitizedSrc = Object.create(null) as Record<string, unknown>;
+
+        for (const [key, value] of Object.entries(src)) {
+          if (!filterProps.has(key)) {
+            sanitizedSrc[key] = value;
+          }
+        }
+
+        Object.assign(dest, sanitizedSrc);
+      }
+    }
+  }
+
+  return dest as T;
+}

package/src/object/values.spec.ts

@@ -0,0 +1,19 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { objectValues } from './index.js';
+
+describe('objectValues', (): void => {
+  it('extracts all values', (): void => {
+    const o = { a: 1, b: 2, c: 3 };
+    const values = objectValues(o);
+
+    expect(values).toEqual([1, 2, 3]);
+
+    for (const v of values) {
+      expect(v).toBeDefined();
+    }
+  });
+});

package/src/object/values.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name objectValues
+ * @summary A version of Object.values that is typed for TS
+ */
+export function objectValues<T extends object> (obj: T): T[keyof T][] {
+  return Object.values(obj) as T[keyof T][];
+}

package/src/packageDetect.ts

@@ -0,0 +1,13 @@
+// Copyright 2017-2026 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Do not edit, auto-generated by @pezkuwi/dev
+// (packageInfo imports will be kept as-is, user-editable)
+
+import { packageInfo as decoderInfo } from '@pezkuwi/x-textdecoder';
+import { packageInfo as encoderInfo } from '@pezkuwi/x-textencoder';
+
+import { detectPackage } from './detectPackage.js';
+import { packageInfo } from './packageInfo.js';
+
+detectPackage(packageInfo, null, [decoderInfo, encoderInfo]);

package/src/packageInfo.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2026 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Do not edit, auto-generated by @pezkuwi/dev
+
+export const packageInfo = { name: '@pezkuwi/util', path: 'auto', type: 'auto', version: '14.0.10' };

package/src/promisify.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 { promisify } from './index.js';
+
+describe('promisify', (): void => {
+  it('handles functions with no parameters (resolve)', (): Promise<void> => {
+    const fn = (cb: (error: null, value: [boolean, string, number]) => void): void =>
+      cb(null, [true, 'test', 1]);
+
+    return promisify(null, fn).then((result): void => {
+      expect(result).toEqual([true, 'test', 1]);
+    });
+  });
+
+  it('handles functions with no parameters (reject)', (): Promise<void> => {
+    const fn = (cb: (error: Error, result?: boolean) => void): void =>
+      cb(new Error('test reject'));
+
+    return promisify(null, fn)
+      .then((): void => {
+        throw new Error('Received unexpected result');
+      })
+      .catch((error: Error): void => {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect(error.message).toEqual('test reject');
+      });
+  });
+
+  it('handles functions with parameters (resolve)', (): Promise<void> => {
+    const fn = (a: number, b: boolean, cb: (error: Error | null, result?: [number, boolean]) => void): void =>
+      cb(null, [a, b]);
+
+    return promisify(null, fn, 2, false).then((result: [number, boolean]): void => {
+      expect(result).toEqual([2, false]);
+    });
+  });
+
+  it('handles functions with parameters (reject)', (): Promise<void> => {
+    const fn = (a: number, b: boolean, c: string, cb: (error: Error | null, result?: [number, boolean, string]) => void): void =>
+      cb(new Error(`test reject: ${a},${b.toString()},${c}`));
+
+    return promisify(null, fn, 3, 'string', true).catch((error: Error): void => {
+      // eslint-disable-next-line jest/no-conditional-expect
+      expect(error.message).toEqual('test reject: 3,string,true');
+    });
+  });
+});