This directory contains comprehensive, working examples for ALL TONL features with automated testing.
npm run test:featuresThis runs a comprehensive test suite validating all 35+ features across 5 categories!
# Core serialization features
npm run examples:core
# Navigation & tree traversal
npm run examples:navigation
# Schema & validation
npm run examples:schema
# Query API
npm run examples:query
# Modification API
npm run examples:modification
# Performance & indexing
npm run examples:indexing
# Stream processing
npm run examples:streaming
# Run ALL examples
npm run examples:allexamples/
├── feature-coverage-test.ts ← 🎯 Comprehensive feature test suite
├── core/ ← Core serialization features
│ └── 01-serialization-basics.ts
├── navigation/ ← Tree traversal & navigation
│ └── 01-tree-traversal.ts
├── schema/ ← Schema & validation
│ └── 01-validation-demo.ts
├── query/ ← Query API examples
│ ├── 01-basic-queries.ts
│ └── 02-filter-expressions.ts
├── modification/ ← Modification API examples
│ ├── 01-basic-crud.ts
│ └── 02-transactions.ts
├── indexing/ ← Indexing examples
│ └── 01-basic-indexing.ts
├── streaming/ ← Streaming examples
│ └── 01-large-files.ts
└── integration/ ← Complete application examples
└── 01-complete-application.ts
01-serialization-basics.ts - Fundamental features
- Compact format with 32-50% token savings
- Human-readable output
- Perfect round-trip conversion
- Smart encoding with auto-delimiter selection
- Type hints for validation
What you'll learn:
- How TONL reduces token costs
- When to use type hints
- Delimiter selection strategies
- Token cost optimization
01-tree-traversal.ts - Navigate complex data structures
- entries() - Iterate over key-value pairs
- keys() - Get all keys at current level
- values() - Get all values
- walk() - Deep tree traversal
- Path navigation and exploration
What you'll learn:
- How to explore nested data
- Tree traversal patterns
- Path-based access
- Data structure inspection
01-validation-demo.ts - Comprehensive validation
- Schema definition with TSL (TONL Schema Language)
- All 13 constraint types
- Runtime validation
- Strict mode enforcement
- TypeScript type generation
- Validation error reporting
What you'll learn:
- Writing schema files
- Using all constraint types
- Runtime validation
- Type safety with TypeScript
01-basic-queries.ts - Learn the basics
- Simple property access
- Nested property access
- Array indexing (positive/negative)
- Path existence checking
- Type inspection
- Wildcards
- Recursive descent
02-filter-expressions.ts - Advanced filtering
- Comparison operators (>, <, >=, <=, ==, !=)
- Logical operators (&&, ||, !)
- Complex conditions
- Real-world scenarios
What you'll learn:
- How to query any data structure
- Filter syntax and operators
- Wildcard and recursive queries
- Performance characteristics
01-basic-crud.ts - CRUD operations
- CREATE: Adding new data with path creation
- READ: Querying data
- UPDATE: Modifying existing data
- DELETE: Removing data
- Method chaining
02-transactions.ts - Safe modifications
- Creating snapshots
- Tracking changes with diff()
- Rollback patterns
- Safe modification workflow
- Change auditing
What you'll learn:
- Full CRUD operation set
- Automatic path creation
- Change tracking
- Safe update patterns
- Rollback strategies
01-basic-indexing.ts - Fast lookups
- Hash index creation (O(1))
- BTree index for range queries (O(log n))
- Index management
- Performance comparison
- Statistics and monitoring
What you'll learn:
- When to use hash vs btree indices
- Index creation and management
- Performance benefits
- Memory usage
01-large-files.ts - Memory-efficient processing
- Stream query with filter/limit
- Aggregation functions
- Pipeline transformations
- Memory efficiency
- File statistics
What you'll learn:
- Processing multi-GB files
- Constant memory usage
- Aggregation patterns
- Pipeline composition
01-complete-application.ts - Real-world application
- Complete user management system
- All features working together
- Index creation for fast lookups
- CRUD operations
- Change tracking
- Atomic file saves
- Statistics and monitoring
What you'll learn:
- How to structure a real application
- Using multiple features together
- Best practices
- Production patterns
query/01-basic-queries.ts- Learn to query datamodification/01-basic-crud.ts- Learn to modify dataintegration/01-complete-application.ts- See it all together
query/02-filter-expressions.ts- Master filtersmodification/02-transactions.ts- Safe modificationsindexing/01-basic-indexing.ts- Fast lookups
streaming/01-large-files.ts- Large file processing- Build your own application combining all features
All examples have been tested and verified:
| Example | Status | Features Demonstrated |
|---|---|---|
| feature-coverage-test.ts | ✅ | All 35+ features across 5 categories |
| core/01-serialization-basics | ✅ | Compact format, round-trip, smart encoding, type hints |
| navigation/01-tree-traversal | ✅ | entries(), keys(), values(), walk(), path navigation |
| schema/01-validation-demo | ✅ | Schema definition, 13 constraints, validation, strict mode |
| query/01-basic-queries | ✅ | Simple paths, nested access, wildcards, recursive descent |
| query/02-filter-expressions | ✅ | All operators, complex conditions, real-world filters |
| modification/01-basic-crud | ✅ | Set, delete, push, pop, merge, chaining |
| modification/02-transactions | ✅ | Snapshots, diff, rollback, safe patterns |
| indexing/01-basic-indexing | ✅ | Hash (O(1)), BTree (O(log n)), compound index |
| streaming/01-large-files | ✅ | Stream query, aggregate, pipeline, memory efficiency |
| integration/01-complete-application | ✅ | All features in realistic scenario |
Result: 11/11 examples + comprehensive feature test suite! ✅
| Category | Features | Coverage | Test Script |
|---|---|---|---|
| 🎯 Core Serialization | 5 | ✅ 100% | npm run examples:core |
| 🧭 Navigation | 5 | ✅ 100% | npm run examples:navigation |
| ✅ Schema & Validation | 13 | ✅ 100% | npm run examples:schema |
| 🔍 Query & Navigation | 6 | ✅ 100% | npm run examples:query |
| ✏️ Modification | 5 | ✅ 100% | npm run examples:modification |
| ⚡ Performance & Indexing | 5 | ✅ 100% | npm run examples:indexing |
| 📊 Streaming | 3 | ✅ 100% | npm run examples:streaming |
Total: 42 features tested and verified! 🎉
npm run test:featuresThis comprehensive test validates ALL features and gives you confidence that everything works!
npm run examples:allnpm run examples:core # Core serialization
npm run examples:navigation # Tree traversal
npm run examples:schema # Schema & validation
npm run examples:query # Query API
npm run examples:modification # Modification API
npm run examples:indexing # Performance & indexing
npm run examples:streaming # Stream processingnode examples/core/01-serialization-basics.ts
node examples/query/01-basic-queries.ts
node examples/schema/01-validation-demo.ts- See TypeScript types and JSDoc in source code
- IntelliSense will show all available methods
- Check
dist/*.d.tsfiles for type definitions
After running these examples:
- Build something! - Use TONL in your project
- Explore the API - Check out the full documentation
- Try the REPL - Interactive exploration with
tonlcommand - Contribute - Found a bug or have an idea? Open an issue!
- Start with simple examples and gradually explore advanced features
- Use TypeScript for better IntelliSense and type safety
- Check console output for detailed results
- Modify examples to experiment with your own data
- Reference the main documentation for complete API details
Happy coding with TONL! 🚀