chore(release): 1.0.0

.gitignore

@@ -0,0 +1,5 @@
+node_modules
+build
+*.js
+coverage
+.nyc_output

.npmignore

@@ -0,0 +1,4 @@
+src
+tsconfig.json
+tslint.json
+.travis.yml

.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: node_js
+node_js:
+  - 6
+  - 4

README.md

@@ -1,2 +1,120 @@
-# node-typescript-starter
-A starter typescript project for node projects & libraries
+# es7-typescript-starter
+An es7/typescript starter for building javascript libraries:
+
+* Write **standard, future javascript** – with stable es7 features – today ([stage 3](https://github.com/tc39/proposals) or [finished](https://github.com/tc39/proposals/blob/master/finished-proposals.md) features)
+* Use optional typescript typings to improve tooling, linting, and documentation generation
+* Export as an [es module](https://github.com/rollup/rollup/wiki/pkg.module), making your work **fully tree-shakable** for consumers using es imports (like [Rollup](http://rollupjs.org/) or [Webpack 2](https://webpack.js.org/))
+* Export typescript declarations to improve your downstream development experience
+* Backwards compatibility for Node.js CommonJS imports (v4 or greater)
+* Both [strict](config/tsconfig.strict.json) and [flexible](config/tsconfig.flexible.json) typing configurations available
+
+So we can have nice things:
+* Generate API documentation (HTML or JSON) [without a mess of JSDoc tags](https://blog.cloudflare.com/generating-documentation-for-typescript-projects/) to maintain
+* Co-located, atomic, concurrent tests with [AVA](https://github.com/avajs/ava)
+* Source-mapped code coverage reports with [nyc](https://github.com/istanbuljs/nyc)
+* Configurable code coverage testing (for continuous integration)
+
+## Get started
+
+Before you start, consider configuring or switching to an [editor with good typescript support](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support).
+
+## Development zen
+
+
+This starter includes watch tasks which make development faster and more interactive. They're particularly helpful for TDD/BDD workflows.
+
+To start working, run:
+
+```
+$ yarn watch:build
+```
+
+which will build and watch the entire project for changes (to both the library and test sources). In another tab or terminal window, run:
+
+```
+$ yarn watch:test
+```
+
+As you develop, you can add tests for new functionality – which will initially fail – before developing the new functionality. Each time you save, any changes will be rebuilt and retested.
+
+Since only changed files are rebuilt and retested, this workflow remains fast even for large projects.
+
+## Enable stronger typechecking (Recommended)
+
+To make getting started easier, the default `tsconfig.json` is using the `config/tsconfig.flexible` configuration. This will allow you to get started without many warning from Typescript.
+
+To enable additional Typescript typechecking features (a good idea for mission-critical or large projects), change the `extends` value in `tsconfig.json` to `./config/tsconfig.strict`.
+
+## View test coverage
+
+To generate and view test coverage, run:
+```bash
+$ yarn cov
+```
+
+This will create an HTML report of test coverage – source-mapped back to Typescript – and open in in your default browser.
+
+## Generate your API docs
+
+The src folder is analyzed and documentation is automatically generated using [typedoc](https://github.com/TypeStrong/typedoc).
+
+```bash
+$ yarn docs
+```
+This command generates API documentation for your library in HTML format.
+
+Since types are tracked by Typescript, there's no need to indicate types in JSDoc format. For more information, see the [typedoc documentation](http://typedoc.org/guides/doccomments/).
+
+For more advanced documentation generation, you can provide your own [typedoc theme](http://typedoc.org/guides/themes/), or [build your own documentation](https://blog.cloudflare.com/generating-documentation-for-typescript-projects/) using the JSON typedoc export:
+
+```bash
+$ yarn docs:json
+```
+
+## All package scripts
+
+You can run the `info` script for information on each available package script.
+
+```
+$ yarn run info
+
+info:
+  Display information about the scripts
+build:
+  (Trash and re)build the library
+lint:
+  Lint all typescript source files
+unit:
+  Run unit tests
+test:
+  Lint and test the library
+watch:build:
+  Watch source files, rebuild library on changes
+watch:unit:
+  Watch the build, rerun relevant tests on changes
+cov:
+  Run tests, generate the HTML coverage report, and open it in a browser
+html-coverage:
+  Output HTML test coverage report
+send-coverage:
+  Output lcov test coverage report and send it to codecov
+docs:
+  Generate API documentation and open it in a browser
+docs:json:
+  Generate API documentation in typedoc JSON format
+```
+## Notes
+
+### Browser libraries
+
+This starter currently doesn't run tests in a browser ([AVA](https://github.com/avajs/ava) tests in Node exclusively). While the current testing system will be sufficient for most use cases, some projects will (also) need to implement a browser-based testing system like [karma-ava](https://github.com/avajs/karma-ava). (Pull requests welcome!)
+
+### Dependency on `tslib`
+
+By default, this project requires [tslib](https://github.com/Microsoft/tslib) as a dependency. This is the recommended way to use Typescript's es6 & es7 transpiling for sizable projects, but you can remove this dependency by removing the `importHelpers` compiler option in `tsconfig.json`. Depending on your usage, this may increase the size of your library significantly, as the Typescript compiler will inject it's helper functions directly into every file which uses them.
+
+### Targetting Old Environments
+
+By default, this library targets environments with native (or already-polyfilled) support for es6 features. If your library needs to target Internet Explorer, outdated Android browsers, or versions of Node older than v4, you may need to change the `target` in `tsconfig.json` to `es5` (rather than `es6`) and bring in a Promise polyfill (such as [es6-promise](https://github.com/stefanpenner/es6-promise)).
+
+It's a good idea to maintain 100% unit test coverage, and always test in the environments you target.

config/tsconfig-node.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny" : true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}

config/tsconfig.flexible.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "strictNullChecks": true
+  }
+}

config/tsconfig.strict.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny" : true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}

package.json

@@ -0,0 +1,82 @@
+{
+  "name": "es7-typescript-starter",
+  "version": "1.0.0",
+  "description": "An es7/typescript starter for building javascript libraries",
+  "main": "build/index.commonjs.js",
+  "module": "build/index.js",
+  "typings": "build/index.d.ts",
+  "repository": "https://github.com/bitjson/node-typescript-starter",
+  "author": "Jason Dreyzehner <jason@dreyzehner.com>",
+  "license": "MIT",
+  "scripts": {
+    "info": "npm-scripts-info",
+    "build": "trash build && tsc",
+    "lint": "tslint src/**/*.ts",
+    "unit": "yarn build && nyc ava",
+    "check-coverage": "nyc check-coverage --lines 100 --functions 100 --branches 95",
+    "test": "yarn lint && yarn unit && yarn check-coverage",
+    "watch:build": "yarn build -- -w",
+    "watch:unit": "ava --watch --verbose",
+    "cov": "yarn unit && yarn html-coverage && opn coverage/index.html",
+    "html-coverage": "nyc report --reporter=html",
+    "send-coverage": "nyc report --reporter=lcov > coverage.lcov && codecov",
+    "docs": "typedoc src/index.ts --excludePrivate --mode file --theme minimal --out build/docs && opn build/docs/index.html",
+    "docs:json": "typedoc --mode file --json build/docs/typedoc.json src/index.ts"
+  },
+  "scripts-info": {
+    "info": "Display information about the scripts",
+    "build": "(Trash and re)build the library",
+    "lint": "Lint all typescript source files",
+    "unit": "Run unit tests",
+    "test": "Lint and test the library",
+    "watch:build": "Watch source files, rebuild library on changes",
+    "watch:unit": "Watch the build, rerun relevant tests on changes",
+    "cov": "Run tests, generate the HTML coverage report, and open it in a browser",
+    "html-coverage": "Output HTML test coverage report",
+    "send-coverage": "Output lcov test coverage report and send it to codecov",
+    "docs": "Generate API documentation and open it in a browser",
+    "docs:json": "Generate API documentation in typedoc JSON format"
+  },
+  "engines": {
+    "node": ">=4"
+  },
+  "devDependencies": {
+    "@types/node": "^0.0.2",
+    "ava": "^0.17.0",
+    "codecov": "^1.0.1",
+    "npm-scripts-info": "^0.3.6",
+    "nyc": "^10.0.0",
+    "opn-cli": "^3.1.0",
+    "trash-cli": "^1.4.0",
+    "tslint": "^4.0.2",
+    "tslint-config-standard": "^2.0.0",
+    "typedoc": "^0.5.5",
+    "typescript": "^2.1.5"
+  },
+  "keywords": [
+    "node",
+    "typescript",
+    "typings",
+    "boilerplate",
+    "starter",
+    "es6",
+    "es7",
+    "library"
+  ],
+  "nyc": {
+    "exclude": [
+      "**/*.spec.js"
+    ]
+  },
+  "ava": {
+    "files": [
+      "build/**/*.spec.js"
+    ],
+    "source": [
+      "build/**/*"
+    ]
+  },
+  "dependencies": {
+    "tslib": "^1.5.0"
+  }
+}

src/index.spec.ts

@@ -0,0 +1,8 @@
+import { test } from 'ava'
+import * as lib from './'
+
+test('functions can be used without es imports', (t) => {
+  t.true(typeof lib.double === 'function')
+  t.true(typeof lib.power === 'function')
+  t.true(typeof lib.asyncABC === 'function')
+})

src/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/numberOps'
+export * from './lib/asyncOps'

src/lib/asyncOps.spec.ts

@@ -0,0 +1,6 @@
+import { test } from 'ava'
+import { asyncABC } from '../'
+
+test('getABC', async t => {
+  t.deepEqual(await asyncABC(), ['a','b', 'c'])
+})

src/lib/asyncOps.ts

@@ -0,0 +1,32 @@
+/**
+ * A sample async function (to demo Typescript's es7 async/await downleveling).
+ *
+ * ### Example (es imports)
+ * ```js
+ * import { asyncABC } from 'es7-typescript-starter'
+ * console.log(await asyncABC())
+ * // => ['a','b','c']
+ * ```
+ *
+ * ### Example (commonjs)
+ * ```js
+ * var double = require('es7-typescript-starter').asyncABC;
+ * asyncABC().then(console.log);
+ * // => ['a','b','c']
+ * ```
+ *
+ * @returns       a Promise which should contain `['a','b','c']`
+ */
+export async function asyncABC() {
+  function somethingSlow(index: 0 | 1 | 2) {
+    let storage = 'abc'.charAt(index)
+    return new Promise<string>(resolve => {
+      // here we pretend to wait on the network
+      setTimeout(() => resolve(storage), 0)
+    })
+  }
+  let a = await somethingSlow(0)
+  let b = await somethingSlow(1)
+  let c = await somethingSlow(2)
+  return [a, b, c]
+}

src/lib/numberOps.spec.ts

@@ -0,0 +1,10 @@
+import { test } from 'ava'
+import { double, power } from '../'
+
+test('double', t => {
+  t.deepEqual(double(2), 4)
+})
+
+test('power', t => {
+  t.deepEqual(power(2,4), 16)
+})

src/lib/numberOps.ts

@@ -0,0 +1,46 @@
+/**
+ * Multiplies a value by 2. (Also a full example of Typedoc's functionality.)
+ *
+ * ### Example (es module)
+ * ```js
+ * import { double } from 'es7-typescript-starter'
+ * console.log(double(4))
+ * // => 8
+ * ```
+ *
+ * ### Example (commonjs)
+ * ```js
+ * var double = require('es7-typescript-starter').double;
+ * console.log(double(4))
+ * // => 8
+ * ```
+ *
+ * @param value   Comment describing the `value` parameter.
+ * @returns       Comment describing the return type.
+ * @anotherNote   Some other value.
+ */
+export function double (value: number) {
+  return value * 2
+}
+
+/**
+ * Raise the value of the first parameter to the power of the second using the es7 `**` operator.
+ *
+ * ### Example (es module)
+ * ```js
+ * import { power } from 'es7-typescript-starter'
+ * console.log(power(2,3))
+ * // => 8
+ * ```
+ *
+ * ### Example (commonjs)
+ * ```js
+ * var power = require('es7-typescript-starter').power;
+ * console.log(power(2,3))
+ * // => 8
+ * ```
+ */
+export function power (base: number, exponent: number) {
+  // This is a proposed es7 operator, which should be transpiled by Typescript
+  return base ** exponent
+}

tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "extends": "./config/tsconfig.flexible",
+  "compilerOptions": {
+    "target": "es6",
+    "outDir": "build",
+    "moduleResolution": "node",
+    "module": "commonjs",
+    "declaration": true,
+    "strictNullChecks": true,
+    "importHelpers": true,
+    "inlineSourceMap": true,
+    "listFiles": false,
+    "pretty": true,
+    "lib" : [
+      "ES6"
+    ],
+    "types" : [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules/**"
+  ],
+  "compileOnSave": false
+}

tslint.json

@@ -0,0 +1,3 @@
+{
+  "extends": "tslint-config-standard"
+}