noob-components/.trellis/spec/plugs-api/buffer.md

# Buffer API

> `plugs/api/buffer.ts` - Buffer/state management operations.

## Overview

Buffer API for managing temporary state/cache operations. Has unique pattern - uses `set` and `del` instead of typical CRUD naming.

## Endpoint

- **Root**: `buffer`

## Exports

| Function | HTTP | Description |
|----------|------|-------------|
| `list` | GET | List buffer entries |
| `set` | PUT | Create or update buffer entry |
| `del` | DELETE | Delete buffer entry |
| `clean` | DELETE | Clear all buffer entries |

---

## Functions

### list

```typescript
export const list = () => {
  return queryList(root);
};
```

- **Uses**: `queryList` from base
- **URL**: `buffer`
- **Parameters**: None
- **Returns**: Array of buffer entries

---

### clean

```typescript
export const clean = () => {
  return new Promise((resolve, reject) => {
    delate(root).then(
      (rsp: any) => {
        if (rsp) {
          resolve(rsp);
        } else {
          resolve(false);
        }
      },
      (err) => {
        resolve(false);
      }
    );
  });
};
```

- **HTTP**: DELETE to `buffer` (no ID - clears all)
- **Custom implementation** - Does not use base `deleteById`
- **Returns**: `false` on error

---

### set

```typescript
export const set = (buffer) => {
  return update(root, buffer);
};
```

- **Uses**: `update` from base (PUT)
- **URL**: `buffer`
- **Parameters**: `buffer` - Buffer entry object
- **Note**: PUT to root (not root + id) - creates or updates entire buffer entry

---

### del

```typescript
export const del = (buffer) => {
  return deleteById(root, buffer.key);
};
```

- **Uses**: `deleteById` from base (DELETE)
- **ID Field**: `buffer.key` (string key, not numeric ID)
- **Note**: Uses `key` field for identification

---

## Usage Example

```typescript
import { buffer } from 'plugs/api';

// List all buffer entries
const entries = await buffer.list();

// Set/update buffer entry
await buffer.set({ key: 'userPrefs', value: { theme: 'dark' } });

// Delete specific entry
await buffer.del({ key: 'userPrefs' });

// Clear all entries
await buffer.clean();
```

---

## Pattern Differences

| Aspect | This API | Typical Pattern |
|--------|----------|-----------------|
| Update/Create | `set` | `save` or `update` |
| Delete | Uses `buffer.key` | Uses numeric `id` |
| Clear all | `clean()` custom | Not typical |

---

## Anti-Patterns

1. **`delate` vs `delete`** - Uses typo'd `delate` throughout
2. **`set` for create/update** - Inconsistent with other APIs using `save`/`add`
3. **`clean` is non-standard** - DELETE to root without ID is unusual
4. **No `add`** - Only `list`, `set`, `del`, `clean` - no explicit create