Add comprehensive unit tests and improve example documentation

[llbbl]

Summary

This PR significantly improves the test coverage and documentation for libsql-client-go by adding comprehensive unit tests and enhancing the examples.

Changes

Test Coverage Improvements

Added extensive unit tests across multiple packages, bringing coverage from near-zero to production-ready levels:

Package	Before	After	Improvement
libsql	0.0%	80.6%	+80.6% ✅
libsql/internal/hrana	57.3%	79.0%	+21.7% ✅
libsql/internal/http/hranaV2	0.0%	42.6%	+42.6% ✅
libsql/internal/http/shared	20.4%	94.2%	+73.8% ✅

New Test Files

1. libsql/sql_test.go (737 lines)

   • Tests for NewConnector with various URL schemes and options
   • All option functions (WithAuthToken, WithTls, WithProxy, WithSchemaDb)
   • URL parsing and validation logic
   • TLS configuration handling
   • Helper functions (Contains, Index, extractJwt, extractTls)
   • Driver registration verification

2. libsql/internal/http/shared/params_test.go (470 lines)

   • Parameter conversion (positional/named)
   • Statement parsing and argument handling
   • ParseStatement and ParseStatementAndArgs functions
   • EXPLAIN statement detection
   • Params struct methods (Len, MarshalJSON, Type)

3. libsql/internal/http/shared/result_test.go (71 lines)

   • Result interface implementation
   • LastInsertId and RowsAffected methods

4. libsql/internal/http/shared/rows_test.go (305 lines)

   • Rows iteration and navigation
   • Multiple result sets handling
   • Error handling in result sets

5. libsql/internal/http/hranaV2/hranaV2_test.go (617 lines)

   • Connection initialization
   • Statement preparation with different parameter types
   • Transaction options validation
   • Statement chunking for large queries
   • Replication index handling
   • Rows provider implementations

6. libsql/internal/hrana/stream_request_test.go (238 lines)

   • Stream request creation (ExecuteStream, BatchStream, etc.)
   • Stored SQL operations
   • Batch operations with conditions

7. libsql/internal/hrana/batch_test.go (128 lines)

   • Batch step management
   • Batch condition types (ok, error, not, and, or)

Total Test Coverage

• 140+ test cases added
• 2,876 lines of test code
• All tests passing ✅

Documentation Improvements

Enhanced Example Code (examples/sql/counter/main.go)

• Added comprehensive package documentation
• Detailed function-level comments for all helper functions
• Inline comments explaining:
  • All 5 parameter binding styles (?, ?N, :name, @name, $name)
  • Why indexed parameters are useful (parameter reuse)
  • Transaction rollback handling
  • SQLite quirks and best practices
  • Concurrent access patterns
• Progress output for better user experience

New Examples README (examples/README.md)

Comprehensive guide covering:

• Prerequisites and setup instructions
• How to run examples with both local files and remote servers
• Feature demonstrations with code snippets for:
  • All parameter binding styles
  • Prepared statements
  • Transactions
  • Concurrent access
• Connection string formats for all supported schemes
• Turso integration example with authentication
• Troubleshooting section
• Contributing guidelines

Testing

All new tests pass successfully:

go test ./libsql/...

Coverage reports are available via:

go test -cover ./libsql/...

Benefits

1. Improved Reliability: Core functionality now has comprehensive test coverage
2. Better Developer Experience: Clear examples and documentation for new users
3. Regression Prevention: Tests catch breaking changes before they reach production
4. Easier Onboarding: Well-documented examples demonstrate best practices
5. CI/CD Integration: Tests run automatically on all PRs via GitHub Actions

Checklist

• Added unit tests with 80%+ coverage for critical packages
• All tests pass locally
• Enhanced example code with detailed comments
• Created comprehensive examples README
• No breaking changes to existing APIs
• Documentation is clear and helpful for new users

[llbbl]

Just trying to help add some tests. 🕊