npm package: @saouas/cascade-js
Description: The CasC SDK made for interacting with your AWS secrets from JavaScript or TypeScript applications.
Latest version: 0.0.4

# CasC JS SDK

The CasC SDK made for interacting with your AWS secrets from JavaScript or TypeScript applications.

## Table of Contents

- [Install](#install)
- [Usage](#usage)
- [Casc CLI options](#casc-cli-commands)

## Install

NPM
```shell
npm install @saouas/cascade-js --save 
```

Yarn
```shell
yarn add @saouas/cascade-js
```

## Usage

### Define your configuration contract

Create a `casc.config.yml` file in the root of your project, and define the structure and types of your application configuration.

For example:
```yaml
database:
  host:
    type: string
  port:
    type: integer
  username:
    type: string
  password:
    type: string
    secret: true
    regex: ^[a-zA-Z0-9]+$
```

- You can nest properties to any depth level
- Supported types are `boolean`, `string`, `integer` and `float`
- Properties can be flagged with `optional: true`, or `secret: true`
- For type `string`, you can add a regex expression that the value will have to match

### Build your configuration to access it in your code

You can add a build configuration command to your package.json:

```json
{
  "scripts": {
    "build:config": "cascade-js build"
  }
}
```

And then run `npm run build:config` or `yarn build:config`

### Init your configuration at the start of your application

For example, in `main.ts`:

```typescript
import { Casc } from '@casc-sdk';

async function bootstrap() {
  await Casc.init({ secretId: process.env.AWS_SECRET_ID });
  const app = await NestFactory.create(ApplicationModule);
  await app.listen(9999);
}

bootstrap();
```

### Use your configuration anywhere in your code

Your configuration is then accessible with the import:

```typescript
import { Casc } from '@casc-sdk';
```

Or using require:

```javascript
const { Casc } = require('@casc-sdk');
```

For example:

```typescript
import { Casc } from '@casc-sdk';
import { Client } from "postgres";

export class DatabaseClient {
  private client: Client;

  constructor() {
    this.client = new Client({
      host: Casc.config.database.host,
      port: Casc.config.database.port,
      username: Casc.config.database.username,
      password: Casc.config.database.password,
    })
  }
}
```

### Create your local configuration file

Create a `casc.local.yml` file in the root of your project, defining the values matching your configuration contract.

For example:
```yaml
database:
  host: "localhost"
  port: 5432
  username: "postgres"
  password: "XPJc5qAbQcn77GWg"
```

### Check your configuration is valid

In your CI or CD pipeline, run:

```shell
cascade-js validate --api-key $YOUR_ENVIRONMENT_API_KEY
```

Which will check if the values filled in the Casc platform comply with your contract.

## Casc CLI commands

### cascade-js build

Build your typescript types from your contract file.

#### `-c, --contract-file`

The path to your configuration contract file. Default is `casc.config.yml`.

#### `-r, --force-recreate`

By default, if contract stays identical, configuration won't be rebuilt to save time. Passing this option will force the rebuild of your configuration.


### cascade-js validate


Check that with your configuration values, either read from a local file or fetched from the Casc platform, match your contract.

#### `-c, --contract-file`

The path to your configuration contract file. Default is `casc.config.yml`.

#### `-f, --values-file`

The path to your local values file. Default is `casc.local.yml`.

#### `-s, --secret-id`

The AWS secret id that will be used to fetch values. If specified, parameter `-f, --values-file` is ignored.