From e9e258c255b94ee788aae7709c44745fa09a1f9c Mon Sep 17 00:00:00 2001 From: "Jeremy D. Miller" Date: Tue, 23 Jun 2026 18:33:26 -0500 Subject: [PATCH 1/2] feat: document diagnostics surface for store-agnostic consoles (#468) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enrich DocumentMappingDescriptor with the subclass list (SubClasses) and a structured PartitioningDescriptor (Strategy + PartitionNames) alongside the existing SubClassCount / PartitioningStrategy back-compat fields. Add JasperFx.Documents.IDocumentStoreDiagnostics — a store-agnostic, read-only query surface over stored documents (list types / page as JSON / fetch by id), mirroring the role IEventStore plays for event streams. Implemented by Marten and Polecat, registered in DI; consumers use the graceful-no-op pattern. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../Descriptors/DocumentMappingDescriptor.cs | 39 +++++++++++++++- .../Documents/IDocumentStoreDiagnostics.cs | 45 +++++++++++++++++++ 2 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 src/JasperFx/Documents/IDocumentStoreDiagnostics.cs diff --git a/src/JasperFx/Descriptors/DocumentMappingDescriptor.cs b/src/JasperFx/Descriptors/DocumentMappingDescriptor.cs index 3b87c09a..c94b9561 100644 --- a/src/JasperFx/Descriptors/DocumentMappingDescriptor.cs +++ b/src/JasperFx/Descriptors/DocumentMappingDescriptor.cs @@ -69,15 +69,31 @@ public class DocumentMappingDescriptor /// /// Number of subclass mappings registered against this aggregate root — /// non-zero indicates a hierarchy (doc_type column is present). + /// Retained for back-compat; carries the list. /// public int SubClassCount { get; set; } + /// + /// The subclass-mapping document types registered against this root, so a + /// console can render the hierarchy rather than just a "has subclasses" + /// hint. Empty when the type is not a hierarchy root. + /// + public TypeDescriptor[] SubClasses { get; set; } = []; + /// /// CLR type name of the IPartitionStrategy in effect, or - /// when the table is not partitioned. + /// when the table is not partitioned. Retained for + /// back-compat; carries the structured shape. /// public string? PartitioningStrategy { get; set; } + /// + /// Structured partitioning shape (strategy + declared partition names), or + /// when the table is not partitioned. Lets the + /// console render the actual partitions, not just the strategy label. + /// + public PartitioningDescriptor? Partitioning { get; set; } + /// /// Full DDL the store will generate for this document type — table /// definition, indexes, foreign keys, and any partition declarations. @@ -86,3 +102,24 @@ public class DocumentMappingDescriptor /// public string Ddl { get; set; } = ""; } + +/// +/// Structured description of a partitioned document table: the partition +/// strategy (e.g. "List", "Hash", "Range") plus the +/// declared partition names where the store can surface them. +/// +public class PartitioningDescriptor +{ + /// + /// Partition strategy label — "List", "Hash", "Range", + /// etc. Mirrors the store's partition-strategy kind as a string for + /// serialization-friendliness across version skews. + /// + public string Strategy { get; set; } = ""; + + /// + /// Declared partition names where known (e.g. per-tenant or per-range + /// partition table suffixes). Empty when the partitions are not enumerable. + /// + public string[] PartitionNames { get; set; } = []; +} diff --git a/src/JasperFx/Documents/IDocumentStoreDiagnostics.cs b/src/JasperFx/Documents/IDocumentStoreDiagnostics.cs new file mode 100644 index 00000000..42ebd7e7 --- /dev/null +++ b/src/JasperFx/Documents/IDocumentStoreDiagnostics.cs @@ -0,0 +1,45 @@ +namespace JasperFx.Documents; + +/// +/// Store-agnostic, read-only query surface over a document store's stored documents (#544 / #545, +/// JasperFx/CritterWatch). Mirrors the role JasperFx.Events.IEventStore plays for event streams: +/// it lets a monitoring console (which must not reference Marten / Polecat directly) browse, page, and +/// fetch stored documents as JSON regardless of the backing store. Implemented by Marten and Polecat +/// and registered in DI; consumers use the graceful-no-op pattern +/// (services.GetServices<IDocumentStoreDiagnostics>() is empty on a store that predates this, +/// so the feature degrades to "not available"). +/// +public interface IDocumentStoreDiagnostics +{ + /// + /// The mapped document types this store can query (CLR type name + table alias + schema), so a + /// console can populate a type picker without a separate metadata round-trip. + /// + Task> DocumentTypesAsync(CancellationToken token = default); + + /// + /// A page of documents of the named type, each as raw JSON, plus the total matching count. + /// + Task QueryDocumentsAsync( + string documentTypeName, DocumentQueryOptions options, CancellationToken token = default); + + /// + /// One document of the named type by its string id, as raw JSON, or when + /// not found. + /// + Task LoadDocumentJsonAsync( + string documentTypeName, string id, CancellationToken token = default); +} + +/// A queryable document type on a store: CLR type name, table alias, and schema. +public record DocumentTypeRef(string TypeName, string Alias, string SchemaName); + +/// +/// Options for . Paging is required; the +/// optional narrows to a single id. Room to grow simple criteria later without a +/// signature break. +/// +public record DocumentQueryOptions(int PageNumber, int PageSize, string? IdEquals = null); + +/// A page of stored documents as raw JSON, with the total matching count for pager UIs. +public record DocumentQueryResult(IReadOnlyList DocumentsJson, long TotalCount, int PageNumber, int PageSize); From cc8d4a04ae89c4196cf133bcf3cea2f1f1ef7399 Mon Sep 17 00:00:00 2001 From: "Jeremy D. Miller" Date: Tue, 23 Jun 2026 19:23:46 -0500 Subject: [PATCH 2/2] build: bump version to 2.14.0 for document-diagnostics release Co-Authored-By: Claude Opus 4.8 (1M context) --- Directory.Build.props | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Directory.Build.props b/Directory.Build.props index f4385175..0c0a2590 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -1,7 +1,7 @@ - 2.13.3 + 2.14.0 13 1570;1571;1572;1573;1574;1587;1591;1701;1702;1711;1735;0618 Jeremy D. Miller;Jaedyn Tonee