Mongous

Yet another mongo wrapper library.

Features

A light library that depends only on the mongo driver and bson, except for built-in and standard attachments.
Document item constraints can be described in Array, Range, Regexp, Proc instances, or base classes.
Check if the constraint conditions are met when saving the document.
Check if the constraint condition is satisfied when setting the item value of the document.
The contents of undefined items in the document can be described by value or Proc.
Item contents at the time of document creation and update can be described by value or Proc.
The database collection name corresponding to the class name is not converted to the plural form.

Installation

Add this line to your application’s Gemfile:

gem 'mongous'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install mongous
or
$ gem install -l mongous-x.x.x.gem

Usage

Simple declaration

require  "mongous"

Mongous.document!  :Book

Detail declaration

require  "mongous"

Mongous.connect!  ["localhost:27017"], database: "test"

class Book
  include  Mongous::Document

  field  :title,      String,   :must
  field  :author,     String
  field  :publisher,  String
  field  :style,      String,   %w[hardcover softcover paperback]
  field  :size,       String,   /[AB]\d/
  field  :price,      Integer,  (0..1_000_000)
  field  :page,       Integer,  proc{ page % 4 == 0 }
  field  :isbn,       String,   proc{ isbn? }
  field  :lang,       String,   default: "en"
  field  :created_at, Time,     create: proc{ Time.now }
  field  :updated_at, Time,     update: proc{ Time.now }

  filter :foobar,     {title: /foobar/}

  verify :strict
  verify do
    having?(author) | having?(publisher)
  end

  def isbn?
    isbn.gsub(/[\D]*/, '').size == 13
  end

  index  :title
end

Create document

book = Book.new
book.title = "title 1"
book.price = 1000
book.size = "A4"
book.save

book = Book.new( title: "title 2", price: 2000, size: "A5" )
book.save

doc = { title: "title 3", price: 3000, size: "A6" }
Book.create( **doc )

Search document

pp books = Book.all

p book = Book.where( title: /title/ ).first
p book = Book.where( title: /title/ ).last

books = Book.where( title: /title/ ).all
books.each do |book|
  p book
end

Book.where( title: /title/ ).projection( _id: 0 ).each do |book|
  p book
end

Book.where( price: (1..2000), size: ["A4","A5"] ).each do |book|
  p book
end

filter1 = Book.where( title: /title/ )
filter2 = Book.where( :foobar )
filter3 = Book.where( price: (1..2000) )
filter4 = Book.where( size: ["A4","A5"] )

Book.not( filter1 ).each do |book|
  p book
end
Book.and( filter1, filter3 ).each do |book|
  p book
end
Book.or( filter2, filter4 ).each do |book|
  p book
end

Book.find( { title: /title/ }, { projection: {_id: 0} } ).each do |book|
  p book
end

Book.where( title: /title/ ).select( _id: 0 ).each do |book|
  p book
end

Book.select( _id: 0 )[0, 5].each do |book|
  p book
end

pp Book.select( :title, :price, :size )[5, 5].all

Update document

book = Book.where( title: "title 1" ).first
book.title = "title 1 [update]"
book.save

Delete document

book = Book.where( title: "title 1" ).first
book.delete

Reference

Connect default database.

Mongous.connect!( hosts_or_uri = nil, **options )

Result:
- nil.
Parameter:
- hosts_or_uri: Array of hosts, or URI (default: ["localhost:21017"])
- options: Options.
  - file: Path to database configuration file.
  - mode: Execution mode. (default: "development")
  - database: Database name. (default: "test")
  - Other optional arguments for Mongo::Client.new.

Connect database.

Mongous.connect( hosts_or_uri = nil, **options )

Result:
- Mongo::Client instance.

Define collection operate class with default settings.

Mongous.document!( *names, **options )

Result:
- nil.
Parameter:
- names: Collection names. (String or Symbol)
- options: Options.
  - timestamp: If true then add fields :created_at, :updated_at.

Include document functions into collection operate class.

include Mongous::Document

Bind another database.

self.client=( client )

Result:
- Mongo::Client instance.
Parameter:
- client: Mongo::Client instance.

Get binded database.

self.client

Result:
- Mongo::Client instance.
Parameter:
- None.

Bind another collection.

self.collection_name=( _collection_name )

Result:
- Collection name string.
Parameter:
- collection_name: Collection name.

Get binded collection name.

self.collection_name

Result:
- Collection name string.
Parameter:
- None.

Get collection.

self.collection( collection_name = nil )

Result:
- Mongo::Collection instance.
Parameter:
- collection_name: Tempolary collection name.

Declare document structure.

self.field( symbol, *attrs, **items )

Parameter:
- symbol: Field name.
- attrs: Field attributes.
  - Class: Class for field verification.
  - Proc: Proc for field verification.
  - Range: Range for field verification.
  - Array: Array for field verification.
  - Symbol: Special directive symbol.
    
    must: Not nil nor empty.
- items: Operation when saving.
  - default: Value or proc when undefined.
  - create: Value or proc when saving a new document.
  - update: Value or proc when saving update document.

Verify before save or assignment action.

self.verify( *directives, &block )

Parameter:
- directives: Special directive symbol.
  - strict: Verify that it is a defined item name.
- block: Describe the content that verifies each item value and returns the truth.

Make index.

self.index( *symbols, **options )

Parameter:
- symbols: Field names.
- options: Options for Mongo::Collection#indexes().

Verify field value is not nil nor empty.

self.having?( label )

Result:
- Boolean
Parameter:
- label: Field label for method call.

Name the search condition.

self.filter( symbol, filter_or_cond )

Parameter:
- symbol: Filter name.
- filter_or_cond: Filter or search criteria.

Select output fields.

Mongous::Document.select( *keys, **kwargs )
Mongous::Filter#select( *keys, **kwargs )

Result:
- Mongous::Filter instance.
Parameter:
- keys: Field symbols.
- kwargs: Field symbols and values.

Search condition.

Mongous::Document.where( filter = nil, **conditions )
Mongous::Filter#where( filter = nil, **conditions )

Result:
- Mongous::Filter instance.
Parameter:
- filter: Filter name symbol, or filter instance.
- conditions: Search criteria.

NOT search condition.

Mongous::Document.not( filter = nil, **conditions )
Mongous::Filter#not( filter = nil, **conditions )

Result:
- Mongous::Filter instance.
Parameter:
- filter: Filter name symbol, or filter instance.
- conditions: Search criteria.

AND search condition.

Mongous::Document.and( *filters )
Mongous::Filter#and( *filters )

Result:
- Mongous::Filter instance.
Parameter:
- filters: Filter name symbol, or filter instance.

OR search condition.

Mongous::Document.or( *filters )
Mongous::Filter#or( *filters )

Result:
- Mongous::Filter instance.
Parameter:
- filters: Field name symbol, or filter instance.

Create document.

Mongous::Document.create( **doc )

Result:
- nil.
Parameter:
- doc: Keyword arguments.

Save document.

Mongous::Document#save

Result:
- nil.

Convert document to Hash.

Mongous::Document#to_hash

Result:
- Hash object.

Convert document to JSON.

Mongous::Document#to_json

Result:
- JSON String.

Read document field.

Mongous::Document#[]( field_name )
Mongous::Document#field_name

Result:
- field_value.
Parameter:
- field_name: Field name.

Write document field.

Mongous::Document#[]=( field_name, field_value )
Mongous::Document#field_name = field_value

Result:
- field_value.
Parameter:
- field_name: Field name.
- field_value: Field value.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/arimay/mongous.

License

The gem is available as open source under the terms of the MIT License.

mongous

Development

Runtime