npm package: @herodevs/scully-plugin-the-vault
Description: This is the home of The Vault plugin for Scully. It provides local caching for Scully, and (in the enterprise offering) shared caching.
Latest version: 0.0.4

# The Vault

This is the home of The Vault plugin for Scully.
It provides local caching for Scully, and (in the enterprise offering) shared caching.

The cache works with a approximately 5 minute granularity. This means that when a resource is in the cache it will live for the time it has assigned to it, but with a 5 minute margin.
When you have resources where this 5 minutes cache time is to long, set the resource to a TTL of `0` making it un-cachable.

To use this plugin you must first install it using npm:

```bash
 npm i @herodevs/scully-plugin-the-vault
 ```

 After that add it to your config file:

 ```typescript
import { theVaultReady } from '@herodevs/scully-plugin-the-vault';
import { ScullyConfig } from '@scullyio/scully';

/** note that the config must be a promise */
export const config: Promise<ScullyConfig> = (async () => {

// setPluginConfig(theVault, { customerId: 2, projectId: 2 });

/** Mandatory! *//
await theVaultReady({
    includeReferer: false,
    customerId: 2,
    projectId: 3,
  });

  const conf: ScullyConfig = {
    projectRoot: './apps/demo/src',
    projectName: 'demo',
    outDir: './dist/static',
    handle404: 'index',
    maxRenderThreads: 24,
    routes: {
      '/user/:id': {
        type: 'json',
        id: {
          url: 'http://localhost:8200/users',
          resultsHandler: (raw) => raw.slice(0, 20),
          property: 'id',
        },
      },
    },
  };
  return conf;
})();
 ```

## config must be a promise.

Because the Vault needs to talk to the cache, and this is an asynchronous process, this plugin demands the Scully config the return a promise. You can use an async function as showen in the above config, or use a normal promise chain when that is your preference.

## Runtime Parameters

### nocache

If you want to do a local run of your app, without the Vault being used, you can add the command line option `--noCache` to your scully command.

```bash
npx scully --project MyProject --noCache
```

When you want to run a separate scully server, it _must_ exclude the cache. start it like this:

```bash
npx scully --project MyProject serve --noCache
```

This is needed, because the _local_ cache can only be used by once Scully instance.

### clearCache

the `--clearCache` option removes the local cache.


## The Vault Config

The Vault has a config object that can be set using `setPluginConfig(theVault, customConfig);` or using the `await theVaultReady(customConfig);` option.
Settings provided to the `theVaultReady()` function will overwrite the `setPluginConfig`

```typescript
export interface TheVaultConfig {
  /** the url of the Vault server */
  server?: string;
  /** use the Referer as a key differentiation, defaults to false */
  includeReferer?: boolean;
  /** your Scully Enterprise customerID, as provided by HeroDevs */
  customerId?: number;
  /** your project id number */
  projectId?: number;
  /** your environment */
  environment?: 'dev' | 'prod' | 'staging' | 'test';
  /** the default Time To Live. 12 hours if unset */
  defaultTTL?: number;
  /** TTL exceptions */
  ttlExceptions?: {
    /** the full URL, is used as: `testUrl.startsWith(urlStart)`  */
    [urlStart: string]: number;
  };
}
```