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

# Dictionary API

> `plugs/api/dictionary.ts` - Dictionary data management.

## Overview

Dictionary/config key-value storage API with standard CRUD operations.

## Endpoint

- **Root**: `dict`

## Exports

| Function | HTTP | Description |
|----------|------|-------------|
| `list` | GET | List dictionary entries with filter |
| `add` | POST | Create new dictionary entry |
| `set` | PUT | Update existing dictionary entry |
| `del` | DELETE | Delete dictionary entry |

---

## Functions

### list

```typescript
export const list = (example) => {
  return queryPage(root, example);
};
```

- **Uses**: `queryPage` from base (not `queryList`)
- **URL**: `dict`
- **Parameters**: `example` - Filter criteria (optional)
- **Returns**: Paginated result (PageResult)

---

### add

```typescript
export const add = (dictionary) => {
  return save(root, dictionary);
};
```

- **Uses**: `save` from base (POST)
- **Parameters**: `dictionary` - Dictionary entry to create

---

### set

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

- **Uses**: `update` from base (PUT)
- **Parameters**: `dictionary` - Dictionary entry to update

---

### del

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

- **Uses**: Custom implementation using `delate` directly
- **Note**: Does NOT use `deleteById` from base - passes full dictionary object
- **Difference from base pattern**: `deleteById` passes `id` as second param, but `del` passes entire object

---

## Usage Example

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

// List dictionary entries
const entries = await dictionary.list({ type: 'status' });

// Add entry
await dictionary.add({ type: 'status', label: 'Active', value: '1' });

// Update entry
await dictionary.set({ type: 'status', label: 'Active', value: '1', id: 1 });

// Delete entry
await dictionary.del({ id: 1 });
```

---

## Pattern Differences

| Aspect | Pattern Used | Explanation |
|--------|-------------|-------------|
| List | `queryPage` | Returns paginated results |
| Delete | Custom Promise | Passes full object, not just ID |

This differs from `role.ts` and `permission.ts` which use `queryList` for list and `deleteById` for delete.