NodeJS 工具模块 #53
Description
概述
1. assert
assert 模块提供了断言测试的函数，用于测试不变式。
2. Buffer（缓冲区）
Buffer 类的实例类似于整数数组，但 Buffer 的大小是固定的、且在 V8 堆外分配物理内存。 Buffer 的大小在被创建时确定，且无法调整。
API：
创建缓冲区：
类方法：Buffer.alloc(size[, fill[, encoding]])
类方法：Buffer.allocUnsafe(size)
类方法：Buffer.allocUnsafeSlow(size)
类方法：Buffer.byteLength(string[, encoding])
类方法：Buffer.compare(buf1, buf2)
类方法：Buffer.concat(list[, totalLength])
类方法：Buffer.from(array)
类方法：Buffer.from(arrayBuffer[, byteOffset[, length]])
类方法：Buffer.from(buffer)
类方法：Buffer.from(string[, encoding])
类方法：Buffer.from(object[, offsetOrEncoding[, length]])
类方法：Buffer.isBuffer(obj)
类方法：Buffer.isEncoding(encoding)
写入缓冲区
从缓冲区读取数据
将 Buffer 转换为 JSON 对象
缓冲区合并
缓冲区比较
拷贝缓冲区
缓冲区裁剪
缓冲区长度
3. console
console 模块提供了一个简单的调试控制台，类似于 Web 浏览器提供的 JavaScript 控制台。
API：
创建Console类：
new Console(stdout[, stderr][, ignoreErrors])
new Console(options)
用一个或两个输出流实例创建一个新的 Console。 输出流 stdout 用来记录日志和信息；stderr 用来记录警告和错误。如果不提供 stderr，则 stdout 会被用作 stderr。
4. crypto
crypto 模块提供了加密功能，包含对 OpenSSL 的哈希、HMAC、加密、解密、签名、以及验证功能的一整套封装。
5. Error
类别：
- 标准的 JavaScript 错误
- 由底层操作系触发的系统错误
- 由应用程序代码触发的用户自定义的错误
- 断言错误是错误的一个特殊类别，每当 Node.js 检测到一个不应该发生的异常逻辑时触发
API：
创建Error：
new Error(message)
error.code
error.message
error.stack
AssertionError
RangeError
ReferenceError
SyntaxError
TypeError
6. path
path 模块提供了一些工具函数，用于处理文件与目录的路径。
API：
path.posix，提供了 path 方法针对 POSIX 的实现。
path.win32，提供了 path 方法针对 Windows 的实现。
path.sep，提供了平台特定的路径内的分隔符。
path.delimiter，提供平台特定的路径间的分隔符。
path.basename(path[, ext])，返回一个 path 的最后一部分。
path.dirname(path)，返回一个 path 的目录名。
path.extname(path)，返回 path 的扩展名，即从 path 的最后一部分中的最后一个 .（句号）字符到字符串结束。
path.isAbsolute(path)，判定 path 是否为一个绝对路径。
path.relative(from, to)，返回从 from 到 to 的相对路径（基于当前工作目录）。
path.join([...paths])，使用平台特定的分隔符把全部给定的 path 片段连接到一起，并规范化生成的路径。
path.format(pathObject)，从一个对象返回一个路径字符串。 与 path.parse() 相反。
path.normalize(path)，规范化给定的 path，并解析 '..' 和 '.' 片段。
path.parse(path)，返回一个对象，对象的属性表示 path 的元素。
path.resolve([...paths])，把一个路径或路径片段的序列解析为一个绝对路径。给定的路径的序列是从右往左被处理的，后面每个 path 被依次解析，直到构造完成一个绝对路径。如果处理完全部给定的 path 片段后还未生成一个绝对路径，则当前工作目录会被用上。
path.toNamespacedPath(path)
path会根据运行环境，调用path.posix或者path.win32的API。也就是说path的api和path.posix、path.win32的api是一样的，这里用的是代理模式。
7. querystring
querystring 模块提供了一些实用函数，用于解析与格式化 URL 查询字符串。
API：
querystring.escape(str)，对给定的 str 进行 URL 编码。该方法是提供给 querystring.stringify() 使用的，通常不直接使用。
querystring.parse(str[, sep[, eq[, options]]])，该方法会把一个 URL 查询字符串 str 解析成一个键值对的集合。
querystring.stringify(obj[, sep[, eq[, options]]])，该方法通过遍历给定的 obj 对象的自身属性，生成 URL 查询字符串。
querystring.unescape(str)，对给定的 str 进行解码。该方法是提供给 querystring.parse() 使用的，通常不直接使用。
8. readline
require('readline') 模块提供了一个接口，用于从可读流（如 process.stdin）读取数据，每次读取一行。
API：
readline.clearLine(stream, dir)，，以 dir 指定的方向清除给定的 TTY 流的当前行。
readline.clearScreenDown(stream)，从光标的当前位置向下清除给定的 TTY 流。
readline.createInterface(options)，创建一个新的 readline.Interface 实例。
readline.cursorTo(stream, x, y)，会移动光标到给定的 TTY stream 中指定的位置。
readline.emitKeypressEvents(stream[, interface])
readline.moveCursor(stream, dx, dy)，移动光标到给定的 TTY stream 中相对当前的位置。
Interface
事件：
'close' 事件
'line' 事件，每当 input 流接收到接收行结束符（\n、\r 或 \r\n）时触发 'line' 事件。
'pause' 事件
'resume' 事件
'SIGCONT' 事件
'SIGINT' 事件
'SIGTSTP' 事件
API：
rl.close()，关闭 readline.Interface 实例，且撤回对 input 和 output 流的控制。
rl.pause()，暂停 input 流，且稍后需要时可被恢复。
rl.prompt([preserveCursor])，在 output 流中新的一行写入 readline.Interface 实例配置后的 prompt，用于为用户提供一个可供输入的新的位置。
rl.question(query, callback)，通过写入到 output 来展示 query，并等待用户提供到 input 的输入，然后调用 callback 函数并传入提供的输入作为第一个参数。
rl.resume()，如果 input 流已被暂停，则 rl.resume() 方法会恢复 input 流。
rl.setPrompt(prompt)，设置每当 rl.prompt() 被调用时要被写入到 output 的提示。
rl.write(data[, key])，把 data 或一个由 key 指定的按键序列写入到 output。 只有当 output 是一个 TTY 文本终端时，key 参数才被支持。
9. stream
流（stream）是一种在 Node.js 中处理流式数据的抽象接口。 stream 模块提供了一些基础的 API，用于构建实现了流接口的对象。
流可以是可读的、可写的、或是可读写的。 所有的流都是 EventEmitter 的实例。
类型：
- Writable - 可写入数据的流（例如 fs.createWriteStream()）。
- Readable - 可读取数据的流（例如 fs.createReadStream()）。
- Duplex - 可读又可写的流（例如 net.Socket）。
- Transform - 在读写过程中可以修改或转换数据的 Duplex 流（例如 zlib.createDeflate()）。
缓冲：
可写流和可读流都会在一个内部的缓冲器中存储数据，可以分别使用的 writable.writableBuffer 或 readable.readableBuffer 来获取。
可写流：
事件：
'close' 事件，当流或其底层资源（比如文件描述符）被关闭时，触发 'close' 事件。
'drain' 事件，如果调用 stream.write(chunk) 方法返回 false，则在适合恢复写入数据到流时触发 'drain' 事件。
'error' 事件
'finish' 事件，调用 stream.end() 方法且缓冲数据都已经传给底层系统之后，触发 'finish' 事件。
'pipe' 事件，当在可读流上调用 stream.pipe() 方法添加可写流到目标流向时，触发 'pipe' 事件。
'unpipe' 事件，当在可读流上调用 stream.unpipe() 方法从目标流向中移除当前可写流时，触发 'unpipe' 事件。
API：
writable.cork()，强制把所有写入的数据都缓冲到内存中。
writable.destroy([error])，摧毁流，并触发传入的 'error' 与 'close' 事件。
writable.end([chunk][, encoding][, callback])，调用 writable.end() 方法表明已没有数据要被写入可写流。
writable.setDefaultEncoding(encoding)
writable.uncork()，输出 stream.cork() 方法被调用后缓冲的全部数据。
writable.writableHighWaterMark，返回当构造可写流时传入的 highWaterMark 的值。
writable.writableLength，返回队列中准备被写入的字节数（或对象数）。
writable.write(chunk[, encoding][, callback])，写入一些数据到流中，并在这些数据被完全处理之后调用提供的 callback 。
可读流：
两种模式：
可读流实质上运作于流动中（flowing）或已暂停（paused）两种模式之一。
在 flowing 模式中，数据自动地从底层的系统被读取，并通过 EventEmitter 接口的事件尽可能快地被提供给应用程序。
在 paused 模式中，必须显式调用 stream.read() 方法来从流中读取数据片段。
需要记住的重要概念是，只有提供了消费或忽略数据的机制后，可读流才会产生数据。 如果消费的机制被禁用或移除，则可读流会停止产生数据。
三种状态：
当 readable.readableFlowing 为 null 时，没有提供消费流数据的机制，所以流不会产生数据。 在这个状态下，监听 'data' 事件、调用 readable.pipe() 方法、或调用 readable.resume() 方法， 则 readable.readableFlowing 会变成 true ，可读流开始主动地产生数据触发事件。
调用 readable.pause()、readable.unpipe()、或接收背压，则 readable.readableFlowing 会被设为 false，暂时停止事件流动但不会停止数据的生成。 在这个状态下，为 'data' 事件设置监听器不会使 readable.readableFlowing 变成 true。
事件：
'close' 事件
'data' 事件，'data' 事件会在流将数据传递给消费者时触发。
'end' 事件，'end' 事件将在流中再没有数据可供消费时触发。
'error' 事件
'readable' 事件，'readable' 事件将在流中有数据可供读取时触发。
API：
readable.destroy([error])，销毁流，并且触发error事件。然后，可读流将释放所有的内部资源。
readable.isPaused()，返回可读流的当前操作状态。
readable.pause()，将会使 flowing 模式的流停止触发 'data' 事件， 进而切出 flowing 模式。
readable.pipe(destination[, options])，readable.pipe() 绑定一个 Writable 到 readable 上， 将可写流自动切换到 flowing 模式并将所有数据传给绑定的 Writable。
readable.read([size])，readable.read()方法从内部缓冲区中抽出并返回一些数据。 如果没有可读的数据，返回null。
readable.readableHighWaterMark
readable.readableLength
readable.resume()，readable.resume() 方法会重新触发 'data' 事件, 将暂停模式切换到流动模式。
readable.setEncoding(encoding)
readable.unpipe([destination])，如果 destination 没有传入, 则所有绑定的流都会被分离。
readable.unshift(chunk)
readable.wrap(stream)
readable[Symbol.asyncIterator]()
10. string_decoder
string_decoder 模块提供了一个 API，用于把 Buffer 对象解码成字符串，但会保留编码过的多字节 UTF-8 与 UTF-16 字符。
StringDecoder类：
new StringDecoder([encoding])，创建一个新的 StringDecoder 实例。
stringDecoder.end([buffer])，以字符串的形式返回内部 buffer 中剩余的字节。
stringDecoder.write(buffer)，返回一个解码后的字符串，并确保返回的字符串不包含 Buffer 末尾残缺的多字节字符，残缺的多字节字符会被保存在一个内部的 buffer 中用于下次调用 stringDecoder.write() 或 stringDecoder.end()。
11. timer
timer 模块暴露了一个全局的 API，用于在某个未来时间段调用调度函数。
API：
Immediate 类，该对象是内部创建的，并从 setImmediate() 返回。它可以传给 clearImmediate() 以便取消预定的动作。
Immediate 类，该对象是内部创建的，并从 setTimeout() 和 setInterval() 返回。 它可以传给 clearTimeout() 或 clearInterval() 以便取消预定的动作。
setImmediate(callback[, ...args])
setInterval(callback, delay[, ...args])
setTimeout(callback, delay[, ...args])
clearImmediate(immediate)
clearInterval(timeout)
clearTimeout(timeout)
12. url
url 模块提供了一些实用函数，用于 URL 处理与解析。
URL 字符串与 URL 对象：
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ href │
├──────────┬──┬─────────────────────┬─────────────────────┬───────────────────────────┬───────┤
│ protocol │ │ auth │ host │ path │ hash │
│ │ │ ├──────────────┬──────┼──────────┬────────────────┤ │
│ │ │ │ hostname │ port │ pathname │ search │ │
│ │ │ │ │ │ ├─┬──────────────┤ │
│ │ │ │ │ │ │ │ query │ │
" https: // user : pass @ sub.host.com : 8080 /p/a/t/h ? query=string #hash "
│ │ │ │ │ hostname │ port │ │ │ │
│ │ │ │ ├──────────────┴──────┤ │ │ │
│ protocol │ │ username │ password │ host │ │ │ │
├──────────┴──┼──────────┴──────────┼─────────────────────┤ │ │ │
│ origin │ │ origin │ pathname │ search │ hash │
├─────────────┴─────────────────────┴─────────────────────┴──────────┴────────────────┴───────┤
│ href │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
(请忽略字符串中的空格，它们只是为了排版需要)
API：
Class: URL
Constructor: new URL(input[, base])
url.hash
url.host
url.hostname
url.href
url.origin
url.password
url.pathname
url.port
url.protocol
url.search，获取及设置URL的序列化查询(query)部分部分。
url.searchParams，获取表示URL查询参数的URLSearchParams对象。
url.username
url.toString()
url.toJSON()，在URL对象上调用toJSON()方法将返回序列化的URL。返回值与url.href和url.toString()的相同。
Class: URLSearchParams
Constructor: new URLSearchParams()
Constructor: new URLSearchParams(string)
Constructor: new URLSearchParams(obj)
Constructor: new URLSearchParams(iterable)
urlSearchParams.append(name, value)
urlSearchParams.delete(name)
urlSearchParams.entries()
urlSearchParams.forEach(fn[, thisArg])
urlSearchParams.get(name)
urlSearchParams.getAll(name)
urlSearchParams.has(name)
urlSearchParams.keys()
urlSearchParams.set(name, value)
urlSearchParams.sort()
urlSearchParams.toString()
urlSearchParams.values()
urlSearchParams[Symbol.iterator]()
url.domainToASCII(domain)
url.domainToUnicode(domain)
url.format(URL[, options])
13. util
util 模块主要用于支持 Node.js 内部 API 的需求。 大部分实用工具也可用于应用程序与模块开发者。
API：
util.callbackify(original)，将 async 异步函数(或者一个返回值为 Promise 的函数)转换成遵循异常优先的回调风格的函数。
util.debuglog(section)，util.debuglog() 方法用于创建一个函数，基于 NODE_DEBUG 环境变量的存在与否有条件地写入调试信息到 stderr。
util.deprecate(fn, msg[, code])，标记类或函数为过期的。
util.format(format[, ...args])，返回一个格式化后的字符串，使用第一个参数作为一个类似 printf 的格式。
util.formatWithOptions(inspectOptions, format[, ...args])
util.getSystemErrorName(err)
util.inherits(constructor, superConstructor)，不建议使用 util.inherits()。 请使用 ES6 的 class 和 extends 关键词获得语言层面的继承支持。
util.inspect(object[, options])，返回 object 的字符串表示，主要用于调试。
util.isDeepStrictEqual(val1, val2)，深度相等意味着子对象中可枚举的自身属性也会按以下规则递归地比较。
util.promisify(original)，让一个遵循异常优先的回调风格的函数， 即 (err, value) => ... 回调函数是最后一个参数, 返回一个返回值是一个 promise 版本的函数。
util.TextDecoder
util.TextEncoder
util.types，提供很多判断类型的方法。
14. zlib
zlib模块提供通过 Gzip 和 Deflate/Inflate 实现的压缩功能。
API：
Class: Options
Class: zlib.Deflate，使用 deflate 压缩数据。
Class: zlib.DeflateRaw，使用 deflate 压缩数据，并且不附加一个 zlib 头。
Class: zlib.Gunzip，解压缩 gzip 流。
Class: zlib.Gzip，使用 gzip 压缩数据。
Class: zlib.Inflate，解压一个 deflate 流。
Class: zlib.InflateRaw，解压一个 raw deflate 流。
Class: zlib.Unzip，通过自动检测头信息解压 Gzip 或者 Deflate 压缩的流。
Class: zlib.Zlib，没有被 zlib 模块导出. 它被记录于此因为它是 compressor/decompressor 类的基础类。
zlib.constants
zlib.createDeflate([options])
zlib.createDeflateRaw([options])
zlib.createGunzip([options])
zlib.createGzip([options])
zlib.createInflate([options])
zlib.createInflateRaw([options])
zlib.createUnzip([options])
zlib.deflate(buffer[, options], callback)
zlib.deflateSync(buffer[, options])
zlib.deflateRaw(buffer[, options], callback)
zlib.deflateRawSync(buffer[, options])
zlib.gunzip(buffer[, options], callback)
zlib.gunzipSync(buffer[, options])
zlib.gzip(buffer[, options], callback)
zlib.gzipSync(buffer[, options])
zlib.inflate(buffer[, options], callback)
zlib.inflateSync(buffer[, options])
zlib.inflateRaw(buffer[, options], callback)
zlib.inflateRawSync(buffer[, options])
zlib.unzip(buffer[, options], callback)
zlib.unzipSync(buffer[, options])