tinybind-go
日本語
Reflection-free, code-generation-first binding for TinyGo and standard Go. Runtime dependencies are isolated into HTTP, JSON, SQL, and DynamoDB packages.
User guides: httpbind · jsonbind · cborbind · configbind · tomlbind · htmlbind · sqlbind · dynamobind · firestorebind · cachekeybind · reloadable components · fasthttp backend · size and shape limits
Building a framework on top of this? Start with framework facilities, the index of what is available to you and what is not, then htmlbind for framework owners and, if your users will build against fasthttp, the fasthttp backend for framework owners. Owning a browser runtime as well? Client behaviour covers server actions, client handlers, and component parameters in one place.
Define request/response structs once. The generator emits type-specific binders and writers, so the same model covers JSON, form, multipart, and query (plus path / header / cookie via tags). Responses adapt to the client Accept (and streaming negotiation where used). From the same analysis it also generates OpenAPI 3.1 (JSON), kept in sync with binders and writers, with godoc comments carried into summary / description. Route registration is discovered by static analysis of real net/http styles (HandleFunc, Handle, method values, wrappers, and so on)—not by a separate DSL.
type CreateUserRequest struct {
// input = query + payload (JSON / form / multipart). Tag may be omitted.
Name string `input:"name"` // same as untagged: Name string
Email string `input:"email"` // same as untagged: Email string
OrgID string `path:"org_id"`
Token string `header:"Authorization"`
}
type CreateUserResponse struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
OrgID string `json:"org_id"`
}
func createUserHandler(w http.ResponseWriter, r *http.Request) {
input, err := httpbind.Bind[CreateUserRequest](r)
if err != nil {
httpbind.WriteError(w, r, err)
return
}
// Name/Email: query and/or JSON/form/multipart body (input).
// OrgID from path, Token from Authorization header.
out := CreateUserResponse{
ID: "u_1",
Name: input.Name,
Email: input.Email,
OrgID: input.OrgID,
}
_ = httpbind.Write[CreateUserResponse](w, r, out)
}
Run the generator on the package (binders + OpenAPI embed):
go run ./cmd/tinybind-gen generate -dir . -openapi
The same generation pass also supports CLI-only application subcommands through
configbind.SubCommand[T], including required, optional, and rest positional
arguments. See the configbind subcommand guide.
Struct tag reference
Wire name defaults to the lower-camel field name when a tag value is omitted (e.g. untagged Name → "name").
| Tag |
Source |
Notes |
(none) or input:"name" |
query + payload |
Default. Payload covers JSON, application/x-www-form-urlencoded, and multipart/form-data. Tag is optional when the field is plain user input. |
query:"page" |
query only |
Not read from the body. |
payload:"name" |
body only |
JSON / form / multipart by Content-Type. Not read from the query string. |
payload:"image" on httpbind.File |
multipart file part |
Binds filename, content type, size, and bytes from the named part. Payload-only (not query). Multipart bodies are capped at 1 MiB by default; override with httpbind.SetMaxMultipartBodyBytes. |
path:"org_id" |
path parameter |
Matches {org_id} (or equivalent) in the route pattern. |
header:"Authorization" |
request header |
Header name is the tag value. |
cookie:"session" |
cookie |
Cookie name is the tag value. |
input vs payload vs query
- Prefer
input (or no tag) for normal fields that may arrive as query or body.
- Use
query / payload only when you must restrict the origin (e.g. search filters in the query string, body-only JSON fields).
payload is not the same as input: it does not accept query parameters.
Example that mixes restrictions:
type SearchRequest struct {
Keyword string `query:"keyword"` // query only
Page int `query:"page"`
Filter string `payload:"filter"` // body only (JSON/form/multipart)
}
Response structs commonly use standard json:"..." names for encoding; request binding still uses the source tags above.
Streaming (ideal API)
httpbind.WriteStream(w, r, func(s *httpbind.Stream[ChatEvent]) error {
if err := s.Write(ChatEvent{Type: "delta", Delta: "hi"}); err != nil {
return err
}
return s.Write(ChatEvent{Type: "done"})
})
Write can be called many times (incremental events).
- Format is chosen once when the stream opens, from
?stream=, Accept, User-Agent, then default NDJSON.
- The entry closes the stream, so the trailing
] of the JSON array framing is written even when the callback fails halfway.
- Formats:
- SSE —
text/event-stream
- NDJSON / JSONL —
application/x-ndjson (one object per line; not a JSON array)
- JSON array —
application/json as [obj1,obj2,...] (Close writes the trailing ])
- Do not use removed helpers
WriteNDJSON / WriteSSE.
Packages
| Path |
Role |
httpbind/ |
Runtime: Bind / Write / WriteError / WriteStream / OpenAPI serve / SwaggerUI (the module root before v0.6) |
jsonbind/ |
Standalone DecodeJSON / EncodeJSON runtime; does not import net/http or database/sql |
tomlbind/ |
Standalone DecodeTOML runtime over minitoml; the TOML layer of configbind without its env, CLI, or config-dir parsers |
sqlbind/ |
ScanRows runtime and row helpers; does not import net/http |
dynamobind/ |
DynamoDB item runtime over tinygodriver/nosql/dynamodb; does not import net/http or database/sql |
firestorebind/ |
Firestore Datastore-mode entity runtime over tinygodriver/nosql/datastore; does not import net/http or database/sql |
cachekeybind/ |
Cache key framing runtime; stdlib only |
generator/ |
Field-plan binders/writers + OpenAPI 3.1 + template generation |
parser/ |
Route/handler discovery (Bind, Write, WriteStream, errors) |
templates/htmlbind/ |
Typed, context-safe HTML template compiler |
templates/sqlbind/ |
Typed, parameterized SQL template compiler |
templates/firestorebind/ |
Typed Firestore access-pattern declarations (.tb.firestore) |
cmd/tinybind-gen |
CLI: binders + OpenAPI + templates from a package dir |
examples/demo |
End-to-end sample app |
internal/* |
Test fixtures |
testdata/cmd/* |
Dev-only helpers (not for distribution; under testdata so go get / ./... skip them) |
go run ./cmd/tinybind-gen generate -dir ./path/to/package
Every generated file records a // tinybind:generated comment holding the
SHA-256 of the inputs that produced it, so a run whose package sources,
templates, go.mod, options, and generator binary all hash to the recorded
value exits without regenerating. -force regenerates regardless. See
docs/httpbind.md.
The CLI automatically discovers .tb.html and .tb.sql files in the target
package and writes tinybind_templates_gen.go. A package containing SQL
templates must name its database with -sql-dialect postgresql, mysql, or
sqlite; there is no default. SQL value expressions become driver arguments,
and placeholders are generated in encounter order in the style that dialect
requires — $1, $2, … for PostgreSQL and ? for MySQL and SQLite:
package store
type User { id: int, name: string }
export statement FindUser(id: int): sql.optional<User> {
SELECT id, name FROM users WHERE id = {id}
}
This generates both BuildFindUser(id) (Statement, error) and the
FindUser(ctx, db, id) (*User, error) convenience API. The SQL compiler also
supports sql.exec, sql.one<T>, sql.many<T>, private sql.predicate
composition, private sql.relation<T> subqueries, conditional clauses, and
array value-list expansion. Hand-authored placeholders and unguarded
UPDATE/DELETE statements are rejected.
sql.many<T> streams rows as iter.Seq2[T, error] without first allocating a
result slice. Query, scan, and iteration errors are yielded as the error value,
and stopping the range early closes the underlying sql.Rows:
for user, err := range FindUsers(ctx, db, filter) {
if err != nil {
return err
}
// consume user
}
Web frameworks can opt in to executor-from-Context wrappers while the explicit
db APIs remain available:
go run ./cmd/tinybind-gen generate -dir ./path/to/package -sql-context-api
The generated FindUsersContext(ctx, filter) resolves the *sql.DB,
*sql.Conn, or *sql.Tx installed with sqlbind.WithSQLExecutor. This allows
transaction middleware to keep the executor inside its callback Context:
web.Transaction(func(ctx context.Context) error {
for user, err := range FindUsersContext(ctx, filter) {
if err != nil {
return err
}
// consume user within the transaction
}
return nil
})
Custom generator commands may use a framework-owned Context key by setting a
resolver with the signature
func(context.Context) (SQLExecutor, error); setting it also enables the
Context wrappers:
options.SQLExecutorResolver = &generator.SymbolPattern{
PackagePath: "example.com/web/dbctx",
Name: "Executor",
}
Frameworks may wrap the runtime functions and still make those calls visible to
the generator. Register the wrapper's package identity, semantic operation, and
the zero-based positions of only the type/value roles that the generator needs:
package main
import "github.com/shibukawa/tinybind-go/generator"
func main() {
calls := generator.NewCallRegistry()
if err := calls.Register(
// func RegisterConfig[T any](ctx context.Context, name string) *T
generator.ConfigBindCall(
generator.Function("example.com/framework", "RegisterConfig"),
generator.GenericType("config", 0),
generator.Argument("prefix", 1),
),
// func Created(ctx context.Context, w http.ResponseWriter, value any) error
generator.ResponseWriteStatusCall(
generator.Function("example.com/framework", "Created"),
generator.ArgumentType("response", 2),
generator.Constant("status", 201),
),
); err != nil {
panic(err)
}
options, err := calls.Options(generator.DefaultOptions())
if err != nil {
panic(err)
}
generator.Main(generator.MustCommandSet(generator.GenerateCommand(options)))
}
Extra wrapper arguments do not need to be described. Use GenericType when the
model comes from a generic type argument, ArgumentType when it comes from a
value argument's static type, Argument for a runtime value such as a config
prefix or route pattern, and Constant when the wrapper hides a fixed value
such as status 201. The available operations have matching constructors:
RequestBindCall, ResponseWriteCall, ResponseWriteStatusCall,
StreamCreateCall, JSONDecodeCall, JSONEncodeCall, RowsScanCall,
ConfigBindCall, ConfigSubCommandCall, RouteRegisterCall, and
ErrorResponseCall. Function
targets package functions; Method targets named-receiver methods.
The required role names, in the same order, are request; response;
response + status; stream; decode; encode; row; config +
prefix; config + name + help; pattern + handler; and status.
RuntimePackages remains a shorthand for functions with the standard tinybind
names and signatures. Use explicit call patterns for renamed wrappers, reordered
arguments, extra arguments, or hidden constants. generator.Options{}
deliberately has no discovery identities. Add a feature to DisableFeatures to
prevent discovery even under -generate-all.
A framework can combine the built-in generate command with its own lifecycle
commands:
commands := generator.MustCommandSet(
generator.GenerateCommand(options),
generator.Command{Name: "init", Summary: "initialize a project", Run: runInit},
generator.Command{Name: "build", Summary: "generate and build", Run: runBuild},
generator.Command{Name: "watch", Summary: "watch, generate, and build", Run: runWatch},
)
generator.Main(commands)
Each command receives a context.Context, arguments, and injected CommandIO
containing stdin/stdout/stderr, working directory, and environment. A build or
watch implementation can generate in-process without invoking a CLI:
result, err := generator.New(options).GeneratePackage(ctx, generator.GenerateRequest{
Dir: dir, OpenAPI: true,
})
GeneratePackage runs template, mapping, configbind, and optional OpenAPI
generation and returns the written paths. generator.Main is only the outer
process boundary; tests and composed commands should call CommandSet.Run or
GeneratePackage directly.
Generation is usage-aware: a package that only calls DecodeJSON[T] gets only
its JSON decoder, imports jsonbind, and does not import the httpbind HTTP runtime
or net/http. Set Options.GenerateAll for
the legacy all-enabled-mappings mode. Compatible multipart file aliases can be
listed in Options.FileTypes.Set.
Standalone JSON uses the dependency-isolated package:
value, err := jsonbind.DecodeJSON[Document](reader)
err = jsonbind.EncodeJSON(writer, value)
JSON reads are capped at 1 MiB by default, and objects and arrays may nest
10000 deep, matching encoding/json. jsonbind returns transport-neutral
errors; httpbind.Bind maps an oversized HTTP request to status 413 and a
malformed one to 400. Every limit a request can run into — bodies, nesting,
uploads, WebSocket messages, and the ones the transport owns rather than this
module — is collected in size and shape limits.
Joined SQL rows can be grouped into an object tree with generated, reflection-free ScanRows[T] code:
type Organization struct {
ID int `db:"organization_id" groupkey:""`
Name string `db:"organization_name"`
Users []User
}
type User struct {
ID int `db:"user_id" groupkey:""`
Name string `db:"user_name"`
}
organizations, err := sqlbind.ScanRows[Organization](rows)
Every grouped struct level has one groupkey field. Repeated keys merge into
the same object; a NULL child key represents an absent outer-join child.
.tb.html, .tb.sql, and .tb.dynamo are file formats this module invented, so
no editor knows how to format them. The generator ships the formatter:
go run ./cmd/tinybind-gen fmt -w -dir ./store
-l lists the files that would change and exits non-zero, which is the CI form.
-as sql (or html, dynamo) filters one source from stdin to stdout, which is
what an editor "format on save" hook needs.
What it does per format:
- SQL — one clause per line, CTE bodies and subqueries indented under their
own
SELECT, JOIN and its ON split, AND/OR aligned when a condition
list is long. Keyword case, literals, and comments are left exactly as written.
- HTML — one tag per line inside
head, table, and the other positions
where the HTML parser discards whitespace anyway. Elsewhere a line break only
replaces whitespace that was already there, so <b>a</b><i>b</i> stays glued
and rendering never changes. pre, textarea, script, style, and any
preserve-whitespace subtree are copied byte for byte.
- DynamoDB —
table then key, one clause per line.
A source that does not parse is reported and left untouched. Everything the
command does is available as a library:
import "github.com/shibukawa/tinybind-go/templates/templatefmt"
formatted, err := templatefmt.Source("users.tb.sql", source, templatefmt.Options{})
results, err := templatefmt.Dir("./store", templatefmt.Options{Width: 120})
templatefmt.Dir reads but never writes; each Result reports whether the file
would change and carries Write() for when you want it applied.
Template positions in generated Go
Generated Go is output, not source, so an error inside it names a file you never
wrote. -template-line-directives maps the generated code back to the template
line that produced it, using Go //line directives:
go run ./cmd/tinybind-gen generate -dir ./store -template-line-directives
A type error in a template expression then reports store/users.tb.sql:5 instead
of a line of tinybind_templates_gen.go, and every reader that honours the
directive follows: the compiler, go vet, delve, gopls, and your editor.
Generated lines that came from no template keep reporting against the generated
file.
The path written into the directive is absolute. The toolchain shortens it
against wherever you ran the command, so the same string reads as
store/users.tb.sql from the module root and ./users.tb.sql from inside the
package — and go build and go vet agree on it, which no relative form
manages. -trimpath normalises it in the binary exactly as it does any other
source path, so a release build carries yourmodule/store/users.tb.sql.
How far it reaches depends on the dialect:
- SQL — a statement is emitted as a real Go function, so a panic inside one
names the
.tb.sql file in its stack frame as well.
- HTML — compile time only. Rendering walks an instruction list inside the
shared
htmlbind coordinator, so a failing render's frames are in that
package and no directive on generated code can move them.
- DynamoDB — one mapping per declaration. The parser records a line and no
column, so there is nothing finer to map.
It is off by default, and two things are worth knowing before turning it on.
Enabling it rewrites every generated file that carries a template — with
absolute paths in it, so its bytes now depend on where the checkout lives. That
costs nothing if you keep generated Go out of version control, and misleads
every other machine if you commit it. It also grows the
mapped parts of it by roughly a third: a directive is repeated per line, because
one that is not only maps the line directly below it. Comments reach no binary,
so this is source size and nothing else. Second, a covered test run under
directives writes a profile that keeps the generated file's path while using the
mapped line numbers, so go tool cover renders against lines that do not exist
in the file it names — leave the flag off for coverage.
Taking Artifact values instead of written files? The directive that ends a
mapped span has to name the file you write it as, and only you know that name:
content := generator.ResolveTemplatePositions(artifact.Content, artifact.OutputBase+"_pw_gen.go")
Skipping that call misreports generated scaffolding and leaves every template
position intact.
Demo
go generate ./examples/demo
go run ./examples/demo
# http://localhost:8080/ index + browser stream demo
# http://localhost:8080/docs/ Swagger UI
# http://localhost:8080/chat WriteStream (SSE / NDJSON / JSON array auto)
See examples/demo/README.md for full curl recipes.
Benchmarks
Generated code has no reflection to drive and no intermediate map[string]any
to build, which is where the difference comes from. Measured on an Apple M3,
Go 1.27.0, darwin/arm64, best of 10 runs.
Each pair produces the same output: the JSON codecs are checked against
encoding/json by differential fuzzing, and the handler and template pairs are
asserted equivalent by the tests sitting beside the benchmarks. Reproduce with:
go test ./internal/benchfixture -run xxx -bench . -benchmem
Throughput
The document is a 312-byte order with a nested object, a three-element array of
objects, and a string array. The page is a five-row user list.
| Path |
Standard library |
Generated |
JSON decode (io.Reader) |
2381 ns · 1889 B · 18 allocs |
428 ns · 752 B · 4 allocs |
JSON decode (json.Unmarshal, bytes in hand) |
1753 ns · 496 B · 10 allocs |
— |
| JSON encode |
866 ns · 288 B · 2 allocs |
227 ns · 0 B · 0 allocs |
Bind + Write (request reused) |
783 ns · 1154 B · 14 allocs |
371 ns · 529 B · 6 allocs |
Bind + Write (incl. request construction) |
1601 ns · 7024 B · 28 allocs |
1140 ns · 6399 B · 20 allocs |
HTML render (html/template vs htmlbind) |
6421 ns · 2705 B · 107 allocs |
1197 ns · 72 B · 2 allocs |
The JSON comparisons are against encoding/json; the handler row against a
hand-written net/http handler doing the same decode, path, and header reads;
the HTML row against an html/template template rendering the same document.
Encoding allocates nothing: generated encoders append into a pooled buffer, so
a response costs no garbage at all. Decoding's four allocations are the two
slices in the result, the body buffer, and its reader. The document's eleven
strings come from a small cache the decoder keeps across calls, which serves a
value it has seen before rather than allocating it again; this benchmark
decodes one document repeatedly, so every string is a hit. On a stream of
documents whose values all differ, each string is allocated once as before.
The HTML render's two allocations are per render rather than per row, so a
longer page costs the same two: the bound page and its parameters, and the
writer's conversion buffer; the renderer itself comes from a pool.
Binary size
The same small JSON program built two ways, once over encoding/json and once
over generated jsonbind codecs. jsonbind does not import encoding/json at
all, so the reflection-based codec never enters the binary. Built with Go
1.26.5 and TinyGo 0.41.1; the native rows are darwin/arm64.
| Build |
encoding/json |
jsonbind |
Saved |
go build |
3,075,666 |
2,565,106 |
−511 KB (−16.6%) |
go build -ldflags="-s -w" |
2,061,138 |
1,708,034 |
−353 KB (−17.1%) |
tinygo build (native) |
474,256 |
293,632 |
−181 KB (−38.1%) |
tinygo build (native) + strip |
287,856 |
187,968 |
−100 KB (−34.7%) |
tinygo build -target wasi |
1,264,464 |
738,966 |
−525 KB (−41.6%) |
tinygo build -target wasi -no-debug |
488,762 |
222,564 |
−266 KB (−54.5%) |
Stripping makes the gap matter more, not less: once debug information is gone,
the reflection machinery is a larger share of what is left. On a stripped TinyGo
wasm build it is about half the binary.
The wasm and native rows strip differently because the debug information lives
in different places. A wasm binary embeds its DWARF, which is what -no-debug
removes; a Mach-O binary never carries it (macOS keeps DWARF in a separate
dSYM), so -no-debug changes nothing there and strip, which drops the symbol
table, is the flag's native equivalent.
encoding/json/v2
encoding/json/v2 and jsontext are stable as of Go 1.27, which this module
now declares, so the comparison compiles as it stands — the locally bumped
go.mod it used to need is no longer part of the invocation. It still sits
behind an opt-in build tag, because it measures whether v2 is worth switching
to rather than being something an ordinary go build or go test ./...
should reach:
go test ./internal/benchfixture -tags tinybind_jsonv2bench -run xxx -bench JSON -benchmem
| Path |
v1, flag off |
v1, flag on |
v2 API |
Generated |
decode (io.Reader) |
3543 ns · 1688 B · 30 |
2536 ns · 1889 B · 18 |
1650 ns · 544 B · 11 |
799 ns · 856 B · 15 |
| decode (bytes in hand) |
3352 ns · 888 B · 25 |
1871 ns · 496 B · 10 |
1525 ns · 496 B · 10 |
— |
| encode |
587 ns · 144 B · 1 |
1330 ns · 1824 B · 11 |
943 ns · 288 B · 2 |
274 ns · 0 B · 0 |
Turning the flag on and changing nothing else is a real improvement for
decoding, because the v1 API is reimplemented over v2 — but watch the encode
row, which gets 2.3× slower and allocates 12× more. The flag is not free either
way.
Generating onto jsontext, the v2 tokenizer, was the interesting option: the
same key-switch shape driven by ReadToken lands on 13 allocations with a
reused decoder — exactly what jsonbind.Parser allocates — but takes 1320 ns to
do it, and 1804 ns · 1600 B · 38 allocs when the decoder is constructed per
call, as a codec entry point would have to.
Size settles it. On the same small program, the experiment costs:
| Build |
Flag off |
Flag on |
go build |
3,075,522 |
3,887,730 (+26%) |
go build -ldflags="-s -w" |
2,061,010 |
2,598,722 (+26%) |
tinygo build -target wasi |
1,345,144 |
2,217,774 (+65%) |
tinygo build -target wasi -no-debug |
496,869 |
881,891 (+78%) |
A stripped wasm build with the experiment on is 3.5× the size of the same
program on jsonbind. For a library whose first-class target is TinyGo, that
rules v2 out as a dependency, and nothing in the speed columns argues for
carrying a second implementation behind a build tag to get it.
TinyGo
TinyGo is a first-class target for generated binding code. The JSON runtime is
kept independent of net/http so it can be used on js/wasm toolchains where
TinyGo's standard-library HTTP path is unavailable.
Verified with TinyGo 0.42.0 + Go 1.27.x.
./scripts/tinygo-check.sh
Runtime notes relevant to TinyGo
AsHTTPError avoids errors.As (unimplemented AssignableTo on some TinyGo builds).
WriteError hand-builds problem JSON (avoids fragile nested encoding/json + RawMessage interactions).
- Registry uses
reflect.Type only as a type identity key, not for field walking.
- Generated bind/write code does not import
reflect.
jsonbind parses and writes JSON itself and does not import encoding/json, so a JSON-only binary carries no reflection-based codec — around 40% of a tinygo build -target wasi binary, and about half of a -no-debug one. See Benchmarks.
- Do not import
encoding/json/v2 or jsontext into code a TinyGo build reaches. jsonbind never calls either, and the one place this repo does — internal/benchfixture, behind the tinybind_jsonv2bench build tag — measured a stripped wasi binary at 3.5× the size of the same program on jsonbind; see encoding/json/v2.
Known limitations
| Topic |
Limitation |
| Toolchain |
Project baseline is TinyGo 0.42.0 + Go 1.27.x |
| js/wasm HTTP |
Builds on the current baseline; the net/http/roundtrip_js.go compile failure seen on TinyGo 0.41.1 + Go 1.26.x is gone. jsonbind is still the smaller choice for WASM code that needs no HTTP |
| Streaming |
Prefer host go test for WriteStream; not fully TinyGo-matrixed |
| ServeMux |
DefaultOptions discovers both net/http.ServeMux and tinygodriver/httpmux.ServeMux; use httpmux for Go 1.22 method and wildcard routing under TinyGo |
Multipart File |
Supported via httpbind.File (payload); size/MIME check rules deferred. Body cap defaults to 1 MiB (SetMaxMultipartBodyBytes) |
| SQL mapping |
ScanRows and generated SQL scanners target host Go and are excluded from TinyGo builds |
| Generator |
Host-side only (go run / go test) |
License
Licensed under the Apache License, Version 2.0.