Record (Запросы API) / Трансформация

В Nuxoblivius можно не только получать "сырое" response.body, но и преобразовывать его под свои нужды. Этот процесс мы называем трансформацией ответа (или "шаблонизацией").

С помощью встроенных механизмов вы можете:

1. Удобно обращаться к данным внутри ответа.
2. Выполнять преобразования прямо при чтении.
3. Настраивать единый формат работы с API, чтобы избавить компоненты от "ручной" обработки.

Как использовать template() в Record

Метод .template() позволяет настроить трансформацию ответа от API в удобный для вас формат. Он принимает функцию, которая должна вернуть объект следующей структуры:

• data?: unknown — преобразованные данные тела ответа (основной результат, с которым будут работать).
• pageCount?: number — общее количество страниц (актуально для пагинации, если API возвращает такую информацию).
• protocol?: Record<string, unknown> — дополнительные данные, которые нужно сохранить вместе с ответом (например, вычиляемые данные или метаданные).

---

Таким образом, .template() помогает вынести всю логику обработки ответа из компонентов и хранить её в одном месте.

Безопасный режим

.template() отработает только если запрос был без ошибок, т.е. если
response.ok === true

import { Record } from "nuxoblivius";

const posts = Record.new<Posts>("/api/posts", []);

posts.template((rawData: Raw<Posts>) => {
  return {
    data: rawData.items, // Сами данные
    pageCount: rawData?.meta?.pageCount ?? 1, // Сохраняем кол-во страниц
    protocol: rawData?.meta ?? {}, // Сохраняем метаданные
  };
});

posts.response.items[0].title; 
posts.response[0].title; 

Что такое протокол (protocol)?

protocol — это специальное место для хранения дополнительных данных, которые сохраняются после трансформации ответа.

Особенности:

• поддерживает типизацию, что упрощает работу в больших проектах;
• позволяет задавать значения по умолчанию, что делает код более безопасным и защищает от случайных ошибок;
• используется для хранения служебных данных, не относящихся напрямую к data (например, флаги, технические параметры, метаданные).

Для создания участника протокола можно использовать метод .defineProtocol().

Регистрация

import { Record } from "nuxoblivius";

const post = Record.new<Post>("/api/posts/{id}", {});

// Указываем что такой протокол существует
post.defineProtocol<string>("cutDescription", "");

// Получаем данное значение
post.protocol.cutDescription;

Использование

post.template((rawData: Raw<Post>) => {
  return {
    data: rawData, // Сам пост
    protocol: {
      // Создаём краткое описание
      cutDescription: rawData.description.slice(0, 100),
    },
  };
});

Создание глобального шаблона

Иногда один и тот же формат трансформации данных требуется использовать в разных запросах. Чтобы не дублировать логику, в Nuxoblivius можно создавать глобальные шаблоны.

Для этого используется метод RegisterTemplate(). Он работает аналогично методу .template(), но принимает:

1. строку — уникальное имя шаблона;
2. функцию — саму логику трансформации.

После регистрации такой шаблон можно подключать в любом Record по имени.

Регистрация

import { RegisterTemplate } from "nuxoblivius";

RegisterTemplate("my-template", (rawData: Raw<any>) => {
  return {
    data: rawData.items ?? rawData,
    pageCount: rawData?.meta?.pageCount ?? 1,
    protocol: rawData?.meta ?? {},
  };
});

Использование

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.template("my-template");

Обработка данных по шаблону в любом месте

Шаблон можно вызывать не только внутри Record, но и в любом другом месте приложения. Это удобно, когда требуется повторно использовать одну и ту же логику преобразования.

Метод принимает два аргумента:

1. Имя шаблона (или функцию трансформации);
2. Данные, которые необходимо обработать.

Таким образом, вы не привязаны к Record и можете применять шаблон там, где это действительно нужно.

Функция

import { CallPattern } from "nuxoblivius";

const { data } = CallPattern((rawData) => {
  return {
    data: rawData.items,
  };
}, myRawData);

По именни

import { CallPattern } from "nuxoblivius";

const { data } = CallPattern("my-template", myRawData);