Initial commit

.c8rc

@@ -0,0 +1,5 @@
+{
+    "reporter": [
+        "lcov", "html", "text", "text-summary"
+    ]
+}

.eslintrc

@@ -0,0 +1,23 @@
+{
+  "env": {
+    "node": true
+  },
+  "plugins": ["eslint-plugin-tsdoc"],
+  "extends": [
+    "plugin:@shopify/typescript",
+    "plugin:@shopify/typescript-type-checking"
+  ],
+  "parserOptions": {
+    "project": "tsconfig.json"
+  },
+  "rules": {
+    "tsdoc/syntax": "warn"
+  },
+  "ignorePatterns": [
+    "dist/*",
+    "lib/*",
+    "build/*",
+    "prebuild/*",
+    "externals"
+  ]
+}

.github/workflows/coveralls.yml

@@ -0,0 +1,27 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Coveralls build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+
+  # job to push lcov test coverage data to coveralls.io
+  coveralls:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js 20.x
+      uses: actions/setup-node@v3
+      with:
+        node-version: 20.x
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test
+    - name: Coveralls
+      uses: coverallsapp/github-action@v2

.github/workflows/linux-ci.yml

@@ -0,0 +1,29 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Linux build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 21.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish package to GitHub Packages
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      pages: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get Release Name
+        run: echo "release_name=${{ github.event.release.name }}" >> $GITHUB_ENV
+      - name: get version
+        id: version
+        uses: notiz-dev/github-action-json-property@release
+        with: 
+          path: 'package.json'
+          prop_path: 'version'
+      - run: echo "package_version=v${{ steps.version.outputs.prop }}" >> $GITHUB_ENV
+      - name: Don't Publish if versions are different
+        if: ${{ env.release_name != env.package_version }}
+        run: exit 1
+      # Setup .npmrc file to publish to GitHub Packages
+      - name: Use node.js 20.x
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20.x'
+          registry-url: 'https://npm.pkg.github.com'
+          # Defaults to the user or organization that owns the workflow file
+          # scope: '@your-org'
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PUBLISH_PACKAGES_TOKEN }}
+      # publish github pages
+      # add documentation to ./pages/docs
+      - run: npm run docs
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./pages
+      # add anything else to be published in pages here
+      # deploy pages
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/windows-ci.yml

@@ -0,0 +1,29 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Windows build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 21.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

.gitignore

@@ -0,0 +1,31 @@
+# Coverage directory used by tools like istanbul
+coverage
+.nyc_output
+
+# Dependency directory
+# Deployed apps should consider commenting this line out:
+# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
+node_modules
+
+# FS stuff
+.DS_Store
+thumbs.db
+
+# IDE Stuff
+*.iml
+*.swp
+*~
+.vscode/**/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+#Generated
+dist
+lib
+build
+prebuild
+externals
+*.tgz
+pages

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "streetsidesoftware.code-spell-checker",
+        "ryanluker.vscode-coverage-gutters",
+        "dbaeumer.vscode-eslint",
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "editor.tabSize": 2
+}

CONTRIBUTING.md

@@ -0,0 +1,149 @@
+# Tools
+
+## Typescript, ECM and CommonJS
+
+Node modules `ts-node` and `typescript` provide compilation of Typescript to Javascript. Settings within `tsconfig.json` allow for ESM style Typescript (including linting) in the `/src` and `/tests` directories.
+
+For compilation there are `tsconfig-cjs.json` and `tsconfig-esm.json` which are used to transpile identical source to CommonJS and ESM respectively into the `/build/cjs` and `/build/esm` directories with strict type checking.
+
+The script `tsc` produces both ESM and the CommonJS output which is run by:
+
+```cmd
+> npm run tsc
+```
+
+Typescript declaration (*.d.ts) files are produced in both cases. For any other compilation options the tsconfig files can be modified accordingly.
+
+## Test
+
+To run Tests including Spell check and code coverage:
+
+```
+> npm test
+```
+
+Test is facilitated by the `chai` and `mocha` node modules. Tests are written as ESM, stored in the `/tests` directory with `*.spec.ts` filenames. There are sample tests on the file `/tests/test1.spec.ts`. 
+
+There is a `mocha` script which just runs all tests:
+
+```cmd
+> npm run mocha
+```
+
+To view the html test output by opening it in a browser window:
+```
+> npm run mocha:view
+```
+
+If html output of test results is not required remove `html` from the `./.c8rc` file.
+
+## Test Coverage
+
+Test coverage is facilitated by the `c8` node module. The `.c8rc` file contains the settings for Coverage which is set up to produce lcov, html and inline text output into the `/coverage` directory. Coverage is run with testing by:
+
+```cmd
+> npm run mocha:cov
+```
+
+In this boilerplate the tests cover `add.ts` and `index.ts`, but not `subtract.ts`, giving a partial Coverage output.
+
+## Coveralls.io
+
+Coveralls is already set up and this provides a coverage report when commits are made to github. Coverage.io is free for public repositories. To set up Coverage on a new project created from this template:
+
+    1 at [coveralls.io](http://coveralls.io), obtain a repo_token for your new repository and paste it into `/.coveralls.yml`
+    2 in the /README.md file, change the link to the coveralls badge 
+
+## Typescript Linting
+
+Linting is provided by the `eslint` and `@shopify/eslint-plugin` node modules. The configuration is in the `./.eslintrc` file. To run the linter:
+
+```
+> npm run eslint
+```
+
+Some errors may be fixed with:
+```
+> npm run eslint:fix
+```
+
+## TSDoc
+
+<!--- cspell:disable-next-line --->
+TSDoc linting is provided by the `eslint-plugin-tsdoc` eslint plugin. The config in `./.eslintrc` is set to `warn` rather than `error`.
+
+TSDoc will be run as put of eslint so TSDoc and Typescript linting are done together. 
+
+## Spelling
+
+Spell checking is provided by the `cspell` node module. The `.cspell.config.json` contains the settings for cspell.
+
+The script to run spell check is:
+
+```
+> npm run spellcheck
+```
+
+A Visual Studio extensions recommendation for Code Spell CHecker is included which highlights spelling errors live in visual studio using the same system and configuration file.
+
+# Development
+
+During development it may not be desirable to meet all the linting and spelling requirements. In which case code can be just built (transpiled) using the `npm run tsc` script, and can be tested using the `npm run mocha` script, neither of which run the linter or spellcheck.
+
+To see what will be published without actually publishing:
+```
+> npm publish --dry-run
+```
+
+To create a package locally:
+```
+> npm pack
+```
+
+Then install that in another npm package using:
+```
+> npm install path/to/my-package-1.0.0.tgz
+```
+
+## How to publish
+
+1. Ensure `version` within `package.json` has been incremented
+1. Check that a publish will be successful
+    ```
+    > npm publish --dry-run
+    ```
+1. Commit changes, push to github and create pull request
+1. After committing to main branch in github, create a release with a name which matches the version number (ie. if version number is `1.0.0`, release name **MUST** be `v1.0.0`)
+1. Check that the publish action has published the package from the release
+
+
+# Visual Studio Extensions
+
+The following recommendations are made:
+
+- `Code Spell Checker` - see above section on Spelling
+<!--- cspell:disable-next-line --->
+- `ryanluker.vscode-coverage-gutters` - provides live coverage info in the left gutter.
+    - Command Palette `Coverage Gutters: Display Coverage` to start
+    - Command Palette `Coverage Gutters: Watch` to watch for changes
+<!--- cspell:disable-next-line --->
+- `dbaeumer.vscode-eslint` - provides typescript linting
+
+## devDependencies List
+
+- Typescript:
+    - `typescript`
+    - `ts-node`
+- Testing:
+    - `@types/chai`
+    - `@types/mocha`
+    - `chai`
+    - `mocha`
+- Test Coverage:
+    - `c8`
+- Linting:
+    - `eslint`
+    - `@shopify/eslint-plugin` (typescript)
+    - `eslint-plugin-tsdoc` (TSDoc)
+- Spelling:
+    - `cspell`