rapids-active-doc

Share and coordinate data amongst runs. Active documents store data, verify that data using a schema and allow for actions to be run when certain conditions are met.

Installation

1. Add the following to your project dependencies:

   [precisely/rapids-active-doc "0.0.1"]

2. Ensure you have something like the following in your project.clj file:

   :repositories {"precisely" {:url        "s3p://precisely-maven-repo/"
                              :username   #=(eval (System/getenv "MAVEN_REPO_AWS_ACCESS_KEY_ID"))
                              :passphrase #=(eval (System/getenv "MAVEN_REPO_AWS_ACCESS_KEY_SECRET"))}}

   Where your environment has the access key and secret set appropriately (ask Aneil or Constantine)

Usage

Active doc stores hierarchical data, accessible by set-data! and get-data. The add-actions and remove-actions methods allow detecting changes to the data and acting on them. The monitor-doc macro uses these methods to detect and handle changes made by other runs within a body of code.

Note that since the active doc is in fact a rapids Run, the set-index! method may be used with it.

Example

(ns myns 
  (:require [rapids.active-doc :as adoc]))
  
(deflow main []
  (let [doc (adoc/create!)]
    (set-data! doc [:foo :bar] "initial") ; (get-data doc) => {:foo {:bar "initial"}}
    (monitor-doc [doc {:when (fn [changes _] (if (get-in changes [:foo :bar]) true))
                       :handle (flow [i] (handle-the-change))}]
      ;; code here can be interrupted by a change to the document
     )))

create!

Creates an active document - takes optional keyword arguments.

(create! :data {:foo 1} :schema [:map [:foo :int]] 
         :actions {:foo-greater-than-10 (fn [changes _] 
                                          (if (and (contains? changes :foo) (> 10 (:foo changes)))
                                            (send-alert!)))
         :index {:type :foo-document})
; data - an optional map representing the data
; schema - an optional malli schema
; actions - an optional map of keywords to closures
; index - for indexing the document"

get-data

Gets data from the active-doc.

(get-data adoc :foo :bar) ; Equivalent to (get-in (get-data adoc) [:foo :bar])

Get all the data by providing an empty sequence or dropping the second argument:

(get-data adoc []) ; empty sequence
(get-data adoc) ; or no second argument

set-data!

Sets data in the active doc.

(set-data! adoc [:foo :bar] 1 :baz 3) ; data is now {:foo {:bar 1} :baz 3}

add-actions!

Adds one or more functions to the active doc. These functions will be called whenever a change is made (using set-data!).

(add-actions! adoc 
   :foo-change (fn [changes original] 
                 (if (contains? changes :foo)
                   (do-something))))

remove-actions!

Removes one or more actions added with add-actions!:

(remove-actions! adoc :foo-change :baz-too-low)

monitor-doc

Monitors an active-doc for one or more changes and trigger a corresponding interruption. Code inside the body of this macro may be interrupted when the active doc is changed by other runs or by the code in the body.

  (monitor-doc [adoc {:when (fn [changes original] 
                               (if (:foo changes) 
                                 :value-passed-to-interruption-data
                      :handle (flow [i] (do-something-with (:data i)))}]
    (do-things))

License

Copyright © 2022 Precise.ly, Inc

All rights reserved