# mongodb/js-bson architecture

> Architecture diagram of the GitHub repository mongodb/js-bson, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mongodb/js-bson
- Repository: https://github.com/mongodb/js-bson

## Overview

##### Main Components

a) Core BSON Processing Layer:
- Serializer component
- Deserializer component
- Parser utilities
- On-demand parsing system

b) Data Type Handlers:
- Primitive types (Binary, Boolean, Double, Int32, etc.)
- Complex types (ObjectId, Timestamp, Decimal128, etc.)
- Extended JSON support

c) Platform-Specific Implementations:
- Node.js specific utilities
- Web/Browser utilities
- React Native support

**┌─────────────────────────────────────────────────────────────┐**
- Client Applications                      │
- ┬─────────────────┬────────────────┬─────────┘

**┌───────────────▼─────┐   ┌──────▼───────┐ ┌─────▼──────────┐**
- Node.js Bundle   │   │  Web Bundle  │ │   RN Bundle    │
- ┬─────┘   └──────┬───────┘ └─────┬──────────┘

**┌───────────────▼──────────────▼──────────────────▼───────────┐**
- BSON Core Layer                          │
- ┌─────────────┐ ┌────────────┐ ┌────────────────────┐     │
- Serializer  │ │Deserializer│ │  Parser Utilities  │     │
- ┘ └────────────┘ └────────────────────┘     │

- ┌─────────────────────────┐    ┌───────────────────────┐  │
- Type System Layer     │    │   Extended JSON Layer  │  │
- ┌─────────┐ ┌─────────┐│    │                       │  │
- Primitive│ │Complex  ││    │ ┌─────────┐┌────────┐ │  │
- Types   │ │ Types   ││    │ │Parse    ││Stringify│ │  │
- ┘ └─────────┘│    │ └─────────┘└────────┘ │  │
- ┘    └───────────────────────┘  │
- ┘

##### Key Relationships
- One-way flow from parser utilities to both serializer and deserializer
- Platform-specific utilities feeding into core components
- Extended JSON conversion pathways

##### Important Implementation Details to Note
- Separation between sync and async operations
- Error handling pathways
- Polyfill requirements for different platforms
- EJSON conversion layer

##### Performance-Critical Paths
- On-demand parsing system
- Optimized byte handling routines
- Buffer management paths

This architecture should clearly show how the system maintains compatibility with the BSON specification while providing optimized implementations for different JavaScript environments.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Applications"]
        NodeApp["Node.js Application"]
        WebApp["Web Application"]
        RNApp["React Native Application"]
    end

    subgraph Bundles["Platform-Specific Bundles"]
        NodeBundle["Node.js Bundle"]:::platform
        WebBundle["Web Bundle"]:::platform
        RNBundle["React Native Bundle"]:::platform
    end

    subgraph Core["BSON Core Layer"]
        direction TB
        Serializer["Serializer"]:::core
        Deserializer["Deserializer"]:::core
        ParserUtils["Parser Utilities"]:::core
        OnDemand["On-demand Parser"]:::core
        ByteUtils["Byte Processing"]:::core
        ErrorHandler["Error Handling"]:::core
        Constants["Core Constants"]:::core
    end

    subgraph Types["Type System Layer"]
        direction TB
        subgraph PrimitiveTypes["Primitive Types"]
            Binary["Binary"]:::type
            Double["Double"]:::type
            Int32["Int32"]:::type
            Boolean["Boolean"]:::type
        end

        subgraph ComplexTypes["Complex Types"]
            ObjectId["ObjectId"]:::type
            Timestamp["Timestamp"]:::type
            Decimal128["Decimal128"]:::type
            Code["Code"]:::type
            DBRef["DBRef"]:::type
        end
    end

    subgraph Platform["Platform Utilities"]
        NodeUtils["Node.js Utils"]:::platform
        WebUtils["Web/Browser Utils"]:::platform
    end

    subgraph EJSON["Extended JSON Layer"]
        EJSONParse["Parse"]:::ejson
        EJSONStringify["Stringify"]:::ejson
    end

    %% Connections
    NodeApp --> NodeBundle
    WebApp --> WebBundle
    RNApp --> RNBundle

    NodeBundle --> NodeUtils
    WebBundle --> WebUtils
    RNBundle --> WebUtils

    NodeUtils --> ByteUtils
    WebUtils --> ByteUtils

    ByteUtils --> Serializer
    ByteUtils --> Deserializer

    Serializer --> PrimitiveTypes
    Serializer --> ComplexTypes
    Deserializer --> PrimitiveTypes
    Deserializer --> ComplexTypes

    ParserUtils --> Serializer
    ParserUtils --> Deserializer
    OnDemand --> Deserializer

    EJSONParse --> Types
    Types --> EJSONStringify

    ErrorHandler --> Core
    Constants --> Core

    %% Styles
    classDef core fill:#a8e6cf
    classDef platform fill:#dcedc1
    classDef type fill:#ffd3b6
    classDef ejson fill:#ffaaa5

    %% Click events
    click Serializer "https://github.com/mongodb/js-bson/blob/main/src/parser/serializer.ts"
    click Deserializer "https://github.com/mongodb/js-bson/blob/main/src/parser/deserializer.ts"
    click ParserUtils "https://github.com/mongodb/js-bson/blob/main/src/parser/utils.ts"
    click OnDemand "https://github.com/mongodb/js-bson/tree/main/src/parser/on_demand/"
    click EJSONParse "https://github.com/mongodb/js-bson/blob/main/src/extended_json.ts"
    click EJSONStringify "https://github.com/mongodb/js-bson/blob/main/src/extended_json.ts"
    click NodeUtils "https://github.com/mongodb/js-bson/blob/main/src/utils/node_byte_utils.ts"
    click WebUtils "https://github.com/mongodb/js-bson/blob/main/src/utils/web_byte_utils.ts"
    click Binary "https://github.com/mongodb/js-bson/blob/main/src/binary.ts"
    click Double "https://github.com/mongodb/js-bson/blob/main/src/double.ts"
    click Int32 "https://github.com/mongodb/js-bson/blob/main/src/int_32.ts"
    click Boolean "https://github.com/mongodb/js-bson/blob/main/src/boolean.ts"
    click ObjectId "https://github.com/mongodb/js-bson/blob/main/src/objectid.ts"
    click Timestamp "https://github.com/mongodb/js-bson/blob/main/src/timestamp.ts"
    click Decimal128 "https://github.com/mongodb/js-bson/blob/main/src/decimal128.ts"
    click Code "https://github.com/mongodb/js-bson/blob/main/src/code.ts"
    click DBRef "https://github.com/mongodb/js-bson/blob/main/src/db_ref.ts"
    click ErrorHandler "https://github.com/mongodb/js-bson/blob/main/src/error.ts"
    click Constants "https://github.com/mongodb/js-bson/blob/main/src/constants.ts"
    click ByteUtils "https://github.com/mongodb/js-bson/blob/main/src/utils/byte_utils.ts"
```
