{"id":17132178,"url":"https://github.com/bitsofinfo/io-event-reactor","last_synced_at":"2025-04-13T07:55:32.330Z","repository":{"id":57275606,"uuid":"60310989","full_name":"bitsofinfo/io-event-reactor","owner":"bitsofinfo","description":"Node.js module for conditionally reacting to watches and monitors on filesystem events by executing customizable plugins","archived":false,"fork":false,"pushed_at":"2016-11-23T02:38:10.000Z","size":225,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T07:55:27.865Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitsofinfo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-03T02:07:16.000Z","updated_at":"2024-12-27T14:31:13.000Z","dependencies_parsed_at":"2022-09-15T19:12:48.450Z","dependency_job_id":null,"html_url":"https://github.com/bitsofinfo/io-event-reactor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsofinfo","download_url":"https://codeload.github.com/bitsofinfo/io-event-reactor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681491,"owners_count":21144700,"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":[],"created_at":"2024-10-14T19:26:17.327Z","updated_at":"2025-04-13T07:55:32.305Z","avatar_url":"https://github.com/bitsofinfo.png","language":"JavaScript","readme":"# io-event-reactor\n\nNode.js module for reacting to filesystem events by invoking plugins that match configurable evaluators.\n\n[![Build Status](https://travis-ci.org/bitsofinfo/io-event-reactor.svg?branch=master)](https://travis-ci.org/bitsofinfo/io-event-reactor) \n\n[![NPM](https://nodei.co/npm/io-event-reactor.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/io-event-reactor/)\n\n* [How it works](#works)\n* [Requirements](#requirements)\n* [Install](#install)\n* [Usage](#usage)\n* [Plugins](#plugins)\n* [Monitor Plugins](#monitors)\n* [Reactor Plugins](#reactors)\n* [Unit tests](#tests)\n\n## How it works \u003ca id=\"works\"\u003e\u003c/a\u003e\n\nThe basic concept is this; you have a `monitor` that listens for IO events for particular paths\non the filesystem. As these IO events occur, they are passed on to one or more `evaluators` to\ndecide whether or not the `IoEvent` should be reacted to by one or more configured `reactors`.\nThe entire latter sequence is encapsulated in an `IoReactor` instance that manages the flow\nbetween the three described components.\n\n\u003cimg src=\"docs/diag1.png\" width=\"400\"/\u003e)\n\nWith this module, you construct and configure a single `IoReactorService` which can manage and contain\none or more `IoReactor` instances, as many as you wish, providing for lots of flexibility for reacting to filesystem events.\n\nWhen you configure the `IoReactorService` and its `IoReactor` instances, you specify which plugins you would like\nto use to fulfill the `monitor` and `reactor` roles. For `evaluators` you simply provide one or more functions\nwhich evaluate whether or not an `IoEvent` should be passed on to one or more `reactors`.\n\n\u003cimg src=\"docs/diag2.png\" width=\"600\"/\u003e\n\n### Requirements \u003ca id=\"requirements\"\u003e\u003c/a\u003e\n\n* [Node](https://nodejs.org/en/) 4.4.5+\n\n### Install \u003ca id=\"install\"\u003e\u003c/a\u003e\n\n```\nnpm install io-event-reactor\n```\n\n### Usage \u003ca id=\"usage\"\u003e\u003c/a\u003e\n\nUsage is pretty straight forward, one of the better starting points to to review one of the following apps:\n* [io-event-reactor-integration-tests](https://github.com/bitsofinfo/io-event-reactor-integration-tests) - simple low level app you can run\n* [io-overwatch](https://github.com/bitsofinfo/io-overwatch) - command line directory watching daemon \n\nBelow is an end-to-end simple sample:\n\n1. `mkdir myapp/`\n2. `mkdir -p /tmp/myapp`\n3. `npm install io-event-reactor`\n4. `npm install io-event-reactor-plugin-chokidar`\n5. `vi myapp.js`\n\n```\nvar IoReactorService = require(\"io-event-reactor\");\nvar EvaluatorUtil = require('io-event-reactor/ioReactor').EvaluatorUtil;\n\n// IoReactorService configuration\nvar config = {\n  ioReactors: [\n        {   id: \"reactor1\",\n            monitor: {\n                plugin: \"io-event-reactor-plugin-chokidar\",\n                config: {\n                    paths: \"/tmp/myapp\",\n                    options: {\n                        alwaysStat: false,\n                        awaitWriteFinish: {\n                            stabilityThreshold: 200,\n                            pollInterval: 100\n                        },\n                        ignoreInitial:true\n                    }\n                }\n            },\n\n            /**\n            *\n            * evaluators - REQUIRED array[] of one or more config objects, each containing the following properties\n            *   - evaluator: function(ioEventType, fullPath, optionalFsStats, optionalExtraInfo), if function returns 'true' all attached reactors will be invoked. If false, nothing will happen. See the 'Evaluators' class for methods that will generate an applicable function for simple use-cases.\n            *   - reactors: array[] of reactor ids that should be invoked if the 'evaluator' function returns 'true'\n            */\n            evaluators: [\n                {\n                    // see ioReactor.js (EvaluatorUtil class) for some helper function generators for simple use cases\n                    evaluator: EvaluatorUtil.regex(['add','change','unlink','unlinkDir','addDir'],'.*bitsofinfo.*','ig'),\n                    reactors: ['code1']\n                }\n            ],\n\n            reactors: [\n                { id: \"code1\",\n                  plugin: \"./default_plugins/code/codeReactorPlugin\",\n                  config: {\n                      codeFunction: function(ioEvent) {\n                          return new Promise(function(resolve,reject){\n                             console.log(\"I just reacted to an IoEvent! type: \" +ioEvent.eventType + \" file: \" +ioEvent.fullPath);\n                          });\n                      }\n                  }\n                }\n            ]\n        }\n   ]\n};\n\n// start the reactor\nvar reactor = new IoReactorService(config);\n```\n\n6. `node myapp.js`\n7. In another shell: `touch /tmp/myapp/bitsofinfo.txt`\n8. You should see output: `I just reacted to an IoEvent! type: add file: /tmp/myapp/bitsofinfo.txt`\n\nFor more info on configuration options see the JSDoc in [ioReactorService.js](https://github.com/bitsofinfo/io-event-reactor/blob/master/ioReactorService.js)\nand [ioReactor.js](https://github.com/bitsofinfo/io-event-reactor/blob/master/ioReactor.js)\n\n### Plugin support \u003ca id=\"plugins\"\u003e\u003c/a\u003e\n\nThis module is extensible via plugin contracts for both `monitors` and `reactors`. You can pretty much customize it to\nintegrate it with anything you want. See [io-event-reactor-plugin-support](https://github.com/bitsofinfo/io-event-reactor-plugin-support)\nfor more details on creating plugins.\n\n* [io-event-reactor-plugin-support](https://github.com/bitsofinfo/io-event-reactor-plugin-support) - Required module for developing any plugin\n\n### Monitor plugins \u003ca id=\"monitors\"\u003e\u003c/a\u003e\n* [io-event-reactor-plugin-chokidar](https://github.com/bitsofinfo/io-event-reactor-plugin-chokidar) - Monitor the filesystem for changes using [Chokidar](https://github.com/paulmillr/chokidar)\n\n### Reactor plugins \u003ca id=\"reactors\"\u003e\u003c/a\u003e\n\n **Default Plugins**\n\nThe plugins below are simple and just come with this module by default.\n\n* [code](default_plugins/code) - Permits arbitrary execution of javascript, to use: `./default_plugins/code/codeReactorPlugin`\n* [logger](default_plugins/logger) - Log reactions to monitored events, to use: `./default_plugins/logger/loggerReactorPlugin`\n\n**External module plugins**\n* [io-event-reactor-plugin-shell-exec](https://github.com/bitsofinfo/io-event-reactor-plugin-shell-exec) - Exec shell commands via [stateful-process-command-proxy](https://github.com/bitsofinfo/stateful-process-command-proxy)\n* [io-event-reactor-plugin-mysql](https://github.com/bitsofinfo/io-event-reactor-plugin-mysql) - Exec SQL against data in MySql via [node-mysql](https://github.com/felixge/node-mysql)\n\n\n### Unit tests \u003ca id=\"tests\"\u003e\u003c/a\u003e\n\nTo run the unit tests go to the root of the project and run the following.\n\n```\nmocha test/all.js\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fio-event-reactor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsofinfo%2Fio-event-reactor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fio-event-reactor/lists"}