Add examples/ sub-project

.travis.yml

@@ -6,7 +6,9 @@ node_js:
 
 script:
     - npm run lint
-    - npm run build:silent
+    - npm run build
+    - npm run init:examples
+    - npm run build:examples:silent
     - npm run test
     - npm run test:int
     - npm run test:coverage:coveralls

commons/constants.ts

@@ -1,4 +1,7 @@
+import type { IConfigOptions } from '../interfaces/config.interfaces'
 import type { LoggerConfig } from '../interfaces/interfaces'
+import type { IChromeFullConfig, IChromeSingleConfig } from '../interfaces/interfaces'
+import { ComparableVersion } from './ComparableVersion'
 
 export const LOAD_CONFIG: LoggerConfig = {
     start: 'Downloading local storage file',
@@ -25,3 +28,49 @@ export const SEARCH_BINARY: LoggerConfig = {
     success: 'Binary found.',
     fail: 'No binary found!',
 }
+
+export const DEFAULT_CONFIG_OPTIONS: IConfigOptions = {
+    min: '0',
+    max: '10000',
+
+    nonInteractive: false,
+    hideNegativeHits: false,
+    onlyNewestMajor: false,
+    inverse: false,
+    store: true,
+    download: true,
+    increaseOnFail: false,
+    decreaseOnFail: false,
+    unzip: false,
+    quiet: false,
+}
+
+export const DEFAULT_FULL_CONFIG: IChromeFullConfig = {
+    arch: 'x64',
+    autoUnzip: false,
+    download: true,
+    downloadFolder: null,
+    hideNegativeHits: false,
+    interactive: true,
+    max: new ComparableVersion(10000, 0, 0, 0),
+    min: new ComparableVersion(0, 0, 0, 0),
+    onFail: 'nothing',
+    onlyNewestMajor: false,
+    os: 'linux',
+    results: 10,
+    store: true,
+    single: null,
+    inverse: false,
+    quiet: false,
+}
+
+export const DEFAULT_SINGLE_CONFIG: IChromeSingleConfig = {
+    arch: 'x64',
+    os: 'linux',
+    autoUnzip: false,
+    store: true,
+    download: true,
+    downloadFolder: null,
+    single: new ComparableVersion(10, 0, 0, 0),
+    quiet: false,
+}

config/config.spec.ts

@@ -8,11 +8,12 @@ import type { MaybeMockedDeep } from 'ts-jest/dist/utils/testing'
 import { mocked } from 'ts-jest/utils'
 
 import { ComparableVersion } from '../commons/ComparableVersion'
+import { DEFAULT_CONFIG_OPTIONS } from '../commons/constants'
 import type { IChromeConfigWrapper, IStoreConfigWrapper, IExportConfigWrapper } from '../interfaces/interfaces'
 import type { OS } from '../interfaces/os.interfaces'
 import { Spinner, logger } from '../log/spinner'
 import { createChromeFullConfig, createChromeOptions, createImportConfig, createExportConfig, createChromeSingleConfig } from '../test/test.utils'
-import { DEFAULT_OPTIONS, readConfig } from './config'
+import { readConfig } from './config'
 
 /* eslint-disable-next-line @typescript-eslint/no-var-requires */
 const program = require('commander')
@@ -116,7 +117,7 @@ describe('config', () => {
 
             it('should set increase on fail', () => {
                 programMock.opts.mockReturnValue({
-                    ...DEFAULT_OPTIONS,
+                    ...DEFAULT_CONFIG_OPTIONS,
                     increaseOnFail: true,
                 })
 

config/config.ts

@@ -3,52 +3,37 @@
 import * as program from 'commander'
 
 import { ComparableVersion } from '../commons/ComparableVersion'
+import { DEFAULT_CONFIG_OPTIONS } from '../commons/constants'
 import type { IConfigOptions } from '../interfaces/config.interfaces'
 import type { ConfigWrapper, IChromeSingleConfig } from '../interfaces/interfaces'
 import { logger } from '../log/spinner'
 /* eslint-disable-next-line import/no-namespace */
 import * as packageJson from '../package.json'
 import { mapOS } from '../utils'
 
-export const DEFAULT_OPTIONS: IConfigOptions = {
-    min: '0',
-    max: '10000',
-
-    nonInteractive: false,
-    hideNegativeHits: false,
-    onlyNewestMajor: false,
-    inverse: false,
-    store: true,
-    download: true,
-    increaseOnFail: false,
-    decreaseOnFail: false,
-    unzip: false,
-    quiet: false,
-}
-
 /**
  * Checks the arguments passed to the programm and returns them
  */
 export function readConfig(args: string[], platform: NodeJS.Platform): ConfigWrapper {
     program
         .version(packageJson.version)
-        .option('-m, --min <version>', 'The minimum version', DEFAULT_OPTIONS.min)
-        .option('-M, --max <version>', 'The maximum version. Newest version if not specificied', DEFAULT_OPTIONS.max)
+        .option('-m, --min <version>', 'The minimum version', DEFAULT_CONFIG_OPTIONS.min)
+        .option('-M, --max <version>', 'The maximum version. Newest version if not specificied', DEFAULT_CONFIG_OPTIONS.max)
         .option('-r, --max-results <results>', 'The maximum amount of results to choose from', null)
         .option('-o, --os <os>', 'The operating system for what the binary should be downloaded')
         .option('-a, --arch <arch>', 'The architecture for what the binary should be downloaded. Valid values are "x86" and "x64". Only works when --os is also set')
         .option('-d, --decrease-on-fail', 'If a binary does not exist, go to the next lower version number and try again (regarding --min, --max and --max-results)', false)
         .option('-i, --increase-on-fail', 'If a binary does not exist, go to the next higher version number and try again (regarding --min, --max and --max-results), overwrites "--decrease-on-fail" if both set', false)
         .option('-z, --unzip', 'Directly unzip the downloaded zip-file and delete the .zip afterwards', false)
         .option('-n, --non-interactive', 'Don\'t show the selection menu. Automatically select the newest version. Only works when --decrease-on-fail is also set.', false)
-        .option('-t, --no-store', 'Don\'t store negative hits in the local store file.', DEFAULT_OPTIONS.store)
-        .option('-l, --no-download', 'Don\'t download the binary. It also continues with the next version, if --decrease-on-fail or --increase-on-fail is set. Useful to build up the negative hit store', DEFAULT_OPTIONS.download)
+        .option('-t, --no-store', 'Don\'t store negative hits in the local store file.', DEFAULT_CONFIG_OPTIONS.store)
+        .option('-l, --no-download', 'Don\'t download the binary. It also continues with the next version, if --decrease-on-fail or --increase-on-fail is set. Useful to build up the negative hit store', DEFAULT_CONFIG_OPTIONS.download)
         .option('-I, --import-store <url>', 'Imports a localstore.json file either by URL (starting with "http://" or "https://" or by local file')
         .option('-E, --export-store [path]', 'Exports the localstore.json file to stdout')
-        .option('-H, --hide-negative-hits', 'Hide negative hits', DEFAULT_OPTIONS.hideNegativeHits)
+        .option('-H, --hide-negative-hits', 'Hide negative hits', DEFAULT_CONFIG_OPTIONS.hideNegativeHits)
         .option('-f, --folder <folder>', 'Set the download folder', null)
-        .option('-O, --only-newest-major', 'Show only the newest major version in user selection', DEFAULT_OPTIONS.onlyNewestMajor)
-        .option('-v, --inverse', 'Sort the selectable versions ascending', DEFAULT_OPTIONS.inverse)
+        .option('-O, --only-newest-major', 'Show only the newest major version in user selection', DEFAULT_CONFIG_OPTIONS.onlyNewestMajor)
+        .option('-v, --inverse', 'Sort the selectable versions ascending', DEFAULT_CONFIG_OPTIONS.inverse)
         .option('-s, --single <version>', 'Download a specific version in non-interactive mode, even if the file is listed in the localstore.json. Several other flags have no effect.')
         .option('-q, --quiet', 'Suppress any logging output', false)
         .parse(args)

download.ts

@@ -4,11 +4,13 @@ import { Extract } from 'unzipper'
 import { promisify } from 'util'
 
 import { fetchChromeZipFile } from './api'
+import { DEFAULT_FULL_CONFIG, DEFAULT_SINGLE_CONFIG } from './commons/constants'
 import { NoChromiumDownloadError } from './errors'
 import type { IChromeConfig } from './interfaces/interfaces'
 import { progress } from './log/progress'
 import { logger } from './log/spinner'
 import { loadStore } from './store/loadStore'
+import { isChromeSingleConfig } from './utils/typeguards'
 import { getChromeDownloadUrl, loadVersions, mapVersions } from './versions'
 
 /* eslint-disable-next-line @typescript-eslint/no-var-requires */
@@ -37,7 +39,30 @@ function registerSigIntHandler(path: string): void {
     })
 }
 
-export async function downloadChromium(config: IChromeConfig): Promise<void> {
+function enrichAdditionalConfig(additionalConfig: Partial<IChromeConfig> = {}): IChromeConfig {
+    if (isChromeSingleConfig(additionalConfig)) {
+        return {
+            ...DEFAULT_SINGLE_CONFIG,
+            ...additionalConfig,
+        }
+    } else {
+        return {
+            ...DEFAULT_FULL_CONFIG,
+            ...additionalConfig,
+        }
+    }
+}
+
+/**
+ * Downloads a chromium zip file based on the given config
+ * @see DEFAULT_FULL_CONFIG
+ * @see DEFAULT_SINGLE_CONFIG
+ * @param additionalConfig Manually set config, which will override the settings in the default config
+ */
+export async function downloadChromium(additionalConfig?: Partial<IChromeConfig>): Promise<void> {
+
+    const config = enrichAdditionalConfig(additionalConfig)
+
     const versions = await loadVersions()
     const store = await loadStore()
 

examples/README.md

@@ -0,0 +1,110 @@
+# Examples for using rusted-chromium as API
+
+## Setup
+
+**in rusted-chromium folder:**
+```
+# in rusted-chromium folder:
+npm install
+npm run build
+```
+
+**switch to examples folder:**
+```
+cd examples
+npm install
+```
+
+## Usage
+
+**run directly using ts-node:**
+```bash
+npx ts-node example-download-single.ts
+```
+
+**build first:**
+```bash
+npm run build
+node example-download-single.js
+```
+
+## Available examples
+
+### example-download-all-params.ts
+Opens the cli prompt with a specific configuration (max version 95, ten results, ...).
+```ts
+import { ComparableVersion, downloadChromium } from 'rusted-chromium'
+
+downloadChromium({
+    arch: 'x64',
+    autoUnzip: false,
+    download: true,
+    hideNegativeHits: false,
+    interactive: true,
+    inverse: false,
+    max: new ComparableVersion(95, 0, 0, 0),
+    min: new ComparableVersion(0,0,0,0),
+    onFail: 'nothing',
+    onlyNewestMajor: false,
+    os: 'linux',
+    quiet: false,
+    store: true,
+    results: 10,
+    downloadFolder: null,
+    single: null,
+})
+```
+
+### example-download-single.ts
+
+Downloads a specific version (98.0.4707.2) for Linux 64-Bit.
+
+```
+import { ComparableVersion, downloadChromium } from 'rusted-chromium'
+
+downloadChromium({
+    single: new ComparableVersion(98, 0, 4707, 2),
+    os: 'linux',
+    arch: 'x64',
+})
+```
+
+### example-download.ts
+Opens the cli prompt with the default configuration, only setting os and arch.
+```ts
+import { downloadChromium } from 'rusted-chromium'
+
+downloadChromium({
+    arch: 'x64',
+    os: 'linux',
+})
+```
+
+### example-download-default-config.ts
+Opens the cli prompt with the default configuration.
+```ts
+import { downloadChromium } from 'rusted-chromium'
+
+downloadChromium()
+```
+
+### example-export.ts
+Exports the localstore.json to stdout.
+```ts
+import { exportStore } from 'rusted-chromium'
+
+exportStore({
+    quiet: false,
+}, process.stdout)
+```
+
+### example-import.ts
+Imports the localstore.json from a URL and merges it with an existing localstore.json file (if it exists).
+```ts
+import { importAndMergeLocalstore } from 'rusted-chromium'
+
+importAndMergeLocalstore({
+    quiet: false,
+    url: 'https://rusted.buzz-t.eu/localstore.json'
+})
+```

examples/example-download-all-params.ts

@@ -0,0 +1,20 @@
+import { ComparableVersion, downloadChromium } from 'rusted-chromium'
+
+downloadChromium({
+    arch: 'x64',
+    autoUnzip: false,
+    download: true,
+    hideNegativeHits: false,
+    interactive: true,
+    inverse: false,
+    max: new ComparableVersion(95, 0, 0, 0),
+    min: new ComparableVersion(0,0,0,0),
+    onFail: 'nothing',
+    onlyNewestMajor: false,
+    os: 'linux',
+    quiet: false,
+    store: true,
+    results: 10,
+    downloadFolder: null,
+    single: null,
+})

examples/example-download-default-config.ts

@@ -0,0 +1,3 @@
+import { downloadChromium } from 'rusted-chromium'
+
+downloadChromium()

examples/example-download-single.ts

@@ -0,0 +1,7 @@
+import { ComparableVersion, downloadChromium } from 'rusted-chromium'
+
+downloadChromium({
+    single: new ComparableVersion(98, 0, 4707, 2),
+    os: 'linux',
+    arch: 'x64',
+})

examples/example-download.ts

@@ -0,0 +1,6 @@
+import { downloadChromium } from 'rusted-chromium'
+
+downloadChromium({
+    arch: 'x64',
+    os: 'linux',
+})

examples/example-export.ts

@@ -0,0 +1,5 @@
+import { exportStore } from 'rusted-chromium'
+
+exportStore({
+    quiet: false,
+}, process.stdout)

examples/example-import.ts

@@ -0,0 +1,6 @@
+import { importAndMergeLocalstore } from 'rusted-chromium'
+
+importAndMergeLocalstore({
+    quiet: false,
+    url: 'https://rusted.buzz-t.eu/localstore.json'
+})