@ayonli/jsext
Version:
A JavaScript extension package for building strong and modern applications.
216 lines (215 loc) • 6 kB
TypeScript
/**
* Functions for dealing with byte arrays (`Uint8Array`).
* @module
*/
/**
* A byte array is a `Uint8Array` that can be coerced to a string with `utf8`
* encoding.
*/
export declare class ByteArray extends Uint8Array {
toString(): string;
toJSON(): {
type: "ByteArray";
data: number[];
};
}
/**
* Converts the given data to a byte array.
*
* @example
* ```ts
* import bytes from "@ayonli/jsext/bytes";
*
* const arr = bytes("Hello, World!");
*
* console.log(arr);
* // ByteArray(13) [Uint8Array] [ 72, 101, 108, 108, 111, 44, 32, 87, 111, 114, 108, 100, 33 ]
*
* console.log(String(arr)); // "Hello, World!"
*
* // from hex
* const arr2 = bytes("48656c6c6f2c20576f726c6421", "hex");
*
* // from base64
* const arr3 = bytes("SGVsbG8sIFdvcmxkIQ==", "base64");
* ```
*/
export default function bytes(str: string, encoding?: "utf8" | "hex" | "base64"): ByteArray;
export default function bytes(arr: string | ArrayBufferLike | ArrayBufferView | ArrayLike<number>): ByteArray;
/**
* Creates a byte array with the specified length.
*
* @example
* ```ts
* import bytes from "@ayonli/jsext/bytes";
*
* const arr = bytes(10);
*
* console.log(arr);
* // ByteArray(10) [Uint8Array] [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
* ```
*/
export default function bytes(length: number): ByteArray;
/**
* Converts the byte array (or `Uint8Array`) to a string.
* @param encoding Default value: `utf8`.
*
* @example
* ```ts
* import { text } from "@ayonli/jsext/bytes";
*
* const arr = new Uint8Array([72, 101, 108, 108, 111, 44, 32, 87, 111, 114, 108, 100, 33]);
*
* console.log(text(arr)); // "Hello, World!"
* console.log(text(arr, "hex")); // "48656c6c6f2c20576f726c6421"
* console.log(text(arr, "base64")); // "SGVsbG8sIFdvcmxkIQ=="
* ```
*/
export declare function text(bytes: Uint8Array, encoding?: "utf8" | "hex" | "base64"): string;
/**
* Copies bytes from `src` array to `dest` and returns the number of bytes copied.
*
* @example
* ```ts
* import { copy } from "@ayonli/jsext/bytes";
*
* const src = new Uint8Array([1, 2, 3, 4, 5]);
* const dest = new Uint8Array(3);
*
* const n = copy(src, dest);
*
* console.log(n); // 3
* console.log(dest); // Uint8Array(3) [ 1, 2, 3 ]
* ```
*/
export declare function copy(src: Uint8Array, dest: Uint8Array): number;
/**
* Like `Buffer.concat` but for native `Uint8Array`.
*
* @example
* ```ts
* import { concat } from "@ayonli/jsext/bytes";
*
* const arr1 = new Uint8Array([1, 2, 3]);
* const arr2 = new Uint8Array([4, 5, 6]);
*
* const result = concat(arr1, arr2);
*
* console.log(result); // Uint8Array(6) [ 1, 2, 3, 4, 5, 6 ]
* ```
*/
export declare function concat<T extends Uint8Array>(...arrays: T[]): T;
/**
* Like `Buffer.compare` but for native `Uint8Array`.
*
* @example
* ```ts
* import { compare } from "@ayonli/jsext/bytes";
*
* const arr1 = new Uint8Array([1, 2, 3]);
* const arr2 = new Uint8Array([1, 2, 4]);
* const arr3 = new Uint8Array([1, 2, 3, 4]);
* const arr4 = new Uint8Array([1, 2, 3]);
* const arr5 = new Uint8Array([1, 2]);
*
* console.log(compare(arr1, arr2)); // -1
* console.log(compare(arr1, arr3)); // -1
* console.log(compare(arr1, arr4)); // 0
* console.log(compare(arr1, arr5)); // 1
* ```
*/
export declare function compare(arr1: Uint8Array, arr2: Uint8Array): -1 | 0 | 1;
/**
* Checks if the two byte arrays are equal to each other.
*
* @example
* ```ts
* import { equals } from "@ayonli/jsext/bytes";
*
* const arr1 = new Uint8Array([1, 2, 3]);
* const arr2 = new Uint8Array([1, 2, 3]);
* const arr3 = new Uint8Array([1, 2, 4]);
*
* console.log(equals(arr1, arr2)); // true
* console.log(equals(arr1, arr3)); // false
* ```
*/
export declare function equals(arr1: Uint8Array, arr2: Uint8Array): boolean;
/**
* Checks if the byte array contains another array as a slice of its contents.
*
* @example
* ```ts
* import { includesSlice } from "@ayonli/jsext/bytes";
*
* const arr = new Uint8Array([1, 2, 3, 4, 5]);
*
* console.log(includesSlice(arr, new Uint8Array([3, 4]))); // true
* console.log(includesSlice(arr, new Uint8Array([4, 3]))); // false
* ```
*/
export declare function includesSlice(arr: Uint8Array, slice: Uint8Array): boolean;
/**
* Checks if the byte array starts with the given prefix.
*
* @example
* ```ts
* import { startsWith } from "@ayonli/jsext/bytes";
*
* const arr = new Uint8Array([1, 2, 3, 4, 5]);
*
* console.log(startsWith(arr, new Uint8Array([1, 2]))); // true
* console.log(startsWith(arr, new Uint8Array([2, 1]))); // false
* ```
*/
export declare function startsWith(arr: Uint8Array, prefix: Uint8Array): boolean;
/**
* Checks if the byte array ends with the given suffix.
*
* @example
* ```ts
* import { endsWith } from "@ayonli/jsext/bytes";
*
* const arr = new Uint8Array([1, 2, 3, 4, 5]);
*
* console.log(endsWith(arr, new Uint8Array([4, 5]))); // true
* console.log(endsWith(arr, new Uint8Array([5, 4]))); // false
* ```
*/
export declare function endsWith(arr: Uint8Array, suffix: Uint8Array): boolean;
/**
* Breaks the byte array into smaller chunks according to the given delimiter.
*
* @example
* ```ts
* import { split } from "@ayonli/jsext/bytes";
*
* const arr = new Uint8Array([1, 2, 3, 0, 4, 5, 0, 6, 7]);
*
* console.log(split(arr, 0));
* // [
* // Uint8Array(3) [ 1, 2, 3 ],
* // Uint8Array(2) [ 4, 5 ],
* // Uint8Array(2) [ 6, 7 ]
* // ]
* ```
*/
export declare function split<T extends Uint8Array>(arr: T, delimiter: number): T[];
/**
* Breaks the byte array into smaller chunks according to the given length.
*
* @example
* ```ts
* import { chunk } from "@ayonli/jsext/bytes";
*
* const arr = new Uint8Array([1, 2, 3, 4, 5, 6, 7]);
*
* console.log(chunk(arr, 3));
* // [
* // Uint8Array(3) [ 1, 2, 3 ],
* // Uint8Array(3) [ 4, 5, 6 ],
* // Uint8Array(1) [ 7 ]
* // ]
* ```
*/
export declare function chunk<T extends Uint8Array>(arr: T, length: number): T[];