https://github.com/maximgb/re-service
Re-frame supplementary library to easily declare services and dispatch co-effects/effects requests to service functions
https://github.com/maximgb/re-service
clojurescript co-effect effect re-frame service utility
Last synced: 8 months ago
JSON representation
Re-frame supplementary library to easily declare services and dispatch co-effects/effects requests to service functions
- Host: GitHub
- URL: https://github.com/maximgb/re-service
- Owner: MaximGB
- License: mit
- Created: 2019-11-12T22:59:03.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2019-11-17T12:23:07.000Z (over 6 years ago)
- Last Synced: 2025-10-21T23:51:12.899Z (8 months ago)
- Topics: clojurescript, co-effect, effect, re-frame, service, utility
- Language: Clojure
- Size: 26.4 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Changelog: CHANGELOG.adoc
- License: LICENSE
Awesome Lists containing this project
README
= Re-service
:source-highlighter: coderay
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning
:endif::[]
image:https://img.shields.io/clojars/v/maximgb/re-service.svg[link=https://clojars.org/maximgb/re-service]
image:https://img.shields.io/badge/License-MIT-yellow.svg[link=https://raw.githubusercontent.com/MaximGB/re-service/master/LICENSE]
Re-frame supplementary library to easily declare services and dispatch co-effects/effects requests to implementing functions
== TL;DR
Re-service allows re-frame user to easily define services. A service here is a named set of functions which provide co-effects
and execute effects required or issued by re-frame event handlers. What re-service does is it translates re-frame co-effects/effects
descriptors into service function calls return values.
== Basic API
=== Service definition
A service can be defined using macros or function calls from `maximgb.re-service.core` namespace.
To define a service and it's implementation one have to:
- define a service having application unique id
- define set of named commands by providing command id and implementing function for the service registed
[source, clojure]
----
(ns my.service.core
(:require [maximgb.re-service.core :refer [def-re-service
def-re-service-command]
:include-macros true])) ;; <1>
(def-re-service ::my-service) ;; <2>
(def-re-service-command ::my-service ;; <3>
:sum ;; <4>
[cofx & args] ;; <5>
(apply + args)) ;; <6>
----
<1> Require `maximgb.re-service.core` namespace and refer to service and command definition macros.
<2> Define service with application unique id
<3> Define service command with:
<4> - id `:sum`
<5> - variable list of arguments (non-variable lists are also allowed)
<6> - implementing function body
=== Service commands invocation
When service is defined a corresponding re-frame's co-effect and effect are registered using provided service id as co-effect/effect id.
Thus each service command can be invoked as co-effect via re-frame's `(inject-cofx)` or as effect requested
via `(reg-event-fx)` or `(reg-event-ctx)` return value.
==== Calling service command as co-effect
To call service command as co-effect a user have to use `(inject-cofx service-id [key? command-1-id [& args] command-2-id [& args]] ...)` syntax.
Commands are executed in the order each command is called with the given arguments. The results will be added to re-frame's co-effects
map under `service-id` or `key?` (if one has been provided) key. The key value will be a map keyed by command ids, map values will be set to
corresponding command invokation results.
[NOTE]
====
If command is called as co-effect the first argument it recieves will be set to re-frame's co-effects map.
====
[source, clojure]
----
(reg-event-fx
::my-command
[(inject-cofx ::my-service [:sum [1 2 3 4] :mul [1 2 3 4]])] ;; <1>
(fn [cofx]
(let [my-sum (get-in cofx [::my-service :sum]) ;; <2>
my-mul (get-in cofx [::my-service :mul])] ;; <3>
(is (= my-sum 10) "Sum is correct")
(is (= my-mul 24) "Mul is correct"))
{}))
----
<1> Injecting service co-effect, requesting two commands invokation (`:sum` and `:mul`) each will recieve the same list of parameters
<2> Getting `:sum` command result
<3> Getting `:mul` command result
==== Calling service command as effect
To call service command as effect a user have to add to re-frame's effects map using `service-id` as effect id a value designating
service commands invokation request (the value syntax is the same as for co-effect case)
[source, clojure]
----
(reg-event-fx
::my-command
(fn [cofx]
{::my-service [:sum [1 2 3 4] :mul [1 2 3 4]})) ;; <1>
----
<1> Of course `:sum` and `:mul` has no side-effects, thus calling'em as effects is meaningless, so here they are called for illustrative
reasons only.