npm - entangld - Versions diffs - 2.1.6 → 2.3.0 - Mend

entangld 2.1.6 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md CHANGED Viewed

@@ -145,6 +145,7 @@ Any object can store values.  And a Map can store values keyed to objects.  But
 - Have your store synchronized with multiple data sources (other stores)?
 - Over a network?
 - Subscribe to events within the datastore?
+- Support subscription wildcards?
 ## Notes
@@ -178,6 +179,15 @@ If these two issues can be resolved at some point, _deref_mode will probably be
 ## Classes
 <dl>
+<dt><a href="#Entangld">Entangld</a> ⇐ <code>EventEmitter</code></dt>
+<dd><p>Synchronized Event Store</p>
+</dd>
+<dt><a href="#EntangldError">EntangldError</a></dt>
+<dd><p>Error class for Entangld.</p>
+</dd>
+<dt><a href="#RPCError">RPCError</a></dt>
+<dd><p>Remote Error class for Entangld.</p>
+</dd>
 <dt><a href="#Entangld_Message">Entangld_Message</a></dt>
 <dd><p>Message class for Entangld.</p>
 <p>These messages are used for executing datastore operations between
@@ -191,7 +201,8 @@ downstream datastores do not necessarilly have access to the upstream store
 structure, and so cannot generally construct upstream paths. This means that
 the <code>.path</code> attribute is a <code>tree</code> relative to the upstream datastore, and
 the upstream path can be reconstructed as:</p>
-<pre><code class="language-javascript"> &gt; upstream._namespaces.get(downstream) + &quot;.&quot; + msg.path;</code></pre>
+<pre><code class="language-javascript"> &gt; upstream._namespaces.get(downstream) + &quot;.&quot; + msg.path;
+</code></pre>
 <p>Since <code>unsubscribe</code> messages can pass either upstream or downstream, the notion
 of a path is ill-defined, and so unsubscribe messages should have their <code>.path</code>
 attributes set to undefined or null.</p>
@@ -202,621 +213,679 @@ callback functions to be trigger properly, and for unsubscribe messages to
 propogate both directions. <code>set</code>/<code>push</code> messages do not use the <code>.uuid</code> attribute
 since they require no response.</p>
 </dd>
-<dt><a href="#EntangldError">EntangldError</a></dt>
-<dd><p>Error class for Entangld.</p>
-</dd>
 <dt><a href="#Subscription">Subscription</a></dt>
 <dd><p>A datastore subscription object</p>
 </dd>
-<dt><a href="#Entangld">Entangld</a> ⇐ <code>EventEmitter</code></dt>
-<dd><p>Synchronized Event Store</p>
-</dd>
 </dl>
-<a name="Entangld_Message"></a>
-## Entangld\_Message
-Message class for Entangld.
-These messages are used for executing datastore operations between
-remote datastores. In these relationships, there is always an upstream
-and downstream pair, so that `get`, `set`, `push` and `subscribe` messages
-are created upstream and passed downstream while `event` and `value` messages
-are created downstream and are passed back up. `unsubscribe` events can travel
-in both directions. To maintain consistency, the internal `.path` attribute
-will always refer a path relative to the downstream datastore, since the
-downstream datastores do not necessarilly have access to the upstream store
-structure, and so cannot generally construct upstream paths. This means that
-the `.path` attribute is a `tree` relative to the upstream datastore, and
-the upstream path can be reconstructed as:
-```javascript
- > upstream._namespaces.get(downstream) + "." + msg.path;
-```
-Since `unsubscribe` messages can pass either upstream or downstream, the notion
-of a path is ill-defined, and so unsubscribe messages should have their `.path`
-attributes set to undefined or null.
+<a name="Entangld"></a>
-Most messages will also have a `.uuid` attribute. For `get`/`value` messages,
-this allows for the value to be properly linked back up with the original `get`
-message. For the `subscribe`/`unsubscribe`/`event` messages, this allows for
-callback functions to be trigger properly, and for unsubscribe messages to
-propogate both directions. `set`/`push` messages do not use the `.uuid` attribute
-since they require no response.
+## Entangld ⇐ <code>EventEmitter</code>
+Synchronized Event Store
 **Kind**: global class
+**Extends**: <code>EventEmitter</code>
-* [Entangld_Message](#Entangld_Message)
-    * [.get(tree, [get_params])](#Entangld_Message.get) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-    * [.value(get_msg, value)](#Entangld_Message.value) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-    * [.setpush(obj)](#Entangld_Message.setpush) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-    * [.subscribe(tree, uuid)](#Entangld_Message.subscribe) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-    * [.event(path, value, uuid)](#Entangld_Message.event) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-    * [.unsubscribe(uuid)](#Entangld_Message.unsubscribe)
+* [Entangld](#Entangld) ⇐ <code>EventEmitter</code>
+    * [.namespaces](#Entangld+namespaces) ⇒ <code>array</code>
+    * [.subscriptions](#Entangld+subscriptions) ⇒ [<code>Array.&lt;Subscription&gt;</code>](#Subscription)
+    * [.namespace()](#Entangld+namespace) ⇒ <code>string</code>
+    * [.attach(namespace, obj)](#Entangld+attach)
+    * [.detach([namespace], [obj])](#Entangld+detach) ⇒ <code>boolean</code>
+    * [.transmit(func)](#Entangld+transmit)
+    * [.receive(msg, obj)](#Entangld+receive)
+    * [.push(path, data, [limit])](#Entangld+push)
+    * [.set(path, data, [operation_type], [params])](#Entangld+set)
+    * [.set_rpc(path, func, opts)](#Entangld+set_rpc)
+    * [.set_rpc_class(object, key_description_pairs, opts)](#Entangld+set_rpc_class)
+    * [.call_rpc(path, [args])](#Entangld+call_rpc) ⇒ <code>Promise</code>
+    * [.get(path, [params])](#Entangld+get) ⇒ <code>Promise</code>
+    * [.subscribe(path, func, [every])](#Entangld+subscribe) ⇒ <code>uuidv4</code>
+    * [.subscribed_to(subscription)](#Entangld+subscribed_to) ⇒ <code>Boolean</code>
+    * [.unsubscribe(path_or_uuid)](#Entangld+unsubscribe) ⇒ <code>number</code>
+    * [.unsubscribe_tree(path)](#Entangld+unsubscribe_tree)
-<a name="Entangld_Message.get"></a>
+<a name="Entangld+namespaces"></a>
-### Entangld_Message.get(tree, [get_params]) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-Create a `get` message for remote datastores
+### entangld.namespaces ⇒ <code>array</code>
+Get namespaces
-**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
-**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - - The get message to pass to the remote datastore
+**Kind**: instance property of [<code>Entangld</code>](#Entangld)
+**Returns**: <code>array</code> - namespaces - an array of attached namespaces
+**Read only**: true
+<a name="Entangld+subscriptions"></a>
-| Param | Type | Description |
-| --- | --- | --- |
-| tree | <code>string</code> | the path relative to the remote datastore |
-| [get_params] | <code>\*</code> | any parameters to be passed to the                                        remote datastore's local get function |
+### entangld.subscriptions ⇒ [<code>Array.&lt;Subscription&gt;</code>](#Subscription)
+Get list of subscriptions associated with this object
-<a name="Entangld_Message.value"></a>
+Note, this will include `head`, `terminal` and `pass through` subscriptions,
+which can be checked using getter methods of the subscription object.
-### Entangld_Message.value(get_msg, value) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-Create a `value` message in response to a `get` message
+**Kind**: instance property of [<code>Entangld</code>](#Entangld)
+**Returns**: [<code>Array.&lt;Subscription&gt;</code>](#Subscription) - array of Subscriptions associated with this object
+**Read only**: true
+<a name="Entangld+namespace"></a>
-**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
-**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - - The `value` message to pass back
+### entangld.namespace() ⇒ <code>string</code>
+Get namespace for a store
-| Param | Type | Description |
-| --- | --- | --- |
-| get_msg | [<code>Entangld\_Message</code>](#Entangld_Message) | the `get` message which this is in response to |
-| value |  | the value of the `get` |
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Returns**: <code>string</code> - namespace for the given store
+**Read only**: true
+<a name="Entangld+attach"></a>
-<a name="Entangld_Message.setpush"></a>
+### entangld.attach(namespace, obj)
+Attach a namespace and a store
-### Entangld_Message.setpush(obj) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-Create a `set`/`push` message for a remote datastore
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
+- <code>TypeError</code> if namespace/obj is null or empty.
+- [<code>EntangldError</code>](#EntangldError) if you try to attach to the same namespace twice.
-**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
-**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - - the "set" or "push" message
 | Param | Type | Description |
 | --- | --- | --- |
-| obj | <code>Object</code> | The parameter object for the set/push |
-| obj.type | <code>string</code> | either "set" or "push" |
-| obj.tree | <code>string</code> | the path (relative to the downstream datastore) |
-| obj.value | <code>\*</code> | the value to insert into the datastore |
-| obj.params | <code>\*</code> | any additional parameters |
-<a name="Entangld_Message.subscribe"></a>
+| namespace | <code>string</code> | a namespace for this store. |
+| obj | <code>object</code> | an object that will be sent along with "transmit" callbacks when we need something from this store. |
-### Entangld_Message.subscribe(tree, uuid) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-Construct subscribe message
+<a name="Entangld+detach"></a>
-**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
-**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - the `subscribe` message
+### entangld.detach([namespace], [obj]) ⇒ <code>boolean</code>
+Detach a namespace / obj pair.
-| Param | Type | Description |
-| --- | --- | --- |
-| tree | <code>string</code> | the path (relative to the downstream datastore) |
-| uuid | <code>Uuid</code> | the subscription uuid |
+If you only pass a namespace or a store, it will find the missing item
+before detaching.
-<a name="Entangld_Message.event"></a>
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Returns**: <code>boolean</code> - true if the element existed and was removed.
+**Throws**:
-### Entangld_Message.event(path, value, uuid) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
-Create an `event` message to return data to subscribe callbacks
+- [<code>EntangldError</code>](#EntangldError) Error will be thrown if you don't pass at least
+one parameter.
-**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
-**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - the `event` message
 | Param | Type | Description |
 | --- | --- | --- |
-| path | <code>string</code> | the path (relative to the downstream store) |
-| value | <code>\*</code> | the updated datastore value at the path |
-| uuid | <code>Uuid</code> | the uuid of the subscribe being triggered |
+| [namespace] | <code>string</code> | the namespace. |
+| [obj] | <code>object</code> | the store object. |
-<a name="Entangld_Message.unsubscribe"></a>
+<a name="Entangld+transmit"></a>
-### Entangld_Message.unsubscribe(uuid)
-Create an unsubscribe message for a subscription uuid
+### entangld.transmit(func)
+Transmit
-**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
+Specify a callback to be used so we can transmit data to another store.
+Callback will be passed (message, obj) where 'message' is an
+Entangld_Message object and obj is the object provided by attach().
-| Param | Type | Description |
-| --- | --- | --- |
-| uuid | <code>String</code> | the subscription uuid |
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
-<a name="EntangldError"></a>
+- <code>TypeError</code> if func is not a function.
-## EntangldError
-Error class for Entangld.
-**Kind**: global class
-<a name="Subscription"></a>
+| Param | Type | Description |
+| --- | --- | --- |
+| func | <code>function</code> | the callback function. |
-## Subscription
-A datastore subscription object
+<a name="Entangld+receive"></a>
-**Kind**: global class
+### entangld.receive(msg, obj)
+Receive
-* [Subscription](#Subscription)
-    * [new Subscription(obj)](#new_Subscription_new)
-    * [.is_pass_through](#Subscription+is_pass_through) ⇒ <code>Boolean</code>
-    * [.is_terminal](#Subscription+is_terminal) ⇒ <code>Boolean</code>
-    * [.is_head](#Subscription+is_head) ⇒ <code>Boolean</code>
-    * [.has_downstream](#Subscription+has_downstream) ⇒ <code>Boolean</code>
-    * [.has_upstream](#Subscription+has_upstream) ⇒ <code>Boolean</code>
-    * [.call()](#Subscription+call)
-    * [.matches_subscription(sub)](#Subscription+matches_subscription) ⇒ <code>Boolean</code>
-    * [.matches_event_message(msg)](#Subscription+matches_event_message) ⇒ <code>Boolean</code>
-    * [.matches_unsubscribe_message(msg)](#Subscription+matches_unsubscribe_message) ⇒ <code>Boolean</code>
-    * [.matches_path(path)](#Subscription+matches_path) ⇒ <code>Boolean</code>
-    * [.matches_uuid(uuid)](#Subscription+matches_uuid) ⇒ <code>Boolean</code>
-    * [.is_beneath(path)](#Subscription+is_beneath) ⇒ <code>Boolean</code>
-    * [.is_above(path)](#Subscription+is_above) ⇒ <code>Boolean</code>
-    * [.static_copy()](#Subscription+static_copy) ⇒ [<code>Subscription</code>](#Subscription)
+Call this function with the data that was sent via the transmit()
+callback.
-<a name="new_Subscription_new"></a>
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
-### new Subscription(obj)
-Constructor
+- <code>ReferenceError</code> if event object was not provided.
+- [<code>EntangldError</code>](#EntangldError) if an unknown message type was received.
-**Returns**: [<code>Subscription</code>](#Subscription) - - the subscription object
 | Param | Type | Description |
 | --- | --- | --- |
-| obj | <code>Object</code> | the configuration object |
-| obj.path | <code>string</code> | the datastore path (relative to this datastore)                             of the subscription |
-| obj.uuid | <code>Uuid</code> | the uuid of the subscription chain |
-| obj.callback | <code>function</code> | the callback function, with signature (path, value),                               where path is relative to this datastore |
-| obj.downstream | [<code>Entangld</code>](#Entangld) \| <code>null</code> | the downstream datastore (if any)                                          associated with this subscription |
-| obj.upstream | [<code>Entangld</code>](#Entangld) \| <code>null</code> | the upstream datastore (if any)                                          associated with this subscription |
-| obj.every | <code>number</code> \| <code>null</code> | how many `set` messages to wait before calling callback |
+| msg | [<code>Entangld\_Message</code>](#Entangld_Message) | the message to process. |
+| obj | <code>object</code> | the attach() object where the message originted. |
-<a name="Subscription+is_pass_through"></a>
+<a name="Entangld+push"></a>
-### subscription.is\_pass\_through ⇒ <code>Boolean</code>
-Check if subscription is a `pass through` type
+### entangld.push(path, data, [limit])
+Push an object into an array in the store.
-Pass throughs are as the links in a chain of subscriptions to allows
-subscriptions to remote datastores. One store acts as the `head`, where
-the callback function is registered, an all others are `path through` datastores
-which simply pass event messages back up to the head subscription.
+Convenience method for set(path, o, "push").
-**Kind**: instance property of [<code>Subscription</code>](#Subscription)
-<a name="Subscription+is_terminal"></a>
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
-### subscription.is\_terminal ⇒ <code>Boolean</code>
-Check if this subscription will be directly given data by a datastore
+- <code>TypeError</code> if path is not a string.
-**Kind**: instance property of [<code>Subscription</code>](#Subscription)
-<a name="Subscription+is_head"></a>
-### subscription.is\_head ⇒ <code>Boolean</code>
-Check if this subscription will apply a user-supplied callback to data
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| path | <code>string</code> |  | the path to set (like "system.fan.voltage"). |
+| data | <code>object</code> |  | the object or function you want to store at path. |
+| [limit] | <code>number</code> | <code></code> | maximum size of the array. Older entries will be removed until the array size is less than or equal to limit. |
-**Kind**: instance property of [<code>Subscription</code>](#Subscription)
-<a name="Subscription+has_downstream"></a>
+<a name="Entangld+set"></a>
-### subscription.has\_downstream ⇒ <code>Boolean</code>
-Check if subscription has any downstream subscriptions
+### entangld.set(path, data, [operation_type], [params])
+Set an object into the store
-It the subscription refers to a remote datastore (the downstream), this
-getter will return a true. Note that !this.has_downstream will check if
-the subscription is the `tail` subscription object in a subscription chain.
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
-**Kind**: instance property of [<code>Subscription</code>](#Subscription)
-<a name="Subscription+has_upstream"></a>
-### subscription.has\_upstream ⇒ <code>Boolean</code>
-Check if subscription has any upstream subscriptions
-It the subscription passes data back to a remote datastore (the upstream), this
-getter will return a true.
-**Kind**: instance property of [<code>Subscription</code>](#Subscription)
-<a name="Subscription+call"></a>
-### subscription.call()
-Apply this callback function
-Note, this method also tracks the number of times that a callback
-function is called (if this subscription is terminal), so that if
-the subscriptions are throttled by specifying an `this.every`,
-this method will only call the callback function every `this.every`
-times it receives a `set` message. If this subscription is not
-terminal, then the callback function is called every time.
-This method also is safed when a callback function is not give (i.e.
-by the `this.static_copy()` method).
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-<a name="Subscription+matches_subscription"></a>
+- <code>TypeError</code> if path is not a string.
-### subscription.matches\_subscription(sub) ⇒ <code>Boolean</code>
-Check if a different `Subscription` object matches this subscription
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - True if the subscriptions match
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| path | <code>string</code> |  | the path to set (like "system.fan.voltage"). |
+| data | <code>object</code> |  | the object or function you want to store at path. |
+| [operation_type] | <code>string</code> | <code>&quot;\&quot;set\&quot;&quot;</code> | whether to set or push the new data (push only works if the data item exists and is an array). |
+| [params] | <code>object</code> |  | additional parameters. |
-| Param | Type | Description |
-| --- | --- | --- |
-| sub | [<code>Subscription</code>](#Subscription) | a different subscription |
+<a name="Entangld+set_rpc"></a>
-<a name="Subscription+matches_event_message"></a>
+### entangld.set\_rpc(path, func, opts)
+Set a function as an RPC in the datastore
-### subscription.matches\_event\_message(msg) ⇒ <code>Boolean</code>
-Check if an `event` message matches this subscription
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - True if the message is associated with the subscription
+- <code>TypeError</code> if path is not a string.
-| Param | Type | Description |
-| --- | --- | --- |
-| msg | [<code>Entangld\_Message</code>](#Entangld_Message) | a received message from a downstream datastore |
-<a name="Subscription+matches_unsubscribe_message"></a>
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| path | <code>string</code> |  | the path to set (like "system.fan.voltage"). |
+| func | <code>function</code> |  | the function you want to store at path. |
+| opts | <code>object</code> |  |  |
+| [opts.description] | <code>string</code> | <code>null</code> | description for the function |
+| [opts.function_string] | <code>string</code> | <code>null</code> | optional string of function source code to pass to parameter_parser |
-### subscription.matches\_unsubscribe\_message(msg) ⇒ <code>Boolean</code>
-Check if an `unsubscribe` message matches this subscription
+<a name="Entangld+set_rpc_class"></a>
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - True if the message is associated with the subscription
+### entangld.set\_rpc\_class(object, key_description_pairs, opts)
+Set a class instance as an RPC object in the datastore
-| Param | Type | Description |
-| --- | --- | --- |
-| msg | [<code>Entangld\_Message</code>](#Entangld_Message) | a received message from a downstream datastore |
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Throws**:
-<a name="Subscription+matches_path"></a>
+- <code>TypeError</code> if path is not a string.
-### subscription.matches\_path(path) ⇒ <code>Boolean</code>
-Check if a provided path matches this path
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - true if the path matches
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| object | <code>\*</code> |  | The object to attach |
+| key_description_pairs | <code>Array</code> |  | An array of key, description pairs |
+| opts | <code>object</code> |  |  |
+| [opts.description] | <code>string</code> | <code>null</code> | description for the function |
+| [opts.function_string] | <code>string</code> | <code>null</code> | optional string of function source code to pass to parameter_parser |
-| Param | Type | Description |
-| --- | --- | --- |
-| path | <code>String</code> | a path string to check against |
+<a name="Entangld+call_rpc"></a>
-<a name="Subscription+matches_uuid"></a>
+### entangld.call\_rpc(path, [args]) ⇒ <code>Promise</code>
+Call an RPC procedure in the datastore
-### subscription.matches\_uuid(uuid) ⇒ <code>Boolean</code>
-Check if a provided uuid matches this uuid
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Returns**: <code>Promise</code> - promise resolving to return value of the rpc
+**Throws**:
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - true if the path matches
+- [<code>RPCError</code>](#RPCError) if the rpc call experienced an error
-| Param | Type | Description |
-| --- | --- | --- |
-| uuid | <code>Uuid</code> | a uuid string to check against |
-<a name="Subscription+is_beneath"></a>
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| path | <code>string</code> |  | the path to query (like "system.voltage"). |
+| [args] | <code>Array</code> | <code>[]</code> | the arguments to pass to the RPC. |
-### subscription.is\_beneath(path) ⇒ <code>Boolean</code>
-Check if subscription path is beneath a provided path
+<a name="Entangld+get"></a>
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - true if the subscription is beneath the path
+### entangld.get(path, [params]) ⇒ <code>Promise</code>
+Get an object from the store.
-| Param | Type | Description |
-| --- | --- | --- |
-| path | <code>String</code> | a path string to check against |
+Note: using max_depth, especially large max_depth, involves a lot of
+recursion and may be expensive.
-<a name="Subscription+is_above"></a>
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Returns**: <code>Promise</code> - promise resolving to the object at that path.
+**Throws**:
-### subscription.is\_above(path) ⇒ <code>Boolean</code>
-Check if subscription path is above a provided path
+- <code>TypeError</code> if path is not a string.
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: <code>Boolean</code> - - true if the subscription is beneath the path
 | Param | Type | Description |
 | --- | --- | --- |
-| path | <code>String</code> | a path string to check against |
-<a name="Subscription+static_copy"></a>
-### subscription.static\_copy() ⇒ [<code>Subscription</code>](#Subscription)
-Get a copy of this subscription without external references
-This creates a copy, except the upstream/downstream references
-are set to true (if they exist) or null (if they don't. Addtionally,
-the callback function is excluded.
+| path | <code>string</code> | the path to query (like "system.voltage"). |
+| [params] | <code>object</code> | the parameters to be passed to the remote function (RPC) or the maximum depth of the returned object (normal mode). |
-**Kind**: instance method of [<code>Subscription</code>](#Subscription)
-**Returns**: [<code>Subscription</code>](#Subscription) - a copy of this subscription object
-<a name="Entangld"></a>
+<a name="Entangld+subscribe"></a>
-## Entangld ⇐ <code>EventEmitter</code>
-Synchronized Event Store
+### entangld.subscribe(path, func, [every]) ⇒ <code>uuidv4</code>
+Subscribe to change events for a path
-**Kind**: global class
-**Extends**: <code>EventEmitter</code>
+If objects at or below this path change, you will get a callback
-* [Entangld](#Entangld) ⇐ <code>EventEmitter</code>
-    * [.namespaces](#Entangld+namespaces) ⇒ <code>array</code>
-    * [.subscriptions](#Entangld+subscriptions) ⇒ [<code>Array.&lt;Subscription&gt;</code>](#Subscription)
-    * [.namespace()](#Entangld+namespace) ⇒ <code>string</code>
-    * [.attach(namespace, obj)](#Entangld+attach)
-    * [.detach([namespace], [obj])](#Entangld+detach) ⇒ <code>boolean</code>
-    * [.transmit(func)](#Entangld+transmit)
-    * [.receive(msg, obj)](#Entangld+receive)
-    * [.push(path, data, [limit])](#Entangld+push)
-    * [.set(path, data, [operation_type], [params])](#Entangld+set)
-    * [.get(path, [params])](#Entangld+get) ⇒ <code>Promise</code>
-    * [.subscribe(path, func, [every])](#Entangld+subscribe) ⇒ <code>Uuid</code>
-    * [.subscribed_to(subscription)](#Entangld+subscribed_to) ⇒ <code>Boolean</code>
-    * [.unsubscribe(path_or_uuid)](#Entangld+unsubscribe) ⇒ <code>number</code>
-    * [.unsubscribe_tree(path)](#Entangld+unsubscribe_tree)
+Subscriptions to keys within attach()ed stores are remote subscriptions.
+If several stores are attached in some kind of arrangement, a given key
+may actually traverse multiple stores!  Since each store only knows its
+immediate neighbors - and has no introspection into those neighbors - each
+store is only able to keeps track of the neighbor on each side with
+respect to a particular path and has no knowledge of the eventual
+endpoints.  This means that subscribing across several datstores is accomplished
+by daisy-chaining 2-way subscriptions across each datastore interface.
-<a name="Entangld+namespaces"></a>
+For example, let's suppose capital letters represent Entangld stores and
+lowercase letters are actual objects.  Then  the path "A.B.c.d.E.F.g.h"
+will represent a subscription that traverses four Entangld stores.
+From the point of view of a store in the middle - say, E - the "upstream"
+is B and the "downstream" is F.
-### entangld.namespaces ⇒ <code>array</code>
-Get namespaces
+Each store involved keeps track of any subscriptions with which it is
+involved.  It tracks the upstream and downstream, and the uuid of the
+subscription.  The uuid is the same across all stores for a given
+subscription.  For a particular store, the upstream is null if it is the
+original link in the chain (called the `head`), and the downstream is
+null if this store owns the endpoint value (called the `tail`). Any
+subscription which is not the head of a chain is called a `pass through`
+subscription, because it exist only to pass `event` messages back up the
+chain to the head (where the user-provided callback function exists).
+subscriptions can be checked to see if they are `pass through` type via
+the getter `sub.is_pass_through`.
-**Kind**: instance property of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>array</code> - namespaces - an array of attached namespaces
-**Read only**: true
-<a name="Entangld+subscriptions"></a>
+**Kind**: instance method of [<code>Entangld</code>](#Entangld)
+**Returns**: <code>uuidv4</code> - - the uuid of the subscription
+**Throws**:
-### entangld.subscriptions ⇒ [<code>Array.&lt;Subscription&gt;</code>](#Subscription)
-Get list of subscriptions associated with this object
+- <code>TypeError</code> if path is not a string.
-Note, this will include `head`, `terminal` and `pass through` subscriptions,
-which can be checked using getter methods of the subscription object.
-**Kind**: instance property of [<code>Entangld</code>](#Entangld)
-**Returns**: [<code>Array.&lt;Subscription&gt;</code>](#Subscription) - array of Subscriptions associated with this object
-**Read only**: true
-<a name="Entangld+namespace"></a>
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| path | <code>string</code> |  | the path to watch.  Use of '*' is allowed as a wildcard (e.g. "system.*") |
+| func | <code>function</code> |  | the callback - will be of the form (path, value). |
+| [every] | <code>number</code> \| <code>null</code> | <code></code> | the number of `set` messages to wait before calling callback |
-### entangld.namespace() ⇒ <code>string</code>
-Get namespace for a store
+<a name="Entangld+subscribed_to"></a>
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>string</code> - namespace for the given store
-**Read only**: true
-<a name="Entangld+attach"></a>
+### entangld.subscribed\_to(subscription) ⇒ <code>Boolean</code>
+Check for subscription
-### entangld.attach(namespace, obj)
-Attach a namespace and a store
+Are we subscribed to a particular remote path?
 **Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Throws**:
-- <code>TypeError</code> if namespace/obj is null or empty.
-- [<code>EntangldError</code>](#EntangldError) if you try to attach to the same namespace twice.
+**Returns**: <code>Boolean</code> - true if we are subscribed.
 | Param | Type | Description |
 | --- | --- | --- |
-| namespace | <code>string</code> | a namespace for this store. |
-| obj | <code>object</code> | an object that will be sent along with "transmit" callbacks when we need something from this store. |
+| subscription | <code>String</code> | the subscription to check for. |
-<a name="Entangld+detach"></a>
+<a name="Entangld+unsubscribe"></a>
-### entangld.detach([namespace], [obj]) ⇒ <code>boolean</code>
-Detach a namespace / obj pair.
+### entangld.unsubscribe(path_or_uuid) ⇒ <code>number</code>
+Unubscribe to change events for a given path or uuid.
-If you only pass a namespace or a store, it will find the missing item
-before detaching.
+Caution - if a path is provided, _all_ events belonging to you with that
+path will be deleted, so if you have multiple subscriptions on a single path,
+and only want one of them to be removed, you must provide the uuid instead.
 **Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>boolean</code> - true if the element existed and was removed.
+**Returns**: <code>number</code> - count of subscriptions removed.
 **Throws**:
-- [<code>EntangldError</code>](#EntangldError) Error will be thrown if you don't pass at least
-one parameter.
+- [<code>EntangldError</code>](#EntangldError) if no subscriptions were found.
 | Param | Type | Description |
 | --- | --- | --- |
-| [namespace] | <code>string</code> | the namespace. |
-| [obj] | <code>object</code> | the store object. |
+| path_or_uuid | <code>String</code> \| <code>uuidv4</code> | the path (or uuid) to unwatch. |
-<a name="Entangld+transmit"></a>
+<a name="Entangld+unsubscribe_tree"></a>
-### entangld.transmit(func)
-Transmit
+### entangld.unsubscribe\_tree(path)
+Unsubscribe tree.
-Specify a callback to be used so we can transmit data to another store.
-Callback will be passed (message, obj) where 'message' is an
-Entangld_Message object and obj is the object provided by attach().
+Remove any subscriptions that are beneath a path.
 **Kind**: instance method of [<code>Entangld</code>](#Entangld)
 **Throws**:
-- <code>TypeError</code> if func is not a function.
+- [<code>EntangldError</code>](#EntangldError) error if there are stores we cannot detach
+(i.e. they belong to someone else / upstream != null)
 | Param | Type | Description |
 | --- | --- | --- |
-| func | <code>function</code> | the callback function. |
+| path | <code>string</code> | the tree to unwatch. |
-<a name="Entangld+receive"></a>
+<a name="EntangldError"></a>
-### entangld.receive(msg, obj)
-Receive
+## EntangldError
+Error class for Entangld.
-Call this function with the data that was sent via the transmit()
-callback.
+**Kind**: global class
+<a name="RPCError"></a>
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Throws**:
+## RPCError
+Remote Error class for Entangld.
-- <code>ReferenceError</code> if event object was not provided.
-- [<code>EntangldError</code>](#EntangldError) if an unknown message type was received.
+**Kind**: global class
+<a name="Entangld_Message"></a>
+## Entangld\_Message
+Message class for Entangld.
+These messages are used for executing datastore operations between
+remote datastores. In these relationships, there is always an upstream
+and downstream pair, so that `get`, `set`, `push` and `subscribe` messages
+are created upstream and passed downstream while `event` and `value` messages
+are created downstream and are passed back up. `unsubscribe` events can travel
+in both directions. To maintain consistency, the internal `.path` attribute
+will always refer a path relative to the downstream datastore, since the
+downstream datastores do not necessarilly have access to the upstream store
+structure, and so cannot generally construct upstream paths. This means that
+the `.path` attribute is a `tree` relative to the upstream datastore, and
+the upstream path can be reconstructed as:
+```javascript
+ > upstream._namespaces.get(downstream) + "." + msg.path;
+```
+Since `unsubscribe` messages can pass either upstream or downstream, the notion
+of a path is ill-defined, and so unsubscribe messages should have their `.path`
+attributes set to undefined or null.
+Most messages will also have a `.uuid` attribute. For `get`/`value` messages,
+this allows for the value to be properly linked back up with the original `get`
+message. For the `subscribe`/`unsubscribe`/`event` messages, this allows for
+callback functions to be trigger properly, and for unsubscribe messages to
+propogate both directions. `set`/`push` messages do not use the `.uuid` attribute
+since they require no response.
+**Kind**: global class
+* [Entangld_Message](#Entangld_Message)
+    * [.get(tree, [get_params])](#Entangld_Message.get) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+    * [.value(get_msg, value)](#Entangld_Message.value) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+    * [.setpush(obj)](#Entangld_Message.setpush) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+    * [.subscribe(tree, uuid)](#Entangld_Message.subscribe) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+    * [.event(path, value, uuid)](#Entangld_Message.event) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+    * [.unsubscribe(uuid)](#Entangld_Message.unsubscribe)
+<a name="Entangld_Message.get"></a>
+### Entangld_Message.get(tree, [get_params]) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+Create a `get` message for remote datastores
+**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
+**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - - The get message to pass to the remote datastore
 | Param | Type | Description |
 | --- | --- | --- |
-| msg | [<code>Entangld\_Message</code>](#Entangld_Message) | the message to process. |
-| obj | <code>object</code> | the attach() object where the message originted. |
+| tree | <code>string</code> | the path relative to the remote datastore |
+| [get_params] | <code>\*</code> | any parameters to be passed to the                                        remote datastore's local get function |
-<a name="Entangld+push"></a>
+<a name="Entangld_Message.value"></a>
-### entangld.push(path, data, [limit])
-Push an object into an array in the store.
+### Entangld_Message.value(get_msg, value) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+Create a `value` message in response to a `get` message
-Convenience method for set(path, o, "push").
+**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
+**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - - The `value` message to pass back
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Throws**:
+| Param | Type | Description |
+| --- | --- | --- |
+| get_msg | [<code>Entangld\_Message</code>](#Entangld_Message) | the `get` message which this is in response to |
+| value |  | the value of the `get` |
-- <code>TypeError</code> if path is not a string.
+<a name="Entangld_Message.setpush"></a>
+### Entangld_Message.setpush(obj) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+Create a `set`/`push` message for a remote datastore
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| path | <code>string</code> |  | the path to set (like "system.fan.voltage"). |
-| data | <code>object</code> |  | the object or function you want to store at path. |
-| [limit] | <code>number</code> | <code></code> | maximum size of the array. Older entries will be removed until the array size is less than or equal to limit. |
+**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
+**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - - the "set" or "push" message
-<a name="Entangld+set"></a>
+| Param | Type | Description |
+| --- | --- | --- |
+| obj | <code>Object</code> | The parameter object for the set/push |
+| obj.type | <code>string</code> | either "set" or "push" |
+| obj.tree | <code>string</code> | the path (relative to the downstream datastore) |
+| obj.value | <code>\*</code> | the value to insert into the datastore |
+| obj.params | <code>\*</code> | any additional parameters |
-### entangld.set(path, data, [operation_type], [params])
-Set an object into the store
+<a name="Entangld_Message.subscribe"></a>
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Throws**:
+### Entangld_Message.subscribe(tree, uuid) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+Construct subscribe message
-- <code>TypeError</code> if path is not a string.
+**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
+**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - the `subscribe` message
+| Param | Type | Description |
+| --- | --- | --- |
+| tree | <code>string</code> | the path (relative to the downstream datastore) |
+| uuid | <code>uuidv4</code> | the subscription uuid |
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| path | <code>string</code> |  | the path to set (like "system.fan.voltage"). |
-| data | <code>object</code> |  | the object or function you want to store at path. |
-| [operation_type] | <code>string</code> | <code>&quot;\&quot;set\&quot;&quot;</code> | whether to set or push the new data (push only works if the data item exists and is an array). |
-| [params] | <code>object</code> |  | additional parameters. |
+<a name="Entangld_Message.event"></a>
-<a name="Entangld+get"></a>
+### Entangld_Message.event(path, value, uuid) ⇒ [<code>Entangld\_Message</code>](#Entangld_Message)
+Create an `event` message to return data to subscribe callbacks
-### entangld.get(path, [params]) ⇒ <code>Promise</code>
-Get an object from the store.
+**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
+**Returns**: [<code>Entangld\_Message</code>](#Entangld_Message) - the `event` message
-Note: using max_depth, especially large max_depth, involves a lot of
-recursion and may be expensive.
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | the path (relative to the downstream store) |
+| value | <code>\*</code> | the updated datastore value at the path |
+| uuid | <code>uuidv4</code> | the uuid of the subscribe being triggered |
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>Promise</code> - promise resolving to the object at that path.
-**Throws**:
+<a name="Entangld_Message.unsubscribe"></a>
-- <code>TypeError</code> if path is not a string.
+### Entangld_Message.unsubscribe(uuid)
+Create an unsubscribe message for a subscription uuid
+**Kind**: static method of [<code>Entangld\_Message</code>](#Entangld_Message)
 | Param | Type | Description |
 | --- | --- | --- |
-| path | <code>string</code> | the path to query (like "system.voltage"). |
-| [params] | <code>object</code> | the parameters to be passed to the remote function (RPC) or the maximum depth of the returned object (normal mode). |
+| uuid | <code>String</code> | the subscription uuid |
-<a name="Entangld+subscribe"></a>
+<a name="Subscription"></a>
-### entangld.subscribe(path, func, [every]) ⇒ <code>Uuid</code>
-Subscribe to change events for a path
+## Subscription
+A datastore subscription object
-If objects at or below this path change, you will get a callback
+**Kind**: global class
-Subscriptions to keys within attach()ed stores are remote subscriptions.
-If several stores are attached in some kind of arrangement, a given key
-may actually traverse multiple stores!  Since each store only knows its
-immediate neighbors - and has no introspection into those neighbors - each
-store is only able to keeps track of the neighbor on each side with
-respect to a particular path and has no knowledge of the eventual
-endpoints.  This means that subscribing across several datstores is accomplished
-by daisy-chaining 2-way subscriptions across each datastore interface.
+* [Subscription](#Subscription)
+    * [new Subscription(obj)](#new_Subscription_new)
+    * [.is_pass_through](#Subscription+is_pass_through) ⇒ <code>Boolean</code>
+    * [.is_terminal](#Subscription+is_terminal) ⇒ <code>Boolean</code>
+    * [.is_head](#Subscription+is_head) ⇒ <code>Boolean</code>
+    * [.has_downstream](#Subscription+has_downstream) ⇒ <code>Boolean</code>
+    * [.has_upstream](#Subscription+has_upstream) ⇒ <code>Boolean</code>
+    * [.call()](#Subscription+call)
+    * [.matches_subscription(sub)](#Subscription+matches_subscription) ⇒ <code>Boolean</code>
+    * [.matches_event_message(msg)](#Subscription+matches_event_message) ⇒ <code>Boolean</code>
+    * [.matches_unsubscribe_message(msg)](#Subscription+matches_unsubscribe_message) ⇒ <code>Boolean</code>
+    * [.matches_path(path)](#Subscription+matches_path) ⇒ <code>Boolean</code>
+    * [.matches_uuid(uuid)](#Subscription+matches_uuid) ⇒ <code>Boolean</code>
+    * [.is_beneath(path)](#Subscription+is_beneath) ⇒ <code>Boolean</code>
+    * [.is_above(path)](#Subscription+is_above) ⇒ <code>Boolean</code>
+    * [.static_copy()](#Subscription+static_copy) ⇒ [<code>Subscription</code>](#Subscription)
-For example, let's suppose capital letters represent Entangld stores and
-lowercase letters are actual objects.  Then  the path "A.B.c.d.E.F.g.h"
-will represent a subscription that traverses four Entangld stores.
-From the point of view of a store in the middle - say, E - the "upstream"
-is B and the "downstream" is F.
+<a name="new_Subscription_new"></a>
-Each store involved keeps track of any subscriptions with which it is
-involved.  It tracks the upstream and downstream, and the uuid of the
-subscription.  The uuid is the same across all stores for a given
-subscription.  For a particular store, the upstream is null if it is the
-original link in the chain (called the `head`), and the downstream is
-null if this store owns the endpoint value (called the `tail`). Any
-subscription which is not the head of a chain is called a `pass through`
-subscription, because it exist only to pass `event` messages back up the
-chain to the head (where the user-provided callback function exists).
-subscriptions can be checked to see if they are `pass through` type via
-the getter `sub.is_pass_through`.
+### new Subscription(obj)
+Constructor
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>Uuid</code> - - the uuid of the subscription
-**Throws**:
+**Returns**: [<code>Subscription</code>](#Subscription) - - the subscription object
-- <code>TypeError</code> if path is not a string.
+| Param | Type | Description |
+| --- | --- | --- |
+| obj | <code>Object</code> | the configuration object |
+| obj.path | <code>string</code> | the datastore path (relative to this datastore)                             of the subscription |
+| obj.uuid | <code>uuidv4</code> | the uuid of the subscription chain |
+| obj.callback | <code>function</code> | the callback function, with signature (path, value),                               where path is relative to this datastore |
+| obj.downstream | [<code>Entangld</code>](#Entangld) \| <code>null</code> | the downstream datastore (if any)                                          associated with this subscription |
+| obj.upstream | [<code>Entangld</code>](#Entangld) \| <code>null</code> | the upstream datastore (if any)                                          associated with this subscription |
+| obj.every | <code>number</code> \| <code>null</code> | how many `set` messages to wait before calling callback |
+<a name="Subscription+is_pass_through"></a>
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| path | <code>string</code> |  | the path to watch. |
-| func | <code>function</code> |  | the callback - will be of the form (path, value). |
-| [every] | <code>number</code> \| <code>null</code> | <code></code> | the number of `set` messages to wait before calling callback |
+### subscription.is\_pass\_through ⇒ <code>Boolean</code>
+Check if subscription is a `pass through` type
-<a name="Entangld+subscribed_to"></a>
+Pass throughs are as the links in a chain of subscriptions to allows
+subscriptions to remote datastores. One store acts as the `head`, where
+the callback function is registered, an all others are `path through` datastores
+which simply pass event messages back up to the head subscription.
-### entangld.subscribed\_to(subscription) ⇒ <code>Boolean</code>
-Check for subscription
+**Kind**: instance property of [<code>Subscription</code>](#Subscription)
+<a name="Subscription+is_terminal"></a>
-Are we subscribed to a particular remote path?
+### subscription.is\_terminal ⇒ <code>Boolean</code>
+Check if this subscription will be directly given data by a datastore
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>Boolean</code> - true if we are subscribed.
+**Kind**: instance property of [<code>Subscription</code>](#Subscription)
+<a name="Subscription+is_head"></a>
+### subscription.is\_head ⇒ <code>Boolean</code>
+Check if this subscription will apply a user-supplied callback to data
+**Kind**: instance property of [<code>Subscription</code>](#Subscription)
+<a name="Subscription+has_downstream"></a>
+### subscription.has\_downstream ⇒ <code>Boolean</code>
+Check if subscription has any downstream subscriptions
+It the subscription refers to a remote datastore (the downstream), this
+getter will return a true. Note that !this.has_downstream will check if
+the subscription is the `tail` subscription object in a subscription chain.
+**Kind**: instance property of [<code>Subscription</code>](#Subscription)
+<a name="Subscription+has_upstream"></a>
+### subscription.has\_upstream ⇒ <code>Boolean</code>
+Check if subscription has any upstream subscriptions
+It the subscription passes data back to a remote datastore (the upstream), this
+getter will return a true.
+**Kind**: instance property of [<code>Subscription</code>](#Subscription)
+<a name="Subscription+call"></a>
+### subscription.call()
+Apply this callback function
+Note, this method also tracks the number of times that a callback
+function is called (if this subscription is terminal), so that if
+the subscriptions are throttled by specifying an `this.every`,
+this method will only call the callback function every `this.every`
+times it receives a `set` message. If this subscription is not
+terminal, then the callback function is called every time.
+This method also is safed when a callback function is not give (i.e.
+by the `this.static_copy()` method).
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+<a name="Subscription+matches_subscription"></a>
+### subscription.matches\_subscription(sub) ⇒ <code>Boolean</code>
+Check if a different `Subscription` object matches this subscription
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - True if the subscriptions match
 | Param | Type | Description |
 | --- | --- | --- |
-| subscription | <code>String</code> | the subscription to check for. |
+| sub | [<code>Subscription</code>](#Subscription) | a different subscription |
-<a name="Entangld+unsubscribe"></a>
+<a name="Subscription+matches_event_message"></a>
-### entangld.unsubscribe(path_or_uuid) ⇒ <code>number</code>
-Unubscribe to change events for a given path or uuid.
+### subscription.matches\_event\_message(msg) ⇒ <code>Boolean</code>
+Check if an `event` message matches this subscription
-Caution - if a path is provided, _all_ events belonging to you with that
-path will be deleted, so if you have multiple subscriptions on a single path,
-and only want one of them to be removed, you must provide the uuid instead.
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - True if the message is associated with the subscription
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Returns**: <code>number</code> - count of subscriptions removed.
-**Throws**:
+| Param | Type | Description |
+| --- | --- | --- |
+| msg | [<code>Entangld\_Message</code>](#Entangld_Message) | a received message from a downstream datastore |
-- [<code>EntangldError</code>](#EntangldError) if no subscriptions were found.
+<a name="Subscription+matches_unsubscribe_message"></a>
+### subscription.matches\_unsubscribe\_message(msg) ⇒ <code>Boolean</code>
+Check if an `unsubscribe` message matches this subscription
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - True if the message is associated with the subscription
 | Param | Type | Description |
 | --- | --- | --- |
-| path_or_uuid | <code>String</code> \| <code>Uuid</code> | the path (or uuid) to unwatch. |
+| msg | [<code>Entangld\_Message</code>](#Entangld_Message) | a received message from a downstream datastore |
-<a name="Entangld+unsubscribe_tree"></a>
+<a name="Subscription+matches_path"></a>
-### entangld.unsubscribe\_tree(path)
-Unsubscribe tree.
+### subscription.matches\_path(path) ⇒ <code>Boolean</code>
+Check if a provided path matches this path
-Remove any subscriptions that are beneath a path.
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - true if the path matches
-**Kind**: instance method of [<code>Entangld</code>](#Entangld)
-**Throws**:
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>String</code> | a path string to check against |
-- [<code>EntangldError</code>](#EntangldError) error if there are stores we cannot detach
-(i.e. they belong to someone else / upstream != null)
+<a name="Subscription+matches_uuid"></a>
+### subscription.matches\_uuid(uuid) ⇒ <code>Boolean</code>
+Check if a provided uuid matches this uuid
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - true if the path matches
 | Param | Type | Description |
 | --- | --- | --- |
-| path | <code>string</code> | the tree to unwatch. |
+| uuid | <code>uuidv4</code> | a uuid string to check against |
+<a name="Subscription+is_beneath"></a>
+### subscription.is\_beneath(path) ⇒ <code>Boolean</code>
+Check if subscription path is beneath a provided path
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - true if the subscription is beneath the path
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>String</code> | a path string to check against |
+<a name="Subscription+is_above"></a>
+### subscription.is\_above(path) ⇒ <code>Boolean</code>
+Check if subscription path is above a provided path
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: <code>Boolean</code> - - true if the subscription is beneath the path
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>String</code> | a path string to check against |
+<a name="Subscription+static_copy"></a>
+### subscription.static\_copy() ⇒ [<code>Subscription</code>](#Subscription)
+Get a copy of this subscription without external references
+This creates a copy, except the upstream/downstream references
+are set to true (if they exist) or null (if they don't. Addtionally,
+the callback function is excluded.
+**Kind**: instance method of [<code>Subscription</code>](#Subscription)
+**Returns**: [<code>Subscription</code>](#Subscription) - a copy of this subscription object
 ## TODO
 - Make sure incoming values request store doesn't build up