chunk_norris

Chuck Norris doesn't wait for JSON to load. JSON loads instantly when Chuck Norris needs it.

That's exactly what this library does - it loads JSON so fast, it's almost supernatural!

Chunk Norris is a powerful Dart library for progressive JSON hydration. It allows you to work with JSON data that arrives in chunks, using placeholders that get resolved as data becomes available. Perfect for streaming APIs, Server-Sent Events, and any scenario where you need to handle partial data loading.

🚀 Features

Progressive Loading: Load JSON data incrementally as chunks arrive
Placeholder System: Use $1, $2 (or custom placeholder patterns), etc. as placeholders that get resolved dynamically
Type Safety: Strongly typed access to your data with automatic deserialization
Streaming Support: Built-in support for data streams (SSE, WebSockets, etc.)
State Management: Track loading states (pending, loaded, error) for each chunk
Flexible API: Work with raw JSON or strongly typed objects
Error Handling: Comprehensive error handling with fallback mechanisms

📦 Installation

Add this to your

pubspec.yaml

🎯 Quick Start

Basic ChunkJson Usage

Typed ChunkObject Usage

🔧 Advanced Features

Working with ChunkField

ChunkField

provides type-safe access to chunked data with built-in deserializers:

Streaming Data Processing

State Management

Error Handling

🎛️ API Reference

ChunkJson

Method	Description
`ChunkJson.fromJson(Map<String, dynamic> json)`	Create instance from JSON with placeholders
`getValue(String key)`	Get resolved value for key
`getValueAsync(String key)`	Get Future for value
`getKeyState(String key)`	Get loading state for key
`getResolvedData()`	Get fully resolved JSON
`processChunk(Map<String, dynamic> chunk)`	Process incoming chunk
`processChunkStream(Stream<String> stream)`	Process chunk stream
`waitForAllData()`	Wait for all chunks to load
`listenUpdateStream(callback)`	Listen for data updates
`allChunksResolved`	Check if all chunks are loaded
`dispose()`	Clean up resources

ChunkObject

Method	Description
`ChunkObject.fromJson(json, deserializer, {chunkFields})`	Create typed object instance
`getData()`	Get fully resolved object (throws if not ready)
`getDataOrNull()`	Get object or null if not ready
`processChunk(Map<String, dynamic> chunk)`	Process incoming chunk
`waitForData()`	Wait for all data to load
`allChunksResolved`	Check if all chunks are loaded
`getChunkField<V>(String key)`	Get typed chunk field by key
`isFieldReady(String fieldKey)`	Check if specific field is ready
`getFieldState(String fieldKey)`	Get state of specific field
`getFieldError(String fieldKey)`	Get field error (if any)
`chunkFields`	Get unmodifiable map of chunk fields

ChunkField

Property/Method	Description
`state`	Current loading state
`isResolved`	Whether field is loaded
`hasError`	Whether field has error
`value`	Get resolved value (throws if not ready)
`valueOrNull`	Get resolved value or null
`future`	Future that completes when loaded
`resolve(data)`	Resolve field with data

ChunkState

State	Description
`ChunkState.pending`	Data not yet loaded
`ChunkState.loaded`	Data successfully loaded
`ChunkState.error`	Error occurred during loading

🎨 Custom Placeholder Patterns

By default, Chunk Norris uses the pattern

$<id>

for placeholders (e.g.,

$123

$456

). You can customize this pattern by providing a custom RegExp to match your specific needs.

Using Custom Patterns

Custom Patterns with ChunkObject

Pattern Requirements

Your custom RegExp pattern must:

Include exactly one capture group () for the placeholder ID
Match the complete placeholder string (use ^ and $ anchors)
Extract a unique identifier from the first capture group

Pattern Examples

Pattern	RegExp	Matches	Extracts
Default	`^\$(\d+)$`	`$123`, `$456`	`123`, `456`
Braces	`^\{id:(\d+)\}$`	`{id:123}`, `{id:456}`	`123`, `456`
Variables	`^@var(\d+)$`	`@var123`, `@var456`	`123`, `456`
Custom	`^placeholder_(\w+)$`	`placeholder_user`, `placeholder_posts`	`user`, `posts`

🌟 Use Cases

Server-Sent Events, WebSockets (SSE, WS)

Perfect for real-time data streaming where the initial response contains a skeleton and subsequent events fill in the details.

Progressive Web Apps

Load critical data first, then enhance with additional information as it becomes available.

API Optimization

Reduce initial response times by sending partial data immediately and streaming the rest.

Data Aggregation from Multiple Sources

Combine data from different sources (databases, APIs, files) into a single unified model. Load available data immediately and fill in missing pieces as they become available from slower sources.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Remember: When Chuck Norris needs JSON data, it loads instantly. When you need JSON data, use Chunk Norris! 🥋