# Session - Memorio

> 🖥️ **Browser & Edge**: Uses sessionStorage for persistence
> ⚙️ **Node.js/Deno**: Falls back to in-memory storage (not persistent)

Session provides temporary storage using browser sessionStorage. Data persists until the tab or window is closed.

## Installation

```bash
npm install memorio
```

```javascript
import 'memorio';
```

---

## Quick Examples

### Example 1: Basic Usage

```javascript
// Save session data
session.set('token', 'abc123');
session.set('userId', 42);

// Read session data
console.debug(session.get('token')); // "abc123"

// Check persistence
console.debug(session.isPersistent); // true in browser, false in Node.js/Deno
```

### Example 2: Intermediate

```javascript
// Store objects
session.set('user', { name: 'Mario', role: 'admin' });

// Remove specific item
session.remove('token');

// Clear all session data
session.removeAll();
```

### Example 3: Advanced

```javascript
// Check if session has data
if (session.get('authToken')) {
  // User is logged in
}

// Get storage quota (returns Promise<[usage, quota]> in KB)
const [used, total] = await session.quota();
console.debug(`Using ${used} out of ${total} KB`);

// Get total size in characters
const size = session.size();
console.debug(`${size} bytes`);

// Handle session expiry
window.addEventListener('storage', (e) => {
  if (e.key === 'session' && !e.newValue) {
    // Session cleared
    redirectToLogin();
  }
});
```

---

## API Reference

### Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `session.get(name)` | `name: string` | `any` | Get value from session |
| `session.set(name, value)` | `name: string, value: any` | `void` | Save value to session |
| `session.remove(name)` | `name: string` | `boolean` | Remove single item |
| `session.delete(name)` | `name: string` | `boolean` | Alias for remove |
| `session.removeAll()` | `none` | `boolean` | Clear all session data |
| `session.clearAll()` | `none` | `boolean` | Alias for removeAll |
| `session.size()` | `none` | `number` | Get total size in characters |
| `session.quota()` | `none` | `Promise<[number, number]>` | Get storage usage/quota in KB |

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `session.isPersistent` | `boolean` | `true` if using real sessionStorage, `false` if in-memory fallback |

---

## Store vs Session

| Feature | Store | Session |
|---------|-------|---------|
| Storage | localStorage | sessionStorage |
| Lifetime | Forever | Until tab closes |
| Use case | User preferences | Temporary auth |
| Shared across tabs | Yes | No |
| Platform | Browser/Edge | Browser/Edge |
| Persistence | ✅ Always | ✅ Browser only |

---

## Platform Notes

| Platform | Behavior |
|----------|----------|
| Browser | Uses real sessionStorage - data persists until tab closes |
| Edge Worker | Uses real sessionStorage |
| Node.js | In-memory fallback - data lost on process restart |
| Deno | In-memory fallback - data lost on process restart |

---

## Best Practices

1. Use for auth tokens: `session.set('token', jwt)`
2. Clear on logout: `session.removeAll()`
3. Don't use for persistent data
4. Check for null: `session.get('key') || defaultValue`

---

## Common Use Cases

### Authentication

```javascript
// Login
session.set('authToken', response.token);
session.set('user', response.user);

// Logout
session.removeAll();
router.push('/login');
```

### Form Progress

```javascript
// Save form draft
session.set('formDraft', formData);

// Restore on page refresh
const draft = session.get('formDraft');
if (draft) restoreForm(draft);