commonjs

package module
v0.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2023 License: Apache-2.0 Imports: 13 Imported by: 8

README

CommonJS for Goja

Use the Goja JavaScript engine in a CommonJS-style modular environment. Supports require, exports, and more, following the Node.js implementation as much as possible.

Features:

  • Customize the JavaScript environment with your own special APIs. A set of useful optional APIs are included.
  • By default require supports full URLs and can resolve paths relative to the current module's location. But this can be customized to support your own special resolution and code loading method (e.g. loading modules from a database).
  • Automatically converts Go field names to dromedary case for a more idiomatic JavaScript experience, e.g. .DoTheThing becomes .doTheThing.
  • Optional support for watching changes to all resolved JavaScript files if they are in the local filesystem, allowing your application to restart or otherwise respond to live code updates.
  • Optional support for bind, which is similar to require but exports the JavaScript objects, including functions, into a new goja.Runtime. This is useful for multi-threaded Go environments because a single goja.Runtime cannot be used simulatenously by more than one thread. Two variations exist: early binding, which creates the Runtime when bind is called (lower concurrency, higher performance), and late binding, which creates the Runtime every time the bound object is unbound (higher concurrency, lower performance).

Example

start.go:

package main

import (
    "github.com/tliron/commonjs-goja"
    "github.com/tliron/commonjs-goja/api"
    "github.com/tliron/exturl"
)

func main() {
    urlContext := exturl.NewContext()
    defer urlContext.Release()

    wd, _ := urlContext.NewWorkingDirFileURL()

    environment := commonjs.NewEnvironment(urlContext, wd)
    defer environment.Release()

    environment.Extensions = api.DefaultExtensions{}.Create()

    // Start!
    environment.Require("./start", false, nil)
}

start.js:

const hello = require('./lib/hello');

hello.sayit();

lib/hello.js:

exports.sayit = function() {
    console.log('hi!');
};

Documentation

Index

Constants

View Source 
const DEFAULT_TIMEOUT = time.Second * 5

Variables

View Source 
var DromedaryCaseMapper dromedaryCaseMapper

Functions

func Call 

func Call(runtime *goja.Runtime, function any, this any, arguments ...any) (value any, err error)

The function argument can be a ExportedJavaScriptFunc or a goja.Value representing a function.

func CallExported added in v0.2.3 

func CallExported(runtime *goja.Runtime, function ExportedJavaScriptFunc, this any, arguments ...any) (value any, err error)

func CallValue added in v0.2.3 

func CallValue(runtime *goja.Runtime, function goja.Value, this any, arguments ...any) (any, error)

func GetAndCall added in v0.1.10 

func GetAndCall(runtime *goja.Runtime, object *goja.Object, name string, this any, arguments ...any) (value any, err error)

func HandleJavaScriptPanic added in v0.2.0 

func HandleJavaScriptPanic(r any) error

Call with a recover() value. If it's an error, then it will be unwrapped and returned.

Otherwise, will re-panic the value.

This function is useful for cases in which Goja indicates errors by panicking instead of returning an error.

Usage: 

func MyFunc() (err error) {
	defer func() {
		if err_ := HandleJavaScriptPanic(recover()); err_ != nil {
			err = err_
		}
	}()
	// do something that can panic
}

func NewObject added in v0.2.0 

func NewObject(runtime *goja.Runtime, value any) *goja.Object

func UnwrapJavaScriptException added in v0.2.0 

func UnwrapJavaScriptException(err error) error

Types

type Bind 

type Bind interface {
	Unbind() (any, *Context, error)
}

type BindFunc added in v0.2.0 

type BindFunc func(id string, exportName string) (any, error)

type Context 

type Context struct {
	Environment *Environment
	Parent      *Context
	UserContext any
	Module      *Module
	Resolve     ResolveFunc
	Extensions  []goja.Value
}

func Unbind added in v0.2.0 

func Unbind(value any, jsContext *Context) (any, *Context, error)

If value is a Bind will unbind it, recursively, and return the bound value and Context.

Otherwise will return the provided value and Context as is.

func (*Context) AppendExtension added in v0.2.0 

func (self *Context) AppendExtension(extension Extension)

func (*Context) CreateExtension added in v0.2.0 

func (self *Context) CreateExtension(extension Extension) goja.Value

func (*Context) NewEarlyBind added in v0.2.0 

func (self *Context) NewEarlyBind(id string, exportName string) (EarlyBind, error)

Will attempt to immediately require the id and export the result, storing the result in an EarlyBind.

func (*Context) NewLateBind added in v0.2.0 

func (self *Context) NewLateBind(id string, exportName string) (LateBind, error)

Will resolve the id and store the URL and exportName in a LateBind. Only when LateBind.Unbind is called will require the URL and export the result (and cache the return values).

func (*Context) NewRequire added in v0.2.4 

func (self *Context) NewRequire() *goja.Object

func (*Context) Require added in v0.2.4 

func (self *Context) Require(context contextpkg.Context, url exturl.URL, childEnvironment bool, userContext any) (*goja.Object, *Context, error)

func (*Context) RequireAndExport added in v0.2.0 

func (self *Context) RequireAndExport(context contextpkg.Context, url exturl.URL, childEnvironment bool, userContext any, exportName string) (value any, jsContext *Context, err error)

func (*Context) ResolveAndRequire added in v0.2.4 

func (self *Context) ResolveAndRequire(context contextpkg.Context, id string, bareId bool, childEnvironment bool, userContext any) (*goja.Object, *Context, error)

func (*Context) ResolveAndWatch added in v0.2.0 

func (self *Context) ResolveAndWatch(context contextpkg.Context, id string, bareId bool) (exturl.URL, error)

type CreateExtensionFunc 

type CreateExtensionFunc func(jsContext *Context) any

Can return a goja.Value, nil, or other values, which will be converted to a goja.Value.

type CreateResolverFunc 

type CreateResolverFunc func(fromUrl exturl.URL, jsContext *Context) ResolveFunc

func NewDefaultResolverCreator 

func NewDefaultResolverCreator(defaultExtension string, allowFilePaths bool, urlContext *exturl.Context, basePaths ...exturl.URL) CreateResolverFunc

type EarlyBind 

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

func (EarlyBind) Unbind 

func (self EarlyBind) Unbind() (any, *Context, error)

(Bind interface)

type Environment 

type Environment struct {
	Runtime        *goja.Runtime
	URLContext     *exturl.Context
	BasePaths      []exturl.URL
	Extensions     []Extension
	Modules        *goja.Object
	Precompile     PrecompileFunc
	CreateResolver CreateResolverFunc
	OnFileModified OnFileModifiedFunc
	Timeout        time.Duration
	Strict         bool
	Log            commonlog.Logger
	Lock           sync.Mutex
	// contains filtered or unexported fields
}

func NewEnvironment 

func NewEnvironment(urlContext *exturl.Context, basePaths ...exturl.URL) *Environment

func (*Environment) AddModule 

func (self *Environment) AddModule(url exturl.URL, module *Module)

func (*Environment) Call 

func (self *Environment) Call(function any, this any, arguments ...any) (any, error)

func (*Environment) ClearCache 

func (self *Environment) ClearCache()

func (*Environment) GetAndCall added in v0.1.10 

func (self *Environment) GetAndCall(object *goja.Object, name string, this any, arguments ...any) (any, error)

func (*Environment) NewChild 

func (self *Environment) NewChild() *Environment

func (*Environment) NewContext 

func (self *Environment) NewContext(url exturl.URL, parent *Context, userContext any) *Context

func (*Environment) NewModule 

func (self *Environment) NewModule() *Module

func (*Environment) NewTimeoutContext added in v0.2.0 

func (self *Environment) NewTimeoutContext() (contextpkg.Context, contextpkg.CancelFunc)

func (*Environment) Release 

func (self *Environment) Release() error

func (*Environment) Require added in v0.2.0 

func (self *Environment) Require(id string, bareId bool, userContext any) (*goja.Object, error)

func (*Environment) RequireURL 

func (self *Environment) RequireURL(url exturl.URL, userContext any) (*goja.Object, error)

func (*Environment) StartWatcher added in v0.1.10 

func (self *Environment) StartWatcher() error

func (*Environment) StopWatcher 

func (self *Environment) StopWatcher() error

func (*Environment) Watch 

func (self *Environment) Watch(path string) error

type ExportedJavaScriptFunc added in v0.2.3 

type ExportedJavaScriptFunc = func(functionCall goja.FunctionCall) goja.Value

This is the returned type when calling Export() on a goja.FunctionCall.

type Extension 

type Extension struct {
	Name   string
	Create CreateExtensionFunc
}

func NewExtensions added in v0.2.0 

func NewExtensions(extensions map[string]CreateExtensionFunc) []Extension

type JavaScriptConstructorFunc added in v0.2.0 

type JavaScriptConstructorFunc = func(constructor goja.ConstructorCall) *goja.Object

func NewConstructor added in v0.2.0 

func NewConstructor(runtime *goja.Runtime, f func(constructor goja.ConstructorCall) (any, error)) JavaScriptConstructorFunc

type LateBind 

type LateBind struct {
	EarlyBind
	// contains filtered or unexported fields
}

func (LateBind) Unbind 

func (self LateBind) Unbind() (any, *Context, error)

(Bind interface)

type Module 

type Module struct {
	Id           string
	Children     []*Module
	Filename     string
	Path         string
	Paths        []string
	Exports      *goja.Object
	Require      *goja.Object
	IsPreloading bool
	Loaded       bool
}

type OnFileModifiedFunc added in v0.1.10 

type OnFileModifiedFunc func(id string, module *Module)

type PrecompileFunc 

type PrecompileFunc func(url exturl.URL, script string, jsContext *Context) (string, error)

type ResolveFunc 

type ResolveFunc func(context contextpkg.Context, id string, bareId bool) (exturl.URL, error)

type ThreadSafeObject 

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

func NewThreadSafeObject 

func NewThreadSafeObject() *ThreadSafeObject

func (*ThreadSafeObject) Delete 

func (self *ThreadSafeObject) Delete(key string) bool

(goja.DynamicObject interface)

func (*ThreadSafeObject) Get 

func (self *ThreadSafeObject) Get(key string) goja.Value

(goja.DynamicObject interface)

func (*ThreadSafeObject) Has 

func (self *ThreadSafeObject) Has(key string) bool

(goja.DynamicObject interface)

func (*ThreadSafeObject) Keys 

func (self *ThreadSafeObject) Keys() []string

(goja.DynamicObject interface)

func (*ThreadSafeObject) NewDynamicObject 

func (self *ThreadSafeObject) NewDynamicObject(runtime *goja.Runtime) *goja.Object

func (*ThreadSafeObject) Set 

func (self *ThreadSafeObject) Set(key string, value goja.Value) bool

(goja.DynamicObject interface)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.