b2c-custom-caches

# B2C Custom Caches

Custom caches improve code performance by storing data that is expensive to calculate, takes a long time to retrieve, or is accessed frequently. Caches are defined in JSON files within cartridges and accessed via the Script API.

## When to Use Custom Caches

| Use Case | Example |
|----------|---------|
| Expensive calculations | Check if any variation product is on sale for base product display |
| External system responses | Cache in-store availability or prices from external APIs |
| Configuration settings | Store configuration data from JSON files or external sources |
| Frequently accessed data | Product attributes, category data, site preferences |

## Limitations

| Constraint | Value |
|------------|-------|
| Total memory per app server | ~20 MB for all custom caches |
| Max caches per code version | 100 |
| Max entry size | 128 KB |
| Supported value types | Primitives, arrays, plain objects, `null` (not `undefined`) |
| Cross-server sync | None (caches are per-application-server) |

## Defining a Custom Cache

### File Structure

```
my_cartridge/
├── package.json       # References caches.json
└── caches.json        # Cache definitions
```

### package.json

Add a `caches` entry pointing to the cache definition file:

```json
{
  "name": "my_cartridge",
  "caches": "./caches.json"
}
```

### caches.json

Define caches with unique IDs and optional expiration:

```json
{
  "caches": [
    {
      "id": "ProductAttributeCache"
    },
    {
      "id": "ExternalPriceCache",
      "expireAfterSeconds": 300
    },
    {
      "id": "SiteConfigCache",
      "expireAfterSeconds": 60
    }
  ]
}
```

| Property | Required | Description |
|----------|----------|-------------|
| `id` | Yes | Unique ID across all cartridges in code version |
| `expireAfterSeconds` | No | Maximum seconds an entry is retained |

## Using Custom Caches

### Script API Classes

| Class | Description |
|-------|-------------|
| `dw.system.CacheMgr` | Entry point for