Full upgrade

.eslintrc.json

@@ -0,0 +1,12 @@
+{
+    "extends": ["@tfso/eslint-config/javascript", "prettier"],
+    "env": {
+        "mocha": true
+    },
+    "rules": {
+        "no-unused-vars": [
+            "warn",
+            { "vars": "all", "args": "none", "ignoreRestSiblings": true }
+        ]
+    }
+}

.github/workflows/build.yml

@@ -1,31 +1,79 @@
+## The workflow will:
+##  - create a new version, build the package and run tests
+##  - publish a release to npm when you create a new GitHub release.
+##  - publish a prerelease to npm from:
+##     - main branch
+##     - all branches with #deploy_branch in the commit message.
+##
+## The workflow assumes the following:
+##  - package.json has a "version" property
+##  - package.json has a "name" with the format "@tfso/<my-package>"
+##  - package.json has the following scripts
+##    - "build" - build the package into the ./dist folder
+##    - "test"
+##  - the project is installable with "npm ci"
+
 name: Build Package
 
 on:
-  push:
-    branches:
-      - "**"
-    tags-ignore:
-      - "*.*"
+    push:
+        branches:
+            - '**'
+        tags-ignore:
+            - '*.*'
 
 jobs:
-  Publish:
-    name: Build Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: build code
-        uses: actions/checkout@v3
-
-      - name: setup
-        uses: actions/setup-node@v3
-        with:
-          node-version: "18.x"
-
-      - name: npm access token
-        run: |
-          npm config set @tfso:registry=https://npm.pkg.github.com --userconfig .npmrc
-          npm config set //npm.pkg.github.com/:_authToken=${NPM_TOKEN} --userconfig .npmrc
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TFSO_TOKEN }}
-
-      - name: build project
-        run: npm ci
+    build:
+        name: Build and test
+        runs-on: ubuntu-latest
+        outputs:
+            version: ${{ steps.npm.outputs.version }}
+            prerelease: ${{ steps.npm.outputs.prerelease }}
+            is_prerelease: ${{ steps.npm.outputs.is_prerelease }}
+            deploy: ${{ steps.npm.outputs.deploy }}
+
+        steps:
+            - name: Install, build and test
+              uses: tfso/action-helpers/npm-build@v1
+              id: npm
+              with:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                  GITHUB_GLOBAL_TOKEN: ${{ secrets.TFSO_REPO_READ }}
+                  NPM_TOKEN: ${{ secrets.NPM_TFSO_TOKEN }}
+                  TRUNCATE_PRERELEASE: true
+                  NODE_VERSION: 18
+
+            - name: upload artifact (from content in ./dist folder)
+              uses: actions/upload-artifact@v3
+              with:
+                  name: artifact
+                  path: ./dist
+
+    publish:
+        name: publish prerelease
+        if: ${{ needs.build.outputs.deploy == 'true' }}
+        needs: build
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            packages: write
+
+        steps:
+            - name: download artifact
+              uses: actions/download-artifact@v3
+              with:
+                  name: artifact
+
+            - name: setup
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 18
+                  registry-url: https://npm.pkg.github.com/
+                  scope: '@tfso'
+
+            - name: Publish prerelease to Npm
+              run: |
+                  npm version prerelease --preid=${{github.ref_name}}-${{github.run_number}} --no-git-tag-version
+                  npm publish --verbose --tag dev --no-tag
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -1,70 +1,88 @@
+## The workflow will:
+##  - create a new version, build the package and run tests
+##  - publish a release to npm when you create a new GitHub release.
+##  - publish a prerelease to npm from:
+##     - main branch
+##     - all branches with #deploy_branch in the commit message.
+##
+## The workflow assumes the following:
+##  - package.json has a "version" property
+##  - package.json has a "name" with the format "@tfso/<my-package>"
+##  - package.json has the following scripts
+##    - "build" - build the package into the ./dist folder
+##    - "test"
+##  - the project is installable with "npm ci"
+
 name: Release Package
 
 on:
-  release:
-    types: [published]
+    release:
+        types: [published]
 
 jobs:
-  build:
-    name: create release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
+    build:
+        name: build release
+        runs-on: ubuntu-latest
+        if: github.event.release.draft == false && github.event.release.prerelease == false
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: npm access token
+              run: |
+                  npm config set @tfso:registry=https://npm.pkg.github.com --userconfig .npmrc
+                  npm config set //npm.pkg.github.com/:_authToken=${NPM_TOKEN} --userconfig .npmrc
+              env:
+                  NPM_TOKEN: ${{ secrets.NPM_TFSO_TOKEN }}
+
+            - name: Update package.json and CHANGELOG.md
+              run: |
+                  git config --global user.name '${{github.actor}}'
+                  git config --global user.email '${{github.actor}}@users.noreply.github.com'
+                  npm version ${{github.event.release.tag_name}} --no-git-tag-version
+                  npx auto-changelog -p && git add CHANGELOG.md
+                  git add package.json
+                  git commit -m "Update package.json version to ${{github.event.release.tag_name}} "
+                  git push origin HEAD:${{github.event.release.target_commitish}}
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 18
 
-      - name: npm access token
-        run: |
-          npm config set @tfso:registry=https://npm.pkg.github.com --userconfig .npmrc
-          npm config set //npm.pkg.github.com/:_authToken=${NPM_TOKEN} --userconfig .npmrc
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TFSO_TOKEN }}
+            - name: install project
+              run: npm ci
 
-      - name: Update package.json
-        run: |
-          git config --global user.name '${{github.actor}}'
-          git config --global user.email '${{github.actor}}@users.noreply.github.com'
-          npm version ${{github.event.release.tag_name}} --no-git-tag-version
-          git add package.json
-          git commit -m "Update package.json version to $version"
-          git push origin HEAD:master
+            - name: build project
+              run: npm run build
 
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-      - name: build project
-        run: npm ci
+            - name: upload artifact (from content in ./dist folder)
+              uses: actions/upload-artifact@v3
+              with:
+                  name: artifact
+                  path: ./dist
 
-      - name: upload artifact
-        uses: actions/[email protected]
-        with:
-          name: artifact
-          path: |
-            src/
-            index.js
-            package.json
-            README.md
+    publish:
+        name: publish release
+        needs: build
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            packages: write
 
-  publish-gpr:
-    name: publish to github
-    if: github.event.release.draft == false && github.event.release.prerelease == false
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    steps:
-      - name: download artifact
-        uses: actions/[email protected]
-        with:
-          name: artifact
+        steps:
+            - name: download artifact
+              uses: actions/download-artifact@v3
+              with:
+                  name: artifact
 
-      - name: setup
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: https://npm.pkg.github.com/
-          scope: "@tfso"
+            - name: setup
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 18
+                  registry-url: https://npm.pkg.github.com/
+                  scope: '@tfso'
 
-      - name: publish
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
+            - name: Publish release to Npm
+              run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -1,2 +1,5 @@
 .idea/
-node_modules/
+node_modules/
+.nyc_output/
+coverage/
+dist/

.prettierignore

@@ -0,0 +1,5 @@
+dist
+.nyc_output
+coverage
+package-lock.json
+package.json

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+    "trailingComma": "es5",
+    "tabWidth": 4,
+    "semi": false,
+    "singleQuote": true,
+    "printWidth": 80
+}

README.md

@@ -129,4 +129,76 @@ async function main(){
     readers[1].asArrayAll('list.item.nestedlist.nesteditem').map(r => r.val())
     // ['3', '4']
 }
-````
+````
+
+## Change log
+The [CHANGELOG.md](CHANGELOG.md) is automatically generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog) by analysing PR, tags and commits.
+
+# Contribution
+You are welcome to contribute to the project by creating a pull request. Please follow the guidelines below to 
+contribute effectively.
+
+## Creating a Pull Request (PR)
+To create a pull request, follow these steps:
+### 1. Clone the repository
+
+### 2. Create branch
+
+- Create a new branch for your feature or bug fix.
+
+```shell
+git checkout -b feature/your-feature
+```
+
+### 2. Make Changes
+
+- Make your changes and ensure they follow our coding standards.
+
+### 3. Commit Changes
+
+- Include `#deploy_branch` in your commit message in order to create a prerelease of your branch
+
+```shell
+git add .
+git commit -m "Descriptive commit message #deploy_branch"
+```
+
+### 4. Push Changes
+
+- Push your changes to the repository.
+
+```shell
+git push origin feature/your-feature
+```
+
+### 5. Open a Pull Request
+
+- Go this repository on GitHub
+- Click on "New Pull Request."
+- Provide a detailed description of your changes.
+- Add a reviewer to your pull request.
+
+## Prerelease
+If you need to test your branch during development, create a commit that includes `#deploy_branch` in the commit message. 
+This will trigger a prerelease, allowing you to test in your project without creating a full package release. 
+
+### CICD rules
+- auto prerelease on commit message `#deploy_branch`
+- auto prerelease from `main` branch
+
+## Release
+To create a new official release that update the `latest` release of the package, follow these steps:
+
+### 1. Merge to Master
+   - Ensure your changes are merged into the main branch.
+### 2. Draft a New Release
+   - Go to the GitHub repository.
+   - Click on the "Releases" tab.
+   - Click "Draft a new release."
+### 3. Tag the Release
+   - Choose a version number following semantic versioning (e.g., v1.0.0).
+   - Provide release notes summarizing the changes since the last release.
+### 4. Publish the Release
+   - Click "Publish release" to make it official.
+
+Thank you for your contribution!

build.sh

@@ -0,0 +1,15 @@
+#! /bin/bash
+
+export dir=dist
+if [[ ! -e $dir ]]; then
+    mkdir $dir
+elif [[ ! -d $dir ]]; then
+    echo "$dir already exists but is not a directory" 1>&2
+fi
+
+rm -rf ./dist/*
+
+cp -r ./src ./dist/
+cp README.md ./dist/
+cp package.json ./dist/
+cp index.js ./dist/