{"id":19942054,"url":"https://github.com/day8/re-frame-forward-events-fx","last_synced_at":"2025-05-03T15:32:03.476Z","repository":{"id":49212226,"uuid":"63420976","full_name":"day8/re-frame-forward-events-fx","owner":"day8","description":"A re-frame effects handler for listening-for and then post-processing dispatched events","archived":false,"fork":false,"pushed_at":"2021-11-04T22:53:54.000Z","size":178,"stargazers_count":35,"open_issues_count":0,"forks_count":4,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-29T13:44:33.371Z","etag":null,"topics":["re-frame"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/day8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"mike-thompson-day8"}},"created_at":"2016-07-15T12:42:18.000Z","updated_at":"2024-11-26T12:31:49.000Z","dependencies_parsed_at":"2022-09-07T10:12:42.560Z","dependency_job_id":null,"html_url":"https://github.com/day8/re-frame-forward-events-fx","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-forward-events-fx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-forward-events-fx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-forward-events-fx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-forward-events-fx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/day8","download_url":"https://codeload.github.com/day8/re-frame-forward-events-fx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252211069,"owners_count":21712327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["re-frame"],"created_at":"2024-11-13T00:11:31.495Z","updated_at":"2025-05-03T15:32:03.187Z","avatar_url":"https://github.com/day8.png","language":"Clojure","funding_links":["https://github.com/sponsors/mike-thompson-day8"],"categories":[],"sub_categories":[],"readme":"\u003c!-- [![CI](https://github.com/day8/re-frame-forward-events-fx/workflows/ci/badge.svg)](https://github.com/day8/re-frame-forward-events-fx/actions?workflow=ci)\n[![CD](https://github.com/day8/re-frame-forward-events-fx/workflows/cd/badge.svg)](https://github.com/day8/re-frame-forward-events-fx/actions?workflow=cd)\n[![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/day8/re-frame-forward-events-fx?style=flat)](https://github.com/day8/re-frame-forward-events-fx/tags) --\u003e\n[![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/forward-events-fx?style=for-the-badge\u0026logo=clojure\u0026logoColor=fff)](https://clojars.org/day8.re-frame/forward-events-fx)\n[![GitHub issues](https://img.shields.io/github/issues-raw/day8/re-frame-forward-events-fx?style=for-the-badge\u0026logo=github)](https://github.com/day8/re-frame-forward-events-fx/issues)\n[![License](https://img.shields.io/github/license/day8/re-frame-forward-events-fx?style=for-the-badge)](license.txt)\n\n\u003c!-- [![GitHub pull requests](https://img.shields.io/github/issues-pr/day8/re-frame-forward-events-fx?style=for-the-badge\u0026logo=github)](https://github.com/day8/re-frame-forward-events-fx/pulls) --\u003e\n\u003c!--\n[![Sample Project](https://img.shields.io/badge/project-example-ff69b4.svg)](https://github.com/day8/re-frame-forward-events-fx/sample)\n--\u003e\n\n# re-frame-forward-events-fx\n\nThis re-frame library contains an [Effect Handler](https://github.com/day8/re-frame/tree/develop/docs),\nkeyed `:forward-events`, which allows you to listen-for, and then post-process events, typically for higher-level\ncontrol flow purposes (eg. coordination).\n\n## Quick Start Guide\n\n### Step 1. Add Dependency\n\nAdd the following project dependency:  \u003cbr\u003e \n[![clojars](https://img.shields.io/clojars/v/day8.re-frame/forward-events-fx?style=for-the-badge\u0026logo=clojure\u0026logoColor=fff)](https://clojars.org/day8.re-frame/forward-events-fx)\n\nAlso requires re-frame \u003e= v0.8.0\n\n### Step 2. Registration And Use\n\nIn the namespace where you register your event handlers, perhaps called `events.cljs`, you have 2 things to do.\n\n**First**, add this require to the `ns`:\n```clj\n(ns app.events\n  (:require\n    ...\n    [day8.re-frame.forward-events-fx]   ;; \u003c-- add this\n    ...))\n```\n\n\nBecause we never subsequently use this require, it\nappears redundant.  But its existence will cause the `:forward-events` effect\nhandler to self-register with re-frame, which is important\nto everything that follows.\n\n**Second**, use it when writing an effectful event handler:\n```clj\n(reg-event-fx             ;; note the -fx\n  :my-event\n  (fn [world event]       ;; note: world\n    {:db   (assoc (:db world) :some :thing)          ;; optional update to db\n     :forward-events  {:register  :coordinator1      ;;  \u003c-- used\n                       :events      #{:event1  :event2}\n                       :dispatch-to [:coordinator 1]}}))\n```\n\nNotice the use of an effect `:forward-event`.  This library defines the \"effect handler\" which implements `:forward-events`.\n\n## Tutorial\n\nThis effect handler provides a way to \"forward\" events. To put it another way,\nit provides a way to listen-for and then post-process events. Some might say it allows you to \"sniff\" certain events.\n\nNormally, when `(dispatch [:a 42])` happens, the event will be routed to\nthe registered handler for `:a`, and that's the end of the matter.\n\nBut, with this effect, you can specify that a particular set of events be\nforwarded to another handler for further processing __after__ normal handling.\nThis 2nd handler can then further process the events, often carrying out\nsome sort of meta level, coordination function.\n\nThe \"forwarding\" is done via a 2nd dispatch. The payload of this `dispatch`\nis the __entire__ event dispatched in the first place.\n\n`:forward-events` accepts the following keys (all mandatory):\n  - `:register` - an id, typically a keyword. Used when you later want to unregister a forwarder. Should be unique across all `:forward-event` effects.\n  - `:events` - the set of events for which you'd like to \"listen\"\n  - `:dispatch-to` a vector which represents the template for the \"further event\" to dispatch.  The\n    detected event is provided (conj-ed) to this event template.\n\nFor clarity, here's a worked example. If you registered a \":forward-events\" for event `:a`  and you gave a `:dispatch-to` of `[:later :blah]`, then:\n  - when if any `(dispatch [:a 42])` happened,\n  - the handler for `:a` would be run normally. No change so far.\n  - but then a further dispatch would be happen:  `(dispatch [:later :blah [:a 42]])`. The entire first event `[:a 42]` is \"forwarded\" in the further `dispatch`.\n\nExamples of use:\n```clj\n{:forward-events {:register    :an-id-for-this-listener\n                  :events      #{:event1  :event2}\n                  :dispatch-to [:later \"blah\"]}    ;; the forwarded event is conj to the end of this event vec\n```\n\n```clj\n{:forward-events  {:unregister :the-id-supplied-when-registering}}\n```\n\nWhen necessary, the value of `:forward-events` can also be a `list` of `maps`,\nwith each map either registering or unregistering.\n\n## Testing\n\nTo run the tests in a browser\n\n```\nlein dev\n```\n\nTo run the tests with Karma (i.e. for continuous integration)\n\n```\nsudo npm -g install karma-cli\nlein ci\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fday8%2Fre-frame-forward-events-fx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fday8%2Fre-frame-forward-events-fx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fday8%2Fre-frame-forward-events-fx/lists"}