Quick Start: Get Up and Running in 5 Minutes • SafeMapper

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

# 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:

library(SafeMapper)
#> SafeMapper: Fault-tolerant functional programming

Traditional Approach (using purrr)

# 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

# SafeMapper: automatically saves progress
result <- s_map(1:20, function(x) {
  Sys.sleep(0.01)  # Simulate slow operation
  x^2
})
#> [5%] Processing items 1-20 of 20
#> Completed 20 items

# View results
head(unlist(result), 10)
#>  [1]   1   4   9  16  25  36  49  64  81 100

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

Core Features Demo

1. Automatic Recovery

# First run
result1 <- s_map(1:50, ~ .x * 2, .session_id = "demo_recovery")
#> [2%] Processing items 1-50 of 50
#> Completed 50 items

# 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

# Return character vector
char_result <- s_map_chr(c("a", "b", "c"), toupper)
#> [33%] Processing items 1-3 of 3
#> Completed 3 items
print(char_result)
#> [1] "A" "B" "C"

# Return numeric vector
num_result <- s_map_dbl(1:5, ~ .x^2)
#> [20%] Processing items 1-5 of 5
#> Completed 5 items
print(num_result)
#> [1]  1  4  9 16 25

# Return logical vector
lgl_result <- s_map_lgl(1:5, ~ .x > 3)
#> [20%] Processing items 1-5 of 5
#> Completed 5 items
print(lgl_result)
#> [1] FALSE FALSE FALSE  TRUE  TRUE

3. Dual-Input Mapping

# s_map2: process two vectors simultaneously
x <- 1:5
y <- 6:10
sums <- s_map2_dbl(x, y, ~ .x + .y)
#> [20%] Processing items 1-5 of 5
#> Completed 5 items
print(sums)
#> [1]  7  9 11 13 15

4. Multi-Input Mapping

# s_pmap: process multiple inputs
params <- list(
  a = 1:3,
  b = 4:6,
  c = 7:9
)
products <- s_pmap(params, ~ ..1 * ..2 * ..3)
#> [33%] Processing items 1-3 of 3
#> Completed 3 items
print(unlist(products))
#> [1]  28  80 162

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:

# 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

# Clean checkpoint files older than 7 days
s_clean_sessions(older_than_days = 7)

Next Steps

📖 Core Concepts - Deep dive into how SafeMapper works
🔧 Map Functions - Master all mapping functions
⚡ Parallel Processing - Speed up your computations
🛡️ Error Handling - 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            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘