@wener/utils 1.1.6 → 1.1.8

package/src/io/ArrayBuffers.ts

@@ -0,0 +1,288 @@
+import { classOf } from '../langs/classOf';
+import { isBuffer } from './isBuffer';
+
+/**
+ * Various utils to work with {@link ArrayBuffer}
+ */
+export interface ArrayBuffers {
+  /**
+   * isArrayBuffer check if the given value is an {@link ArrayBuffer}
+   */
+  isArrayBuffer(v: any): v is ArrayBuffer;
+
+  /**
+   * slice the given view with the given offset and length, will handle the {@link Buffer} as well
+   *
+   * @see {@link https://nodejs.org/api/buffer.html#bufslicestart-end Buffer.slice}
+   */
+  slice<T extends ArrayBufferView>(o: T, start?: number, end?: number): T;
+
+  /**
+   * asView convert the given value to given {@link TypedArray} view
+   *
+   * TypedArray can be {@link Buffer}, will avoid copy
+   */
+  asView<C extends ArrayBufferViewConstructor<unknown>>(
+    TypedArray: C,
+    v: BufferSource,
+    byteOffset?: number,
+    byteLength?: number,
+  ): InstanceType<C>;
+
+  /**
+   * toString convert the given {@link BufferSource} to string
+   */
+  toString(v: BufferSource | string, encoding?: ToStringEncoding): string;
+
+  /**
+   * Returns true if encoding is the name of a supported character encoding, or false otherwise.
+   */
+  isEncoding(v?: string): v is ToStringEncoding;
+
+  toJSON<T = any>(v: BufferSource | string, reviver?: (this: any, key: string, value: any) => any): T;
+
+  /**
+   * from convert the given value to {@link ArrayBuffer}
+   */
+  from(v: string | BufferSource, encoding?: ToStringEncoding): ArrayBuffer;
+
+  /**
+   * concat the given {@link BufferSource} to a new {@link ArrayBuffer}
+   */
+  concat(buffers: Array<BufferSource>, result?: ArrayBuffer, offset?: number): ArrayBuffer;
+}
+
+type ToStringEncoding =
+  | 'ascii'
+  | 'utf16le'
+  // | 'utf-16le'
+  | 'ucs2'
+  | 'ucs-2'
+  | 'base64'
+  | 'base64url'
+  | 'latin1'
+  | 'binary'
+  | 'utf8'
+  | 'utf-8'
+  | 'hex';
+
+export class ArrayBuffers {
+  static #_allowedNativeBuffer: boolean = true;
+
+  static #isNativeBufferValid() {
+    return this.#_allowedNativeBuffer && !(globalThis.Buffer as any)?.isPollyfill?.();
+  }
+
+  static setAllowedNativeBuffer(v: boolean) {
+    this.#_allowedNativeBuffer = v;
+  }
+
+  static isArrayBuffer = (v: any): v is ArrayBuffer => {
+    return v instanceof ArrayBuffer;
+  };
+
+  static slice = (o: TypedArray, start?: number, end?: number) => {
+    // NodeJS Buffer slice is not the same as UInt8Array slice
+    // https://nodejs.org/api/buffer.html#bufslicestart-end
+    if (isBuffer(o)) {
+      return Uint8Array.prototype.slice.call(o, start, end);
+    }
+    return o.slice(start, end);
+  };
+
+  static asView = <C extends ArrayBufferViewConstructor<unknown>, I extends InstanceType<C>>(
+    TypedArray: C,
+    v: BufferSource,
+    byteOffset?: number,
+    byteLength?: number,
+  ): I => {
+    if (v instanceof TypedArray && (byteOffset ?? 0) === 0 && byteLength === undefined) {
+      return v as I;
+    }
+    if (ArrayBuffer.isView(v) || isBuffer(v)) {
+      if (ArrayBuffers.#isNativeBufferValid() && (TypedArray as any) === Buffer) {
+        // new Buffer() is deprecated
+        return Buffer.from(v.buffer, byteOffset, byteLength) as I;
+      }
+      return new TypedArray(v.buffer, v.byteOffset + (byteOffset ?? 0), byteLength ?? v.byteLength) as I;
+    }
+    return new TypedArray(v, byteOffset, byteLength) as I;
+  };
+
+  static toString = (buf: BufferSource | string, encoding: ToStringEncoding = 'utf8') => {
+    // 'ascii'  'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex'
+    if (typeof buf === 'string') {
+      return buf;
+    }
+    if (ArrayBuffers.#isNativeBufferValid()) {
+      return Buffer.from(ArrayBuffers.asView(Uint8Array, buf)).toString(encoding);
+    }
+    // reference
+    // https://github.com/feross/buffer/blob/master/index.js
+    switch (encoding) {
+      case 'hex': {
+        const view: Uint8Array = ArrayBuffers.asView(Uint8Array, buf);
+        return [...view].map((b) => hexLookupTable[b]).join('');
+      }
+      case 'base64': {
+        const view: Uint8Array = ArrayBuffers.asView(Uint8Array, buf);
+        return btoa(String.fromCharCode(...view));
+      }
+      case 'utf8':
+      // falls through
+      case 'utf-8':
+        return new TextDecoder().decode(buf as any);
+      case 'ascii': {
+        const view: Uint8Array = ArrayBuffers.asView(Uint8Array, buf);
+        return String.fromCharCode(...view.map((v) => v & 0x7f));
+      }
+      case 'latin1':
+      // falls through
+      case 'binary': {
+        const view: Uint8Array = ArrayBuffers.asView(Uint8Array, buf);
+        return String.fromCharCode(...view);
+      }
+      case 'ucs2':
+      // falls through
+      case 'ucs-2':
+      // case 'utf-16le':
+      // falls through
+      case 'utf16le': {
+        const view: Uint8Array = ArrayBuffers.asView(Uint8Array, buf);
+        let res = '';
+        // If length is odd, the last 8 bits must be ignored (same as node.js)
+        for (let i = 0; i < view.length - 1; i += 2) {
+          res += String.fromCharCode(view[i] + view[i + 1] * 256);
+        }
+        return res;
+      }
+      default:
+        throw new Error(`[ArrayBuffers.toString] Unknown encoding: ${encoding}`);
+    }
+  };
+
+  static toJSON = (v: BufferSource | string, reviver?: (this: any, key: string, value: any) => any) => {
+    return JSON.parse(ArrayBuffers.toString(v), reviver);
+  };
+
+  static alloc = (size: number, fill?: string | number, encoding?: ToStringEncoding) => {
+    if (fill !== undefined) {
+      if (typeof fill === 'number') {
+        return new Uint8Array(size).fill(fill);
+      }
+      // as cast
+      // https://stackoverflow.com/questions/73994091
+      return ArrayBuffers.asView(Uint8Array, ArrayBuffers.from(fill, encoding)).slice(0, size);
+    }
+    return new ArrayBuffer(size);
+  };
+
+  static from = (
+    v: string | BufferSource | ArrayLike<number> | Iterable<number>,
+    encoding: ToStringEncoding = 'utf8',
+  ): BufferSource => {
+    if (!v) {
+      return new ArrayBuffer(0);
+    }
+    if (typeof v === 'string') {
+      if (ArrayBuffers.#isNativeBufferValid()) {
+        return Buffer.from(v, encoding);
+      }
+
+      switch (encoding) {
+        case 'utf-8':
+        // falls through
+        case 'utf8':
+          return new TextEncoder().encode(v).buffer;
+        case 'base64':
+          // replaceAll
+          return Uint8Array.from(atob(v.replace(/[^0-9a-zA-Z=+/_ \r\n]/g, '')), (c) => c.charCodeAt(0));
+        default:
+          throw new Error(`[ArrayBuffers.from] Unknown encoding: ${encoding}`);
+      }
+    }
+    if (v instanceof ArrayBuffer) {
+      return v;
+    }
+    // lost length
+    if (ArrayBuffer.isView(v) || isBuffer(v)) {
+      if (v.byteOffset !== 0) {
+        // return v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength)
+        throw new Error('ArrayBuffers.from do not support view with offset');
+      }
+      return v.buffer;
+    }
+    if (Array.isArray(v)) {
+      return new Uint8Array(v);
+    }
+    const type = classOf(v);
+    throw new TypeError(`ArrayBuffers.from unsupported type ${type}`);
+  };
+
+  static isEncoding = (encoding?: string) => {
+    switch (String(encoding).toLowerCase()) {
+      case 'hex':
+      case 'utf8':
+      case 'utf-8':
+      case 'ascii':
+      case 'latin1':
+      case 'binary':
+      case 'base64':
+      case 'ucs2':
+      case 'ucs-2':
+      case 'utf16le':
+        // case 'utf-16le':
+        return true;
+      default:
+        return false;
+    }
+  };
+
+  static concat = (buffers: Array<BufferSource>, result?: ArrayBuffer, offset = 0) => {
+    // https://stackoverflow.com/questions/10786128/appending-arraybuffers
+
+    const length = buffers.reduce((a, b) => a + b.byteLength, 0);
+    const r = result ? new Uint8Array(result) : new Uint8Array(length);
+    for (const buffer of buffers) {
+      if (!buffer || !buffer.byteLength) continue;
+      let n: Uint8Array;
+      if (buffer instanceof ArrayBuffer) {
+        n = new Uint8Array(buffer);
+      } else if (ArrayBuffer.isView(buffer)) {
+        n = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+      } else {
+        throw new Error(`ArrayBuffers.concat unsupported type ${classOf(buffer)}`);
+      }
+      r.set(n, offset);
+      offset += buffer.byteLength;
+    }
+    return r.buffer;
+  };
+}
+
+export type TypedArray =
+  | Uint8Array
+  | Uint8ClampedArray
+  | Uint16Array
+  | Uint32Array
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | BigUint64Array
+  | BigInt64Array
+  | Float32Array
+  | Float64Array;
+
+type ArrayBufferViewConstructor<T> = new (buffer: ArrayBufferLike, byteOffset?: number, byteLength?: number) => T;
+
+const hexLookupTable = (function () {
+  const alphabet = '0123456789abcdef';
+  const table = new Array(256);
+  for (let i = 0; i < 16; ++i) {
+    const i16 = i * 16;
+    for (let j = 0; j < 16; ++j) {
+      table[i16 + j] = alphabet[i] + alphabet[j];
+    }
+  }
+  return table;
+})();

package/src/io/Buffer.test.ts

@@ -0,0 +1,23 @@
+import test from 'ava';
+import { Buffer } from './Buffer';
+import { isBuffer } from './isBuffer';
+
+test('basic', (t) => {
+  {
+    const buf = new Buffer(0);
+    t.true(Buffer.isBuffer(buf));
+    t.true(isBuffer(buf));
+  }
+  // const b = new Buffer(10)
+  // t.is(b.length,10)
+  // t.is(b.byteLength,10)
+  // t.is(b.byteOffset,0)
+  // t.is(b.buffer.byteLength,10)
+  // t.is(b.buffer.byteOffset,0)
+  // t.is(b.buffer.length,1)
+  // t.is(b.buffer[0].byteLength,10)
+  // t.is(b.buffer[0].byteOffset,0)
+  // t.is(b.buffer[0].length,10)
+  // t.is(b.buffer[0][0],0)
+  // t.is(b.buffer[0][9],0)
+});

package/src/io/Buffer.ts

@@ -0,0 +1,30 @@
+import { ArrayBuffers } from './ArrayBuffers';
+import { isBuffer } from './isBuffer';
+
+/**
+ * Buffer is a polyfill version of NodeJS Buffer
+ */
+export class Buffer extends Uint8Array {
+  // constructor(buffer: ArrayBufferLike, byteOffset?: number, length?: number) {
+  //   super(buffer, byteOffset, length);
+  // }
+
+  static get isPolyfill() {
+    return true;
+  }
+
+  static isBuffer(v: any): v is Buffer {
+    return v instanceof Buffer || isBuffer(v);
+  }
+
+  static from(array: string | BufferSource | ArrayLike<number> | Iterable<number>, arg2?: any): Buffer {
+    // todo mapfn
+    return new Buffer(ArrayBuffers.from(array, arg2) as ArrayBuffer);
+  }
+
+  static isEncoding = ArrayBuffers.isEncoding;
+
+  toString(encoding?: string): string {
+    return ArrayBuffers.toString(this, encoding as any);
+  }
+}

package/src/io/isBuffer.test.ts

@@ -1,7 +1,9 @@
 import test from 'ava';
 import { Buffer } from 'node:buffer';
+import { classOf } from '../langs/classOf';
 import { isBuffer } from './isBuffer';
 
 test('isBuffer', (t) => {
   t.true(isBuffer(Buffer.from('')));
+  t.is(classOf(Buffer), 'Function');
 });

package/src/io/isBuffer.ts

@@ -1,13 +1,8 @@
 /**
- * check {@code obj} is Buffer
+ * check {@link obj} is Buffer
  *
- * {@link https://github.com/feross/is-buffer feross/is-buffer}
+ * @see {@link https://github.com/feross/is-buffer feross/is-buffer}
  */
 export function isBuffer(obj: any): obj is Buffer {
-  return (
-    obj != null &&
-    obj.constructor != null &&
-    typeof obj.constructor.isBuffer === 'function' &&
-    obj.constructor.isBuffer(obj)
-  );
+  return obj?.constructor?.isBuffer?.(obj);
 }

package/src/io/isTransferable.ts

@@ -3,7 +3,7 @@
  *
  * - Chrome 87, FF 103, Safari X, NodeJS X
  *
- * {@link https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects | Transferable objects}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects | Transferable objects}
  */
 export function isTransferable(v: any): v is TransferableObject {
   _ctors ||= ctors();

package/src/isomorphics/structuredClone.test.ts

@@ -7,7 +7,7 @@ test('structuredClone', (t) => {
     ['', ''],
     [Number(1), 1],
   ]) {
-    let c = _clone(k);
+    const c = _clone(k);
     t.deepEqual(c, v);
     t.is(classOf(c), classOf(v));
   }

package/src/isomorphics/structuredClone.ts

@@ -1,11 +1,14 @@
+/* eslint no-proto:0 */
+import { classOf } from '../langs/classOf';
+
 /**
- * Chrome 98, Safari 15.4
+ * Clone an object using structured cloning algorithm
+ *
+ * - Chrome 98, Safari 15.4, NodeJS 17
  *
- * {@link https://developer.mozilla.org/en-US/docs/Web/API/structuredClone structuredClone}
- * {@link https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/web.structured-clone.js core-js}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/structuredClone structuredClone}
+ * @see {@link https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/web.structured-clone.js core-js}
  */
-import { classOf } from '../langs/classOf';
-
 export const structuredClone: <T>(value: T, options?: StructuredSerializeOptions) => T =
   globalThis.structuredClone || _clone;
 
@@ -17,7 +20,7 @@ function set(obj: any, key: any, val: any) {
 }
 
 /**
- * {@link https://github.com/lukeed/klona/blob/master/src/full.js klona}
+ * @see {@link https://github.com/lukeed/klona/blob/master/src/full.js klona}
  */
 export function _clone(x: any): any {
   // too complex

package/src/langs/deepEqual.ts

@@ -101,5 +101,6 @@ export function deepEqual(foo: any, bar: any) {
     }
   }
 
+  // eslint-disable-next-line no-self-compare
   return foo !== foo && bar !== bar;
 }

package/src/langs/shallowClone.ts

@@ -0,0 +1,13 @@
+export function shallowClone<T>(obj: T): T {
+  if (!obj) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.slice() as T;
+  }
+  if (typeof obj === 'object') {
+    return Object.assign({}, obj);
+  }
+  // skip Map, Set, WeakMap, WeakSet, Date, RegExp, etc.
+  return obj;
+}

package/src/langs/shallowEqual.ts

@@ -16,7 +16,7 @@ export function shallowEqual<T, U>(objA: T, objB: U) {
   }
   for (let i = 0; i < keysA.length; i++) {
     if (
-      !Object.prototype.hasOwnProperty.call(objB, keysA[i] as string) ||
+      !Object.prototype.hasOwnProperty.call(objB, keysA[i]) ||
       !Object.is(objA[keysA[i] as keyof T], objB[keysA[i] as keyof U])
     ) {
       return false;

package/src/logging/Logger.ts

@@ -1,3 +1,6 @@
+/**
+ * Logger interface satisfies the `console`, `pino` logger interface.
+ */
 export interface Logger {
   trace(...data: any[]): void;
 
@@ -9,6 +12,9 @@ export interface Logger {
 
   error(...data: any[]): void;
 
+  /**
+   * create child logger with given context
+   */
   child?: (o: object) => Logger;
 }
 

package/src/logging/createChildLogger.ts

@@ -1,4 +1,4 @@
-import { Logger, LoggerWithChild } from './Logger';
+import type { Logger, LoggerWithChild } from './Logger';
 import { createWriteLogger } from './createWriteLogger';
 
 export function createChildLogger(l: Logger, ctx: object): LoggerWithChild {

package/src/logging/createNoopLogger.ts

@@ -1,7 +1,7 @@
-import { LoggerWithChild } from './Logger';
+import type { LoggerWithChild } from './Logger';
 
 export function createNoopLogger(): LoggerWithChild {
-  const noop = (..._: any[]) => void 0;
+  const noop = (..._: any[]) => undefined;
   return {
     trace: noop,
     debug: noop,

package/src/logging/createWriteLogger.ts

@@ -1,4 +1,4 @@
-import { LoggerWithChild, LogLevel } from './Logger';
+import type { LoggerWithChild, LogLevel } from './Logger';
 
 export function createWriteLogger(
   write: (o: { level: LogLevel; values: any[] } & Record<string | symbol, any>) => void,

package/src/logging/logger.test.ts

@@ -4,9 +4,9 @@ import { createWriteLogger } from './createWriteLogger';
 
 test('logger', (t) => {
   {
-    let logs: any[] = [];
+    const logs: any[] = [];
     const base = createWriteLogger((o) => logs.push(o));
-    let l = createChildLogger(base, { c: 'test' });
+    const l = createChildLogger(base, { c: 'test' });
     l.info('hello');
     t.deepEqual(logs.shift(), { level: 'info', values: ['hello'], c: 'test' });
     l.child({ m: 1 }).trace('trace');
@@ -15,7 +15,7 @@ test('logger', (t) => {
   createChildLogger(console, { c: 'test' }).info('hello');
   {
     let pass = 0;
-    let l = createWriteLogger(
+    const l = createWriteLogger(
       (o) => {
         pass++;
         t.log(`${o.level}: [${[o.m, o.c].filter(Boolean).join('.') || 'default'}]`, ...o.values);

package/src/modules/isModule.ts

@@ -1,3 +1,6 @@
+/**
+ * Check is ESM Module
+ */
 export function isModule(o: any): o is Module {
   return o && o[Symbol.toStringTag] === 'Module';
 }

package/src/modules/parseModuleId.test.ts

@@ -10,6 +10,7 @@ test('parseModuleId', (t) => {
       scoped: true,
       org: 'wener',
       pkg: 'reaction',
+      versioned: false,
     },
     reaction: {
       id: `reaction@latest`,
@@ -17,6 +18,7 @@ test('parseModuleId', (t) => {
       range: 'latest',
       pkg: 'reaction',
       scoped: false,
+      versioned: false,
     },
     'reaction@1': {
       id: `reaction@1`,
@@ -24,6 +26,7 @@ test('parseModuleId', (t) => {
       range: '1',
       pkg: 'reaction',
       scoped: false,
+      versioned: true,
     },
     'reaction@1.1.1': {
       id: `reaction@1.1.1`,
@@ -32,6 +35,7 @@ test('parseModuleId', (t) => {
       range: '1.1.1',
       pkg: 'reaction',
       scoped: false,
+      versioned: true,
     },
     'reaction@1.1.1-alpha': {
       id: `reaction@1.1.1-alpha`,
@@ -39,7 +43,7 @@ test('parseModuleId', (t) => {
       version: '1.1.1-alpha',
       range: '1.1.1-alpha',
       pkg: 'reaction',
-
+      versioned: true,
       scoped: false,
     },
     'reaction@1.1.1/index.js': {
@@ -49,7 +53,7 @@ test('parseModuleId', (t) => {
       range: '1.1.1',
       scoped: false,
       pkg: 'reaction',
-
+      versioned: true,
       path: '/index.js',
     },
     'reaction@1.1.1/': {
@@ -60,6 +64,7 @@ test('parseModuleId', (t) => {
       scoped: false,
       pkg: 'reaction',
       path: '/',
+      versioned: true,
     },
   };
   for (const [k, v] of Object.entries(tests)) {

package/src/modules/parseModuleId.ts

@@ -9,18 +9,22 @@ export type ParsedModuleId = {
   range: string; // version, tag, range
   pkg: string;
   path?: string;
+  org?: string;
+  versioned: boolean; // is module id contain a version specifier
 } & (
   | { scoped: false }
   | {
       scoped: true;
-      org?: string;
+      org: string;
     }
 );
 
 /**
  * Parse NPM module id
  *
- *    parseModuleId('@wener/reaction@latest/index.js') // => { id: '@wener/reaction@latest', name: '@wener/reaction', version: 'latest', range: 'latest', pkg: 'reaction', path: '/index.js', scoped: true, org: 'wener' }
+ * @example
+ * parseModuleId('@wener/reaction@latest/index.js')
+ * // { id: '@wener/reaction@latest', name: '@wener/reaction', version: 'latest', range: 'latest', pkg: 'reaction', path: '/index.js', scoped: true, org: 'wener' }
  */
 export function parseModuleId(s: string): ParsedModuleId | undefined {
   const groups = s.match(regModuleId)?.groups;
@@ -28,24 +32,26 @@ export function parseModuleId(s: string): ParsedModuleId | undefined {
     return undefined;
   }
   const { n: name, v: version, p: path, org, pkg } = groups;
-  let scoped = Boolean(org);
+  const scoped = Boolean(org);
   const v = /^\d+\.\d+\.\d+/.test(version) ? version : undefined;
-  let range = version || 'latest';
-  const o = {
+  const range = version || 'latest';
+  const o: ParsedModuleId = {
     id: `${name}@${range}`,
     name,
-    range: range,
+    range,
     scoped,
     pkg,
-  } as ParsedModuleId;
+    org,
+    versioned: Boolean(version),
+  };
   if (v) {
     o.version = v;
   }
   if (path) {
     o.path = path;
   }
-  if (o.scoped) {
-    o.org = org;
+  if (!o.scoped) {
+    delete o.org;
   }
   return o;
 }