ribelo.doxa — com.github.ribelo/doxa 0.1.160

-entity-lookup clj/s

(-entity-lookup dx ref k denormalize?)

This function is used for looking up entities in the Doxa database, with an option to denormalize the references. It's an internal function, not intended for public use.

-submit-commit clj/s multimethod

'-submit-commit', is used to commit changes to the in-memory database. It's an internal function, not intended for public use.

Arguments

• db: the current state of the in-memory database.
• tx (^clojure.lang.IPersistentVector): This is a persistent vector in Clojure that holds the transaction information.

The dispatch function provided to defmulti is a function that takes the same arguments as '-submit-commit' and returns a value. This returned value is used to decide which method implementation will be used for a given set of arguments.

Returns

• This function return a updated db. Its purpose is to commit the changes given by the transaction 'tx' to the database _db.

Examples

This function's usage will highly depend on how it has been designed to interact with your specific in-memory database keeping in mind the transactional context. Therefore, providing a generalizable example wouldn't be feasible.

-submit-failure clj/s multimethod

This Clojure code consists of a multifunction for defining custom errors in response to specific types of transactions in a Doxa database.

Arguments

• tx: This should be a vector. The first element of the vector is read as the transaction type, while the second element and onwards may hold relevant transaction data.
• msg: This is an optional argument that specifies a custom error message, replacing any default message.

commit clj/s

(commit dx txs)

(commit dx txs meta')

This function, commit, is designed to handle the transactions to be processed within the Doxa database.

Arguments

• dx: Doxa database where the transactions will be processed.
• txs: Sequence of transactions to be committed. Each transaction is an array with a keyword at the first position representing the kind of transaction.
• meta' - (Optional) Any metadata associated with the operation.

This function goes through each transaction and depending upon its kind, commits it to the Doxa database. It has built-in error checking functionalities to prevent the application from crashing when encountering invalid transactions in the list. Once all transactions are processed, any listeners in the database are notified with the updated state.

This function also handles caching and reindexing in the database, which are imperative for performance improvement and efficient data retrieval.

Examples

(def dx (empty-dx))
(def txs [[:dx/put {:dx/id 1 :name "Alice"}] [:dx/put {:dx/id 2 :name "Bob"}]])
(commit dx txs)
; Updated Doxa database with inserted data {"Alice", "Bob"}.

commit! clj/s

(commit! conn_ txs)

This function is intended to commit transactions to the given db in place. For more look at [commit].

connect! clj/s

(connect! dx)

(connect! dx x)

This function is used to establish a connection in a data-oriented context. This function's usage would largely depend on specific use-case and implementation of p/-connect

create-dx clj/s

(create-dx)

(create-dx empty-db)

(create-dx empty-db data)

(create-dx empty-db data meta)

This function create a new instance of Doxa(a.k.a. dx), an in-memory immutable database.

Arguments

• empty-db: (map) represents an optional map that will be populated by the data parameter. Has a default value of {} if left undefined.

• data: (seq) contains an optional sequence of data (which can be queries, rules or facts) to populate the empty-db. Has a default value of [] if left undefined.

• meta: (map) is used for any additional metadata that should be associated with the DX instance. By default, will provide an atom enclosing an empty map to capture any potential listeners.

Returns

• Returns a new database by merging the data and metadata into the passed empty-db map or a default empty Db. If no data is passed, it returns the updated meta passed to it or a default meta.

Examples

(create-dx)
; => returns a new db with default meta

(create-dx {} [{:id 1, :name "doxa"}] {:meta-key "meta-value"})
; => {[:id 1] {:id 1, :name "doxa"}}

denormalize clj/s

dx-with clj/s

(dx-with data)

(dx-with dx data)

This function is to perform a batch update or insertion in a Doxa (DX) database. It takes a Doxa instance and a vector of maps, which represent the data which will be merged into the Doxa instance. If the Doxa instance is not provided, it will create a new one.

Arguments

• dx: (optional, map) the current Doxa instance (database state). If it's not passed, the function will use an empty map {}
• data: (vector of maps) each map represents an entity to be added.

Returns

• It returns a new Doxa instance (a new database state) with the data merged in.

Examples

(def data [{:id 1, :author "Author 1", :book "Book 1"} {:id 2, :author "Author 2", :book "Book 2"}])

(dx-with data)
; => Returns a Doxa instance containing the provided data

(def dx {:example "Existing data"})

(dx-with dx data)
; => Returns a Doxa instance merging the existing Doxa instance and the new data

dx? clj/s

entity clj/s

(entity dx ref)

(entity dx ref {:keys [denormalize?]})

This function, entity, is a core part of the Doxa database. It provides a dynamic view on a specific entity in the database. The function is overloaded, meaning it can be called with different numbers of arguments.

The function uses the reify macro to create an instance of an anonymous type that implements specific interfaces. This allows the function to return a dynamic view on an entity, which can be interacted with as if it were a map.

The interfaces implemented are different for Clojure and ClojureScript due to differences in the language.

Clojure, interfaces

• clojure.lang.ILookup: This allows the entity to be used like a map, where a key can be used to retrieve a value.

• clojure.lang.Associative: This allows a key-value pair to be added to the entity.

• clojure.lang.IDeref: This allows the entity to be dereferenced, returning the entity itself.

ClojureScript interfaces

• IMap: This allows the entity to be used like a map.

• IPrintWithWriter: This allows the entity to be printed.

• ILookup: This allows a key to be used to retrieve a value from the entity.

• IAssociative: This allows a key-value pair to be added to the entity.

• IDeref: This allows the entity to be dereferenced, returning the entity itself.

Arguments

• dx: (Doxa) The Doxa database instance.
• ref: ([k v]) The reference to the entity in the database.
• An optional map with the key denormalize? which indicates whether the entity should be denormalized.

listen! clj/s

(listen! dx k f)

This function registers a listener for a Doxa datastore and returns another function to remove the listener once it's no longer needed.

Arguments

• dx: (atom) a Doxa instance where listeners are registered. It should be an atom containing a Doxa database
• k: (keyword) unique identifier of the listener. Makes sure your listener can be later identified
• f: (function) listener's function. It would be invoked with Doxa instance every time a transaction is committed in dx

Returns

• a function with no arguments that would remove the listener k when called

Examples

(def dx (create-dx))
(defn test-listener [dx] (println "Something has changed"))
(def remove-listener (listen! dx :test-listener test-listener))
; After every committed transaction in `dx`, "Something has changed" will be printed

; when you want to stop observing
(remove-listener)

Exception

• this function will throw an exception if dx does not have a metadata entry for ::listeners. The exception's data will contain the metadata of dx.

mpull clj/s

mq clj/s

normalize clj/s

pick clj/s

pull clj/s

q clj/s

table clj/s

(table dx table)

This function retrieves a specific table from the Doxa database.

Arguments

• dx: (Doxa instance) the Doxa database instance from which to retrieve the table.
• table: (keyword) the keyword identifier of the table to retrieve. The format is :table-namespace/id.

Returns

• If the table exists in the Doxa instance, it returns a new Doxa instance containing only the specified table and its associated data.
• If the table does not exist, it returns an empty Doxa instance.

Examples

(def dx (doxa/db {:table-namespace/id {:a 1, :b 2}}))
(table dx :table-namespace/id)
;; => TODO:

(def dx (doxa/db {:table-namespace/id {:a 1, :b 2}}))
(table dx :non-existent-table)
;; => TODO:

unlisten! clj/s

(unlisten! dx k)

This function is designed to remove a specific listener from the doxa.

Arguments

• dx: (Doxa) - Doxa instance from which we want to remove a listener
• k: any valid Clojure value

Returns

If successful, it returns true if listener exists or false, if not.

Otherwise, it throws an exception with a message that indicates the listener cannot be removed because the atom (in which listeners are stored) does not exist. The metadata of the Doxa instance is attached to the exception data.

Example

(unlisten! dx :listener-key)
;; => true