Update documentation

Author: helightdev

docs/.vitepress/config.mts

@@ -2,46 +2,41 @@ import {defineConfig} from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  title: "Krescent",
-  description: "Kotlin Event Sourcing Library",
-  base: '/krescent/',
-  cleanUrls: true,
-  lang: 'en-US',
-  appearance: 'dark',
-  lastUpdated: true,
-  ignoreDeadLinks: 'localhostLinks',
-  themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Guide', link: '/guide/installation' }
-    ],
-    search: {
-      provider: "local"
-    },
+    title: "Krescent",
+    description: "Kotlin Event Sourcing Library",
+    base: '/krescent/',
+    cleanUrls: true,
+    lang: 'en-US',
+    appearance: 'dark',
+    lastUpdated: true,
+    ignoreDeadLinks: 'localhostLinks',
+    themeConfig: {
+        // https://vitepress.dev/reference/default-theme-config
+        nav: [
+            {text: 'Home', link: '/'},
+            {text: 'Guide', link: '/guide/installation'}
+        ],
+        search: {
+            provider: "local"
+        },
 
-    footer: {
-      copyright: "Released under the Apache License 2.0",
-    },
+        footer: {
+            copyright: "Released under the Apache License 2.0",
+        },
 
-    sidebar: [
-      {
-        text: 'Concepts',
-        items: [
-          { text: 'Events', link: '/concepts/events' },
-          {text: 'Models', link: '/concepts/models'},
-          {text: 'Checkpointing', link: '/concepts/checkpointing'}
+        sidebar: [
+            {
+                text: 'Guide',
+                items: [
+                    {text: 'Installation', link: '/guide/installation'},
+                    {text: 'Events', link: '/guide/events'},
+                    {text: 'Models', link: '/guide/models'},
+                    {text: 'Checkpointing', link: '/guide/checkpointing'}
+                ]
+            }
+        ],
+        socialLinks: [
+            {icon: 'github', link: 'https://github.com/helightdev/krescent'}
         ]
-      },
-      {
-        text: 'Guide',
-        items: [
-          { text: 'Installation', link: '/guide/installation' },
-        ]
-      }
-    ],
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/helightdev/krescent' }
-    ]
-  }
+    }
 })

docs/concepts/checkpointing.md docs/guide/checkpointing.mddocs/concepts/checkpointing.md renamed to docs/guide/checkpointing.md

@@ -2,11 +2,34 @@
 title: Checkpointing
 ---
 
+# Checkpointing
+
 Checkpointing in Krescent is a crucial optimization mechanism for event models. Its primary purpose is to periodically
 save the current state of an event model, along with the position (e.g., `StreamingToken`) of the last event processed
 to reach that state. This avoids the need to reprocess the entire event stream from the beginning every time the model
 is initialized or restarted.
 
+### Example Configuration
+
+```kotlin
+val mongoCheckpointStorage = MongoCheckpointStorage(mongoDatabase)
+
+AllAvailableBooksReadModel(
+  collectionName = "available_books",
+  database = mongoDatabase
+).withConfiguration { // [!code focus:6]
+  useCheckpoints( // [!code ++:4]
+    mongoCheckpointStorage,
+    FixedEventRateCheckpointStrategy(25)
+  )
+}.stream(eventSource)
+```
+
+> You can configure checkpoint using the model builder api, in this example using the `withConfiguration` method.
+> All model extensions used by this model will now use the configured checkpoint storage and strategy for checkpointing.
+> Not using checkpointing will result in the model performing a full replay of the event stream every time it is
+> initialized.
+
 ## `CheckpointStrategy`
 
 A `CheckpointStrategy` determines *when* a checkpoint should be taken. Krescent offers several built-in strategies:
@@ -25,9 +48,15 @@ A `CheckpointStrategy` determines *when* a checkpoint should be taken. Krescent
 
 The `CheckpointStorage` interface defines *how* and *where* checkpoints are saved and loaded. Implementations of this
 interface are responsible for serializing the model's state and the associated `StreamingToken`, persisting them to a
-durable store (like a file system, database, or cloud storage), and retrieving them when needed.
+durable store (like a file system, database or cloud storage), and retrieving them when needed.
 
 ## `CheckpointSupport`
 
-`CheckpointSupport` is an interface that must be implemented by components (typically event models or parts of them)
-that can be checkpointed.
+`CheckpointSupport` is an interface that may be implemented by event models or model extensions to provide
+methods for creating and restoring checkpoints. Data is written to `CheckpointBuckets` which support primitive
+types, JSON objects and binary data.
+
+> [!WARNING]
+> Some model extensions may only write references to the data in the checkpoint bucket, not the actual data. When
+> deleting tables, databases, etc. related to models which are using checkpointing, make sure to also delete the
+> corresponding checkpoints if the data is referential.

docs/concepts/events.md docs/guide/events.mddocs/concepts/events.md renamed to docs/guide/events.md

@@ -2,6 +2,8 @@
 title: Events
 ---
 
+# Events
+
 Events in Krescent are immutable facts that represent something that has happened in the system. They are the primary
 building blocks of Krescent's event-driven architecture.
 
@@ -16,7 +18,7 @@ In Krescent, events can be categorized into three types:
 - **System Events**: These are just a special case of virtual events which are only emitted by the framework and usually
   represent internal state changes, notifications or stream state changes.
 
-#### Example Event Definition
+### Example Event Definitions
 
 ```kotlin
 @Serializable

docs/concepts/models.md docs/guide/models.mddocs/concepts/models.md renamed to docs/guide/models.md

@@ -2,6 +2,8 @@
 title: Models
 ---
 
+# Models
+
 Models in Krescent are the core components of the framework yet relatively loosely defined. In essence, they are
 end-user flavored event handlers with additional syntactic sugar. While there is a base `EventModelBase`, you will
 mostly
@@ -144,4 +146,85 @@ BookWriteModel("1", lockProvider).withSource(eventSource) handles { // [!code fo
 > `handles` infix function to execute the model build. This will do a transactional catchup replay from the event
 > source and then execute the specified block while still in transaction. We use this scope to execute the
 > `lend` method to create a new event and emit it to the event source. After this operation, the events will be
-> added to the event source and the transaction will be finished, freeing the lock that has been acquired.
+> added to the event source and the transaction will be finished, freeing the lock that has been acquired.
+
+## Reducing Models
+
+Krescent also provides a reduce-style syntax for models, which automatically adds serialization for
+checkpointing and enforces clearly visible state changes.
+
+### Example Reducing Read Model
+
+```kotlin
+class BooksAvailableModel() : ReducingReadModel<BooksAvailableModel.State>(
+    "book.available", 1, bookstoreEventCatalog
+) {
+    override val initialState: State
+        get() = State()
+
+    override suspend fun reduce(state: State, event: Event) = when (event) {
+        is BookAddedEvent -> state.copy(
+            available = state.available + (event.bookId to event.copies)
+        )
+        // Other events can be handled here
+        else -> state
+    }
+
+    @Serializable
+    data class State(
+        val available: Map<String, Int> = emptyMap(),
+    )
+}
+````
+
+### Example Reducing Write Model
+
+````kotlin
+class ReducingBookWriteModel(
+    val bookId: String,
+    val lockProvider: KrescentLockProvider,
+) : ReducingWriteModel<ReducingBookWriteModel.State>(
+    "test", 1, bookstoreEventCatalog,
+    configure = { useTransaction(lockProvider, "book-$bookId") }
+) {
+    override val initialState: State
+        get() = State()
+
+    override suspend fun reduce(state: State, event: Event): State {
+        if (event !is BookEvent || event.bookId != bookId) return state
+        return when (event) {
+            is BookAddedEvent -> state.copy(
+                book = BookState(
+                    title = event.title, author = event.author,
+                    price = event.price, copies = event.copies
+                ), available = event.copies
+            )
+            // Handle other events here
+            is BookLentEvent -> state.copy(available = state.available - 1)
+            is BookReturnedEvent -> state.copy(available = state.available + 1)
+            else -> state
+        }
+    }
+
+    // [!code focus:7]
+    suspend fun lend(userId: String) = useState {
+        if (canBeLent(1)) error("No book available to be lent.")
+        emitEvent(BookLentEvent(bookId, userId, "2025-1-1"))
+
+        // Use .push() to update the internal state of the model
+        state.copy(available = state.available - 1).push()
+    }
+
+    // [!code focus:4]
+    // Use useState() to access the current state of the model as "state"
+    fun canBeLent(count: Int): Boolean = useState {
+        state.available >= count
+    }
+
+    @Serializable
+    data class State(
+        val book: BookState? = null,
+        val available: Int = 0,
+    )
+}
+````