opal-pouchdb 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3c84d1d843149bb0d58c39411237a37846881524
+  data.tar.gz: f6a923fd1df134a6c2c31cdf38a34ebaf6970527
+SHA512:
+  metadata.gz: 3879fab123704c625967452763fcccf51ee5d7e5b2f1393a2ef360f162960f319a84abd648e3bc439a1ec12e1dd2ffe8f469a572047f7ee63cd098f5d0773df8
+  data.tar.gz: d286d7489c7a41de8688216468be1dbd458de75fd97220fd96ea9ae3de42165e155ca6b3ea07a4629f1ff533ca43d4de6f054ed76e7ba364f2439097e9117355

data/.gitignore

@@ -0,0 +1,6 @@
+.ruby-version
+.DS_Store
+.bundle/
+Gemfile.lock
+doc/
+.yardoc

data/.travis.yml

@@ -0,0 +1,6 @@
+language:
+  - ruby
+rvm:
+  - 1.9.3
+  - 2.1.5
+  - 2.2.1

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2015 by Vitor Capela 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,45 @@
+# opal-pouchdb: A PouchDB Wrapper for Opal
+
+[![Build Status](https://travis-ci.org/dodecaphonic/opal-pouchdb.svg?branch=master)](https://travis-ci.org/dodecaphonic/opal-pouchdb)
+[![Code Climate](https://codeclimate.com/github/dodecaphonic/opal-pouchdb/badges/gpa.svg)](https://codeclimate.com/github/dodecaphonic/opal-pouchdb)
+
+opal-pouchdb allows [PouchDB][pouchdb] databases to be used with a nice Ruby API.
+
+## Usage
+
+Basic usage follows [PouchDB's API][pouchdb-api] very closely. The major difference is that, in JavaScript, a developer may decide if she wishes get the results of her interactions with the database via callbacks or promises. In opal-pouchdb, everything returns an [Opal Promise][opal-promise], allowing your async code to be as composable as that abstraction allows.
+
+``` ruby
+db = PouchDB::Database.new("my_database")
+
+db.put(_id: "doc-1", summary: "Awesome", text: "Cake").then
+  db.get("doc-1")
+end.then do |db_record|
+  puts db_record # => { "_id" => "doc-1", "_rev" => "some-large-string", "summary" => "Awesome", "text" => "Cake" }
+end
+```
+
+Every single CRUD operation is supported right now:
+
+- put
+- post
+- get
+- delete
+- all_docs
+- bulk_docs
+
+## TODO
+
+- Attachments
+- Querying
+- Views
+- Database info
+- Compaction
+- Revision diff
+- Events
+- Plugins
+- Debug mode
+
+[pouchdb]: http://pouchdb.com
+[pouchdb-api]: http://pouchdb.com/api.html
+[opal-promise]: http://opalrb.org/docs/promises/

data/Rakefile

@@ -0,0 +1,17 @@
+require "bundler"
+Bundler.require
+
+require "bundler/gem_tasks"
+require "opal/rspec/rake_task"
+
+require "yard"
+
+Opal::RSpec::RakeTask.new(:default) do |s|
+  s.index_path = "spec/pouchdb/index.html.erb"
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', "opal/**/*.rb"]   # optional
+  t.options = ['--any', '--extra', '--opts']    # optional
+  t.stats_options = ['--list-undoc']            # optional
+end

data/config.ru

@@ -0,0 +1,12 @@
+require "bundler"
+Bundler.require
+
+require "opal-rspec"
+Opal.append_path File.expand_path('../spec', __FILE__)
+
+run Opal::Server.new { |s|
+  s.main = "opal/rspec/sprockets_runner"
+  s.append_path "spec"
+  s.debug = false
+  s.index_path = "spec/pouchdb/index.html.erb"
+}

data/lib/opal-pouchdb.rb

@@ -0,0 +1 @@
+require "opal/pouchdb"

data/lib/opal/pouchdb.rb

@@ -0,0 +1,4 @@
+require "opal"
+require "opal/pouchdb/version"
+
+Opal.append_path File.expand_path("../../../opal", __FILE__)

data/lib/opal/pouchdb/version.rb

@@ -0,0 +1,5 @@
+module Opal
+  module PouchDB
+    VERSION = "0.1.1"
+  end
+end

data/opal-pouchdb.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/opal/pouchdb/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name         = "opal-pouchdb"
+  s.version      = Opal::PouchDB::VERSION
+  s.author       = "Vitor Capela"
+  s.email        = "dodecaphonic@gmail.com"
+  s.homepage     = "https://github.com/dodecaphonic/opal-pouchdb"
+  s.summary      = "Opal bridge to PouchDB"
+  s.description  = "An Opal bridge to the PouchDB database library"
+
+  s.files          = `git ls-files`.split("\n")
+  s.executables    = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.test_files     = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths  = ["lib"]
+
+  s.add_runtime_dependency "opal", ">= 0.7.0", "< 0.9.0"
+  s.add_development_dependency "opal-rspec", "~> 0.4.0"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "rake"
+end

data/opal/opal-pouchdb.rb

@@ -0,0 +1,95 @@
+require "native"
+require "promise"
+
+module PouchDB
+  require "pouchdb/conversion"
+  require "pouchdb/database"
+  require "pouchdb/all_documents"
+  require "pouchdb/row"
+  require "pouchdb/event_emitter"
+  require "pouchdb/replication"
+
+  # Replicate data from source to target. Both the source and target can be a
+  # PouchDB instance or a string representing a CouchDB database URL or the name
+  # of a local PouchDB database. If `options.live` is true, then this will track
+  # future changes and also replicate them automatically. This method returns an
+  # object with the method `cancel()`, which you call if you want to cancel live
+  # replication.
+  #
+  # Replication is an event emitter like changes() and emits the "complete",
+  # "active", "paused", "change", "denied" and "error" events.
+  #
+  # Example:
+  #
+  #   stream = PouchDB.replicate("mydb", "http://localhost:5984/mydb",
+  #                              live: true, retry: true)
+  #           .on "change" do
+  #             # ...
+  #           end.on "paused" do
+  #             # ...
+  #           end # ...
+  #
+  #  stream.cancel
+  #
+  # @param source [String, Database] A source database, local or URL
+  # @param target [String, Database] A target database, local or URL
+  # @param options [Hash] Optional arguments, defaulting to `false` unless
+  #   specified
+  #
+  # @option options [Boolean] live If `true`, starts subscribing to future
+  #   changes in the `source` database and continue replicating them
+  # @option options [Boolean] retry If `true`, will attempt to retry
+  #   replications in the case of failure (due to being offline), using a
+  #   backoff algorithm that retries at longer and longer intervals until
+  #   a connection is re-established. Only applicable if `live: true`
+  # @option options [String] filter References a filter function from a
+  #   design document to selectively get upgrades
+  # @option options [Hash] query parameters to send to the filter function
+  # @option options [Array<String>] doc_ids Only replicate docs with these
+  #   ids
+  # @option options [Fixnum] since Replicate changes after the given
+  #   sequence number
+  # @option options [Boolean] create_target Create target database if it
+  #   does not exist. Only for server replications
+  # @option options [Fixnum] batch_size Number of documents to process at a
+  #   time. Defaults to 100. This affects the number of docs held in memory
+  #   and the number sent at a time to the target server. You may need to
+  #   adjust downward if targeting devices with low amounts of memory
+  #   (e.g. phones) or if the documents are large in size (e.g. with
+  #   attachments). If your documents are small in size, then increasing this
+  #   number will probably speed replication up.
+  # @option options [Fixnum] batches_limit Number of batches to process at a
+  #   time. Defaults to 10. This (along with `batch_size`) controls how many
+  #   docs are kept in memory at a time, so the maximum docs in memory at
+  #   once would equal `batch_size` x `batches_limit`.
+  #
+  # @return [EventEmitter] An EventEmitter with the 'complete', 'active',
+  #   'paused', 'change', 'denied' and 'error' events
+  def self.replicate(source, target, options = {})
+    s = database_as_string(source)
+    t = database_as_string(target)
+    EventEmitter.new(`PouchDB.replicate(#{s}, #{t}, #{options.to_n})`)
+  end
+
+  # Sync data from `source` to `target` and `target` to `src`. This is a
+  # convenience method for bidirectional data replication. In other words,
+  # this code:
+  #
+  #     PouchDB.replicate("mydb", "http://localhost:5984/mydb")
+  #     PouchDB.replicate("http://localhost:5984/mydb", "mydb")
+  #
+  # is equivalent to this code:
+  #
+  #     PouchDB.sync("mydb", "http://localhost:5984/mydb")
+  #
+  # @see .replicate
+  # @return [EventEmitter] An EventEmitter with the 'complete', 'active',
+  #   'paused', 'change', 'denied' and 'error' events
+  def self.sync(source, target, options = {})
+    s = database_as_string(source)
+    t = database_as_string(target)
+    EventEmitter.new(`PouchDB.sync(#{s}, #{t}, #{options.to_n})`)
+  end
+
+  extend Conversion
+end

data/opal/pouchdb/all_documents.rb

@@ -0,0 +1,30 @@
+module PouchDB
+  class AllDocuments
+    include Enumerable
+
+    def initialize(results)
+      @results = results
+    end
+
+    def offset
+      `#{@results}.offset`
+    end
+
+    def total_rows
+      `#{@results}.total_rows`
+    end
+
+    def size
+      `#{@results}.rows.length`
+    end
+
+    alias_method :count, :size
+    alias_method :length, :size
+
+    def each
+      `#{@results}.rows`.each do |r|
+        yield Row.new(r)
+      end
+    end
+  end
+end

data/opal/pouchdb/conversion.rb

@@ -0,0 +1,28 @@
+module PouchDB
+  module Conversion
+    OBJECT_CONVERSION = ->(response) {
+      if (maybe_exception = Native(response)).is_a?(Exception)
+        maybe_exception
+      else
+        Hash.new(response)
+      end
+    }
+    ARRAY_CONVERSION = ->(response) { response.map { |o| OBJECT_CONVERSION.call(o) } }
+
+    def as_opal_promise(pouch_promise_n, &response_handler)
+      pouch_promise = Native(pouch_promise_n)
+      handler       = response_handler || OBJECT_CONVERSION
+      promise       = Promise.new
+
+      pouch_promise
+        .then(-> (response) do promise.resolve(handler.call(response)) end)
+        .catch(-> (error) do promise.reject(error) end)
+
+      promise
+    end
+
+    def database_as_string(db)
+      db.is_a?(Database) ? db.name : db
+    end
+  end
+end

data/opal/pouchdb/database.rb

@@ -0,0 +1,266 @@
+# coding: utf-8
+module PouchDB
+  # Creates a Database, either interacting with it locally or remotely. If
+  # remotely, the library will act as a CouchDB client.
+  #
+  # Unless explicitly noted, this wrapper follows the same API names and
+  # conventions of the original JavaScript code, with the exception of not
+  # providing the alternative between callbacks and promises on CRUD operations,
+  # opting for promises in every stance. The only situations in which that is
+  # not the case are those involving EventEmitter, where only providing promises
+  # would break semantics.
+  #
+  # That means you can safely read the original documentation and translate it
+  # directly to Ruby. An `options` Object will be an options Hash, an Object
+  # representing a document will be a Hash in Ruby land.
+  #
+  # This is not a toll-free library. It tries to follow the principle of least
+  # surprise, forcing it to convert PouchDB's promises to Opal promises and
+  # Objects to Hashes. It's not that great of a price to pay for convenience.
+  #
+  # Basic usage:
+  #
+  #   db = PouchDB::Database.new(name: "awesome_db")
+  #   db.put(_id: "doc-id", contents: "This is important").then do
+  #     db.all_docs(include_docs: true).then do |docs|
+  #       puts "Yay, #{docs.size} docs"
+  #     end
+  #   end.fail do |error|
+  #     puts "This code is perfect, but something went wrong"
+  #   end
+  #
+  # Refer to the PouchDB API and Getting Started guides for more.
+  class Database
+    include Native
+    include Conversion
+
+    # Creates a Database. If passed a URL, the Database will act as a CouchDB
+    # client. Otherwise, data will be stored and queried locally.
+    #
+    # Notice that here we don't support the alternative between passing the name
+    # or `options` as the first argument. As such, name must *always* be
+    # passed in as a keyword argument. A KeyError will be thrown otherwise.
+    #
+    # @param [Hash] options The options for database creation
+    # @option options [String] :name The name or URL of the database (mandatory)
+    # @option options [Boolean] :auto_compaction This turns on auto compaction, which means
+    #   compact() is called after every change (default: false)
+    # @option options [String] :adapter One of 'idb', 'leveldb', 'websql', or 'http'.
+    #   If unspecified, PouchDB will infer this automatically, preferring IndexedDB
+    #   to WebSQL in browsers that support both (i.e. Chrome, Opera and Android 4.4+).
+    # @option options [Hash] :ajax For CouchDB clients only. Refer to official doc
+    #   for more info.
+    # @raise [KeyError] if `:name` is not passed in as a keyword argument
+    def initialize(options = {})
+      @name = options.fetch(:name)
+      super `new PouchDB(#{options.to_n})`
+    end
+
+    attr_reader :name
+
+    # Deletes the database. Be aware this will not affect replicas.
+    #
+    # @option options [Hash] :ajax Refer to the official doc for more info.
+    # @return [Promise<Hash>]
+    def destroy(options = {})
+      as_opal_promise(`#{@native}.destroy()`)
+    end
+
+    # Deletes a document from the database. It can be called in one of two ways:
+    #
+    #    db.remove(doc: <full document hash>)
+    #    # or, alternatively
+    #    db.remove(doc_id: <id>, doc_rev: <revision>)
+    #
+    # @param args [Hash] The arguments for the function
+    # @option args [Hash] :doc A document with _id and _rev to be removed. If defined,
+    #   :doc_id and :doc_rev will be ignored.
+    # @option args [String] :doc_id A document's id (requires :doc_rev)
+    # @option args [String] :doc_rev A document's revision (requires :doc_id)
+    # @option args [Hash] :options Extra options (refer to the official doc).
+    # @return [Promise<Hash>]
+    def remove(args = {})
+      doc     = args[:doc]
+      doc_id  = args[:doc_id]
+      doc_rev = args[:doc_rev]
+      options = args[:options]
+
+      %x{
+        var pouchPromise;
+        if (doc) {
+          pouchPromise = #{@native}.remove(#{doc.to_n}, #{options.to_n})
+        } else {
+          pouchPromise = #{@native}.remove(doc_id, doc_rev, #{options.to_n})
+        }
+      }
+
+      as_opal_promise(`pouchPromise`)
+    end
+
+    # Creates or updates a document. When updating a document, its _id and _rev
+    # can either be in `doc` or passed explicitly as :doc_id and :doc_rev.
+    #
+    # @param doc [Hash] The contents to create or update
+    # @param args [Hash] Optional arguments
+    # @option args [String] :doc_id A document's id (requires :doc_rev)
+    # @option args [String] :doc_rev A document's rev (requires :id)
+    # @option args [Hash] :options Extra options (refer to the official doc)
+    # @return [Promise<Hash>]
+    def put(doc, args = {})
+      doc_id  = args[:doc_id]
+      doc_rev = args[:doc_rev]
+      options = args[:options]
+
+      as_opal_promise(`#{@native}.put(#{doc.to_n}, doc_id, doc_rev, #{options.to_n})`)
+    end
+
+    # Creates a document, generating its id in the process. It's better to
+    # always use `put` with an explicit id in order to avoid PouchDB's very long
+    # Strings and to take advantage of its sorting of keys when using `all_docs`.
+    #
+    # @param doc [Hash] The contents to use when creating
+    # @param options [Hash] Extra options (refer to the official doc)
+    # @return [Promise<Hash>]
+    def post(doc, options = {})
+      as_opal_promise(`#{@native}.post(#{doc.to_n}, #{options.to_n})`)
+    end
+
+    # Retrieves a document from the database.
+    #
+    # @param doc_id [String] A document's id
+    # @param options [Hash] Optional arguments. All default to `false`
+    # @option options [String] :rev Fetch a specific revision. Defaults to
+    #   winning revision
+    # @option options [Boolean] :revs Include revision history with the document
+    # @option options [Boolean] :revs_info Include a list of revisions, and
+    #   their availability
+    # @option options [String, Array<String>] :open_revs Fetch all leaf
+    #   revisions if open_revs="all" or fetch all leaf revisions specified
+    #   in open_revs array. Leaves will be returned in the same order as
+    #   specified in input array
+    # @option options [Boolean] :conflicts If specified, conflicting leaf
+    #   revisions will be attached in _conflicts array
+    # @option options [Boolean] :attachments Include attachment data
+    # @option options [Hash] :ajax Refer to the official doc
+    # @return [Promise<Hash>]
+    def get(doc_id, options = {})
+      as_opal_promise(`#{@native}.get(doc_id, #{options.to_n})`)
+    end
+
+    # Creates, updates or deletes multiple documents. If you omit an _id in one
+    # of the documents, a new document will be created with a generated id; if
+    # you pass in both an _id and _rev, it will be updated; if you add
+    # `_deleted: true`, it will be removed.
+    #
+    # @param docs [Array<Hash>] an Array of documents
+    # @param options [Hash] optional arguments
+    def bulk_docs(docs, options = {})
+      as_opal_promise(`#{@native}.bulkDocs(#{docs.to_n}, #{options.to_n})`,
+                      &ARRAY_CONVERSION)
+    end
+
+    # Fetches multiple documents in bulk, indexing and sorting them by their
+    # _ids. Deleted documents are only included if `options.keys` is specified.
+    # All options are `false` unless otherwise specified.
+    #
+    # @param options [Hash] optional arguments
+    # @option options [Boolean] include_docs include the document itself in
+    #   each row in the `doc` field. Otherwise by default you only get the
+    #   _id and rev properties.
+    # @option options [Boolean] conflicts Include conflict information in
+    #   the `_conflicts` field of a doc (only if `include_docs` is `true`)
+    # @option options [Boolean] attachments Include attachment data as
+    #   base64-encoded string (only if `include_docs` is `true`)
+    # @option options [String] startkey Used in conjuction with `endkey`.
+    #   Get documents with IDs in a certain range
+    # @option options [String] endkey Used in conjuction with `startkey`.
+    #   Get documents with IDs in a certain range
+    # @option options [Boolean] inclusive_end Include documents having an
+    #   ID equal to the given `options.endkey` (default: `true`)
+    # @option options [Fixnum] limit Maximum number of documents to return
+    # @option options [Fixnum] skip Number of documents to skip before
+    #   returning (warning: poor performance on IndexedDB/LevelDB)
+    # @option options [Boolean] descending Reverse the order of the output
+    #   documents
+    # @option options [String] key Only return documents with IDs matching
+    #   this key
+    # @option options [Array<String>] keys Keys to be fetched in a single
+    #   shot. Neither `startkey` nor `endkey` can be specified with this
+    #   option; the rows returned are in the same order as the supplied
+    #   `keys` Array; the row for a deleted document will have the revision
+    #   ID of the deletion, and an extra `deleted: true` in the `value`
+    #   key; the row for a nonexistent document will just contain an
+    #   `"error"` key with the value `"not_found"`. For details, see the
+    #   CouchDB query options documentation.
+    # @return [Promise]
+    def all_docs(options = {})
+      as_opal_promise(`#{@native}.allDocs(#{options.to_n})`) { |response|
+        AllDocuments.new(response)
+      }
+    end
+
+    # A list of changes made to documents in the database, in the order they
+    # were made. It returns an object with the method `cancel()`, which you call
+    # if you don't want to listen to new changes anymore.
+    #
+    # It is an EventEmitter and will emit a 'change' event on each document
+    # change, a 'complete' event when all the changes have been processed, and
+    # an 'error' event when an error occurs. In addition to the 'change' event,
+    # any change will also emit a 'create', 'update', or 'delete' event.
+    #
+    # @param options [Hash] optional arguments
+    # @option options [Boolean] include_docs Include the associated document
+    #   with each change
+    # @option options [Boolean] conflicts Include conflict information in
+    #   the `_conflicts` field of a doc (only if `include_docs` is `true`)
+    # @option options [Boolean] attachments Include attachment data as
+    #   base64-encoded string (only if `include_docs` is `true`)
+    # @option options [Boolean] descending Reverse the order of the output
+    #   documents
+    # @option options [String,Fixnum] since Start the results from the change
+    #   immediately after the given sequence number. You can also pass
+    #   'now' if you want only new changes (depends on `live: true` )
+    # @option options [Fixnum] timeout The request timeout, in milliseconds
+    # @option options [Fixnum] limit Limit the numbers of results to this
+    #   number
+    # @option options [Array<String>] Only shows changes for docs with these
+    #   ids
+    # @option options [String] filter Reference a filter function from a design
+    #   document to selectively get updates. To use a view function, pass in
+    #   `_view` and provide a reference to that function with the `view` key
+    # @option options [Hash] query_params Properties to pass to the filter
+    #   function (e.g.: { foo: "bar" }, where "bar" will be available in the
+    #   filter function as `params.query.foo`. To have access to the params,
+    #   define your function as receiving a second argument
+    # @option options [String] view Specify a view function (e.g.
+    #   "design_doc_name/view_name") to act as a filter. Documents counted
+    #   as "passed" for a view filter if a map function emits at least one
+    #   record of them (`options.filter` must be set to `"_view"`)
+    # @option options [Boolean] returnDocs Available for non-http databases
+    #   only, and defaults to `true`. Passing `false` prevents the changes
+    #   feed from keeping all the documents in memory -- in other words,
+    #   complete always has an empty results array, and the `change` event
+    #   is the only way to get the event. Useful for large change sets
+    #   where otherwise you would run out of memory
+    # @option options [Fixnum] batch_size Only available for http databases,
+    #   this configures how many changes to fetch at a time. Increasing this
+    #   can reduce the number of requests made. Default is 25.
+    # @option options [String] style Specifies how many revisions are returned
+    #   in the changes array. The default, `"main_only"`, will only return
+    #   the current "winning" revision; `"all_docs"` will return all leaf
+    #   revisions (including conflicts and deleted former conflicts). Most
+    #   likely you won't need this unless you are writing a replicator.
+    # @return [EventEmitter]
+    def changes(options = {})
+      EventEmitter.new(`#{@native}.changes(#{options.to_n})`)
+    end
+
+    def replicate
+      Replication.new(@native)
+    end
+
+    def sync(other)
+      EventEmitter.new(`#{@native}.sync(#{database_as_string(other)})`)
+    end
+  end
+end