-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathbuffer.d.ts
More file actions
executable file
·2312 lines (2310 loc) · 102 KB
/
buffer.d.ts
File metadata and controls
executable file
·2312 lines (2310 loc) · 102 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**
* `Buffer` objects are used to represent a fixed-length sequence of bytes. Many
* Node.js APIs support `Buffer`s.
*
* The `Buffer` class is a subclass of JavaScript's [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) class and
* extends it with methods that cover additional use cases. Node.js APIs accept
* plain [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) s wherever `Buffer`s are supported as well.
*
* While the `Buffer` class is available within the global scope, it is still
* recommended to explicitly reference it via an import or require statement.
*
* ```js
* import { Buffer } from 'buffer';
*
* // Creates a zero-filled Buffer of length 10.
* const buf1 = Buffer.alloc(10);
*
* // Creates a Buffer of length 10,
* // filled with bytes which all have the value `1`.
* const buf2 = Buffer.alloc(10, 1);
*
* // Creates an uninitialized buffer of length 10.
* // This is faster than calling Buffer.alloc() but the returned
* // Buffer instance might contain old data that needs to be
* // overwritten using fill(), write(), or other functions that fill the Buffer's
* // contents.
* const buf3 = Buffer.allocUnsafe(10);
*
* // Creates a Buffer containing the bytes [1, 2, 3].
* const buf4 = Buffer.from([1, 2, 3]);
*
* // Creates a Buffer containing the bytes [1, 1, 1, 1] – the entries
* // are all truncated using `(value & 255)` to fit into the range 0–255.
* const buf5 = Buffer.from([257, 257.5, -255, '1']);
*
* // Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
* // [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
* // [116, 195, 169, 115, 116] (in decimal notation)
* const buf6 = Buffer.from('tést');
*
* // Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74].
* const buf7 = Buffer.from('tést', 'latin1');
* ```
* @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/buffer.js)
*/
declare module 'buffer' {
import { BinaryLike } from 'node:crypto';
import { ReadableStream as WebReadableStream } from 'node:stream/web';
export function isUtf8(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean;
export function isAscii(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean;
export const INSPECT_MAX_BYTES: number;
export const kMaxLength: number;
export const kStringMaxLength: number;
export const constants: {
MAX_LENGTH: number;
MAX_STRING_LENGTH: number;
};
export type TranscodeEncoding = 'ascii' | 'utf8' | 'utf16le' | 'ucs2' | 'latin1' | 'binary';
/**
* Re-encodes the given `Buffer` or `Uint8Array` instance from one character
* encoding to another. Returns a new `Buffer` instance.
*
* Throws if the `fromEnc` or `toEnc` specify invalid character encodings or if
* conversion from `fromEnc` to `toEnc` is not permitted.
*
* Encodings supported by `buffer.transcode()` are: `'ascii'`, `'utf8'`,`'utf16le'`, `'ucs2'`, `'latin1'`, and `'binary'`.
*
* The transcoding process will use substitution characters if a given byte
* sequence cannot be adequately represented in the target encoding. For instance:
*
* ```js
* import { Buffer, transcode } from 'buffer';
*
* const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii');
* console.log(newBuf.toString('ascii'));
* // Prints: '?'
* ```
*
* Because the Euro (`€`) sign is not representable in US-ASCII, it is replaced
* with `?` in the transcoded `Buffer`.
* @since v7.1.0
* @param source A `Buffer` or `Uint8Array` instance.
* @param fromEnc The current encoding.
* @param toEnc To target encoding.
*/
export function transcode(source: Uint8Array, fromEnc: TranscodeEncoding, toEnc: TranscodeEncoding): Buffer;
export const SlowBuffer: {
/** @deprecated since v6.0.0, use `Buffer.allocUnsafeSlow()` */
new (size: number): Buffer;
prototype: Buffer;
};
/**
* Resolves a `'blob:nodedata:...'` an associated `Blob` object registered using
* a prior call to `URL.createObjectURL()`.
* @since v16.7.0
* @experimental
* @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`.
*/
export function resolveObjectURL(id: string): Blob | undefined;
export { Buffer };
/**
* @experimental
*/
export interface BlobOptions {
/**
* @default 'utf8'
*/
encoding?: BufferEncoding | undefined;
/**
* The Blob content-type. The intent is for `type` to convey
* the MIME media type of the data, however no validation of the type format
* is performed.
*/
type?: string | undefined;
}
/**
* A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) encapsulates immutable, raw data that can be safely shared across
* multiple worker threads.
* @since v15.7.0, v14.18.0
*/
export class Blob {
/**
* The total size of the `Blob` in bytes.
* @since v15.7.0, v14.18.0
*/
readonly size: number;
/**
* The content-type of the `Blob`.
* @since v15.7.0, v14.18.0
*/
readonly type: string;
/**
* Creates a new `Blob` object containing a concatenation of the given sources.
*
* {ArrayBuffer}, {TypedArray}, {DataView}, and {Buffer} sources are copied into
* the 'Blob' and can therefore be safely modified after the 'Blob' is created.
*
* String sources are also copied into the `Blob`.
*/
constructor(sources: Array<BinaryLike | Blob>, options?: BlobOptions);
/**
* Returns a promise that fulfills with an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) containing a copy of
* the `Blob` data.
* @since v15.7.0, v14.18.0
*/
arrayBuffer(): Promise<ArrayBuffer>;
/**
* Creates and returns a new `Blob` containing a subset of this `Blob` objects
* data. The original `Blob` is not altered.
* @since v15.7.0, v14.18.0
* @param start The starting index.
* @param end The ending index.
* @param type The content-type for the new `Blob`
*/
slice(start?: number, end?: number, type?: string): Blob;
/**
* Returns a promise that fulfills with the contents of the `Blob` decoded as a
* UTF-8 string.
* @since v15.7.0, v14.18.0
*/
text(): Promise<string>;
/**
* Returns a new (WHATWG) `ReadableStream` that allows the content of the `Blob` to be read.
* @since v16.7.0
*/
stream(): WebReadableStream;
}
export interface FileOptions {
/**
* One of either `'transparent'` or `'native'`. When set to `'native'`, line endings in string source parts will be
* converted to the platform native line-ending as specified by `require('node:os').EOL`.
*/
endings?: 'native' | 'transparent';
/** The File content-type. */
type?: string;
/** The last modified date of the file. `Default`: Date.now(). */
lastModified?: number;
}
/**
* A [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) provides information about files.
* @experimental
* @since v18.13.0
*/
export class File extends Blob {
constructor(sources: Array<BinaryLike | Blob>, fileName: string, options?: FileOptions);
/**
* The name of the `File`.
* @since v18.13.0
*/
readonly name: string;
/**
* The last modified date of the `File`.
* @since v18.13.0
*/
readonly lastModified: number;
}
export import atob = globalThis.atob;
export import btoa = globalThis.btoa;
import { Blob as NodeBlob } from 'buffer';
// This conditional type will be the existing global Blob in a browser, or
// the copy below in a Node environment.
type __Blob = typeof globalThis extends { onmessage: any; Blob: infer T } ? T : NodeBlob;
global {
// Buffer class
type BufferEncoding =
| 'ascii'
| 'utf8'
| 'utf-8'
| 'utf16le'
| 'ucs2'
| 'ucs-2'
| 'base64'
| 'base64url'
| 'latin1'
| 'binary'
| 'hex';
type WithImplicitCoercion<T> =
| T
| {
valueOf(): T;
};
/**
* Raw data is stored in instances of the Buffer class.
* A Buffer is similar to an array of integers but corresponds to a raw memory allocation outside the V8 heap. A Buffer cannot be resized.
* Valid string encodings: 'ascii'|'utf8'|'utf16le'|'ucs2'(alias of 'utf16le')|'base64'|'base64url'|'binary'(deprecated)|'hex'
*/
interface BufferConstructor {
/**
* Allocates a new buffer containing the given {str}.
*
* @param str String to store in buffer.
* @param encoding encoding to use, optional. Default is 'utf8'
* @deprecated since v10.0.0 - Use `Buffer.from(string[, encoding])` instead.
*/
new (str: string, encoding?: BufferEncoding): Buffer;
/**
* Allocates a new buffer of {size} octets.
*
* @param size count of octets to allocate.
* @deprecated since v10.0.0 - Use `Buffer.alloc()` instead (also see `Buffer.allocUnsafe()`).
*/
new (size: number): Buffer;
/**
* Allocates a new buffer containing the given {array} of octets.
*
* @param array The octets to store.
* @deprecated since v10.0.0 - Use `Buffer.from(array)` instead.
*/
new (array: Uint8Array): Buffer;
/**
* Produces a Buffer backed by the same allocated memory as
* the given {ArrayBuffer}/{SharedArrayBuffer}.
*
*
* @param arrayBuffer The ArrayBuffer with which to share memory.
* @deprecated since v10.0.0 - Use `Buffer.from(arrayBuffer[, byteOffset[, length]])` instead.
*/
new (arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer;
/**
* Allocates a new buffer containing the given {array} of octets.
*
* @param array The octets to store.
* @deprecated since v10.0.0 - Use `Buffer.from(array)` instead.
*/
new (array: ReadonlyArray<any>): Buffer;
/**
* Copies the passed {buffer} data onto a new {Buffer} instance.
*
* @param buffer The buffer to copy.
* @deprecated since v10.0.0 - Use `Buffer.from(buffer)` instead.
*/
new (buffer: Buffer): Buffer;
/**
* Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`.
* Array entries outside that range will be truncated to fit into it.
*
* ```js
* import { Buffer } from 'buffer';
*
* // Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'.
* const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
* ```
*
* A `TypeError` will be thrown if `array` is not an `Array` or another type
* appropriate for `Buffer.from()` variants.
*
* `Buffer.from(array)` and `Buffer.from(string)` may also use the internal`Buffer` pool like `Buffer.allocUnsafe()` does.
* @since v5.10.0
*/
from(
arrayBuffer: WithImplicitCoercion<ArrayBuffer | SharedArrayBuffer>,
byteOffset?: number,
length?: number,
): Buffer;
/**
* Creates a new Buffer using the passed {data}
* @param data data to create a new Buffer
*/
from(data: Uint8Array | ReadonlyArray<number>): Buffer;
from(data: WithImplicitCoercion<Uint8Array | ReadonlyArray<number> | string>): Buffer;
/**
* Creates a new Buffer containing the given JavaScript string {str}.
* If provided, the {encoding} parameter identifies the character encoding.
* If not provided, {encoding} defaults to 'utf8'.
*/
from(
str:
| WithImplicitCoercion<string>
| {
[Symbol.toPrimitive](hint: 'string'): string;
},
encoding?: BufferEncoding,
): Buffer;
/**
* Creates a new Buffer using the passed {data}
* @param values to create a new Buffer
*/
of(...items: number[]): Buffer;
/**
* Returns `true` if `obj` is a `Buffer`, `false` otherwise.
*
* ```js
* import { Buffer } from 'buffer';
*
* Buffer.isBuffer(Buffer.alloc(10)); // true
* Buffer.isBuffer(Buffer.from('foo')); // true
* Buffer.isBuffer('a string'); // false
* Buffer.isBuffer([]); // false
* Buffer.isBuffer(new Uint8Array(1024)); // false
* ```
* @since v0.1.101
*/
isBuffer(obj: any): obj is Buffer;
/**
* Returns `true` if `encoding` is the name of a supported character encoding,
* or `false` otherwise.
*
* ```js
* import { Buffer } from 'buffer';
*
* console.log(Buffer.isEncoding('utf8'));
* // Prints: true
*
* console.log(Buffer.isEncoding('hex'));
* // Prints: true
*
* console.log(Buffer.isEncoding('utf/8'));
* // Prints: false
*
* console.log(Buffer.isEncoding(''));
* // Prints: false
* ```
* @since v0.9.1
* @param encoding A character encoding name to check.
*/
isEncoding(encoding: string): encoding is BufferEncoding;
/**
* Returns the byte length of a string when encoded using `encoding`.
* This is not the same as [`String.prototype.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length), which does not account
* for the encoding that is used to convert the string into bytes.
*
* For `'base64'`, `'base64url'`, and `'hex'`, this function assumes valid input.
* For strings that contain non-base64/hex-encoded data (e.g. whitespace), the
* return value might be greater than the length of a `Buffer` created from the
* string.
*
* ```js
* import { Buffer } from 'buffer';
*
* const str = '\u00bd + \u00bc = \u00be';
*
* console.log(`${str}: ${str.length} characters, ` +
* `${Buffer.byteLength(str, 'utf8')} bytes`);
* // Prints: ½ + ¼ = ¾: 9 characters, 12 bytes
* ```
*
* When `string` is a
* `Buffer`/[`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)/[`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/-
* Reference/Global_Objects/TypedArray)/[`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)/[`SharedArrayBuffer`](https://develop-
* er.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer), the byte length as reported by `.byteLength`is returned.
* @since v0.1.90
* @param string A value to calculate the length of.
* @param [encoding='utf8'] If `string` is a string, this is its encoding.
* @return The number of bytes contained within `string`.
*/
byteLength(
string: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
encoding?: BufferEncoding,
): number;
/**
* Returns a new `Buffer` which is the result of concatenating all the `Buffer`instances in the `list` together.
*
* If the list has no items, or if the `totalLength` is 0, then a new zero-length`Buffer` is returned.
*
* If `totalLength` is not provided, it is calculated from the `Buffer` instances
* in `list` by adding their lengths.
*
* If `totalLength` is provided, it is coerced to an unsigned integer. If the
* combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is
* truncated to `totalLength`.
*
* ```js
* import { Buffer } from 'buffer';
*
* // Create a single `Buffer` from a list of three `Buffer` instances.
*
* const buf1 = Buffer.alloc(10);
* const buf2 = Buffer.alloc(14);
* const buf3 = Buffer.alloc(18);
* const totalLength = buf1.length + buf2.length + buf3.length;
*
* console.log(totalLength);
* // Prints: 42
*
* const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);
*
* console.log(bufA);
* // Prints: <Buffer 00 00 00 00 ...>
* console.log(bufA.length);
* // Prints: 42
* ```
*
* `Buffer.concat()` may also use the internal `Buffer` pool like `Buffer.allocUnsafe()` does.
* @since v0.7.11
* @param list List of `Buffer` or {@link Uint8Array} instances to concatenate.
* @param totalLength Total length of the `Buffer` instances in `list` when concatenated.
*/
concat(list: ReadonlyArray<Uint8Array>, totalLength?: number): Buffer;
/**
* Compares `buf1` to `buf2`, typically for the purpose of sorting arrays of`Buffer` instances. This is equivalent to calling `buf1.compare(buf2)`.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf1 = Buffer.from('1234');
* const buf2 = Buffer.from('0123');
* const arr = [buf1, buf2];
*
* console.log(arr.sort(Buffer.compare));
* // Prints: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
* // (This result is equal to: [buf2, buf1].)
* ```
* @since v0.11.13
* @return Either `-1`, `0`, or `1`, depending on the result of the comparison. See `compare` for details.
*/
compare(buf1: Uint8Array, buf2: Uint8Array): -1 | 0 | 1;
/**
* Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the`Buffer` will be zero-filled.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.alloc(5);
*
* console.log(buf);
* // Prints: <Buffer 00 00 00 00 00>
* ```
*
* If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown.
*
* If `fill` is specified, the allocated `Buffer` will be initialized by calling `buf.fill(fill)`.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.alloc(5, 'a');
*
* console.log(buf);
* // Prints: <Buffer 61 61 61 61 61>
* ```
*
* If both `fill` and `encoding` are specified, the allocated `Buffer` will be
* initialized by calling `buf.fill(fill, encoding)`.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
*
* console.log(buf);
* // Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
* ```
*
* Calling `Buffer.alloc()` can be measurably slower than the alternative `Buffer.allocUnsafe()` but ensures that the newly created `Buffer` instance
* contents will never contain sensitive data from previous allocations, including
* data that might not have been allocated for `Buffer`s.
*
* A `TypeError` will be thrown if `size` is not a number.
* @since v5.10.0
* @param size The desired length of the new `Buffer`.
* @param [fill=0] A value to pre-fill the new `Buffer` with.
* @param [encoding='utf8'] If `fill` is a string, this is its encoding.
*/
alloc(size: number, fill?: string | Buffer | number, encoding?: BufferEncoding): Buffer;
/**
* 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.
*
* The underlying memory for `Buffer` instances created in this way is _not_
* _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.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.allocUnsafe(10);
*
* console.log(buf);
* // Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
*
* buf.fill(0);
*
* console.log(buf);
* // Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>
* ```
*
* A `TypeError` will be thrown if `size` is not a number.
*
* The `Buffer` module pre-allocates an internal `Buffer` instance of
* 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
* deprecated`new Buffer(size)` constructor only when `size` is less than or equal
* to `Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two).
*
* Use of this pre-allocated internal memory pool is a key difference between
* calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`.
* 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
* than or equal to half `Buffer.poolSize`. The
* difference is subtle but can be important when an application requires the
* additional performance that `Buffer.allocUnsafe()` provides.
* @since v5.10.0
* @param size The desired length of the new `Buffer`.
*/
allocUnsafe(size: number): Buffer;
/**
* 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 `size` is 0.
*
* The underlying memory for `Buffer` instances created in this way is _not_
* _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `buf.fill(0)` to initialize
* such `Buffer` instances with zeroes.
*
* When using `Buffer.allocUnsafe()` to allocate new `Buffer` instances,
* allocations under 4 KB are sliced from a single pre-allocated `Buffer`. This
* allows applications to avoid the garbage collection overhead of creating many
* individually allocated `Buffer` instances. This approach improves both
* performance and memory usage by eliminating the need to track and clean up as
* many individual `ArrayBuffer` objects.
*
* However, in the case where a developer may need to retain a small chunk of
* memory from a pool for an indeterminate amount of time, it may be appropriate
* to create an un-pooled `Buffer` instance using `Buffer.allocUnsafeSlow()` and
* then copying out the relevant bits.
*
* ```js
* import { Buffer } from 'buffer';
*
* // Need to keep around a few small chunks of memory.
* const store = [];
*
* socket.on('readable', () => {
* let data;
* while (null !== (data = readable.read())) {
* // Allocate for retained data.
* const sb = Buffer.allocUnsafeSlow(10);
*
* // Copy the data into the new allocation.
* data.copy(sb, 0, 0, 10);
*
* store.push(sb);
* }
* });
* ```
*
* A `TypeError` will be thrown if `size` is not a number.
* @since v5.12.0
* @param size The desired length of the new `Buffer`.
*/
allocUnsafeSlow(size: number): Buffer;
/**
* This is the size (in bytes) of pre-allocated internal `Buffer` instances used
* for pooling. This value may be modified.
* @since v0.11.3
*/
poolSize: number;
}
interface Buffer extends Uint8Array {
/**
* Writes `string` to `buf` at `offset` according to the character encoding in`encoding`. The `length` parameter is the number of bytes to write. If `buf` did
* not contain enough space to fit the entire string, only part of `string` will be
* written. However, partially encoded characters will not be written.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.alloc(256);
*
* const len = buf.write('\u00bd + \u00bc = \u00be', 0);
*
* console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
* // Prints: 12 bytes: ½ + ¼ = ¾
*
* const buffer = Buffer.alloc(10);
*
* const length = buffer.write('abcd', 8);
*
* console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`);
* // Prints: 2 bytes : ab
* ```
* @since v0.1.90
* @param string String to write to `buf`.
* @param [offset=0] Number of bytes to skip before starting to write `string`.
* @param [length=buf.length - offset] Maximum number of bytes to write (written bytes will not exceed `buf.length - offset`).
* @param [encoding='utf8'] The character encoding of `string`.
* @return Number of bytes written.
*/
write(string: string, encoding?: BufferEncoding): number;
write(string: string, offset: number, encoding?: BufferEncoding): number;
write(string: string, offset: number, length: number, encoding?: BufferEncoding): number;
/**
* Decodes `buf` to a string according to the specified character encoding in`encoding`. `start` and `end` may be passed to decode only a subset of `buf`.
*
* If `encoding` is `'utf8'` and a byte sequence in the input is not valid UTF-8,
* then each invalid byte is replaced with the replacement character `U+FFFD`.
*
* The maximum length of a string instance (in UTF-16 code units) is available
* as {@link constants.MAX_STRING_LENGTH}.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf1 = Buffer.allocUnsafe(26);
*
* for (let i = 0; i < 26; i++) {
* // 97 is the decimal ASCII value for 'a'.
* buf1[i] = i + 97;
* }
*
* console.log(buf1.toString('utf8'));
* // Prints: abcdefghijklmnopqrstuvwxyz
* console.log(buf1.toString('utf8', 0, 5));
* // Prints: abcde
*
* const buf2 = Buffer.from('tést');
*
* console.log(buf2.toString('hex'));
* // Prints: 74c3a97374
* console.log(buf2.toString('utf8', 0, 3));
* // Prints: té
* console.log(buf2.toString(undefined, 0, 3));
* // Prints: té
* ```
* @since v0.1.90
* @param [encoding='utf8'] The character encoding to use.
* @param [start=0] The byte offset to start decoding at.
* @param [end=buf.length] The byte offset to stop decoding at (not inclusive).
*/
toString(encoding?: BufferEncoding, start?: number, end?: number): string;
/**
* Returns a JSON representation of `buf`. [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) implicitly calls
* this function when stringifying a `Buffer` instance.
*
* `Buffer.from()` accepts objects in the format returned from this method.
* In particular, `Buffer.from(buf.toJSON())` works like `Buffer.from(buf)`.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
* const json = JSON.stringify(buf);
*
* console.log(json);
* // Prints: {"type":"Buffer","data":[1,2,3,4,5]}
*
* const copy = JSON.parse(json, (key, value) => {
* return value && value.type === 'Buffer' ?
* Buffer.from(value) :
* value;
* });
*
* console.log(copy);
* // Prints: <Buffer 01 02 03 04 05>
* ```
* @since v0.9.2
*/
toJSON(): {
type: 'Buffer';
data: number[];
};
/**
* Returns `true` if both `buf` and `otherBuffer` have exactly the same bytes,`false` otherwise. Equivalent to `buf.compare(otherBuffer) === 0`.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf1 = Buffer.from('ABC');
* const buf2 = Buffer.from('414243', 'hex');
* const buf3 = Buffer.from('ABCD');
*
* console.log(buf1.equals(buf2));
* // Prints: true
* console.log(buf1.equals(buf3));
* // Prints: false
* ```
* @since v0.11.13
* @param otherBuffer A `Buffer` or {@link Uint8Array} with which to compare `buf`.
*/
equals(otherBuffer: Uint8Array): boolean;
/**
* Compares `buf` with `target` and returns a number indicating whether `buf`comes before, after, or is the same as `target` in sort order.
* Comparison is based on the actual sequence of bytes in each `Buffer`.
*
* * `0` is returned if `target` is the same as `buf`
* * `1` is returned if `target` should come _before_`buf` when sorted.
* * `-1` is returned if `target` should come _after_`buf` when sorted.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf1 = Buffer.from('ABC');
* const buf2 = Buffer.from('BCD');
* const buf3 = Buffer.from('ABCD');
*
* console.log(buf1.compare(buf1));
* // Prints: 0
* console.log(buf1.compare(buf2));
* // Prints: -1
* console.log(buf1.compare(buf3));
* // Prints: -1
* console.log(buf2.compare(buf1));
* // Prints: 1
* console.log(buf2.compare(buf3));
* // Prints: 1
* console.log([buf1, buf2, buf3].sort(Buffer.compare));
* // Prints: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
* // (This result is equal to: [buf1, buf3, buf2].)
* ```
*
* The optional `targetStart`, `targetEnd`, `sourceStart`, and `sourceEnd`arguments can be used to limit the comparison to specific ranges within `target`and `buf` respectively.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]);
* const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]);
*
* console.log(buf1.compare(buf2, 5, 9, 0, 4));
* // Prints: 0
* console.log(buf1.compare(buf2, 0, 6, 4));
* // Prints: -1
* console.log(buf1.compare(buf2, 5, 6, 5));
* // Prints: 1
* ```
*
* `ERR_OUT_OF_RANGE` is thrown if `targetStart < 0`, `sourceStart < 0`,`targetEnd > target.byteLength`, or `sourceEnd > source.byteLength`.
* @since v0.11.13
* @param target A `Buffer` or {@link Uint8Array} with which to compare `buf`.
* @param [targetStart=0] The offset within `target` at which to begin comparison.
* @param [targetEnd=target.length] The offset within `target` at which to end comparison (not inclusive).
* @param [sourceStart=0] The offset within `buf` at which to begin comparison.
* @param [sourceEnd=buf.length] The offset within `buf` at which to end comparison (not inclusive).
*/
compare(
target: Uint8Array,
targetStart?: number,
targetEnd?: number,
sourceStart?: number,
sourceEnd?: number,
): -1 | 0 | 1;
/**
* Copies data from a region of `buf` to a region in `target`, even if the `target`memory region overlaps with `buf`.
*
* [`TypedArray.prototype.set()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/set) performs the same operation, and is available
* for all TypedArrays, including Node.js `Buffer`s, although it takes
* different function arguments.
*
* ```js
* import { Buffer } from 'buffer';
*
* // Create two `Buffer` instances.
* const buf1 = Buffer.allocUnsafe(26);
* const buf2 = Buffer.allocUnsafe(26).fill('!');
*
* for (let i = 0; i < 26; i++) {
* // 97 is the decimal ASCII value for 'a'.
* buf1[i] = i + 97;
* }
*
* // Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`.
* buf1.copy(buf2, 8, 16, 20);
* // This is equivalent to:
* // buf2.set(buf1.subarray(16, 20), 8);
*
* console.log(buf2.toString('ascii', 0, 25));
* // Prints: !!!!!!!!qrst!!!!!!!!!!!!!
* ```
*
* ```js
* import { Buffer } from 'buffer';
*
* // Create a `Buffer` and copy data from one region to an overlapping region
* // within the same `Buffer`.
*
* const buf = Buffer.allocUnsafe(26);
*
* for (let i = 0; i < 26; i++) {
* // 97 is the decimal ASCII value for 'a'.
* buf[i] = i + 97;
* }
*
* buf.copy(buf, 0, 4, 10);
*
* console.log(buf.toString());
* // Prints: efghijghijklmnopqrstuvwxyz
* ```
* @since v0.1.90
* @param target A `Buffer` or {@link Uint8Array} to copy into.
* @param [targetStart=0] The offset within `target` at which to begin writing.
* @param [sourceStart=0] The offset within `buf` from which to begin copying.
* @param [sourceEnd=buf.length] The offset within `buf` at which to stop copying (not inclusive).
* @return The number of bytes copied.
*/
copy(target: Uint8Array, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;
/**
* Returns a new `Buffer` that references the same memory as the original, but
* offset and cropped by the `start` and `end` indices.
*
* This method is not compatible with the `Uint8Array.prototype.slice()`,
* which is a superclass of `Buffer`. To copy the slice, use`Uint8Array.prototype.slice()`.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.from('buffer');
*
* const copiedBuf = Uint8Array.prototype.slice.call(buf);
* copiedBuf[0]++;
* console.log(copiedBuf.toString());
* // Prints: cuffer
*
* console.log(buf.toString());
* // Prints: buffer
*
* // With buf.slice(), the original buffer is modified.
* const notReallyCopiedBuf = buf.slice();
* notReallyCopiedBuf[0]++;
* console.log(notReallyCopiedBuf.toString());
* // Prints: cuffer
* console.log(buf.toString());
* // Also prints: cuffer (!)
* ```
* @since v0.3.0
* @deprecated Use `subarray` instead.
* @param [start=0] Where the new `Buffer` will start.
* @param [end=buf.length] Where the new `Buffer` will end (not inclusive).
*/
slice(start?: number, end?: number): Buffer;
/**
* Returns a new `Buffer` that references the same memory as the original, but
* offset and cropped by the `start` and `end` indices.
*
* Specifying `end` greater than `buf.length` will return the same result as
* that of `end` equal to `buf.length`.
*
* This method is inherited from [`TypedArray.prototype.subarray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray).
*
* Modifying the new `Buffer` slice will modify the memory in the original `Buffer`because the allocated memory of the two objects overlap.
*
* ```js
* import { Buffer } from 'buffer';
*
* // Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
* // from the original `Buffer`.
*
* const buf1 = Buffer.allocUnsafe(26);
*
* for (let i = 0; i < 26; i++) {
* // 97 is the decimal ASCII value for 'a'.
* buf1[i] = i + 97;
* }
*
* const buf2 = buf1.subarray(0, 3);
*
* console.log(buf2.toString('ascii', 0, buf2.length));
* // Prints: abc
*
* buf1[0] = 33;
*
* console.log(buf2.toString('ascii', 0, buf2.length));
* // Prints: !bc
* ```
*
* Specifying negative indexes causes the slice to be generated relative to the
* end of `buf` rather than the beginning.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.from('buffer');
*
* console.log(buf.subarray(-6, -1).toString());
* // Prints: buffe
* // (Equivalent to buf.subarray(0, 5).)
*
* console.log(buf.subarray(-6, -2).toString());
* // Prints: buff
* // (Equivalent to buf.subarray(0, 4).)
*
* console.log(buf.subarray(-5, -2).toString());
* // Prints: uff
* // (Equivalent to buf.subarray(1, 4).)
* ```
* @since v3.0.0
* @param [start=0] Where the new `Buffer` will start.
* @param [end=buf.length] Where the new `Buffer` will end (not inclusive).
*/
subarray(start?: number, end?: number): Buffer;
/**
* Writes `value` to `buf` at the specified `offset` as big-endian.
*
* `value` is interpreted and written as a two's complement signed integer.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.allocUnsafe(8);
*
* buf.writeBigInt64BE(0x0102030405060708n, 0);
*
* console.log(buf);
* // Prints: <Buffer 01 02 03 04 05 06 07 08>
* ```
* @since v12.0.0, v10.20.0
* @param value Number to be written to `buf`.
* @param [offset=0] Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`.
* @return `offset` plus the number of bytes written.
*/
writeBigInt64BE(value: bigint, offset?: number): number;
/**
* Writes `value` to `buf` at the specified `offset` as little-endian.
*
* `value` is interpreted and written as a two's complement signed integer.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.allocUnsafe(8);
*
* buf.writeBigInt64LE(0x0102030405060708n, 0);
*
* console.log(buf);
* // Prints: <Buffer 08 07 06 05 04 03 02 01>
* ```
* @since v12.0.0, v10.20.0
* @param value Number to be written to `buf`.
* @param [offset=0] Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`.
* @return `offset` plus the number of bytes written.
*/
writeBigInt64LE(value: bigint, offset?: number): number;
/**
* Writes `value` to `buf` at the specified `offset` as big-endian.
*
* This function is also available under the `writeBigUint64BE` alias.
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.allocUnsafe(8);
*
* buf.writeBigUInt64BE(0xdecafafecacefaden, 0);
*
* console.log(buf);
* // Prints: <Buffer de ca fa fe ca ce fa de>
* ```
* @since v12.0.0, v10.20.0
* @param value Number to be written to `buf`.
* @param [offset=0] Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`.
* @return `offset` plus the number of bytes written.
*/
writeBigUInt64BE(value: bigint, offset?: number): number;
/**
* @alias Buffer.writeBigUInt64BE
* @since v14.10.0, v12.19.0
*/
writeBigUint64BE(value: bigint, offset?: number): number;
/**
* Writes `value` to `buf` at the specified `offset` as little-endian
*
* ```js
* import { Buffer } from 'buffer';
*
* const buf = Buffer.allocUnsafe(8);
*
* buf.writeBigUInt64LE(0xdecafafecacefaden, 0);
*
* console.log(buf);
* // Prints: <Buffer de fa ce ca fe fa ca de>
* ```
*
* This function is also available under the `writeBigUint64LE` alias.
* @since v12.0.0, v10.20.0
* @param value Number to be written to `buf`.