@saouas/cascade-js

CasC JS SDK

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

Table of Contents

• Install
• Usage
• Casc CLI options

Install

NPM

npm install @saouas/cascade-js --save 

Yarn

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:

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:

{
  "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:

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:

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

Or using require:

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

For example:

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:

database:
  host: "localhost"
  port: 5432
  username: "postgres"
  password: "XPJc5qAbQcn77GWg"

Check your configuration is valid

In your CI or CD pipeline, run:

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.