Migración a Codec Reflection-free (docs/PLAN.md)

.gitignore

@@ -0,0 +1 @@
+.env

AGENTS.md

@@ -0,0 +1,26 @@
+# TinyBin Agents Guidelines
+
+TinyBin is a high-performance binary serialization library for Go, optimized for TinyGo and resource-constrained environments.
+
+## Core Restrictions
+
+- **No `reflect`**: Do not use the `reflect` package in the core library. All serialization must be handled through the `fmt.Encodable` and `fmt.Decodable` interfaces.
+- **No `sync`**: Avoid using the `sync` package. The library should be 0-alloc and map-free, eliminating the need for complex synchronization or caching.
+- **No `map`**: Do not use the `map` type in the serialization path.
+- **No `stdlib`**: Minimize dependencies on the Go standard library, especially those that are large or not well-supported in TinyGo.
+- **WASM+Backend Agnostic**: The code must compile and run correctly on both WASM (TinyGo) and standard Go backends.
+- **0-alloc**: The `Encode` process should aim for zero allocations.
+
+## Testing and Verification
+
+- **`gotest`**: Use the `gotest` command to run tests. Do not use `go test` directly.
+- **Performance**: Always verify that changes do not introduce performance regressions or new allocations. Update `docs/BENCHMARK.md` when performance characteristics change.
+
+## Codec Contract
+
+The library follows the codec contract defined in `github.com/tinywasm/fmt`.
+
+- `EncodeFields(w fmt.FieldWriter)`: Used for serializing objects.
+- `DecodeFields(r fmt.FieldReader) error`: Used for deserializing objects.
+
+In the binary format, field names are omitted for compactness. The order of fields in `EncodeFields` must match the order in `DecodeFields`.

binary.go

@@ -3,241 +3,80 @@ package binary
 import (
 	"bytes"
 	"io"
-	"reflect"
-	"sync"
 
-	. "github.com/tinywasm/fmt"
+	"github.com/tinywasm/fmt"
 )
 
-var (
-	global *instance
-	once   sync.Once
-)
-
-// namedHandler allows types to provide a stable name for schema caching.
-// This helps avoid reflect.ValueOf() calls on every encode/decode.
-type namedHandler interface {
-	HandlerName() string
-}
-
-func getInstance() *instance {
-	once.Do(func() {
-		global = newInstance()
-	})
-	return global
-}
-
 // Encode encodes input to output.
-// input: struct or pointer to struct
+// input: Encodable struct
 // output: *[]byte or io.Writer
-func Encode(input, output any) error {
-	inst := getInstance()
+func Encode(input fmt.Encodable, output any) error {
+	if input == nil || input.IsNil() {
+		return fmt.Err("Encode: input is nil")
+	}
+
+	w := getWriter()
+	defer putWriter(w)
 
+	var err error
 	switch out := output.(type) {
 	case *[]byte:
 		var buffer bytes.Buffer
-		buffer.Grow(64)
-		if err := inst.encodeTo(input, &buffer); err == nil {
+		w.reset(&buffer)
+		input.EncodeFields(w)
+		if w.err == nil {
 			*out = buffer.Bytes()
-			return nil
-		} else {
-			return err
 		}
+		err = w.err
 	case io.Writer:
-		return inst.encodeTo(input, out)
+		w.reset(out)
+		input.EncodeFields(w)
+		err = w.err
 	default:
-		return Err("Encode", "output", "must be *[]byte or io.Writer")
+		err = fmt.Err("Encode", "output", "must be *[]byte or io.Writer")
 	}
+
+	return err
 }
 
 // Decode decodes input to output.
 // input: []byte or io.Reader
-// output: pointer to struct
+// output: pointer to Decodable struct
 func Decode(input, output any) error {
-	inst := getInstance()
-
-	switch in := input.(type) {
-	case []byte:
-		return inst.decode(in, output)
-	case io.Reader:
-		return inst.decodeFrom(in, output)
-	default:
-		return Err("Decode", "input", "must be []byte or io.Reader")
-	}
-}
-
-// SetLog sets a custom logging function for debug/testing.
-// Pass nil to disable logging.
-func SetLog(fn func(msg ...any)) {
-	getInstance().log = fn
-}
-
-// instance represents a binary encoder/decoder with isolated state.
-type instance struct {
-	// log is an optional custom logging function
-	log func(msg ...any)
-
-	// schemas is a slice-based cache for TinyGo compatibility (no maps allowed)
-	schemas []schemaEntry
-
-	// encoders is a private pool for encoder instances
-	encoders *sync.Pool
-
-	// decoders is a private pool for decoder instances
-	decoders *sync.Pool
-
-	// Mutex to protect schemas slice
-	mu sync.RWMutex
-}
-
-// schemaEntry represents a cached schema with its type and codec
-type schemaEntry struct {
-	Type  reflect.Type
-	codec codec
-	Name  string // Optional handler name
-}
-
-func newInstance(args ...any) *instance {
-	var logFunc func(msg ...any) // Default: no logging
-
-	for _, arg := range args {
-		if log, ok := arg.(func(msg ...any)); ok {
-			logFunc = log
-		}
+	if output == nil {
+		return fmt.Err("Decode: output is nil")
 	}
 
-	tb := &instance{log: logFunc}
-
-	tb.schemas = make([]schemaEntry, 0, 100) // Pre-allocate reasonable size
-	tb.encoders = &sync.Pool{
-		New: func() any {
-			return &encoder{
-				tb: tb,
-			}
-		},
+	dec, ok := output.(fmt.Decodable)
+	if !ok {
+		return fmt.Err("Decode", "output", "must implement fmt.Decodable")
 	}
-	tb.decoders = &sync.Pool{
-		New: func() any {
-			return &decoder{
-				tb: tb,
-			}
-		},
+	if dec.IsNil() {
+		return fmt.Err("Decode: output is nil")
 	}
 
-	return tb
-}
-
-// EncodeTo encodes the payload into a specific destination using this instance.
-func (tb *instance) encodeTo(data any, dst io.Writer) error {
-	// Get the encoder from the pool, reset it
-	e := tb.encoders.Get().(*encoder)
-	e.reset(dst, tb)
-
-	// Encode and set the buffer if successful
-	err := e.encode(data)
-
-	// Put the encoder back when we're finished
-	tb.encoders.Put(e)
-	return err
-}
-
-// Decode decodes the payload from the binary format using this instance.
-func (tb *instance) decode(data []byte, target any) error {
-	// Get the decoder from the pool, reset it
-	d := tb.decoders.Get().(*decoder)
-	d.reset(data, tb)
-
-	// Decode and free the decoder
-	err := d.decode(target)
-	tb.decoders.Put(d)
-	return err
-}
+	r := getReader()
+	defer putReader(r)
 
-func (tb *instance) decodeFrom(r io.Reader, target any) error {
-	// Get the decoder from the pool, reset it
-	d := tb.decoders.Get().(*decoder)
-	if d.reader == nil {
-		d.reader = newReader(r)
-	} else {
-		// If it's a slice reader, we need to replace it with a stream reader
-		if _, ok := d.reader.(*sliceReader); ok {
-			d.reader = newReader(r)
-		} else {
-			// It's already a stream reader, but we can't easily reset its inner reader
-			// because streamReader has a private field.
-			// Let's just create a new reader for now or check if we can reset it.
-			d.reader = newReader(r)
-		}
+	var err error
+	switch in := input.(type) {
+	case []byte:
+		r.reset(bytes.NewReader(in))
+		err = dec.DecodeFields(r)
+	case io.Reader:
+		r.reset(in)
+		err = dec.DecodeFields(r)
+	default:
+		err = fmt.Err("Decode", "input", "must be []byte or io.Reader")
 	}
-	d.tb = tb
 
-	// Decode and free the decoder
-	err := d.decode(target)
-	tb.decoders.Put(d)
 	return err
 }
 
-// findSchema performs a linear search in the slice-based cache for TinyGo compatibility
-func (tb *instance) findSchema(t reflect.Type) (codec, bool) {
-	tb.mu.RLock()
-	defer tb.mu.RUnlock()
-	for _, entry := range tb.schemas {
-		if entry.Type == t {
-			return entry.codec, true
-		}
-	}
-	return nil, false
-}
-
-// findSchemaByName performs a linear search in the schemas cache by handler name
-func (tb *instance) findSchemaByName(name string) (codec, reflect.Type, bool) {
-	tb.mu.RLock()
-	defer tb.mu.RUnlock()
-	for _, entry := range tb.schemas {
-		if entry.Name == name {
-			return entry.codec, entry.Type, true
-		}
-	}
-	return nil, nil, false
-}
-
-// addSchema adds a new schema to the slice-based cache
-func (tb *instance) addSchema(t reflect.Type, codec codec, name string) {
-	tb.mu.Lock()
-	defer tb.mu.Unlock()
-	// Simple cache size limit (optional, for memory control)
-	if len(tb.schemas) >= 1000 { // Reasonable default limit
-		// Simple eviction: remove oldest (first) entry
-		tb.schemas = tb.schemas[1:]
-	}
-
-	tb.schemas = append(tb.schemas, schemaEntry{
-		Type:  t,
-		codec: codec,
-		Name:  name,
-	})
-}
-
-// scanToCache scans the type and caches it in the instance using slice-based cache
-func (tb *instance) scanToCache(t reflect.Type, name string) (codec, error) {
-	if t == nil {
-		return nil, Err("scanToCache", "type", "nil")
-	}
-
-	// Double check if we already have this schema cached by type
-	// (Though callers usually check first, it's safer here)
-	if c, found := tb.findSchema(t); found {
-		return c, nil
-	}
-
-	// Scan for the first time
-	c, err := scan(t)
-	if err != nil {
-		return nil, err
-	}
-
-	// Cache the schema
-	tb.addSchema(t, c, name)
+// SetLog is deprecated and does nothing.
+func SetLog(fn func(msg ...any)) {}
 
-	return c, nil
+// Errorf is a helper for fmt.Errorf
+func Errorf(format string, a ...any) error {
+	return fmt.Errf(format, a...)
 }