From eb735f86b653fbf3c1d37581248260407e2f086b Mon Sep 17 00:00:00 2001 From: Andrey Tselishchev Date: Fri, 6 Jul 2018 21:55:43 +0300 Subject: [PATCH] Update [@types/bson] to match js-bson@1.0.6 (#27098) * [@types/bson] Updated BSON class definitions * Updated BSON.serialize (changed the way how options are passed) * Updated BSON.deserialize (added missing options, removed `isArray` argument) * Added BSON.serializeWithBufferAndIndex * Added BSON.deserializeStream * [@types/bson] Updated BSON types * Binary: Made static constants 'readonly', added comments * ObjectID: 'equals' can accept string, added comments * Code, DBRef, Double, Decimal128, MaxKey, MinKey, ObjectID, BSONRegExp, Symbol: Added comments * [@types/bson] Updated Long & Timestamp BSON types * In original js-node@1.0.x code 'Timestamp' is a 100% copy-paste of 'Long' with 'Long' replaced by 'Timestamp' (changed to inheritance in js-node@2.0.0). Do avoid duplication in typings a base class 'LongLike' was introduced and both 'Long' and 'Timestamp' are inherited from 'LongLike'. * Made static constants 'readonly', fixed return-type for greaterThan and greaterThanOrEqual (boolean), renamed argument for shiftLeft, shiftRight, shiftRightUnsigned, added comments * [@types/bson] Changed header version number to 1.0.6 --- types/bson/bson-tests.ts | 2 +- types/bson/index.d.ts | 364 +++++++++++++++++++++++++++++---------- 2 files changed, 271 insertions(+), 95 deletions(-) diff --git a/types/bson/bson-tests.ts b/types/bson/bson-tests.ts index b3173053c8..f75ee94523 100644 --- a/types/bson/bson-tests.ts +++ b/types/bson/bson-tests.ts @@ -9,7 +9,7 @@ let Long = bson.Long; let doc = { long: Long.fromNumber(100) } // Serialize a document -let data = BSON.serialize(doc, false, true, false); +let data = BSON.serialize(doc); console.log("data:", data); // Deserialize the resulting Buffer diff --git a/types/bson/index.d.ts b/types/bson/index.d.ts index 4d30097478..6bad691dcf 100644 --- a/types/bson/index.d.ts +++ b/types/bson/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for bson 1.0.4 +// Type definitions for bson 1.0.6 // Project: https://github.com/mongodb/js-bson // Definitions by: Hiroki Horiuchi // Federico Caselli @@ -6,34 +6,81 @@ /// +interface CommonSerializeOptions { + /** {default:false}, the serializer will check if keys are valid. */ + checkKeys?: boolean; + /** {default:false}, serialize the javascript functions. */ + serializeFunctions?: boolean; + /** {default:true}, ignore undefined fields. */ + ignoreUndefined?: boolean; +} + +export interface SerializeOptions extends CommonSerializeOptions { + /** {default:1024*1024*17}, minimum size of the internal temporary serialization buffer. */ + minInternalBufferSize?: number; +} + +export interface SerializeWithBufferAndIndexOptions extends CommonSerializeOptions { + /** {default:0}, the index in the buffer where we wish to start serializing into. */ + index?: number; +} + export interface DeserializeOptions { - /** {Boolean, default:false}, evaluate functions in the BSON document scoped to the object deserialized. */ + /** {default:false}, evaluate functions in the BSON document scoped to the object deserialized. */ evalFunctions?: boolean; - /** {Boolean, default:false}, cache evaluated functions for reuse. */ + /** {default:false}, cache evaluated functions for reuse. */ cacheFunctions?: boolean; - /** {Boolean, default:false}, use a crc32 code for caching, otherwise use the string of the function. */ + /** {default:false}, use a crc32 code for caching, otherwise use the string of the function. */ cacheFunctionsCrc32?: boolean; - /** {Boolean, default:false}, deserialize Binary data directly into node.js Buffer object. */ + /** {default:true}, when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */ + promoteLongs?: boolean; + /** {default:false}, deserialize Binary data directly into node.js Buffer object. */ promoteBuffers?: boolean; + /** {default:false}, when deserializing will promote BSON values to their Node.js closest equivalent types. */ + promoteValues?: boolean; + /** {default:null}, allow to specify if there what fields we wish to return as unserialized raw buffer. */ + fieldsAsRaw?: { readonly [fieldName: string]: boolean }; + /** {default:false}, return BSON regular expressions as BSONRegExp instances. */ + bsonRegExp?: boolean; } export interface CalculateObjectSizeOptions { - /** {Boolean, default:false}, serialize the javascript functions */ + /** {default:false}, serialize the javascript functions */ serializeFunctions?: boolean; - /** {Boolean, default:true}, ignore undefined fields. */ + /** {default:true}, ignore undefined fields. */ ignoreUndefined?: boolean; } export class BSON { + /** - * @param {Object} object the Javascript object to serialize. - * @param {Boolean} checkKeys the serializer will check if keys are valid. - * @param {Boolean} asBuffer return the serialized object as a Buffer object (ignore). - * @param {Boolean} serializeFunctions serialize the javascript functions (default:false) - * @return {Buffer} returns a TypedArray or Array depending on what your browser supports + * Serialize a Javascript object. + * + * @param object The Javascript object to serialize. + * @param options Serialize options. + * @return The Buffer object containing the serialized object. */ - serialize(object: any, checkKeys?: boolean, asBuffer?: boolean, serializeFunctions?: boolean): Buffer; - deserialize(buffer: Buffer, options?: DeserializeOptions, isArray?: boolean): any; + serialize(object: any, options?: SerializeOptions): Buffer; + + /** + * Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization. + * + * @param object The Javascript object to serialize. + * @param buffer The Buffer you pre-allocated to store the serialized BSON object. + * @param options Serialize options. + * @returns The index pointing to the last written byte in the buffer + */ + serializeWithBufferAndIndex(object: any, buffer: Buffer, options?: SerializeWithBufferAndIndexOptions): number; + + /** + * Deserialize data as BSON. + * + * @param buffer The buffer containing the serialized set of BSON documents. + * @param options Deserialize options. + * @returns The deserialized Javascript Object. + */ + deserialize(buffer: Buffer, options?: DeserializeOptions): any; + /** * Calculate the bson size for a passed in Javascript object. * @@ -42,17 +89,44 @@ export class BSON { * @return {Number} returns the number of bytes the BSON object will take up. */ calculateObjectSize(object: any, options?: CalculateObjectSizeOptions): number; + + /** + * Deserialize stream data as BSON documents. + * + * @param data The buffer containing the serialized set of BSON documents. + * @param startIndex The start index in the data Buffer where the deserialization is to start. + * @param numberOfDocuments Number of documents to deserialize + * @param documents An array where to store the deserialized documents + * @param docStartIndex The index in the documents array from where to start inserting documents + * @param options Additional options used for the deserialization + * @returns The next index in the buffer after deserialization of the `numberOfDocuments` + */ + deserializeStream( + data: Buffer, + startIndex: number, + numberOfDocuments: number, + documents: Array, + docStartIndex: number, + options?: DeserializeOptions + ): number; + } +/** A class representation of the BSON Binary type. */ export class Binary { - static SUBTYPE_DEFAULT: number; - static SUBTYPE_FUNCTION: number; - static SUBTYPE_BYTE_ARRAY: number; - static SUBTYPE_UUID_OLD: number; - static SUBTYPE_UUID: number; - static SUBTYPE_MD5: number; - static SUBTYPE_USER_DEFINED: number; + static readonly SUBTYPE_DEFAULT: number; + static readonly SUBTYPE_FUNCTION: number; + static readonly SUBTYPE_BYTE_ARRAY: number; + static readonly SUBTYPE_UUID_OLD: number; + static readonly SUBTYPE_UUID: number; + static readonly SUBTYPE_MD5: number; + static readonly SUBTYPE_USER_DEFINED: number; + + /** + * @param buffer A buffer object containing the binary data + * @param subType Binary data subtype + */ constructor(buffer: Buffer, subType?: number); /** The underlying Buffer which stores the binary data. */ @@ -69,80 +143,193 @@ export class Binary { /** Writes a buffer or string to the binary */ write(buffer: Buffer | string, offset: number): void; } + +/** A class representation of the BSON Code type. */ export class Code { + /** + * @param code A string or function. + * @param scope An optional scope for the function. + */ constructor(code: string | Function, scope?: any); } + +/** + * A class representation of the BSON DBRef type. + * @deprecated + */ export class DBRef { + /** + * @param namespace The collection name. + * @param oid The reference ObjectID. + * @param db Optional db name, if omitted the reference is local to the current db + */ constructor(namespace: string, oid: ObjectID, db?: string); + namespace: string; oid: ObjectID; db?: string; } + +/** A class representation of the BSON Double type. */ export class Double { + /** + * @param value The number we want to represent as a double. + */ constructor(value: number); valueOf(): number; } -export class Long { - static MAX_VALUE: Long; - static MIN_VALUE: Long; - static NEG_ONE: Long; - static ONE: Long; - static ZERO: Long; - static fromInt(i: number): Long; - static fromNumber(n: number): Long; - static fromBits(lowBits: number, highBits: number): Long; - static fromString(s: string, opt_radix?: number): Long; +/** + * Base class for Long and Timestamp. + * In original js-node@1.0.x code 'Timestamp' is a 100% copy-paste of 'Long' + * with 'Long' replaced by 'Timestamp' (changed to inheritance in js-node@2.0.0) + */ +declare class LongLike { + /** + * @param low The low (signed) 32 bits. + * @param high The high (signed) 32 bits. + */ constructor(low: number, high: number); - add(other: Long): Long; - and(other: Long): Long; - compare(other: Long): number; - div(other: Long): Long; - equals(other: Long): boolean; + /** Returns the sum of `this` and the `other`. */ + add(other: T): T; + /** Returns the bitwise-AND of `this` and the `other`. */ + and(other: T): T; + /** + * Compares `this` with the given `other`. + * @returns 0 if they are the same, 1 if the this is greater, and -1 if the given one is greater. + */ + compare(other: T): number; + /** Returns `this` divided by the given `other`. */ + div(other: T): T; + /** Return whether `this` equals the `other` */ + equals(other: T): boolean; + /** Return the high 32-bits value. */ getHighBits(): number; + /** Return the low 32-bits value. */ getLowBits(): number; + /** Return the low unsigned 32-bits value. */ getLowBitsUnsigned(): number; + /** Returns the number of bits needed to represent the absolute value of `this`. */ getNumBitsAbs(): number; - greaterThan(other: Long): number; - greaterThanOrEqual(other: Long): number; + /** Return whether `this` is greater than the `other`. */ + greaterThan(other: T): boolean; + /** Return whether `this` is greater than or equal to the `other`. */ + greaterThanOrEqual(other: T): boolean; + /** Return whether `this` value is negative. */ isNegative(): boolean; + /** Return whether `this` value is odd. */ isOdd(): boolean; + /** Return whether `this` value is zero. */ isZero(): boolean; - lessThan(other: Long): boolean; - lessThanOrEqual(other: Long): boolean; - modulo(other: Long): Long; - multiply(other: Long): Long; - negate(): Long; - not(): Long; - notEquals(other: Long): boolean; - or(other: Long): Long; - shiftLeft(other: number): Long; - shiftRight(other: number): Long; - shiftRightUnsigned(other: number): Long; - subtract(other: Long): Long; + /** Return whether `this` is less than the `other`. */ + lessThan(other: T): boolean; + /** Return whether `this` is less than or equal to the `other`. */ + lessThanOrEqual(other: T): boolean; + /** Returns `this` modulo the given `other`. */ + modulo(other: T): T; + /** Returns the product of `this` and the given `other`. */ + multiply(other: T): T; + /** The negation of this value. */ + negate(): T; + /** The bitwise-NOT of this value. */ + not(): T; + /** Return whether `this` does not equal to the `other`. */ + notEquals(other: T): boolean; + /** Returns the bitwise-OR of `this` and the given `other`. */ + or(other: T): T; + /** + * Returns `this` with bits shifted to the left by the given amount. + * @param numBits The number of bits by which to shift. + */ + shiftLeft(numBits: number): T; + /** + * Returns `this` with bits shifted to the right by the given amount. + * @param numBits The number of bits by which to shift. + */ + shiftRight(numBits: number): T; + /** + * Returns `this` with bits shifted to the right by the given amount, with the new top bits matching the current sign bit. + * @param numBits The number of bits by which to shift. + */ + shiftRightUnsigned(numBits: number): T; + /** Returns the difference of `this` and the given `other`. */ + subtract(other: T): T; + /** Return the int value (low 32 bits). */ toInt(): number; + /** Return the JSON value. */ toJSON(): string; + /** Returns closest floating-point representation to `this` value */ toNumber(): number; + /** + * Return as a string + * @param radix the radix in which the text should be written. {default:10} + */ toString(radix?: number): string; - xor(other: Long): Long; + /** Returns the bitwise-XOR of `this` and the given `other`. */ + xor(other: T): T; + } + +/** + * A class representation of the BSON Long type, a 64-bit two's-complement + * integer value, which faithfully simulates the behavior of a Java "Long". This + * implementation is derived from LongLib in GWT. + */ +export class Long extends LongLike { + + static readonly MAX_VALUE: Long; + static readonly MIN_VALUE: Long; + static readonly NEG_ONE: Long; + static readonly ONE: Long; + static readonly ZERO: Long; + + /** Returns a Long representing the given (32-bit) integer value. */ + static fromInt(i: number): Long; + /** Returns a Long representing the given value, provided that it is a finite number. Otherwise, zero is returned. */ + static fromNumber(n: number): Long; + /** + * Returns a Long representing the 64-bit integer that comes by concatenating the given high and low bits. Each is assumed to use 32 bits. + * @param lowBits The low 32-bits. + * @param highBits The high 32-bits. + */ + static fromBits(lowBits: number, highBits: number): Long; + /** + * Returns a Long representation of the given string + * @param opt_radix The radix in which the text is written. {default:10} + */ + static fromString(s: string, opt_radix?: number): Long; + +} + +/** A class representation of the BSON Decimal128 type. */ export class Decimal128 { + + /** Create a Decimal128 instance from a string representation. */ static fromString(s: string): Decimal128; + /** + * @param bytes A buffer containing the raw Decimal128 bytes. + */ constructor(bytes: Buffer); toJSON(): string; toString(): string; } + +/** A class representation of the BSON MaxKey type. */ export class MaxKey { constructor(); } + +/** A class representation of the BSON MinKey type. */ export class MinKey { constructor(); } + +/** A class representation of the BSON ObjectID type. */ export class ObjectID { /** * Create a new ObjectID instance @@ -173,10 +360,10 @@ export class ObjectID { static isValid(id: string | number | ObjectID): boolean; /** * Compares the equality of this ObjectID with `otherID`. - * @param {object} otherID ObjectID instance to compare against. + * @param {ObjectID|string} otherID ObjectID instance to compare against. * @return {boolean} the result of comparing two ObjectID's */ - equals(otherID: ObjectID): boolean; + equals(otherID: ObjectID | string): boolean; /** * Generate a 12 byte id string used in ObjectID's * @param {number} time optional parameter allowing to pass in a second based timestamp. @@ -185,7 +372,7 @@ export class ObjectID { generate(time?: number): Buffer; /** * Returns the generation date (accurate up to the second) that this ID was generated. - * @return {date} the generation date + * @return {Date} the generation date */ getTimestamp(): Date; /** @@ -194,56 +381,45 @@ export class ObjectID { */ toHexString(): string; } + export { ObjectID as ObjectId }; + +/** A class representation of the BSON RegExp type. */ export class BSONRegExp { constructor(pattern: string, options: string); } + +/** + * A class representation of the BSON Symbol type. + * @deprecated + */ export class Symbol { constructor(value: string); } -export class Timestamp { - constructor(low: number, high: number); - static MAX_VALUE: Timestamp; - static MIN_VALUE: Timestamp; - static NEG_ONE: Timestamp; - static ONE: Timestamp; - static ZERO: Timestamp; +/** A class representation of the BSON Timestamp type. */ +export class Timestamp extends LongLike { - static fromBits(lowBits: number, highBits: number): Timestamp; + static readonly MAX_VALUE: Timestamp; + static readonly MIN_VALUE: Timestamp; + static readonly NEG_ONE: Timestamp; + static readonly ONE: Timestamp; + static readonly ZERO: Timestamp; + + /** Returns a Timestamp represented by the given (32-bit) integer value */ static fromInt(value: number): Timestamp; + /** Returns a Timestamp representing the given number value, provided that it is a finite number. */ static fromNumber(value: number): Timestamp; - static fromString(str: string, radix?: number): Timestamp; + /** + * Returns a Timestamp for the given high and low bits. Each is assumed to use 32 bits. + * @param lowBits The low 32-bits. + * @param highBits The high 32-bits. + */ + static fromBits(lowBits: number, highBits: number): Timestamp; + /** + * Returns a Timestamp from the given string. + * @param opt_radix The radix in which the text is written. {default:10} + */ + static fromString(str: string, opt_radix?: number): Timestamp; - add(other: Timestamp): Timestamp; - and(other: Timestamp): Timestamp; - compare(other: Timestamp): number; - div(other: Timestamp): Timestamp; - equals(other: Timestamp): boolean; - getHighBits(): number; - getLowBits(): number; - getLowBitsUnsigned(): number; - getNumBitsAbs(): number; - greaterThan(other: Timestamp): number; - greaterThanOrEqual(other: Timestamp): number; - isNegative(): boolean; - isOdd(): boolean; - isZero(): boolean; - lessThan(other: Timestamp): boolean; - lessThanOrEqual(other: Timestamp): boolean; - modulo(other: Timestamp): Timestamp; - multiply(other: Timestamp): Timestamp; - negate(): Timestamp; - not(): Timestamp; - notEquals(other: Timestamp): boolean; - or(other: Timestamp): Timestamp; - shiftLeft(other: number): Timestamp; - shiftRight(other: number): Timestamp; - shiftRightUnsigned(other: number): Timestamp; - subtract(other: Timestamp): Timestamp; - toInt(): number; - toJSON(): string; - toNumber(): number; - toString(radix?: number): string; - xor(other: Timestamp): Timestamp; }