or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-pouchdb-binary-utils

PouchDB utilities for operating on binary strings and Buffers/Blobs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pouchdb-binary-utils@9.0.x

To install, run

npx @tessl/cli install tessl/npm-pouchdb-binary-utils@9.0.0

index.mddocs/

PouchDB Binary Utils

PouchDB Binary Utils provides cross-platform utilities for operating on binary strings, Buffers, and Blobs within the PouchDB ecosystem. It handles binary data conversion between different formats (base64, binary strings, ArrayBuffers, Blobs, Buffers) with environment-specific optimizations for both browser and Node.js environments.

Note: This package is conceptually an internal API used by PouchDB and its plugins. It is part of the PouchDB monorepo and does not follow semantic versioning, with versions pegged to PouchDB releases.

Package Information

  • Package Name: pouchdb-binary-utils
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install pouchdb-binary-utils --save-exact

Core Imports

import {
  atob,
  btoa,
  base64StringToBlobOrBuffer,
  binaryStringToArrayBuffer,
  binaryStringToBlobOrBuffer,
  blob,
  blobOrBufferToBase64,
  blobOrBufferToBinaryString,
  readAsArrayBuffer,
  readAsBinaryString,
  typedBuffer
} from "pouchdb-binary-utils";

For CommonJS:

const {
  atob,
  btoa,
  base64StringToBlobOrBuffer,
  binaryStringToArrayBuffer,
  binaryStringToBlobOrBuffer,
  blob,
  blobOrBufferToBase64,
  blobOrBufferToBinaryString,
  readAsArrayBuffer,
  readAsBinaryString,
  typedBuffer
} = require("pouchdb-binary-utils");

Basic Usage

import { atob, btoa, blobOrBufferToBase64, typedBuffer } from "pouchdb-binary-utils";

// Convert between base64 and binary strings
const base64Data = "SGVsbG8gV29ybGQ=";
const binaryString = atob(base64Data); // "Hello World"
const backToBase64 = btoa(binaryString); // "SGVsbG8gV29ybGQ="

// Create typed buffer
const buffer = typedBuffer("Hello", "binary", "text/plain");

// Convert buffer to base64 (async)
blobOrBufferToBase64(buffer, (base64Result) => {
  console.log(base64Result); // Base64 encoded string
});

Architecture

PouchDB Binary Utils is designed around environment-specific implementations:

  • Cross-Platform API: Consistent function signatures across Node.js and browser
  • Environment Detection: Automatic selection of optimal implementation per environment
  • Buffer/Blob Abstraction: Uses Node.js Buffers or browser Blobs transparently
  • Legacy Browser Support: Fallbacks for older browsers without native APIs
  • Callback Pattern: Async operations use callback pattern for compatibility

Capabilities

Base64 Encoding/Decoding

Standard base64 encoding and decoding with cross-platform implementations.

/**
 * Decodes a base64-encoded string to binary string
 * @param {string} str - Base64 encoded string
 * @returns {string} Binary string
 */
function atob(str);

/**
 * Encodes a binary string to base64
 * @param {string} str - Binary string
 * @returns {string} Base64 encoded string
 */
function btoa(str);

Binary String Conversion

Converting binary strings to other formats for cross-platform data handling.

/**
 * Converts binary string to ArrayBuffer (browser only)
 * @param {string} binaryString - Binary string data
 * @returns {ArrayBuffer} ArrayBuffer containing the binary data
 */
function binaryStringToArrayBuffer(binaryString);

/**
 * Converts binary string to Blob/Buffer with specified MIME type
 * @param {string} binaryString - Binary string data
 * @param {string} type - MIME type string
 * @returns {Buffer|Blob} Buffer (Node.js) or Blob (browser)
 */
function binaryStringToBlobOrBuffer(binaryString, type);

Base64 to Binary Object Conversion

Converting base64 strings directly to Blob/Buffer objects.

/**
 * Converts base64 string to Blob/Buffer with specified MIME type
 * @param {string} b64 - Base64 encoded string
 * @param {string} type - MIME type string
 * @returns {Buffer|Blob} Buffer (Node.js) or Blob (browser)
 */
function base64StringToBlobOrBuffer(b64, type);

Blob/Buffer Creation

Creating and manipulating binary objects across environments.

/**
 * Creates Blob objects with cross-platform compatibility
 * @param {Array} parts - Array of data parts
 * @param {Object} properties - Blob properties including type
 * @param {string} [properties.type] - MIME type string
 * @param {string} [properties.endings] - Line ending normalization ('transparent' or 'native')
 * @returns {Blob|Function} Blob (browser) or empty function (Node.js)
 */
function blob(parts, properties);

/**
 * Creates Buffer with optional type property (Node.js only)
 * @param {string} binString - Binary string data
 * @param {string} buffType - Either 'binary' or 'base64'
 * @param {string} type - MIME type to assign as property
 * @returns {Buffer|undefined} Buffer with type property (Node.js) or undefined (browser)
 */
function typedBuffer(binString, buffType, type);

Blob/Buffer to String Conversion

Converting binary objects back to string formats via callbacks.

/**
 * Converts Blob/Buffer to base64 string via callback
 * @param {Blob|Buffer} blobOrBuffer - Binary data object
 * @param {function} callback - Callback function receiving base64 string
 * @param {string} callback.result - The base64 encoded result
 */
function blobOrBufferToBase64(blobOrBuffer, callback);

/**
 * Converts Blob/Buffer to binary string via callback (browser only)
 * @param {Blob|Buffer} blobOrBuffer - Binary data object
 * @param {function} callback - Callback function receiving binary string
 * @param {string} callback.result - The binary string result
 */
function blobOrBufferToBinaryString(blobOrBuffer, callback);

File Reading Operations

Reading Blob objects via FileReader API (browser only).

/**
 * Reads Blob as ArrayBuffer via callback using FileReader (browser only)
 * @param {Blob} blob - Blob object to read
 * @param {function} callback - Callback function receiving ArrayBuffer
 * @param {ArrayBuffer} callback.result - The ArrayBuffer result
 */
function readAsArrayBuffer(blob, callback);

/**
 * Reads Blob as binary string via callback using FileReader (browser only)
 * @param {Blob} blob - Blob object to read
 * @param {function} callback - Callback function receiving binary string
 * @param {string} callback.result - The binary string result
 */
function readAsBinaryString(blob, callback);

Types

/**
 * @typedef {Object} BlobPropertyBag
 * @property {string} [type] - MIME type string
 * @property {string} [endings] - Line ending normalization ('transparent' or 'native') 
 */

Environment Differences

Node.js Environment

  • Uses Node.js Buffer objects for binary data
  • Implements atob/btoa using Buffer.from() with validation
  • File reading functions (readAsArrayBuffer, readAsBinaryString) are exported but will throw errors if used (browser-only functionality)
  • blob() function returns empty function since Blobs are browser-specific
  • typedBuffer() function creates Buffer objects with type property

Browser Environment

  • Uses Blob objects for binary data
  • Uses native atob/btoa functions when available
  • Includes FileReader-based functions for reading Blobs
  • Provides fallbacks for older browsers without native APIs
  • binaryStringToArrayBuffer available for ArrayBuffer conversion
  • typedBuffer() function returns undefined (no-op in browser)

Error Handling

The package includes validation for base64 strings:

  • atob() throws an Error if the input is not a valid base64 string
  • Invalid base64 strings are detected by round-trip validation in Node.js implementation

Usage Notes

  • This package is conceptually an internal API for PouchDB and plugins
  • Install with --save-exact flag as it follows PouchDB versioning, not semantic versioning
  • Callback-based async operations for broad compatibility
  • Environment-specific optimizations are handled automatically
  • Type properties on buffers/blobs are non-standard but used for consistency across environments