bson 4.1.0 → 4.2.3

package/src/binary.ts

@@ -0,0 +1,272 @@
+import { Buffer } from 'buffer';
+import { ensureBuffer } from './ensure_buffer';
+import type { EJSONOptions } from './extended_json';
+import { parseUUID, UUIDExtended } from './uuid';
+
+/** @public */
+export type BinarySequence = Uint8Array | Buffer | number[];
+
+/** @public */
+export interface BinaryExtendedLegacy {
+  $type: string;
+  $binary: string;
+}
+
+/** @public */
+export interface BinaryExtended {
+  $binary: {
+    subType: string;
+    base64: string;
+  };
+}
+
+/**
+ * A class representation of the BSON Binary type.
+ * @public
+ */
+export class Binary {
+  _bsontype!: 'Binary';
+
+  /**
+   * Binary default subtype
+   * @internal
+   */
+  private static readonly BSON_BINARY_SUBTYPE_DEFAULT = 0;
+
+  /** Initial buffer default size */
+  static readonly BUFFER_SIZE = 256;
+  /** Default BSON type */
+  static readonly SUBTYPE_DEFAULT = 0;
+  /** Function BSON type */
+  static readonly SUBTYPE_FUNCTION = 1;
+  /** Byte Array BSON type */
+  static readonly SUBTYPE_BYTE_ARRAY = 2;
+  /** Deprecated UUID BSON type @deprecated Please use SUBTYPE_UUID */
+  static readonly SUBTYPE_UUID_OLD = 3;
+  /** UUID BSON type */
+  static readonly SUBTYPE_UUID = 4;
+  /** MD5 BSON type */
+  static readonly SUBTYPE_MD5 = 5;
+  /** User BSON type */
+  static readonly SUBTYPE_USER_DEFINED = 128;
+
+  buffer!: Buffer;
+  sub_type!: number;
+  position!: number;
+
+  /**
+   * @param buffer - a buffer object containing the binary data.
+   * @param subType - the option binary type.
+   */
+  constructor(buffer?: string | BinarySequence, subType?: number) {
+    if (!(this instanceof Binary)) return new Binary(buffer, subType);
+
+    if (
+      !(buffer == null) &&
+      !(typeof buffer === 'string') &&
+      !ArrayBuffer.isView(buffer) &&
+      !(buffer instanceof ArrayBuffer) &&
+      !Array.isArray(buffer)
+    ) {
+      throw new TypeError(
+        'Binary can only be constructed from string, Buffer, TypedArray, or Array<number>'
+      );
+    }
+
+    this.sub_type = subType ?? Binary.BSON_BINARY_SUBTYPE_DEFAULT;
+
+    if (buffer == null) {
+      // create an empty binary buffer
+      this.buffer = Buffer.alloc(Binary.BUFFER_SIZE);
+      this.position = 0;
+    } else {
+      if (typeof buffer === 'string') {
+        // string
+        this.buffer = Buffer.from(buffer, 'binary');
+      } else if (Array.isArray(buffer)) {
+        // number[]
+        this.buffer = Buffer.from(buffer);
+      } else {
+        // Buffer | TypedArray | ArrayBuffer
+        this.buffer = ensureBuffer(buffer);
+      }
+
+      this.position = this.buffer.byteLength;
+    }
+  }
+
+  /**
+   * Updates this binary with byte_value.
+   *
+   * @param byteValue - a single byte we wish to write.
+   */
+  put(byteValue: string | number | Uint8Array | Buffer | number[]): void {
+    // If it's a string and a has more than one character throw an error
+    if (typeof byteValue === 'string' && byteValue.length !== 1) {
+      throw new TypeError('only accepts single character String');
+    } else if (typeof byteValue !== 'number' && byteValue.length !== 1)
+      throw new TypeError('only accepts single character Uint8Array or Array');
+
+    // Decode the byte value once
+    let decodedByte: number;
+    if (typeof byteValue === 'string') {
+      decodedByte = byteValue.charCodeAt(0);
+    } else if (typeof byteValue === 'number') {
+      decodedByte = byteValue;
+    } else {
+      decodedByte = byteValue[0];
+    }
+
+    if (decodedByte < 0 || decodedByte > 255) {
+      throw new TypeError('only accepts number in a valid unsigned byte range 0-255');
+    }
+
+    if (this.buffer.length > this.position) {
+      this.buffer[this.position++] = decodedByte;
+    } else {
+      const buffer = Buffer.alloc(Binary.BUFFER_SIZE + this.buffer.length);
+      // Combine the two buffers together
+      this.buffer.copy(buffer, 0, 0, this.buffer.length);
+      this.buffer = buffer;
+      this.buffer[this.position++] = decodedByte;
+    }
+  }
+
+  /**
+   * Writes a buffer or string to the binary.
+   *
+   * @param sequence - a string or buffer to be written to the Binary BSON object.
+   * @param offset - specify the binary of where to write the content.
+   */
+  write(sequence: string | BinarySequence, offset: number): void {
+    offset = typeof offset === 'number' ? offset : this.position;
+
+    // If the buffer is to small let's extend the buffer
+    if (this.buffer.length < offset + sequence.length) {
+      const buffer = Buffer.alloc(this.buffer.length + sequence.length);
+      this.buffer.copy(buffer, 0, 0, this.buffer.length);
+
+      // Assign the new buffer
+      this.buffer = buffer;
+    }
+
+    if (ArrayBuffer.isView(sequence)) {
+      this.buffer.set(ensureBuffer(sequence), offset);
+      this.position =
+        offset + sequence.byteLength > this.position ? offset + sequence.length : this.position;
+    } else if (typeof sequence === 'string') {
+      this.buffer.write(sequence, offset, sequence.length, 'binary');
+      this.position =
+        offset + sequence.length > this.position ? offset + sequence.length : this.position;
+    }
+  }
+
+  /**
+   * Reads **length** bytes starting at **position**.
+   *
+   * @param position - read from the given position in the Binary.
+   * @param length - the number of bytes to read.
+   */
+  read(position: number, length: number): BinarySequence {
+    length = length && length > 0 ? length : this.position;
+
+    // Let's return the data based on the type we have
+    return this.buffer.slice(position, position + length);
+  }
+
+  /**
+   * Returns the value of this binary as a string.
+   * @param asRaw - Will skip converting to a string
+   * @remarks
+   * This is handy when calling this function conditionally for some key value pairs and not others
+   */
+  value(asRaw?: boolean): string | BinarySequence {
+    asRaw = !!asRaw;
+
+    // Optimize to serialize for the situation where the data == size of buffer
+    if (asRaw && this.buffer.length === this.position) {
+      return this.buffer;
+    }
+
+    // If it's a node.js buffer object
+    if (asRaw) {
+      return this.buffer.slice(0, this.position);
+    }
+    return this.buffer.toString('binary', 0, this.position);
+  }
+
+  /** the length of the binary sequence */
+  length(): number {
+    return this.position;
+  }
+
+  /** @internal */
+  toJSON(): string {
+    return this.buffer.toString('base64');
+  }
+
+  /** @internal */
+  toString(format: string): string {
+    return this.buffer.toString(format);
+  }
+
+  /** @internal */
+  toExtendedJSON(options?: EJSONOptions): BinaryExtendedLegacy | BinaryExtended {
+    options = options || {};
+    const base64String = this.buffer.toString('base64');
+
+    const subType = Number(this.sub_type).toString(16);
+    if (options.legacy) {
+      return {
+        $binary: base64String,
+        $type: subType.length === 1 ? '0' + subType : subType
+      };
+    }
+    return {
+      $binary: {
+        base64: base64String,
+        subType: subType.length === 1 ? '0' + subType : subType
+      }
+    };
+  }
+
+  /** @internal */
+  static fromExtendedJSON(
+    doc: BinaryExtendedLegacy | BinaryExtended | UUIDExtended,
+    options?: EJSONOptions
+  ): Binary {
+    options = options || {};
+    let data: Buffer | undefined;
+    let type;
+    if ('$binary' in doc) {
+      if (options.legacy && typeof doc.$binary === 'string' && '$type' in doc) {
+        type = doc.$type ? parseInt(doc.$type, 16) : 0;
+        data = Buffer.from(doc.$binary, 'base64');
+      } else {
+        if (typeof doc.$binary !== 'string') {
+          type = doc.$binary.subType ? parseInt(doc.$binary.subType, 16) : 0;
+          data = Buffer.from(doc.$binary.base64, 'base64');
+        }
+      }
+    } else if ('$uuid' in doc) {
+      type = 4;
+      data = Buffer.from(parseUUID(doc.$uuid));
+    }
+    if (!data) {
+      throw new TypeError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
+    }
+    return new Binary(data, type);
+  }
+
+  /** @internal */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.inspect();
+  }
+
+  inspect(): string {
+    const asBuffer = this.value(true);
+    return `new Binary(Buffer.from("${asBuffer.toString('hex')}", "hex"), ${this.sub_type})`;
+  }
+}
+
+Object.defineProperty(Binary.prototype, '_bsontype', { value: 'Binary' });

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,61 @@
+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) {
+    if (!(this instanceof Code)) return new Code(code, scope);
+
+    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 `new Code("${codeJson.code}"${
+      codeJson.scope ? `, ${JSON.stringify(codeJson.scope)}` : ''
+    })`;
+  }
+}
+
+Object.defineProperty(Code.prototype, '_bsontype', { value: 'Code' });