Soenneker.Librarian.FileSystem 4.0.2

Soenneker.Librarian

Document storage for .NET 10 with interchangeable memory, JSON file, and Redis providers.

• Async document operations — store, retrieve, update, and delete JSON by ID.
• Atomic batches — update related documents together, with conditions to prevent conflicting writes.
• Typed repositories — work with document classes through ILibrarianRepository<TDocument>.
• Indexed queries — filter, sort, count, and page with LINQ or explicit async index methods.

Quick start · Providers · Queries · Typed repositories · Performance

Installation

Install the provider you need. Shared dependencies are included automatically.

dotnet add package Soenneker.Librarian.Memory
# Or: dotnet add package Soenneker.Librarian.FileSystem
# Or: dotnet add package Soenneker.Librarian.Redis

Quick start

This standalone example registers the memory provider, stores a document, and reads it back:

using Microsoft.Extensions.DependencyInjection;
using Soenneker.Librarian.Abstractions;
using Soenneker.Librarian.Memory.Registrars;

var services = new ServiceCollection();
services.AddLogging();
services.AddMemoryLibrarianDatabaseAsSingleton();

await using var provider = services.BuildServiceProvider();
var database = provider.GetRequiredService<ILibrarianDatabase>();
var users = await database.GetContainer("users");

await users.AddItem("user-1", """{"name":"Alex","age":30,"active":true}""");
string? json = await users.GetItem("user-1");

In a hosted application, register the provider on builder.Services and inject ILibrarianDatabase into your service.

Choose a provider

Register one provider for ILibrarianDatabase. Each registrar also offers an AsScoped() variant; a scoped memory database has its own data.

FileSystem

using Soenneker.Librarian.FileSystem.Registrars;

builder.Services.AddFileSystemLibrarianDatabaseAsSingleton();

Add to appsettings.json:

{
  "Librarian": {
    "FileSystem": { "FilePath": "data/librarian.json" }
  }
}

• Use one database owner per file.
• Await database.Save() when changes must be flushed explicitly.
• Dispose the database's owner asynchronously to complete shutdown persistence.

Redis

using Soenneker.Librarian.Redis.Registrars;

builder.Services.AddRedisLibrarianDatabaseAsSingleton();

Add to application configuration:

{
  "Azure": { "Redis": { "ConnectionString": "localhost:6379" } },
  "Librarian": { "Redis": { "Key": "my-app:librarian", "KeyPrefix": "librarian", "Database": -1 } }
}

• Key is the required namespace; Database is optional (-1 uses the connection default).
• Reads fetch current Redis data; writes update documents and indexes together.
• No RedisJSON, Redis Search, or Lua scripts required.
• Redis persistence and eviction settings determine durability. Use a non-evicting database for document storage.
• Cluster deployments require Redis 8 or later.

See the Redis guide for supported queries, index costs, concurrency, and deployment details.

Applications that already resolve a shared Redis database can use new RedisLibrarianDatabase(key, storeFactory) with a Func<CancellationToken, ValueTask<IDatabase>>. The caller retains connection ownership. GetServerTime() reads UTC time from the primary owning the namespace's hash slot using native Redis commands, without Lua.

Query documents

The following examples use the users container from the quick start and this model:

public sealed record User(string Name, int Age, bool Active);

LINQ

using System.Linq;

var adults = users.BuildQueryable<User>()
    .Where(user => user.Active && user.Age >= 18 && user.Age <= 65)
    .OrderBy(user => user.Age)
    .Take(25)
    .ToList();

Indexes are created automatically for supported filters and ordering, then maintained on writes. The first indexed query pays the index creation cost.

For async query execution, use the explicit index methods below.

Async index queries

await users.EnsureIndex("age");

var page = await users.FindRangeByIndex<User>(
    "age", minimum: 18, maximum: 65, skip: 0, take: 25);

var thirtyYearOlds = await users.FindByIndex<User>("age", 30, take: 10);
int count = await users.CountByIndex("age", 30);
bool exists = await users.ExistsByIndex("age", 30);

foreach (User user in page.Items)
    System.Console.WriteLine(user.Name);

• Use case-sensitive JSON field paths, such as age or address.city.
• Call EnsureIndex before explicit queries; missing indexes throw instead of scanning.
• Range bounds are inclusive; null means unbounded. skip must be nonnegative and take positive.
• Index values support strings, decimal-compatible numbers, booleans, and null. Missing fields are excluded.
• Results expose Items, Index, IndexEntriesExamined, and DocumentsDeserialized.

Document operations

All methods above are awaitable and accept a cancellation token. Document IDs are case-insensitive; container names are case-sensitive. The database owns container lifetime; use UnloadContainer() to release a container after stopping its concurrent operations.

Atomic batches

Update related documents across containers in one all-or-nothing operation with ILibrarianDatabase.Execute. Add conditions to prevent overwriting concurrent changes; if a condition fails, it returns false and applies no writes.

Available with all three providers, including coordination across application instances with Redis. See the atomic batch guide for an example, provider guarantees, and retry handling.

Typed repositories

Use LibrarianRepository<TDocument> for serialization and typed CRUD. Models must inherit from Document and have a nonempty ID when added.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
using Soenneker.Documents.Document;
using Soenneker.Librarian.Abstractions;
using Soenneker.Librarian.Core;

public sealed class Customer : Document
{
    public string Email { get; set; } = "";
}

public sealed class CustomerRepository(
    IConfiguration configuration,
    ILogger<LibrarianRepository<Customer>> logger,
    ILibrarianDatabase database)
    : LibrarianRepository<Customer>(configuration, logger, database, "customers")
{
}

Register with builder.Services.AddScoped<ILibrarianRepository<Customer>, CustomerRepository>(), then inject ILibrarianRepository<Customer>.

await repository.AddItem(new Customer { Id = "customer-1", Email = "alex@example.com" });
Customer? customer = await repository.GetItem("customer-1");

Typed repositories also expose explicit index methods. Batch additions and updates execute sequentially; they are not atomic transactions.

Performance

100,000 documents, warm indexes, .NET 10.0.12 Release. Librarian LINQ, LiteDB 5.0.21 native expression queries, and sqlite-net-pcl 1.11.285 all use in-memory storage. Query construction and execution are included. Times are medians over seven rounds.

Managed bytes allocated per operation:

SQLite native allocations are excluded. sqlite-net uses its synchronous expression API except for existence checks, which use parameterized SQL SELECT EXISTS. These measurements cover warm reads; index construction, writes, persistence, and concurrency are outside the comparison.