Fix broken persistence and improve reliability in dream_ets

[dcrockwell]

Summary

This PR fixes critical bugs in dream_ets that made persistence operations completely non-functional, improves error handling to prevent panics, and adds comprehensive documentation with verified examples.

Why These Changes Were Made

While working on documentation, we discovered that example code snippets couldn't be verified because they weren't being compiled. This led to discovering several critical issues:

1. Persistence operations were completely broken - save_to_file() and load_from_file() had never been tested and didn't work due to FFI bugs
2. Error handling violated our standards - Code was throwing away errors with Error(_) patterns and panicking on decode failures
3. Documentation taught bad practices - Examples showed Error(_) patterns users would copy into production
4. Test coverage gaps - Several public functions had zero tests, allowing bugs to ship

The root cause: untested code is broken code. The persistence operations had zero unit tests and were fundamentally broken.

What Was Changed

Critical Bug Fixes

FFI Bugs Fixed:

• save_to_file() / load_from_file(): Fixed binary/charlist conversion - Gleam Strings are binaries but Erlang file operations need charlists
• update_element(): Fixed return type from ok atom to {ok, nil} tuple
• ets_first(): Fixed return value from empty to empty_table to match type system

Error Handling Fixed:

• Removed all Error(_) patterns - now explicitly handle all error variants
• Removed panic calls from keys(), values(), to_list() helper functions
• Added proper error propagation with descriptive messages

Breaking API Changes (v1.0.2 → v2.0.0)

Four functions now return Result instead of bare values to properly handle decode errors:

• operations.keys(): List(k) → Result(List(k), EtsError)
• operations.values(): List(v) → Result(List(v), EtsError)
• operations.to_list(): List(#(k,v)) → Result(List(#(k,v)), EtsError)
• operations.size(): Int → Result(Int, EtsError)

Why this is necessary: These functions iterate the table and decode keys/values. If decode fails (corrupt data, encoder mismatch, migration issues), the old code would panic and crash the user's process. Now users can handle decode errors gracefully.

Migration is simple:

// Before (1.x):
let all_keys = operations.keys(table)

// After (2.x):
case operations.keys(table) {
  Ok(all_keys) -> use_keys(all_keys)
  Error(err) -> handle_corruption(err)
}

Documentation & Testing

Test Coverage:

• Added 15 new tests across 4 new test suites
• Increased from 62 to 77 tests (24% increase)
• Achieved 100% coverage of public API in src/dream_ets/
• Previously untested functions now have tests:
  • Persistence operations (save/load)
  • Advanced operations (update_element, match, select)
  • Encoders (bool, float)
  • Config options (keypos, bag types)

Documentation:

• World-class hexdocs for all 100+ public functions and types
• 9 tested code snippets showing realistic use cases
• Completely rewrote README with proper error handling examples
• Added custom type encoding example (JSON)
• Added preventing duplicates example (insert_new)

Impact Assessment

Who's Affected:

• Anyone using keys(), values(), to_list(), or size() needs to handle Result
• Core Dream and examples are NOT affected (verified - all tests pass)

Who Benefits:

• Everyone using persistence operations (were broken, now work)
• Anyone with custom encoders (can now handle decode errors instead of crashes)
• New users learning from documentation (now see correct patterns)

Testing

✅ dream_ets: 77 tests, 0 failures
✅ Dream core: 239 tests, 0 failures
✅ rate_limiter example: 8 integration tests, 0 failures
✅ streaming example: 6 integration tests, 0 failures

Total: 330 tests across entire codebase, all passing

Files Changed

• 57 files changed (+4000 lines, -1417 lines)
• Core modules: config.gleam, operations.gleam, helpers.gleam, encoders.gleam
• FFI: internal_ffi.erl (charlist conversions, return type fixes)
• Tests: 4 new test files, 15 new tests
• Examples: 9 new verified snippets in test/snippets/
• Docs: README.md, CHANGELOG.md, comprehensive hexdocs

Review Notes

Focus areas for review:

1. FFI changes (charlist conversion, return types) - critical bug fixes
2. Breaking API changes (Result returns) - verify this is the right approach
3. Error handling improvements (no more panics/Error(_)) - verify standards compliance

This is a significant quality improvement that fixes production-breaking bugs while maintaining backward compatibility for the most common use cases.