Improving the Projections Documentation

docs/.vitepress/config.mts

@@ -176,15 +176,22 @@ const config: UserConfig<DefaultTheme.Config> = {
               text: 'Projections Overview', link: '/events/projections/', collapsed: true, items: [
                 {
                   text: 'Aggregate Projections', link: '/events/projections/aggregate-projections', items: [
+                    { text: 'Using Conventional Methods', link: '/events/projections/conventions'},
+                    { text: 'Using Explicit Code', link: '/events/projections/explicit' },
                     { text: 'Live Aggregations', link: '/events/projections/live-aggregates' },
-                    { text: 'Multi-Stream Projections', link: '/events/projections/multi-stream-projections' },
-                    { text: 'Explicit Aggregations', link: '/events/projections/custom-aggregates' },
-                    { text: 'Reading Aggregates', link: '/events/projections/read-aggregates' }]
+                    { text: 'Single Stream Projections and Snapshots', link: '/events/projections/single-stream-projections' },
+                    { text: 'Multi Stream Projections', link: '/events/projections/multi-stream-projections' },
+                    { text: 'Reading Aggregates', link: '/events/projections/read-aggregates' },
+                    { text: 'Using Event Metadata', link: '/events/projections/using-metadata' },
+                    { text: 'Side Effects', link: '/events/projections/side-effects'},
+                    { text: 'Enriching Events', link: '/events/projections/enrichment' }
+                    ]
                 },
                 { text: 'Event Projections', link: '/events/projections/event-projections' },
                 { text: 'Custom Projections', link: '/events/projections/custom' },
                 { text: 'Inline Projections', link: '/events/projections/inline' },
                 { text: 'Flat Table Projections', link: '/events/projections/flat' },
+                { text: 'Composite or Chained Projections', link: '/events/projections/composite' },
                 { text: 'Asynchronous Projections', link: '/events/projections/async-daemon' },
                 { text: 'Testing Projections', link: '/events/projections/testing' },
                 { text: 'Rebuilding Projections', link: '/events/projections/rebuilding' },

docs/configuration/cli.md

@@ -29,28 +29,28 @@ scenarios.
 To use the expanded command line options to a .NET application, add this last line of code shown below to your `Program.cs`:
 
 <!-- snippet: sample_using_WebApplication_1 -->
-<a id='snippet-sample_using_WebApplication_1'></a>
+<a id='snippet-sample_using_webapplication_1'></a>
 ```cs
 var builder = WebApplication.CreateBuilder(args);
 
 // Easiest to just do this right after creating builder
 // Must be done before calling builder.Build() at least
 builder.Host.ApplyJasperFxExtensions();
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/samples/MinimalAPI/Program.cs#L10-L18' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_WebApplication_1' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/samples/MinimalAPI/Program.cs#L10-L18' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_webapplication_1' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 And finally, use JasperFx as the command line parser and executor by replacing `App.Run()` as the last line of code in your
 `Program.cs` file:
 
 <!-- snippet: sample_using_WebApplication_2 -->
-<a id='snippet-sample_using_WebApplication_2'></a>
+<a id='snippet-sample_using_webapplication_2'></a>
 ```cs
 // Instead of App.Run(), use the app.RunJasperFxCommands(args)
 // as the last line of your Program.cs file
 return await app.RunJasperFxCommands(args);
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/samples/MinimalAPI/Program.cs#L56-L62' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_WebApplication_2' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/samples/MinimalAPI/Program.cs#L56-L62' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_webapplication_2' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 In your command line in the project directory, you can run:

docs/configuration/ioc.md

@@ -20,7 +20,7 @@ use the `AddMarten()` method directly with Lamar as well.
 Using [Lamar](https://jasperfx.github.io/lamar) as the example container, we recommend registering Marten something like this:
 
 <!-- snippet: sample_MartenServices -->
-<a id='snippet-sample_MartenServices'></a>
+<a id='snippet-sample_martenservices'></a>
 ```cs
 public class MartenServices : ServiceRegistry
 {
@@ -49,7 +49,7 @@ public class MartenServices : ServiceRegistry
     }
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten.Testing/DevelopmentModeRegistry.cs#L8-L35' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_MartenServices' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten.Testing/DevelopmentModeRegistry.cs#L8-L35' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_martenservices' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 There are really only two key points here:

docs/configuration/json.md

@@ -232,7 +232,7 @@ Please talk to the Marten team before you undergo any significant effort to supp
 Internally, Marten uses an adapter interface for JSON serialization:
 
 <!-- snippet: sample_ISerializer -->
-<a id='snippet-sample_ISerializer'></a>
+<a id='snippet-sample_iserializer'></a>
 ```cs
 /// <summary>
 ///     When selecting data through Linq Select() transforms,
@@ -338,7 +338,7 @@ public interface ISerializer
     string ToJsonWithTypes(object document);
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/ISerializer.cs#L11-L117' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_ISerializer' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/ISerializer.cs#L11-L117' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_iserializer' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 To support a new serialization library or customize the JSON serialization options, you can write a new version of `ISerializer` and plug it

docs/configuration/multitenancy.md

@@ -267,7 +267,7 @@ It is strongly recommended that you first refer to the existing Marten options f
 The multi-tenancy strategy is pluggable. Start by implementing the `Marten.Storage.ITenancy` interface:
 
 <!-- snippet: sample_ITenancy -->
-<a id='snippet-sample_ITenancy'></a>
+<a id='snippet-sample_itenancy'></a>
 ```cs
 /// <summary>
 ///     Pluggable interface for Marten multi-tenancy by database
@@ -324,19 +324,19 @@ public interface ITenancy: IDatabaseSource, IDisposable, IDatabaseUser
     bool IsTenantStoredInCurrentDatabase(IMartenDatabase database, string tenantId);
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Storage/ITenancy.cs#L21-L78' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_ITenancy' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Storage/ITenancy.cs#L21-L78' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_itenancy' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Assuming that we have a custom `ITenancy` model:
 
 <!-- snippet: sample_MySpecialTenancy -->
-<a id='snippet-sample_MySpecialTenancy'></a>
+<a id='snippet-sample_myspecialtenancy'></a>
 ```cs
 // Make sure you implement the Dispose() method and
 // dispose all MartenDatabase objects
 public class MySpecialTenancy: ITenancy
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/MultiTenancyTests/using_per_database_multitenancy.cs#L29-L35' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_MySpecialTenancy' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/MultiTenancyTests/using_per_database_multitenancy.cs#L29-L35' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_myspecialtenancy' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 We can utilize that by applying that model at configuration time:

docs/configuration/retries.md

@@ -7,7 +7,7 @@ Marten's previous, homegrown `IRetryPolicy` mechanism was completely replaced by
 Out of the box, Marten is using [Polly.Core](https://www.pollydocs.org/) for resiliency on most operations with this setup:
 
 <!-- snippet: sample_default_Polly_setup -->
-<a id='snippet-sample_default_Polly_setup'></a>
+<a id='snippet-sample_default_polly_setup'></a>
 ```cs
 // default Marten policies
 return builder
@@ -22,7 +22,7 @@ return builder
         BackoffType = DelayBackoffType.Exponential
     });
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Util/ResilientPipelineBuilderExtensions.cs#L14-L29' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_default_Polly_setup' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Util/ResilientPipelineBuilderExtensions.cs#L14-L29' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_default_polly_setup' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The general idea is to have _some_ level of retry with an exponential backoff on typical transient errors encountered

docs/configuration/storeoptions.md

@@ -5,7 +5,7 @@ The static builder methods like `DocumentStore.For(configuration)` or `IServiceC
 syntactic sugar around building up a `StoreOptions` object and passing that to the constructor function of a `DocumentStore`:
 
 <!-- snippet: sample_DocumentStore.For -->
-<a id='snippet-sample_DocumentStore.For'></a>
+<a id='snippet-sample_documentstore.for'></a>
 ```cs
 public static DocumentStore For(Action<StoreOptions> configure)
 {
@@ -15,7 +15,7 @@ public static DocumentStore For(Action<StoreOptions> configure)
     return new DocumentStore(options);
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/DocumentStore.cs#L498-L508' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_DocumentStore.For' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/DocumentStore.cs#L498-L508' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_documentstore.for' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The major parts of `StoreOptions` are shown in the class diagram below:
@@ -83,7 +83,7 @@ to compose your document type configuration in additional `MartenRegistry` objec
 To use your own subclass of `MartenRegistry` and place declarations in the constructor function like this example:
 
 <!-- snippet: sample_OrganizationRegistry -->
-<a id='snippet-sample_OrganizationRegistry'></a>
+<a id='snippet-sample_organizationregistry'></a>
 ```cs
 public class OrganizationRegistry: MartenRegistry
 {
@@ -94,13 +94,13 @@ public class OrganizationRegistry: MartenRegistry
     }
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/MartenRegistryTests.cs#L173-L184' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_OrganizationRegistry' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/MartenRegistryTests.cs#L173-L184' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_organizationregistry' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 To apply your new `MartenRegistry`, just include it when you bootstrap the `IDocumentStore` as in this example:
 
 <!-- snippet: sample_including_a_custom_MartenRegistry -->
-<a id='snippet-sample_including_a_custom_MartenRegistry'></a>
+<a id='snippet-sample_including_a_custom_martenregistry'></a>
 ```cs
 var store = DocumentStore.For(opts =>
 {
@@ -109,7 +109,7 @@ var store = DocumentStore.For(opts =>
     opts.Connection(ConnectionSource.ConnectionString);
 });
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/MartenRegistryTests.cs#L206-L215' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_including_a_custom_MartenRegistry' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/MartenRegistryTests.cs#L206-L215' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_including_a_custom_martenregistry' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Do note that you could happily use multiple `MartenRegistry` classes in larger applications if that is advantageous.
@@ -140,7 +140,7 @@ If there's some kind of customization you'd like to use attributes for that isn'
 you're still in luck. If you write a subclass of the `MartenAttribute` shown below:
 
 <!-- snippet: sample_MartenAttribute -->
-<a id='snippet-sample_MartenAttribute'></a>
+<a id='snippet-sample_martenattribute'></a>
 ```cs
 public abstract class MartenAttribute: Attribute
 {
@@ -167,7 +167,7 @@ public abstract class MartenAttribute: Attribute
     public virtual void Register(Type discoveredType, StoreOptions options){}
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Schema/MartenAttribute.cs#L12-L39' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_MartenAttribute' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Schema/MartenAttribute.cs#L12-L39' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_martenattribute' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 And decorate either classes or individual field or properties on a document type, your custom attribute will be
@@ -178,7 +178,7 @@ As an example, an attribute to add a gin index to the JSONB storage for more eff
 would look like this:
 
 <!-- snippet: sample_GinIndexedAttribute -->
-<a id='snippet-sample_GinIndexedAttribute'></a>
+<a id='snippet-sample_ginindexedattribute'></a>
 ```cs
 [AttributeUsage(AttributeTargets.Class)]
 public class GinIndexedAttribute: MartenAttribute
@@ -189,7 +189,7 @@ public class GinIndexedAttribute: MartenAttribute
     }
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Schema/GinIndexedAttribute.cs#L10-L21' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_GinIndexedAttribute' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/Marten/Schema/GinIndexedAttribute.cs#L10-L21' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_ginindexedattribute' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ## Embedding Configuration in Document Types
@@ -199,7 +199,7 @@ and invoke that to let the document type make its own customizations for its sto
 the unit tests:
 
 <!-- snippet: sample_ConfigureMarten-generic -->
-<a id='snippet-sample_ConfigureMarten-generic'></a>
+<a id='snippet-sample_configuremarten-generic'></a>
 ```cs
 public class ConfiguresItself
 {
@@ -211,7 +211,7 @@ public class ConfiguresItself
     }
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/DocumentMappingTests.cs#L891-L903' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_ConfigureMarten-generic' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/DocumentMappingTests.cs#L891-L903' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_configuremarten-generic' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The `DocumentMapping` type is the core configuration class representing how a document type is persisted or
@@ -222,7 +222,7 @@ You can optionally take in the more specific `DocumentMapping<T>` for your docum
 some convenience methods for indexing or duplicating fields that depend on .Net Expression's:
 
 <!-- snippet: sample_ConfigureMarten-specifically -->
-<a id='snippet-sample_ConfigureMarten-specifically'></a>
+<a id='snippet-sample_configuremarten-specifically'></a>
 ```cs
 public class ConfiguresItselfSpecifically
 {
@@ -235,7 +235,7 @@ public class ConfiguresItselfSpecifically
     }
 }
 ```
-<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/DocumentMappingTests.cs#L905-L918' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_ConfigureMarten-specifically' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/marten/blob/master/src/DocumentDbTests/Configuration/DocumentMappingTests.cs#L905-L918' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_configuremarten-specifically' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ## Document Policies