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 ClassDeclaration and 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.