Resource<Key, Value> class abstract interface

A generic abstraction for JetLeaf-compatible resource.

The Resource interface formalizes how key/value resource structures behave throughout the JetLeaf framework. It provides a unified contract that applies to a wide variety of resource backends—ranging from simple in-memory maps to advanced distributed or persistent stores.

Purpose

JetLeaf components such as:

• caching layers,
• rate-limit engines,
• configuration pods,
• diagnostics utilities, all rely on a consistent resource interface that behaves predictably regardless of the underlying implementation.

The Resource interface guarantees that all JetLeaf resource backends:

• Support a basic existence check via exists.
• Support value retrieval via get.
• Are generic over both stored values and keys.
• Can be wrapped, extended, decorated, or introspected by JetLeaf systems.

This interface does not dictate mutation, eviction, locking, or persistence behavior. Those capabilities are optionally introduced by more specialized interfaces such as:

• CacheResource
• RateLimitResource
• or user-defined resource classes.

Resource Characteristics

Implementations should aim to be:

🔒 Consistent

Access and lookups should be deterministic, even when concurrently used across async or parallel contexts.

🔁 Representable

Implementations are often examined or surfaced in JetLeaf diagnostics, meaning their internal structure or metadata should be representable in a stable form.

🧩 Interoperable

The abstraction enables JetLeaf to plug in different resource backends without requiring consumer-level changes.

Typical Implementations

These implementations commonly wrap a map-like structure but may use more complex distributed or persistent backends.

Example

class InMemoryUserResource implements Resource<User, String> {
  final Map<String, User> _users = {};

  @override
  bool exists(String key) => _users.containsKey(key);

  @override
  User? get(String key) => _users[key];

  void addUser(User user) => _users[user.id] = user;
}

final resource = InMemoryUserResource();
resource.addUser(User('123', 'Alice'));

print(resource.exists('123')); // → true
print(resource.get('123')?.name); // → Alice

Design Notes

JetLeaf’s architecture separates:

• resource behavior (implemented here), and
• management logic (implemented in managers such as CacheManager).

This allows resource layers to remain lightweight, independent, and easy to replace while keeping higher-level components declarative.

Related Interfaces

• CacheResource – Defines additional mutation and eviction behaviors.
• RateLimitResource – Defines atomic update semantics for rate limiting.
• StorableResource (user-defined) – Useful for external integrations.