---
title: "Quick Start: Get Up and Running in 5 Minutes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quick Start: Get Up and Running in 5 Minutes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

## Why SafeMapper?

When running long computations in R, the most frustrating experience is:

```
Processing 10,000 API requests...
[Completed 9847/10000]
❌ Error: Connection timeout
❌ 3 hours of work lost
❌ Must restart from scratch
```

**SafeMapper** solves this problem — it provides **drop-in replacements** for `purrr` and `furrr` functions with automatic checkpointing and recovery.

## Installation

```{r eval=FALSE}
# From r-universe (recommended)
install.packages("SafeMapper", repos = "https://zaoqu-liu.r-universe.dev")

# Or from GitHub
devtools::install_github("Zaoqu-Liu/SafeMapper")
```

## Your First Example: From purrr to SafeMapper

Load the package:

```{r}
library(SafeMapper)
```

### Traditional Approach (using purrr)

```{r eval=FALSE}
# Traditional: if interrupted, all progress is lost
library(purrr)
result <- map(1:100, function(x) {
  Sys.sleep(0.1)  # Simulate slow operation
  x^2
})
```

### The SafeMapper Way

```{r}
# SafeMapper: automatically saves progress
result <- s_map(1:20, function(x) {
  Sys.sleep(0.01)  # Simulate slow operation
  x^2
})

# View results
head(unlist(result), 10)
```

**That's it!** Just replace `map()` with `s_map()`, and your code gains fault tolerance.

## Core Features Demo

### 1. Automatic Recovery

```{r}
# First run
result1 <- s_map(1:50, ~ .x * 2, .session_id = "demo_recovery")

# If interrupted, just run the same code again to resume
# result2 <- s_map(1:50, ~ .x * 2, .session_id = "demo_recovery")
# Output: "Resuming from item XX/50"
```

### 2. Multiple Output Types

```{r}
# Return character vector
char_result <- s_map_chr(c("a", "b", "c"), toupper)
print(char_result)

# Return numeric vector
num_result <- s_map_dbl(1:5, ~ .x^2)
print(num_result)

# Return logical vector
lgl_result <- s_map_lgl(1:5, ~ .x > 3)
print(lgl_result)
```

### 3. Dual-Input Mapping

```{r}
# s_map2: process two vectors simultaneously
x <- 1:5
y <- 6:10
sums <- s_map2_dbl(x, y, ~ .x + .y)
print(sums)
```

### 4. Multi-Input Mapping

```{r}
# s_pmap: process multiple inputs
params <- list(
  a = 1:3,
  b = 4:6,
  c = 7:9
)
products <- s_pmap(params, ~ ..1 * ..2 * ..3)
print(unlist(products))
```

## Function Reference Table

| purrr/furrr | SafeMapper | Description |
|-------------|------------|-------------|
| `map()` | `s_map()` | Returns list |
| `map_chr()` | `s_map_chr()` | Returns character vector |
| `map_dbl()` | `s_map_dbl()` | Returns numeric vector |
| `map_int()` | `s_map_int()` | Returns integer vector |
| `map_lgl()` | `s_map_lgl()` | Returns logical vector |
| `map_dfr()` | `s_map_dfr()` | Returns row-bound data frame |
| `map2()` | `s_map2()` | Dual-input mapping |
| `pmap()` | `s_pmap()` | Multi-input mapping |
| `walk()` | `s_walk()` | Side effects only |
| `future_map()` | `s_future_map()` | Parallel mapping |

## Workflow Diagram

```
┌──────────────────────────────────────────────────────────────────┐
│                     SafeMapper Workflow                           │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│   Input Data ──► Generate ──► Checkpoint ──► Yes ──► Resume from │
│                  Fingerprint   Exists?              Checkpoint    │
│                                │                                  │
│                                ▼ No                               │
│                          Start Fresh                              │
│                                │                                  │
│                                ▼                                  │
│                    ┌─────────────────┐                           │
│                    │  Batch Loop     │                           │
│                    │  ┌───────────┐  │                           │
│                    │  │ Process   │  │                           │
│                    │  │   Batch   │  │                           │
│                    │  │     ↓     │  │                           │
│                    │  │   Save    │  │                           │
│                    │  │Checkpoint │  │                           │
│                    │  │     ↓     │  │                           │
│                    │  │   More?   │──┼──► No ──► Complete!       │
│                    │  └─────┬─────┘  │         Delete Checkpoint │
│                    │        │Yes     │                           │
│                    │        └────────┘                           │
│                    └─────────────────┘                           │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘
```

## Configuration (Optional)

SafeMapper works out of the box, but you can customize settings as needed:

```{r}
# Adjust batch size and retry attempts
s_configure(
  batch_size = 50,      # Save checkpoint every 50 items
  retry_attempts = 5    # Retry 5 times on failure
)
```

## Clean Old Sessions

```{r eval=FALSE}
# Clean checkpoint files older than 7 days
s_clean_sessions(older_than_days = 7)
```

## Next Steps

- 📖 [Core Concepts](core-concepts.html) - Deep dive into how SafeMapper works
- 🔧 [Map Functions](map-functions.html) - Master all mapping functions
- ⚡ [Parallel Processing](parallel-processing.html) - Speed up your computations
- 🛡️ [Error Handling](error-handling.html) - Build more robust code

## Summary

```
┌─────────────────────────────────────────────────────────────────┐
│                   SafeMapper Core Advantages                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ✅ Zero Config  ─────────► Works out of the box                │
│                                                                  │
│  ✅ Auto Recovery ────────► Just re-run to resume               │
│                                                                  │
│  ✅ Drop-in ──────────────► 100% compatible with purrr/furrr    │
│                                                                  │
│  ✅ Transparent ──────────► Auto checkpoint, no manual work     │
│                                                                  │
│  ✅ Parallel Support ─────► Full furrr compatibility            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```