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

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

• Uses: queryList from base
• URL: buffer
• Parameters: None
• Returns: Array of buffer entries

---

clean

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

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

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

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