Peculiar Ventures TypeScript Utilities (pvtsutils)

1.3.6 · active · verified Sun Apr 19

pvtsutils is a utility library designed for TypeScript-based projects, offering a suite of common helper functions for data manipulation. Key functionalities include robust ArrayBuffer conversions, enabling seamless transformation between various string encodings such as hexadecimal, UTF-8, binary, Base64, and Base64Url. Additionally, it provides utilities for combining multiple ArrayBuffer instances, performing deep equality checks on buffers, and handling object property assignment akin to Object.assign. The library is currently stable at version 1.3.6, with consistent maintenance reflected in recent minor updates to its Convert class functionality. While it is built with TypeScript, its module system primarily supports CommonJS and UMD patterns, making it compatible with Node.js environments via require() and browser environments through script tags or AMD loaders. This design choice differentiates it from many modern ESM-first libraries, offering broad compatibility for existing codebases. Its focused approach on ArrayBuffer operations makes it particularly useful in cryptographic contexts, data processing pipelines, and other scenarios requiring low-level binary data handling.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'FromString') OR TypeError: pvtsutils.Convert is not a constructor
```
cause Attempting to use `Convert` or other utilities directly after an incorrect ESM named import.

fix Correct the import statement to `import * as pvtsutils from 'pvtsutils';` and then access `pvtsutils.Convert.FromString(...)`.
```
Error [ERR_REQUIRE_ESM]: require() of ES Module ...pvtsutils/lib/index.js not supported
```
cause This error is unlikely for pvtsutils itself (as it's CJS-first), but could occur if bundling tools incorrectly interpret it as ESM when it's consumed by a CJS module. More likely: `import ... from 'pvtsutils'` in CJS code.

fix For CommonJS environments, ensure you use `const pvtsutils = require('pvtsutils');`. If using ESM, use `import * as pvtsutils from 'pvtsutils';` and ensure your `tsconfig.json` and build setup are correctly configured for CJS interoperability.

Warnings

gotcha Despite being a TypeScript library, pvtsutils uses a CommonJS/UMD export style (`export = pvtsutils;`). This means direct named ESM imports like `import { Convert } from 'pvtsutils';` will not work out-of-the-box and typically result in a module resolution error.
Fix: Use a namespace import: `import * as pvtsutils from 'pvtsutils';` in ESM/TypeScript, or `const pvtsutils = require('pvtsutils');` in CommonJS. Then access members as `pvtsutils.Convert`, `pvtsutils.assign`, etc.
gotcha When working with `Convert.FromString` or `Convert.ToString`, ensure the encoding type matches the data. Passing incorrect encodings (e.g., 'hex' for a UTF-8 string) will lead to incorrect or corrupt data conversions without throwing explicit errors.
Fix: Always specify the correct encoding string (e.g., 'hex', 'utf8', 'binary', 'base64', 'base64url') based on the input data format. UTF-8 is the default if no encoding is provided.

Install

npm install pvtsutils npm
yarn add pvtsutils yarn
pnpm add pvtsutils pnpm

Imports

pvtsutils
wrong:
```
import { Convert, assign } from 'pvtsutils';
```
correct:
```
import * as pvtsutils from 'pvtsutils';
```
The library uses 'export = pvtsutils;' for CommonJS/UMD, requiring a namespace import in ESM/TypeScript. Direct named imports are not supported without bundler configuration.
pvtsutils (CommonJS)
```
const pvtsutils = require('pvtsutils');
```
This is the native and fully supported import method for Node.js CommonJS environments.

Convert class

wrong:

import { Convert } from 'pvtsutils';

correct:

import * as pvtsutils from 'pvtsutils';
const { Convert } = pvtsutils;

Access members like 'Convert' from the imported 'pvtsutils' namespace.

Quickstart

Demonstrates `Convert` for encoding/decoding, `assign` for object merging, `combine` for buffer concatenation, and `isEqual` for buffer comparison.

import * as pvtsutils from 'pvtsutils';

const { Convert, assign, combine, isEqual } = pvtsutils;

// 1. Convert strings to ArrayBuffer and back
const hexString = '736f6d6520737472696e67'; // 'some string'
const bufFromHex = Convert.FromString(hexString, 'hex');
console.log(`Buffer from hex: ${new Uint8Array(bufFromHex)}`);

const utf8String = Convert.ToString(bufFromHex, 'utf8');
console.log(`UTF-8 string from buffer: '${utf8String}'`);

const base64UrlString = Convert.ToString(bufFromHex, 'base64url');
console.log(`Base64URL string from buffer: '${base64UrlString}'`);

// 2. Assign properties to an object
const obj1 = { id: 1 };
const obj2 = { name: 'Bob' };
const obj3 = { age: 30, city: 'New York' };
const mergedObj = assign({}, obj1, obj2, obj3);
console.log('Merged Object:', mergedObj);

// 3. Combine ArrayBuffers
const bufferPart1 = new Uint8Array([1, 2, 3]).buffer;
const bufferPart2 = new Uint8Array([4, 5, 6]).buffer;
const combinedBuffer = combine(bufferPart1, bufferPart2);
console.log(`Combined Buffer: ${new Uint8Array(combinedBuffer)}`);

// 4. Compare ArrayBuffers
const sameBuffer = combine(bufferPart1, bufferPart2);
const areEqual = isEqual(combinedBuffer, sameBuffer);
console.log(`Are combined buffers equal? ${areEqual}`);

view raw JSON →