Core tools

This repository contains general-purpose functions for use in Javascript runtime environments.

There are no runtime dependencies on other packages, nor any environment-specific API's. They only refer to ES2015 built-ins.

The build creates several distributables, including a single-file module bundle.

The module is intended to be used with Rollup as a packaging tool, and no particular effort is made to scope the content by subject matter.

The library is written in TypeScript and includes type definitions.

Note on modules

The JavaScript code here is written using the "ES2015" module format, and this is exported (by tsc) to AMD format. In places where module loading is wanted, it is assumed that an AMD-compliant require is in the global scope.

Note on explicit index reference

In intra-library imports, we do not take advantage of implicit index resolution, meaning that a statement like

import { flip } from './function';

which would work in TypeScript or Node.js, is instead written as

import { flip } from './function/index';

This is done to support Rollup, which, as is observed whenever anyone posts issues about this, does not use index to resolve imports:

That behaviour is Node and NPM specific and therefore not included in the core Rollup library. Please install rollup-plugin-npm to add the behaviour.

TypeScript quirks

TS4023 - Placeholder for notes about the export of type definitions. Currently, the public type definitions include both generated and authored type definitions. The postbuild task ships the authored definitions files, while the --declaration true option in build generates definitions in the output directory.

Documentation these decisions to follow. Bottom line, right now it's necessary to generate type definitions to meet all of the package's objectives, and as a result, there are a few places where annotations are necessary that wouldn't be otherwise. This compromise was chosen because TS issue threads indicate that a mitigation is marked for a future version, (I thought 2.7, but I can't find the link right now), where types will be transitively imported into generated declaration files, preventing the need for redundant annotations and imports.

UPDATE: With TypeScript 2.6 (now in RC), you can suppress errors in individual lines of TS files. This enables a cleaner solution than adding explicit type signatures, since you can simply import the referenced types and suppress the "unused local" error. This is the recommended approach for now.