nodejs

README

nodejs tools for Go

This contains a few nice tools for using nodejs in go

Usage

First you need a nodejs factory:

factory, err := nodejs.New()
if err != nil {
    // handle error: nodejs could not be found or didn't run
}

You can then start processes directly with factory.New() or use factory.NewPool(0, 0) to get a pool of pre-initialized nodejs instances.

Documentation

Index

• Variables
• type Factory
  • func New() (*Factory, error)
  • func (factory *Factory) New() (*Process, error)
  • func (f *Factory) NewPool(queueSize, maxProcs int) *Pool
  • func (factory *Factory) NewWithTimeout(timeout time.Duration) (*Process, error)
• type IpcFunc
• type Pool
  • func (pool *Pool) Take(ctx context.Context) (*Process, error)
  • func (pool *Pool) TakeIfAvailable() *Process
  • func (pool *Pool) TakeTimeout(t time.Duration) (*Process, error)
• type Process
  • func (p *Process) Alive() <-chan struct{}
  • func (p *Process) Checkpoint(timeout time.Duration) error
  • func (p *Process) Close() error
  • func (p *Process) Console() []byte
  • func (p *Process) Eval(ctx context.Context, code string, opts map[string]any) (any, error)
  • func (p *Process) EvalChannel(code string, opts map[string]any) (chan map[string]any, error)
  • func (p *Process) GetVersion(what string) string
  • func (p *Process) Kill()
  • func (p *Process) Log(msg string, args ...any)
  • func (p *Process) MakeResponse() (string, chan map[string]any)
  • func (p *Process) Run(code string, opts map[string]any)
  • func (p *Process) Set(v string, val any)
  • func (p *Process) SetContext(ctx context.Context)
  • func (p *Process) SetIPC(name string, f IpcFunc)

Variables

var (
	ErrTimeout     = errors.New("nodejs: timeout reached")
	ErrDeadProcess = errors.New("nodejs: process has died")
)

Types

type Factory

type Factory struct {
	// contains filtered or unexported fields
}

func New

func New() (*Factory, error)

func (*Factory) New

func (factory *Factory) New() (*Process, error)

func (*Factory) NewPool

func (f *Factory) NewPool(queueSize, maxProcs int) *Pool

NewPool returns a pool of nodejs processes generated by the factory. The pool will always generate at least queueSize processes in memory and will start new ones as they are taken. Passing queueSize <=0 will use the number of CPUs.

func (*Factory) NewWithTimeout

func (factory *Factory) NewWithTimeout(timeout time.Duration) (*Process, error)

type IpcFunc

type IpcFunc func(map[string]any) (any, error)

type Pool

type Pool struct {
	Timeout time.Duration // timeout for running nodejs, defaults to 10 second if zero
	// contains filtered or unexported fields
}

func (*Pool) Take

func (pool *Pool) Take(ctx context.Context) (*Process, error)

Take returns a Process from the pool and will wait until one is available, unless the context is cancelled.

func (*Pool) TakeIfAvailable

func (pool *Pool) TakeIfAvailable() *Process

TakeIfAvailable returns a Process if any is available, or nil if not

func (*Pool) TakeTimeout

func (pool *Pool) TakeTimeout(t time.Duration) (*Process, error)

TakeTimeout will return a Process taken from the pool if any is available before the timeout expires.

type Process

type Process struct {
	*exec.Cmd
	// contains filtered or unexported fields
}

func (*Process) Alive

func (p *Process) Alive() <-chan struct{}

Alive returns a channel that will be closed when the nodejs process ends

func (*Process) Checkpoint

func (p *Process) Checkpoint(timeout time.Duration) error

Checkpoint ensures the process is running and returns within the specified time

func (*Process) Close

func (p *Process) Close() error

Close closes the nodejs stdin pipe, causing the process to die of natual causes

func (*Process) Console

func (p *Process) Console() []byte

Console returns the console output so far for the nodejs process

func (*Process) Eval

func (p *Process) Eval(ctx context.Context, code string, opts map[string]any) (any, error)

Eval is similar to Run, but will return whatever the javascript code evaluated returned

func (*Process) EvalChannel

func (p *Process) EvalChannel(code string, opts map[string]any) (chan map[string]any, error)

EvalChannel will execute the provided code and return a channel that can be used to read the response once it is made available

func (*Process) GetVersion

func (p *Process) GetVersion(what string) string

func (*Process) Kill

func (p *Process) Kill()

Kill will kill the nodejs instance

func (*Process) Log

func (p *Process) Log(msg string, args ...any)

Log appends a message to the nodejs console directly so it can be retrieved with Console()

func (*Process) MakeResponse

func (p *Process) MakeResponse() (string, chan map[string]any)

MakeResponse returns a handler id and a channel that will see data appended to it if triggered from the javascript side with a response event to that id. This can be useful for asynchronisous events.

func (*Process) Run

func (p *Process) Run(code string, opts map[string]any)

Run executes the provided code in the nodejs instance. options can contain things like filename. If filename ends in .mjs, the code will be run as a JS module

func (*Process) Set

func (p *Process) Set(v string, val any)

Set sets a variable in the javascript global scope of this instance

func (*Process) SetContext

func (p *Process) SetContext(ctx context.Context)

func (*Process) SetIPC

func (p *Process) SetIPC(name string, f IpcFunc)

SetIPC adds an IPC that can be called from nodejs