go/js
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: go:main
Branches Tags
go:main
go:v1.5.7
go:v1.5.6
go:v1.5.5
go:v1.5.4
go:v1.5.3
go:v1.5.2
go:v1.5.1
go:v1.5.0
go:v1.0.2
go:v1.0.1
go:v1.0.0
..
compare: go:v1.5.5
Branches Tags
go:main
go:v1.5.7
go:v1.5.6
go:v1.5.5
go:v1.5.4
go:v1.5.3
go:v1.5.2
go:v1.5.1
go:v1.5.0
go:v1.0.2
go:v1.0.1
go:v1.0.0

No commits in common. "main" and "v1.5.5" have entirely different histories.
main ... v1.5.5

8 changed files with 31 additions and 180 deletions
Show Stats Expand all files Collapse all files

12
CHANGELOG.md
View File

@ -1,17 +1,5 @@
# CHANGELOG - go/js
## v1.5.7 (2026-06-28)
- **低代码 TS 文档对齐**:
- `Doc()` 生成的模块入口改为顶层全局变量声明，如 `declare const api: Api_Module;`，不再使用 `declare const go: { ... }` 包裹。
- 为运行时注入的日志对象补充 `Logger` 接口，仅暴露 `Debug`、`Info`、`Warning`、`Error` 四个 JS 侧需要的方法。
- 统一非项目类型的不透明命名风格，默认声明改为 `GoContext`、`GoHTTPRequest`、`GoHTTPResponse`、`GoURL`，标准库结构体采用 `GoTime` 这类更稳定的命名。
- **测试增强**:
- `TestDocGeneration` 新增对顶层全局模块声明、`Logger` 暴露面和 `GoTime` 命名的覆盖。
## v1.5.6 (2026-06-21)
- **可变参数桥接修复**: `wrapGoFunc` 修复对 Go 可变参数（`...any`）的桥接处理。之前将 JS 剩余参数错误打包为单一切片元素，导致 `Call` 二次嵌套；现在改为逐个追加到 `goArgs` 尾部，由 `reflect.Call` 自动构建可变切片，确保 JS 调用 `redis.Do('HSET', a, b, c)` 正确展开。
- **新增测试**: `TestBridgeVariadic` 覆盖可变参数 0/1/多参数场景。
## v1.5.5 (2026-06-21)
- **JS 对齐**: 重构 JS 运行时的报错堆栈提取逻辑，采用高效的字符解析替换正则表达式，并支持 `jsmod.MakeError` 错误包装在桥接层还原出真实的 Go 运行时调用堆栈。
- **依赖更新**: 升级依赖 `jsmod` 至 `v1.5.3`，`cast` 至 `v1.5.3`，`log` 至 `v1.5.8`。

19
README.md
View File

@ -58,25 +58,6 @@ dts := js.Doc()
// Feed d.ts to LLM to provide coding context
```
The generated declarations are optimized for low-code editors:
- bridged modules are exposed as top-level globals such as `api`, `cast`, `db`, `service`
- injected logger values are typed as `Logger`
- opaque runtime handles use stable names such as `GoContext`, `GoHTTPRequest`, `GoHTTPResponse`, `GoURL`
- exposed standard-library structs use stable names such as `GoTime`
Example:
```ts
declare const service: Service_Module
interface Logger {
Debug(message: string, ...extra: any[]): void
Info(message: string, ...extra: any[]): void
Warning(message: string, ...extra: any[]): void
Error(message: string, ...extra: any[]): void
}
```
## 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.

13
TEST.md
View File

@ -1,15 +1,15 @@
# Test Report - go/js
## Performance (Benchmark)
Date: 2026-06-28
Date: 2026-06-21
OS: darwin
Arch: amd64
CPU: Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz
| Benchmark | Iterations | Time/op |
|-----------|------------|---------|
| BenchmarkCall | 766462 | 1331 ns/op |
| BenchmarkSync | 31066 | 52789 ns/op |
| BenchmarkCall | 661954 | 1566 ns/op |
| BenchmarkSync | 51656 | 50748 ns/op |
*Note: BenchmarkCall covers the hot path of executing a JS function from the pool. BenchmarkSync covers the cost of defining new code (including VM sync).*
@ -31,8 +31,6 @@ CPU: Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz
--- PASS: TestBridgeMixedInjection (0.00s)
=== RUN TestBridgeOptionalParams
--- PASS: TestBridgeOptionalParams (0.00s)
=== RUN TestBridgeVariadic
--- PASS: TestBridgeVariadic (0.00s)
=== RUN TestDocGeneration
--- PASS: TestDocGeneration (0.00s)
=== RUN TestPoolVersioning
@ -50,7 +48,7 @@ CPU: Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz
=== RUN TestDefineRedefine
--- PASS: TestDefineRedefine (0.00s)
PASS
ok apigo.cc/go/js 0.800s
ok apigo.cc/go/js 0.572s
```
## Features Verified
@ -63,7 +61,4 @@ ok apigo.cc/go/js 0.800s
- [x] Context cancellation interruption.
- [x] Graceful shutdown.
- [x] TypeScript definition generation.
- [x] Top-level global module declarations for low-code hints.
- [x] Opaque type naming stability (`GoContext`, `GoTime`, `GoURL`).
- [x] Runtime-injected `Logger` type hints with JS-safe methods only.
- [x] JS VM call stack parsing & Go dynamic call stack restoration with `jsmod.MakeError`.

31
bridge.go
View File

@ -52,10 +52,9 @@ func wrapGoFunc(vm *goja.Runtime, fn any, isUnsafe bool) goja.Value {
// 2. Prepare Arguments
numIn := t.NumIn()
goArgs := make([]reflect.Value, 0, numIn+len(call.Arguments))
goArgs := make([]reflect.Value, numIn)
jsArgs := call.Arguments
jsArgIdx := 0
isVariadic := t.IsVariadic()
for i := 0; i < numIn; i++ {
argType := t.In(i)
@ -66,7 +65,7 @@ func wrapGoFunc(vm *goja.Runtime, fn any, isUnsafe bool) goja.Value {
if ctx == nil {
ctx = context.Background()
}
goArgs = append(goArgs, reflect.ValueOf(ctx))
goArgs[i] = reflect.ValueOf(ctx)
continue
}
@ -81,42 +80,24 @@ func wrapGoFunc(vm *goja.Runtime, fn any, isUnsafe bool) goja.Value {
if logger == nil {
logger = log.DefaultLogger
}
goArgs = append(goArgs, reflect.ValueOf(logger))
continue
}
// 可变参数：剩余 JS 参数直接追加到 goArgs，不由 Call 再包一层
if isVariadic && i == numIn-1 {
elemType := argType.Elem()
for jsArgIdx < len(jsArgs) {
exported := jsArgs[jsArgIdx].Export()
expV := reflect.ValueOf(exported)
if !expV.IsValid() || !expV.Type().AssignableTo(elemType) {
elem := reflect.New(elemType).Elem()
cast.Convert(elem.Addr().Interface(), exported)
expV = elem
}
goArgs = append(goArgs, expV)
jsArgIdx++
}
goArgs[i] = reflect.ValueOf(logger)
continue
}
// Normal JS Argument with go/cast
goArg := reflect.New(argType).Elem()
goArgs[i] = reflect.New(argType).Elem()
if jsArgIdx < len(jsArgs) {
jsVal := jsArgs[jsArgIdx]
exported := jsVal.Export()
expV := reflect.ValueOf(exported)
if expV.IsValid() && expV.Type().AssignableTo(argType) {
goArg.Set(expV)
goArgs[i].Set(expV)
} else {
cast.Convert(goArg.Addr().Interface(), exported)
cast.Convert(goArgs[i].Addr().Interface(), exported)
}
jsArgIdx++
}
goArgs = append(goArgs, goArg)
}
// 3. Call the Go function

39
bridge_test.go
View File

@ -106,42 +106,3 @@ func TestBridgeOptionalParams(t *testing.T) {
t.Errorf("Optional param failed (val), got %v", val.Export())
}
}
func TestBridgeVariadic(t *testing.T) {
vm := goja.New()
variadicFn := func(cmd string, args ...any) string {
t.Logf("DEBUG variadicFn received: cmd=%q len(args)=%d args=%v argsType=%T", cmd, len(args), args, args)
for i, a := range args {
t.Logf("DEBUG args[%d] = %v (type=%T)", i, a, a)
}
return fmt.Sprintf("%s:%d:%v", cmd, len(args), args)
}
vm.Set("vfn", wrapGoFunc(vm, variadicFn, false))
// 无额外参数
val, _ := vm.RunString(`vfn("PING")`)
t.Logf("DEBUG vfn(PING) result: %v", val.Export())
if val.Export() != "PING:0:[]" {
t.Errorf("Variadic zero args failed, got %v", val.Export())
}
// 一个额外参数
val, _ = vm.RunString(`vfn("GET", "key1")`)
t.Logf("DEBUG vfn(GET, key1) result: %v", val.Export())
if val.Export() != "GET:1:[key1]" {
t.Errorf("Variadic one arg failed, got %v", val.Export())
}
// 多个额外参数
val, _ = vm.RunString(`vfn("HSET", "key1", "field1", "val1")`)
result := val.Export().(string)
t.Logf("DEBUG vfn(HSET, key1, field1, val1) result: %v", result)
if !strings.Contains(result, "HSET:3:") {
t.Errorf("Variadic multi args failed, got %v", result)
}
if !strings.Contains(result, "key1") || !strings.Contains(result, "field1") || !strings.Contains(result, "val1") {
t.Errorf("Variadic args content wrong, got %v", result)
}
}

68
doc.go
View File

@ -16,23 +16,17 @@ func Doc() string {
sb.WriteString("/**\n * Go/JS Low-Code Environment Type Definitions\n")
sb.WriteString(" * Generated by js.Doc(). DO NOT EDIT.\n */\n\n")
// 1. Basic opaque types for critical non-project types
// 1. Basic Opaque types (Manual fallback for critical non-project types)
sb.WriteString("/** Opaque handle to Go context.Context */\n")
sb.WriteString("interface GoContext { _isGoContext: true; }\n")
sb.WriteString("/** Logger injected by the Go runtime */\n")
sb.WriteString("interface Logger {\n")
sb.WriteString(" _isLogger: true;\n")
sb.WriteString(" Debug(message: string, ...extra: any[]): void;\n")
sb.WriteString(" Info(message: string, ...extra: any[]): void;\n")
sb.WriteString(" Warning(message: string, ...extra: any[]): void;\n")
sb.WriteString(" Error(message: string, ...extra: any[]): void;\n")
sb.WriteString("}\n")
sb.WriteString("/** Opaque handle to Go log.Logger */\n")
sb.WriteString("interface GoLogger { _isGoLogger: true; }\n")
sb.WriteString("/** Opaque handle to Go net/http.Request */\n")
sb.WriteString("interface GoHTTPRequest { _isGoHTTPRequest: true; }\n")
sb.WriteString("interface GoHttp_Request { _isGoHttpReq: true; }\n")
sb.WriteString("/** Opaque handle to Go net/http.Response */\n")
sb.WriteString("interface GoHTTPResponse { _isGoHTTPResponse: true; }\n")
sb.WriteString("interface GoHttp_Response { _isGoHttpRes: true; }\n")
sb.WriteString("/** Opaque handle to Go net/url.URL */\n")
sb.WriteString("interface GoURL { _isGoURL: true; }\n\n")
sb.WriteString("interface GoNet_URL { _isGoNetURL: true; }\n\n")
modules := jsmod.GetModules()
modNames := make([]string, 0, len(modules))
@ -112,11 +106,13 @@ func Doc() string {
sb.WriteString("\n\n")
}
// 5. Global module declarations
sb.WriteString("/** Global Go bridged modules */\n")
// 5. Global 'go' declaration
sb.WriteString("/** Global entry point for Go bridged modules */\n")
sb.WriteString("declare const go: {\n")
for _, modName := range modNames {
sb.WriteString(fmt.Sprintf("declare const %s: %s_Module;\n", modName, strings.Title(modName)))
sb.WriteString(fmt.Sprintf(" readonly %s: %s_Module;\n", modName, strings.Title(modName)))
}
sb.WriteString("};\n")
return sb.String()
}
@ -236,21 +232,6 @@ func goTypeToTS(t reflect.Type, ctx *docCtx) string {
}
// 3. Special Mappings for remaining named types (mostly Structs/Interfaces)
if pkgPath == "context" && rawName == "Context" {
return "GoContext"
}
if pkgPath == "apigo.cc/go/log" && rawName == "Logger" {
return "Logger"
}
if pkgPath == "net/http" && rawName == "Request" {
return "GoHTTPRequest"
}
if pkgPath == "net/http" && rawName == "Response" {
return "GoHTTPResponse"
}
if pkgPath == "net/url" && rawName == "URL" {
return "GoURL"
}
if pkgPath == "time" && rawName == "Time" {
return registerInterface(t, ctx)
}
@ -261,7 +242,7 @@ func goTypeToTS(t reflect.Type, ctx *docCtx) string {
if pkgPath != "" && !isProject {
base := filepath.Base(pkgPath)
opaqueName := strings.Title(base) + "_" + rawName
opaqueName := "Go" + strings.Title(base) + "_" + rawName
ctx.opaqueList[opaqueName] = true
return opaqueName
}
@ -293,7 +274,9 @@ func registerInterface(t reflect.Type, ctx *docCtx) string {
parts := strings.Split(pkgPath, "/")
name = fmt.Sprintf("%s_%s", strings.Title(parts[len(parts)-1]), rawName)
} else if pkgPath != "" {
name = externalTypeName(pkgPath, rawName)
// Standard lib types like time.Time
base := filepath.Base(pkgPath)
name = fmt.Sprintf("Go%s_%s", strings.Title(base), rawName)
} else {
name = fmt.Sprintf("%s_%s", strings.Title(ctx.currentMod), rawName)
}
@ -347,27 +330,6 @@ func registerInterface(t reflect.Type, ctx *docCtx) string {
return name
}
func externalTypeName(pkgPath, rawName string) string {
base := filepath.Base(pkgPath)
baseName := externalSegmentName(base)
typeName := externalSegmentName(rawName)
if baseName == typeName {
return "Go" + typeName
}
return "Go" + baseName + typeName
}
func externalSegmentName(name string) string {
switch strings.ToLower(name) {
case "http":
return "HTTP"
case "url":
return "URL"
default:
return strings.Title(name)
}
}
func isMethodUnusable(t reflect.Type) bool {
for i := 0; i < t.NumIn(); i++ {
if isTypeUnusable(t.In(i)) {

23
doc_test.go
View File

@ -4,7 +4,6 @@ import (
"context"
"strings"
"testing"
"time"
"apigo.cc/go/jsmod"
)
@ -14,35 +13,19 @@ func TestDocGeneration(t *testing.T) {
"query": func(ctx context.Context, sql string, args []any) ([]map[string]any, error) {
return nil, nil
},
"now": func() time.Time { return time.Time{} },
"version": "1.0.0",
"__exportInternal": func() *struct{ Name string } { return nil },
})
doc := Doc()
if !strings.Contains(doc, "interface GoContext {") {
t.Error("doc should contain GoContext interface")
}
if !strings.Contains(doc, "interface Logger {") {
t.Error("doc should contain Logger interface")
}
if !strings.Contains(doc, "Info(message: string, ...extra: any[]): void;") {
t.Error("doc should contain Logger methods")
}
if strings.Contains(doc, "GetTraceId(): string;") || strings.Contains(doc, "New(traceId: string): Logger;") || strings.Contains(doc, "As<T = any>(value: T, err: any): T;") {
t.Error("doc should not contain Logger internal methods")
}
if !strings.Contains(doc, "interface GoTime {") {
if !strings.Contains(doc, "interface GoTime") {
t.Error("doc should contain GoTime interface")
}
if !strings.Contains(doc, "interface Db_Module") {
t.Error("doc should contain Db_Module interface")
}
if !strings.Contains(doc, "declare const db: Db_Module;") {
t.Error("doc should contain top-level module declaration")
}
if strings.Contains(doc, "declare const go:") {
t.Error("doc should not contain legacy go namespace declaration")
if !strings.Contains(doc, "declare const go:") {
t.Error("doc should contain global go declaration")
}
if strings.Contains(doc, "__exportInternal") {
t.Error("doc should NOT contain __exportInternal")

6
go.mod
View File

@ -11,12 +11,12 @@ require (
require (
apigo.cc/go/config v1.5.3 // indirect
apigo.cc/go/encoding v1.5.5 // indirect
apigo.cc/go/encoding v1.5.4 // indirect
apigo.cc/go/file v1.5.5 // indirect
apigo.cc/go/id v1.5.6 // indirect
apigo.cc/go/id v1.5.4 // indirect
apigo.cc/go/rand v1.5.3 // indirect
apigo.cc/go/safe v1.5.2 // indirect
apigo.cc/go/shell v1.5.4 // indirect
apigo.cc/go/shell v1.5.3 // indirect
github.com/dlclark/regexp2 v1.11.4 // indirect
github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e // indirect