@naturalcycles/js-lib 15.94.1 → 15.96.0

package/dist/array/array.util.d.ts

@@ -1,4 +1,4 @@
-import type { AbortablePredicate, FalsyValue, Mapper, MutateOptions, Predicate, StringMap } from '../types.js';
+import type { AbortablePredicate, FalsyValue, Mapper, MutateOptions, NonEmptyArray, Predicate, StringMap } from '../types.js';
 /**
  * Creates an array of elements split into groups the length of size. If collection can’t be split evenly, the
  * final chunk will be the remaining elements.
@@ -11,7 +11,7 @@ import type { AbortablePredicate, FalsyValue, Mapper, MutateOptions, Predicate,
  *
  * Based on: https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_chunk
  */
-export declare function _chunk<T>(array: readonly T[], size?: number): T[][];
+export declare function _chunk<T>(array: readonly T[], size?: number): NonEmptyArray<T>[];
 /**
  * Removes duplicates from given array.
  */
@@ -89,7 +89,7 @@ export declare function _mapBy<ITEM, KEY>(items: readonly ITEM[], mapper: Mapper
  *
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
-export declare function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]>;
+export declare function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<NonEmptyArray<T>>;
 /**
  * Similar to `Array.find`, but the `predicate` may return `END` to stop the iteration early.
  *
@@ -217,6 +217,12 @@ export declare function _first<T>(array: readonly T[]): T;
  * Returns first item of the array (or undefined if array is empty).
  */
 export declare function _firstOrUndefined<T>(array: readonly T[]): T | undefined;
+/**
+ * Type guard that narrows an array to NonEmptyArray (array with at least one element).
+ * Readonly arrays are narrowed to `Readonly<NonEmptyArray<T>>`.
+ */
+export declare function _isNonEmptyArray<T>(array: T[]): array is NonEmptyArray<T>;
+export declare function _isNonEmptyArray<T>(array: readonly T[]): array is Readonly<NonEmptyArray<T>>;
 /**
  * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
  * Throws if the iterable is empty.

package/dist/array/array.util.js

@@ -144,9 +144,14 @@ export function _groupBy(items, mapper) {
     const map = {};
     for (const item of items) {
         const key = mapper(item);
-        if (key !== undefined) {
-            ;
-            (map[key] ||= []).push(item);
+        if (key === undefined)
+            continue;
+        const group = map[key];
+        if (group) {
+            group.push(item);
+        }
+        else {
+            map[key] = [item];
         }
     }
     return map;
@@ -403,6 +408,9 @@ export function _first(array) {
 export function _firstOrUndefined(array) {
     return array[0];
 }
+export function _isNonEmptyArray(array) {
+    return array.length > 0;
+}
 /**
  * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
  * Throws if the iterable is empty.

package/dist/buffer/buffer.util.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns an ArrayBuffer that contains exactly the bytes of the given view (e.g Uint8Array or Buffer).
+ *
+ * Safe alternative to `view.buffer`, which returns the whole underlying ArrayBuffer.
+ * It can be larger than the view, and the view may start at a non-zero offset:
+ * e.g Node.js allocates small Buffers from a shared pool (`Buffer.from(string)`,
+ * `fs.readFileSync` of small files), or the view was created with `subarray()`.
+ *
+ * Zero-copy when the view covers the whole ArrayBuffer, otherwise copies exactly its bytes.
+ */
+export declare function _toArrayBuffer<T extends ArrayBufferLike>(view: ArrayBufferView<T>): T;
+/**
+ * Same as _chunk, but for Uint8Array (or Buffer).
+ * Chunks are zero-copy views (subarray) into the input, and preserve its type
+ * (e.g Buffer in - Buffer[] out).
+ */
+export declare function _chunkBuffer<T extends Uint8Array>(buf: T, size: number): T[];

package/dist/buffer/buffer.util.js

@@ -0,0 +1,29 @@
+/**
+ * Returns an ArrayBuffer that contains exactly the bytes of the given view (e.g Uint8Array or Buffer).
+ *
+ * Safe alternative to `view.buffer`, which returns the whole underlying ArrayBuffer.
+ * It can be larger than the view, and the view may start at a non-zero offset:
+ * e.g Node.js allocates small Buffers from a shared pool (`Buffer.from(string)`,
+ * `fs.readFileSync` of small files), or the view was created with `subarray()`.
+ *
+ * Zero-copy when the view covers the whole ArrayBuffer, otherwise copies exactly its bytes.
+ */
+export function _toArrayBuffer(view) {
+    const { buffer, byteOffset, byteLength } = view;
+    if (byteOffset === 0 && byteLength === buffer.byteLength)
+        return buffer;
+    return buffer.slice(byteOffset, byteOffset + byteLength);
+}
+/**
+ * Same as _chunk, but for Uint8Array (or Buffer).
+ * Chunks are zero-copy views (subarray) into the input, and preserve its type
+ * (e.g Buffer in - Buffer[] out).
+ */
+export function _chunkBuffer(buf, size) {
+    const out = [];
+    for (let i = 0; i < buf.length; i += size) {
+        // subarray preserves the subclass at runtime (Buffer#subarray returns a Buffer)
+        out.push(buf.subarray(i, i + size));
+    }
+    return out;
+}

package/dist/buffer/index.d.ts

@@ -0,0 +1 @@
+export * from './buffer.util.js';

package/dist/buffer/index.js

@@ -0,0 +1 @@
+export * from './buffer.util.js';

package/dist/types.d.ts

@@ -181,6 +181,17 @@ export interface BatchResult<RES = any, ERR = Error> {
  * type Foo = ValuesOf<typeof arr> // 'a' | 'b'
  */
 export type ValuesOf<T extends readonly any[]> = T[number];
+/**
+ * Array with at least one element.
+ * Index 0 is typed as `T` (not `T | undefined`) under `noUncheckedIndexedAccess`.
+ *
+ * Use `_isNonEmptyArray` to narrow a regular array to it.
+ *
+ * Caveats:
+ * - Mutating methods (pop, shift, splice, `length = 0`) can empty it without the type noticing.
+ * - Non-emptiness is lost after map, filter, slice, concat (they return `T[]`). Spread preserves it.
+ */
+export type NonEmptyArray<T> = [T, ...T[]];
 /**
  * Based on: https://stackoverflow.com/a/49286056/4919972
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.94.1",
+  "version": "15.96.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -28,6 +28,8 @@
     "./array/*.js": "./dist/array/*.js",
     "./browser": "./dist/browser/index.js",
     "./browser/*.js": "./dist/browser/*.js",
+    "./buffer": "./dist/buffer/index.js",
+    "./buffer/*.js": "./dist/buffer/*.js",
     "./datetime": "./dist/datetime/index.js",
     "./datetime/*.js": "./dist/datetime/*.js",
     "./decorators": "./dist/decorators/index.js",

package/src/array/array.util.ts

@@ -4,6 +4,7 @@ import type {
   FalsyValue,
   Mapper,
   MutateOptions,
+  NonEmptyArray,
   Predicate,
   StringMap,
 } from '../types.js'
@@ -21,12 +22,12 @@ import { END } from '../types.js'
  *
  * Based on: https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_chunk
  */
-export function _chunk<T>(array: readonly T[], size = 1): T[][] {
+export function _chunk<T>(array: readonly T[], size = 1): NonEmptyArray<T>[] {
   const a: T[][] = []
   for (let i = 0; i < array.length; i += size) {
     a.push(array.slice(i, i + size))
   }
-  return a
+  return a as NonEmptyArray<T>[]
 }
 
 /**
@@ -158,13 +159,20 @@ export function _mapBy<ITEM, KEY>(
  *
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
-export function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]> {
-  const map: StringMap<T[]> = {}
+export function _groupBy<T>(
+  items: readonly T[],
+  mapper: Mapper<T, any>,
+): StringMap<NonEmptyArray<T>> {
+  const map: StringMap<NonEmptyArray<T>> = {}
 
   for (const item of items) {
     const key = mapper(item)
-    if (key !== undefined) {
-      ;(map[key] ||= []).push(item)
+    if (key === undefined) continue
+    const group = map[key]
+    if (group) {
+      group.push(item)
+    } else {
+      map[key] = [item]
     }
   }
   return map
@@ -468,6 +476,16 @@ export function _firstOrUndefined<T>(array: readonly T[]): T | undefined {
   return array[0]
 }
 
+/**
+ * Type guard that narrows an array to NonEmptyArray (array with at least one element).
+ * Readonly arrays are narrowed to `Readonly<NonEmptyArray<T>>`.
+ */
+export function _isNonEmptyArray<T>(array: T[]): array is NonEmptyArray<T>
+export function _isNonEmptyArray<T>(array: readonly T[]): array is Readonly<NonEmptyArray<T>>
+export function _isNonEmptyArray(array: readonly unknown[]): boolean {
+  return array.length > 0
+}
+
 /**
  * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
  * Throws if the iterable is empty.

package/src/buffer/buffer.util.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns an ArrayBuffer that contains exactly the bytes of the given view (e.g Uint8Array or Buffer).
+ *
+ * Safe alternative to `view.buffer`, which returns the whole underlying ArrayBuffer.
+ * It can be larger than the view, and the view may start at a non-zero offset:
+ * e.g Node.js allocates small Buffers from a shared pool (`Buffer.from(string)`,
+ * `fs.readFileSync` of small files), or the view was created with `subarray()`.
+ *
+ * Zero-copy when the view covers the whole ArrayBuffer, otherwise copies exactly its bytes.
+ */
+export function _toArrayBuffer<T extends ArrayBufferLike>(view: ArrayBufferView<T>): T {
+  const { buffer, byteOffset, byteLength } = view
+  if (byteOffset === 0 && byteLength === buffer.byteLength) return buffer
+  return buffer.slice(byteOffset, byteOffset + byteLength) as T
+}
+
+/**
+ * Same as _chunk, but for Uint8Array (or Buffer).
+ * Chunks are zero-copy views (subarray) into the input, and preserve its type
+ * (e.g Buffer in - Buffer[] out).
+ */
+export function _chunkBuffer<T extends Uint8Array>(buf: T, size: number): T[] {
+  const out: T[] = []
+
+  for (let i = 0; i < buf.length; i += size) {
+    // subarray preserves the subclass at runtime (Buffer#subarray returns a Buffer)
+    out.push(buf.subarray(i, i + size) as T)
+  }
+
+  return out
+}

package/src/buffer/index.ts

@@ -0,0 +1 @@
+export * from './buffer.util.js'

package/src/types.ts

@@ -225,6 +225,18 @@ export interface BatchResult<RES = any, ERR = Error> {
  */
 export type ValuesOf<T extends readonly any[]> = T[number]
 
+/**
+ * Array with at least one element.
+ * Index 0 is typed as `T` (not `T | undefined`) under `noUncheckedIndexedAccess`.
+ *
+ * Use `_isNonEmptyArray` to narrow a regular array to it.
+ *
+ * Caveats:
+ * - Mutating methods (pop, shift, splice, `length = 0`) can empty it without the type noticing.
+ * - Non-emptiness is lost after map, filter, slice, concat (they return `T[]`). Spread preserves it.
+ */
+export type NonEmptyArray<T> = [T, ...T[]]
+
 /**
  * Based on: https://stackoverflow.com/a/49286056/4919972
  *