Joi.extract и утилиты типов

Joi предоставляет механизм работы с составными схемами, где одна из ключевых возможностей — извлечение части схемы по пути. Метод extract применяется к уже собранной схеме и позволяет получить под-схему, соответствующую конкретному пути в объектной структуре.

Сигнатура и базовая идея

Метод вызывается на экземпляре схемы:

const subSchema = schema.extract(path);

path — строка, описывающая путь к вложенному полю, либо массив ключей.

Пример:

const schema = Joi.object({
  user: Joi.object({
    name: Joi.string(),
    age: Joi.number(),
  }),
  meta: Joi.object({
    createdAt: Joi.date(),
  })
});

const nameSchema = schema.extract('user.name');

Результат — схема Joi.string(), извлечённая из глубоко вложенной структуры.

Семантика извлечения схем

1. Навигация по объектной структуре

extract интерпретирует путь как последовательность ключей:

  • user → объект
  • user.name → строковая схема
  • meta.createdAt → схема даты

Это не копирование структуры, а получение ссылки на часть схемы, уже описанной в исходной конфигурации.

2. Ограничения извлечения

Поведение зависит от структуры исходной схемы:

  • если путь не существует — возникает ошибка
  • если путь ведёт не к схеме, а к примитиву — возвращается соответствующий валидатор
  • динамические ключи (Joi.object().pattern()) могут не поддерживать прямой extract

Пример ошибки:

schema.extract('user.address.city'); // если address не определён

3. Использование в модульной архитектуре

extract часто применяется для:

  • переиспользования частей схемы
  • композиции валидаторов
  • построения частичных схем API

Пример:

const baseUserSchema = Joi.object({
  id: Joi.string(),
  profile: Joi.object({
    name: Joi.string(),
    email: Joi.string(),
  })
});

const emailSchema = baseUserSchema.extract('profile.email');

Отличие extract от reach

В экосистеме Joi также встречается метод reach, и важно различать их поведение:

  • extract — работает на экземпляре схемы
  • reach — работает на корневом объекте Joi
const Joi = require('joi');

const schema = Joi.object({
  a: Joi.object({
    b: Joi.string()
  })
});

const sub = schema.extract('a.b');
// vs
const sub2 = Joi.reach(schema, 'a.b');

Ключевое различие — контекст вызова и сценарий использования в библиотеке.

Типизация в TypeScript: утилиты извлечения типов

В типовой системе Joi важную роль играют вспомогательные типы, позволяющие синхронизировать runtime-схемы и compile-time типы.

Общая модель

Типы выводятся из схемы через условные и выводимые конструкции:

  • Joi.Schema как базовый тип
  • вывод через generics
  • утилиты извлечения структуры объекта

Вывод типа схемы (schema inference)

Часто используется паттерн:

type User = Joi.extractType<typeof schema>;

или эквивалентные формы в зависимости от версии типизации.

Суть механизма:

  • анализ структуры Joi.object()
  • рекурсивное сопоставление полей
  • преобразование валидаторов в TypeScript-типы

Пример соответствия

const schema = Joi.object({
  id: Joi.string(),
  age: Joi.number(),
  isActive: Joi.boolean()
});

Результирующий тип:

type User = {
  id: string;
  age: number;
  isActive: boolean;
}

Утилиты работы с частичными типами

Partial extraction

При использовании .optional() или .default() типы автоматически становятся расширенными:

const schema = Joi.object({
  id: Joi.string(),
  nickname: Joi.string().optional()
});

Тип:

type Result = {
  id: string;
  nickname?: string;
}

Извлечение вложенных типов

Для вложенных объектов применяется рекурсивная модель:

const schema = Joi.object({
  user: Joi.object({
    profile: Joi.object({
      email: Joi.string()
    })
  })
});

Тип:

type Email = string;

или:

type UserProfile = {
  user: {
    profile: {
      email: string;
    }
  }
}

Комбинация extract и типовой системы

Сильная сторона Joi заключается в том, что runtime-операции и типизация могут использовать одинаковую структуру.

Пример сценария:

const schema = Joi.object({
  user: Joi.object({
    name: Joi.string(),
    email: Joi.string()
  })
});

const emailSchema = schema.extract('user.email');

Типовая модель может быть синхронизирована:

type Email = string;

Поведение при глубокой композиции

При работе с многоуровневыми схемами важно учитывать:

  • глубина пути влияет на сложность извлечения
  • промежуточные узлы должны быть объектами Joi
  • схемы с .alter(), .when() могут менять структуру динамически

Практическая модель применения extract в архитектуре

1. Сервисная декомпозиция схем

Схемы делятся на доменные части:

  • user
  • auth
  • billing

Каждая часть может быть извлечена независимо:

const authSchema = schema.extract('auth.login');

2. Переиспользование валидаторов

Базовая схема служит источником атомарных правил:

  • email
  • password
  • id

3. Изоляция контрактов API

При изменении структуры API можно извлекать только нужные части без переписывания всей схемы.

Ограничения типовых утилит

Типовая система Joi имеет ряд особенностей:

  • не всегда полностью отражает runtime-ветвления
  • сложные .when() могут теряться в inference
  • динамические ключи ограничивают точность вывода

Поведение при несовпадении runtime и типов

Если схема изменяется динамически:

Joi.object().keys(dynamicConfig)

типовая система может не отразить реальную структуру, и extract остаётся только runtime-инструментом.

Итоговая модель взаимодействия

  • extract — механизм навигации по схемам
  • типовые утилиты — механизм отражения структуры на уровне TypeScript
  • совместное использование обеспечивает единый контракт между runtime и compile-time слоями
Оглавление