69 lines
2.0 KiB
Markdown
69 lines
2.0 KiB
Markdown
# Go/JS Low-Code Engine
|
|
|
|
A lightweight, frictionless, and AI-friendly JavaScript engine for Go applications based on `goja`.
|
|
|
|
## Features
|
|
|
|
- **Decoupled Architecture**: Capability providers only need to depend on `apigo.cc/go/jsmod`.
|
|
- **Frictionless Bridging**: Automatic type conversion using `go/cast`.
|
|
- **Host Object Fidelity**: Go pointers and structs are preserved when passed back and forth between Go and JS.
|
|
- **Context Injection**: Automatic `context.Context` propagation from `js.Call`.
|
|
- **Versioned Pool**: Thread-safe VM pool with incremental code synchronization and version checking (`CheckVersion`).
|
|
- **Function Discovery**: List all defined functions via `FuncList()`.
|
|
- **Context Interruption**: Safe execution with `context.Context` cancellation support.
|
|
- **AI-Ready**: Generates TypeScript definitions (`.d.ts`) for AI to understand available capabilities.
|
|
|
|
## Usage
|
|
|
|
### 1. Register Go Capability (in any module)
|
|
|
|
```go
|
|
import "apigo.cc/go/jsmod"
|
|
|
|
func init() {
|
|
jsmod.Register("db", map[string]any{
|
|
"query": func(ctx context.Context, sql string) ([]map[string]any, error) {
|
|
// ...
|
|
},
|
|
})
|
|
}
|
|
```
|
|
|
|
### 2. Execute JS with Version Checking
|
|
|
|
```go
|
|
import "apigo.cc/go/js"
|
|
|
|
func main() {
|
|
// Check if script needs update (e.g., from file mtime)
|
|
if !js.CheckVersion("myTask.js", mtime) {
|
|
js.Define(code, "myTask.js", mtime)
|
|
}
|
|
|
|
res, err := js.Call(ctx, "myTask", "star")
|
|
}
|
|
```
|
|
|
|
### 3. Discover Functions
|
|
|
|
```go
|
|
funcs := js.FuncList()
|
|
// ["myTask", ...]
|
|
```
|
|
|
|
### 3. Generate AI Context
|
|
|
|
```go
|
|
dts := js.Doc()
|
|
// Feed d.ts to LLM to provide coding context
|
|
```
|
|
|
|
## Internal Bridge Details
|
|
|
|
The engine uses `goja`'s Host Object mechanism. When a Go struct/pointer is returned to JS, it remains a Go object. When passed back to a Go function, the original pointer is preserved, ensuring zero data loss and state consistency.
|
|
|
|
Types are automatically coerced:
|
|
- JS `string` -> Go `int` (via `go/cast`)
|
|
- JS `Object` -> Go `Struct`
|
|
- Go `error` -> JS `Exception`
|