Add scroll API. (#94) (#95)

Author: zantvoort

README.md

@@ -144,7 +144,7 @@ Storm provides a Bill of Materials (BOM) for centralized version management. Imp
         <dependency>
             <groupId>st.orm</groupId>
             <artifactId>storm-bom</artifactId>
-            <version>1.10.0</version>
+            <version>1.11.0</version>
             <type>pom</type>
             <scope>import</scope>
         </dependency>
@@ -156,7 +156,7 @@ Storm provides a Bill of Materials (BOM) for centralized version management. Imp
 
 ```kotlin
 dependencies {
-    implementation(platform("st.orm:storm-bom:1.10.0"))
+    implementation(platform("st.orm:storm-bom:1.11.0"))
 }
 ```
 
@@ -166,7 +166,7 @@ With the BOM imported, add Storm modules without specifying versions:
 
 ```kotlin
 dependencies {
-    implementation(platform("st.orm:storm-bom:1.10.0"))
+    implementation(platform("st.orm:storm-bom:1.11.0"))
     implementation("st.orm:storm-kotlin")
     runtimeOnly("st.orm:storm-core")
     // Use storm-compiler-plugin-2.0 for Kotlin 2.0.x, -2.1 for 2.1.x, etc.

docs/api-java.md

@@ -16,7 +16,7 @@ The main Java API module. It provides the `ORMTemplate` entry point, repository
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-java21</artifactId>
-    <version>1.10.0</version>
+    <version>1.11.0</version>
 </dependency>
 ```
 
@@ -44,7 +44,7 @@ Spring Framework integration for Java. Provides `RepositoryBeanFactoryPostProces
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-spring</artifactId>
-    <version>1.10.0</version>
+    <version>1.11.0</version>
 </dependency>
 ```
 
@@ -58,7 +58,7 @@ Spring Boot auto-configuration for Java. Automatically creates an `ORMTemplate`
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-spring-boot-starter</artifactId>
-    <version>1.10.0</version>
+    <version>1.11.0</version>
 </dependency>
 ```
 
@@ -83,7 +83,7 @@ The `storm-metamodel-processor` annotation processor generates type-safe metamod
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-metamodel-processor</artifactId>
-    <version>1.10.0</version>
+    <version>1.11.0</version>
     <scope>provided</scope>
 </dependency>
 ```

docs/api-kotlin.md

@@ -14,15 +14,15 @@ The main Kotlin API module. It provides the `ORMTemplate` interface, extension f
 
 ```kotlin
 // Gradle (Kotlin DSL)
-implementation("st.orm:storm-kotlin:1.10.0")
+implementation("st.orm:storm-kotlin:1.11.0")
 ```
 
 ```xml
 <!-- Maven -->
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-kotlin</artifactId>
-    <version>1.10.0</version>
+    <version>1.11.0</version>
 </dependency>
 ```
 
@@ -33,7 +33,7 @@ The Kotlin API does not depend on any preview features. All APIs are stable and
 Spring Framework integration for Kotlin. Provides `RepositoryBeanFactoryPostProcessor` for repository auto-discovery and injection, `@EnableTransactionIntegration` for bridging Storm's programmatic transactions with Spring's `@Transactional`, and transaction-aware coroutine support. Add this module when you use Spring Framework without Spring Boot.
 
 ```kotlin
-implementation("st.orm:storm-kotlin-spring:1.10.0")
+implementation("st.orm:storm-kotlin-spring:1.11.0")
 ```
 
 See [Spring Integration](spring-integration.md) for configuration details.
@@ -43,7 +43,7 @@ See [Spring Integration](spring-integration.md) for configuration details.
 Spring Boot auto-configuration for Kotlin. Automatically creates an `ORMTemplate` bean from the `DataSource`, discovers repositories, enables transaction integration, and binds `storm.*` properties from `application.yml`. This is the recommended dependency for Spring Boot applications.
 
 ```kotlin
-implementation("st.orm:storm-kotlin-spring-boot-starter:1.10.0")
+implementation("st.orm:storm-kotlin-spring-boot-starter:1.11.0")
 ```
 
 See [Spring Integration: Spring Boot Starter](spring-integration.md#spring-boot-starter) for what the starter provides and how to override its defaults.
@@ -96,7 +96,7 @@ plugins {
 }
 
 dependencies {
-    ksp("st.orm:storm-metamodel-ksp:1.10.0")
+    ksp("st.orm:storm-metamodel-ksp:1.11.0")
 }
 ```
 
@@ -115,7 +115,7 @@ dependencies {
                     <path>
                         <groupId>st.orm</groupId>
                         <artifactId>storm-metamodel-processor</artifactId>
-                        <version>1.10.0</version>
+                        <version>1.11.0</version>
                     </path>
                 </annotationProcessorPaths>
             </configuration>

docs/common-patterns.md

@@ -357,9 +357,9 @@ public class SoftDeleteGuard implements EntityCallback<Customer> {
 
 ---
 
-## Pagination
+## Pagination and Scrolling
 
-Storm provides built-in types for both offset-based and keyset-based pagination, so you do not need to define your own page wrappers or write raw `LIMIT`/`OFFSET` queries.
+Storm provides two strategies for traversing large result sets: pagination (by page number) and scrolling (by cursor). You do not need to define your own page wrappers or write raw `LIMIT`/`OFFSET` queries.
 
 ### Offset-Based Pagination
 
@@ -443,56 +443,67 @@ Page<Ref<User>> refPage = userRepository.pageRef(0, 20);
 </TabItem>
 </Tabs>
 
-### Keyset-Based Pagination
+### Scrolling
 
-Use the `slice()`, `sliceAfter()`, and `sliceBefore()` methods on any entity repository. These use a unique column value (typically the primary key) as a cursor, which lets the database seek directly to the correct position using an index.
+Use the `scroll()` method on any entity repository with a `Scrollable` that captures the cursor state. These navigate sequentially using a unique column value (typically the primary key) as a cursor, which lets the database seek directly to the correct position using an index.
 
 <Tabs groupId="language">
 <TabItem value="kotlin" label="Kotlin" default>
 
 ```kotlin
 // First page of 20 users ordered by ID
-val page1: Slice<User> = userRepository.slice(User_.id, 20)
+val window: Window<User> = userRepository.scroll(Scrollable.of(User_.id, 20))
 
-// Next page using the last ID as cursor
-val page2: Slice<User> = userRepository.sliceAfter(User_.id, page1.content.last().id, 20)
+// Next page
+if (window.hasNext()) {
+    val next: Window<User> = userRepository.scroll(window.nextScrollable())
+}
 
-// Previous page before a known cursor
-val previous: Slice<User> = userRepository.sliceBefore(User_.id, someId, 20)
+// Previous page
+if (window.hasPrevious()) {
+    val previous: Window<User> = userRepository.scroll(window.previousScrollable())
+}
 ```
 
 </TabItem>
 <TabItem value="java" label="Java">
 
 ```java
 // First page of 20 users ordered by ID
-Slice<User> page1 = userRepository.slice(User_.id, 20);
+Window<User> window = userRepository.scroll(Scrollable.of(User_.id, 20));
 
-// Next page using the last ID as cursor
-User last = page1.content().getLast();
-Slice<User> page2 = userRepository.sliceAfter(User_.id, last.id(), 20);
+// Next page
+if (window.hasNext()) {
+    Window<User> next = userRepository.scroll(window.nextScrollable());
+}
 
-// Previous page before a known cursor
-Slice<User> previous = userRepository.sliceBefore(User_.id, someId, 20);
+// Previous page
+if (window.hasPrevious()) {
+    Window<User> previous = userRepository.scroll(window.previousScrollable());
+}
 ```
 
 </TabItem>
 </Tabs>
 
-Each method returns a `Slice` containing the page content and a `hasNext` flag. See [Repositories: Keyset Pagination](repositories.md#keyset-pagination) for the full API, including sort overloads, filtering, and ref variants.
+Each method returns a `Window` containing the page content, a `hasNext` flag, and navigation tokens (`nextScrollable()`, `previousScrollable()`) for sequential traversal. For REST APIs, `Window` also provides `nextCursor()` and `previousCursor()` to serialize the scroll position as an opaque string, and `Scrollable.fromCursor(key, cursor)` to reconstruct a `Scrollable` from a cursor string. See [Repositories: Scrolling](repositories.md#scrolling) for the full API, including sort overloads, filtering, and Ref variants.
 
 ### Choosing Between the Two
 
-| Factor | Offset-Based (`page`) | Keyset-Based (`slice`) |
+| Factor | Pagination (`page`) | Scrolling (`scroll`) |
 |---|---|---|
-| Implementation complexity | Simple | Moderate |
-| Jump to arbitrary page | Yes | No (sequential only) |
+| Request type | `Pageable` | `Scrollable` |
+| Result type | `Page` | `Window` |
+| Navigation | page number | cursor |
+| Count query | yes | no |
+| Random access | yes | no |
 | Performance at page 1 | Good | Good |
 | Performance at page 1,000 | Degrades (database must skip rows) | Consistent (index seek) |
 | Handles concurrent inserts | Rows may shift between pages | Stable cursor |
-| Total element count | Included in `Page` | Not available in `Slice` |
+| Navigate forward | `page.nextPageable()` | `window.nextScrollable()` |
+| Navigate backward | `page.previousPageable()` | `window.previousScrollable()` |
 
-Use offset-based pagination when you need random page access or a total count (for example, displaying "Page 3 of 12" in a UI). Use keyset pagination when you need consistent performance over deep result sets or when the data changes frequently between requests.
+Use pagination when you need random page access or a total count (for example, displaying "Page 3 of 12" in a UI). Use scrolling when you need consistent performance over deep result sets or when the data changes frequently between requests.
 
 ---
 

docs/comparison.md

@@ -34,7 +34,7 @@ The following tables provide a side-by-side comparison of concrete features acro
 | SQL Templates | Yes | No | No | XML/Ann | Yes | Yes | No | No |
 | N+1 prevention | Yes | No | No | No | Manual | Manual | No | No |
 | Lazy loading | Refs | Yes | Yes | No | No | No | Yes | Yes |
-| Keyset pagination | Yes | No | Yes | No | Yes | No | No | No |
+| Scrolling | Yes | No | Yes | No | Yes | No | No | No |
 | JSON columns | Yes | Yes<sup>4</sup> | Via JPA | Manual | Yes | Module | Yes | Module |
 | JSON aggregation | Yes | No | No | No | Yes | No | No | No |
 

docs/configuration.md

@@ -20,6 +20,7 @@ Storm can be configured through `StormConfig`, system properties, or Spring Boot
 | `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot only) |
 | `storm.validation.strict` | `false` | Treat schema validation warnings as errors |
 | `storm.validation.interpolation_mode` | `warn` | Interpolation safety mode: `warn`, `fail`, or `none` (see [Interpolation Safety](#interpolation-safety)) |
+| `st.orm.scrollable.maxSize` | `1000` | Maximum window size allowed in a serialized cursor (system property only) |
 
 ### Setting Properties
 
@@ -490,6 +491,22 @@ record Order(@PK Integer id,
 
 ---
 
+## Scrolling Properties
+
+### st.orm.scrollable.maxSize
+
+Sets the maximum window size that a deserialized cursor (via `Scrollable.fromCursor()`) is allowed to carry. This is a safety limit that prevents untrusted clients from requesting excessively large pages through cursor manipulation. The limit is only enforced when deserializing a cursor string; programmatic usage via `Scrollable.of()` is not restricted.
+
+This property is a JVM system property only; it is not configurable through `StormConfig` or `application.yml`, because it applies at the `Scrollable` record level in storm-foundation, before any ORM template is created.
+
+```bash
+java -Dst.orm.scrollable.maxSize=5000 -jar myapp.jar
+```
+
+Repository or API layers may choose to enforce stricter per-endpoint limits on top of this framework-level bound.
+
+---
+
 ## Dirty Checking Properties
 
 These properties control how Storm detects changes to entities during update operations. Dirty checking determines whether an UPDATE statement is sent to the database and, if so, which columns it includes. Choosing the right mode depends on your entity size, update frequency, and whether you use immutable records or mutable objects. See [Dirty Checking](dirty-checking.md) for a detailed explanation of each strategy.