RainCatcher

Feedhenry RainCatcher Core Repository

About RainCatcher

Developing

RainCatcher supports and is tested on Node.JS@4 and should run on latest LTS.

Check your Node.JS version running node -v

Setup

git clone https://github.com/feedhenry-raincatcher/raincatcher-core.git
cd raincatcher-core
npm install -g lerna
npm install
lerna bootstrap

Repository folder structure

This repository contains many subpackages managed through Lerna, and they're contained in the following directories:

client/: Front-end packages, from API clients to user interface modules
cloud/: Cloud app packages, intended to be run on an Node.JS environment
demo/: Full-fledged Demo applications, showcasing the usage of multiple modules
templates/: Templates and examples for other packages in the repository

Creating a new package

In order to create a new package, we recommend duplicating examples/base, which is a sample base that contains the skeleton expected of a new package. Refer to the linked README for more details.

Package structure

Directories

src/: Contains the TypeScript sources.
test/: The unit tests for the module. Should contain a `mocha.opts` file for configuring Mocha.
coverage/ and .nyc_output: Istanbul output, should be .gitignored.
example/: Example usage for module.

Module structure

RainCatcher modules are written in TypeScript.

The main files are modules that by default export a class containing the main implementation for the module's intent, with a named export containing a public interface that should be depended upon, and reimplemented.

import Implementation, { PublicInterface } from '@raincatcher/module';

See the Reusing unit tests section in order to know how to leverage the existing test suites on custom implementations.

Default exports

For each module, the default export is the main implementation itself, as the most common scenario is it being used by the requiring code.

Other RainCatcher modules depend only on the interfaces explained in the next section

Public interface

Along with the default export, all modules include a public interface definition that are depended upon by other RainCatcher modules instead of depending on the implementation itself. See the BaseModule for an example.

This is done so they can be more easily replaced or extended by custom implementations. Custom modules can skip this concern.

Unit test structure

For each module unit tests are present on the test/ folder, the Mocha default for storing the mocha.opts file as well.

Since code that requires a module's tests are most likely interested in a reusable test suite, the test/index.ts file's default export should be a function that receives all the required parameters for running the test suite on a given implementation of the interface.

import publicInterfaceTestSuite from '@raincatcher/module/test';
import { PublicInterface } from '@raincatcher/module';

class MyClass implements PublicInterface {
  // ...
}

// test/MyClass.ts
describe('MyClass', function() {
  publicInterfaceTestSuite(MyClass);
});

Tests for the module's specific implementation can be included as other files inside the same folder.

Using modules from JavaScript

We recommend users to write their code in TypeScript, especially if their new RainCatcher-based solution is a greenfield project, however JavaScript usage is partially supported by editor plugins that will still offer suggestions based on the TypeScript interfaces and access to jsdoc annotations:

See the example on examples/js for more information also for reusing the unit test suites from JavaScript code.

Publishing modules

Before publishing the typescript modules, do a manual compilation step via npm run build on the root of the repository.

Repository commands

npm run test - run unit tests

npm run bootstrap - perform boostrap for all modules

npm run start - run top level applications

npm run lint - execute tslint for all modules

npm run build - execute the build command for all modules, compiling TypeScript sources to JavaScript

npm run cleanInstall - perform install without executing additional scripts

tomjackman / raincatcher-core