From 58a3f74f008e0d6ffb177283fa7fc929752c1381 Mon Sep 17 00:00:00 2001 From: Andrea Baccega Date: Sat, 16 Mar 2024 11:28:49 +0100 Subject: [PATCH] fixing README.md --- packages/bigint-uint8array/README.md | 72 ++++++++-------------------- 1 file changed, 21 insertions(+), 51 deletions(-) diff --git a/packages/bigint-uint8array/README.md b/packages/bigint-uint8array/README.md index 912fd78..b0050a9 100644 --- a/packages/bigint-uint8array/README.md +++ b/packages/bigint-uint8array/README.md @@ -1,9 +1,10 @@ -# 💪🔢 @vekexasia/bigint-buffer: Enhanced Buffer Utilities for BigInt Handling +# @vekexasia/bigint-uint8array: Enhanced Buffer Utilities for BigInt Handling +src="https://img.shields.io/badge/rollup-323330?style=for-the-badge&logo=rollup.js&logoColor=Brown"/> -This project builds upon the original [`bigint-buffer`](https://www.npmjs.org/package/bigint-buffer) utility, which provides efficient conversion between TC39 BigInts and buffers, by introducing additional functionality for more flexible bigint handling, including support for reading and writing arbitrarily large **signed** and unsigned bigints. +This project builds upon the original [`bigint-buffer`](https://github.com/no2chem/bigint-buffer/) utility, which provides efficient conversion between TC39 BigInts and buffers, by introducing additional functionality for more flexible bigint handling, including support for reading and writing arbitrarily large **signed** and unsigned bigints. ## New Features @@ -13,32 +14,9 @@ This project builds upon the original [`bigint-buffer`](https://www.npmjs.org/pa - **Value Coercion Based on Byte Length**: When writing BigInts to a buffer, the library intelligently checks or coerces values based on the specified number of bytes. This ensures that the value fits within the allocated space, preserving the sign and magnitude as accurately as possible. -### Buffer class monkey patch utility methods for Arbitrary-Length BigInts +- **Real browser support**: The library works in browser environments, while the original `bigint-buffer` is [built upon the Buffer class](https://github.com/no2chem/bigint-buffer/issues/15) which is not available in browsers. -For convenience the library allows to monkey patch (only if properly imported) the Buffer class with the new methods. This is done by importing the library as follows: - -```typescript -import '@vekexasia/bigint-buffer/buffer'; -``` - -Upon doing so the following methods will be available on the Buffer class: -```typescript -interface Buffer { - // signed - writeBigIntBE: (value: bigint, width: number, offset?: number) => number - writeBigIntLE: (value: bigint, width: number, offset?: number) => number - readBigIntBE: (width: number, offset?: number) => bigint - readBigIntLE: (width: number, offset?: number) => bigint - // unsigned - writeBigUIntBE: (value: bigint, width: number, offset?: number) => number - writeBigUIntLE: (value: bigint, width: number, offset?: number) => number - readBigUIntBE: (width: number, offset?: number) => bigint - readBigUIntLE: (width: number, offset?: number) => bigint -} -``` - - -## Why Extend bigint-buffer? +## Why extend bigint-buffer? The original `bigint-buffer` library provided a solid foundation for working with BigInts, offering efficient conversion to and from buffers without the need for intermediate hexadecimal string conversion. By extending its capabilities to include support for signed integers, this project aims to address a broader spectrum of use cases, making it a more versatile tool for developers working with large or complex numerical data. @@ -50,38 +28,30 @@ Add the extended bigint-buffer to your project: ```bash npm install @vekexasia/bigint-buffer ``` +## Documentation + +You can find typedoc documentation [here](https://vekexasia.github.io/bigint-uint8array/). ## Usage The extended functionality integrates seamlessly with the existing `bigint-buffer` API, providing additional methods for working with BigInts: ```typescript -import { - toBufferBigIntLE, - toBigIntLE, -} from '@vekexasia/bigint-buffer'; - -let buffer = toBufferBigIntLE(42n, 1); -let bigint = toBigIntLE(buffer, 1); // 42n +import { converter } from '@vekexasia/bigint-uint8array'; -buffer = toBufferBigIntLE(-42n, 1); -bigint = toBigIntLE(buffer, 1); // -42n - -buffer = toBufferBigIntLE(128, 1); // throws Error as 128 does not fit in 1 signed integer byte +let arr = converter + .unsigned // or .signed if working with signed integers + .be // or .le for little endian + .toNewArray(42n, 1 /* bytes */); // Uint8Array [ 42 ] +let bigint = converter.unsigned.be.toBigInt(arr); // 42n ``` -or by leveraging buffer monkey patching: - -```typescript -import '@vekexasia/bigint-buffer/buffer'; - -const buffer = Buffer.alloc(8); -buffer.writeBigIntLE(42n, 8); -const bigint = buffer.readBigIntLE(8); // 42n -``` +## Performance -## Documentation +The library uses the NAPI bindings when available. Besides the default `converter` there is also the [`uncheckedConverter`](https://vekexasia.github.io/bigint-swissknife/variables/_vekexasia_bigint_uint8array.uncheckedConverter.html) +which is faster but does not check for overflows. -All the methods are documented in the source code. \ No newline at end of file +Furthermore, the library allows to reuse the same buffer for multiple operations, which can be useful in performance-critical scenarios. +**NOTE**: the bigint-buffer implementation will always create a new buffer even in