actioman v0.7.0
🏹 actioman
Share functions with other JS clients. Call backend functions with type-safety.
Actioman is a tool to expose Javascript functions as web services in a simple and fast way. With actioman, you can build robust and type-safe APIs using your existing Javascript functions, facilitating communication between your backend and Javascript clients (whether they are browsers, mobile applications, or even other backend services).
Features
- Simple service deployment: With actioman, setting up a service is as easy as running a command, without complex configurations or laborious deployments.
- Flexible deployment: It can be deployed over HTTP, HTTPS, and HTTP2 (with or without SSL), adapting to your security and performance needs.
- Clear contracts with Zod: Define clear contracts between client and server using Zod to describe the shape and type of input and output data of your services. This ensures type-safety and facilitates data validation.
- Fast service exposure: Convert your Javascript functions into endpoints accessible over the network instantly. Ideal for rapid prototyping or for exposing backend functionalities in an agile manner.
- Easy installation of exposed services: Clients can install and use exposed services with a single command line, simplifying the integration and consumption of your APIs.
- Easy to protect: Implement security mechanisms to protect your services from unauthorized access, ensuring the integrity and confidentiality of your data.
Setup
To start using actioman, follow these simple steps:
Create an
actions.js
file:Create a file named
actions.js
in your project. In this file, define the Javascript functions you want to expose as services.// ./actions.js export const hello = () => "hello world";
Start the actioman server:
Open your terminal in the root of your project and run the following command to start the actioman server, serving the functions defined in
actions.js
:npx actioman actions.js
When you run this command, you will see a message similar to this in the console:
Route GET /__actions Route POST /__actions/hello Listening on http://localhost:30320/
This message indicates:
Route GET /__actions
: A GET route has been created at/__actions
. This route exposes the contracts of all services defined inactions.js
in JSON format. You can use it to inspect the structure of your services.Route POST /__actions/hello
: A POST route has been created at/__actions/hello
. This route corresponds to thehello
function you defined inactions.js
. To invoke this service, you will need to make a POST request to this URL.Listening on http://localhost:30320/
: The actioman server is running and listening for requests at the URLhttp://localhost:30320/
. The port30320
may vary.
Adding Actioman services to your project
Once your actioman service is running, you can consume it from another Javascript project. Follow these steps to import and use your services:
Install the
actioman
dependency:In your client project, install the
actioman
library using npm:npm add actioman
Add the Actioman service:
Use the
actioman add
command to register an Actioman service in your client project. Replacemyservice
with the name you want to give to your service locally, andhttp://localhost:30320/
with the URL where your actioman server is running (the one shown in the console when you started the server).npx actioman add myservice http://localhost:30320/
This command configures
actioman
so that it can access the services exposed at the provided URL under the namemyservice
.Use the services in your code:
Now you can import and use your actioman services in your Javascript code. The following example shows how to call the
hello
function of themyservice
service:// my-app.js import { actions } from "actioman"; const myservice = actions.myservice(); const message = await myservice.hello(); console.log(message); // => "hello world"
In this code:
import { actions } from "actioman"
: Imports theactions
object from theactioman
library.const myservice = actions.myservice()
: Creates an instance of themyservice
service that you configured previously.actions.myservice()
generates a type-safe client to interact with your remote service.await myservice.hello()
: Calls thehello
function of themyservice
service. This call translates into an HTTP request to the actioman server. Since service calls are asynchronous, we useawait
to wait for the response.