Belljar 1.0.0

belljar.net 🫙

Conditional, mid-execution memoization for complex runtime state.

Standard tools (like IMemoryCache or PostSharp) check the cache before execution, failing completely when your logic relies on mutable state (like advancing database cursors, API paginators, or stream readers).

belljar lets you check the cache during execution.

By calling include(), you continuously update a cryptographic hash with runtime variables. If belljar detects that this specific state sequence has been processed before, execution stops immediately and the cached result is returned.

The Showcase

No boilerplate. No interfaces. No partial classes. Just an attribute and your native code.

using System.Threading.Tasks;
using Belljar;

public class LogParser
{
    @Store(".jar/logs") // Caches to disk automatically
    public async Task<string> ParseAsync(FileHandle file)
    {
        // 1. Add standard arguments to the hash
        belljar.include(file.FileName);

        // 2. Add dynamic runtime state (e.g., current cursor position)
        belljar.include(file.Position);

        // CHECKPOINT:
        // If we've processed this exact file at this exact cursor position before,
        // execution STOPS here. The IL Weaver catches the signal, safely unrolls
        // the Task state machine, and returns the JSON payload from disk.
        belljar.check();

        Console.WriteLine("Heavy processing...");
        await Task.Delay(1000);
        return file.ReadChunk();
    }
}

How It Beats Standard Caching

Features

• Mid-Execution Cache Hits: Skip the heavy lifting by bailing out of a function halfway through if the intermediate state is recognized.
• IL-Bytecode Auto-Invalidation: belljar hashes the actual compiled Intermediate Language (IL) of your method. If you change your code and recompile, the cache automatically invalidates.
• True Async/Await Support: Safely hijacks Task<T> and ValueTask<T> state machines across background threads without exploding the call stack.
• Topological Nesting: Infinite recursion support. Method A can miss while its nested Method B hits; belljar maintains perfect stack isolation.
• Atomic Persistence: Thread-safe disk caching prevents corrupted JSON reads, even when hundreds of parallel requests hit the exact same state simultaneously.

Installation

Powered by compile-time IL Weaving.

dotnet add package Belljar

(Note: Requires the .NET SDK. Powered mechanically by Rougamo IL injection).