Skip to content

Latest commit

 

History

History

examples

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

TONL Examples

This directory contains comprehensive, working examples for ALL TONL features with automated testing.


🚀 Quick Start

Run Feature Coverage Test (Recommended)

npm run test:features

This runs a comprehensive test suite validating all 35+ features across 5 categories!

Run Individual Examples

# 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:all

📁 Directory Structure

examples/
├── 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

📚 Examples By Feature

Core Serialization

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

Navigation & Tree Traversal

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

Schema & Validation

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

Query API

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

Modification API

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

Indexing

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

Streaming

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

Integration

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

🎯 Learning Path

Beginner (Start Here)

  1. query/01-basic-queries.ts - Learn to query data
  2. modification/01-basic-crud.ts - Learn to modify data
  3. integration/01-complete-application.ts - See it all together

Intermediate

  1. query/02-filter-expressions.ts - Master filters
  2. modification/02-transactions.ts - Safe modifications
  3. indexing/01-basic-indexing.ts - Fast lookups

Advanced

  1. streaming/01-large-files.ts - Large file processing
  2. Build your own application combining all features

✅ Example Test Matrix

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! ✅

Feature Coverage by Category

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! 🎉


🔧 Running Examples

Run Feature Coverage Test (Recommended First Step)

npm run test:features

This comprehensive test validates ALL features and gives you confidence that everything works!

Run All Examples at Once

npm run examples:all

Run Examples by Category

npm 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 processing

Run Individual Example Directly

node examples/core/01-serialization-basics.ts
node examples/query/01-basic-queries.ts
node examples/schema/01-validation-demo.ts

📖 Additional Resources

Documentation

API Reference

  • See TypeScript types and JSDoc in source code
  • IntelliSense will show all available methods
  • Check dist/*.d.ts files for type definitions

Community


🎓 Next Steps

After running these examples:

  1. Build something! - Use TONL in your project
  2. Explore the API - Check out the full documentation
  3. Try the REPL - Interactive exploration with tonl command
  4. Contribute - Found a bug or have an idea? Open an issue!

💡 Tips

  • 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! 🚀