bson 5.1.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +3 -126
  2. package/bson.d.ts +79 -22
  3. package/lib/binary.d.ts +182 -0
  4. package/lib/binary.d.ts.map +1 -0
  5. package/lib/bson.bundle.js +87 -89
  6. package/lib/bson.bundle.js.map +1 -1
  7. package/lib/bson.cjs +87 -89
  8. package/lib/bson.cjs.map +1 -1
  9. package/lib/bson.d.ts +97 -0
  10. package/lib/bson.d.ts.map +1 -0
  11. package/lib/bson.mjs +87 -89
  12. package/lib/bson.mjs.map +1 -1
  13. package/lib/bson_value.d.ts +10 -0
  14. package/lib/bson_value.d.ts.map +1 -0
  15. package/lib/code.d.ts +32 -0
  16. package/lib/code.d.ts.map +1 -0
  17. package/lib/constants.d.ts +107 -0
  18. package/lib/constants.d.ts.map +1 -0
  19. package/lib/db_ref.d.ts +40 -0
  20. package/lib/db_ref.d.ts.map +1 -0
  21. package/lib/decimal128.d.ts +34 -0
  22. package/lib/decimal128.d.ts.map +1 -0
  23. package/lib/double.d.ts +35 -0
  24. package/lib/double.d.ts.map +1 -0
  25. package/lib/error.d.ts +50 -0
  26. package/lib/error.d.ts.map +1 -0
  27. package/lib/extended_json.d.ts +82 -0
  28. package/lib/extended_json.d.ts.map +1 -0
  29. package/lib/index.d.ts +4 -0
  30. package/lib/index.d.ts.map +1 -0
  31. package/lib/int_32.d.ts +35 -0
  32. package/lib/int_32.d.ts.map +1 -0
  33. package/lib/long.d.ts +323 -0
  34. package/lib/long.d.ts.map +1 -0
  35. package/lib/max_key.d.ts +19 -0
  36. package/lib/max_key.d.ts.map +1 -0
  37. package/lib/min_key.d.ts +19 -0
  38. package/lib/min_key.d.ts.map +1 -0
  39. package/lib/objectid.d.ts +96 -0
  40. package/lib/objectid.d.ts.map +1 -0
  41. package/lib/regexp.d.ts +36 -0
  42. package/lib/regexp.d.ts.map +1 -0
  43. package/lib/symbol.d.ts +28 -0
  44. package/lib/symbol.d.ts.map +1 -0
  45. package/lib/timestamp.d.ts +66 -0
  46. package/lib/timestamp.d.ts.map +1 -0
  47. package/lib/validate_utf8.d.ts +10 -0
  48. package/lib/validate_utf8.d.ts.map +1 -0
  49. package/package.json +20 -20
  50. package/src/binary.ts +67 -43
  51. package/src/bson.ts +1 -1
  52. package/src/constants.ts +1 -1
  53. package/src/extended_json.ts +11 -3
  54. package/src/objectid.ts +11 -5
  55. package/src/parser/deserializer.ts +37 -12
  56. package/src/parser/serializer.ts +17 -4
  57. package/src/timestamp.ts +1 -1
  58. package/src/uuid_utils.ts +0 -33
package/README.md CHANGED
@@ -69,35 +69,9 @@ npm install bson
69
69
 
70
70
  ## Documentation
71
71
 
72
- ### Objects
73
-
74
- <dl>
75
- <dt><a href="#EJSON">EJSON</a> : <code>object</code></dt>
76
- <dd></dd>
77
- </dl>
78
-
79
- ### Functions
80
-
81
- <dl>
82
- <dt><a href="#setInternalBufferSize">setInternalBufferSize(size)</a></dt>
83
- <dd><p>Sets the size of the internal serialization buffer.</p>
84
- </dd>
85
- <dt><a href="#serialize">serialize(object)</a> ⇒ <code>Buffer</code></dt>
86
- <dd><p>Serialize a Javascript object.</p>
87
- </dd>
88
- <dt><a href="#serializeWithBufferAndIndex">serializeWithBufferAndIndex(object, buffer)</a> ⇒ <code>Number</code></dt>
89
- <dd><p>Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.</p>
90
- </dd>
91
- <dt><a href="#deserialize">deserialize(buffer)</a> ⇒ <code>Object</code></dt>
92
- <dd><p>Deserialize data as BSON.</p>
93
- </dd>
94
- <dt><a href="#calculateObjectSize">calculateObjectSize(object)</a> ⇒ <code>Number</code></dt>
95
- <dd><p>Calculate the bson size for a passed in Javascript object.</p>
96
- </dd>
97
- <dt><a href="#deserializeStream">deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])</a> ⇒ <code>Number</code></dt>
98
- <dd><p>Deserialize stream data as BSON documents.</p>
99
- </dd>
100
- </dl>
72
+ ### BSON
73
+
74
+ [API documentation](https://mongodb.github.io/node-mongodb-native/Next/modules/BSON.html)
101
75
 
102
76
  <a name="EJSON"></a>
103
77
 
@@ -189,103 +163,6 @@ Serializes an object to an Extended JSON string, and reparse it as a JavaScript
189
163
 
190
164
  Deserializes an Extended JSON object into a plain JavaScript object with native/BSON types
191
165
 
192
- <a name="setInternalBufferSize"></a>
193
-
194
- ### setInternalBufferSize(size)
195
-
196
- | Param | Type | Description |
197
- | --- | --- | --- |
198
- | size | <code>number</code> | The desired size for the internal serialization buffer |
199
-
200
- Sets the size of the internal serialization buffer.
201
-
202
- <a name="serialize"></a>
203
-
204
- ### serialize(object)
205
-
206
- | Param | Type | Default | Description |
207
- | --- | --- | --- | --- |
208
- | object | <code>Object</code> | | the Javascript object to serialize. |
209
- | [options.checkKeys] | <code>Boolean</code> | | the serializer will check if keys are valid. |
210
- | [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
211
- | [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
212
-
213
- Serialize a Javascript object.
214
-
215
- **Returns**: <code>Buffer</code> - returns the Buffer object containing the serialized object.
216
- <a name="serializeWithBufferAndIndex"></a>
217
-
218
- ### serializeWithBufferAndIndex(object, buffer)
219
-
220
- | Param | Type | Default | Description |
221
- | --- | --- | --- | --- |
222
- | object | <code>Object</code> | | the Javascript object to serialize. |
223
- | buffer | <code>Buffer</code> | | the Buffer you pre-allocated to store the serialized BSON object. |
224
- | [options.checkKeys] | <code>Boolean</code> | | the serializer will check if keys are valid. |
225
- | [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
226
- | [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
227
- | [options.index] | <code>Number</code> | | the index in the buffer where we wish to start serializing into. |
228
-
229
- Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.
230
-
231
- **Returns**: <code>Number</code> - returns the index pointing to the last written byte in the buffer.
232
- <a name="deserialize"></a>
233
-
234
- ### deserialize(buffer)
235
-
236
- | Param | Type | Default | Description |
237
- | --- | --- | --- | --- |
238
- | buffer | <code>Buffer</code> | | the buffer containing the serialized set of BSON documents. |
239
- | [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
240
- | [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
241
- | [options.useBigInt64] | <code>Object</code> | <code>false</code> | when deserializing a Long will return a BigInt. |
242
- | [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
243
- | [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
244
- | [options.promoteValues] | <code>Object</code> | <code>false</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
245
- | [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
246
- | [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
247
- | [options.allowObjectSmallerThanBufferSize] | <code>boolean</code> | <code>false</code> | allows the buffer to be larger than the parsed BSON object. |
248
-
249
- Deserialize data as BSON.
250
-
251
- **Returns**: <code>Object</code> - returns the deserialized Javascript Object.
252
- <a name="calculateObjectSize"></a>
253
-
254
- ### calculateObjectSize(object)
255
-
256
- | Param | Type | Default | Description |
257
- | --- | --- | --- | --- |
258
- | object | <code>Object</code> | | the Javascript object to calculate the BSON byte size for. |
259
- | [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
260
- | [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
261
-
262
- Calculate the bson size for a passed in Javascript object.
263
-
264
- **Returns**: <code>Number</code> - returns the number of bytes the BSON object will take up.
265
- <a name="deserializeStream"></a>
266
-
267
- ### deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])
268
-
269
- | Param | Type | Default | Description |
270
- | --- | --- | --- | --- |
271
- | data | <code>Buffer</code> | | the buffer containing the serialized set of BSON documents. |
272
- | startIndex | <code>Number</code> | | the start index in the data Buffer where the deserialization is to start. |
273
- | numberOfDocuments | <code>Number</code> | | number of documents to deserialize. |
274
- | documents | <code>Array</code> | | an array where to store the deserialized documents. |
275
- | docStartIndex | <code>Number</code> | | the index in the documents array from where to start inserting documents. |
276
- | [options] | <code>Object</code> | | additional options used for the deserialization. |
277
- | [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
278
- | [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
279
- | [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
280
- | [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
281
- | [options.promoteValues] | <code>Object</code> | <code>false</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
282
- | [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
283
- | [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
284
-
285
- Deserialize stream data as BSON documents.
286
-
287
- **Returns**: <code>Number</code> - returns the next index in the buffer after deserialization **x** numbers of documents.
288
-
289
166
  ## Error Handling
290
167
 
291
168
  It is our recommendation to use `BSONError.isBSONError()` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code. We guarantee `BSONError.isBSONError()` checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.
package/bson.d.ts CHANGED
@@ -74,6 +74,10 @@ export declare class Binary extends BSONValue {
74
74
  toString(encoding?: 'hex' | 'base64' | 'utf8' | 'utf-8'): string;
75
75
  /* Excluded from this release type: toExtendedJSON */
76
76
  toUUID(): UUID;
77
+ /** Creates an Binary instance from a hex digit string */
78
+ static createFromHexString(hex: string, subType?: number): Binary;
79
+ /** Creates an Binary instance from a base64 string */
80
+ static createFromBase64(base64: string, subType?: number): Binary;
77
81
  /* Excluded from this release type: fromExtendedJSON */
78
82
  inspect(): string;
79
83
  }
@@ -276,7 +280,7 @@ export declare const BSONType: Readonly<{
276
280
  }>;
277
281
 
278
282
  /** @public */
279
- export declare type BSONType = typeof BSONType[keyof typeof BSONType];
283
+ export declare type BSONType = (typeof BSONType)[keyof typeof BSONType];
280
284
 
281
285
  /** @public */
282
286
  export declare abstract class BSONValue {
@@ -412,21 +416,45 @@ export declare function deserialize(buffer: Uint8Array, options?: DeserializeOpt
412
416
 
413
417
  /** @public */
414
418
  export declare interface DeserializeOptions {
415
- /** when deserializing a Long will return as a BigInt. */
419
+ /**
420
+ * when deserializing a Long return as a BigInt.
421
+ * @defaultValue `false`
422
+ */
416
423
  useBigInt64?: boolean;
417
- /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
424
+ /**
425
+ * when deserializing a Long will fit it into a Number if it's smaller than 53 bits.
426
+ * @defaultValue `true`
427
+ */
418
428
  promoteLongs?: boolean;
419
- /** when deserializing a Binary will return it as a node.js Buffer instance. */
429
+ /**
430
+ * when deserializing a Binary will return it as a node.js Buffer instance.
431
+ * @defaultValue `false`
432
+ */
420
433
  promoteBuffers?: boolean;
421
- /** when deserializing will promote BSON values to their Node.js closest equivalent types. */
434
+ /**
435
+ * when deserializing will promote BSON values to their Node.js closest equivalent types.
436
+ * @defaultValue `true`
437
+ */
422
438
  promoteValues?: boolean;
423
- /** allow to specify if there what fields we wish to return as unserialized raw buffer. */
439
+ /**
440
+ * allow to specify if there what fields we wish to return as unserialized raw buffer.
441
+ * @defaultValue `null`
442
+ */
424
443
  fieldsAsRaw?: Document;
425
- /** return BSON regular expressions as BSONRegExp instances. */
444
+ /**
445
+ * return BSON regular expressions as BSONRegExp instances.
446
+ * @defaultValue `false`
447
+ */
426
448
  bsonRegExp?: boolean;
427
- /** allows the buffer to be larger than the parsed BSON object. */
449
+ /**
450
+ * allows the buffer to be larger than the parsed BSON object.
451
+ * @defaultValue `false`
452
+ */
428
453
  allowObjectSmallerThanBufferSize?: boolean;
429
- /** Offset into buffer to begin reading document from */
454
+ /**
455
+ * Offset into buffer to begin reading document from
456
+ * @defaultValue `0`
457
+ */
430
458
  index?: number;
431
459
  raw?: boolean;
432
460
  /** Allows for opt-out utf-8 validation for all keys or
@@ -518,11 +546,19 @@ declare function EJSONdeserialize(ejson: Document, options?: EJSONOptions): any;
518
546
 
519
547
  /** @public */
520
548
  export declare type EJSONOptions = {
521
- /** Output using the Extended JSON v1 spec */
549
+ /**
550
+ * Output using the Extended JSON v1 spec
551
+ * @defaultValue `false`
552
+ */
522
553
  legacy?: boolean;
523
- /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
554
+ /**
555
+ * Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types
556
+ * @defaultValue `false` */
524
557
  relaxed?: boolean;
525
- /** Enable native bigint support */
558
+ /**
559
+ * Enable native bigint support
560
+ * @defaultValue `false`
561
+ */
526
562
  useBigInt64?: boolean;
527
563
  };
528
564
 
@@ -991,6 +1027,8 @@ export declare class ObjectId extends BSONValue {
991
1027
  * @param hexString - create a ObjectId from a passed in 24 character hexstring.
992
1028
  */
993
1029
  static createFromHexString(hexString: string): ObjectId;
1030
+ /** Creates an ObjectId instance from a base64 string */
1031
+ static createFromBase64(base64: string): ObjectId;
994
1032
  /**
995
1033
  * Checks if a value is a valid bson ObjectId
996
1034
  *
@@ -1043,14 +1081,27 @@ export declare function serialize(object: Document, options?: SerializeOptions):
1043
1081
 
1044
1082
  /** @public */
1045
1083
  export declare interface SerializeOptions {
1046
- /** the serializer will check if keys are valid. */
1084
+ /**
1085
+ * the serializer will check if keys are valid.
1086
+ * @defaultValue `false`
1087
+ */
1047
1088
  checkKeys?: boolean;
1048
- /** serialize the javascript functions **(default:false)**. */
1089
+ /**
1090
+ * serialize the javascript functions
1091
+ * @defaultValue `false`
1092
+ */
1049
1093
  serializeFunctions?: boolean;
1050
- /** serialize will not emit undefined fields **(default:true)** */
1094
+ /**
1095
+ * serialize will not emit undefined fields
1096
+ * note that the driver sets this to `false`
1097
+ * @defaultValue `true`
1098
+ */
1051
1099
  ignoreUndefined?: boolean;
1052
1100
  /* Excluded from this release type: minInternalBufferSize */
1053
- /** the index in the buffer where we wish to start serializing into */
1101
+ /**
1102
+ * the index in the buffer where we wish to start serializing into
1103
+ * @defaultValue `0`
1104
+ */
1054
1105
  index?: number;
1055
1106
  }
1056
1107
 
@@ -1068,7 +1119,7 @@ export declare function serializeWithBufferAndIndex(object: Document, finalBuffe
1068
1119
  /**
1069
1120
  * Sets the size of the internal serialization buffer.
1070
1121
  *
1071
- * @param size - The desired size for the internal serialization buffer
1122
+ * @param size - The desired size for the internal serialization buffer in bytes
1072
1123
  * @public
1073
1124
  */
1074
1125
  export declare function setInternalBufferSize(size: number): void;
@@ -1101,7 +1152,7 @@ declare function stringify(value: any, replacer?: (number | string)[] | ((this:
1101
1152
  /**
1102
1153
  * @public
1103
1154
  * @category BSONType
1104
- * */
1155
+ */
1105
1156
  export declare class Timestamp extends LongWithoutOverridesClass {
1106
1157
  get _bsontype(): 'Timestamp';
1107
1158
  static readonly MAX_VALUE: Long;
@@ -1162,10 +1213,12 @@ export declare type TimestampOverrides = '_bsontype' | 'toExtendedJSON' | 'fromE
1162
1213
  * @public
1163
1214
  */
1164
1215
  export declare class UUID extends Binary {
1216
+ /** @deprecated Hex string is no longer cached, this control will be removed in a future major release */
1165
1217
  static cacheHexString: boolean;
1166
- /* Excluded from this release type: __id */
1167
1218
  /**
1168
- * Create an UUID type
1219
+ * Create a UUID type
1220
+ *
1221
+ * When the argument to the constructor is omitted a random v4 UUID will be generated.
1169
1222
  *
1170
1223
  * @param input - Can be a 32 or 36 character hex string (dashes excluded/included) or a 16 byte binary Buffer.
1171
1224
  */
@@ -1179,7 +1232,7 @@ export declare class UUID extends Binary {
1179
1232
  /**
1180
1233
  * Returns the UUID id as a 32 or 36 character hex string representation, excluding/including dashes (defaults to 36 character dash separated)
1181
1234
  * @param includeDashes - should the string exclude dash-separators.
1182
- * */
1235
+ */
1183
1236
  toHexString(includeDashes?: boolean): string;
1184
1237
  /**
1185
1238
  * Converts the id into a 36 character (dashes included) hex string, unless a encoding is specified.
@@ -1208,12 +1261,16 @@ export declare class UUID extends Binary {
1208
1261
  * Checks if a value is a valid bson UUID
1209
1262
  * @param input - UUID, string or Buffer to validate.
1210
1263
  */
1211
- static isValid(input: string | Uint8Array | UUID): boolean;
1264
+ static isValid(input: string | Uint8Array | UUID | Binary): boolean;
1212
1265
  /**
1213
1266
  * Creates an UUID from a hex string representation of an UUID.
1214
1267
  * @param hexString - 32 or 36 character hex string (dashes excluded/included).
1215
1268
  */
1216
1269
  static createFromHexString(hexString: string): UUID;
1270
+ /** Creates an UUID from a base64 string representation of an UUID. */
1271
+ static createFromBase64(base64: string): UUID;
1272
+ /* Excluded from this release type: bytesFromString */
1273
+ /* Excluded from this release type: isValidUUIDString */
1217
1274
  inspect(): string;
1218
1275
  }
1219
1276
 
@@ -0,0 +1,182 @@
1
+ import type { EJSONOptions } from './extended_json';
2
+ import { BSONValue } from './bson_value';
3
+ /** @public */
4
+ export type BinarySequence = Uint8Array | number[];
5
+ /** @public */
6
+ export interface BinaryExtendedLegacy {
7
+ $type: string;
8
+ $binary: string;
9
+ }
10
+ /** @public */
11
+ export interface BinaryExtended {
12
+ $binary: {
13
+ subType: string;
14
+ base64: string;
15
+ };
16
+ }
17
+ /**
18
+ * A class representation of the BSON Binary type.
19
+ * @public
20
+ * @category BSONType
21
+ */
22
+ export declare class Binary extends BSONValue {
23
+ get _bsontype(): 'Binary';
24
+ /**
25
+ * Binary default subtype
26
+ * @internal
27
+ */
28
+ private static readonly BSON_BINARY_SUBTYPE_DEFAULT;
29
+ /** Initial buffer default size */
30
+ static readonly BUFFER_SIZE = 256;
31
+ /** Default BSON type */
32
+ static readonly SUBTYPE_DEFAULT = 0;
33
+ /** Function BSON type */
34
+ static readonly SUBTYPE_FUNCTION = 1;
35
+ /** Byte Array BSON type */
36
+ static readonly SUBTYPE_BYTE_ARRAY = 2;
37
+ /** Deprecated UUID BSON type @deprecated Please use SUBTYPE_UUID */
38
+ static readonly SUBTYPE_UUID_OLD = 3;
39
+ /** UUID BSON type */
40
+ static readonly SUBTYPE_UUID = 4;
41
+ /** MD5 BSON type */
42
+ static readonly SUBTYPE_MD5 = 5;
43
+ /** Encrypted BSON type */
44
+ static readonly SUBTYPE_ENCRYPTED = 6;
45
+ /** Column BSON type */
46
+ static readonly SUBTYPE_COLUMN = 7;
47
+ /** User BSON type */
48
+ static readonly SUBTYPE_USER_DEFINED = 128;
49
+ buffer: Uint8Array;
50
+ sub_type: number;
51
+ position: number;
52
+ /**
53
+ * Create a new Binary instance.
54
+ *
55
+ * This constructor can accept a string as its first argument. In this case,
56
+ * this string will be encoded using ISO-8859-1, **not** using UTF-8.
57
+ * This is almost certainly not what you want. Use `new Binary(Buffer.from(string))`
58
+ * instead to convert the string to a Buffer using UTF-8 first.
59
+ *
60
+ * @param buffer - a buffer object containing the binary data.
61
+ * @param subType - the option binary type.
62
+ */
63
+ constructor(buffer?: string | BinarySequence, subType?: number);
64
+ /**
65
+ * Updates this binary with byte_value.
66
+ *
67
+ * @param byteValue - a single byte we wish to write.
68
+ */
69
+ put(byteValue: string | number | Uint8Array | number[]): void;
70
+ /**
71
+ * Writes a buffer or string to the binary.
72
+ *
73
+ * @param sequence - a string or buffer to be written to the Binary BSON object.
74
+ * @param offset - specify the binary of where to write the content.
75
+ */
76
+ write(sequence: string | BinarySequence, offset: number): void;
77
+ /**
78
+ * Reads **length** bytes starting at **position**.
79
+ *
80
+ * @param position - read from the given position in the Binary.
81
+ * @param length - the number of bytes to read.
82
+ */
83
+ read(position: number, length: number): BinarySequence;
84
+ /**
85
+ * Returns the value of this binary as a string.
86
+ * @param asRaw - Will skip converting to a string
87
+ * @remarks
88
+ * This is handy when calling this function conditionally for some key value pairs and not others
89
+ */
90
+ value(asRaw?: boolean): string | BinarySequence;
91
+ /** the length of the binary sequence */
92
+ length(): number;
93
+ toJSON(): string;
94
+ toString(encoding?: 'hex' | 'base64' | 'utf8' | 'utf-8'): string;
95
+ /** @internal */
96
+ toExtendedJSON(options?: EJSONOptions): BinaryExtendedLegacy | BinaryExtended;
97
+ toUUID(): UUID;
98
+ /** Creates an Binary instance from a hex digit string */
99
+ static createFromHexString(hex: string, subType?: number): Binary;
100
+ /** Creates an Binary instance from a base64 string */
101
+ static createFromBase64(base64: string, subType?: number): Binary;
102
+ /** @internal */
103
+ static fromExtendedJSON(doc: BinaryExtendedLegacy | BinaryExtended | UUIDExtended, options?: EJSONOptions): Binary;
104
+ inspect(): string;
105
+ }
106
+ /** @public */
107
+ export type UUIDExtended = {
108
+ $uuid: string;
109
+ };
110
+ /**
111
+ * A class representation of the BSON UUID type.
112
+ * @public
113
+ */
114
+ export declare class UUID extends Binary {
115
+ /** @deprecated Hex string is no longer cached, this control will be removed in a future major release */
116
+ static cacheHexString: boolean;
117
+ /**
118
+ * Create a UUID type
119
+ *
120
+ * When the argument to the constructor is omitted a random v4 UUID will be generated.
121
+ *
122
+ * @param input - Can be a 32 or 36 character hex string (dashes excluded/included) or a 16 byte binary Buffer.
123
+ */
124
+ constructor(input?: string | Uint8Array | UUID);
125
+ /**
126
+ * The UUID bytes
127
+ * @readonly
128
+ */
129
+ get id(): Uint8Array;
130
+ set id(value: Uint8Array);
131
+ /**
132
+ * Returns the UUID id as a 32 or 36 character hex string representation, excluding/including dashes (defaults to 36 character dash separated)
133
+ * @param includeDashes - should the string exclude dash-separators.
134
+ */
135
+ toHexString(includeDashes?: boolean): string;
136
+ /**
137
+ * Converts the id into a 36 character (dashes included) hex string, unless a encoding is specified.
138
+ */
139
+ toString(encoding?: 'hex' | 'base64'): string;
140
+ /**
141
+ * Converts the id into its JSON string representation.
142
+ * A 36 character (dashes included) hex string in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
143
+ */
144
+ toJSON(): string;
145
+ /**
146
+ * Compares the equality of this UUID with `otherID`.
147
+ *
148
+ * @param otherId - UUID instance to compare against.
149
+ */
150
+ equals(otherId: string | Uint8Array | UUID): boolean;
151
+ /**
152
+ * Creates a Binary instance from the current UUID.
153
+ */
154
+ toBinary(): Binary;
155
+ /**
156
+ * Generates a populated buffer containing a v4 uuid
157
+ */
158
+ static generate(): Uint8Array;
159
+ /**
160
+ * Checks if a value is a valid bson UUID
161
+ * @param input - UUID, string or Buffer to validate.
162
+ */
163
+ static isValid(input: string | Uint8Array | UUID | Binary): boolean;
164
+ /**
165
+ * Creates an UUID from a hex string representation of an UUID.
166
+ * @param hexString - 32 or 36 character hex string (dashes excluded/included).
167
+ */
168
+ static createFromHexString(hexString: string): UUID;
169
+ /** Creates an UUID from a base64 string representation of an UUID. */
170
+ static createFromBase64(base64: string): UUID;
171
+ /** @internal */
172
+ static bytesFromString(representation: string): Uint8Array;
173
+ /**
174
+ * @internal
175
+ *
176
+ * Validates a string to be a hex digit sequence with or without dashes.
177
+ * The canonical hyphenated representation of a uuid is hex in 8-4-4-4-12 groups.
178
+ */
179
+ static isValidUUIDString(representation: string): boolean;
180
+ inspect(): string;
181
+ }
182
+ //# sourceMappingURL=binary.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":"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"}