Skip to content

Commit 6257425

Browse files
committed
docs: Enhance preview method documentation for clarity and completeness
1 parent c05d3cf commit 6257425

File tree

1 file changed

+18
-11
lines changed

1 file changed

+18
-11
lines changed

docs/04-advanced-features/05-preview-and-batch.md

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,16 @@ $next = Generator::make()
3838

3939
### How It Works
4040

41-
The `preview()` method:
42-
1. Reads the current counter state
43-
2. Accounts for pending resets
44-
3. Calculates what the next number would be
45-
4. Formats and returns it
46-
5. Does NOT increment the database counter
41+
The `preview()` method is **completely read-only**:
42+
43+
1. Queries the database for existing record (no writes)
44+
2. If record doesn't exist, shows what first number would be based on `startFrom()`
45+
3. If record exists, reads current counter state
46+
4. Accounts for pending resets
47+
5. Calculates what the next number would be
48+
6. Formats and returns it
49+
7. **No database modifications** - No record creation, no transactions, no locks
50+
8. Pure read operation - safe to call anytime without side effects
4751

4852
### Use Cases
4953

@@ -358,11 +362,14 @@ $next = Generator::make()
358362

359363
### Preview Mode
360364

361-
1. **UI Displays**: Show users what their next number will be
362-
2. **Validation**: Validate forms with preview data
363-
3. **No Side Effects**: Preview doesn't affect the counter
364-
4. **Concurrent Safe**: Multiple previews don't interfere
365-
5. **Caching**: Cache preview results if needed
365+
1. **Completely Read-Only**: No database writes, no record creation, no transactions
366+
2. **UI Displays**: Show users what their next number will be
367+
3. **Validation**: Validate forms with preview data
368+
4. **No Side Effects**: Preview doesn't affect the counter or database state
369+
5. **Concurrent Safe**: Multiple previews don't interfere with each other
370+
6. **Performance**: Lightweight operation with no locking overhead
371+
7. **Caching**: Safe to cache preview results as they have no side effects
372+
8. **New Types**: Shows what first number would be for non-existent types
366373

367374
### Bulk Generation
368375

0 commit comments

Comments
 (0)