Release: Update documentation and migrate to TypeScript and GitHub Actions

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - run: npm ci
+      - run: npm test

.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.mocharc.json

@@ -0,0 +1,5 @@
+{
+  "require": ["ts-node/register"],
+  "spec": "test/**/*.ts",
+  "reporter": "spec"
+}

.npmignore

@@ -68,10 +68,10 @@ typings/
 out
 gen
 /.npmignore
-/.jshintrc
-/source/
+/src/
+/test/
 /.gitignore
 /.editorconfig
-/test/
 /.travis.yml
-/.babelrc
+/.mocharc.json
+/tsconfig.json

README.md

@@ -1,31 +1,103 @@
-# Resistor Data [![NPM version][npm-image]][npm-url] [![Build status][travis-image]][travis-url]
+# Resistor Data [![NPM version][npm-image]][npm-url] [![CI][ci-image]][ci-url]
 
-A simple module to calculate properties for resistors. 
+A simple module to calculate properties for resistors.
 
-* convert resistor bands to standard resistor notation
-* convert standard resistor notation to resistor bands
-* convert a number to standard resistor notation
-* convert standard resistor notation to a number
+* Convert resistor bands to standard resistor notation
+* Convert standard resistor notation to resistor bands
+* Convert a number to standard resistor notation
+* Convert standard resistor notation to a number
 
-Install Resistor Data:
+## Install
 
 ```sh
 npm install resistor-data
 ```
 
+## Usage
+
+### JavaScript
+
 ```js
-var resistorData = require('resistor-data');
+const { bandsToNotation, notationToBands, notationToValue, valueToNotation } = require('resistor-data');
+
+bandsToNotation(['red', 'yellow', 'black', 'brown', 'brown']); // ['2k4', 1]
+notationToBands(['2k4', 1], 5);                                // ['red', 'yellow', 'black', 'brown', 'brown']
+
+notationToValue('2k4');  // 2400
+valueToNotation(2400);   // '2k4'
+```
+
+### TypeScript
+
+```ts
+import {
+    bandsToNotation,
+    notationToBands,
+    notationToValue,
+    valueToNotation,
+} from 'resistor-data';
+import type { ResistorColor, ResistorTolerance, ResistorData, BandCount } from 'resistor-data';
 
-resistorData.bandsToNotation(['red', 'yellow', 'black', 'brown', 'brown'], 5); //['2k4', 1]
-resistorData.notationToBands(['2k4', 1], 5); //['red', 'yellow', 'black', 'brown', 'brown']
+// ResistorData is [notation: string, tolerance: ResistorTolerance]
+const result: ResistorData = bandsToNotation(['red', 'yellow', 'black', 'brown', 'brown']);
+// result => ['2k4', 1]
 
-resistorData.notationToValue('2k4'); //2400
-resistorData.valueToNotation(2400); //'2k4'
+const bands: ResistorColor[] = notationToBands(['2k4', 1], 5);
+// bands => ['red', 'yellow', 'black', 'brown', 'brown']
 
+const value: number = notationToValue('2k4');  // 2400
+const notation: string = valueToNotation(2400); // '2k4'
 ```
 
+## API
+
+### `bandsToNotation(bands: string[]): ResistorData`
+
+Converts an array of 4 or 5 resistor band colour names into `[notation, tolerance]`.
+
+```ts
+bandsToNotation(['orange', 'orange', 'black', 'red', 'brown']); // ['33k', 1]
+```
+
+### `notationToBands(data: [string, ResistorTolerance?], bands?: BandCount): ResistorColor[]`
+
+Converts a `[notation, tolerance]` pair into an array of colour names. `bands` defaults to `5`.
+
+```ts
+notationToBands(['33k', 1], 4); // ['orange', 'orange', 'orange', 'brown']
+notationToBands(['33k', 1], 5); // ['orange', 'orange', 'black', 'red', 'brown']
+```
+
+### `notationToValue(notation: string): number`
+
+Converts standard resistor notation to a numeric value.
+
+```ts
+notationToValue('5k');   // 5000
+notationToValue('5k5');  // 5500
+notationToValue('1M2');  // 1200000
+```
+
+### `valueToNotation(value: number | string): string`
+
+Converts a numeric value to standard resistor notation.
+
+```ts
+valueToNotation(3000);    // '3k'
+valueToNotation(3300);    // '3k3'
+valueToNotation(1000000); // '1m'
+```
+
+## Types
+
+| Type | Description |
+|---|---|
+| `ResistorColor` | Union of valid band colour strings (`'black'`, `'brown'`, `'red'`, ...) |
+| `ResistorTolerance` | Union of valid tolerance values (`0.05`, `0.1`, `0.25`, `0.5`, `1`, `2`, `5`, `10`, `20`) |
+| `ResistorData` | Tuple returned by `bandsToNotation`: `[notation: string, tolerance: ResistorTolerance]` |
+| `BandCount` | `4 \| 5` |
 
-[travis-url]: http://travis-ci.org/OneLittleRobot/resistor-data
-[travis-image]: https://secure.travis-ci.org/OneLittleRobot/resistor-data.svg?branch=master
+[ci-url]: https://github.com/OneLittleRobot/resistor-data/actions/workflows/ci.yml
+[ci-image]: https://github.com/OneLittleRobot/resistor-data/actions/workflows/ci.yml/badge.svg
 [npm-url]: https://npmjs.org/package/resistor-data
-[npm-image]: https://badge.fury.io/js/resistor-data.svg
+[npm-image]: https://badge.fury.io/js/resistor-data.svg