napi

package module
v0.0.0-...-e3d73f5 Latest Latest
Warning

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

Go to latest
Published: Apr 25, 2024 License: MIT Imports: 6 Imported by: 0

README

napi-go

A Go library for building Node.js Native Addons using Node-API.

Usage

Use go get to install the library:

go get -u github.com/Automattic/napi-go

Then use the library to define handlers:

package handlers

import "github.com/Automattic/napi-go"

func MyHandler(env napi.Env, info napi.CallbackInfo) napi.Value {
  return nil
}

Next, create a main.go that registers all module exports:

package main

import "github.com/Automattic/napi-go/entry"

func init() {
  entry.Export("myHandler", MyHandler)
}

func main() {}

Finally, build the Node.js addon using go build:

go build -buildmode=c-shared -o "example.node" .

The output .node file can now be imported via require:

const example = require("./example.node");

example.myHandler();
JS Helpers

In addition to the Node-API exposed via package napi, the napi-go/js package provides functions similar to the syscall/js standard library.

package main

import (
  "github.com/Automattic/napi-go/entry"
  "github.com/Automattic/napi-go/js"
)

func init() {
  entry.Export("myCallback", js.AsCallback(MyCallback))
}

func MyCallback(env js.Env, this js.Value, args []js.Value) any {
  return map[string]any{
    "message": "hello world",
    "args":    args,
  }
}

func main() {}

Examples

Check out the example addons in docs/examples.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateArray

func CreateArray(env Env) (Value, Status)

func CreateArrayWithLength

func CreateArrayWithLength(env Env, length int) (Value, Status)

func CreateAsyncWork

func CreateAsyncWork(
	env Env,
	asyncResource, asyncResourceName Value,
	execute AsyncExecuteCallback,
	complete AsyncCompleteCallback,
) (AsyncWork, Status)

func CreateDouble

func CreateDouble(env Env, value float64) (Value, Status)

func CreateError

func CreateError(env Env, code, msg Value) (Value, Status)

func CreateFunction

func CreateFunction(env Env, name string, cb Callback) (Value, Status)

func CreateObject

func CreateObject(env Env) (Value, Status)

func CreatePromise

func CreatePromise(env Env) (Promise, Status)

func CreateStringUtf8

func CreateStringUtf8(env Env, str string) (Value, Status)

func CreateSymbol

func CreateSymbol(env Env, description Value) (Value, Status)

func CreateThreadsafeFunction

func CreateThreadsafeFunction(
	env Env,
	fn Value,
	asyncResource, asyncResourceName Value,
	maxQueueSize, initialThreadCount int,
) (ThreadsafeFunction, Status)

func DeleteCallbackData

func DeleteCallbackData(
	cEnv C.napi_env,
	finalizeData, finalizeHint unsafe.Pointer,
)

func DeleteInstanceData

func DeleteInstanceData(
	env C.napi_env,
	finalizeData, finalizeHint unsafe.Pointer,
)

func ExecuteAsyncCompleteCallback

func ExecuteAsyncCompleteCallback(
	cEnv C.napi_env,
	cStatus C.napi_status,
	cData unsafe.Pointer,
)

func ExecuteAsyncExecuteCallback

func ExecuteAsyncExecuteCallback(cEnv C.napi_env, cData unsafe.Pointer)

func ExecuteCallback

func ExecuteCallback(
	cEnv C.napi_env,
	cInfo C.napi_callback_info,
) C.napi_value

func GetBoolean

func GetBoolean(env Env, value bool) (Value, Status)

func GetCbInfo

func GetCbInfo(env Env, info CallbackInfo) (GetCbInfoResult, Status)

func GetGlobal

func GetGlobal(env Env) (Value, Status)

func GetNodeVersion

func GetNodeVersion(env Env) (NodeVersion, Status)

func GetNull

func GetNull(env Env) (Value, Status)

func GetUndefined

func GetUndefined(env Env) (Value, Status)

func Typeof

func Typeof(env Env, value Value) (ValueType, Status)

Types

type AsyncCompleteCallback

type AsyncCompleteCallback func(env Env, status Status)

type AsyncExecuteCallback

type AsyncExecuteCallback func(env Env)

type AsyncWork

type AsyncWork struct {
	Handle unsafe.Pointer
	ID     NapiGoAsyncWorkID
}

type AsyncWorkDataProvider

type AsyncWorkDataProvider interface {
	CreateAsyncWork(
		env Env,
		asyncResource, asyncResourceName Value,
		execute AsyncExecuteCallback,
		complete AsyncCompleteCallback,
	) (AsyncWork, Status)
	GetAsyncWork(id NapiGoAsyncWorkID) *NapiGoAsyncWorkMapEntry
	DeleteAsyncWork(id NapiGoAsyncWorkID)
}

type Callback

type Callback func(env Env, info CallbackInfo) Value

type CallbackDataProvider

type CallbackDataProvider interface {
	CreateCallback(env Env, name string, cb Callback) (Value, Status)
	GetCallback(id NapiGoCallbackID) *NapiGoCallbackMapEntry
	DeleteCallback(id NapiGoCallbackID)
}

type CallbackInfo

type CallbackInfo unsafe.Pointer

type Deferred

type Deferred unsafe.Pointer

type Env

type Env unsafe.Pointer

type GetCbInfoResult

type GetCbInfoResult struct {
	Args []Value
	This Value
}

type InstanceDataProvider

type InstanceDataProvider interface {
	GetUserData() any
	SetUserData(userData any)

	GetCallbackData() CallbackDataProvider
	GetAsyncWorkData() AsyncWorkDataProvider
}

type NapiGoAsyncWorkID

type NapiGoAsyncWorkID int

type NapiGoAsyncWorkMapEntry

type NapiGoAsyncWorkMapEntry struct {
	Execute  AsyncExecuteCallback
	Complete AsyncCompleteCallback
	ID       NapiGoAsyncWorkID
}

type NapiGoCallbackID

type NapiGoCallbackID int

type NapiGoCallbackMapEntry

type NapiGoCallbackMapEntry struct {
	Callback Callback
	ID       NapiGoCallbackID
}

type NapiGoInstanceAsyncWorkData

type NapiGoInstanceAsyncWorkData struct {
	AsyncWorkMap NapiGoInstanceAsyncWorkMap
	NextID       NapiGoAsyncWorkID
	Lock         sync.RWMutex
}

func (*NapiGoInstanceAsyncWorkData) CreateAsyncWork

func (d *NapiGoInstanceAsyncWorkData) CreateAsyncWork(
	env Env,
	asyncResource, asyncResourceName Value,
	execute AsyncExecuteCallback,
	complete AsyncCompleteCallback,
) (AsyncWork, Status)

func (*NapiGoInstanceAsyncWorkData) DeleteAsyncWork

func (d *NapiGoInstanceAsyncWorkData) DeleteAsyncWork(id NapiGoAsyncWorkID)

func (*NapiGoInstanceAsyncWorkData) GetAsyncWork

type NapiGoInstanceAsyncWorkMap

type NapiGoInstanceAsyncWorkMap map[NapiGoAsyncWorkID]*NapiGoAsyncWorkMapEntry

type NapiGoInstanceCallbackData

type NapiGoInstanceCallbackData struct {
	CallbackMap NapiGoInstanceCallbackMap
	NextID      NapiGoCallbackID
	Lock        sync.RWMutex
}

func (*NapiGoInstanceCallbackData) CreateCallback

func (d *NapiGoInstanceCallbackData) CreateCallback(
	env Env,
	name string,
	cb Callback,
) (Value, Status)

func (*NapiGoInstanceCallbackData) DeleteCallback

func (d *NapiGoInstanceCallbackData) DeleteCallback(id NapiGoCallbackID)

func (*NapiGoInstanceCallbackData) GetCallback

type NapiGoInstanceCallbackMap

type NapiGoInstanceCallbackMap map[NapiGoCallbackID]*NapiGoCallbackMapEntry

type NapiGoInstanceData

type NapiGoInstanceData struct {
	UserData      any
	CallbackData  NapiGoInstanceCallbackData
	AsyncWorkData NapiGoInstanceAsyncWorkData
}

func (*NapiGoInstanceData) GetAsyncWorkData

func (d *NapiGoInstanceData) GetAsyncWorkData() AsyncWorkDataProvider

func (*NapiGoInstanceData) GetCallbackData

func (d *NapiGoInstanceData) GetCallbackData() CallbackDataProvider

func (*NapiGoInstanceData) GetUserData

func (d *NapiGoInstanceData) GetUserData() any

func (*NapiGoInstanceData) SetUserData

func (d *NapiGoInstanceData) SetUserData(userData any)

type NodeVersion

type NodeVersion struct {
	Major   uint
	Minor   uint
	Patch   uint
	Release string
}

type Promise

type Promise struct {
	Deferred Deferred
	Value    Value
}

type Status

type Status int
const (
	StatusOK                            Status = C.napi_ok
	StatusInvalidArg                    Status = C.napi_invalid_arg
	StatusObjectExpected                Status = C.napi_object_expected
	StatusStringExpected                Status = C.napi_string_expected
	StatusNameExpected                  Status = C.napi_name_expected
	StatusFunctionExpected              Status = C.napi_function_expected
	StatusNumberExpected                Status = C.napi_number_expected
	StatusBooleanExpected               Status = C.napi_boolean_expected
	StatusArrayExpected                 Status = C.napi_array_expected
	StatusGenericFailure                Status = C.napi_generic_failure
	StatusPendingException              Status = C.napi_pending_exception
	StatusCancelled                     Status = C.napi_cancelled
	StatusEscapeCalledTwice             Status = C.napi_escape_called_twice
	StatusHandleScopeMismatch           Status = C.napi_handle_scope_mismatch
	StatusCallbackScopeMismatch         Status = C.napi_callback_scope_mismatch
	StatusQueueFull                     Status = C.napi_queue_full
	StatusClosing                       Status = C.napi_closing
	StatusBigintExpected                Status = C.napi_bigint_expected
	StatusDateExpected                  Status = C.napi_date_expected
	StatusArraybufferExpected           Status = C.napi_arraybuffer_expected
	StatusDetachableArraybufferExpected Status = C.napi_detachable_arraybuffer_expected
	StatusWouldDeadlock                 Status = C.napi_would_deadlock
)

func AcquireThreadsafeFunction

func AcquireThreadsafeFunction(fn ThreadsafeFunction) Status

func CallThreadsafeFunction

func CallThreadsafeFunction(
	fn ThreadsafeFunction,
) Status

func CancelAsyncWork

func CancelAsyncWork(env Env, work AsyncWork) Status

func DeleteAsyncWork

func DeleteAsyncWork(env Env, work AsyncWork) Status

func GetInstanceData

func GetInstanceData(env Env) (any, Status)

func GetModuleFileName

func GetModuleFileName(env Env) (string, Status)

func GetValueBool

func GetValueBool(env Env, value Value) (bool, Status)

func GetValueDouble

func GetValueDouble(env Env, value Value) (float64, Status)

func GetValueStringUtf8

func GetValueStringUtf8(env Env, value Value) (string, Status)

func InitializeInstanceData

func InitializeInstanceData(env Env) Status

func QueueAsyncWork

func QueueAsyncWork(env Env, work AsyncWork) Status

func RejectDeferred

func RejectDeferred(env Env, deferred Deferred, rejection Value) Status

func ReleaseThreadsafeFunction

func ReleaseThreadsafeFunction(
	fn ThreadsafeFunction,
) Status

func ResolveDeferred

func ResolveDeferred(env Env, deferred Deferred, resolution Value) Status

func SetElement

func SetElement(env Env, object Value, index int, value Value) Status

func SetInstanceData

func SetInstanceData(env Env, data any) Status

func SetProperty

func SetProperty(env Env, object, key, value Value) Status

func StrictEquals

func StrictEquals(env Env, lhs, rhs Value) (bool, Status)

func Throw

func Throw(env Env, err Value) Status

func ThrowError

func ThrowError(env Env, code, msg string) Status

func (Status) String

func (s Status) String() string

type StatusError

type StatusError Status

func (StatusError) Error

func (err StatusError) Error() string

type ThreadsafeFunction

type ThreadsafeFunction unsafe.Pointer

type Value

type Value unsafe.Pointer

type ValueType

type ValueType int
const (
	ValueTypeUndefined ValueType = C.napi_undefined
	ValueTypeNull      ValueType = C.napi_null
	ValueTypeBoolean   ValueType = C.napi_boolean
	ValueTypeNumber    ValueType = C.napi_number
	ValueTypeString    ValueType = C.napi_string
	ValueTypeSymbol    ValueType = C.napi_symbol
	ValueTypeObject    ValueType = C.napi_object
	ValueTypeFunction  ValueType = C.napi_function
	ValueTypeExternal  ValueType = C.napi_external
	ValueTypeBigint    ValueType = C.napi_bigint
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL