tessl/npm-uint8arrays

Utility functions to make dealing with Uint8Arrays easier

—

Pending

Overview

Eval results

Files

Array Operations

Name: tessl/npm-uint8arrays
Author: tessl

Core array manipulation functions for Uint8Arrays including concatenation, comparison, and equality testing. These operations are optimized for performance with Node.js Buffer support when available.

Capabilities

Array Concatenation

Efficiently concatenates multiple Uint8Arrays into a single array. Optimizes performance when total length is known.

/**
 * Returns a new Uint8Array created by concatenating the passed Uint8Arrays
 * @param arrays - Array of Uint8Arrays to concatenate
 * @param length - Optional total length hint for optimization
 * @returns New Uint8Array containing concatenated data
 */
function concat(arrays: Uint8Array[], length?: number): Uint8Array;

Usage Examples:

import { concat } from "uint8arrays/concat";
import { fromString } from "uint8arrays/from-string";
import { toString } from "uint8arrays/to-string";

// Basic concatenation
const part1 = fromString("Hello");
const part2 = fromString(" ");
const part3 = fromString("World");

const combined = concat([part1, part2, part3]);
console.log(toString(combined)); // "Hello World"

// With length hint for better performance
const arrays = [
  new Uint8Array([1, 2, 3]),
  new Uint8Array([4, 5]),
  new Uint8Array([6, 7, 8, 9])
];
const result = concat(arrays, 9); // Length hint improves performance
console.log(result); // Uint8Array(9) [1, 2, 3, 4, 5, 6, 7, 8, 9]

// Concatenating many small arrays
const chunks = [];
for (let i = 0; i < 100; i++) {
  chunks.push(new Uint8Array([i]));
}
const all = concat(chunks, 100);

Array Comparison

Lexicographic comparison of two Uint8Arrays, compatible with Array.sort for ordering arrays.

/**
 * Can be used with Array.sort to sort an array with Uint8Array entries
 * @param a - First array to compare
 * @param b - Second array to compare
 * @returns -1 if a < b, 1 if a > b, 0 if equal
 */
function compare(a: Uint8Array, b: Uint8Array): number;

Usage Examples:

import { compare } from "uint8arrays/compare";

// Direct comparison
const array1 = new Uint8Array([1, 2, 3]);
const array2 = new Uint8Array([1, 2, 4]);
console.log(compare(array1, array2)); // -1 (array1 < array2)

const array3 = new Uint8Array([1, 2, 3]);
console.log(compare(array1, array3)); // 0 (equal)

// Sorting arrays
const arrays = [
  new Uint8Array([3, 4, 5]),
  new Uint8Array([1, 2, 3]),
  new Uint8Array([2, 3, 4])
];

const sorted = arrays.sort(compare);
console.log(sorted);
// [
//   Uint8Array(3) [1, 2, 3],
//   Uint8Array(3) [2, 3, 4], 
//   Uint8Array(3) [3, 4, 5]
// ]

// Length affects comparison
const short = new Uint8Array([1, 2]);
const long = new Uint8Array([1, 2, 0]);
console.log(compare(short, long)); // -1 (shorter array is "less")

Array Equality

Fast equality testing for Uint8Arrays with identical content. Optimized for performance with early returns.

/**
 * Returns true if the two passed Uint8Arrays have the same content
 * @param a - First array to compare
 * @param b - Second array to compare
 * @returns true if arrays are identical, false otherwise
 */
function equals(a: Uint8Array, b: Uint8Array): boolean;

Usage Examples:

import { equals } from "uint8arrays/equals";
import { fromString } from "uint8arrays/from-string";

// Basic equality
const array1 = new Uint8Array([1, 2, 3]);
const array2 = new Uint8Array([1, 2, 3]);
const array3 = new Uint8Array([1, 2, 4]);

console.log(equals(array1, array2)); // true
console.log(equals(array1, array3)); // false

// Same reference check (optimized)
console.log(equals(array1, array1)); // true (fast path)

// String comparison
const str1 = fromString("hello");
const str2 = fromString("hello");
const str3 = fromString("world");

console.log(equals(str1, str2)); // true
console.log(equals(str1, str3)); // false

// Different lengths
const short = new Uint8Array([1, 2]);
const long = new Uint8Array([1, 2, 3]);
console.log(equals(short, long)); // false (early return)

Performance Characteristics

concat()

Time Complexity: O(n) where n is total length of all arrays
Space Complexity: O(n) for result array
Optimization: Providing length parameter avoids array traversal
Node.js: Uses Buffer.concat() when available

compare()

Time Complexity: O(min(a.length, b.length)) average case
Early Termination: Stops at first differing byte
Lexicographic: Shorter arrays are considered "less than" longer arrays with same prefix
Node.js: Uses Buffer.compare() when available