MintPlayer.Spark 1.0.0

MintPlayer.Spark

A low-code .NET library for building data-driven web applications with minimal boilerplate. Spark uses a PersistentObject pattern to eliminate DTOs and repository layers, letting you focus on your domain logic.

Installation

dotnet add package MintPlayer.Spark

Quick Start

1. Configure Services

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSpark(builder.Configuration);
builder.Services.AddScoped<SparkContext, MySparkContext>();
builder.Services.AddSparkActions(); // Auto-discovered Actions

var app = builder.Build();

app.UseSpark();
app.SynchronizeSparkModelsIfRequested<MySparkContext>(args);
app.CreateSparkIndexes();

app.UseEndpoints(endpoints =>
{
    endpoints.MapSpark();
});

app.Run();

2. Configuration (appsettings.json)

{
  "Spark": {
    "RavenDb": {
      "Urls": ["http://localhost:8080"],
      "Database": "MyApp"
    }
  }
}

3. Define SparkContext

Create a context class that exposes your entity collections:

public class MySparkContext : SparkContext
{
    public IRavenQueryable<Person> People => Session.Query<Person>();
    public IRavenQueryable<Company> Companies => Session.Query<Company>();
}

4. Define Entities

public class Person
{
    public string? Id { get; set; }
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;

    [Reference(typeof(Company), "GetCompanies")]
    public string? Company { get; set; }

    public Address? Address { get; set; } // Nested object (AsDetail)
}

public class Address
{
    public string Street { get; set; } = string.Empty;
    public string City { get; set; } = string.Empty;
    public string ZipCode { get; set; } = string.Empty;
}

5. Synchronize Models

Run with the synchronization flag to generate JSON model files:

dotnet run --spark-synchronize-model

This creates entity definitions in App_Data/Model/ that the framework uses at runtime.

Core Concepts

PersistentObject

The universal data container that replaces traditional DTOs. Contains an ID, type name, and a collection of attributes with their values and metadata.

SparkContext

A registry pattern (similar to EF Core's DbContext) that tracks available entity types through IRavenQueryable<T> properties. The framework discovers entities by reflecting over these properties.

Actions Classes

Customization hooks for entity-specific business logic. Inherit from DefaultPersistentObjectActions<T> to add validation or custom behavior:

public class PersonActions : DefaultPersistentObjectActions<Person>
{
    public override Task OnBeforeSaveAsync(Person entity)
    {
        if (string.IsNullOrEmpty(entity.FirstName))
            throw new ValidationException("FirstName is required");
        return Task.CompletedTask;
    }

    public override Task OnAfterSaveAsync(Person entity)
    {
        // Post-save logic (notifications, logging, etc.)
        return Task.CompletedTask;
    }
}

Available hooks:

• OnQueryAsync - Customize list queries
• OnLoadAsync - Customize single entity loading
• OnSaveAsync - Customize save operation
• OnDeleteAsync - Customize delete operation
• OnBeforeSaveAsync - Pre-save validation/logic
• OnAfterSaveAsync - Post-save logic
• OnBeforeDeleteAsync - Pre-delete logic

Entity Attributes

API Endpoints

The MapSpark() extension creates these REST endpoints:

Extension Methods

JSON Model Structure

Entity Type Definition (App_Data/Model/*.json)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Person",
  "clrType": "MyApp.Data.Person",
  "displayAttribute": "FullName",
  "attributes": [
    {
      "name": "FirstName",
      "dataType": "string",
      "isRequired": true,
      "showedOn": "Query, PersistentObject"
    },
    {
      "name": "Company",
      "dataType": "Reference",
      "referenceType": "Company",
      "referenceQuery": "GetCompanies",
      "showedOn": "PersistentObject"
    }
  ]
}

Spark Query (App_Data/Queries/*.json)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "GetPeople",
  "contextProperty": "People",
  "sortBy": "LastName",
  "sortDirection": "asc"
}

Program Units (App_Data/programUnits.json)

{
  "programUnitGroups": [
    {
      "name": "Master Data",
      "icon": "bi-database",
      "programUnits": [
        {
          "id": "990e8400-e29b-41d4-a716-446655440001",
          "name": "People",
          "type": "query",
          "queryId": "550e8400-e29b-41d4-a716-446655440001"
        }
      ]
    }
  ]
}

Data Types

ShowedOn Visibility

Control where attributes appear using the showedOn property:

Index-Based Queries

For optimized list views with projections, use RavenDB indexes:

// Projection class
[FromIndex(typeof(People_Overview))]
public class VPerson
{
    public string? Id { get; set; }
    public string FullName { get; set; } = string.Empty;
    public string? CompanyName { get; set; }
}

// Index definition
public class People_Overview : AbstractIndexCreationTask<Person>
{
    public People_Overview()
    {
        Map = people => from p in people
                        let company = LoadDocument<Company>(p.Company)
                        select new VPerson
                        {
                            Id = p.Id,
                            FullName = p.FirstName + " " + p.LastName,
                            CompanyName = company != null ? company.Name : null
                        };
    }
}

Then reference the projection in your SparkContext:

public IRavenQueryable<VPerson> PeopleOverview => Session.Query<VPerson, People_Overview>();

Requirements

• .NET 10.0+
• RavenDB 6.2+

License

MIT License