bson 4.0.4 → 4.2.2

package/src/bson.ts

@@ -0,0 +1,326 @@
+import { Buffer } from 'buffer';
+import { Binary } from './binary';
+import { Code } from './code';
+import { DBRef } from './db_ref';
+import { Decimal128 } from './decimal128';
+import { Double } from './double';
+import { ensureBuffer } from './ensure_buffer';
+import { EJSON } from './extended_json';
+import { Int32 } from './int_32';
+import { Long } from './long';
+import { Map } from './map';
+import { MaxKey } from './max_key';
+import { MinKey } from './min_key';
+import { ObjectId } from './objectid';
+import { calculateObjectSize as internalCalculateObjectSize } from './parser/calculate_size';
+// Parts of the parser
+import { deserialize as internalDeserialize, DeserializeOptions } from './parser/deserializer';
+import { serializeInto as internalSerialize, SerializeOptions } from './parser/serializer';
+import { BSONRegExp } from './regexp';
+import { BSONSymbol } from './symbol';
+import { Timestamp } from './timestamp';
+export { BinaryExtended, BinaryExtendedLegacy, BinarySequence } from './binary';
+export { CodeExtended } from './code';
+export {
+  BSON_BINARY_SUBTYPE_BYTE_ARRAY,
+  BSON_BINARY_SUBTYPE_DEFAULT,
+  BSON_BINARY_SUBTYPE_FUNCTION,
+  BSON_BINARY_SUBTYPE_MD5,
+  BSON_BINARY_SUBTYPE_USER_DEFINED,
+  BSON_BINARY_SUBTYPE_UUID,
+  BSON_BINARY_SUBTYPE_UUID_NEW,
+  BSON_DATA_ARRAY,
+  BSON_DATA_BINARY,
+  BSON_DATA_BOOLEAN,
+  BSON_DATA_CODE,
+  BSON_DATA_CODE_W_SCOPE,
+  BSON_DATA_DATE,
+  BSON_DATA_DBPOINTER,
+  BSON_DATA_DECIMAL128,
+  BSON_DATA_INT,
+  BSON_DATA_LONG,
+  BSON_DATA_MAX_KEY,
+  BSON_DATA_MIN_KEY,
+  BSON_DATA_NULL,
+  BSON_DATA_NUMBER,
+  BSON_DATA_OBJECT,
+  BSON_DATA_OID,
+  BSON_DATA_REGEXP,
+  BSON_DATA_STRING,
+  BSON_DATA_SYMBOL,
+  BSON_DATA_TIMESTAMP,
+  BSON_DATA_UNDEFINED,
+  BSON_INT32_MAX,
+  BSON_INT32_MIN,
+  BSON_INT64_MAX,
+  BSON_INT64_MIN
+} from './constants';
+export { DBRefLike } from './db_ref';
+export { Decimal128Extended } from './decimal128';
+export { DoubleExtended } from './double';
+export { EJSON, EJSONOptions } from './extended_json';
+export { Int32Extended } from './int_32';
+export { LongExtended } from './long';
+export { MaxKeyExtended } from './max_key';
+export { MinKeyExtended } from './min_key';
+export { ObjectIdExtended, ObjectIdLike } from './objectid';
+export { BSONRegExpExtended, BSONRegExpExtendedLegacy } from './regexp';
+export { BSONSymbolExtended } from './symbol';
+export {
+  LongWithoutOverrides,
+  LongWithoutOverridesClass,
+  TimestampExtended,
+  TimestampOverrides
+} from './timestamp';
+export { UUIDExtended } from './uuid';
+export { SerializeOptions, DeserializeOptions };
+export {
+  Code,
+  Map,
+  BSONSymbol,
+  DBRef,
+  Binary,
+  ObjectId,
+  Long,
+  Timestamp,
+  Double,
+  Int32,
+  MinKey,
+  MaxKey,
+  BSONRegExp,
+  Decimal128,
+  // In 4.0.0 and 4.0.1, this property name was changed to ObjectId to match the class name.
+  // This caused interoperability problems with previous versions of the library, so in
+  // later builds we changed it back to ObjectID (capital D) to match legacy implementations.
+  ObjectId as ObjectID
+};
+
+/** @public */
+export interface Document {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+/** @internal */
+// Default Max Size
+const MAXSIZE = 1024 * 1024 * 17;
+
+// Current Internal Temporary Serialization Buffer
+let buffer = Buffer.alloc(MAXSIZE);
+
+/**
+ * Sets the size of the internal serialization buffer.
+ *
+ * @param size - The desired size for the internal serialization buffer
+ * @public
+ */
+export function setInternalBufferSize(size: number): void {
+  // Resize the internal serialization buffer if needed
+  if (buffer.length < size) {
+    buffer = Buffer.alloc(size);
+  }
+}
+
+/**
+ * Serialize a Javascript object.
+ *
+ * @param object - the Javascript object to serialize.
+ * @returns Buffer object containing the serialized object.
+ * @public
+ */
+export function serialize(object: Document, options: SerializeOptions = {}): Buffer {
+  // Unpack the options
+  const checkKeys = typeof options.checkKeys === 'boolean' ? options.checkKeys : false;
+  const serializeFunctions =
+    typeof options.serializeFunctions === 'boolean' ? options.serializeFunctions : false;
+  const ignoreUndefined =
+    typeof options.ignoreUndefined === 'boolean' ? options.ignoreUndefined : true;
+  const minInternalBufferSize =
+    typeof options.minInternalBufferSize === 'number' ? options.minInternalBufferSize : MAXSIZE;
+
+  // Resize the internal serialization buffer if needed
+  if (buffer.length < minInternalBufferSize) {
+    buffer = Buffer.alloc(minInternalBufferSize);
+  }
+
+  // Attempt to serialize
+  const serializationIndex = internalSerialize(
+    buffer,
+    object,
+    checkKeys,
+    0,
+    0,
+    serializeFunctions,
+    ignoreUndefined,
+    []
+  );
+
+  // Create the final buffer
+  const finishedBuffer = Buffer.alloc(serializationIndex);
+
+  // Copy into the finished buffer
+  buffer.copy(finishedBuffer, 0, 0, finishedBuffer.length);
+
+  // Return the buffer
+  return finishedBuffer;
+}
+
+/**
+ * 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 finalBuffer - the Buffer you pre-allocated to store the serialized BSON object.
+ * @returns the index pointing to the last written byte in the buffer.
+ * @public
+ */
+export function serializeWithBufferAndIndex(
+  object: Document,
+  finalBuffer: Buffer,
+  options: SerializeOptions = {}
+): number {
+  // Unpack the options
+  const checkKeys = typeof options.checkKeys === 'boolean' ? options.checkKeys : false;
+  const serializeFunctions =
+    typeof options.serializeFunctions === 'boolean' ? options.serializeFunctions : false;
+  const ignoreUndefined =
+    typeof options.ignoreUndefined === 'boolean' ? options.ignoreUndefined : true;
+  const startIndex = typeof options.index === 'number' ? options.index : 0;
+
+  // Attempt to serialize
+  const serializationIndex = internalSerialize(
+    buffer,
+    object,
+    checkKeys,
+    0,
+    0,
+    serializeFunctions,
+    ignoreUndefined
+  );
+  buffer.copy(finalBuffer, startIndex, 0, serializationIndex);
+
+  // Return the index
+  return startIndex + serializationIndex - 1;
+}
+
+/**
+ * Deserialize data as BSON.
+ *
+ * @param buffer - the buffer containing the serialized set of BSON documents.
+ * @returns returns the deserialized Javascript Object.
+ * @public
+ */
+export function deserialize(
+  buffer: Buffer | ArrayBufferView | ArrayBuffer,
+  options: DeserializeOptions = {}
+): Document {
+  return internalDeserialize(ensureBuffer(buffer), options);
+}
+
+/** @public */
+export type CalculateObjectSizeOptions = Pick<
+  SerializeOptions,
+  'serializeFunctions' | 'ignoreUndefined'
+>;
+
+/**
+ * Calculate the bson size for a passed in Javascript object.
+ *
+ * @param object - the Javascript object to calculate the BSON byte size for
+ * @returns size of BSON object in bytes
+ * @public
+ */
+export function calculateObjectSize(
+  object: Document,
+  options: CalculateObjectSizeOptions = {}
+): number {
+  options = options || {};
+
+  const serializeFunctions =
+    typeof options.serializeFunctions === 'boolean' ? options.serializeFunctions : false;
+  const ignoreUndefined =
+    typeof options.ignoreUndefined === 'boolean' ? options.ignoreUndefined : true;
+
+  return internalCalculateObjectSize(object, serializeFunctions, ignoreUndefined);
+}
+
+/**
+ * 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 next index in the buffer after deserialization **x** numbers of documents.
+ * @public
+ */
+export function deserializeStream(
+  data: Buffer | ArrayBufferView | ArrayBuffer,
+  startIndex: number,
+  numberOfDocuments: number,
+  documents: Document[],
+  docStartIndex: number,
+  options: DeserializeOptions
+): number {
+  const internalOptions = Object.assign(
+    { allowObjectSmallerThanBufferSize: true, index: 0 },
+    options
+  );
+  const bufferData = ensureBuffer(data);
+
+  let index = startIndex;
+  // Loop over all documents
+  for (let i = 0; i < numberOfDocuments; i++) {
+    // Find size of the document
+    const size =
+      bufferData[index] |
+      (bufferData[index + 1] << 8) |
+      (bufferData[index + 2] << 16) |
+      (bufferData[index + 3] << 24);
+    // Update options with index
+    internalOptions.index = index;
+    // Parse the document at this point
+    documents[docStartIndex + i] = internalDeserialize(bufferData, internalOptions);
+    // Adjust index by the document size
+    index = index + size;
+  }
+
+  // Return object containing end index of parsing and list of documents
+  return index;
+}
+
+/**
+ * BSON default export
+ * @deprecated Please use named exports
+ * @privateRemarks
+ * We want to someday deprecate the default export,
+ * so none of the new TS types are being exported on the default
+ * @public
+ */
+const BSON = {
+  Binary,
+  Code,
+  DBRef,
+  Decimal128,
+  Double,
+  Int32,
+  Long,
+  Map,
+  MaxKey,
+  MinKey,
+  ObjectId,
+  ObjectID: ObjectId,
+  BSONRegExp,
+  BSONSymbol,
+  Timestamp,
+  EJSON,
+  setInternalBufferSize,
+  serialize,
+  serializeWithBufferAndIndex,
+  deserialize,
+  calculateObjectSize,
+  deserializeStream
+};
+export default BSON;

package/src/code.ts

@@ -0,0 +1,57 @@
+import type { Document } from './bson';
+
+/** @public */
+export interface CodeExtended {
+  $code: string | Function;
+  $scope?: Document;
+}
+
+/**
+ * A class representation of the BSON Code type.
+ * @public
+ */
+export class Code {
+  _bsontype!: 'Code';
+
+  code: string | Function;
+  scope?: Document;
+  /**
+   * @param code - a string or function.
+   * @param scope - an optional scope for the function.
+   */
+  constructor(code: string | Function, scope?: Document) {
+    this.code = code;
+    this.scope = scope;
+  }
+
+  /** @internal */
+  toJSON(): { code: string | Function; scope?: Document } {
+    return { code: this.code, scope: this.scope };
+  }
+
+  /** @internal */
+  toExtendedJSON(): CodeExtended {
+    if (this.scope) {
+      return { $code: this.code, $scope: this.scope };
+    }
+
+    return { $code: this.code };
+  }
+
+  /** @internal */
+  static fromExtendedJSON(doc: CodeExtended): Code {
+    return new Code(doc.$code, doc.$scope);
+  }
+
+  /** @internal */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.inspect();
+  }
+
+  inspect(): string {
+    const codeJson = this.toJSON();
+    return `Code("${codeJson.code}"${codeJson.scope ? `, ${JSON.stringify(codeJson.scope)}` : ''})`;
+  }
+}
+
+Object.defineProperty(Code.prototype, '_bsontype', { value: 'Code' });

package/src/constants.ts

@@ -0,0 +1,104 @@
+/** @internal */
+export const BSON_INT32_MAX = 0x7fffffff;
+/** @internal */
+export const BSON_INT32_MIN = -0x80000000;
+/** @internal */
+export const BSON_INT64_MAX = Math.pow(2, 63) - 1;
+/** @internal */
+export const BSON_INT64_MIN = -Math.pow(2, 63);
+
+/**
+ * Any integer up to 2^53 can be precisely represented by a double.
+ * @internal
+ */
+export const JS_INT_MAX = Math.pow(2, 53);
+
+/**
+ * Any integer down to -2^53 can be precisely represented by a double.
+ * @internal
+ */
+export const JS_INT_MIN = -Math.pow(2, 53);
+
+/** Number BSON Type @internal */
+export const BSON_DATA_NUMBER = 1;
+
+/** String BSON Type @internal */
+export const BSON_DATA_STRING = 2;
+
+/** Object BSON Type @internal */
+export const BSON_DATA_OBJECT = 3;
+
+/** Array BSON Type @internal */
+export const BSON_DATA_ARRAY = 4;
+
+/** Binary BSON Type @internal */
+export const BSON_DATA_BINARY = 5;
+
+/** Binary BSON Type @internal */
+export const BSON_DATA_UNDEFINED = 6;
+
+/** ObjectId BSON Type @internal */
+export const BSON_DATA_OID = 7;
+
+/** Boolean BSON Type @internal */
+export const BSON_DATA_BOOLEAN = 8;
+
+/** Date BSON Type @internal */
+export const BSON_DATA_DATE = 9;
+
+/** null BSON Type @internal */
+export const BSON_DATA_NULL = 10;
+
+/** RegExp BSON Type @internal */
+export const BSON_DATA_REGEXP = 11;
+
+/** Code BSON Type @internal */
+export const BSON_DATA_DBPOINTER = 12;
+
+/** Code BSON Type @internal */
+export const BSON_DATA_CODE = 13;
+
+/** Symbol BSON Type @internal */
+export const BSON_DATA_SYMBOL = 14;
+
+/** Code with Scope BSON Type @internal */
+export const BSON_DATA_CODE_W_SCOPE = 15;
+
+/** 32 bit Integer BSON Type @internal */
+export const BSON_DATA_INT = 16;
+
+/** Timestamp BSON Type @internal */
+export const BSON_DATA_TIMESTAMP = 17;
+
+/** Long BSON Type @internal */
+export const BSON_DATA_LONG = 18;
+
+/** Decimal128 BSON Type @internal */
+export const BSON_DATA_DECIMAL128 = 19;
+
+/** MinKey BSON Type @internal */
+export const BSON_DATA_MIN_KEY = 0xff;
+
+/** MaxKey BSON Type @internal */
+export const BSON_DATA_MAX_KEY = 0x7f;
+
+/** Binary Default Type @internal */
+export const BSON_BINARY_SUBTYPE_DEFAULT = 0;
+
+/** Binary Function Type @internal */
+export const BSON_BINARY_SUBTYPE_FUNCTION = 1;
+
+/** Binary Byte Array Type @internal */
+export const BSON_BINARY_SUBTYPE_BYTE_ARRAY = 2;
+
+/** Binary Deprecated UUID Type @deprecated Please use BSON_BINARY_SUBTYPE_UUID_NEW @internal */
+export const BSON_BINARY_SUBTYPE_UUID = 3;
+
+/** Binary UUID Type @internal */
+export const BSON_BINARY_SUBTYPE_UUID_NEW = 4;
+
+/** Binary MD5 Type @internal */
+export const BSON_BINARY_SUBTYPE_MD5 = 5;
+
+/** Binary User Defined Type @internal */
+export const BSON_BINARY_SUBTYPE_USER_DEFINED = 128;

package/src/db_ref.ts

@@ -0,0 +1,115 @@
+import type { Document } from './bson';
+import type { EJSONOptions } from './extended_json';
+import type { ObjectId } from './objectid';
+import { isObjectLike } from './parser/utils';
+
+/** @public */
+export interface DBRefLike {
+  $ref: string;
+  $id: ObjectId;
+  $db?: string;
+}
+
+/** @internal */
+export function isDBRefLike(value: unknown): value is DBRefLike {
+  return isObjectLike(value) && value['$id'] != null && value['$ref'] != null;
+}
+
+/**
+ * A class representation of the BSON DBRef type.
+ * @public
+ */
+export class DBRef {
+  _bsontype!: 'DBRef';
+
+  collection: string;
+  oid: ObjectId;
+  db?: string;
+  fields: Document;
+
+  /**
+   * @param collection - the collection name.
+   * @param oid - the reference ObjectId.
+   * @param db - optional db name, if omitted the reference is local to the current db.
+   */
+  constructor(collection: string, oid: ObjectId, db?: string, fields?: Document) {
+    // check if namespace has been provided
+    const parts = collection.split('.');
+    if (parts.length === 2) {
+      db = parts.shift();
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      collection = parts.shift()!;
+    }
+
+    this.collection = collection;
+    this.oid = oid;
+    this.db = db;
+    this.fields = fields || {};
+  }
+
+  // Property provided for compatibility with the 1.x parser
+  // the 1.x parser used a "namespace" property, while 4.x uses "collection"
+
+  /** @internal */
+  get namespace(): string {
+    return this.collection;
+  }
+
+  set namespace(value: string) {
+    this.collection = value;
+  }
+
+  /** @internal */
+  toJSON(): DBRefLike & Document {
+    const o = Object.assign(
+      {
+        $ref: this.collection,
+        $id: this.oid
+      },
+      this.fields
+    );
+
+    if (this.db != null) o.$db = this.db;
+    return o;
+  }
+
+  /** @internal */
+  toExtendedJSON(options?: EJSONOptions): DBRefLike {
+    options = options || {};
+    let o: DBRefLike = {
+      $ref: this.collection,
+      $id: this.oid
+    };
+
+    if (options.legacy) {
+      return o;
+    }
+
+    if (this.db) o.$db = this.db;
+    o = Object.assign(o, this.fields);
+    return o;
+  }
+
+  /** @internal */
+  static fromExtendedJSON(doc: DBRefLike): DBRef {
+    const copy = Object.assign({}, doc) as Partial<DBRefLike>;
+    delete copy.$ref;
+    delete copy.$id;
+    delete copy.$db;
+    return new DBRef(doc.$ref, doc.$id, doc.$db, copy);
+  }
+
+  /** @internal */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.inspect();
+  }
+
+  inspect(): string {
+    // NOTE: if OID is an ObjectId class it will just print the oid string.
+    const oid =
+      this.oid === undefined || this.oid.toString === undefined ? this.oid : this.oid.toString();
+    return `DBRef("${this.namespace}", "${oid}"${this.db ? `, "${this.db}"` : ''})`;
+  }
+}
+
+Object.defineProperty(DBRef.prototype, '_bsontype', { value: 'DBRef' });