chore(release): v3.1.0 ✨

.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  github-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/github-script@v6
+        id: get-version
+        with:
+          result-encoding: string
+          script: |
+            const major = process.env.GITHUB_REF_NAME.substring(1, 2)
+            const fullVersion = process.env.GITHUB_REF_NAME.substring(1)
+
+            core.setOutput('major', major)
+            core.setOutput('full', fullVersion)
+      - uses: actions/github-script@v6
+        id: extract-changelog
+        env:
+          VERSION_MAJOR: '${{ steps.get-version.outputs.major }}'
+          VERSION_FULL: '${{ steps.get-version.outputs.full }}'
+        with:
+          result-encoding: string
+          script: |
+            const file = `docs/changelog/${process.env.VERSION_MAJOR}/${process.env.VERSION_FULL}.md`
+
+            let output = ''
+            const options = {
+              listeners: {
+                stdout: (data: Buffer) => {
+                  output += data.toString('utf8')
+                }
+              }
+            }
+            await exec.exec(`cat ${file} | tail -n +5`)
+
+            core.setOutput('markdown', output.trim())
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: |
+            ## Changelog
+            ${{ steps.extract-changelog.outputs.markdown }}

docs/versioned_docs/version-3.1.0/api.md

@@ -0,0 +1,103 @@
+---
+sidebar_position: 4
+sidebar_label: 🧩 API
+---
+
+# API
+
+```js
+// Require the module
+const versionCheck = require('@version-checker/core');
+
+// Or import
+import versionCheck from '@version-checker/core'
+```
+
+## `function versionCheck(options, [callback])`
+Performs an update check with the given options. The `callback` is optional, can be omitted to return a `Promise`.
+
+### The `options` object
+Option | Description | Default Value | Introduction
+--- | --- | --- | ---
+token | A [personal access token](https://blog.github.com/2013-05-16-personal-api-tokens/) used to access the **Github GraphQL API (v4)**. Can be omitted and instead be read from an env variable called `GITHUB_API_TOKEN`. When no token can be found, the module will fall back to the **Github Rest API (v3)**. | `undefined` | `v2.0.0`
+repo | The name of your Github repository.| **None. Required.** | `v1.0.0`
+owner | The owner of your Github repository (usually your username).| **None. Required.** | `v1.0.0`
+currentVersion | Your app's current version. | **None. Required.** | `v1.0.0`
+fetchTags | Whether to fetch the repositories' git tags instead of the GitHub releases. Useful when no releases are created, but only tags. | `false` | `v1.0.0`
+latestOnly | Setting this to `true` will fetch the latest release only | `false` | `v2.2.0`
+excludePrereleases | Excludes pre-releases from checks. Currently only works when no token is specified. | `false` | `v2.3.0`
+forceRest | Will use the Github REST API (v3) even with a supplied token. | `false` | `v3.0.0`
+
+### The `callback` function (optional)
+Should be of the following form:
+```javascript
+function(error, update) {
+  // ...your code
+}
+```
+* `error`:
+  * If an error occurs, this holds the error message. `null` if no error occurs.
+* `update`:
+  * An object in the format specified below. `null` if no update was found.
+
+### Return type
+
+The function returns a `CheckResult` which has the following structure:
+
+```typescript
+interface CheckResult {
+    src: string
+    type: string
+    update: ReleaseDescriptor | TagDescriptor | undefined
+}
+```
+
+#### Properties
+##### `src`
+
+States which API endpoint has been used.
+
+Possible values:
+
+- `rest`
+- `graphql`
+
+##### `type`
+
+States whether releases or tags have been fetched.
+
+Possible values:
+
+- `releases`
+- `tags`
+
+##### `update`
+
+Holds the actual data on a possible update. For structure details refer to [Object schemes](#object-schemes).
+
+It is `undefined` in case no update could be found.
+
+### Using `Promise`
+You can omit the `callback` function to return a `Promise`, which resolves with the `update` object.
+
+## Object schemes
+### ReleaseDescriptor
+When fetching releases, an object with the following structure will be returned:
+```typescript
+interface ReleaseDescriptor {
+    name: string
+    tag: TagDescriptor
+    isPrerelease: boolean
+    isDraft: boolean
+    publishedAt: string
+    url: string
+}
+```
+
+### TagDescriptor
+When fetching tags, you will receive an object with the following structure:
+```typescript
+interface TagDescriptor {
+    name: string
+}
+```

docs/versioned_docs/version-3.1.0/browser-support.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 3
+sidebar_label: 🌐 Browser Support
+---
+
+# Browser Support
+
+To use this in the browser, install `@version-checker/browser` instead of `@version-checker/core`.
+
+Subsequently, import `@version-checker/browser` instead of `@version-checker/core`.
+
+**Note**: This is currently **EXPERIMENTAL**, as it depends on `@octokit/core^5.0.0-beta.4^` and the
+[Node.js Fetch API](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#fetch).

docs/versioned_docs/version-3.1.0/cli/01-installation.md

@@ -0,0 +1,11 @@
+# Installation
+
+## npm
+
+```shell
+npm install -g @version-checker/cli
+```
+
+## Binary
+
+Download a binary version from the [releases page](https://github.com/axelrindle/github-version-checker/releases).

docs/versioned_docs/version-3.1.0/cli/02-examples.md

@@ -0,0 +1,40 @@
+# Usage Examples
+
+## Basic
+
+```shell
+$ version-checker \
+    --owner axelrindle \
+    --repository version-checker \
+    --current-version 2.2.0
+```
+
+```
+An update is available! v3.0.0
+You are on version 2.3.0!
+```
+
+## With json output
+
+```shell
+$ version-checker --json \
+    --owner axelrindle \
+    --repository version-checker \
+    --current-version 2.2.0
+```
+
+```json
+{
+  "type": "outdated",
+  "data": {
+    "name": "v2.3.0",
+    "tag": {
+      "name": "2.3.0"
+    },
+    "isPrerelease": false,
+    "isDraft": false,
+    "publishedAt": "2022-03-18T15:22:03Z",
+    "url": "https://github.com/axelrindle/github-version-checker/releases/tag/2.3.0"
+  }
+}
+```

docs/versioned_docs/version-3.1.0/cli/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "⌨️ Command Line Interface (CLI)",
+    "position": 5,
+    "link": {
+        "type": "doc",
+        "id": "cli/index"
+    }
+}

docs/versioned_docs/version-3.1.0/cli/index.md

@@ -0,0 +1,24 @@
+# Command Line Interface (CLI)
+
+The CLI offers to perform a version check in non-Node.js environments.
+It supports plain-text and JSON-formatted output.
+
+## Usage
+
+```
+
+  $ version-checker [options]
+
+  Options
+    -o, --owner              The repository owner. May be a username or organization name.
+    -r, --repository         The repository name.
+    -c, --current-version    The current application version.
+    -t, --tags               Fetches tags instead of releases.
+    --no-pre-releases        Excludes pre-releases.  (default false)
+    --token                  A PAT to use.
+    --json                   Outputs the raw result data as JSON.  (default false)
+    --verbose                Enables verbose logging.  (default false)
+    -v, --version            Displays current version
+    -h, --help               Displays this message
+
+```

docs/versioned_docs/version-3.1.0/examples/01-basic/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "🥸 Basic",
+    "position": 1,
+    "link": {
+        "type": "generated-index",
+        "title": "Basic Examples"
+    }
+}

docs/versioned_docs/version-3.1.0/examples/01-basic/async.md

@@ -0,0 +1,26 @@
+# Async / Await
+
+The future is now! Futuristic approach leveraging top-level await.
+
+```js showLineNumbers title="src/util/version-check.js"
+const versionCheck = require('@version-checker/core')
+const options = {
+    // token: '...',
+    repo: 'version-checker',
+    owner: 'axelrindle',
+    currentVersion: require('../package.json').version
+}
+
+try {
+    // highlight-next-line
+    const { update } = await versionCheck(options)
+    if (update) { // update is null if there is no update available, so check here
+        console.log('An update is available! ' + update.name)
+        console.log('You are on version ' + options.currentVersion + '!')
+    } else {
+        console.log('You are up to date.')
+    }
+} catch (e) {
+    console.error(e)
+}
+```

docs/versioned_docs/version-3.1.0/examples/01-basic/callback.md

@@ -0,0 +1,28 @@
+# Callback
+
+Using a plain old callback.
+
+````js showLineNumbers title="src/util/version-check.js"
+const versionCheck = require('@version-checker/core')
+const options = {
+    // token: '...',
+    repo: 'version-checker',
+    owner: 'axelrindle',
+    currentVersion: require('../package.json').version
+}
+
+versionCheck(options, function (error, result) {
+    if (error) {
+        console.error(error)
+        process.exit(-1)
+    }
+
+    const { update } = result
+    if (update) {
+        console.log('An update is available! ' + update.name)
+        console.log('You are on version ' + options.currentVersion + '!')
+    } else {
+        console.log('You are up to date.')
+    }
+})
+```

docs/versioned_docs/version-3.1.0/examples/01-basic/promise.md

@@ -0,0 +1,27 @@
+# Promise
+
+Modern version using a Promise-based approach.
+
+```js showLineNumbers title="src/util/version-check.js"
+const versionCheck = require('@version-checker/core')
+const options = {
+    // token: '...',
+    repo: 'version-checker',
+    owner: 'axelrindle',
+    currentVersion: require('../package.json').version
+}
+
+versionCheck(options)
+    .then(function (result) {
+        const { update } = result
+        if (update) { // update is null if there is no update available, so check here
+            console.log('An update is available! ' + update.name)
+            console.log('You are on version ' + options.currentVersion + '!')
+        } else {
+            console.log('You are up to date.')
+        }
+    })
+    .catch(function (error) {
+        console.error(error)
+    })
+```

docs/versioned_docs/version-3.1.0/examples/02-advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "👨‍🎓 Advanced",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "title": "Advanced Examples"
+    }
+}

docs/versioned_docs/version-3.1.0/examples/02-advanced/git-tags.md

@@ -0,0 +1,33 @@
+# Fetch Git tags instead of GitHub releases
+
+In case your repository does not use GitHub releases but just Git tags a call to the
+releases api won't work.
+
+Fetch the tags instead by setting `fetchTags` to `true`:
+
+```js showLineNumbers title="src/util/version-check.js"
+const versionCheck = require('@version-checker/core')
+const options = {
+    token: 'my-token',
+    repo: 'version-checker',
+    owner: 'axelrindle',
+    currentVersion: require('../package.json').version,
+    // highlight-next-line
+    fetchTags: true
+}
+
+versionCheck(options, function (error, result) {
+    if (error) {
+        console.error(error)
+        process.exit(-1)
+    }
+
+    const { update } = result
+    if (update) {
+        console.log('An update is available! ' + update.name)
+        console.log('You are on version ' + options.currentVersion + '!')
+    } else {
+        console.log('You are up to date.')
+    }
+})
+```