<!-- Source: https://memory.svelte.page/docs/getting-started -->

# Getting Started

> Install and configure @humanspeak/memory-cache for TypeScript apps, covering basic usage, TTL expiration, LRU eviction, and decorators quickly.

**Source:** [https://memory.svelte.page/docs/getting-started](https://memory.svelte.page/docs/getting-started)

---

@humanspeak/memory-cache is a lightweight, zero-dependency in-memory cache for TypeScript and JavaScript. It provides TTL expiration, true LRU (Least Recently Used) eviction, wildcard pattern deletion, and a powerful `@cached` decorator for method-level memoization.

## Installation

Install the package using your preferred package manager:

```bash
npm install @humanspeak/memory-cache
```

```bash
pnpm add @humanspeak/memory-cache
```

```bash
yarn add @humanspeak/memory-cache
```

## Quick Start

### Basic Cache Usage

```typescript
import { MemoryCache } from '@humanspeak/memory-cache'

// Create a cache with default options (100 entries, 5 minute TTL)
const cache = new MemoryCache<string>()

// Or customize the options
const customCache = new MemoryCache<string>({
    maxSize: 1000,        // Maximum entries before eviction
    ttl: 10 * 60 * 1000   // 10 minutes TTL
})

// Store and retrieve values
cache.set('user:123', 'John Doe')
const name = cache.get('user:123') // 'John Doe'

// Check if key exists
if (cache.has('user:123')) {
    console.log('User is cached')
}

// Delete entries
cache.delete('user:123')
cache.clear() // Remove all entries
```

### Using the @cached Decorator

The `@cached` decorator provides automatic method-level memoization:

```typescript
import { cached } from '@humanspeak/memory-cache'

class UserService {
    @cached<User>({ ttl: 60000, maxSize: 100 })
    async getUser(id: string): Promise<User> {
        // This expensive operation will be cached
        return await database.findUser(id)
    }
}

const service = new UserService()

// First call - executes the method
await service.getUser('123')

// Second call - returns cached result instantly
await service.getUser('123')
```

### Using getOrSet()

The `getOrSet()` method combines lookup and population in a single call — ideal for async caching patterns:

```typescript
const cache = new MemoryCache<User>()

// Returns cached value if it exists, otherwise calls the factory and caches the result
const user = await cache.getOrSet('user:123', async () => {
    return await database.findUser('123')
})
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `maxSize` | `number` | `100` | Maximum number of entries before eviction. Set to `0` for unlimited. |
| `ttl` | `number` | `300000` | Time-to-live in milliseconds. Set to `0` for no expiration. |
| `hooks` | `object` | — | Lifecycle hooks (`onEvict`, `onExpire`, `onSet`, `onDelete`, `onClear`) for reacting to cache events. |

## Features

- **Zero Dependencies** - No external dependencies, keeping your bundle small
- **TTL Expiration** - Entries automatically expire after a configurable time
- **LRU Eviction** - Least recently used entries are evicted when the cache is full
- **Wildcard Deletion** - Delete entries by prefix or wildcard patterns
- **Full TypeScript Support** - Complete type definitions included
- **Method Decorator** - `@cached` decorator for automatic memoization
- **Null/Undefined Support** - Properly distinguishes between cached falsy values and cache misses

## Next Steps

- Learn about the [MemoryCache API](/docs/api/memory-cache)
- Explore the [@cached decorator](/docs/api/cached-decorator)
- See [usage examples](/docs/examples)