82e4b75e94975d41a23c3eda9bb796efbb4109c64b51e4528445b7e56c3ae7d20c42f07d4723c6152b1a8056abbf28ffb93e5322d616bcca5d8b86202d44dd 22 KB

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