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

$3

``sh
stdlibjs up [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 |

$3


`sh
stdlibjs down [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

$3


`sh
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).

$3


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:
`js
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:
`js
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.




$3

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.

`js
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 🐐?

`js
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?

`js
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
}
})
`

$3

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

`js
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.
})
``