0
# MZ - Modernize Node.js
1

2
MZ is a Node.js library that modernizes Node.js core APIs to current ECMAScript standards by providing promise-based wrappers for callback-based methods. It enables clean async/await syntax with Node.js core APIs without requiring Node.js API updates, making it ideal for applications wanting to modernize their asynchronous code patterns while maintaining compatibility with existing Node.js ecosystem tools.
3

4
## Package Information
5

6
- **Package Name**: mz
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mz`
10

11
## Core Imports
12

13
Individual module imports (recommended):
14

15
```javascript
16
const fs = require('mz/fs');
17
const crypto = require('mz/crypto');
18
const dns = require('mz/dns');
19
const zlib = require('mz/zlib');
20
const readline = require('mz/readline');
21
const child_process = require('mz/child_process');
22
```
23

24
Full library import:
25

26
```javascript
27
const mz = require('mz');
28
const fs = mz.fs;
29
const crypto = mz.crypto;
30
// etc...
31
```
32

33
## Basic Usage
34

35
```javascript
36
const fs = require('mz/fs');
37
const crypto = require('mz/crypto');
38

39
async function example() {
40
  // Check if file exists
41
  if (await fs.exists('./package.json')) {
42
    // Read file contents
43
    const content = await fs.readFile('./package.json', 'utf8');
44
    console.log('Package.json content:', content);
45
  }
46
  
47
  // Generate random bytes
48
  const randomData = await crypto.randomBytes(16);
49
  console.log('Random bytes:', randomData.toString('hex'));
50
}
51
```
52

53
## Architecture
54

55
MZ uses several key libraries and patterns:
56

57
- **Promise Engine**: Uses `any-promise` for flexible promise implementation compatibility
58
- **Thenification**: Uses `thenify-all` to convert callback-based methods to promise-based
59
- **Dual Interface**: All async methods support both promises and callbacks
60
- **Graceful Enhancement**: Uses `graceful-fs` when available, falls back to native `fs`
61
- **Native Compatibility**: Non-async and deprecated properties are proxied unchanged
62

63
## Capabilities
64

65
### File System Operations
66

67
Comprehensive promise-based file system operations with graceful-fs integration and custom exists() implementation.
68

69
```javascript { .api }
70
// Core file operations
71
function readFile(path, options): Promise<Buffer | string>;
72
function writeFile(file, data, options): Promise<void>;
73
function stat(path, options): Promise<Stats>;
74
function exists(path): Promise<boolean>;
75

76
// Directory operations
77
function mkdir(path, options): Promise<void>;
78
function readdir(path, options): Promise<string[] | Dirent[]>;
79
function rmdir(path, options): Promise<void>;
80
```
81

82
[File System Operations](./fs.md)
83

84
### Child Process Operations
85

86
Execute shell commands and spawn processes with promise support.
87

88
```javascript { .api }
89
function exec(command, options): Promise<string>;
90
function execFile(file, args, options): Promise<string>;
91
```
92

93
[Child Process Operations](./child-process.md)
94

95
### Cryptographic Operations
96

97
Generate random data and perform key derivation with promise support.
98

99
```javascript { .api }
100
function randomBytes(size): Promise<Buffer>;
101
function pbkdf2(password, salt, iterations, keylen, digest): Promise<Buffer>;
102
function pseudoRandomBytes(size): Promise<Buffer>;
103
```
104

105
[Cryptographic Operations](./crypto.md)
106

107
### DNS Operations
108

109
Perform DNS lookups and resolve various record types with promise support.
110

111
```javascript { .api }
112
function lookup(hostname, options): Promise<LookupResult>;
113
function resolve(hostname, rrtype): Promise<string[] | object[]>;
114
function resolve4(hostname, options): Promise<string[]>;
115
function resolve6(hostname, options): Promise<string[]>;
116
```
117

118
[DNS Operations](./dns.md)
119

120
### Interactive Readline
121

122
Create interactive command-line interfaces with promise-based question handling and completer support.
123

124
```javascript { .api }
125
function createInterface(options): Interface;
126

127
class Interface {
128
  question(query): Promise<string>;
129
}
130
```
131

132
[Interactive Readline](./readline.md)
133

134
### Compression Operations
135

136
Compress and decompress data using various algorithms with promise support.
137

138
```javascript { .api }
139
function gzip(buffer, options): Promise<Buffer>;
140
function gunzip(buffer, options): Promise<Buffer>;
141
function deflate(buffer, options): Promise<Buffer>;
142
function inflate(buffer, options): Promise<Buffer>;
143
```
144

145
[Compression Operations](./zlib.md)
146

147
## Types
148

149
```javascript { .api }
150
// Common callback signature for dual interface support
151
type CallbackFunction<T> = (err: Error | null, result?: T) => void;
152

153
// All async functions support both interfaces:
154
// - Promise: functionName(args): Promise<T>
155
// - Callback: functionName(args, callback: CallbackFunction<T>): void
156
```