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

Base API Utilities

plugs/api/base.ts - Core reusable API functions.

Overview

The base module provides generic CRUD operations that other API modules build upon. All functions return Promise and handle errors gracefully by resolving with falsy values instead of rejecting.

Functions

queryPage

Paginated query with automatic empty result handling.

queryPage(url: string, example?: object, noMsg?: boolean, noLoading?: boolean): Promise<PageResult>

Behavior:

• Resolves with PageResult instance when response is falsy
• Resolves with response directly when truthy

Example from plugs/api/dictionary.ts:

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

---

queryList

List query returning array.

queryList(url: string, example?: object, noMsg?: boolean, noLoading?: boolean): Promise<any[]>

Behavior:

• Resolves with [] when response is falsy
• Resolves with response directly when truthy

Example from plugs/api/role.ts:

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

---

getById

Fetch single resource by ID.

getById(url: string, id: string | number): Promise<object>

Behavior:

• Resolves with {} when response is falsy
• Resolves with response directly when truthy

Example:

// URL pattern: resource/id
getById('user', 123)  // GET user/123

---

save

Create new resource (POST).

save(url: string, data: object): Promise<any>

Behavior:

• Resolves with response when truthy
• Resolves with false on error

---

update

Update existing resource (PUT).

update(url: string, data: object): Promise<any>

Behavior:

• Resolves with response when truthy
• Resolves with false on error

---

deleteById

Delete resource by ID.

deleteById(url: string, id: string | number): Promise<any>

Behavior:

• Uses delate (HTTP DELETE)
• Resolves with response when truthy
• Resolves with false on error

---

exportCsv

Recursive CSV export with pagination.

exportCsv(url: string, head: string[], formatter: (row: any) => string, param?: object, content?: string[]): Promise<string>

Behavior:

• Fetches pages until no more data
• Default page size: 10000
• Concatenates rows with \r\n

---

Download Utilities

downloadText(name: string, text: string): void
downloadBlob(name: string, blob: Blob): void
downloadFile(name: string, href: string): void

---

Anti-Patterns

1. Never rejects - All functions resolve, never reject on error. This makes debugging difficult.

2. Uses any - No typed responses. Consider adding TypeScript generics.

3. debugger statement - Line 114 of base.ts contains debugger; which will pause execution in browser devtools.

4. Swallows errors silently - Error cases resolve with false, [], or {} making it impossible to distinguish between "not found" and "network error".