BSON Data Types

/**
 * BSON ObjectId type for unique document identification
 */
class ObjectId {
  /** Create ObjectId from various input types */
  constructor(id?: string | number | ObjectId | ObjectIdLike | Uint8Array);
  
  /** Convert to 24-character hex string representation */
  toHexString(): string;
  
  /** Convert to string (same as toHexString) */
  toString(encoding?: 'hex' | 'base64'): string;
  
  /** Get JSON representation for Extended JSON */
  toJSON(): string;
  
  /** Check equality with another ObjectId */
  equals(otherId: string | ObjectId | ObjectIdLike): boolean;
  
  /** Extract timestamp from ObjectId */
  getTimestamp(): Date;
  
  /** Create ObjectId from timestamp */
  static createFromTime(timestamp: number): ObjectId;
  
  /** Create ObjectId from hex string */
  static createFromHexString(hexString: string): ObjectId;
  
  /** Create ObjectId from base64 string */
  static createFromBase64(base64: string): ObjectId;
  
  /** Validate if input can be converted to ObjectId */
  static isValid(id: string | number | ObjectId | ObjectIdLike | Uint8Array): boolean;
  
  /** Generate raw ObjectId bytes */
  static generate(timestamp?: number): Uint8Array;
  
  /** Raw 12-byte identifier */
  readonly id: Uint8Array;
  
  /** Generation time as number (deprecated, use getTimestamp()) */
  readonly generationTime: number;
}

interface ObjectIdLike {
  id: string | Uint8Array;
  toHexString(): string;
  __id?: string;
}

interface ObjectIdExtended {
  $oid: string;
}

import { ObjectId } from "bson";

// Create new ObjectId
const id = new ObjectId();
console.log(id.toHexString()); // "507f1f77bcf86cd799439011"

// Create from hex string
const fromHex = ObjectId.createFromHexString("507f1f77bcf86cd799439011");

// Create from base64 string (16 characters)
const fromBase64 = ObjectId.createFromBase64("UH8fd7z4bNeZQ5AR");

// Create from timestamp
const fromTime = ObjectId.createFromTime(Date.now() / 1000);
console.log(fromTime.getTimestamp()); // Date corresponding to timestamp

// Validation
console.log(ObjectId.isValid("507f1f77bcf86cd799439011")); // true
console.log(ObjectId.isValid("invalid")); // false

// Equality check
const id1 = new ObjectId();
const id2 = new ObjectId(id1.toHexString());
console.log(id1.equals(id2)); // true

/**
 * BSON Binary type for binary data storage
 */
class Binary {
  /** Create Binary from buffer and optional subtype */
  constructor(buffer?: BinarySequence, subType?: number);
  
  /** Write data to the binary buffer */
  put(byteValue: string | number | Uint8Array | number[]): void;
  
  /** Write sequence at specific offset */
  write(sequence: BinarySequence, offset: number): number;
  
  /** Read data from specific position */
  read(position: number, length: number): BinarySequence;
  
  /** Get binary value as string or raw bytes */
  value(asRaw?: boolean): string | Uint8Array;
  
  /** Get length of binary data */
  length(): number;
  
  /** Convert to JSON representation */
  toJSON(): string;
  
  /** Convert to string with encoding */
  toString(encoding?: 'hex' | 'base64'): string;
  
  /** Raw binary buffer */
  buffer: Uint8Array;
  
  /** Binary subtype identifier */
  sub_type: number;
  
  /** Current position in buffer */
  position: number;
  
  // Subtype constants
  static readonly SUBTYPE_DEFAULT: 0;
  static readonly SUBTYPE_FUNCTION: 1;
  static readonly SUBTYPE_BYTE_ARRAY: 2;
  static readonly SUBTYPE_UUID_OLD: 3;
  static readonly SUBTYPE_UUID: 4;
  static readonly SUBTYPE_MD5: 5;
  static readonly SUBTYPE_ENCRYPTED: 6;
  static readonly SUBTYPE_COLUMN: 7;
  static readonly SUBTYPE_SENSITIVE: 8;
  static readonly SUBTYPE_VECTOR: 9;
  static readonly SUBTYPE_USER_DEFINED: 128;
  
  // Vector type constants
  static readonly VECTOR_TYPE: {
    readonly Int8: 0x03;
    readonly Float32: 0x27;
    readonly PackedBit: 0x10;
  };
}

type BinarySequence = Uint8Array | number[];

interface BinaryExtended {
  $binary: {
    subType: string;
    base64: string;
  };
}

import { Binary } from "bson";

// Create from buffer
const data = new Uint8Array([1, 2, 3, 4, 5]);
const binary = new Binary(data, Binary.SUBTYPE_DEFAULT);

// Write and read operations
binary.put([6, 7, 8]);
const portion = binary.read(0, 3); // Read first 3 bytes

// Get as base64 string
const base64 = binary.value(); // Base64 encoded string
const raw = binary.value(true); // Raw Uint8Array

// Specific subtypes
const uuid = new Binary(uuidBytes, Binary.SUBTYPE_UUID);
const encrypted = new Binary(encryptedData, Binary.SUBTYPE_ENCRYPTED);

/**
 * UUID type extending Binary for UUID-specific operations
 */
class UUID extends Binary {
  /** Create UUID from string, bytes, or another UUID */
  constructor(input?: string | Uint8Array | UUID);
  
  /** Generate random UUID */
  static generate(): UUID;
  
  /** Validate UUID input */
  static isValid(input: string | Uint8Array | UUID): boolean;
  
  /** Convert to hex string with optional dashes */
  toHexString(includeDashes?: boolean): string;
  
  /** Convert to Binary with UUID subtype */
  toBinary(): Binary;
}

interface UUIDExtended {
  $uuid: string;
}

import { UUID } from "bson";

// Generate new UUID
const uuid = UUID.generate();
console.log(uuid.toHexString(true)); // "550e8400-e29b-41d4-a716-446655440000"

// Create from string
const fromString = new UUID("550e8400-e29b-41d4-a716-446655440000");

// Validation
console.log(UUID.isValid("550e8400-e29b-41d4-a716-446655440000")); // true
console.log(UUID.isValid("invalid-uuid")); // false

/**
 * 64-bit integer type for precise large number handling
 */
class Long {
  /** Create Long from various input types */
  constructor(low?: number | bigint | string, high?: number | boolean, unsigned?: boolean);
  
  /** Convert to JavaScript number (may lose precision) */
  toNumber(): number;
  
  /** Convert to native BigInt */
  toBigInt(): bigint;
  
  /** Convert to string representation */
  toString(radix?: number): string;
  
  /** Get JSON representation */
  toJSON(): string;
  
  /** Get primitive number value */
  valueOf(): number;
  
  // Arithmetic operations
  add(addend: string | number | Long): Long;
  subtract(subtrahend: string | number | Long): Long;
  multiply(multiplier: string | number | Long): Long;
  divide(divisor: string | number | Long): Long;
  modulo(divisor: string | number | Long): Long;
  negate(): Long;
  
  // Comparison operations
  compare(other: string | number | Long): number;
  equals(other: string | number | Long): boolean;
  lessThan(other: string | number | Long): boolean;
  greaterThan(other: string | number | Long): boolean;
  
  // Bitwise operations
  and(other: string | number | Long): Long;
  or(other: string | number | Long): Long;
  xor(other: string | number | Long): Long;
  not(): Long;
  shiftLeft(numBits: number): Long;
  shiftRight(numBits: number): Long;
  
  /** Low 32 bits */
  readonly high: number;
  
  /** High 32 bits */
  readonly low: number;
  
  /** Whether the Long is unsigned */
  readonly unsigned: boolean;
  
  // Static creation methods
  static fromBigInt(value: bigint, unsigned?: boolean): Long;
  static fromBits(lowBits: number, highBits: number, unsigned?: boolean): Long;
  static fromInt(value: number, unsigned?: boolean): Long;
  static fromNumber(value: number, unsigned?: boolean): Long;
  static fromString(str: string, unsigned?: boolean | number, radix?: number): Long;
  static fromValue(val: number | string | Long | { low: number; high: number; unsigned?: boolean }): Long;
  static isLong(obj: unknown): obj is Long;
  
  // Constants
  static readonly ZERO: Long;
  static readonly ONE: Long;
  static readonly NEG_ONE: Long;
  static readonly MAX_VALUE: Long;
  static readonly MIN_VALUE: Long;
  static readonly MAX_UNSIGNED_VALUE: Long;
}

interface LongExtended {
  $numberLong: string;
}

import { Long } from "bson";

// Create from string for precision
const bigNumber = Long.fromString("9223372036854775807");

// Arithmetic operations
const a = Long.fromNumber(100);
const b = Long.fromNumber(50);
const sum = a.add(b);
const product = a.multiply(b);

// Comparison
console.log(bigNumber.greaterThan(Long.MAX_VALUE.divide(2))); // true

// Convert to different formats
console.log(bigNumber.toString()); // "9223372036854775807"
console.log(bigNumber.toBigInt()); // 9223372036854775807n

// Bitwise operations
const masked = bigNumber.and(0xFF); // Get low 8 bits
const shifted = bigNumber.shiftRight(8); // Shift right by 8 bits

/**
 * 128-bit decimal floating point for precise decimal calculations
 */
class Decimal128 {
  /** Create from 16-byte buffer */
  constructor(bytes: Uint8Array);
  
  /** Create from string representation */
  static fromString(representation: string): Decimal128;
  
  /** Create from string with rounding options */
  static fromStringWithRounding(
    representation: string, 
    options?: { roundingMode?: string }
  ): Decimal128;
  
  /** Convert to string representation */
  toString(): string;
  
  /** Get JSON representation */
  toJSON(): { $numberDecimal: string };
  
  /** Raw 16-byte representation */
  readonly bytes: Uint8Array;
}

interface Decimal128Extended {
  $numberDecimal: string;
}

import { Decimal128 } from "bson";

// Create from string for precision
const price = Decimal128.fromString("19.99");
const tax = Decimal128.fromString("0.08875");

// Use in documents
const product = {
  name: "Widget",
  price: price,
  taxRate: tax
};

console.log(price.toString()); // "19.99"
console.log(price.toJSON()); // { $numberDecimal: "19.99" }

/**
 * MongoDB internal timestamp type
 */
class Timestamp {
  /** Create timestamp from low/high values */
  constructor(low?: number | bigint | Long, high?: number | boolean);
  
  /** Convert to integer representation */
  toInt(): number;
  
  /** Convert to number */
  toNumber(): number;
  
  /** Convert to string */
  toString(radix?: number): string;
  
  /** Get JSON representation */
  toJSON(): { $timestamp: { t: number; i: number } };
  
  /** Check equality with another timestamp */
  equals(timestamp: Timestamp): boolean;
  
  /** Compare with another timestamp */
  compare(timestamp: Timestamp): number;
  
  /** High 32 bits (timestamp) */
  readonly high: number;
  
  /** Low 32 bits (increment) */
  readonly low: number;
  
  // Static creation methods
  static fromInt(value: number): Timestamp;
  static fromNumber(value: number): Timestamp;
  static fromBits(lowBits: number, highBits: number): Timestamp;
  static fromString(str: string, optRadix?: number): Timestamp;
}

interface TimestampExtended {
  $timestamp: {
    t: number;
    i: number;
  };
}

import { Timestamp } from "bson";

// Create timestamp
const ts = new Timestamp(1, Math.floor(Date.now() / 1000));

// From current time
const now = Timestamp.fromNumber(Date.now());

// Comparison
const earlier = Timestamp.fromNumber(Date.now() - 1000);
console.log(now.compare(earlier)); // 1 (now is greater)

/**
 * IEEE 754 double precision wrapper
 */
class Double {
  /** Create from number value */
  constructor(value: number);
  
  /** Get JSON representation */
  toJSON(): { $numberDouble: string };
  
  /** Convert to string */
  toString(radix?: number): string;
  
  /** Get primitive number value */
  valueOf(): number;
  
  /** Wrapped number value */
  readonly value: number;
}

interface DoubleExtended {
  $numberDouble: string;
}

/**
 * 32-bit signed integer wrapper
 */
class Int32 {
  /** Create from number or string */
  constructor(value: number | string);
  
  /** Create from string */
  static fromString(value: string): Int32;
  
  /** Get JSON representation */
  toJSON(): { $numberInt: string };
  
  /** Convert to string */
  toString(radix?: number): string;
  
  /** Get primitive number value */
  valueOf(): number;
  
  /** Wrapped integer value */
  readonly value: number;
}

interface Int32Extended {
  $numberInt: string;
}

/**
 * BSON Regular Expression type
 */
class BSONRegExp {
  /** Create from pattern and options */
  constructor(pattern: string, options?: string);
  
  /** Get JSON representation */
  toJSON(): { $regularExpression: { pattern: string; options: string } };
  
  /** Regular expression pattern */
  readonly pattern: string;
  
  /** Regular expression options */
  readonly options: string;
}

interface BSONRegExpExtended {
  $regularExpression: {
    pattern: string;
    options: string;
  };
}

/**
 * BSON Symbol type (deprecated)
 */
class BSONSymbol {
  constructor(value: string);
  toString(): string;
  toJSON(): { $symbol: string };
  valueOf(): string;
  readonly value: string;
}

/**
 * BSON JavaScript code type
 */
class Code {
  constructor(code: string | Function, scope?: Document);
  toJSON(): { $code: string; $scope?: Document };
  readonly code: string;
  readonly scope?: Document;
}

/**
 * BSON Database Reference type
 */
class DBRef {
  constructor(collection: string, oid: ObjectId, db?: string, fields?: Document);
  static isDBRefLike(value: unknown): value is DBRefLike;
  toJSON(): DBRefLike & Document;
  readonly collection: string;
  readonly oid: ObjectId;
  readonly db?: string;
  readonly fields?: Document;
}

/**
 * BSON MinKey type (always compares as less than any other value)
 */
class MinKey {
  constructor();
  toJSON(): { $minKey: 1 };
}

/**
 * BSON MaxKey type (always compares as greater than any other value)
 */
class MaxKey {
  constructor();
  toJSON(): { $maxKey: 1 };
}

interface DBRefLike {
  $ref: string;
  $id: ObjectId;
  $db?: string;
}