Mostlylucid.Ephemeral.Atoms.Data.File 2.6.3

Mostlylucid.Ephemeral.Atoms.Data.File

File-based JSON data storage atom for signal-driven persistence. Stores each key-value pair as a separate JSON file.

Installation

dotnet add package Mostlylucid.Ephemeral.Atoms.Data.File

Quick Start

var signals = new SignalSink();

// Simple setup
await using var storage = new FileDataStorageAtom<string, Order>(
    signals,
    databaseName: "orders",
    basePath: "./data");

// Save
await storage.SaveAsync("order-123", new Order { Id = "order-123", Total = 99.99m });

// Load
var order = await storage.LoadAsync("order-123");

Configuration

var config = new FileDataStorageConfig
{
    DatabaseName = "orders",
    BasePath = "./data",              // Storage directory
    FileExtension = ".json",          // File extension
    MaxConcurrency = 1,               // Sequential writes
    EmitCompletionSignals = true,     // Emit saved.data.orders
    JsonOptions = new JsonSerializerOptions
    {
        WriteIndented = true,
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    }
};

await using var storage = new FileDataStorageAtom<string, Order>(signals, config);

Signal-Driven Usage

Atom Style

var signals = new SignalSink();
await using var storage = new FileDataStorageAtom<string, Order>(signals, "orders");

// Fire-and-forget save
storage.EnqueueSave("order-123", order);

// Listen for completion
signals.SignalRaised += signal =>
{
    if (signal.Signal.StartsWith("saved.data.orders"))
        Console.WriteLine($"Order {signal.Key} saved!");
};

Attribute Style

[EphemeralJobs(SignalPrefix = "order")]
public class OrderHandler
{
    private readonly FileDataStorageAtom<string, Order> _storage;
    private readonly SignalSink _signals;

    public OrderHandler(SignalSink signals)
    {
        _signals = signals;
        _storage = new FileDataStorageAtom<string, Order>(signals, "orders");
    }

    [EphemeralJob("created", EmitOnComplete = new[] { "order.persisted" })]
    public async Task HandleOrderCreated(SignalEvent signal, Order order)
    {
        await _storage.SaveAsync(order.Id, order);
    }

    [EphemeralJob("saved.data.orders")]  // Listen to storage completion
    public Task OnOrderSaved(SignalEvent signal)
    {
        Console.WriteLine($"Order {signal.Key} written to disk");
        return Task.CompletedTask;
    }
}

File Structure

Files are stored as:

./data/orders/
├── order-123.json
├── order-456.json
└── order-789.json

Each file contains the JSON-serialized value:

{
  "id": "order-123",
  "total": 99.99,
  "items": [...]
}

Additional Methods

// Check existence
bool exists = await storage.ExistsAsync("order-123");

// Delete
await storage.DeleteAsync("order-123");

// List all keys
foreach (var key in storage.ListKeys())
    Console.WriteLine(key);

// Clear all data
storage.Clear();

// Get storage path
Console.WriteLine(storage.StoragePath); // ./data/orders

Thread Safety

All operations are coordinated through an internal EphemeralWorkCoordinator, ensuring:

• Sequential writes by default (configurable via MaxConcurrency)
• Atomic file writes (write to temp, then move)
• Signal emission after successful operations