Ограничения по длине

В библиотеке Superstruct контроль длины используется для строгого описания допустимых границ данных на уровне строк, массивов и сложных структур. Вместо разрозненных проверок вручную применяются декларативные ограничения, встроенные в композицию структур, что позволяет формировать предсказуемую модель валидации.

Базовая модель ограничения длины

Ограничения длины в Superstruct строятся вокруг трёх основных принципов:

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

Для работы с длиной используются вспомогательные структурные обёртки, которые модифицируют базовые типы.

Ограничения длины строк

Для строк длина контролируется через диапазон допустимых значений символов.

import { string, size } from "superstruct";

const Username = size(string(), 3, 12);

В этом примере:

  • минимальная длина строки — 3 символа;
  • максимальная длина — 12 символов.

Если значение выходит за пределы, структура возвращает ошибку валидации.

Дополнительно возможно фиксировать точную длину:

const PinCode = size(string(), 4, 4);

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

Поведение при некорректной длине строки

При нарушении границ:

  • строки короче минимального значения считаются невалидными;
  • строки длиннее максимального значения также отклоняются;
  • пустая строка трактуется как длина 0 и проверяется по тем же правилам.

Это позволяет унифицировать обработку всех случаев без специальных условий.

Ограничения длины массивов

Для массивов применяется тот же механизм через функцию size, где проверяется количество элементов.

import { array, number, size } from "superstruct";

const Numbers = size(array(number()), 1, 5);

Здесь массив должен содержать от 1 до 5 чисел.

Практическое применение ограничений массивов

Ограничения длины массива используются для:

  • ограничений количества элементов формы;
  • управления вложенными структурами;
  • контроля бизнес-правил (например, число участников, тегов, файлов).

Пример строгого ограничения:

const Tags = size(array(string()), 1, 3);

Это гарантирует, что пользователь не сможет передать больше трёх тегов.

Ограничения длины объектов

Хотя объекты не имеют «длины» в классическом смысле строк и массивов, в Superstruct можно контролировать количество ключей, преобразуя объект через вспомогательные структуры.

Обычно применяется комбинация:

  • record для описания формы;
  • size для ограничения количества ключей.
import { record, string, size } from "superstruct";

const Metadata = size(record(string(), string()), 1, 5);

В этом случае объект должен содержать от 1 до 5 ключей.

Особенности подсчёта длины объектов

При проверке:

  • учитываются только собственные ключи объекта;
  • вложенные объекты не влияют на верхнеуровневый счётчик;
  • свойства с undefined всё равно считаются, если ключ существует.

Комбинирование ограничений длины с другими правилами

Ограничения длины часто применяются совместно с типизацией:

import { object, string, size } from "superstruct";

const Profile = object({
  name: size(string(), 2, 30),
  bio: size(string(), 0, 150)
});

Такой подход позволяет одновременно контролировать тип и диапазон длины.

Вложенные структуры и каскадные ограничения

При работе с вложенными данными ограничения длины применяются на каждом уровне независимо.

const Comment = object({
  text: size(string(), 1, 200),
  replies: size(array(string()), 0, 10)
});

Здесь:

  • текст комментария ограничен 200 символами;
  • количество ответов ограничено 10 элементами;
  • вложенные строки в replies дополнительно могут иметь свои собственные ограничения.

Динамические ограничения длины

В некоторых сценариях границы длины вычисляются динамически:

const max = 10;

const DynamicString = size(string(), 1, max);

Это позволяет адаптировать правила в зависимости от:

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

Ошибки, связанные с нарушением длины

При несоответствии ограничениям возвращается структурированная ошибка, содержащая:

  • путь до значения;
  • ожидаемые границы;
  • фактическое значение длины.

Это упрощает обработку ошибок на уровне интерфейса и серверной логики.

Кастомизация сообщений при нарушении длины

Superstruct позволяет переопределять поведение ошибок через обёртки:

import { size, string } from "superstruct";

const ShortName = size(string(), 2, 10);

При интеграции с обработчиком ошибок можно формировать более информативные сообщения, не изменяя саму структуру.

Ограничения длины и производительность

Проверка длины является одной из самых дешёвых операций валидации:

  • выполняется за O(1) для строк (через встроенное свойство length);
  • выполняется за O(1) для массивов (через length);
  • для объектов — O(n) по количеству ключей.

Поэтому ограничения длины обычно применяются в начале цепочки валидации, снижая стоимость последующих проверок.

Типичные ошибки при использовании ограничений

Часто встречаются следующие проблемы:

  • использование слишком жёстких границ без учёта реальных данных;
  • дублирование ограничений на нескольких уровнях без необходимости;
  • ожидание автоматической нормализации значений вместо их отклонения;
  • применение строковых ограничений к уже преобразованным типам данных.

Эти ошибки приводят к избыточной сложности схем и ухудшению читаемости.

Поведение при отсутствии ограничений

Если ограничение длины не задано:

  • строка может быть любой длины;
  • массив не ограничен по количеству элементов;
  • объект допускает любое количество ключей.

Это делает схему максимально гибкой, но менее предсказуемой в контексте бизнес-правил.

Оглавление