Getting started¶

Installation¶

Isotopes can be installed with npm:

npm install isotopes aws-sdk

TypeScript typings are provided as part of the package, so no need to install a separate package. The aws-sdk is listed as a peer dependency, so make sure it is installed. Note that when you run Isotopes from within AWS Lambda the SDK is already installed.

Usage¶

Isotopes = SimpleDB + TypeScript

The following instructions are intended for usage with TypeScript. You can also use Isotopes from plain JavaScript by omitting all typings from the examples, but what would be the point? Learn TypeScript, it's awesome!

First, import Isotopes into your project:

import { Isotope } from "isotopes"

Next, define a TypeScript interface for the data you want to store, e.g. a type for running a task on a cluster:

export interface Task {
  id: string                           /* Unique identifier */
  active: boolean                      /* Whether the task can be scheduled */
  props: {
    image: string                      /* Docker image to use */
    cpus: number                       /* Number of CPUs */
    memory: number                     /* Reserved memory */
    command?: string                   /* Command override */
  },
  tags: string[]                       /* Tags for categorization */
}

Every type that is handled by Isotopes must contain a unique identifier which is used as an item name. The item name must be on the first level of the type to be stored, all other variables can be arbitrarily nested. Next, create an isotope for the type, e.g. for a SimpleDB domain named tasks:

const tasks = new Isotope<Task>({
  domain: "tasks",                     /* SimpleDB domain name */
  key: "id"                            /* SimpleDB item name (primary key) */
})

Now, suppose we have the following item:

const task: Task = {
  id: "example",
  active: true,
  props: {
    image: "busybox",
    cpus: 2,
    memory: 2048
  },
  tags: [
    "TAG_1",
    "TAG_2"
  ]
}

We can persist, retrieve and delete items from the isotope by using a simple API, cleverly omitting all the boilerplate that is normally necessary for interfacing with SimpleDB.

Create a domain¶

Reference for Isotope.create

If the SimpleDB domain doesn't exist, create it:

await isotope.create()

Persist an item¶

Reference for Isotope.put

Persisting an item is as simple as:

await tasks.put(task) // => void

Retrieve an item¶

Reference for Isotope.get

Retrieving an item by primary key (unique identifier, in our example id):

const task = await tasks.get("example") // => Task | undefined

Delete an item¶

Reference for Isotope.delete

Delete an item by primary key:

await tasks.delete("example") // => void

Query a domain¶

Reference for Isotope.select

We can also build queries using a stripped-down version of the squel query builder interface:

const expr = tasks.getQueryBuilder()
  .where("`active` = ? and `props.memory` > ?", true, 0)
  .order("`props.memory`", "asc")
  .limit(100)

The query expression can then be used to perform a SELECT operation:

await tasks.select(expr)

Handling errors¶

All methods except getQueryBuilder return Promises, so they are best to be used with ES7's async/await and wrapped in try/catch blocks for error handling purposes:

try {
  await tasks.put(task)
} catch (err) {
  /* Handle error */
}