tiny-essentials 1.2.0 → 1.2.1

package/dist/v1/libs/TinyCrypto.d.mts

@@ -13,8 +13,8 @@ declare class TinyCrypto {
      *
      * @param {Object} [options={}] - Configuration options for encryption and decryption.
      * @param {string} [options.algorithm='aes-256-gcm'] - The encryption algorithm to use. Recommended: 'aes-256-gcm' for authenticated encryption.
-     * @param {string} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
-     * @param {string} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
+     * @param {BufferEncoding} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
+     * @param {BufferEncoding} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
      * @param {number} [options.authTagLength=16] - The length of the authentication tag used in GCM mode. Usually 16 for AES-256-GCM.
      * @param {Buffer} [options.key] - Optional 32-byte cryptographic key. If not provided, a random key is generated.
      *
@@ -24,21 +24,23 @@ declare class TinyCrypto {
      * const crypto = new CryptoManager({
      *   algorithm: 'aes-256-gcm',
      *   outputEncoding: 'base64',
-     *   key: crypto.randomBytes(32),
+     *   key: randomBytes(32),
      * });
      */
     constructor(options?: {
         algorithm?: string | undefined;
-        outputEncoding?: string | undefined;
-        inputEncoding?: string | undefined;
+        outputEncoding?: BufferEncoding | undefined;
+        inputEncoding?: BufferEncoding | undefined;
         authTagLength?: number | undefined;
         key?: Buffer<ArrayBufferLike> | undefined;
     });
     algorithm: string;
-    outputEncoding: string;
-    inputEncoding: string;
     authTagLength: number;
     key: Buffer<ArrayBufferLike>;
+    /** @type {BufferEncoding} */
+    outputEncoding: BufferEncoding;
+    /** @type {BufferEncoding} */
+    inputEncoding: BufferEncoding;
     /**
      * Generates a secure random cryptographic key.
      *
@@ -68,10 +70,7 @@ declare class TinyCrypto {
      *
      * @param {*} data - The data to encrypt. Can be of any supported type (string, number, boolean, Date, JSON, etc.).
      * @param {Buffer} [iv=this.generateIV()] - Optional Initialization Vector (IV). If not provided, a secure random IV is generated.
-     * @returns {Object} An object containing:
-     * - `iv` {string} - The IV used, encoded with the output encoding.
-     * - `encrypted` {string} - The encrypted payload.
-     * - `authTag` {string} - The authentication tag used to verify the integrity of the ciphertext.
+     * @returns {EncryptedDataParams} An object containing the encrypted data.
      *
      * @example
      * const result = cryptoManager.encrypt('Hello, world!');
@@ -81,17 +80,33 @@ declare class TinyCrypto {
      * //   authTag: 'aa93...'
      * // }
      */
-    encrypt(data: any, iv?: Buffer): Object;
+    encrypt(data: any, iv?: Buffer): {
+        /**
+         * - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+         */
+        iv: string;
+        /**
+         * - The encrypted data to decrypt, encoded with the output encoding.
+         */
+        encrypted: string;
+        /**
+         * - The authentication tag used to verify the integrity of the encrypted data.
+         */
+        authTag: string;
+    };
+    /**
+     * @typedef {Object} EncryptedDataParams
+     * @property {string} iv - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+     * @property {string} encrypted - The encrypted data to decrypt, encoded with the output encoding.
+     * @property {string} authTag - The authentication tag used to verify the integrity of the encrypted data.
+     */
     /**
      * Decrypts a previously encrypted value.
      *
      * The method checks the integrity of the data using the authentication tag (`authTag`) and ensures the data is properly decrypted.
      * After decryption, it automatically deserializes the data back to its original type.
      *
-     * @param {Object} params - An object containing the encrypted data:
-     *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-     *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-     *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+     * @param {EncryptedDataParams} params - An object containing the encrypted data.
      * @param {string|null} [expectedType=null] - Optionally specify the expected type of the decrypted data. If provided, the method will validate the type of the deserialized value.
      * @returns {*} The decrypted value, which will be the original type of the data before encryption.
      * @throws {Error} Throws if the authentication tag doesn't match or the data has been tampered with.
@@ -106,17 +121,27 @@ declare class TinyCrypto {
      * const decrypted = cryptoManager.decrypt(encryptedData, 'string');
      * console.log(decrypted); // Outputs: 'Hello, world!'
      */
-    decrypt({ iv, encrypted, authTag }: Object, expectedType?: string | null): any;
+    decrypt({ iv, encrypted, authTag }: {
+        /**
+         * - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+         */
+        iv: string;
+        /**
+         * - The encrypted data to decrypt, encoded with the output encoding.
+         */
+        encrypted: string;
+        /**
+         * - The authentication tag used to verify the integrity of the encrypted data.
+         */
+        authTag: string;
+    }, expectedType?: string | null): any;
     /**
      * Retrieves the type of the original data from an encrypted object.
      *
      * This method decrypts the encrypted data and extracts its type information without fully deserializing the value.
      * It is useful when you need to verify the type of the encrypted data before fully decrypting it.
      *
-     * @param {Object} params - An object containing the encrypted data:
-     *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-     *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-     *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+     * @param {EncryptedDataParams} params - An object containing the encrypted data.
      * @returns {string} The type of the original data (e.g., 'string', 'number', 'date', etc.).
      *
      * @example
@@ -128,7 +153,20 @@ declare class TinyCrypto {
      * const dataType = cryptoManager.getTypeFromEncrypted(encryptedData);
      * console.log(dataType); // Outputs: 'string'
      */
-    getTypeFromEncrypted({ iv, encrypted, authTag }: Object): string;
+    getTypeFromEncrypted({ iv, encrypted, authTag }: {
+        /**
+         * - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+         */
+        iv: string;
+        /**
+         * - The encrypted data to decrypt, encoded with the output encoding.
+         */
+        encrypted: string;
+        /**
+         * - The authentication tag used to verify the integrity of the encrypted data.
+         */
+        authTag: string;
+    }): string;
     /**
      * Saves the cryptographic key to a file.
      *
@@ -240,8 +278,8 @@ declare class TinyCrypto {
      *
      * @param {Object} config - The configuration object to import.
      * @param {string} config.algorithm - The encryption algorithm (e.g., 'aes-256-gcm').
-     * @param {string} config.outputEncoding - The output encoding format (e.g., 'hex').
-     * @param {string} config.inputEncoding - The input encoding format (e.g., 'utf8').
+     * @param {BufferEncoding} config.outputEncoding - The output encoding format (e.g., 'hex').
+     * @param {BufferEncoding} config.inputEncoding - The input encoding format (e.g., 'utf8').
      * @param {number} config.authTagLength - The authentication tag length (e.g., 16).
      * @param {string} config.key - The cryptographic key in hexadecimal string format.
      *
@@ -258,8 +296,8 @@ declare class TinyCrypto {
      */
     importConfig(config: {
         algorithm: string;
-        outputEncoding: string;
-        inputEncoding: string;
+        outputEncoding: BufferEncoding;
+        inputEncoding: BufferEncoding;
         authTagLength: number;
         key: string;
     }): void;

package/dist/v1/libs/TinyCrypto.mjs

@@ -1,5 +1,5 @@
-import crypto from 'crypto';
-import fs from 'fs';
+import { randomBytes, createDecipheriv, createCipheriv } from 'crypto';
+import * as fs from 'fs';
 import { Buffer } from 'buffer';
 import { objType } from '../../v1/basics/objFilter.mjs';
 /**
@@ -26,8 +26,8 @@ class TinyCrypto {
      *
      * @param {Object} [options={}] - Configuration options for encryption and decryption.
      * @param {string} [options.algorithm='aes-256-gcm'] - The encryption algorithm to use. Recommended: 'aes-256-gcm' for authenticated encryption.
-     * @param {string} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
-     * @param {string} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
+     * @param {BufferEncoding} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
+     * @param {BufferEncoding} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
      * @param {number} [options.authTagLength=16] - The length of the authentication tag used in GCM mode. Usually 16 for AES-256-GCM.
      * @param {Buffer} [options.key] - Optional 32-byte cryptographic key. If not provided, a random key is generated.
      *
@@ -37,15 +37,17 @@ class TinyCrypto {
      * const crypto = new CryptoManager({
      *   algorithm: 'aes-256-gcm',
      *   outputEncoding: 'base64',
-     *   key: crypto.randomBytes(32),
+     *   key: randomBytes(32),
      * });
      */
     constructor(options = {}) {
         this.algorithm = options.algorithm || 'aes-256-gcm';
-        this.outputEncoding = options.outputEncoding || 'hex';
-        this.inputEncoding = options.inputEncoding || 'utf8';
         this.authTagLength = options.authTagLength || 16;
         this.key = options.key || this.generateKey();
+        /** @type {BufferEncoding} */
+        this.outputEncoding = options.outputEncoding || 'hex';
+        /** @type {BufferEncoding} */
+        this.inputEncoding = options.inputEncoding || 'utf8';
     }
     /**
      * Generates a secure random cryptographic key.
@@ -58,7 +60,7 @@ class TinyCrypto {
      * const customKey = cryptoManager.generateKey(16); // Generates a 16-byte key (e.g. for AES-128)
      */
     generateKey(value = 32) {
-        return crypto.randomBytes(value); // 256-bit
+        return randomBytes(value); // 256-bit
     }
     /**
      * Generates a secure random Initialization Vector (IV).
@@ -71,7 +73,7 @@ class TinyCrypto {
      * const customIV = cryptoManager.generateIV(16); // Generates a 16-byte IV if needed for other algorithms
      */
     generateIV(value = 12) {
-        return crypto.randomBytes(value); // 96-bit padrão para GCM
+        return randomBytes(value); // 96-bit padrão para GCM
     }
     /**
      * Encrypts a given value (string, number, object, etc.)
@@ -80,10 +82,7 @@ class TinyCrypto {
      *
      * @param {*} data - The data to encrypt. Can be of any supported type (string, number, boolean, Date, JSON, etc.).
      * @param {Buffer} [iv=this.generateIV()] - Optional Initialization Vector (IV). If not provided, a secure random IV is generated.
-     * @returns {Object} An object containing:
-     * - `iv` {string} - The IV used, encoded with the output encoding.
-     * - `encrypted` {string} - The encrypted payload.
-     * - `authTag` {string} - The authentication tag used to verify the integrity of the ciphertext.
+     * @returns {EncryptedDataParams} An object containing the encrypted data.
      *
      * @example
      * const result = cryptoManager.encrypt('Hello, world!');
@@ -95,28 +94,37 @@ class TinyCrypto {
      */
     encrypt(data, iv = this.generateIV()) {
         const plainText = this.#serialize(data);
-        const cipher = crypto.createCipheriv(this.algorithm, this.key, iv, {
+        const cipher = createCipheriv(this.algorithm, this.key, iv, {
+            // @ts-ignore
             authTagLength: this.authTagLength,
         });
+        // @ts-ignore
         let encrypted = cipher.update(plainText, this.inputEncoding);
+        // @ts-ignore
         encrypted = Buffer.concat([encrypted, cipher.final()]);
         const authTag = cipher.getAuthTag();
         return {
+            // @ts-ignore
             iv: iv.toString(this.outputEncoding),
+            // @ts-ignore
             encrypted: encrypted.toString(this.outputEncoding),
+            // @ts-ignore
             authTag: authTag.toString(this.outputEncoding),
         };
     }
+    /**
+     * @typedef {Object} EncryptedDataParams
+     * @property {string} iv - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+     * @property {string} encrypted - The encrypted data to decrypt, encoded with the output encoding.
+     * @property {string} authTag - The authentication tag used to verify the integrity of the encrypted data.
+     */
     /**
      * Decrypts a previously encrypted value.
      *
      * The method checks the integrity of the data using the authentication tag (`authTag`) and ensures the data is properly decrypted.
      * After decryption, it automatically deserializes the data back to its original type.
      *
-     * @param {Object} params - An object containing the encrypted data:
-     *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-     *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-     *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+     * @param {EncryptedDataParams} params - An object containing the encrypted data.
      * @param {string|null} [expectedType=null] - Optionally specify the expected type of the decrypted data. If provided, the method will validate the type of the deserialized value.
      * @returns {*} The decrypted value, which will be the original type of the data before encryption.
      * @throws {Error} Throws if the authentication tag doesn't match or the data has been tampered with.
@@ -135,11 +143,15 @@ class TinyCrypto {
         const ivBuffer = Buffer.from(iv, this.outputEncoding);
         const encryptedBuffer = Buffer.from(encrypted, this.outputEncoding);
         const authTagBuffer = Buffer.from(authTag, this.outputEncoding);
-        const decipher = crypto.createDecipheriv(this.algorithm, this.key, ivBuffer, {
+        const decipher = createDecipheriv(this.algorithm, this.key, ivBuffer, {
+            // @ts-ignore
             authTagLength: this.authTagLength,
         });
         decipher.setAuthTag(authTagBuffer);
+        /** @type {string} */
+        // @ts-ignore
         let decrypted = decipher.update(encryptedBuffer, null, this.inputEncoding);
+        // @ts-ignore
         decrypted += decipher.final(this.inputEncoding);
         const { value, type } = this.#deserialize(decrypted);
         if (expectedType)
@@ -152,10 +164,7 @@ class TinyCrypto {
      * This method decrypts the encrypted data and extracts its type information without fully deserializing the value.
      * It is useful when you need to verify the type of the encrypted data before fully decrypting it.
      *
-     * @param {Object} params - An object containing the encrypted data:
-     *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-     *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-     *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+     * @param {EncryptedDataParams} params - An object containing the encrypted data.
      * @returns {string} The type of the original data (e.g., 'string', 'number', 'date', etc.).
      *
      * @example
@@ -171,11 +180,14 @@ class TinyCrypto {
         const ivBuffer = Buffer.from(iv, this.outputEncoding);
         const encryptedBuffer = Buffer.from(encrypted, this.outputEncoding);
         const authTagBuffer = Buffer.from(authTag, this.outputEncoding);
-        const decipher = crypto.createDecipheriv(this.algorithm, this.key, ivBuffer, {
+        const decipher = createDecipheriv(this.algorithm, this.key, ivBuffer, {
+            // @ts-ignore
             authTagLength: this.authTagLength,
         });
         decipher.setAuthTag(authTagBuffer);
+        // @ts-ignore
         let decrypted = decipher.update(encryptedBuffer, null, this.inputEncoding);
+        // @ts-ignore
         decrypted += decipher.final(this.inputEncoding);
         const { type } = this.#deserialize(decrypted);
         return typeof type === 'string' ? type : 'unknown';
@@ -265,10 +277,12 @@ class TinyCrypto {
     async loadConfigFromFile(file) {
         if (isBrowser) {
             return new Promise((resolve, reject) => {
+                if (!(file instanceof File))
+                    return reject(new Error('In browser, the file must be a File object'));
                 const reader = new FileReader();
                 reader.onload = () => {
                     try {
-                        const config = JSON.parse(reader.result);
+                        const config = typeof reader.result === 'string' ? JSON.parse(reader.result) : {};
                         resolve(this.importConfig(config));
                     }
                     catch (err) {
@@ -280,7 +294,7 @@ class TinyCrypto {
             });
         }
         else {
-            const raw = fs.readFileSync(file, 'utf8');
+            const raw = fs.readFileSync(/** @type {string} */ (file), 'utf8');
             const config = JSON.parse(raw);
             return this.importConfig(config);
         }
@@ -311,9 +325,11 @@ class TinyCrypto {
     async loadKeyFromFile(file) {
         if (isBrowser) {
             return new Promise((resolve, reject) => {
+                if (!(file instanceof File))
+                    return reject(new Error('In browser, the file must be a File object'));
                 const reader = new FileReader();
                 reader.onload = () => {
-                    const hexKey = reader.result.trim();
+                    const hexKey = typeof reader.result === 'string' ? reader.result.trim() : '';
                     const keyBuffer = Buffer.from(hexKey, 'hex');
                     this.key = keyBuffer;
                     resolve(keyBuffer);
@@ -323,7 +339,7 @@ class TinyCrypto {
             });
         }
         else {
-            const hexKey = fs.readFileSync(file, 'utf8');
+            const hexKey = fs.readFileSync(/** @type {string} */ (file), 'utf8');
             const keyBuffer = Buffer.from(hexKey, 'hex');
             this.key = keyBuffer;
             return keyBuffer;
@@ -367,8 +383,8 @@ class TinyCrypto {
      *
      * @param {Object} config - The configuration object to import.
      * @param {string} config.algorithm - The encryption algorithm (e.g., 'aes-256-gcm').
-     * @param {string} config.outputEncoding - The output encoding format (e.g., 'hex').
-     * @param {string} config.inputEncoding - The input encoding format (e.g., 'utf8').
+     * @param {BufferEncoding} config.outputEncoding - The output encoding format (e.g., 'hex').
+     * @param {BufferEncoding} config.inputEncoding - The input encoding format (e.g., 'utf8').
      * @param {number} config.authTagLength - The authentication tag length (e.g., 16).
      * @param {string} config.key - The cryptographic key in hexadecimal string format.
      *
@@ -415,7 +431,7 @@ class TinyCrypto {
      * Each key corresponds to a specific data type (e.g., 'number', 'date', 'buffer', etc.),
      * and the value is a function that serializes the data to a specific format.
      *
-     * @type {Object}
+     * @type {Record<string, (data: any) => string>}
      * @property {Function} weakmap - Throws an error as WeakMap cannot be serialized.
      * @property {Function} weakset - Throws an error as WeakSet cannot be serialized.
      * @property {Function} promise - Throws an error as Promise cannot be serialized.
@@ -456,8 +472,8 @@ class TinyCrypto {
         number: (data) => JSON.stringify({ __type: 'number', value: data }),
         boolean: (data) => JSON.stringify({ __type: 'boolean', value: data }),
         string: (data) => JSON.stringify({ __type: 'string', value: data }),
-        null: (data) => JSON.stringify({ __type: 'null' }),
-        undefined: (data) => JSON.stringify({ __type: 'undefined' }),
+        null: () => JSON.stringify({ __type: 'null' }),
+        undefined: () => JSON.stringify({ __type: 'undefined' }),
         map: (data) => JSON.stringify({
             __type: 'map',
             value: Array.from(data.entries()),
@@ -479,7 +495,7 @@ class TinyCrypto {
      * Each key corresponds to a specific data type (e.g., 'Date', 'BigInt', 'Buffer', etc.),
      * and the value is a function that deserializes the value to its original format.
      *
-     * @type {Object}
+     * @type {Record<string, (data: any) => any>}
      * @property {Function} regexp - Deserializes a regular expression from its string representation (e.g., `/pattern/flags`).
      * @property {Function} htmlelement - Deserializes an HTML element from its serialized outerHTML string (only works in browser environments).
      * @property {Function} date - Deserializes a date from its ISO string representation.
@@ -506,14 +522,14 @@ class TinyCrypto {
                 throw new Error('HTMLElement deserialization is only supported in browsers');
             const div = document.createElement('div');
             div.innerHTML = value;
-            return div.firstElementChild;
+            return div;
         },
         date: (value) => new Date(value),
         bigint: (value) => BigInt(value),
         number: (value) => Number(value),
         boolean: (value) => Boolean(value),
-        null: (value) => null,
-        undefined: (value) => undefined,
+        null: () => null,
+        undefined: () => undefined,
         map: (value) => new Map(value),
         set: (value) => new Set(value),
         symbol: (value) => Symbol(value),
@@ -533,7 +549,7 @@ class TinyCrypto {
      */
     #serialize(data) {
         const type = objType(data) || 'undefined';
-        if (this.#valueConvertTypes[type])
+        if (typeof type === 'string' && this.#valueConvertTypes[type])
             return this.#valueConvertTypes[type](data);
         throw new Error(`Unsupported data type for encryption: ${type}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",

package/webpack.config.mjs

@@ -1,69 +0,0 @@
-import path from 'path';
-import { fileURLToPath } from 'url';
-import webpack from 'webpack';
-import NodePolyfillPlugin from 'node-polyfill-webpack-plugin';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Add modules
-const modules = [];
-const addModule = (entry, library, isClass = false) => {
-  const baseConfig = {
-    entry,
-    output: {
-      path: path.resolve(__dirname, 'dist'),
-      library,
-      libraryTarget: 'window',
-      libraryExport: isClass ? library : undefined,
-    },
-    optimization: {
-      runtimeChunk: false,
-      splitChunks: false,
-    },
-    plugins: [
-      new NodePolyfillPlugin(),
-      new webpack.ProvidePlugin({
-        process: 'process/browser',
-      }),
-    ],
-  };
-  modules.push(
-    // Non-minified version
-    {
-      ...baseConfig,
-      mode: 'development',
-      output: {
-        ...baseConfig.output,
-        filename: `${library}.js`,
-      },
-      optimization: {
-        ...baseConfig.optimization,
-        minimize: false,
-      },
-    },
-    // Minified version
-    {
-      ...baseConfig,
-      mode: 'production',
-      output: {
-        ...baseConfig.output,
-        filename: `${library}.min.js`,
-      },
-      optimization: {
-        ...baseConfig.optimization,
-        minimize: true,
-      },
-    },
-  );
-};
-
-// Main
-addModule('./src/v1/index.mjs', 'TinyEssentials');
-addModule('./src/v1/basics/index.mjs', 'TinyBasicsEs');
-
-addModule('./src/v1/build/TinyLevelUp.mjs', 'TinyLevelUp', true);
-addModule('./src/v1/build/TinyCertCrypto.mjs', 'TinyCertCrypto', true);
-addModule('./src/v1/build/TinyCrypto.mjs', 'TinyCrypto', true);
-
-export default modules;