<!-- don't edit here, its from https://@github.com/arangodb/arangodbjs.git / docs/Drivers/ -->
# Managing Foxx services

## database.listServices

`async database.listServices([excludeSystem]): Array<Object>`

Fetches a list of all installed service.

**Arguments**

* **excludeSystem**: `boolean` (Default: `true`)

  Whether system services should be excluded.

**Examples**

```js
const services = await db.listServices();

// -- or --

const services = await db.listServices(false);
```

## database.installService

`async database.installService(mount, source, [options]): Object`

Installs a new service.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **source**: `Buffer | Readable | File | string`

  The service bundle to install.

* **options**: `Object` (optional)

  An object with any of the following properties:

  * **configuration**: `Object` (optional)

    An object mapping configuration option names to values.

  * **dependencies**: `Object` (optional)

    An object mapping dependency aliases to mount points.

  * **development**: `boolean` (Default: `false`)

    Whether the service should be installed in development mode.

  * **legacy**: `boolean` (Default: `false`)

    Whether the service should be installed in legacy compatibility mode.

    This overrides the `engines` option in the service manifest (if any).

  * **setup**: `boolean` (Default: `true`)

    Whether the setup script should be executed.

**Examples**

```js
const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.installService('/hello', source);

// -- or --

const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.installService('/hello', source);

// -- or --

const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.installService('/hello', source);
```

## database.replaceService

`async database.replaceService(mount, source, [options]): Object`

Replaces an existing service with a new service by completely removing the old
service and installing a new service at the same mount point.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **source**: `Buffer | Readable | File | string`

  The service bundle to replace the existing service with.

* **options**: `Object` (optional)

  An object with any of the following properties:

  * **configuration**: `Object` (optional)

    An object mapping configuration option names to values.

    This configuration will replace the existing configuration.

  * **dependencies**: `Object` (optional)

    An object mapping dependency aliases to mount points.

    These dependencies will replace the existing dependencies.

  * **development**: `boolean` (Default: `false`)

    Whether the new service should be installed in development mode.

  * **legacy**: `boolean` (Default: `false`)

    Whether the new service should be installed in legacy compatibility mode.

    This overrides the `engines` option in the service manifest (if any).

  * **teardown**: `boolean` (Default: `true`)

    Whether the teardown script of the old service should be executed.

  * **setup**: `boolean` (Default: `true`)

    Whether the setup script of the new service should be executed.

**Examples**

```js
const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.replaceService('/hello', source);

// -- or --

const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.replaceService('/hello', source);

// -- or --

const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.replaceService('/hello', source);
```

## database.upgradeService

`async database.upgradeService(mount, source, [options]): Object`

Replaces an existing service with a new service while retaining the old
service's configuration and dependencies.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **source**: `Buffer | Readable | File | string`

  The service bundle to replace the existing service with.

* **options**: `Object` (optional)

  An object with any of the following properties:

  * **configuration**: `Object` (optional)

    An object mapping configuration option names to values.

    This configuration will be merged into the existing configuration.

  * **dependencies**: `Object` (optional)

    An object mapping dependency aliases to mount points.

    These dependencies will be merged into the existing dependencies.

  * **development**: `boolean` (Default: `false`)

    Whether the new service should be installed in development mode.

  * **legacy**: `boolean` (Default: `false`)

    Whether the new service should be installed in legacy compatibility mode.

    This overrides the `engines` option in the service manifest (if any).

  * **teardown**: `boolean` (Default: `false`)

    Whether the teardown script of the old service should be executed.

  * **setup**: `boolean` (Default: `true`)

    Whether the setup script of the new service should be executed.

**Examples**

```js
const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.upgradeService('/hello', source);

// -- or --

const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.upgradeService('/hello', source);

// -- or --

const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.upgradeService('/hello', source);
```

## database.uninstallService

`async database.uninstallService(mount, [options]): void`

Completely removes a service from the database.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **options**: `Object` (optional)

  An object with any of the following properties:

  * **teardown**: `boolean` (Default: `true`)

    Whether the teardown script should be executed.

**Examples**

```js
await db.uninstallService('/my-service');
// service was uninstalled
```

## database.getService

`async database.getService(mount): Object`

Retrieves information about a mounted service.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const info = await db.getService('/my-service');
// info contains detailed information about the service
```

## database.getServiceConfiguration

`async database.getServiceConfiguration(mount, [minimal]): Object`

Retrieves an object with information about the service's configuration options
and their current values.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **minimal**: `boolean` (Default: `false`)

  Only return the current values.

**Examples**

```js
const config = await db.getServiceConfiguration('/my-service');
// config contains information about the service's configuration
```

## database.replaceServiceConfiguration

`async database.replaceServiceConfiguration(mount, configuration, [minimal]):
Object`

Replaces the configuration of the given service.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **configuration**: `Object`

  An object mapping configuration option names to values.

* **minimal**: `boolean` (Default: `false`)

  Only return the current values and warnings (if any).

  **Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
  triggering a second request to the database.

**Examples**

```js
const config = {currency: 'USD', locale: 'en-US'};
const info = await db.replaceServiceConfiguration('/my-service', config);
// info.values contains information about the service's configuration
// info.warnings contains any validation errors for the configuration
```

## database.updateServiceConfiguration

`async database.updateServiceConfiguration(mount, configuration, [minimal]):
Object`

Updates the configuration of the given service my merging the new values into
the existing ones.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **configuration**: `Object`

  An object mapping configuration option names to values.

* **minimal**: `boolean` (Default: `false`)

  Only return the current values and warnings (if any).

  **Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
  triggering a second request to the database.

**Examples**

```js
const config = {locale: 'en-US'};
const info = await db.updateServiceConfiguration('/my-service', config);
// info.values contains information about the service's configuration
// info.warnings contains any validation errors for the configuration
```

## database.getServiceDependencies

`async database.getServiceDependencies(mount, [minimal]): Object`

Retrieves an object with information about the service's dependencies and their
current mount points.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **minimal**: `boolean` (Default: `false`)

  Only return the current values and warnings (if any).

**Examples**

```js
const deps = await db.getServiceDependencies('/my-service');
// deps contains information about the service's dependencies
```

## database.replaceServiceDependencies

`async database.replaceServiceDependencies(mount, dependencies, [minimal]):
Object`

Replaces the dependencies for the given service.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **dependencies**: `Object`

  An object mapping dependency aliases to mount points.

* **minimal**: `boolean` (Default: `false`)

  Only return the current values and warnings (if any).

  **Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
  triggering a second request to the database.

**Examples**

```js
const deps = {mailer: '/mailer-api', auth: '/remote-auth'};
const info = await db.replaceServiceDependencies('/my-service', deps);
// info.values contains information about the service's dependencies
// info.warnings contains any validation errors for the dependencies
```

## database.updateServiceDependencies

`async database.updateServiceDependencies(mount, dependencies, [minimal]):
Object`

Updates the dependencies for the given service by merging the new values into
the existing ones.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **dependencies**: `Object`

  An object mapping dependency aliases to mount points.

* **minimal**: `boolean` (Default: `false`)

  Only return the current values and warnings (if any).

  **Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
  triggering a second request to the database.

**Examples**

```js
const deps = {mailer: '/mailer-api'};
const info = await db.updateServiceDependencies('/my-service', deps);
// info.values contains information about the service's dependencies
// info.warnings contains any validation errors for the dependencies
```

## database.enableServiceDevelopmentMode

`async database.enableServiceDevelopmentMode(mount): Object`

Enables development mode for the given service.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const info = await db.enableServiceDevelopmentMode('/my-service');
// the service is now in development mode
// info contains detailed information about the service
```

## database.disableServiceDevelopmentMode

`async database.disableServiceDevelopmentMode(mount): Object`

Disabled development mode for the given service and commits the service state to
the database.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const info = await db.disableServiceDevelopmentMode('/my-service');
// the service is now in production mode
// info contains detailed information about the service
```

## database.listServiceScripts

`async database.listServiceScripts(mount): Object`

Retrieves a list of the service's scripts.

Returns an object mapping each name to a more readable representation.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const scripts = await db.listServiceScripts('/my-service');
// scripts is an object listing the service scripts
```

## database.runServiceScript

`async database.runServiceScript(mount, name, [scriptArg]): any`

Runs a service script and returns the result.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

* **name**: `string`

  Name of the script to execute.

* **scriptArg**: `any`

  Value that will be passed as an argument to the script.

**Examples**

```js
const result = await db.runServiceScript('/my-service', 'setup');
// result contains the script's exports (if any)
```

## database.runServiceTests

`async database.runServiceTests(mount, [reporter]): any`

Runs the tests of a given service and returns a formatted report.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database

* **options**: `Object` (optional)

  An object with any of the following properties:

  * **reporter**: `string` (Default: `default`)

    The reporter to use to process the test results.

    As of ArangoDB 3.2 the following reporters are supported:

    * **stream**: an array of event objects
    * **suite**: nested suite objects with test results
    * **xunit**: JSONML representation of an XUnit report
    * **tap**: an array of TAP event strings
    * **default**: an array of test results

  * **idiomatic**: `boolean` (Default: `false`)

    Whether the results should be converted to the apropriate `string`
    representation:

    * **xunit** reports will be formatted as XML documents
    * **tap** reports will be formatted as TAP streams
    * **stream** reports will be formatted as JSON-LD streams

**Examples**

```js
const opts = {reporter: 'xunit', idiomatic: true};
const result = await db.runServiceTests('/my-service', opts);
// result contains the XUnit report as a string
```

## database.downloadService

`async database.downloadService(mount): Buffer | Blob`

Retrieves a zip bundle containing the service files.

Returns a `Buffer` in Node or `Blob` in the browser version.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const bundle = await db.downloadService('/my-service');
// bundle is a Buffer/Blob of the service bundle
```

## database.getServiceReadme

`async database.getServiceReadme(mount): string?`

Retrieves the text content of the service's `README` or `README.md` file.

Returns `undefined` if no such file could be found.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const readme = await db.getServiceReadme('/my-service');
// readme is a string containing the service README's
// text content, or undefined if no README exists
```

## database.getServiceDocumentation

`async database.getServiceDocumentation(mount): Object`

Retrieves a Swagger API description object for the service installed at the
given mount point.

**Arguments**

* **mount**: `string`

  The service's mount point, relative to the database.

**Examples**

```js
const spec = await db.getServiceDocumentation('/my-service');
// spec is a Swagger API description of the service
```

## database.commitLocalServiceState

`async database.commitLocalServiceState([replace]): void`

Writes all locally available services to the database and updates any service
bundles missing in the database.

**Arguments**

* **replace**: `boolean` (Default: `false`)

  Also commit outdated services.

  This can be used to solve some consistency problems when service bundles are
  missing in the database or were deleted manually.

**Examples**

```js
await db.commitLocalServiceState();
// all services available on the coordinator have been written to the db

// -- or --

await db.commitLocalServiceState(true);
// all service conflicts have been resolved in favor of this coordinator
```