This commit is contained in:
2026-01-28 21:59:04 -05:00
parent dcd516d970
commit ffcb6f658b
10 changed files with 60 additions and 134 deletions

View File

@@ -26,39 +26,37 @@ reichard.io/poiesis/
│ ├── runtime/ # Runtime management, transpilation, execution
│ │ ├── runtime.go
│ │ └── runtime_test.go
│ ├── builtin/ # Builtin registration framework
│ │ ├── types.go
│ ├── functions/ # Function registration framework
│ │ ├── collector.go
│ │ ├── registry.go
│ │ ├── wrapper.go
│ │ ├── convert.go
│ │ ├── types.go
│ │ ├── typescript.go
│ │ ── builtin_test.go
│ └── standard/ # Standard builtin implementations
│ │ ── typescript_test.go
│ └── functions_test.go
│ └── stdlib/ # Standard library implementations
│ ├── fetch.go
── fetch_test.go
│ └── fetch_promise_test.go
└── test_data/ # Test TypeScript files
── fetch_test.go
```
## Key Packages
- `reichard.io/poiesis/internal/runtime` - Runtime management, TypeScript transpilation, JavaScript execution
- `reichard.io/poiesis/internal/builtin` - Generic builtin registration framework (sync/async wrappers, automatic JS/Go conversion via JSON, type definition generation)
- `reichard.io/poiesis/internal/standard` - Standard builtin implementations (fetch, add, greet, etc.)
- `reichard.io/poiesis/internal/functions` - Generic function registration framework (sync/async wrappers, automatic JS/Go conversion via JSON, type definition generation)
- `reichard.io/poiesis/internal/stdlib` - Standard library implementations (fetch)
## Builtin System
## Function System
### Registration
Two types of builtins:
- **Sync**: `RegisterBuiltin[T, R](name, fn)` - executes synchronously, returns value
- **Async**: `RegisterAsyncBuiltin[T, R](name, fn)` - runs in goroutine, returns Promise
Two types of functions:
- **Sync**: `RegisterFunction[T, R](name, fn)` - executes synchronously, returns value
- **Async**: `RegisterAsyncFunction[T, R](name, fn)` - runs in goroutine, returns Promise
### Requirements
- Args must be a struct implementing `Args` interface with `Validate() error` method
- Use JSON tags for TypeScript type definitions
- Async builtins automatically generate `Promise<R>` return types
- Async functions automatically generate `Promise<R>` return types
### Example
@@ -74,11 +72,11 @@ func Add(_ context.Context, args AddArgs) (int, error) {
return args.A + args.B, nil
}
// Register sync builtin
builtin.RegisterBuiltin[AddArgs, int]("add", Add)
// Register sync function
functions.RegisterFunction[AddArgs, int]("add", Add)
// Register async builtin
builtin.RegisterAsyncBuiltin[FetchArgs, *FetchResult]("fetch", Fetch)
// Register async function
functions.RegisterAsyncFunction[FetchArgs, *FetchResult]("fetch", Fetch)
```
## Testing Patterns
@@ -87,6 +85,7 @@ builtin.RegisterAsyncBuiltin[FetchArgs, *FetchResult]("fetch", Fetch)
- **Assertions**: `github.com/stretchr/testify/assert` and `require`
- **Linting**: `golangci-lint run` - must pass before committing
- **Test organization**: Test files use `_test.go` suffix, test functions prefixed with `Test`
- **TypeScript test files**: Tests that require TypeScript files should create them inline using `os.CreateTemp()` instead of relying on external test files
## Dependencies