8e012403eb5e13e6da1b56c17f74509a6ad0b1d09ed0c1a8177b3d7f84cb2bcfb9cd66f11b8522f406c41c4c769cd01db9a16f72361e14d30756adce046c0d 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460
  1. declare module "buffer" {
  2. global {
  3. interface BufferConstructor {
  4. // see ../buffer.d.ts for implementation shared with all TypeScript versions
  5. /**
  6. * Allocates a new buffer containing the given {str}.
  7. *
  8. * @param str String to store in buffer.
  9. * @param encoding encoding to use, optional. Default is 'utf8'
  10. * @deprecated since v10.0.0 - Use `Buffer.from(string[, encoding])` instead.
  11. */
  12. new(str: string, encoding?: BufferEncoding): Buffer;
  13. /**
  14. * Allocates a new buffer of {size} octets.
  15. *
  16. * @param size count of octets to allocate.
  17. * @deprecated since v10.0.0 - Use `Buffer.alloc()` instead (also see `Buffer.allocUnsafe()`).
  18. */
  19. new(size: number): Buffer;
  20. /**
  21. * Allocates a new buffer containing the given {array} of octets.
  22. *
  23. * @param array The octets to store.
  24. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead.
  25. */
  26. new(array: ArrayLike<number>): Buffer;
  27. /**
  28. * Produces a Buffer backed by the same allocated memory as
  29. * the given {ArrayBuffer}/{SharedArrayBuffer}.
  30. *
  31. * @param arrayBuffer The ArrayBuffer with which to share memory.
  32. * @deprecated since v10.0.0 - Use `Buffer.from(arrayBuffer[, byteOffset[, length]])` instead.
  33. */
  34. new(arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer;
  35. /**
  36. * Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`.
  37. * Array entries outside that range will be truncated to fit into it.
  38. *
  39. * ```js
  40. * import { Buffer } from 'node:buffer';
  41. *
  42. * // Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'.
  43. * const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
  44. * ```
  45. *
  46. * If `array` is an `Array`-like object (that is, one with a `length` property of
  47. * type `number`), it is treated as if it is an array, unless it is a `Buffer` or
  48. * a `Uint8Array`. This means all other `TypedArray` variants get treated as an
  49. * `Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use
  50. * `Buffer.copyBytesFrom()`.
  51. *
  52. * A `TypeError` will be thrown if `array` is not an `Array` or another type
  53. * appropriate for `Buffer.from()` variants.
  54. *
  55. * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal
  56. * `Buffer` pool like `Buffer.allocUnsafe()` does.
  57. * @since v5.10.0
  58. */
  59. from(array: WithImplicitCoercion<ArrayLike<number>>): Buffer;
  60. /**
  61. * This creates a view of the `ArrayBuffer` without copying the underlying
  62. * memory. For example, when passed a reference to the `.buffer` property of a
  63. * `TypedArray` instance, the newly created `Buffer` will share the same
  64. * allocated memory as the `TypedArray`'s underlying `ArrayBuffer`.
  65. *
  66. * ```js
  67. * import { Buffer } from 'node:buffer';
  68. *
  69. * const arr = new Uint16Array(2);
  70. *
  71. * arr[0] = 5000;
  72. * arr[1] = 4000;
  73. *
  74. * // Shares memory with `arr`.
  75. * const buf = Buffer.from(arr.buffer);
  76. *
  77. * console.log(buf);
  78. * // Prints: <Buffer 88 13 a0 0f>
  79. *
  80. * // Changing the original Uint16Array changes the Buffer also.
  81. * arr[1] = 6000;
  82. *
  83. * console.log(buf);
  84. * // Prints: <Buffer 88 13 70 17>
  85. * ```
  86. *
  87. * The optional `byteOffset` and `length` arguments specify a memory range within
  88. * the `arrayBuffer` that will be shared by the `Buffer`.
  89. *
  90. * ```js
  91. * import { Buffer } from 'node:buffer';
  92. *
  93. * const ab = new ArrayBuffer(10);
  94. * const buf = Buffer.from(ab, 0, 2);
  95. *
  96. * console.log(buf.length);
  97. * // Prints: 2
  98. * ```
  99. *
  100. * A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer` or a
  101. * `SharedArrayBuffer` or another type appropriate for `Buffer.from()`
  102. * variants.
  103. *
  104. * It is important to remember that a backing `ArrayBuffer` can cover a range
  105. * of memory that extends beyond the bounds of a `TypedArray` view. A new
  106. * `Buffer` created using the `buffer` property of a `TypedArray` may extend
  107. * beyond the range of the `TypedArray`:
  108. *
  109. * ```js
  110. * import { Buffer } from 'node:buffer';
  111. *
  112. * const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements
  113. * const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements
  114. * console.log(arrA.buffer === arrB.buffer); // true
  115. *
  116. * const buf = Buffer.from(arrB.buffer);
  117. * console.log(buf);
  118. * // Prints: <Buffer 63 64 65 66>
  119. * ```
  120. * @since v5.10.0
  121. * @param arrayBuffer An `ArrayBuffer`, `SharedArrayBuffer`, for example the
  122. * `.buffer` property of a `TypedArray`.
  123. * @param byteOffset Index of first byte to expose. **Default:** `0`.
  124. * @param length Number of bytes to expose. **Default:**
  125. * `arrayBuffer.byteLength - byteOffset`.
  126. */
  127. from(
  128. arrayBuffer: WithImplicitCoercion<ArrayBuffer | SharedArrayBuffer>,
  129. byteOffset?: number,
  130. length?: number,
  131. ): Buffer;
  132. /**
  133. * Creates a new `Buffer` containing `string`. The `encoding` parameter identifies
  134. * the character encoding to be used when converting `string` into bytes.
  135. *
  136. * ```js
  137. * import { Buffer } from 'node:buffer';
  138. *
  139. * const buf1 = Buffer.from('this is a tést');
  140. * const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
  141. *
  142. * console.log(buf1.toString());
  143. * // Prints: this is a tést
  144. * console.log(buf2.toString());
  145. * // Prints: this is a tést
  146. * console.log(buf1.toString('latin1'));
  147. * // Prints: this is a tést
  148. * ```
  149. *
  150. * A `TypeError` will be thrown if `string` is not a string or another type
  151. * appropriate for `Buffer.from()` variants.
  152. *
  153. * `Buffer.from(string)` may also use the internal `Buffer` pool like
  154. * `Buffer.allocUnsafe()` does.
  155. * @since v5.10.0
  156. * @param string A string to encode.
  157. * @param encoding The encoding of `string`. **Default:** `'utf8'`.
  158. */
  159. from(string: WithImplicitCoercion<string>, encoding?: BufferEncoding): Buffer;
  160. from(arrayOrString: WithImplicitCoercion<ArrayLike<number> | string>): Buffer;
  161. /**
  162. * Creates a new Buffer using the passed {data}
  163. * @param values to create a new Buffer
  164. */
  165. of(...items: number[]): Buffer;
  166. /**
  167. * Returns a new `Buffer` which is the result of concatenating all the `Buffer` instances in the `list` together.
  168. *
  169. * If the list has no items, or if the `totalLength` is 0, then a new zero-length `Buffer` is returned.
  170. *
  171. * If `totalLength` is not provided, it is calculated from the `Buffer` instances
  172. * in `list` by adding their lengths.
  173. *
  174. * If `totalLength` is provided, it is coerced to an unsigned integer. If the
  175. * combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is
  176. * truncated to `totalLength`.
  177. *
  178. * ```js
  179. * import { Buffer } from 'node:buffer';
  180. *
  181. * // Create a single `Buffer` from a list of three `Buffer` instances.
  182. *
  183. * const buf1 = Buffer.alloc(10);
  184. * const buf2 = Buffer.alloc(14);
  185. * const buf3 = Buffer.alloc(18);
  186. * const totalLength = buf1.length + buf2.length + buf3.length;
  187. *
  188. * console.log(totalLength);
  189. * // Prints: 42
  190. *
  191. * const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);
  192. *
  193. * console.log(bufA);
  194. * // Prints: <Buffer 00 00 00 00 ...>
  195. * console.log(bufA.length);
  196. * // Prints: 42
  197. * ```
  198. *
  199. * `Buffer.concat()` may also use the internal `Buffer` pool like `Buffer.allocUnsafe()` does.
  200. * @since v0.7.11
  201. * @param list List of `Buffer` or {@link Uint8Array} instances to concatenate.
  202. * @param totalLength Total length of the `Buffer` instances in `list` when concatenated.
  203. */
  204. concat(list: readonly Uint8Array[], totalLength?: number): Buffer;
  205. /**
  206. * Copies the underlying memory of `view` into a new `Buffer`.
  207. *
  208. * ```js
  209. * const u16 = new Uint16Array([0, 0xffff]);
  210. * const buf = Buffer.copyBytesFrom(u16, 1, 1);
  211. * u16[1] = 0;
  212. * console.log(buf.length); // 2
  213. * console.log(buf[0]); // 255
  214. * console.log(buf[1]); // 255
  215. * ```
  216. * @since v19.8.0
  217. * @param view The {TypedArray} to copy.
  218. * @param [offset=0] The starting offset within `view`.
  219. * @param [length=view.length - offset] The number of elements from `view` to copy.
  220. */
  221. copyBytesFrom(view: NodeJS.TypedArray, offset?: number, length?: number): Buffer;
  222. /**
  223. * Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the`Buffer` will be zero-filled.
  224. *
  225. * ```js
  226. * import { Buffer } from 'node:buffer';
  227. *
  228. * const buf = Buffer.alloc(5);
  229. *
  230. * console.log(buf);
  231. * // Prints: <Buffer 00 00 00 00 00>
  232. * ```
  233. *
  234. * If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown.
  235. *
  236. * If `fill` is specified, the allocated `Buffer` will be initialized by calling `buf.fill(fill)`.
  237. *
  238. * ```js
  239. * import { Buffer } from 'node:buffer';
  240. *
  241. * const buf = Buffer.alloc(5, 'a');
  242. *
  243. * console.log(buf);
  244. * // Prints: <Buffer 61 61 61 61 61>
  245. * ```
  246. *
  247. * If both `fill` and `encoding` are specified, the allocated `Buffer` will be
  248. * initialized by calling `buf.fill(fill, encoding)`.
  249. *
  250. * ```js
  251. * import { Buffer } from 'node:buffer';
  252. *
  253. * const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
  254. *
  255. * console.log(buf);
  256. * // Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
  257. * ```
  258. *
  259. * Calling `Buffer.alloc()` can be measurably slower than the alternative `Buffer.allocUnsafe()` but ensures that the newly created `Buffer` instance
  260. * contents will never contain sensitive data from previous allocations, including
  261. * data that might not have been allocated for `Buffer`s.
  262. *
  263. * A `TypeError` will be thrown if `size` is not a number.
  264. * @since v5.10.0
  265. * @param size The desired length of the new `Buffer`.
  266. * @param [fill=0] A value to pre-fill the new `Buffer` with.
  267. * @param [encoding='utf8'] If `fill` is a string, this is its encoding.
  268. */
  269. alloc(size: number, fill?: string | Uint8Array | number, encoding?: BufferEncoding): Buffer;
  270. /**
  271. * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown.
  272. *
  273. * The underlying memory for `Buffer` instances created in this way is _not_
  274. * _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `Buffer.alloc()` instead to initialize`Buffer` instances with zeroes.
  275. *
  276. * ```js
  277. * import { Buffer } from 'node:buffer';
  278. *
  279. * const buf = Buffer.allocUnsafe(10);
  280. *
  281. * console.log(buf);
  282. * // Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
  283. *
  284. * buf.fill(0);
  285. *
  286. * console.log(buf);
  287. * // Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>
  288. * ```
  289. *
  290. * A `TypeError` will be thrown if `size` is not a number.
  291. *
  292. * The `Buffer` module pre-allocates an internal `Buffer` instance of
  293. * size `Buffer.poolSize` that is used as a pool for the fast allocation of new `Buffer` instances created using `Buffer.allocUnsafe()`, `Buffer.from(array)`,
  294. * and `Buffer.concat()` only when `size` is less than `Buffer.poolSize >>> 1` (floor of `Buffer.poolSize` divided by two).
  295. *
  296. * Use of this pre-allocated internal memory pool is a key difference between
  297. * calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`.
  298. * Specifically, `Buffer.alloc(size, fill)` will _never_ use the internal `Buffer`pool, while `Buffer.allocUnsafe(size).fill(fill)`_will_ use the internal`Buffer` pool if `size` is less
  299. * than or equal to half `Buffer.poolSize`. The
  300. * difference is subtle but can be important when an application requires the
  301. * additional performance that `Buffer.allocUnsafe()` provides.
  302. * @since v5.10.0
  303. * @param size The desired length of the new `Buffer`.
  304. */
  305. allocUnsafe(size: number): Buffer;
  306. /**
  307. * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. A zero-length `Buffer` is created if
  308. * `size` is 0.
  309. *
  310. * The underlying memory for `Buffer` instances created in this way is _not_
  311. * _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `buf.fill(0)` to initialize
  312. * such `Buffer` instances with zeroes.
  313. *
  314. * When using `Buffer.allocUnsafe()` to allocate new `Buffer` instances,
  315. * allocations under 4 KiB are sliced from a single pre-allocated `Buffer`. This
  316. * allows applications to avoid the garbage collection overhead of creating many
  317. * individually allocated `Buffer` instances. This approach improves both
  318. * performance and memory usage by eliminating the need to track and clean up as
  319. * many individual `ArrayBuffer` objects.
  320. *
  321. * However, in the case where a developer may need to retain a small chunk of
  322. * memory from a pool for an indeterminate amount of time, it may be appropriate
  323. * to create an un-pooled `Buffer` instance using `Buffer.allocUnsafeSlow()` and
  324. * then copying out the relevant bits.
  325. *
  326. * ```js
  327. * import { Buffer } from 'node:buffer';
  328. *
  329. * // Need to keep around a few small chunks of memory.
  330. * const store = [];
  331. *
  332. * socket.on('readable', () => {
  333. * let data;
  334. * while (null !== (data = readable.read())) {
  335. * // Allocate for retained data.
  336. * const sb = Buffer.allocUnsafeSlow(10);
  337. *
  338. * // Copy the data into the new allocation.
  339. * data.copy(sb, 0, 0, 10);
  340. *
  341. * store.push(sb);
  342. * }
  343. * });
  344. * ```
  345. *
  346. * A `TypeError` will be thrown if `size` is not a number.
  347. * @since v5.12.0
  348. * @param size The desired length of the new `Buffer`.
  349. */
  350. allocUnsafeSlow(size: number): Buffer;
  351. }
  352. interface Buffer extends Uint8Array {
  353. // see ../buffer.d.ts for implementation shared with all TypeScript versions
  354. /**
  355. * Returns a new `Buffer` that references the same memory as the original, but
  356. * offset and cropped by the `start` and `end` indices.
  357. *
  358. * This method is not compatible with the `Uint8Array.prototype.slice()`,
  359. * which is a superclass of `Buffer`. To copy the slice, use`Uint8Array.prototype.slice()`.
  360. *
  361. * ```js
  362. * import { Buffer } from 'node:buffer';
  363. *
  364. * const buf = Buffer.from('buffer');
  365. *
  366. * const copiedBuf = Uint8Array.prototype.slice.call(buf);
  367. * copiedBuf[0]++;
  368. * console.log(copiedBuf.toString());
  369. * // Prints: cuffer
  370. *
  371. * console.log(buf.toString());
  372. * // Prints: buffer
  373. *
  374. * // With buf.slice(), the original buffer is modified.
  375. * const notReallyCopiedBuf = buf.slice();
  376. * notReallyCopiedBuf[0]++;
  377. * console.log(notReallyCopiedBuf.toString());
  378. * // Prints: cuffer
  379. * console.log(buf.toString());
  380. * // Also prints: cuffer (!)
  381. * ```
  382. * @since v0.3.0
  383. * @deprecated Use `subarray` instead.
  384. * @param [start=0] Where the new `Buffer` will start.
  385. * @param [end=buf.length] Where the new `Buffer` will end (not inclusive).
  386. */
  387. slice(start?: number, end?: number): Buffer;
  388. /**
  389. * Returns a new `Buffer` that references the same memory as the original, but
  390. * offset and cropped by the `start` and `end` indices.
  391. *
  392. * Specifying `end` greater than `buf.length` will return the same result as
  393. * that of `end` equal to `buf.length`.
  394. *
  395. * This method is inherited from [`TypedArray.prototype.subarray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray).
  396. *
  397. * Modifying the new `Buffer` slice will modify the memory in the original `Buffer`because the allocated memory of the two objects overlap.
  398. *
  399. * ```js
  400. * import { Buffer } from 'node:buffer';
  401. *
  402. * // Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
  403. * // from the original `Buffer`.
  404. *
  405. * const buf1 = Buffer.allocUnsafe(26);
  406. *
  407. * for (let i = 0; i < 26; i++) {
  408. * // 97 is the decimal ASCII value for 'a'.
  409. * buf1[i] = i + 97;
  410. * }
  411. *
  412. * const buf2 = buf1.subarray(0, 3);
  413. *
  414. * console.log(buf2.toString('ascii', 0, buf2.length));
  415. * // Prints: abc
  416. *
  417. * buf1[0] = 33;
  418. *
  419. * console.log(buf2.toString('ascii', 0, buf2.length));
  420. * // Prints: !bc
  421. * ```
  422. *
  423. * Specifying negative indexes causes the slice to be generated relative to the
  424. * end of `buf` rather than the beginning.
  425. *
  426. * ```js
  427. * import { Buffer } from 'node:buffer';
  428. *
  429. * const buf = Buffer.from('buffer');
  430. *
  431. * console.log(buf.subarray(-6, -1).toString());
  432. * // Prints: buffe
  433. * // (Equivalent to buf.subarray(0, 5).)
  434. *
  435. * console.log(buf.subarray(-6, -2).toString());
  436. * // Prints: buff
  437. * // (Equivalent to buf.subarray(0, 4).)
  438. *
  439. * console.log(buf.subarray(-5, -2).toString());
  440. * // Prints: uff
  441. * // (Equivalent to buf.subarray(1, 4).)
  442. * ```
  443. * @since v3.0.0
  444. * @param [start=0] Where the new `Buffer` will start.
  445. * @param [end=buf.length] Where the new `Buffer` will end (not inclusive).
  446. */
  447. subarray(start?: number, end?: number): Buffer;
  448. }
  449. type NonSharedBuffer = Buffer;
  450. type AllowSharedBuffer = Buffer;
  451. }
  452. /** @deprecated Use `Buffer.allocUnsafeSlow()` instead. */
  453. var SlowBuffer: {
  454. /** @deprecated Use `Buffer.allocUnsafeSlow()` instead. */
  455. new(size: number): Buffer;
  456. prototype: Buffer;
  457. };
  458. }