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

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

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

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

---

set

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

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

---

del

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

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.