Overview

This package provides a thin type safe layer over the official mongodb driver package for NodeJS. It enables document models to be created with Sidewinder Types with each document strictly data checked via JSON schema prior to writing to MongoDB. In addition, this package provides automatic ObjectId and binary data encode and decode to and from MongoDB. This allows applications to treat Mongo identifiers as validated hex strings and Mongo Binary objects as Uint8Array.

License MIT

Contents

• Overview
• Example
• ObjectId
• Uint8Array

Example

TypeScript Example Link

The Sidewinder MongoDatabase provides a strict subset of the Mongo Db API. It accepts a Database schema as it's first argument and Db instance for its second. Callers can access a Type Safe Collection API that automatically validates documents based on the Sidewinder Types defined in the Database schema. For indexing MongoDB and specifying other configuration options, use the Db object.

import { Type, MongoDatabase } from '@sidewinder/mongo'
import { MongoClient } from 'mongodb'

// ---------------------------------------------------------
// MongoClient
// ---------------------------------------------------------

const client = new MongoClient('mongodb://localhost:27017/db')
await client.connect()

// ---------------------------------------------------------
// Database Schematic
// ---------------------------------------------------------

const User = Type.Object({
  _id: Type.ObjectId(),
  name: Type.String(),
  email: Type.String({ format: 'email' }),
  created: Type.Integer(),
  updated: Type.Integer(),
})

const Record = Type.Object({
  _id: Type.ObjectId(),
  _user_id: Type.ObjectId(),
  created: Type.Integer(),
  updated: Type.Integer(),
  value: Type.Number(),
})

const Schema = Type.Database({
  users: User,
  records: Record,
})

// ---------------------------------------------------------
// Database
// ---------------------------------------------------------

const database = new MongoDatabase(Schema, client.db())

// ---------------------------------------------------------
// Insert
// ---------------------------------------------------------

const user_id = database.id()

await database.collection('users').insertOne({
  _id: user_id,
  name: 'dave',
  email: '[email protected]',
  created: Date.now(),
  updated: Date.now(),
})

await database.collection('records').insertMany([
  {
    _id: database.id(),
    _user_id: user_id,
    created: Date.now(),
    updated: Date.now(),
    value: 0,
  },
  {
    _id: database.id(),
    _user_id: user_id,
    created: Date.now(),
    updated: Date.now(),
    value: 1,
  },
])

// ---------------------------------------------------------
// Update
// ---------------------------------------------------------

await database.collection('users').updateOne(
  { _id: user_id },
  {
    email: '[email protected]',
    updated: Date.now(),
  },
)

// ---------------------------------------------------------
// Find
// ---------------------------------------------------------

const user = await database.collection('users').findOne({ _id: user_id })

// ---------------------------------------------------------
// Iterate
// ---------------------------------------------------------

for await (const user of database.collection('users').find({}).skip(0).take(10)) {
  // ...
}

// ---------------------------------------------------------
// Delete
// ---------------------------------------------------------

await database.collection('users').deleteOne({ _id: user_id })

ObjectId

Sidewinder Mongo does not use the MongoDB ObjectId to read and write _id fields to Mongo. Rather it detects the format of string values and automatically encodes to and from ObjectId. This allows ObjectId values to be transmitted across a network as strings without additional encoding to and from this type.

const User = Type.Object({
  _id:  Type.ObjectId() // Is a string regex string validated for 24 character hex strings values
  name: Type.String()
})

const Schema = Type.Database({
  users: User
})

const database = new MongoDatabase(Schema, Db)

database.collection('users').insertOne({
  _id: database.id(),  // Generates a new 24 character hex string
  name: 'dave'
})

Uint8Array

Sidewinder Mongo supports automatic encode and decode of JavaScript Uint8Array buffers only. This can be used to read and write binary property values into Mongo.

const ImageSegment = Type.Object({
  _id: Type.ObjectId()    // Is a string regex string validated for 24 character hex strings values
  data: Type.Uint8Array()
})
const Schema = Type.Database({
  imageSegments: ImageSegment
})

const database = new MongoDatabase(Schema, Db)

database.collection('imageSegments').insertOne({
  _id:  database.id(),        // Generates a new 24 character hex string
  data: new Uint8Array(16384) // 16K image segment
})