noob-components/.trellis/spec/plugs-http/axios.md

# Axios (Base HTTP Client)

> Base axios wrapper with request/response interceptors.

## File

`plugs/http/axios.ts`

---

## Overview

The base HTTP client wrapper around axios. Provides a configured axios instance with request/response interceptors for loading states, error handling, and parameter cleanup.

---

## Axios Instance Configuration

```typescript
const config = {
  baseURL: process.env.VUE_APP_BASE_URL ? '/api' : '',
  timeout: 60 * 1000,
  withCredentials: true, // Check cross-site Access-Control
};

export const _axios = axios.create(config);
```

### Key Configuration Points

| Setting | Value | Purpose |
|---------|-------|---------|
| `baseURL` | `/api` or `''` | API base path, toggled by `VUE_APP_BASE_URL` env var |
| `timeout` | `60000ms` | 60 second request timeout |
| `withCredentials` | `true` | Enable cross-site Access-Control requests |

---

## Default Headers

```typescript
_axios.defaults.headers.post['Content-Type'] = 'application/json;charset=UTF-8';
_axios.defaults.headers.put['Content-Type'] = 'application/json;charset=UTF-8';
_axios.defaults.headers.delete['Content-Type'] = 'application/json;charset=UTF-8';
```

---

## Request Interceptor

Located at `plugs/http/axios.ts` lines 23-41:

```typescript
_axios.interceptors.request.use(
  function (config) {
    const time = new Date().getTime().toString();
    const params = config.params;
    if (params) {
      delEmpty(params);
      params.t = time;
    }
    const data = config.data;
    if (data != null && typeof data === 'object') {
      delEmpty(data);
      data.t = time;
    }
    return config;
  },
  function (error) {
    return Promise.reject(error);
  }
);
```

### Request Interceptor Behavior

1. Adds timestamp `t` parameter to prevent caching
2. Removes empty values (`null`, `'null'`, `''`) from params and data
3. Does NOT delete `0` or `false` values

---

## Response Interceptor

Located at `plugs/http/axios.ts` lines 57-64:

```typescript
_axios.interceptors.response.use(
  function (response) {
    return response.data;  // Returns only the data payload, not full response
  },
  function (error) {
    return Promise.reject(error);  // Passes errors to caller
  }
);
```

### Response Interceptor Behavior

- Returns `response.data` directly (strips axios wrapper)
- Forwards errors without transformation

---

## Helper Functions

### delEmpty

Removes empty values from objects:

```typescript
function delEmpty(data) {
  if (data) {
    for (const item in data) {
      if (data.hasOwnProperty(item)) {
        const val = data[item];
        if ((val == null || val == 'null' || val == '') && val !== 0) {
          delete data[item];
        }
      }
    }
  }
}
```

**Note**: Checks `val !== 0` to preserve falsy numeric values.

---

## Export Methods

| Method | Signature | Purpose |
|--------|-----------|---------|
| `post` | `(url, data?, noMsg?, noLoading?)` | POST request |
| `get` | `(url, data?, noMsg?, noLoading?)` | GET request |
| `put` | `(url, data?, noMsg?, noLoading?)` | PUT request |
| `delate` | `(url, data?, noMsg?, noLoading?)` | DELETE request (typo in name) |
| `upload` | `(file, url, data)` | File upload with FormData |
| `getFile` | `(url, data?, noMsg?, noLoading?)` | Download as blob |
| `download` | `(fileName, url, data, callBack?)` | Browser download trigger |
| `registerBaseUrl` | `(url)` | Dynamically set baseURL |

---

## Loading/Error Handling Pattern

All methods follow this pattern:

```typescript
export function post(url, data?, noMsg?, noLoading?) {
  return new Promise((resolve, reject) => {
    if (!noLoading) {
      loading();  // Show loading indicator
    }
    _axios.post(url, data).then(
      (response: any) => {
        handResponse(response, resolve, noMsg, noLoading);
      },
      (err) => {
        handError(err, reject, noMsg, noLoading);
      }
    );
  });
}
```

---

## Error Handling

### handError

```typescript
function handError(err, reject, noMsg, noLoading) {
  if (!noLoading) {
    close();
  }
  if (!noMsg) {
    showMessage('error', t('http.error'), false);
  }
  reject(err);
}
```

---

## Download Behavior

The `download` function at `plugs/http/axios.ts` lines 197-246:

1. Shows loading indicator
2. Requests as blob (`responseType: 'blob'`)
3. Parses response as text to check for error JSON
4. If error JSON found, shows error message
5. Otherwise creates Blob and triggers browser download
6. Supports IE `msSaveBlob` fallback

---

## Anti-Patterns

1. **`delate` function name** - Should be `delete` (typo)
2. **No response filtering** - Unlike axios2/axios3, does not check `response.success`
3. **Inconsistent delete** - Uses `_axios({ method: 'delete' })` instead of `_axios.delete()`