0
# PouchDB Binary Utils
1

2
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.
3

4
**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.
5

6
## Package Information
7

8
- **Package Name**: pouchdb-binary-utils
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install pouchdb-binary-utils --save-exact`
12

13
## Core Imports
14

15
```javascript
16
import {
17
  atob,
18
  btoa,
19
  base64StringToBlobOrBuffer,
20
  binaryStringToArrayBuffer,
21
  binaryStringToBlobOrBuffer,
22
  blob,
23
  blobOrBufferToBase64,
24
  blobOrBufferToBinaryString,
25
  readAsArrayBuffer,
26
  readAsBinaryString,
27
  typedBuffer
28
} from "pouchdb-binary-utils";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const {
35
  atob,
36
  btoa,
37
  base64StringToBlobOrBuffer,
38
  binaryStringToArrayBuffer,
39
  binaryStringToBlobOrBuffer,
40
  blob,
41
  blobOrBufferToBase64,
42
  blobOrBufferToBinaryString,
43
  readAsArrayBuffer,
44
  readAsBinaryString,
45
  typedBuffer
46
} = require("pouchdb-binary-utils");
47
```
48

49
## Basic Usage
50

51
```javascript
52
import { atob, btoa, blobOrBufferToBase64, typedBuffer } from "pouchdb-binary-utils";
53

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

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

62
// Convert buffer to base64 (async)
63
blobOrBufferToBase64(buffer, (base64Result) => {
64
  console.log(base64Result); // Base64 encoded string
65
});
66
```
67

68
## Architecture
69

70
PouchDB Binary Utils is designed around environment-specific implementations:
71

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

78
## Capabilities
79

80
### Base64 Encoding/Decoding
81

82
Standard base64 encoding and decoding with cross-platform implementations.
83

84
```javascript { .api }
85
/**
86
 * Decodes a base64-encoded string to binary string
87
 * @param {string} str - Base64 encoded string
88
 * @returns {string} Binary string
89
 */
90
function atob(str);
91

92
/**
93
 * Encodes a binary string to base64
94
 * @param {string} str - Binary string
95
 * @returns {string} Base64 encoded string
96
 */
97
function btoa(str);
98
```
99

100
### Binary String Conversion
101

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

104
```javascript { .api }
105
/**
106
 * Converts binary string to ArrayBuffer (browser only)
107
 * @param {string} binaryString - Binary string data
108
 * @returns {ArrayBuffer} ArrayBuffer containing the binary data
109
 */
110
function binaryStringToArrayBuffer(binaryString);
111

112
/**
113
 * Converts binary string to Blob/Buffer with specified MIME type
114
 * @param {string} binaryString - Binary string data
115
 * @param {string} type - MIME type string
116
 * @returns {Buffer|Blob} Buffer (Node.js) or Blob (browser)
117
 */
118
function binaryStringToBlobOrBuffer(binaryString, type);
119
```
120

121
### Base64 to Binary Object Conversion
122

123
Converting base64 strings directly to Blob/Buffer objects.
124

125
```javascript { .api }
126
/**
127
 * Converts base64 string to Blob/Buffer with specified MIME type
128
 * @param {string} b64 - Base64 encoded string
129
 * @param {string} type - MIME type string
130
 * @returns {Buffer|Blob} Buffer (Node.js) or Blob (browser)
131
 */
132
function base64StringToBlobOrBuffer(b64, type);
133
```
134

135
### Blob/Buffer Creation
136

137
Creating and manipulating binary objects across environments.
138

139
```javascript { .api }
140
/**
141
 * Creates Blob objects with cross-platform compatibility
142
 * @param {Array} parts - Array of data parts
143
 * @param {Object} properties - Blob properties including type
144
 * @param {string} [properties.type] - MIME type string
145
 * @param {string} [properties.endings] - Line ending normalization ('transparent' or 'native')
146
 * @returns {Blob|Function} Blob (browser) or empty function (Node.js)
147
 */
148
function blob(parts, properties);
149

150
/**
151
 * Creates Buffer with optional type property (Node.js only)
152
 * @param {string} binString - Binary string data
153
 * @param {string} buffType - Either 'binary' or 'base64'
154
 * @param {string} type - MIME type to assign as property
155
 * @returns {Buffer|undefined} Buffer with type property (Node.js) or undefined (browser)
156
 */
157
function typedBuffer(binString, buffType, type);
158
```
159

160
### Blob/Buffer to String Conversion
161

162
Converting binary objects back to string formats via callbacks.
163

164
```javascript { .api }
165
/**
166
 * Converts Blob/Buffer to base64 string via callback
167
 * @param {Blob|Buffer} blobOrBuffer - Binary data object
168
 * @param {function} callback - Callback function receiving base64 string
169
 * @param {string} callback.result - The base64 encoded result
170
 */
171
function blobOrBufferToBase64(blobOrBuffer, callback);
172

173
/**
174
 * Converts Blob/Buffer to binary string via callback (browser only)
175
 * @param {Blob|Buffer} blobOrBuffer - Binary data object
176
 * @param {function} callback - Callback function receiving binary string
177
 * @param {string} callback.result - The binary string result
178
 */
179
function blobOrBufferToBinaryString(blobOrBuffer, callback);
180
```
181

182
### File Reading Operations
183

184
Reading Blob objects via FileReader API (browser only).
185

186
```javascript { .api }
187
/**
188
 * Reads Blob as ArrayBuffer via callback using FileReader (browser only)
189
 * @param {Blob} blob - Blob object to read
190
 * @param {function} callback - Callback function receiving ArrayBuffer
191
 * @param {ArrayBuffer} callback.result - The ArrayBuffer result
192
 */
193
function readAsArrayBuffer(blob, callback);
194

195
/**
196
 * Reads Blob as binary string via callback using FileReader (browser only)
197
 * @param {Blob} blob - Blob object to read
198
 * @param {function} callback - Callback function receiving binary string
199
 * @param {string} callback.result - The binary string result
200
 */
201
function readAsBinaryString(blob, callback);
202
```
203

204
## Types
205

206
```javascript { .api }
207
/**
208
 * @typedef {Object} BlobPropertyBag
209
 * @property {string} [type] - MIME type string
210
 * @property {string} [endings] - Line ending normalization ('transparent' or 'native') 
211
 */
212
```
213

214
## Environment Differences
215

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

223
### Browser Environment  
224
- Uses `Blob` objects for binary data
225
- Uses native `atob`/`btoa` functions when available
226
- Includes FileReader-based functions for reading Blobs
227
- Provides fallbacks for older browsers without native APIs
228
- `binaryStringToArrayBuffer` available for ArrayBuffer conversion
229
- `typedBuffer()` function returns undefined (no-op in browser)
230

231
## Error Handling
232

233
The package includes validation for base64 strings:
234
- `atob()` throws an Error if the input is not a valid base64 string
235
- Invalid base64 strings are detected by round-trip validation in Node.js implementation
236

237
## Usage Notes
238

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