StdLib.js – Node.js SDK (and CLI, because why not?)

Node.js SDK to access the StdLib registry and upload your functions (services).

Getting started

You'll definitely need to take a look at StdLib quickstart guide first.

CLI

Up

stdlibjs up <env> [services..]

Where:

• env is the service environment. When its value is master, a new versioned release is published (aka: same as lib release)
• services is the list of services you want to upload. It's optional: the default behaviour is to upload everything found in /${yourStdlibUsername} folder

Fancy examples, using a serverless workspace that looks like:

`-- awesome-workspace
    |-- awesomer-stdlib-username
        |-- awesome-project-avocado 🥑
        |-- awesome-project-strawberries 🍓
        |-- awesome-project-salad 🥗
        `-- awesome-project-goat 🐐

You can create all these projects by cd'ing to awesome-workspace and running the commands lib create awesome-project-{🥑|🍓|🥗|🐐}. Please refer to StdLib docs for this.

| Command | Result | | --- | --- | | stdlibjs up master | 🥑, 🍓, 🥗, and 🐐 will be uploaded as release (using their respective package.json version) | | stdlibjs up master awesome-project-avocado awesome-project-goat | 🥑 and 🐐 will be uploaded as release, but 🍓 and 🥗 won't be affected | | stdlibjs up develop | 🥑, 🍓, 🥗, and 🐐 will be uploaded to the "dev" environment | | stdlibjs up develop awesome-project-strawberries | Only 🍓 will be uploaded to the "dev" environment | | stdlibjs up ${TRAVIS_BRANCH} awesome-project-goat | You're using Travis, and 🐐 is uploaded to an environment named like the branch Travis is currently building (that may be "master", for instance... hello Continuous Delivery!) | | stdlibjs up ${CI_ENVIRONMENT_SLUG} awesome-project-goat | Same as above, but 🐐 is uploaded to StdLib by Gitlab CI |

Down

stdlibjs down <env> [services..]

Where:

• env is the service environment. When its value is master, a released version is removed (aka: same as lib rollback)
• services is the list of services you want to upload. It's optional: the default behaviour is to tear down everything found in /${yourStdlibUsername} folder

Install

stdlibjs install

It runs an npm install in each service package found in $yourStdLibUsername folder.

SDK

Are you an SDK fan? Hopefully an async/await/Promises fan? Here's your section then. At the end of the day, the CLI commands are just wrappers (made with the awesome yargs!) around a bunch of happy functions. They are also exposed as regular Javascript function by the main script (that's index.js).

List

The SDK comes with a list function exposes to the world, so it can be combined with the up or down commands. It has one optional input argument, that's an array of whitelisted services: if you specify it, the list of services retrieved from your workspace will be filtered against this; if you don't all the services are retrieved.

For instance:

const { list } = require('stdlib.js')
const whitelistedServices = ['awesome-project-avocado', 'awesome-project-goat']

list(whitelistedServices)
  .then(services => {
    services.forEach(({ serviceName, servicePath, packageJson }) => {
      console.log(serviceName)
    })
  })

Or if you're an async/await fan:

const { list } = require('stdlib.js')
const whitelistedServices = ['awesome-project-avocado', 'awesome-project-goat']

let services
try {
  services = await list(whitelistedServices)
} catch (e) {
  console.error(e)
  process.exit(1)
}
services.forEach(({ serviceName, servicePath, packageJson }) => {
  console.log(serviceName)
})

Isn't it useful to log the name of the services we've just retrieved? More useful usages coming in the up and down section, I swear.

Up

The up function takes as its input one single object with two keys, serviceName and env. I suppose you can guess by know what they stand for. It returns a Promise, so you can play with its response in any way you like.

const { up } = require('stdlib.js')
up({
  serviceName: 'awesome-project-avocado',
  env: 'gitflow-branch'
})
  .then(response => {
    // Your 🥑 has just been uploaded to the "gitflow-branch" environment.
  })
  .catch(response => {
    // Something went wrong. Your 🥑 has not been uploaded anywhere
  })

Why not combine it with the list so you can upload both 🥑 and 🐐?

const { up } = require('stdlib.js')
const whitelistedServices = ['awesome-project-avocado', 'awesome-project-goat']

list(whitelistedServices)
  .then(services => {
    services.forEach(({ serviceName, servicePath, packageJson }) => {
      up({
        serviceName,
        env: 'gitflow-branch'
      })
        .then(response => {
          // Your 🥑 or 🐐 has just been uploaded to the "gitflow-branch" environment.
        })
        .catch(response => {
          // Something went wrong. Your 🥑 or 🐐 has not been uploaded anywhere
        })
    })
  })

Let's try with some async/await magic, shall we?

const { up } = require('stdlib.js')
const { TRAVIS_BRANCH: env } = process.env // See what I'm doing here? #hellocontinuousdelivery
const whitelistedServices = ['awesome-project-avocado', 'awesome-project-goat']

const services = await list(whitelistedServices)
services.forEach(({ serviceName, servicePath, packageJson }) => {
  try {
    await up({
      serviceName,
      env
    })
    // Your 🥑 or 🐐 has just been uploaded to the "gitflow-branch" environment.
  } catch {
    // Something went wrong. Your 🥑 or 🐐 has not been uploaded anywhere
  }
})

Down

down works the very same way as up does, taking one input object with the same serviceName and env keys.

const { down } = require('stdlib.js')
down({
  serviceName: 'awesome-project-goat',
  env: 'gitflow-branch'
})
  .then(response => {
    // Your 🐐 has just been removed from the "gitflow-branch" environment.
  })
  .catch(response => {
    // Something went wrong. Your 🐐 is still enjoying the "gitflow-branch" environment.
  })