@mee4dy/crud-client

Клиентская библиотека для работы с CRUD API. Предоставляет удобный интерфейс для выполнения операций создания, чтения, обновления и удаления данных через HTTP запросы.

Установка

npm install @mee4dy/crud-client

Основные возможности

• HTTP клиент для CRUD операций
• Состояние загрузки
• Интеграция с ORM для удобной работы с объектами
• Отмена запросов через AbortController
• Поддержка query параметров
• Автоматическая генерация endpoints по названию сущности
• Гибкая настройка HTTP методов для каждого endpoint
• Типизированные ответы и ошибки

Быстрый старт

Простой способ (с названием сущности)

import { CrudClient } from '@mee4dy/crud-client';

const crud = new CrudClient({
  entity: 'posts',
  http: {
    baseURL: 'http://localhost:3000/api',
    headers: {
      Authorization: 'Bearer your_token',
    },
  },
});

// Автоматически генерируются endpoints:
// GET /api/posts - получение списка
// GET /api/posts/:pk - получение одного элемента
// POST /api/posts - создание
// PUT /api/posts/:pk - обновление
// DELETE /api/posts/:pk - удаление

Кастомизация endpoints

const crud = new CrudClient({
  endpoints: {
    items: { url: '/api/posts', method: 'GET' },
    item: { url: '/api/posts/:pk', method: 'GET' },
    create: { url: '/api/posts', method: 'POST' },
    update: { url: '/api/posts/:pk', method: 'PATCH' }, // Кастомный метод
    delete: { url: '/api/posts/:pk', method: 'DELETE' },
  },
});

Конфигурация

interface CrudOptions {
  entity?: string; // Название сущности для автоматической генерации endpoints
  endpoints?: Endpoints; // Полная настройка endpoints
  pk?: string; // Первичный ключ (по умолчанию 'id')
  orm?: boolean; // Включить ORM (по умолчанию true)
  http?: HttpOptions; // Настройки HTTP клиента
}

interface Endpoints {
  items?: EndpointConfig; // GET /items - получение списка
  item?: EndpointConfig; // GET /items/:pk - получение одного элемента
  create?: EndpointConfig; // POST /items - создание
  update?: EndpointConfig; // PUT /items/:pk - обновление
  delete?: EndpointConfig; // DELETE /items/:pk - удаление
}

type EndpointConfig = { url: string; method: string };

interface HttpOptions {
  baseURL?: string; // Базовый URL для всех запросов
  headers?: object; // Заголовки запросов
  timeout?: number; // Таймаут запросов
  abort?: boolean; // Автоматическая отмена предыдущих запросов
}

Примеры использования

Базовые CRUD операции

// Получить список элементов
const postsData = await crud.items({ limit: 10, offset: 0 });
console.log(postsData.items); // массив элементов

// Получить один элемент по ID
const postData = await crud.item(1);
console.log(postData.item); // объект элемента

// Создать новый элемент
const newPostData = await crud.create({
  title: 'Новый пост',
  content: 'Текст поста',
});
console.log(newPostData.item); // созданный элемент

// Обновить элемент
const updatedPostData = await crud.update(1, {
  title: 'Обновлённый заголовок',
});
console.log(updatedPostData.item); // обновлённый элемент

// Удалить элемент
const deletedData = await crud.delete(1);
console.log(deletedData.result); // результат удаления

Работа с ORM

При включённом ORM (по умолчанию) объекты имеют методы для удобной работы:

// Получить список с ORM объектами
const postsData = await crud.items();
const posts = postsData.items; // массив с ORM объектами

// Модифицировать объект и сохранить
const firstPost = posts[0];
firstPost.title = 'Новое название';
firstPost.content = 'Обновлённый текст';
await firstPost.save();

// Удалить объект
await post.delete();

Работа с состоянием

// Проверить состояние загрузки
if (crud.state.loading) {
  console.log('Запрос выполняется...');
}

Обработка ошибок

try {
  const postsData = await crud.items();
  console.log(postsData.items);
} catch (error: any) {
  console.error('Ошибка:', error.message);
  console.error('Код:', error.statusCode);
  console.error('Тип:', error.errorType);

  // Обработка ошибок валидации
  if (error.fields) {
    Object.entries(error.fields).forEach(([field, message]) => {
      console.error(`${field}: ${message}`);
    });
  }
}

Отмена запросов

// При включённом abort: true (по умолчанию)
// Новый запрос автоматически отменяет предыдущий

// Первый запрос будет отменён
crud.items({ limit: 10 });

// Второй запрос выполнится
const postsData = await crud.items({ limit: 20 });
console.log(postsData.items);

Интеграция с Vue

<template>
  <div>
    <div v-if="crud.state.loading">Загрузка...</div>
    <div v-if="error" class="error">{{ error }}</div>

    <div v-for="post in posts" :key="post.id">
      <h3>{{ post.title }}</h3>
      <p>{{ post.content }}</p>
      <button @click="updatePost(post)">Обновить</button>
      <button @click="deletePost(post)">Удалить</button>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { CrudClient } from '@mee4dy/crud-client';

const posts = ref([]);
const error = ref('');

const crud = new CrudClient({
  entity: 'posts',
  http: {
    baseURL: 'http://localhost:3000/api',
  },
});

const loadPosts = async () => {
  try {
    error.value = '';
    const postsData = await crud.items();
    posts.value = postsData.items;
  } catch (err: any) {
    error.value = err?.message || 'Ошибка загрузки';
  }
};

const updatePost = async (post) => {
  try {
    post.title = 'Обновлённый заголовок';
    await post.save();
  } catch (err: any) {
    error.value = err?.message || 'Ошибка обновления';
  }
};

const deletePost = async (post) => {
  try {
    await post.delete();
    await loadPosts(); // Перезагрузить список
  } catch (err: any) {
    error.value = err?.message || 'Ошибка удаления';
  }
};

onMounted(() => {
  loadPosts();
});
</script>

Интеграция с бэкендом

Пакет полностью совместим с @mee4dy/crud-nestjs для бэкенда.

Типы данных

Структура ответа от методов

Все методы возвращают данные в формате:

// Для items()
{
  items: any[];        // массив элементов
  total?: number;      // общее количество
  page?: number;       // текущая страница
  limit?: number;      // лимит на страницу
  pages?: number;      // общее количество страниц
}

// Для item(), create(), update(), delete()
{
  item: any;           // объект элемента
}

Структура ошибок

При ошибках выбрасывается исключение с объектом:

{
  status: false;
  error: {
    message?: string;                    // сообщение об ошибке
    statusCode?: number;                 // HTTP статус код
    errorType?: string;                  // тип ошибки
    fields?: Record<string, string | string[]>; // ошибки валидации полей
  };
}

Совместимость

Библиотека предназначена для работы с API, возвращающими данные в формате:

{
  status: boolean;
  data?: {
    items?: any[];
    item?: any;
    total?: number;
    page?: number;
    limit?: number;
    pages?: number;
  };
  error?: {
    message?: string;
    statusCode?: number;
    errorType?: string;
    fields?: Record<string, string | string[]>;
  };
}