Akita | A WebSocket CLI
A node.js command line interface for interacting with a WebSocket server. Useful for sending specific or predefined messages over a WebSocket.
Table of contents
An example
# Connect to a WebSocket server (Exit with Ctrl+C) akita ws://localhost:3000 # Send up a specific json payload > {"type": "message", "body": "Hello, world!"} # Send a predefined message (defined in an .akitarc file) > @myCustomMessage
Installing
These are the different ways you can install, in no particular order.
# Install with npm npm i -g akita-ws # Install as a development dependancy npm i --save-dev akita-ws
Usage
Below are the different things you can do.
# Connect to a web socket server # -> Any line you enter after this is emitted to the server # -> Stop with a Ctrl+C akita ws://localhost:3000 # Run an echo server # -> Start an echo server, which will echo back any message you emit # -> You should probably run this in a new terminal tab # -> Run on a specific port with: "--port 1337" # -> Stop with a Ctrl+C akita echo # See usage info akita --helpakita echo --help
Predefined messages
You can use an .akitarc
file to specify predefined message you want to send.
akita uses cosmiconfig
to load config files, so you can use:
.akitarc
, akitarc.json
, akitarc.yml
or akitarc.js
if you want.
Say you have an .akitarc.yml
file:
# Use this block to define you messagesmessages: # You can use a string value helloWorld: A really long string payload # Or you can use an object which will be serialised with JSON.stringify() customData: name: Geoff age: 42
Then you can use do:
# Connect to akita akita ws://localhost:3000 # Send a predefined string payload > @helloWorld # Send a predefined JSON payload (uses JSON.stringify()) > @customData
Predefined URLs
You can also specify the WebSocket server's url in your .akitarc
file.
url: ws://localhost:3000
Then you can run akita without a url argument.
akita
Headers
You can send headers to the socket request with --header key:value
or with the headers
section of the yaml.
akita ws://localhost:3000 --header authorization:top_secret
or in .akitarc.yml
headers: authorization: top_secret
Using the API
You can use akita programatically by importing it in TypeScript or JavaScript. You might want to install it as a production dependancy in this case.
Here's an example script.js
:
const Akita EchoServer = const cmd ...args = processargv if cmd === 'run' const url = args // Run akita with a url Akitaif cmd === 'echo' const port = args EchoServer
I'm not sure what this is useful for, but it's possible. For detailed usage see the source code.
Development
Below is information about development on the project.
Setup
To develop on this repo you will need to have node.js installed on your dev machine and have an understanding of it. This guide assumes you have the repo checked out and are on macOS.
You'll only need to follow this setup once for your dev machine.
# Install dependancies npm install # (optional) Add an config file (.akitarc, .akitarc.yml, .akitarc.json or .akitarc.js) touch .akitarc
Regular use
These are the commands you'll regularly run to develop the CLI, in no particular order.
# Run the CLI directly with ts-node # -> Runs TypeScript on the fly without transpiles to JavaScript # -> Use "-s" to stop npm debug output # -> Use "--" to stop npm stealing CLI arguments # (they get passed to npm instead of our CLI) npm run dev -s --
Irregular use
These are commands you might need to run but probably won't, also in no particular order.
# Generate the table of contents for this readme # -> It'll replace content between the toc-head and toc-tail HTML comments # -> This runs as part of the "preversion" script npm run gen-readme-toc # Manually lint code with TypeScript's `tsc` npm run lint # Manually format code # -> This repo is setup to automatically format code on git-push npm run prettier # Manually transpile TypeScript to JavaScript # -> This is part of the packaging which is triggered when deploying # -> Writes files to dist, which is git-ignored npm run build # Manually start code from transpilled JavaScript npm run start
Code Structure
Folder | Contents |
---|---|
dist | Where the transpiled javascript and type definitions go |
node_modules | Where npm's modules get installed into |
src | Where the code for the CLI is |
Code formatting
This repo uses Prettier to automatically format code to a consistent standard. It works using the husky and lint-staged packages to automatically format code whenever code is commited. This means that code that is pushed to the repo is always formatted to a consistent standard.
You can manually run the formatter with npm run prettier
if you want.
Prettier is slightly configured in .prettierrc.yml and also ignores files using .prettierignore.
Publishing
Use npm's version
and publish
command to push a new version to npmjs.com.
There is a preversion
that does a few things:
- Runs unit tests
- Generates the table of contents in this readme
- Transpiles typescript assets into javascript & type definitions
- Adds those changes to git
Future work
Some ideas I've had for where I want this project to go.
- Parameterised / templated predefined messages
- Different / custom serialisation methods (other that
JSON.stringify
) - Add unit test coverage
- Single usage like
akita ws://localhost @customData @hello ...
- Read the
akitarc
on the fly incase it changes after starting - Document piped usage,
cat data.json | akita
This project was setup with robb-j/ts-node-base