(See RFC 2119 for use of MUST, SHOULD, MAY, MUST NOT, and SHOULD NOT)
The purpose of the moneta specification is to create a general-purpose API for interacting with key-value stores. In general, libraries that need to interact with key-value stores should be able to specify that they can use any “moneta-compliant store”. Moneta ships with a set of executable specs which you can use to verify spec-compliance with your moneta adapter.
new(options[Hash] => {}) => Object
¶ ↑Return an instance of the moneta adapter, with the instance methods listed
below. The options
hash is a required parameter, and the
adapter may specify whatever additional requirements it needs to properly
instantiate it.
[](key[Object]) => Object
¶ ↑Return the value stored in the key-value-store under the provided key. Adapters MUST return a duplicate of the original value, and consumers should expect that adapters might serialize and deserialize the key and value. As a result, both the key and value MUST be objects that can be serialized using Ruby's Marshal system.
[]=(key[Object], value[Object]) => Object(value)
¶ ↑Store the value in the key-value-store under the provided key. Adapters MAY
serialize the value using Ruby's Marshal system, and MUST NOT store a
reference to the original value in the store, unless Ruby disallows
duplication of the original value. Adapters SHOULD NOT simply call
dup
on the value, unless the value stores no references to
other Object. For example, an adapter MAY store a dup
of a
String, but SHOULD NOT store a dup
of
["hello", "world"]
.
fetch(key[Object], options[Hash] => {}, &block) => Object
¶ ↑Return the value stored in the key-value-store under the provided key. If no value is stored under the provided key, the adapter MUST yield to the block, and return the value. The adapter MUST NOT store the value returned from the block in the key-value-store.
fetch(key[Object], value[Object], options[Hash] => {}) => Object
¶ ↑Return the value stored in the key-value-store under the provided key. If no value is stored under the provided key, the adapter MUST return the default value provided. The adapter MUST NOT store the default value in the key-value-store.
delete(key[Object], options[Hash] => {}) => Object
¶ ↑Delete the value stored in the key-value-store for the key provided, and return the value previously stored there. After this operation, the key-value-store MUST behave as though no value was stored for the provided key.
key?(key[Object], options[Hash] => {}) => [TrueClass, FalseClass]
¶ ↑Determine whether a value exists in the key-value-store for the key
provided. If a value exists, the adapter MUST return true
.
Otherwise, the adapter MUST return false
.
store(key[Object], value[Object], options[Hash] => {}) => Object(value)
¶ ↑Behaves the same as []=
, but allows the client to send
additional options which can be specified by the adapter (and which may be
specified by extensions to this specification).
increment(key[Object], amount[Integer] = 1, options[Hash] => {}) => Integer(value)
¶ ↑Increments a value atomically. This method is not supported by all stores
and might raise a NotImplementedError
.
This method MUST accept
negative amounts, but the result MUST be unsigned.
decrement(key[Object], amount[Integer] = 1, options[Hash] => {}) => Integer(value)
¶ ↑Decrements a value atomically. This method is not supported by all stores
and might raise a NotImplementedError
.
This method MUST accept
negative amounts, but the result MUST be unsigned.
create(key[Object], value[Object], options[Hash] => {}) => [TrueClass, FalseClass]
¶ ↑Creates a value atomically. This method is not supported by all stores and
might raise a NotImplementedError
.
It MUST return true if the
value was created.
clear(options[Hash] => {})
¶ ↑Completely empty all keys and values from the key-value-store. Adapters MAY
allow a namespace during initialization, which can scope this operation to
a particular subset of keys. After calling clear
, a
[]
operation MUST return nil for every possible key, and a
key?
query MUST return false for every possible key.
close
¶ ↑Closes the store
features => Array<Symbol>
and supports?(Symbol) => [TrueClass, FalseClass]
¶ ↑Feature detection. Adapters MUST return :create
and
:increment
if these methods are supported.
The following methods may all take an additional Hash as a final argument. This allows the client to send additional options which can be specified by the adapter (and which may be specified by extensions to this specification). The methods MUST NOT modify the supplied option hash.
fetch
load
store
delete
key?
increment
clear
In the case of methods with optional arguments, the Hash MUST be provided as the final argument. Keys in this Hash MUST be Symbols.
The base Moneta specification does not specify any atomicity guarantees. However, extensions to this spec may specify extensions that define additional guarantees for any of the defined operations.