@pezkuwi/util 14.0.1

package/src/is/utf8.ts

@@ -0,0 +1,207 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Adapted from https://github.com/JulienPalard/is_utf8/blob/master/is_utf8.c
+
+import { u8aToU8a } from '../u8a/toU8a.js';
+import { isString } from './string.js';
+
+/**
+ * @name isUtf8
+ * @summary Tests if the input is valid Utf8
+ * @description
+ * Checks to see if the input string or Uint8Array is valid Utf8
+ */
+export function isUtf8 (value?: number[] | Uint8Array | string | null): boolean {
+  if (!value) {
+    return isString(value);
+  }
+
+  const u8a = u8aToU8a(value);
+  const len = u8a.length;
+  let i = 0;
+
+  while (i < len) {
+    if (u8a[i] <= 0x7F) /* 00..7F */ {
+      i += 1;
+    } else if (u8a[i] >= 0xC2 && u8a[i] <= 0xDF) /* C2..DF 80..BF */ {
+      if (i + 1 < len) /* Expect a 2nd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte between C2 and DF, expecting a 2nd byte between 80 and BF";
+          // *faulty_bytes = 2;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte between C2 and DF, expecting a 2nd byte.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 2;
+    } else if (u8a[i] === 0xE0) /* E0 A0..BF 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0xA0 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte of E0, expecting a 2nd byte between A0 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of E0, expecting a 3nd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of E0, expecting two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] >= 0xE1 && u8a[i] <= 0xEC) /* E1..EC 80..BF 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte between E1 and EC, expecting the 2nd byte between 80 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte between E1 and EC, expecting the 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte between E1 and EC, expecting two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] === 0xED) /* ED 80..9F 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0x9F) {
+          // *message = "After a first byte of ED, expecting 2nd byte between 80 and 9F.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of ED, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of ED, expecting two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] >= 0xEE && u8a[i] <= 0xEF) /* EE..EF 80..BF 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte between EE and EF, expecting 2nd byte between 80 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte between EE and EF, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte between EE and EF, two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] === 0xF0) /* F0 90..BF 80..BF 80..BF */ {
+      if (i + 3 < len) /* Expect a 2nd, 3rd 3th byte */ {
+        if (u8a[i + 1] < 0x90 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte of F0, expecting 2nd byte between 90 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of F0, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+
+        if (u8a[i + 3] < 0x80 || u8a[i + 3] > 0xBF) {
+          // *message = "After a first byte of F0, expecting 4th byte between 80 and BF.";
+          // *faulty_bytes = 4;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of F0, expecting three following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 4;
+    } else if (u8a[i] >= 0xF1 && u8a[i] <= 0xF3) /* F1..F3 80..BF 80..BF 80..BF */ {
+      if (i + 3 < len) /* Expect a 2nd, 3rd 3th byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte of F1, F2, or F3, expecting a 2nd byte between 80 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of F1, F2, or F3, expecting a 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+
+        if (u8a[i + 3] < 0x80 || u8a[i + 3] > 0xBF) {
+          // *message = "After a first byte of F1, F2, or F3, expecting a 4th byte between 80 and BF.";
+          // *faulty_bytes = 4;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of F1, F2, or F3, expecting three following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 4;
+    } else if (u8a[i] === 0xF4) /* F4 80..8F 80..BF 80..BF */ {
+      if (i + 3 < len) /* Expect a 2nd, 3rd 3th byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0x8F) {
+          // *message = "After a first byte of F4, expecting 2nd byte between 80 and 8F.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of F4, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+
+        if (u8a[i + 3] < 0x80 || u8a[i + 3] > 0xBF) {
+          // *message = "After a first byte of F4, expecting 4th byte between 80 and BF.";
+          // *faulty_bytes = 4;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of F4, expecting three following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 4;
+    } else {
+      // *message = "Expecting bytes in the following ranges: 00..7F C2..F4.";
+      // *faulty_bytes = 1;
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/is/wasm.spec.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { isWasm } from './index.js';
+
+describe('isWasm', (): void => {
+  it('is false on no value', (): void => {
+    expect(isWasm()).toEqual(false);
+  });
+
+  it('is false on non-wasm header', (): void => {
+    expect(isWasm(new Uint8Array([1, 2, 3]))).toEqual(false);
+  });
+
+  it('is true when a wasm header is found', (): void => {
+    expect(isWasm(new Uint8Array([0, 97, 115, 109, 1, 2, 3]))).toEqual(true);
+  });
+});

package/src/is/wasm.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aEq } from '../u8a/eq.js';
+import { isU8a } from './u8a.js';
+
+const WASM_MAGIC = new Uint8Array([0, 97, 115, 109]); // \0asm
+
+/**
+ * @name isWasm
+ * @summary Tests if the input has a WASM header
+ * @description
+ * Checks to see if the input Uint8Array contains a valid WASM header
+ */
+export function isWasm (value?: unknown): value is Uint8Array {
+  return isU8a(value) && u8aEq(value.subarray(0, 4), WASM_MAGIC);
+}

package/src/lazy.spec.ts

@@ -0,0 +1,71 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { lazyMethod, lazyMethods } from './index.js';
+
+describe('lazyMethod', (): void => {
+  it('adds a key on the object', (): void => {
+    const test: { a?: number } = {};
+
+    expect(test.a).not.toBeDefined();
+
+    lazyMethod(test, 'a', () => 123);
+
+    expect(test.a).toEqual(123);
+  });
+
+  it('allows the name to be retrieved', (): void => {
+    const test: { a?: number } = {};
+
+    expect(test.a).not.toBeDefined();
+
+    lazyMethod(test, 456, () => 123, () => 'a');
+
+    expect(test.a).toEqual(123);
+  });
+
+  it('calls the getter lazily', (): void => {
+    const test: { a?: number } = {};
+    const getter = jest.fn(() => 123);
+
+    expect(test.a).not.toBeDefined();
+
+    lazyMethod(test, 'a', getter);
+
+    expect(Object.prototype.hasOwnProperty.call(test, 'a')).toEqual(true);
+    expect(getter).not.toHaveBeenCalled();
+    expect(test.a).toEqual(123);
+    expect(getter).toHaveBeenCalledWith('a', 0, expect.objectContaining({}));
+  });
+
+  it('calls the getter a single time', (): void => {
+    const test: { a?: number } = {};
+    const getter = jest.fn(() => 123);
+
+    lazyMethod(test, 'a', getter);
+
+    expect(getter).not.toHaveBeenCalled();
+    expect(test.a).toEqual(123);
+    expect(getter).toHaveBeenCalledWith('a', 0, expect.objectContaining({}));
+    expect(test.a).toEqual(123);
+    expect(getter).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('lazyMethods', (): void => {
+  it('sets multiple properties', (): void => {
+    const test: { a?: string; b?: string; c?: string } = {};
+    const getter = jest.fn((name: string) => name);
+
+    lazyMethods(test, ['a', 'b', 'c'], getter);
+
+    expect(test.a).toEqual('a');
+    expect(test.b).toEqual('b');
+    expect(getter).toHaveBeenCalledTimes(2);
+    expect(test.a).toEqual('a');
+    expect(test.b).toEqual('b');
+    expect(getter).toHaveBeenCalledTimes(2);
+  });
+});

package/src/lazy.ts

@@ -0,0 +1,63 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+interface WithToString { toString: () => string }
+
+/**
+ * @name lazyMethod
+ * @description
+ * Creates a lazy, on-demand getter for the specific value. Upon get the value will be evaluated.
+ */
+export function lazyMethod <T, K, S> (result: Record<string, T> | AnyFn, item: K, creator: (item: K, index: number, self: S) => T, getName?: (item: K, index: number) => string, index = 0): void {
+  const name = getName
+    ? getName(item, index)
+    : (item as WithToString).toString();
+  let value: T | undefined;
+
+  Object.defineProperty(result, name, {
+    // This allows for re-configuration with the embedded defineProperty below
+    // and ensures that on tested browsers and Node, it _will_ be redefined
+    // and thus short-circuited for future access
+    configurable: true,
+    enumerable: true,
+
+    // Use a function here, we don't want to capture the outer this, i.e.
+    // don't use arrow functions in this context since we have a this inside
+    get: function (): T {
+      // This check should _always_ be false and unneeded, since we override
+      // with a value below ... however we ensure we are quire vigilant against
+      // all environment failures, so we are rather be safe than sorry
+      if (value === undefined) {
+        value = creator(item, index, this as S);
+
+        try {
+          // re-define the property as a value, next time around this
+          // getter will only return the computed value
+          Object.defineProperty(this, name, { value });
+        } catch {
+          // ignore any errors, since this _should_ not happen due to
+          // the "configurable" property above. But if it ever does
+          // from here-on we will be the cached value the next time
+          // around (with a very slight dip in performance)
+        }
+      }
+
+      return value;
+    }
+  });
+}
+
+/**
+ * @name lazyMethods
+ * @description
+ * Creates lazy, on-demand getters for the specific values.
+ */
+export function lazyMethods <T, K, S> (result: Record<string, T>, items: readonly K[], creator: (item: K, index: number, self: S) => T, getName?: (item: K, index: number) => string): Record<string, T> {
+  for (let i = 0, count = items.length; i < count; i++) {
+    lazyMethod(result, items[i], creator, getName, i);
+  }
+
+  return result;
+}

package/src/logger.spec.ts

@@ -0,0 +1,188 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/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();
+  });
+});