updated docs

.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 /.bundle/
 /.yardoc
 /Gemfile.lock

examples/composite_table.rb

@@ -0,0 +1,64 @@
+require 'rom/dynamodb'
+
+TABLE = "my-dynamodb-users-table"
+
+# any other AWS::DynamoDB::Client options
+credentials = { region: 'us-east-1' }
+
+container = ROM.container(:dynamodb, credentials) do |rom|
+  rom.relation(:logs) do
+    # Key Schema: host<Hash>, timestamp<Range>
+    dataset "my-logs-table"
+
+    def by_host(ip)
+      where { host == ip }
+    end
+
+    def after_timestamp(time)
+      where { timestamp > time }
+    end
+
+    def before_timestamp(time)
+      where { timestamp < time }
+    end
+  end
+
+  rom.commands(:logs) do
+    define(:create) do
+      KEYS = %w(host timestamp message)
+      result :one
+      input Functions[:accept_keys, KEYS]
+    end
+  end
+end
+
+num_of_logs = 20
+
+host = "192.168.0.1"
+
+logs = (1..num_of_logs).to_a.collect do |i|
+  { host: host, timestamp: Time.now.to_f + (i * 60), message: "some message" }
+end
+
+# create fake logs
+container.commands[:logs][:create].call(logs)
+
+relation = container.relation(:logs)
+
+relation.count == num_of_logs # => true
+
+all = relation.where(ip: host) { host == ip }.after(0).to_a # => [{host: "192.168.0.1", ... }, ...]
+
+all.size # => 20
+
+before = relation.where(ip: host) { [host == ip, timestamp < (Time.now.to_f + 60 * 60)] }.limit(1).to_a
+
+before.size # => 1
+
+before.first == logs.first # => true
+
+offset = { ip: host, timestamp: logs[-2][:timestamp] }
+
+last = relation.where(ip: host) { ip == host }.descending.after(0).offset(offset).limit(1).one!
+
+last == logs.last # => true

examples/simple_table.rb

@@ -0,0 +1,61 @@
+require 'rom/dynamodb'
+
+TABLE = "my-dynamodb-users-table"
+
+# any other AWS::DynamoDB::Client options
+credentials = { region: 'us-east-1' }
+
+container = ROM.container(:dynamodb, credentials) do |rom|
+  rom.relation(:users) do
+    # Key Schema: id<Hash>
+    dataset TABLE
+
+    def by_id(val)
+      where { id == val }
+    end
+  end
+
+  rom.commands(:users) do
+    FILTER = Functions[:symbolize_keys] >> Functions[:accept_keys, [:id]]
+
+    define(:create) do
+      KEYS = %w(id name)
+      result :one
+      input Functions[:accept_keys, KEYS]
+    end
+
+    define(:delete) do
+      result :one
+      input FILTER
+    end
+
+    define(:update) do
+      result :one
+      input FILTER
+    end
+  end
+end
+
+relation = container.relation(:users)
+
+relation.count # => 1234
+
+relation.where { id == 1 }.one! # => { id: 1, name: "David" }
+
+relation.info # => <Hash> DynamoDB Table Information
+
+relation.status # => :active
+
+# create a new user
+create = container.commands[:users][:create]
+user = create.call({ id: 2, name: "James" })
+
+# update an existing user
+update = container.commands[:users][:update]
+update.by_id(user[:id]).call(name: "Mark")
+
+relation.where(id: user[:id]) { id == id }.one! # => { id: 2, name: "Mark" }
+
+# delete an existing user
+delete = container.commands[:users][:delete]
+delete.by_id(user[:id]).call

lib/rom/dynamodb/dataset.rb

@@ -3,17 +3,17 @@
 module ROM
   module DynamoDB
     class Dataset
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       # @note This method can be chained with other relational methods.
 
-      # @!macro rom.dynamodb.dataset.order_note
+      # @!macro order_note
       # @note Items with the same partition key value are stored in sorted
       #   order by sort key. If the sort key data type is Number, the results
       #   are stored in numeric order. For type String, the results are stored
       #   in order of ASCII character code values. For type Binary, DynamoDB
       #   treats each byte of the binary data as unsigned.
 
-      # @!macro rom.dynamodb.dataset.series_note
+      # @!macro series_note
       # @note Whilst the naming and parameters of this method indicate a
       #   time-series based operation, DynamoDB can perform a range query
       #   for any orderable data.
@@ -29,7 +29,7 @@ class Dataset
 
       # @attr [Array<Hash>] queries the array of query sets to merge and use
       #   to query DynamoDB.
-
+      #
       #   This array of hashes is built up by chaining the
       #   relational methods together and when the query is finally executed,
       #   all the hashes in this array are merged and send to the underlying
@@ -47,7 +47,7 @@ def initialize(name:, operation: :query, config: {}, queries: [])
       # The name of an index to query. This index can be any local secondary
       # index or global secondary index on the table.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       #
       # @param name [String] the name of the index to query.
       #
@@ -62,8 +62,8 @@ def index(name)
       #
       # @note This is the default behaviour.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
-      # @!macro rom.dynamodb.dataset.order_note
+      # @!macro chain_note
+      # @!macro order_note
       #
       # @return [self] the {Dataset} object the method was performed on.
       def ascending
@@ -76,8 +76,8 @@ def ascending
       #
       # @note This is the default behaviour.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
-      # @!macro rom.dynamodb.dataset.order_note
+      # @!macro chain_note
+      # @!macro order_note
       #
       # @return [self] the {Dataset} object the method was performed on.
       def descending
@@ -91,19 +91,19 @@ def descending
       # limit while processing the results, it stops the operation and returns
       # the matching values up to that point.
       #
-      # If there are more matches to be returned, the {#last_evaluated_key}
+      # If there are more matches to be returned, the last_evaluated_key
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       #
       # @return [self] the {Dataset} object the method was performed on.
       def limit(num = nil)
         append { { limit: num } unless num.nil? }
       end
 
       # The composite key of the first item that the resulting query will
-      # evaluate. Use this method if you have a populated {#last_evaluated_key}.
+      # evaluate. Use this method if you have a populated last_evaluated_key.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       #
       # @note When applying an offset, it must include the same composite key of
       #   which the index you are querying is composed from. Therefore, if your
@@ -122,7 +122,7 @@ def offset(key)
       # These keys can include scalars, sets, or elements of a JSON
       # document.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       #
       # @param keys [Array<String>] an array of string expressions to apply
       #   to the query
@@ -140,11 +140,11 @@ def select(keys)
       # Multiple where clauses can be chained, or multiple predicates defined
       # inside an array within a single clause. See the examples below.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       #
       # @note The following operands are supported, :>=, :>, :<, :<=, :== and :between
       #
-      # @example Given Table[id<Hash>,legs<Range>]
+      # @example Using a composite key table
       #   animals = relation.where { [id == "mammal", legs > 0] }
       #   animals #=> [{id: "mammal", legs: 2, name: "Human"}, ...]
       #
@@ -157,11 +157,6 @@ def select(keys)
       #   keys = { type: "mammal" }
       #   animals = relation.where(keys) { id == type }
       #   animals #=> [{id: "mammal", legs: 2, name: "Elephant"}, ...]
-      #
-      # @example Between two values
-      #
-      # @example Matching with begins_with
-      #
       def where(maps = {}, &block)
         clauses = WhereClause.new(maps).execute(&block).clauses
         append(:query) do
@@ -178,12 +173,12 @@ def where(maps = {}, &block)
       #
       # @deprecated Use {#where} instead.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
       #
-      # @example Given Table[id<Hash>]
+      # @example Given a hash key table
       #   relation.equal(:id, 1).one! #=> { id: 1, ... }
       #
-      # @example Given Table[id<Hash>,created_at<Range>]
+      # @example Given a composite key table
       #   relation.equal(:id, 1).equal(:created_at, Time.now.to_f).one! #=> { id: 1, ... }
       #
       # @param key [Symbol] the key to match the provided value against.
@@ -200,11 +195,10 @@ def equal(key, val, predicate = :eq)
       #
       # @deprecated Use {#where} instead.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
+      # @!macro chain_note
+      # @!macro series_note
       #
-      # @!macro rom.dynamodb.dataset.series_note
-      #
-      # @example Given Table[id<Hash>,legs<Range>]
+      # @example Given a composite key table
       #   users = relation.equal(:id, "mammal").between(:legs, 0, 4).to_a
       #   users #=> [{id: "mammal", legs: 2, name: "Human"}, {id: "mammal", legs: 4, name: "Elephant"}, ...]
       #
@@ -222,17 +216,16 @@ def between(key, after, before, predicate = :between)
       #
       # @deprecated Use {#where} instead.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
-      #
-      # @!macro rom.dynamodb.dataset.series_note
+      # @!macro chain_note
+      # @!macro series_note
       #
       # @deprecated Use {#where} instead.
       #
-      # @example Given Table[id<Hash>,legs<Range>]
+      # @example Given a composite key table
       #   users = relation.equal(:id, "mammal").after(:legs, 0).to_a
       #   users #=> [{id: "mammal", legs: 2, name: "Human"}, ...]
       #
-      # @param key [Symbol] the key to match the provided value against.
+      # @param key {Symbol} the key to match the provided value against.
       # @param after the value to match range values after
       # @param predicate [String] the query predicate to apply to DynamoDB.
       #
@@ -246,9 +239,8 @@ def after(key, after, predicate = :ge)
       #
       # @deprecated Use {#where} instead.
       #
-      # @!macro rom.dynamodb.dataset.chain_note
-      #
-      # @!macro rom.dynamodb.dataset.series_note
+      # @!macro chain_note
+      # @!macro series_note
       def before(key, before, predicate = :le)
         restrict_by(key, predicate, [before])
       end

lib/rom/dynamodb/relation.rb

@@ -1,12 +1,29 @@
 module ROM
   module DynamoDB
+    # Extending the relation class allows you to build in custom queries
+    # that are often repeated throughout your code base, or those which need to be
+    # tested in isolation.
+    #
+    # Below is a guided example for creating, updating, deleting and querying
+    # information for a simple `User` table that consists of an `:id` key in the
+    # form of a hash.
+    #
+    # {include:file:examples/simple_table.rb}
+    #
+    # The additional example below covers the same options but using a `Log`
+    # table that contains a composite key, made up of `:host` and `:timestamp`,
+    # which form the hash and range parts of the key, respectively.
+    #
+    # {include:file:examples/composite_table.rb}
     class Relation < ROM::Relation
       adapter :dynamodb
 
-      # @!macro [attach] r.forward
-      # Performs a $1 action on the relation. In most cases, these operations
+      # @!macro [attach] dm.forward
+      # Performs a $0 $1 action on the relation. In most cases, these operations
       # can be chained to build up larger queries to perform.
+      #
       # @note This method forwards the $1 operation to the underlying dataset.
+      # 
       # @see DynamoDB::Dataset#$1
       forward :restrict
 

rom-dynamodb.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "redcarpet", "~> 3.4"
   spec.add_development_dependency "codeclimate-test-reporter", "~> 1.0"
   spec.add_development_dependency "factory_girl", "~> 4.5"
 end