electrocli

Electro is a CLI utility toolbox for extending the functionality of the node library ElectroDB to the terminal.

Usage no npm install needed!

<script type="module">
  import electrocli from 'https://cdn.skypack.dev/electrocli';
</script>

README

ElectroCLI

ElectroDB Electro is a CLI utility toolbox for extending the functionality of the node library ElectroDB to the terminal.

This app is a work in progress, please submit issues/feedback or reach out on twitter @tinkertamper.

Features

  • Import your models into the cli to run queries and operations directly from your terminal
  • Stand up a web service that dynamically creates endpoints based on your models.

Install

Install globally

npm install electrocli -g

Usage

Usage:  [options] [command]

Electro is a CLI utility toolbox for extending the functionality of the node library ElectroDB to the terminal.

Options:
  -V, --version                 output the version number
  -h, --help                    display help for command

Commands:
  typedef [options] <filepath>  [Deprecated]: Specify a file that exports an ElectroDB Service or Entity and Electro CLI will automatically generate a typescript type definition file.
  add [options] <filepath>      Specify a file that exports an ElectroDB Service, Entity, or JSON Model. Electro will add that Instance to the CLI allowing it to be queried.
  remove|rm <service>           Remove existing ElectroDB Instance from the Electro CLI.
  list|ls                       List all ElectroDB Instances that have been imported into the Electro CLI.
  serve|rest <port> <port>      Stand up a local http endpoint based on your imported Instances.
  scan                          Execute scans against your imported Instances.
  query                         Execute queries against your imported Instances.
  help [command]                display help for command

Commands

typedef

Usage:  typedef [options] <filepath>

[Deprecated]: Specify a file that exports an ElectroDB Service or Entity and Electro CLI will automatically generate a typescript type definition file.

Options:
  -o, --output <filepath>  Specify an output filepath for the generated type definition file.
  -h, --help               display help for command

add

Usage:  add [options] <filepath>

Specify a file that exports an ElectroDB Service, Entity, or JSON Model. Electro will add that Instance to the CLI allowing it to be queried.

Options:
  -l, --label <label>    Specify a custom label for this service to appear in the CLI. (default: Service/Entity name)
  -t, --table <table>    Specify a default table to use with this instance - Required for Models.
  -p, --params <params>  Specify JSON for custom DocumentClient configuration. If filepath exports a Service or Entity this configuration will overwrite any client specified on that instance.
  -o, --overwrite        Overwrite existing tag if already exists
  -h, --help             display help for command

remove

Usage:  remove|rm [options] <service>

Remove existing ElectroDB Instance from the Electro CLI.

Options:
  -h, --help  display help for command

list

Usage:  list|ls [options]

List all ElectroDB Instances that have been imported into the Electro CLI.

Options:
  -h, --help  display help for command

serve

Usage:  serve|rest <port> [options] <port>

Stand up a local http endpoint based on your imported Instances.

Options:
  -h, --help  display help for command

scan

Usage:  scan [options] [command]

Execute scans against your imported Instances.

Options:
  -h, --help      display help for command

Commands:
  taskapp
  help [command]  display help for command

query

Usage:  query [options] [command]

Execute queries against your imported Instances.

Options:
  -h, --help      display help for command

Commands:
  taskapp
  help [command]  display help for command

Examples

TaskApp

TaskApp is a simple three Entity service that tracks Organizations, Employees, and Tasks.

Setup

The following examples use models and code within the ElectroDB repository for examples: electrodb. Follow the steps below to get setup or follow along.

Install ElectroCLI Globally

Install electrocli via npm globally. Note: This may require sudo or administrator privileges.

gt; npm install electrocli --global

Clone/Download Examples

Clone the electrodb repository and then navigate to the the TaskApp example.

gt; git clone https://github.com/tywalch/electrodb.git
gt; cd electrodb/examples/taskapp

Configure your DynamoDB Target

It is recommended that you use the dynamodb-local docker image.

gt; docker pull amazon/dynamodb-local
gt; docker run -p 8000:8000 amazon/dynamodb-local

More information on how to setup and configure that here.

If you want to use your own DynamoDB instance in AWS (be careful with incurring fees) you can modify the client.js file located in the electrodb directory from above: electrodb/examples/taskapp/lib/client.js.

Load the database

Records can be loaded into the example table by executing the file electrodb/examples/taskapp/bin/load.js. You will be prompted to confirm loading by typing y.

gt; node electrodb/examples/taskapp/bin/load.js
   Your configuration is pointed to a local instance of dynamodb. This operation will create a table named 'electro' and then load 500 Employees and 600 Tasks records. Are you sure you want to proceed? y/N
gt; y

Add the "Taskr" Service to electro cli

Use the add command to add the taskr.js within the electrodb/examples/src directory.

gt; electro add electrodb/examples/src/taskr.js

Query TaskApp

Run queries against your models directly from the command line.

gt; electro query taskapp

Options:
  -r, --raw                  Return raw field response.
  -p, --params               Return DocumentClient params as results instead of querying the table.
  -t, --table <table>        Override table defined on Instance.
  -l, --limit <number>       Limit the number of results returned.
  -f, --filter <expression>  Supply a filter expression "<attribute>, <operation>, [value1] [value2]". Use double commas to escape a comma. Available attributes include employee, firstName, lastName, office, title, team, salary, manager, dateHired, birthday. (default: [])
  -d, --delete               Delete items returned from query.
  -h, --help                 display help for command
Access Pattern Command
employee [options] <employee>
coworkers [options] <office> [team] [title] [employee]
teams [options] <team> [dateHired] [title]
employeelookup [options] <employee>
roles [options] <title> [salary]
directreports [options] <manager> [team] [office]
task [options] <task> [project] [employee]
project [options] <project> [employee] [status]
assigned [options] <employee> [project] [status]
statuses [options] <status> [project] [employee]
locations [options] <country> <state> [city] [zip] [office]
office [options] <office>
workplaces [options] <office> [team] [title] [employee]
assignments [options] <employee>

Serve CRUD HTTP Server for TaskApp

Stand up an HTTP Server based all of your models.

gt; electro serve 8080

Options:
  -v, --view-only  Serve with only get/query operations as endpoints. (default: false)
  -h, --help       display help for command

Use the --view-only flag to stand up an http server without exposing any put/create/update/patch/delete operations.

Method Endpoint
GET http://localhost:8080/taskapp/employee/:employee
GET http://localhost:8080/taskapp/coworkers/:office
GET http://localhost:8080/taskapp/coworkers/:office/:team
GET http://localhost:8080/taskapp/coworkers/:office/:team/:title
GET http://localhost:8080/taskapp/coworkers/:office/:team/:title/:employee
GET http://localhost:8080/taskapp/teams/:team
GET http://localhost:8080/taskapp/teams/:team/:dateHired
GET http://localhost:8080/taskapp/teams/:team/:dateHired/:title
GET http://localhost:8080/taskapp/employeelookup/:employee
GET http://localhost:8080/taskapp/roles/:title
GET http://localhost:8080/taskapp/roles/:title/:salary
GET http://localhost:8080/taskapp/directreports/:manager
GET http://localhost:8080/taskapp/directreports/:manager/:team
GET http://localhost:8080/taskapp/directreports/:manager/:team/:office
GET http://localhost:8080/taskapp/task/:task
GET http://localhost:8080/taskapp/task/:task/:project
GET http://localhost:8080/taskapp/task/:task/:project/:employee
GET http://localhost:8080/taskapp/project/:project
GET http://localhost:8080/taskapp/project/:project/:employee
GET http://localhost:8080/taskapp/project/:project/:employee/:status
GET http://localhost:8080/taskapp/assigned/:employee
GET http://localhost:8080/taskapp/assigned/:employee/:project
GET http://localhost:8080/taskapp/assigned/:employee/:project/:status
GET http://localhost:8080/taskapp/statuses/:status
GET http://localhost:8080/taskapp/statuses/:status/:project
GET http://localhost:8080/taskapp/statuses/:status/:project/:employee
GET http://localhost:8080/taskapp/locations/:country/:state
GET http://localhost:8080/taskapp/locations/:country/:state/:city
GET http://localhost:8080/taskapp/locations/:country/:state/:city/:zip
GET http://localhost:8080/taskapp/locations/:country/:state/:city/:zip/:office
GET http://localhost:8080/taskapp/office/:office
GET http://localhost:8080/taskapp/workplaces/:office
GET http://localhost:8080/taskapp/workplaces/:office/:team
GET http://localhost:8080/taskapp/workplaces/:office/:team/:title
GET http://localhost:8080/taskapp/workplaces/:office/:team/:title/:employee
GET http://localhost:8080/taskapp/assignments/:employee
POST http://localhost:8080/taskapp/employee
POST http://localhost:8080/taskapp/task
POST http://localhost:8080/taskapp/locations
PUT http://localhost:8080/taskapp/employee/:employee
PUT http://localhost:8080/taskapp/task/:task/:project/:employee
PUT http://localhost:8080/taskapp/locations/:country/:state/:city/:zip/:office
DELETE http://localhost:8080/taskapp/employee/:employee
DELETE http://localhost:8080/taskapp/task/:task/:project/:employee
DELETE http://localhost:8080/taskapp/locations/:country/:state/:city/:zip/:office