Application Data Service

A TypeScript library providing a hierarchical set of classes for handling data operations via HTTP requests. Built with a foundation of BaseDataService and specialized services for common data operations including CRUD, full list retrieval, and paginated search functionality.

中文 | English

Installation

npm install @ticatec/app-data-service

Prerequisites

This library requires a REST service implementation. The recommended implementation is:

npm install @ticatec/axios-restful-service

Quick Start

import { BaseDataService, FullListDataService } from '@ticatec/app-data-service';
import RestService from '@ticatec/axios-restful-service';

// Configure the REST proxy
const restService = new RestService('https://api.example.com');
BaseDataService.setProxy(restService);

// Create a service for your data
class UserService extends FullListDataService {
  constructor() {
    super('/users');
  }
}

const userService = new UserService();
const users = await userService.getList();

Architecture Overview

The library follows a hierarchical architecture:

BaseDataService (Abstract)
├── CommonDataService (Abstract)
    ├── FullListDataService (Concrete)
    └── PagingDataService (Concrete)

• BaseDataService: Foundation class providing HTTP methods and proxy management
• CommonDataService: Adds CRUD operations with URL-based endpoints
• FullListDataService: Specialized for retrieving complete lists
• PagingDataService: Adds pagination and search capabilities

API Reference

BaseDataService

Abstract base class providing foundational HTTP request methods and static proxy management.

Static Methods

setProxy(value: RestService): void

Configures the HTTP client proxy for all data service instances.

import RestService from '@ticatec/axios-restful-service';
const restService = new RestService('https://api.example.com');
BaseDataService.setProxy(restService);

Protected Methods

get service(): RestService

Getter for accessing the configured REST service proxy.

getService(): RestService

Alternative method for accessing the REST service proxy.

async get(url: string, params?: any, dataProcessor?: any): Promise<any>

Sends an HTTP GET request.

• url: The endpoint URL
• params: Optional query parameters
• dataProcessor: Optional response transformation function

async post(url: string, data: any, params?: any, dataProcessor?: any): Promise<any>

Sends an HTTP POST request with JSON data.

async put(url: string, data?: any, params?: any, dataProcessor?: any): Promise<any>

Sends an HTTP PUT request with JSON data.

async del(url: string, data?: any, params?: any, dataProcessor?: any): Promise<any>

Sends an HTTP DELETE request.

CommonDataService

Abstract class extending BaseDataService with CRUD operations for URL-based endpoints.

Constructor

constructor(url: string)

Initializes the service with a base URL endpoint.

class UserService extends CommonDataService {
  constructor() {
    super('/users');
  }
}

Methods

save(data: any, isNew: boolean): Promise<any>

Saves data using POST for new entries or PUT for updates.

• data: The data to save
• isNew: true for POST (create), false for PUT (update)

// Create new user
await userService.save({ name: 'John Doe', email: 'john@example.com' }, true);

// Update existing user
await userService.save({ id: 1, name: 'John Smith' }, false);

remove(item: any): Promise<any>

Removes a data entry using DELETE request.

await userService.remove({ id: 1 });

Protected Methods

getDeleteUrl(item: any): string

Returns the deletion URL for an item. Override to customize delete URL generation.

class UserService extends CommonDataService {
  protected getDeleteUrl(item: any): string {
    return `${this.url}/${item.id}`;
  }
}

FullListDataService

Concrete class for retrieving complete lists of data without pagination.

Methods

getList(params?: any): Promise<Array<any>>

Retrieves the complete list of data items.

• params: Optional query parameters for filtering

class ProductService extends FullListDataService {
  constructor() {
    super('/products');
  }
}

const productService = new ProductService();

// Get all products
const allProducts = await productService.getList();

// Get filtered products
const electronics = await productService.getList({ category: 'electronics' });

PagingDataService

Concrete class providing paginated search functionality.

Methods

async search(criteria: any): Promise<PaginationList>

Searches for data with pagination support.

• criteria: Search criteria and pagination parameters
  • page: Current page number (starts from 1)
  • rows: Number of records per page
  • Other search filters as needed

const results = await orderService.search({
  status: 'pending',
  page: 1,
  rows: 20,
  sortBy: 'createdAt',
  sortOrder: 'desc'
});

Protected Methods

buildSearchResult(result: any): PaginationList

Constructs pagination results from API response. The expected return format should contain:

• count: Total number of records
• pages: Total number of pages
• hasMore: Boolean indicating if there are more pages
• list: Array of data items

Override this method if your API returns a different format.

class OrderService extends PagingDataService {
  protected buildSearchResult(result: any): PaginationList {
    // If API returns different format, transform it here
    return {
      count: result.totalRecords,
      pages: result.totalPages,
      hasMore: result.currentPage < result.totalPages,
      list: result.data
    };
  }
}

Usage Examples

Basic CRUD Operations

import { CommonDataService, BaseDataService } from '@ticatec/app-data-service';
import RestService from '@ticatec/axios-restful-service';

// Setup
BaseDataService.setProxy(new RestService('https://api.example.com'));

class UserService extends CommonDataService {
  constructor() {
    super('/users');
  }

  protected getDeleteUrl(item: any): string {
    return `${this.url}/${item.id}`;
  }
}

const userService = new UserService();

// Create
const newUser = await userService.save({
  name: 'John Doe',
  email: 'john@example.com'
}, true);

// Update
const updatedUser = await userService.save({
  id: newUser.id,
  name: 'John Smith'
}, false);

// Delete
await userService.remove({ id: newUser.id });

Full List Retrieval

import { FullListDataService } from '@ticatec/app-data-service';

class CategoryService extends FullListDataService {
  constructor() {
    super('/categories');
  }
}

const categoryService = new CategoryService();
const categories = await categoryService.getList();
const activeCategories = await categoryService.getList({ active: true });

Paginated Search

import { PagingDataService } from '@ticatec/app-data-service';
import PaginationList from '@ticatec/app-data-service/PaginationList';

class OrderService extends PagingDataService {
  constructor() {
    super('/orders');
  }

  protected buildSearchResult(result: any): PaginationList {
    return new PaginationList(
      result.items,
      result.totalCount,
      result.page,
      result.pageSize
    );
  }
}

const orderService = new OrderService();
const paginatedOrders = await orderService.search({
  status: 'pending',
  customerName: 'John',
  page: 1,
  rows: 20
});

console.log(`Found ${paginatedOrders.count} orders`);
console.log(`Page ${paginatedOrders.pages} total, has more: ${paginatedOrders.hasMore}`);
paginatedOrders.list.forEach(order => console.log(order));

Advanced Customization

class CustomUserService extends CommonDataService {
  constructor() {
    super('/users');
  }

  // Custom delete URL with ID
  protected getDeleteUrl(item: any): string {
    return `${this.url}/${item.id}`;
  }

  // Custom methods
  async activateUser(userId: number): Promise<any> {
    return this.put(`${this.url}/${userId}/activate`);
  }

  async getUserProfile(userId: number): Promise<any> {
    return this.get(`${this.url}/${userId}/profile`);
  }
}

Configuration

REST Service Configuration

The library requires a REST service implementation that conforms to the RestService interface. The recommended implementation is @ticatec/axios-restful-service:

import RestService from '@ticatec/axios-restful-service';

const restService = new RestService('https://api.example.com', {
  timeout: 10000,
  headers: {
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  }
});

BaseDataService.setProxy(restService);

Error Handling

Implement error handling in your REST service configuration or in your service consumers:

class UserService extends FullListDataService {
  constructor() {
    super('/users');
  }

  async getList(params?: any): Promise<Array<any>> {
    try {
      return await super.getList(params);
    } catch (error) {
      console.error('Failed to fetch users:', error);
      throw new Error('Unable to retrieve user list');
    }
  }
}

Dependencies

• @ticatec/enhanced-utils: Required for PagingDataService (object utilities)
• @ticatec/restful_service_api: Interface definitions for REST services
• @ticatec/axios-restful-service: Recommended REST service implementation

TypeScript Support

This library is written in TypeScript and includes full type definitions. All classes and methods are properly typed for enhanced development experience.

License

MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues, questions, or contributions:

• Email: huili.f@gmail.com
• GitHub: https://github.com/ticatec/app-data-service
• Issues: https://github.com/ticatec/app-data-service/issues

Copyright © 2023 Ticatec. All rights reserved.