Giter Club home page Giter Club logo

spawn-node-sdk's Introduction

Actor model framework for Node/Bun

Installation

yarn add @eigr/spawn-sdk

This package depends on @protobuf-ts/plugin to work with protobufs

Getting Started

We recommend you to use Typescript for better usage overall.

This lib supports both Bun and NodeJS runtimes, Bun performs invocations ~2x faster, we recommend using Bun.

Basic Usage

import spawn, { ActorContext, Value } from '@eigr/spawn-sdk'
import { UserState, ChangeUserNamePayload, ChangeUserNameStatus } from 'src/protos/examples/user_example'

const system = spawn.createSystem('SpawnSystemName')

// You can register multiple actors with different options
const actor = system.buildActor({
  name: 'exampleActor',
  stateType: UserState, // or 'json' if you don't want to use protobufs
  stateful: true,
  snapshotTimeout: 10_000n,
  deactivatedTimeout: 60_000n
})

// This can be defined in a separate file
const setNameHandler = async (context: ActorContext<UserState>, payload: ChangeUserNamePayload) => {
  return Value.of<UserState, ChangeUserNameResponse>()
    .state({ name: payload.newName })
    .response(ChangeUserNameResponse, { status: ChangeUserNameStatus.OK })
}

// This is similar to a Route definition in REST
// the default payloadType is 'json'
actor.addAction({ name: 'setName', payloadType: ChangeUserNamePayload }, setNameHandler)

system.register()
  .then(() => console.log('Spawn System registered'))

With this configured, you can invoke this actor anywhere you want with:

import spawn, { payloadFor } from '@eigr/spawn-sdk'
import { UserState, ChangeUserNamePayload, ChangeUserNameResponse } from 'src/protos/examples/user_example'

(async () => {
  const payload = { newName: 'changedName' } as ChangeUserNamePayload
  const response: ChangeUserNameResponse = await spawn.invoke('exampleActor', {
    action: 'setName',
    response: ChangeUserNameResponse,
    payload: payloadFor(ChangeUserNamePayload, payload)
    // system: 'SpawnSystemName'
  })

  const state: UserState = await spawn.invoke('exampleActor', {
    action: 'getState',
    response: UserState,
    // system: 'SpawnSystemName'
  })

  console.log(state) // { name: 'changedName' }
})()

Using protobufs

NOTE: Its recommended to use Protobufs to ensure your contracts will always be what you expect and also for performance improvements

Define a protobuf file (lets save this at protos/examples/user_example.proto), if you want to skip this part, you can use 'json' type actors.

syntax = "proto3";

message UserState {
  string name = 1;
}

message ChangeUserNamePayload {
  string new_name = 1;
}

enum ChangeUserNameStatus {
  NAME_ALREADY_TAKEN = 0;
  OK = 1;
}

message ChangeUserNameResponse {
  ChangeUserNameStatus status = 1;
}

Compile proto with protoc using ts-protoc-gen:

protoc --ts_out ./src/protos/ --proto_path protos protos/**/*.proto

With this, it should generate a file at src/protos/examples/user_example.ts, we will use this generated module for Actor definitions and invocations.

Running the Proxy

You'll need to make sure Spawn Proxy service is up and running. With docker-compose you can define:

NOTE: using docker is recommended for dev purposes only, see spawn deploy for production examples.

version: "3.8"

services:
  spawn-proxy:
    image: eigr/spawn-proxy:1.1.0
    restart: always
    environment:
      PROXY_ACTOR_SYSTEM_NAME: "spawn-system" # change this to the system you've registered
      PROXY_APP_NAME: spawn-typescript
      PROXY_HTTP_PORT: 9001
      PROXY_DATABASE_TYPE: postgres
      PROXY_DATABASE_NAME: eigr-functions-db
      PROXY_DATABASE_USERNAME: postgres
      PROXY_DATABASE_SECRET: password
      PROXY_DATABASE_HOST: localhost
      PROXY_DATABASE_PORT: 5432
      SPAWN_STATESTORE_KEY: 3Jnb0hZiHIzHTOih7t2cTEPEpY98Tu1wvQkPfq/XwqE=
      USER_FUNCTION_HOST: 0.0.0.0 # Your NodeJS runtime host
      USER_FUNCTION_PORT: 8090 # Your NodeJS runtime exposed port
    network_mode: host
    ports:
      - "9001:9001"

NOTE: Windows w/ WSL2 - If you want to use docker for spawn-proxy and local host for your NodeJS check this article https://www.beyondjava.net/docker-wsl-network

Set the following ENV variables for your NodeJS runtime (following .env.example)

PROXY_HTTP_PORT=9001
PROXY_HTTP_HOST=localhost
USER_FUNCTION_PORT=8090

Documentation

Examples

You can check test folder to see some examples

Environment variables: (you don't need to worry if you are using spawn proxy)

  • PROXY_HTTP_PORT This is the port of spawn proxy service
  • PROXY_HTTP_HOST This is the host of spawn proxy service
  • USER_FUNCTION_PORT This is the port that your service will expose to communicate with Spawn

spawn-node-sdk's People

Contributors

eliasdarruda avatar sleipnir avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

Forkers

sleipnir

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.