@guarani/primitives 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2021 Eduardo Ribeiro Rezende
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# `@guarani/primitives`

package/dist/buffer.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+import { Optional } from '@guarani/types';
+export declare type Endianness = 'be' | 'le';
+/**
+ * Pads the provided bitstring until its length is a multiple of 8.
+ *
+ * @param bits Bitstring to be padded.
+ * @param endianness Defines if the padding will be added at the beginning or at the end of the bitstring.
+ * @returns Padded bitstring.
+ */
+export declare function padBits(bits: string, endianness: Endianness): string;
+/**
+ * Returns the Binary String representation of the provided Buffer.
+ *
+ * @param buffer Buffer to be encoded.
+ * @param endianness Defines if the padding will be added at the beginning or at the end of the bitstring.
+ * @returns Binary String representation of the provided Buffer.
+ */
+export declare function bufferToBinary(buffer: Buffer, endianness?: Optional<Endianness>): string;
+/**
+ * Returns the Buffer representation of the provided Binary String.
+ *
+ * @param bits Binary String to be decoded.
+ * @param endianness Defines if the padding will be added at the beginning or at the end of the bitstring.
+ * @returns Buffer representation of the provided Binary String.
+ */
+export declare function binaryToBuffer(bits: string, endianness?: Optional<Endianness>): Buffer;
+/**
+ * Performs a bitwise NOT operation on the provided Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @returns Buffer that contains the flipped bits.
+ */
+export declare function flipBufferBits(buffer: Buffer): Buffer;
+/**
+ * Returns the Unsigned Integer value of the provided Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @returns Unsigned Integer based on the provided Buffer.
+ */
+export declare function bufferToUnsignedInteger(buffer: Buffer): bigint;
+/**
+ * Returns the Integer value of the provided Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @param asTwosComplement The provided Buffer is in Two's Complement format.
+ * @returns Integer based on the provided Buffer.
+ */
+export declare function bufferToInteger(buffer: Buffer, asTwosComplement?: Optional<true>): bigint;

package/dist/buffer.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bufferToInteger = exports.bufferToUnsignedInteger = exports.flipBufferBits = exports.binaryToBuffer = exports.bufferToBinary = exports.padBits = void 0;
+const integer_1 = require("./integer");
+/**
+ * Pads the provided bitstring until its length is a multiple of 8.
+ *
+ * @param bits Bitstring to be padded.
+ * @param endianness Defines if the padding will be added at the beginning or at the end of the bitstring.
+ * @returns Padded bitstring.
+ */
+function padBits(bits, endianness) {
+    const modulo = bits.length % 8;
+    const unusedBits = modulo === 0 ? 0 : 8 - (bits.length % 8);
+    let paddedBits = bits;
+    if (unusedBits !== 0) {
+        const padding = '0'.repeat(unusedBits);
+        paddedBits = endianness === 'be' ? `${padding}${paddedBits}` : `${paddedBits}${padding}`;
+    }
+    return paddedBits;
+}
+exports.padBits = padBits;
+/**
+ * Returns the Binary String representation of the provided Buffer.
+ *
+ * @param buffer Buffer to be encoded.
+ * @param endianness Defines if the padding will be added at the beginning or at the end of the bitstring.
+ * @returns Binary String representation of the provided Buffer.
+ */
+function bufferToBinary(buffer, endianness = 'be') {
+    if (!Buffer.isBuffer(buffer)) {
+        throw new TypeError('Invalid parameter "buffer".');
+    }
+    return buffer.reduce((bits, byte) => (bits += padBits(byte.toString(2), endianness)), '');
+}
+exports.bufferToBinary = bufferToBinary;
+/**
+ * Returns the Buffer representation of the provided Binary String.
+ *
+ * @param bits Binary String to be decoded.
+ * @param endianness Defines if the padding will be added at the beginning or at the end of the bitstring.
+ * @returns Buffer representation of the provided Binary String.
+ */
+function binaryToBuffer(bits, endianness = 'be') {
+    const paddedBits = padBits(bits, endianness);
+    const binaryBytes = paddedBits.match(/.{8}/g) ?? [];
+    const bytes = binaryBytes.map((byte) => Number.parseInt(byte, 2));
+    return Buffer.from(bytes);
+}
+exports.binaryToBuffer = binaryToBuffer;
+/**
+ * Performs a bitwise NOT operation on the provided Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @returns Buffer that contains the flipped bits.
+ */
+function flipBufferBits(buffer) {
+    if (buffer.length === 0) {
+        throw new Error('The provided buffer must not be empty.');
+    }
+    // buffer.toString("binary") returns latin1 characteres.
+    const bits = bufferToBinary(buffer);
+    const flippedBits = bits
+        .split('')
+        .map((bit) => (bit === '0' ? '1' : '0'))
+        .join('');
+    return binaryToBuffer(flippedBits);
+}
+exports.flipBufferBits = flipBufferBits;
+/**
+ * Returns the Unsigned Integer value of the provided Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @returns Unsigned Integer based on the provided Buffer.
+ */
+function bufferToUnsignedInteger(buffer) {
+    if (buffer.length === 0) {
+        throw new Error('The provided buffer must not be empty.');
+    }
+    return buffer.reduce((result, byte) => (result << 8n) | BigInt(byte), 0n);
+}
+exports.bufferToUnsignedInteger = bufferToUnsignedInteger;
+/**
+ * Returns the original unsigned Buffer from the provided
+ * Two's Complemented Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @returns Original unsigned Buffer.
+ */
+function fromTwosComplement(buffer) {
+    if (buffer.length === 0) {
+        throw new Error('The provided buffer must not be empty.');
+    }
+    const complemented = bufferToUnsignedInteger(buffer);
+    const reciprocal = (0, integer_1.integerToBuffer)(complemented - 1n);
+    const original = flipBufferBits(reciprocal);
+    return original[0] === 0x00 ? original.subarray(1) : original;
+}
+/**
+ * Returns the Integer value of the provided Buffer.
+ *
+ * @param buffer Buffer to be transformed.
+ * @param asTwosComplement The provided Buffer is in Two's Complement format.
+ * @returns Integer based on the provided Buffer.
+ */
+function bufferToInteger(buffer, asTwosComplement) {
+    if (buffer.length === 0) {
+        throw new Error('The provided buffer must not be empty.');
+    }
+    const complemented = asTwosComplement === true && (buffer[0] & 0x80) !== 0x00 ? fromTwosComplement(buffer) : buffer;
+    const integer = bufferToUnsignedInteger(complemented);
+    return asTwosComplement === true && (buffer[0] & 0x80) !== 0x00 ? -integer : integer;
+}
+exports.bufferToInteger = bufferToInteger;

package/dist/exception.d.ts

@@ -0,0 +1,37 @@
+import { Nullable, Optional } from '@guarani/types';
+/**
+ * Exception class that keeps the Stack Trace of rethrown Errors.
+ */
+export declare class Exception extends Error {
+    /**
+     * Previous Error of the Chain.
+     */
+    readonly originalError?: Optional<Error>;
+    /**
+     * Instantiates an empty Exception.
+     */
+    constructor();
+    /**
+     * Instantiates a new Exception based on the provide message.
+     *
+     * @param message Message of the Exception.
+     */
+    constructor(message: string);
+    /**
+     * Instantiates a new Exception by rethrowing the provided Error.
+     *
+     * @param originalError Rethrown Error.
+     */
+    constructor(originalError: Error);
+    /**
+     * Instantiates a new Exception with the provided message and chaining the provided Error's Stack Trace.
+     *
+     * @param message Message of the Exception.
+     * @param originalError Rethrown Error.
+     */
+    constructor(message: Nullable<string>, originalError: Error);
+    /**
+     * Returns the default Exception Message.
+     */
+    protected getDefaultMessage(): string;
+}

package/dist/exception.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Exception = void 0;
+/**
+ * Exception class that keeps the Stack Trace of rethrown Errors.
+ */
+class Exception extends Error {
+    /**
+     * Instantiates a new Exception based on the provided parameters.
+     *
+     * @param messageOrBaseError Message of the Exception or rethrown Error.
+     * @param originalError Rethrown Error.
+     */
+    constructor(messageOrBaseError, originalError) {
+        originalError = messageOrBaseError instanceof Error ? messageOrBaseError : originalError;
+        super(messageOrBaseError === null
+            ? undefined
+            : typeof messageOrBaseError === 'string'
+                ? messageOrBaseError
+                : originalError?.message);
+        this.name = this.constructor.name;
+        Object.defineProperty(this, 'originalError', { enumerable: false, value: originalError, writable: true });
+        if (this.message === '') {
+            this.message = this.getDefaultMessage();
+        }
+        // TODO: Check if this does not cause a memory leak.
+        const thisStack = this.stack ?? '';
+        const originalStack = (this.originalError?.stack ?? '').split('\n').slice(0, Error.stackTraceLimit).join('\n');
+        this.stack =
+            this.originalError === undefined ? `${thisStack}\n${originalStack}` : `${thisStack}\nFrom ${originalStack}`;
+    }
+    /**
+     * Returns the default Exception Message.
+     */
+    getDefaultMessage() {
+        return '';
+    }
+}
+exports.Exception = Exception;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Endianness, binaryToBuffer, bufferToBinary, bufferToInteger, bufferToUnsignedInteger, flipBufferBits, padBits, } from './buffer';
+export { Exception } from './exception';
+export { integerToBuffer } from './integer';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.integerToBuffer = exports.Exception = exports.padBits = exports.flipBufferBits = exports.bufferToUnsignedInteger = exports.bufferToInteger = exports.bufferToBinary = exports.binaryToBuffer = void 0;
+var buffer_1 = require("./buffer");
+Object.defineProperty(exports, "binaryToBuffer", { enumerable: true, get: function () { return buffer_1.binaryToBuffer; } });
+Object.defineProperty(exports, "bufferToBinary", { enumerable: true, get: function () { return buffer_1.bufferToBinary; } });
+Object.defineProperty(exports, "bufferToInteger", { enumerable: true, get: function () { return buffer_1.bufferToInteger; } });
+Object.defineProperty(exports, "bufferToUnsignedInteger", { enumerable: true, get: function () { return buffer_1.bufferToUnsignedInteger; } });
+Object.defineProperty(exports, "flipBufferBits", { enumerable: true, get: function () { return buffer_1.flipBufferBits; } });
+Object.defineProperty(exports, "padBits", { enumerable: true, get: function () { return buffer_1.padBits; } });
+var exception_1 = require("./exception");
+Object.defineProperty(exports, "Exception", { enumerable: true, get: function () { return exception_1.Exception; } });
+var integer_1 = require("./integer");
+Object.defineProperty(exports, "integerToBuffer", { enumerable: true, get: function () { return integer_1.integerToBuffer; } });

package/dist/integer.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import { Optional } from '@guarani/types';
+/**
+ * Encodes the provided Integer into a Buffer.
+ *
+ * @param integer Integer to be encoded.
+ * @param asTwosComplement Represents Natural Number Buffers starting in
+ * **0b1xxxxxxx** as positive by appending a **0x00** byte at the beginning.
+ * @returns Encoded Buffer.
+ */
+export declare function integerToBuffer(integer: number | bigint, asTwosComplement?: Optional<true>): Buffer;

package/dist/integer.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.integerToBuffer = void 0;
+const buffer_1 = require("./buffer");
+/**
+ * Encodes the provided unsigned Integer into a Buffer.
+ *
+ * @param integer Unsigned Integer to be encoded.
+ * @returns Encoded Buffer.
+ */
+function unsignedIntegerToBuffer(integer) {
+    let hex = integer.toString(16);
+    if (hex.length % 2 !== 0) {
+        hex = `0${hex}`;
+    }
+    const bytes = hex.match(/.{2}/g).map((byte) => Number.parseInt(byte, 16));
+    return Buffer.from(bytes);
+}
+/**
+ * Encodes the provided Integer into a Buffer.
+ *
+ * @param integer Integer to be encoded.
+ * @param asTwosComplement Represents Natural Number Buffers starting in
+ * **0b1xxxxxxx** as positive by appending a **0x00** byte at the beginning.
+ * @returns Encoded Buffer.
+ */
+function integerToBuffer(integer, asTwosComplement) {
+    if (typeof integer !== 'bigint' && typeof integer !== 'number') {
+        throw new TypeError('Invalid parameter "integer".');
+    }
+    if (typeof integer === 'number' && !Number.isInteger(integer)) {
+        throw new TypeError('Invalid parameter "integer".');
+    }
+    const data = BigInt(integer);
+    const unsignedInteger = data < 0n ? data * -1n : data;
+    let unsignedBuffer = unsignedIntegerToBuffer(unsignedInteger);
+    if (data >= 0n) {
+        return asTwosComplement === true && (unsignedBuffer[0] & 0x80) !== 0x00
+            ? Buffer.from([0x00, ...unsignedBuffer])
+            : unsignedBuffer;
+    }
+    if (data > 0 && (unsignedBuffer[0] & 0x80) !== 0x00) {
+        unsignedBuffer = Buffer.from([0x00, ...unsignedBuffer]);
+    }
+    const reciprocal = (0, buffer_1.flipBufferBits)(unsignedBuffer);
+    const complementedInteger = (0, buffer_1.bufferToUnsignedInteger)(reciprocal) + 1n;
+    let complemented = unsignedIntegerToBuffer(complementedInteger);
+    if ((complemented[0] & 0x80) === 0x00) {
+        complemented = Buffer.from([0xff, ...complemented]);
+    }
+    return complemented;
+}
+exports.integerToBuffer = integerToBuffer;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@guarani/primitives",
+  "version": "0.7.0",
+  "description": "Utilities for manipulating NodeJS' Primitives.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "homepage": "https://github.com/guaranijs/guarani/tree/master/packages/primitives#readme",
+  "bugs": "https://github.com/guaranijs/guarani/issues",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com/guaranijs/guarani.git",
+    "directory": "packages/primitives"
+  },
+  "author": {
+    "name": "Eduardo Ribeiro Rezende",
+    "email": "eduardorbr7@gmail.com",
+    "url": "https://github.com/revensky"
+  },
+  "directories": {
+    "lib": "lib",
+    "test": "tests"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "rimraf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@guarani/types": "0.7.0"
+  },
+  "gitHead": "bb8bf8ce17ca2d5821bd2be09c67cf93a18340eb"
+}