@hx-cd/services

Business service layer providing RESTful CRUD operations and cached enum/dropdown services.

Installation

pnpm add @hx-cd/services

Setup

Initialize the service config before using any services:

import { setupServiceConfig } from "@hx-cd/services";
import { FetchClient } from "@hx-cd/fetch-client";

setupServiceConfig({
  fetchClient: new FetchClient({ baseURL: "/api" }),
  getTokenParam: () => getAuthToken(), // optional
});

Exports

RestfulService

Generic CRUD base class.

import { RestfulService } from '@hx-cd/services';

class UserService extends RestfulService<UserSchema, CommonParams> {
  constructor() {
    super('users'); // base API path
  }
}

const service = new UserService();
await service.create(data);
await service.retrieve({ page: 1, limit: 10 }); // paginated
await service.all();                              // array
await service.get(id);
await service.update(id, data);
await service.delete(id);
await service.upload(file, (progress) => { ... });
await service.download(id);

Features:

• create() / retrieve() / all() / get(id) / update(id) / delete(id) — standard RESTful operations
• upload() / uploadHelper() — file upload with progress callbacks
• getDownloadUrl() / download() — build download URLs with serialized query params and token injection
• serializeDeep() — deep object-to-query-string serialization
• omitUndef() — strip undefined, empty string, and null from payloads
• withDefault() — method decorator that catches errors and returns a default value

CacheService

Extends RestfulService for cached enum/dropdown fetching.

import { CacheService } from "@hx-cd/services";

class DictService extends CacheService<DictResponse, "status" | "type", Params> {
  constructor() {
    super("dicts");
  }
}

const options = await service.getEnums();
const value = service.getValueByLabel(options, "Active");

Features:

• LRU session storage caching (capacity 20, persistence enabled)
• Request deduplication via requestingMap
• Default 30-minute cache TTL (configurable)
• Error handling with ElMessage toast

Utility Functions

import { pageQuery, queryPageTotal } from "@hx-cd/services";

const pageResult = await pageQuery<User>("/users", { page: 1 });
const total = await queryPageTotal("/users");

Types

import type { Generic, FormSelectOption, FormSelectOptions, RetrieveParam } from "@hx-cd/services";

// Generic.PageResponse<T> — { count, page, rows }
// Generic.ResponseID — string | number
// Generic.PageRequestParams — { limit, page } | { index, size } + extra fields
// FormSelectOption / FormSelectOptions — dropdown option types

Dependencies

• Runtime: @hx-cd/fetch-client, @hx-cd/utils, lodash-es

Build

pnpm build    # tsup → CJS + ESM + declarations

License

MIT