FractalDataWorks.Types.Abstractions 0.4.0-preview.6

FractalDataWorks.Types.Abstractions

TypeCollection metadata models for database persistence.

Overview

This project provides the data models for persisting TypeCollection metadata to a database. It enables dynamic discovery and querying of TypeCollections and their TypeOptions at runtime.

Purpose

Why persist TypeCollection metadata?

1. Runtime Discovery - Query available TypeCollections without assembly scanning
2. Versioning - Track TypeCollection changes over time
3. Documentation - Generate metadata reports from the database
4. Configuration - Store configuration linked to specific TypeOptions
5. Auditing - Track which TypeOptions were used in operations

Key Types

TypeCollectionMetadata

Describes a TypeCollection for database persistence:

public sealed class TypeCollectionMetadata
{
    // Unique identifier (computed from FullName via FNV-1a hash)
    public required int Id { get; init; }

    // Simple name (e.g., "FilterOperators")
    public required string Name { get; init; }

    // Full namespace-qualified name
    public required string FullName { get; init; }

    // The kind of collection
    public required CollectionKind CollectionKind { get; init; }

    // For ServiceTypeCollections, the service category
    public string? ServiceCategory { get; init; }

    // Assembly-qualified name
    public string? AssemblyQualifiedName { get; init; }

    // TypeOptions belonging to this collection
    public IReadOnlyList<TypeOptionMetadata> Options { get; init; } = [];
}

Usage:

var metadata = new TypeCollectionMetadata
{
    Id = ComputeHash("FractalDataWorks.Data.FilterOperators"),
    Name = "FilterOperators",
    FullName = "FractalDataWorks.Data.FilterOperators",
    CollectionKind = CollectionKind.TypeCollection,
    ServiceCategory = null,
    Options = [...]
};

TypeOptionMetadata

Describes a single TypeOption:

public sealed class TypeOptionMetadata
{
    // The integer ID of the TypeOption within its collection
    public required int Id { get; init; }

    // Name of the TypeOption (e.g., "Equal", "Contains")
    public required string Name { get; init; }

    // Parent TypeCollection ID
    public required int TypeCollectionId { get; init; }

    // Full type name of the TypeOption class
    public required string FullTypeName { get; init; }

    // Optional category for grouping
    public string? Category { get; init; }

    // Optional description
    public string? Description { get; init; }

    // Properties defined on this TypeOption
    public IReadOnlyList<TypePropertyMetadata> Properties { get; init; } = [];
}

Usage:

var optionMetadata = new TypeOptionMetadata
{
    Id = 1,
    Name = "Equal",
    TypeCollectionId = collectionId,
    FullTypeName = "FractalDataWorks.Data.Operators.EqualOperator",
    Category = "Comparison",
    Description = "Tests for equality"
};

TypePropertyMetadata

Describes a property on a TypeOption:

public sealed class TypePropertyMetadata
{
    // Property name
    public required string Name { get; init; }

    // CLR type name
    public required string TypeName { get; init; }

    // Is this property required?
    public bool IsRequired { get; init; }

    // Default value (if any)
    public string? DefaultValue { get; init; }

    // Optional description
    public string? Description { get; init; }
}

CollectionKind

Enum describing the kind of TypeCollection:

public enum CollectionKind
{
    TypeCollection,              // Immutable collection
    MutableTypeCollection,       // Allows runtime registration
    TypeInstanceCollection,      // Instances, not types
    ServiceTypeCollection,       // Service plugin architecture
    MutableServiceTypeCollection,
    ServiceTypeInstanceCollection
}

ITypesProvider

Interface for reading/writing TypeCollection metadata:

public interface ITypesProvider
{
    // Get all TypeCollection metadata
    Task<IGenericResult<IReadOnlyList<TypeCollectionMetadata>>> GetCollections(
        CancellationToken cancellationToken = default);

    // Get a TypeCollection by name
    Task<IGenericResult<TypeCollectionMetadata>> GetCollection(
        string name,
        CancellationToken cancellationToken = default);

    // Get all TypeOptions for a collection
    Task<IGenericResult<IReadOnlyList<TypeOptionMetadata>>> GetOptions(
        int collectionId,
        CancellationToken cancellationToken = default);

    // Persist TypeCollection metadata
    Task<IGenericResult> SaveCollection(
        TypeCollectionMetadata collection,
        CancellationToken cancellationToken = default);

    // Persist TypeOption metadata
    Task<IGenericResult> SaveOption(
        TypeOptionMetadata option,
        CancellationToken cancellationToken = default);
}

Example: Persisting TypeCollection Metadata

using FractalDataWorks.Types;
using FractalDataWorks.Types.MsSql;

// Create provider
var provider = new MsSqlTypesProvider(connectionString, logger);

// Create metadata
var collectionMetadata = new TypeCollectionMetadata
{
    Id = ComputeHash("FractalDataWorks.Schema.PropertyRoles"),
    Name = "PropertyRoles",
    FullName = "FractalDataWorks.Schema.PropertyRoles",
    CollectionKind = CollectionKind.MutableTypeCollection,
    ServiceCategory = null,
    Options = []
};

// Save collection
var result = await provider.SaveCollection(collectionMetadata, ct);

// Save TypeOptions
foreach (var role in PropertyRoles.All())
{
    var optionMetadata = new TypeOptionMetadata
    {
        Id = role.Id,
        Name = role.Name,
        TypeCollectionId = collectionMetadata.Id,
        FullTypeName = role.GetType().FullName!,
        Category = role.Category,
        Description = role.Description
    };

    await provider.SaveOption(optionMetadata, ct);
}

Example: Querying TypeCollection Metadata

// Get all TypeCollections
var collectionsResult = await provider.GetCollections(ct);
if (collectionsResult.IsSuccess)
{
    foreach (var collection in collectionsResult.Value)
    {
        Console.WriteLine($"{collection.Name} ({collection.CollectionKind})");

        var optionsResult = await provider.GetOptions(collection.Id, ct);
        if (optionsResult.IsSuccess)
        {
            foreach (var option in optionsResult.Value)
            {
                Console.WriteLine($"  - {option.Name}");
            }
        }
    }
}

Database Schema (SQL Server)

The types schema stores TypeCollection metadata:

CREATE SCHEMA types;

CREATE TABLE types.TypeCollection
(
    Id                  INT                 NOT NULL,
    Name                VARCHAR(256)        NOT NULL,
    FullName            VARCHAR(512)        NOT NULL,
    CollectionKind      VARCHAR(100)        NOT NULL,
    ServiceCategory     VARCHAR(256)        NULL,
    AssemblyName        VARCHAR(512)        NULL,
    IsCurrent           BIT                 NOT NULL    DEFAULT 1,
    CreateDate          DATETIMEOFFSET      NOT NULL    DEFAULT SYSDATETIMEOFFSET(),
    UpdateDate          DATETIMEOFFSET      NULL,

    CONSTRAINT PK_TypeCollection PRIMARY KEY (Id),
    CONSTRAINT UQ_TypeCollection_Name UNIQUE (Name)
);

CREATE TABLE types.TypeOption
(
    Id                  INT                 NOT NULL,
    TypeCollectionId    INT                 NOT NULL,
    Name                VARCHAR(256)        NOT NULL,
    FullTypeName        VARCHAR(512)        NOT NULL,
    Category            VARCHAR(256)        NULL,
    Description         VARCHAR(MAX)        NULL,
    IsCurrent           BIT                 NOT NULL    DEFAULT 1,
    CreateDate          DATETIMEOFFSET      NOT NULL    DEFAULT SYSDATETIMEOFFSET(),

    CONSTRAINT PK_TypeOption PRIMARY KEY (Id),
    CONSTRAINT FK_TypeOption_TypeCollection FOREIGN KEY (TypeCollectionId)
        REFERENCES types.TypeCollection(Id),
    CONSTRAINT UQ_TypeOption_Name UNIQUE (TypeCollectionId, Name)
);

CREATE TABLE types.TypeProperty
(
    Id                  INT                 NOT NULL    IDENTITY(1,1),
    TypeOptionId        INT                 NOT NULL,
    Name                VARCHAR(256)        NOT NULL,
    TypeName            VARCHAR(512)        NOT NULL,
    IsRequired          BIT                 NOT NULL    DEFAULT 0,
    DefaultValue        VARCHAR(MAX)        NULL,
    Description         VARCHAR(MAX)        NULL,

    CONSTRAINT PK_TypeProperty PRIMARY KEY (Id),
    CONSTRAINT FK_TypeProperty_TypeOption FOREIGN KEY (TypeOptionId)
        REFERENCES types.TypeOption(Id)
);

Use Cases

1. Dynamic Configuration UI

Generate configuration forms based on TypeCollection metadata:

var collectionsResult = await provider.GetCollections(ct);
foreach (var collection in collectionsResult.Value)
{
    RenderDropdown(collection.Name, collection.Options);
}

2. API Documentation

Generate API documentation from TypeCollection metadata:

var collections = await provider.GetCollections(ct);
GenerateOpenApiSpec(collections.Value);

3. Version Tracking

Track when TypeOptions were added or removed:

var history = await provider.GetCollectionHistory("FilterOperators", ct);
foreach (var version in history)
{
    Console.WriteLine($"Version {version.Version}: {version.Options.Count} options");
}

Dependencies

None - this is a pure data model package.

Target Framework

netstandard2.0 - Maximum compatibility.

See Also

• FractalDataWorks.Types.MsSql - SQL Server implementation of ITypesProvider
• FractalDataWorks.Collections - TypeCollection base classes
• FractalDataWorks.Collections.SourceGenerators - Source generator that produces TypeCollections