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.

```typescript
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`:**
```typescript
export const list = (example) => {
  return queryPage(root, example);
};
```

---

### queryList

List query returning array.

```typescript
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`:**
```typescript
export const list = (example) => {
  return queryList(root, example);
};
```

---

### getById

Fetch single resource by ID.

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

**Behavior:**
- Resolves with `{}` when response is falsy
- Resolves with `response` directly when truthy

**Example:**
```typescript
// URL pattern: resource/id
getById('user', 123)  // GET user/123
```

---

### save

Create new resource (POST).

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

**Behavior:**
- Resolves with `response` when truthy
- Resolves with `false` on error

---

### update

Update existing resource (PUT).

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

**Behavior:**
- Resolves with `response` when truthy
- Resolves with `false` on error

---

### deleteById

Delete resource by ID.

```typescript
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.

```typescript
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

```typescript
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".