cache library
⚡ Jetleaf Cache & Binary Indexing Subsystem
This library provides binary caching, incremental indexing, and startup acceleration
infrastructure for Jetleaf. By caching scanned AST declarations into compact binary
artifacts (.jetleaf/cache/), subsequent application boots bypass full source scanning.
⚡ Cache Acceleration Pipeline
┌─────────────────────────────────────────────────────────────┐
│ Jetleaf Startup Flow │
├─────────────────────────────────────────────────────────────┤
│ 1. Compute Hash File timestamps & content fingerprint│
│ │ │
│ 2. Check Binary Cache .jetleaf/cache/cache_<hash>.bin │
│ │ │
│ ┌───────────── Hit ────────┴──────── Miss ───────────┐ │
│ ▼ ▼ │
│ Deserializer [BinaryReader] Full AST Scan│
│ Instant Startup (~10ms) Write Cache │
└─────────────────────────────────────────────────────────────┘
📦 Exports Categorization
💾 Serialization & Binary I/O
- CacheableSerializer — contract for serializing and deserializing cached objects.
- BinaryBuilder — low-allocation binary byte packer supporting string deduplication.
- BinaryReader — zero-copy binary parser unpacking serialized AST declarations.
🗂️ Cache Management & Scanners
- CacheableManager — orchestrates cache invalidation, pruning, and persistence.
CacheScanner— reads and writes cached metadata during build phases.- SubClassEntry — indexed hierarchy entry mapping parents to subclasses.
📁 Paths & Locations
- JetleafPaths — centralized path resolution for
.jetleaf/cache/directories.
🎯 Usage Example: Binary Serialization
import 'package:jetleaf_tools/cache.dart';
void main() {
final builder = BinaryBuilder();
// Pack structured data into binary format
builder.writeString('package:my_app/user.dart');
builder.writeBool(true);
builder.writeInt(42);
final bytes = builder.takeBytes();
print('Packed ${bytes.length} binary bytes.');
// Read back through BinaryReader
final reader = BinaryReader(bytes);
final uri = reader.readString();
final active = reader.readBool();
final count = reader.readInt();
print('Read back: $uri, active: $active, count: $count');
}
Classes
- AnnotatedMethodEntry
- A single entry representing a method annotated with a specific annotation.
- BinaryBuilder
- Builder for constructing binary data efficiently.
- BinaryReader
- Reader for parsing binary data produced by BinaryBuilder.
- CacheableManager
-
Manages the scan cache files inside
.jetleaf/. - CacheableReader
- Reads all cache data from disk.
- CacheableSerializer
-
Binary serializer for
ClassDeclarationand related cache types. - CacheableWriter
- Abstract base class for all cache writers.
- CacheDeserializationResult
- Result of deserializing a cache file.
- CacheDiff
- Describes the difference between cached file state and the current filesystem state. Used for incremental cache updates.
- CacheReadResult
- Result of reading cached data.
- CacheSummary
- Summary of what the cache writer discovered and wrote to disk.
- IndexedLibraryMeta
- A lightweight representation of a library for cache metadata.
- JetleafPaths
- Shared path construction for the Jetleaf workspace.
- RuntimeHintEntry
- A single entry representing a RuntimeHint or RuntimeHintProvider implementation.
- SubClassEntry
- A single entry in the subclass graph: maps a parent qualified name to its direct children.
Properties
- CacheManager → CacheableManager
-
Singleton instance of CacheableManager.
final
- CacheSerializer → CacheableSerializer
-
Singleton instance of CacheableSerializer.
final
Functions
-
CacheWriter(
Directory projectRoot) → CacheableWriter -
Factory function to create a
_CacheableWriter.