Document stores, which keep named documents with versions, e.g. the sync documents of a user's devices, or anything else an app saves.
A store is a map of functions over named documents with versions:
{:fetch (fn [name opts]) ; {:body "…" :version "…"}, or nil
:put (fn [name body opts]) ; {:version "…"}, or {:conflict? true}
:list (fn []) ; [{:name "…" :version "…"}], optional
:delete (fn [name]) ; optional
:name "Nextcloud"} ; for the UI and the report
A body is text or bytes, a byte array on the JVM and a Uint8Array in JavaScript. A fetch gives it as text, or as bytes with :as :bytes in its opts, whichever was put. A put is a conflict when its opts have an :if-version other than the store's, where nil means that the document must not exist yet. A store that can't be written, e.g. over the files of an input, has no :put.
On the JVM, each function returns its value and throws when it fails. In ClojureScript, each can return a value or a promise. A store closes over its credentials, so they're never in the map, and you wrap a store by updating a key.
Document stores, which keep named documents with versions, e.g. the
sync documents of a user's devices, or anything else an app saves.
A store is a map of functions over named documents with versions:
{:fetch (fn [name opts]) ; {:body "…" :version "…"}, or nil
:put (fn [name body opts]) ; {:version "…"}, or {:conflict? true}
:list (fn []) ; [{:name "…" :version "…"}], optional
:delete (fn [name]) ; optional
:name "Nextcloud"} ; for the UI and the report
A body is text or bytes, a byte array on the JVM and a Uint8Array in
JavaScript. A fetch gives it as text, or as bytes with :as :bytes in its
opts, whichever was put. A put is a conflict when its opts have an
:if-version other than the store's, where nil means that the document
must not exist yet. A store that can't be written, e.g. over the files
of an input, has no :put.
On the JVM, each function returns its value and throws when it fails. In
ClojureScript, each can return a value or a promise. A store closes over
its credentials, so they're never in the map, and you wrap a store by
updating a key.(check! {:keys [fetch put list delete] :as store})Try store through its contract, e.g. from a button in the settings,
and report what works:
{:ok? true ; it works as a sync backend uses it
:checks [{:id :store/reachable :ok? true :message "…"}
{:id :store/authenticated …}
{:id :store/listing …}
{:id :store/put …} ; a probe written, with a version
{:id :store/conflicts …} ; stale writes refused, or not
{:id :store/fetch …} ; the probe read back as written
{:id :store/delete …}]} ; the probe removed
The report is a promise in ClojureScript. The probe document is probe-name, written and removed, and nothing is written to a store that can't be reached. A store without :list is reached with a fetch, and tried for the one shared document that a sync backend gives it, which needs a put refused both with a stale version and with an :if-version of nil while the document is there. A store without :delete keeps the probe. A store without :put is only reached, and is ok when it can be read. The store's errors tell refused credentials apart from other failures when they have a :status, as those of the WebDAV store do.
Try `store` through its contract, e.g. from a button in the settings,
and report what works:
{:ok? true ; it works as a sync backend uses it
:checks [{:id :store/reachable :ok? true :message "…"}
{:id :store/authenticated …}
{:id :store/listing …}
{:id :store/put …} ; a probe written, with a version
{:id :store/conflicts …} ; stale writes refused, or not
{:id :store/fetch …} ; the probe read back as written
{:id :store/delete …}]} ; the probe removed
The report is a promise in ClojureScript. The probe document is
probe-name, written and removed, and nothing is written to a store that
can't be reached. A store without :list is reached with a fetch, and
tried for the one shared document that a sync backend gives it, which
needs a put refused both with a stale version and with an :if-version
of nil while the document is there. A store without :delete keeps the
probe. A store without :put is only reached, and is ok when it can be
read. The store's errors tell refused credentials apart from other
failures when they have a :status, as those of the WebDAV store do.(fetch-all! store)(fetch-all! store {:keys [except] :or {except #{}} :as opts})The documents of store, fetched with opts, as maps of :name and
:body, in ClojureScript as a promise.
The :except of opts names documents to leave out, and the other
opts go to each fetch. The fetches are under way at once. A store
without :list has none, and a document deleted since the listing is
left out.
The documents of `store`, fetched with `opts`, as maps of :name and :body, in ClojureScript as a promise. The :except of `opts` names documents to leave out, and the other `opts` go to each fetch. The fetches are under way at once. A store without :list has none, and a document deleted since the listing is left out.
(memory)(memory documents)A store over the atom documents, or a fresh one, which holds the :body
and :version of each document by name, the version counting its writes.
A store over the atom `documents`, or a fresh one, which holds the :body and :version of each document by name, the version counting its writes.
The document that a check writes and removes, a text file with a name of its own, so that a probe left behind is never read as a sync document.
The document that a check writes and removes, a text file with a name of its own, so that a probe left behind is never read as a sync document.
(put-all! store documents)Put the documents, maps of :name and :body, into store one after the
other, in order, and give their names, in ClojureScript as a promise.
Put the `documents`, maps of :name and :body, into `store` one after the other, in order, and give their names, in ClojureScript as a promise.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |