112 lines
2.9 KiB
Markdown
112 lines
2.9 KiB
Markdown
# Poiesis
|
|
|
|
A Go tool that transpiles TypeScript to JavaScript using esbuild and executes it with goja, with an extensible builtin system.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
reichard.io/poiesis/
|
|
├── cmd/
|
|
│ └── poiesis/ # CLI application entry point
|
|
│ └── main.go
|
|
├── internal/
|
|
│ └── runtime/
|
|
│ ├── pkg/
|
|
│ │ └── builtin/ # Builtin framework (framework only)
|
|
│ │ └── builtin.go # Registration system & type conversion
|
|
│ ├── standard/ # Standard builtin implementations
|
|
│ │ ├── fetch.go # HTTP fetch builtin
|
|
│ │ └── fetch_test.go # Tests for fetch
|
|
│ ├── runtime.go # Transpilation & execution
|
|
│ └── runtime_test.go # Runtime tests
|
|
└── examples/ # Example TypeScript files
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The project is cleanly separated into three packages:
|
|
|
|
1. **`internal/runtime/pkg/builtin`** - The framework for registering builtins and type conversion
|
|
- Generic registration with automatic type inference
|
|
- Bidirectional Go ↔ JavaScript type conversion
|
|
- No builtin implementations (pure framework)
|
|
|
|
2. **`internal/runtime/standard`** - Standard builtin implementations
|
|
- `fetch`, `add`, `greet`
|
|
- Custom type converters for complex types
|
|
- Independent and easily extensible
|
|
|
|
3. **`internal/runtime`** - Runtime management
|
|
- TypeScript transpilation with esbuild
|
|
- JavaScript execution with goja
|
|
- Automatically imports and registers standard builtins
|
|
|
|
## Installation & Build
|
|
|
|
```bash
|
|
go build ./cmd/poiesis
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
go test ./...
|
|
golangci-lint run
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
poiesis <typescript-file>
|
|
```
|
|
|
|
## Builtin System
|
|
|
|
The builtin system allows you to easily expose Go functions to TypeScript/JavaScript.
|
|
|
|
### Adding a Builtin
|
|
|
|
Just write a Go function and register it:
|
|
|
|
```go
|
|
// Your function
|
|
func add(a, b int) int {
|
|
return a + b
|
|
}
|
|
|
|
// Register it
|
|
func init() {
|
|
builtin.RegisterBuiltin("add", add)
|
|
}
|
|
```
|
|
|
|
That's it! The framework automatically:
|
|
- Converts TypeScript values to Go types
|
|
- Handles errors (panics as JS errors)
|
|
- Generates TypeScript definitions
|
|
- Manages the goja integration
|
|
|
|
### Example
|
|
|
|
```typescript
|
|
// TypeScript code
|
|
console.log("5 + 10 =", add(5, 10));
|
|
|
|
const response = fetch("https://httpbin.org/get");
|
|
console.log("OK:", response.ok);
|
|
console.log("Status:", response.status);
|
|
console.log("Body:", response.text());
|
|
```
|
|
|
|
### Built-in Functions
|
|
|
|
- `fetch(url, options?)` - HTTP requests
|
|
- `add(a, b)` - Simple arithmetic example
|
|
- `greet(name)` - String manipulation example
|
|
|
|
## Dependencies
|
|
|
|
- `github.com/evanw/esbuild/pkg/api` - TypeScript transpilation
|
|
- `github.com/dop251/goja` - JavaScript execution
|
|
- `github.com/stretchr/testify/assert` - Test assertions
|