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