# Store - Memorio

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

Store provides persistent localStorage management with a simple API. Data survives page refreshes and browser restarts.

## Installation

```bash
npm install memorio
```

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

---

## Quick Examples

### Example 1: Basic Usage

```javascript
// Save data
store.set('username', 'Mario');
store.set('score', 1500);

// Read data
console.debug(store.get('username')); // "Mario"
console.debug(store.get('score'));    // 1500

// Check if using real persistence
console.debug(store.isPersistent); // true in browser, false in Node.js/Deno
```

### Example 2: Intermediate

```javascript
// Store objects
store.set('user', { name: 'Luigi', level: 5 });
const user = store.get('user');
console.debug(user.name); // "Luigi"

// Remove single item
store.remove('username');

// Check size
const totalSize = store.size();
console.debug(`${totalSize} bytes`);
```

### Example 3: Advanced

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

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

// Clear all data
store.removeAll();
// or use alias
store.clearAll();

// Handle errors gracefully
try {
  store.set('largeData', hugeObject);
} catch (err) {
  console.error('Storage full:', err);
}
```

---

## API Reference

### Methods

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

### Properties

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

### Supported Types

```javascript
// All JSON-serializable types work
store.set('string', 'hello');
store.set('number', 42);
store.set('boolean', true);
store.set('array', [1, 2, 3]);
store.set('object', { key: 'value' });
store.set('null', null);
store.set('undefined', null); // converted to null
```

### Not Supported

```javascript
// Functions will log an error
store.set('myFunc', () => {});
// Output: "It's not secure to store functions."
```

---

## Platform Comparison

| Feature | Store | Session | Cache | IDB |
|---------|-------|---------|-------|-----|
| **Storage** | localStorage | sessionStorage | Memory | IndexedDB |
| **Lifetime** | Forever | Until tab closes | Until refresh | Forever |
| **Capacity** | ~5-10 MB | ~5-10 MB | Unlimited | 50+ MB |
| **Platform** | Browser/Edge | Browser/Edge | All | Browser |
| **Persistence** | ✅ true | N/A | ❌ false | ✅ true |

---

## How It Works

Store wraps the browser's `localStorage` API with:

- Automatic JSON serialization/deserialization
- Error handling for parse failures
- Size calculation
- Quota monitoring

---

## Storage Limits

- **Chrome/Safari**: ~5-10 MB
- **Firefox**: ~10 MB
- **Edge**: ~5-10 MB

Use `store.quota()` to monitor usage.

---

## Best Practices

1. Prefix keys: `store.set('app_username', '...')`
2. Check before set: `if (store.get('key')) { ... }`
3. Handle quota: Try/catch around large data
4. Clean up: `store.removeAll()` on logout