Skip to content

DEVELOPMENT.adoc

Latest commit

 

History

History
70 lines (56 loc) · 2.98 KB

DEVELOPMENT.adoc

File metadata and controls

70 lines (56 loc) · 2.98 KB

Development Documentation

Common patterns

  • While JavaScript supports the object-oriented paradigm, the functional programming style allows writing more readable code in JS. Hence, all provided data types (interfaces) are immutable, and classes are used only to build fluent method chains (considering methods as infix operators).

  • One of the base patterns used is to provide a constructor function named after each class to discourage the use of the new operator (for readability and consistency with the method chains). Classes should only be used in types declaration. All non-abstract classes should be considered final even TypeScript does not provide a final keyword.

  • For each declared interface or class, there is at least one unit function to instantiate it. This function has the same name as the interface/class but in camelCase.

  • For each declared class, there are two type guards to check if a given value is an instance of that class or not. These functions have prefixes is and isNot.

  • Declared interfaces and types may have other predicates with the is/isNot prefixes.

TypeScript configuration

The project contains a group of TSConfig files to maintain a productive development environment with the WebStorm IDE:

  • The base file with the TypeScript compiler configuration is tsconfig.strict.json. It contains all the default (strict) compiler settings.

  • The root tsconfig.json is picked up by WebStorm and is used by Jest.

  • tsconfig.build.json contains the defaults for the build, and is further overridden in gulpfile.js for CommonJS, ESM, and declaration files compilation.

Testing

  • All functions and classes must have 100% test coverage.

  • Top-level describe() blocks must reference a function or a class directly, not as a string.

  • it() statements must not have any conditions.

  • Conditions should be defined by using (nested) describe() blocks.

  • Group tests for each signature using second-level describe() blocks with the name of the arguments. For example describe('elements(Iterable)') with tests for the elements() function.

  • Higher-order functions should use second-level describe() to define used functions.

Documentation

This project uses the AsciiDoc format for its documentation. Each sub-package has an index.adoc file that is included into the package src/index.adoc. It is automatically compiled into the dist/docs.html file and is published with all other package files.

Note

Unfortunately, npmjs only supports Markdown. As a result, in addition to this README.adoc for the repository, there is a README.md file with only basic information for the npm page.

  • Every type or function must have a JSDoc description. JSDocs are visible in IDEs from a caller location which allows to understand the behavior of a function without reading it.