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 

func (d *NapiGoInstanceAsyncWorkData) GetAsyncWork(
	id NapiGoAsyncWorkID,
) *NapiGoAsyncWorkMapEntry

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 

func (d *NapiGoInstanceCallbackData) GetCallback(
	id NapiGoCallbackID,
) *NapiGoCallbackMapEntry

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
)

Source Files

View all Source files

Directories

Path Synopsis
docs
examples/async-promise
examples/callback
examples/describe-args
examples/hello-world
examples/js

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.