npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

albatross

v4.0.0

Published

Albatross is a small library that makes accessing MongoDB from Node.js a breeze. It's goal is to be a thin wrapper that enables you to forget about connection state and get right to accessing your data.

Downloads

292

Readme

Albatross

Albatross is a small library that makes accessing MongoDB from Node.js a breeze. It's goal is to be a thin wrapper that enables you to forget about connection state and get right to accessing your data.

Installation

npm install --save albatross

Usage

import albatross from 'albatross'
import fs from 'node:fs'

const db = albatross('mongodb://localhost/test')
const user = db.collection('user')

await user.insert({ name: 'Linus', born: 1992 })
await user.insert({ name: 'Steve', born: 1955 })

const doc = await user.findOne({ born: 1992 })
console.log('Hello ' + doc.name)
//=> Hello Linus

const grid = db.grid()

const input = fs.createReadStream('readme.md')
const opts = { filename: 'readme.md', contentType: 'text/plain' }

const id = await grid.upload(input, opts)
const result = await grid.download(id)

result.filename // 'readme.md'
result.contentType // 'text/plain'

result.stream.pipe(process.stdout)

You can start querying the database right away, as soon as a connection is established it will start sending your commands to the server.

API

Module

The module default exports a single function to create a new Albatross instance. It also exports the BSON Binary API as named exports.

albatross(uri)

Creates a new instance of Albatross and connect to the specified uri.

Note: Albatross creates the MongoDB client with ignoreUndefined: true, which means that undefined values will not be stored in the database. This is the new default in the BSON library, and is also how the standard JSON.stringify works.

BSON Binary API

The following functions are exported from the module:

Binary
Code
Decimal128
Double
Int32
Long
MaxKey
MinKey
ObjectId
Timestamp

Albatross

.collection(name)

Returns a new instance of Collection bound to the collection named name.

.grid([name])

Returns a new instance of Grid, optionally using the supplied name as the name of the root collection.

.id(strOrObjectId)

Makes sure that the given argument is an ObjectId.

.ping([timeout]): Promise<void>

Send the ping command to the server, to check that the connection is still intact.

Optionally accepts a timeout in milliseconds.

.transaction(fn): Promise

Runs a provided function within a transaction, retrying either the commit operation or entire transaction as needed (and when the error permits) to better ensure that the transaction can complete successfully.

Example:

const user = db.collection('user')

const result = await db.transaction(async (session) => {
    await user.insert({ name: 'Linus', born: 1992 }, { session })
    await user.insert({ name: 'Steve', born: 1955 }, { session })

    return await user.findOne({ born: 1992 }, { session })
})

console.log('Hello ' + result.name)
//=> Hello Linus

.close(): Promise<void>

Closes the connection to the server.

Collection

.id(strOrObjectId)

Makes sure that the given argument is an ObjectId.

findOne(query[, opts]): Promise<object>

Find the first document that matches query.

find(query[, opts]): Promise<object[]>

Find all records that matches query.

count(query[, opts]): Promise<number>

Count number of documents matching the query.

distinct(key[, query[, opts]]): Promise<any[]>

Finds a list of distinct values for the given key.

note: if you specify opts you also need to specify query

exists(query): Promise<boolean>

Check if at least one document is matching the query.

insert(docs[, opts]): Promise<object | object[]>

Inserts a single document or a an array of documents.

The Promise will resolve with the documents that was inserted. When called with an object instead of an array as the first argument, the Promise resolves with an object instead of an array as well.

Note: Contrary to the standard MongoDB Node.js driver, this function will not modify any objects that are passed in. Instead, the returned documents from this function are what was saved in the database.

findOneAndUpdate(filter, update[, opts]): Promise<object>

Finds a document and updates it in one atomic operation.

By default, the document before the update is returned. To return the document after the update, pass returnDocument: 'after' in the options.

updateOne(filter, update[, opts]): Promise<UpdateResult>

Updates a single document matching filter. Resolves with an object with the following properties:

  • matched: Number of documents that matched the query
  • modified: Number of documents that was modified

updateMany(filter, update[, opts]): Promise<UpdateResult>

Updates multiple documents matching filter. Resolves with an object with the following properties:

  • matched: Number of documents that matched the query
  • modified: Number of documents that was modified

deleteOne(filter[, opts]): Promise<number>

Deletes a single document matching filter. Resolves with the number of documents deleted.

deleteMany(filter[, opts]): Promise<number>

Deletes multiple documents matching filter. Resolves with the number of documents deleted.

aggregate(pipeline[, opts]): Promise<object[]>

Executes an aggregation framework pipeline against the collection. Resolves with the aggregated objects.

Grid

id(strOrObjectId)

Makes sure that the given argument is an ObjectId.

upload(stream[, opts]): Promise<FileInfo>

Store the stream as a file in the grid store, opts is a object with the following properties. All options are optionally.

  • filename: The value of the filename key in the files doc
  • chunkSizeBytes: Overwrite this bucket's chunkSizeBytes for this file
  • metadata: Object to store in the file document's metadata field
  • contentType: String to store in the file document's contentType field
  • aliases: Array of strings to store in the file document's aliases field

The FileInfo object has the following properties:

  • id: The id of the file
  • length: The length of the file
  • chunkSize: The size of each chunk in bytes
  • filename: The value of the filename key in the files doc
  • metadata: An object with the metadata associated with the file
  • contentType: The value of the contentType key in the files doc

download(id): Promise<FileInfo>

Get the file with the specified id from the grid store. The Promise will resolve with an object with the following properties. If no file with the indicated id was found, the Promise will resolve to null.

  • id: The id of the file
  • length: The length of the file
  • chunkSize: The size of each chunk in bytes
  • filename: The value of the filename key in the files doc
  • metadata: An object with the metadata associated with the file
  • contentType: The value of the contentType key in the files doc
  • stream: The stream with the data that was inside the file

delete(id): Promise<void>

Delete the file with the specified id from the grid store.

In depth documentation

For more in depth documentation please see the mongodb module which Albatross wraps, especially the Collection object.

Contributing

Pull requests are always welcome, please make sure to add tests and run mocha before submitting.

The tests requiers a MongoDB server running at localhost.

License

Albatross is licensed under the MIT license.