# `@particle/device-os-version-checks`

Version checking utilities for Device OS


## Installation

```shell
npm install @particle/device-os-version-checks --save
```

<!-- private-module-note-start -->

<!-- private-module-note-end -->


## API
<!-- api-docs-start -->
<a name="module_@particle/device-os-version-checks"></a>

### @particle/device-os-version-checks

* [@particle/device-os-version-checks](#module_@particle/device-os-version-checks)
    * [.isObsoleteFirmware(target, allFirmware)](#module_@particle/device-os-version-checks.isObsoleteFirmware) ⇒ <code>boolean</code>
    * [.isLTSVersion(target)](#module_@particle/device-os-version-checks.isLTSVersion) ⇒ <code>boolean</code>
    * [.isReleaseVersion(target)](#module_@particle/device-os-version-checks.isReleaseVersion) ⇒ <code>boolean</code>
    * [.isPreReleaseVersion(target)](#module_@particle/device-os-version-checks.isPreReleaseVersion) ⇒ <code>boolean</code>
    * [.isSourceVersion(target)](#module_@particle/device-os-version-checks.isSourceVersion) ⇒ <code>boolean</code>
    * [.isExperimental(target)](#module_@particle/device-os-version-checks.isExperimental) ⇒ <code>boolean</code>
    * [.pickLatestVersion(a, b)](#module_@particle/device-os-version-checks.pickLatestVersion) ⇒ <code>string</code>


* * *

<a name="module_@particle/device-os-version-checks.isObsoleteFirmware"></a>

#### deviceOSVersionChecks.isObsoleteFirmware(target, allFirmware) ⇒ <code>boolean</code>
Determines if given Device OS version is considered obsolete based on a list
of available versions.

Summary of rules:
if you're on LTS, you should be on the latest major version. if you're on an
RC (prerelease), it should be newer than any non-RC or LTS release and you
should be on the latest RC available. if you are on a normal release
(non-RC, non-LTS), you should be on the latest major and no more than 2 minor
releases behind. if you're on something older than v1.4.4, you should update.
otherwise, you're good!

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>boolean</code> - Whether or not the given version is considered obsolete.  

| Param | Type | Description |
| --- | --- | --- |
| target | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object                                 with a similarly formatted `version` field. |
| allFirmware | <code>string</code> \| <code>array</code> | The list of firmware versions (either                                     strings or objects) to check against.                                     NOTE: MUST BE SORTED IN DESCENDING ORDER |

**Example**  
```js
const version = '1.0.0';
const dependency = { version };

const allFirmware = [
    { version: '1.0.0' },
    { version: '0.9.0' },
    { version: '0.8.0' },
    { version: '0.7.0' }
];

if (isObsoleteFirmware(version || dependency, allFirmware)){
    console.warn('...');
}
```

* * *

<a name="module_@particle/device-os-version-checks.isLTSVersion"></a>

#### deviceOSVersionChecks.isLTSVersion(target) ⇒ <code>boolean</code>
Determines if given Device OS version is an LTS (long-term support) line.

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>boolean</code> - Whether or not the given version is an LTS line.  

| Param | Type | Description |
| --- | --- | --- |
| target | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object                                 with a similarly formatted `version` field. |

**Example**  
```js
const version = '4.0.0';
const dependency = { version };

if (isLTSVersion(version || dependency)){
    console.log('LTS!');
}
```

* * *

<a name="module_@particle/device-os-version-checks.isReleaseVersion"></a>

#### deviceOSVersionChecks.isReleaseVersion(target) ⇒ <code>boolean</code>
Determines if given Device OS version is a standard (non-LTS, non-rc) line.

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>boolean</code> - Whether or not the given version is a standard (non-LTS, non-rc) line.  

| Param | Type | Description |
| --- | --- | --- |
| target | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object                                 with a similarly formatted `version` field. |

**Example**  
```js
const version = '1.0.0';
const dependency = { version };

if (isReleaseVersion(version || dependency)){
    console.log('standard release line');
}
```

* * *

<a name="module_@particle/device-os-version-checks.isPreReleaseVersion"></a>

#### deviceOSVersionChecks.isPreReleaseVersion(target) ⇒ <code>boolean</code>
Determines if given Device OS version is a pre-release (rc).

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>boolean</code> - Whether or not the given version is a pre-release (rc).  

| Param | Type | Description |
| --- | --- | --- |
| target | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object                                 with a similarly formatted `version` field. |

**Example**  
```js
const version = '1.0.0-rc.1';
const dependency = { version };

if (isPreReleaseVersion(version || dependency)){
    console.log('RC!');
}
```

* * *

<a name="module_@particle/device-os-version-checks.isSourceVersion"></a>

#### deviceOSVersionChecks.isSourceVersion(target) ⇒ <code>boolean</code>
Determines if given Device OS version is source (e.g. `deviceOS@source`).

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>boolean</code> - Whether or not the given version is source (e.g. `deviceOS@source`).  

| Param | Type | Description |
| --- | --- | --- |
| target | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object                                 with a similarly formatted `version` field. |

**Example**  
```js
const version = 'source';

if (isSourceVersion(version)){
    console.log('working from source!');
}
```

* * *

<a name="module_@particle/device-os-version-checks.isExperimental"></a>

#### deviceOSVersionChecks.isExperimental(target) ⇒ <code>boolean</code>
Determines if given Device OS version is experimental.

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>boolean</code> - Whether or not the given version is experimental.  

| Param | Type | Description |
| --- | --- | --- |
| target | <code>object</code> | FirmwareDependency with status property. |


* * *

<a name="module_@particle/device-os-version-checks.pickLatestVersion"></a>

#### deviceOSVersionChecks.pickLatestVersion(a, b) ⇒ <code>string</code>
Returns greater of two targets' semver-compaitble version string.

**Kind**: static method of [<code>@particle/device-os-version-checks</code>](#module_@particle/device-os-version-checks)  
**Returns**: <code>string</code> - The greater version amongst `a` and `b`.  

| Param | Type | Description |
| --- | --- | --- |
| a | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object with                            a similarly formatted `version` field. |
| b | <code>string</code> \| <code>object</code> | Semver-compaitble version string or an object with                            a similarly formatted `version` field. |

**Example**  
```js
const a = '0.6.0';
const b = { version: '0.8.5' };
const latest = pickLatestVersion(a, b);
console.log(latest); // 0.8.5;
```

* * *


<!-- api-docs-end -->

_NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in [tests](./src/index.test.js)_