`RawObjectDataProcessor` — Типовые сценарии

Эта страница не завершена

Приносим свои извинения, но данная страница ещё не завершена.

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

Объекты фиксированной структуры

Объекты фиксированной структуры

Если ожидаются данные типа «объект фиксированной структуры», необходимо в спецификации валидных данных указать subtype: RawObjectDataProcessor.ObjectSubtypes.fixedSchema, а через в properties указать спецификацию каждого свойства:

const externalDataProcessingResult: RawObjectDataProcessor.ProcessingResult<TargetType> = RawObjectDataProcessor.
    process(
      externalData,
      {
        nameForLogging: "Example",
        subtype: RawObjectDataProcessor.ObjectSubtypes.fixedSchema,
        properties: {
          property1: { /* ... */ },
          property1: { /* ... */ },
          // ...
          propertyN: { /* ... */ }
        }
      }
    );

Разумеется, поддерживаются вложенные объекты, причём глубина может быть произвольной:

type TargetType = {
  alpha1: {
    alpha2: number;
    bravo2: string;
  };
};

const externalDataProcessingResult: RawObjectDataProcessor.ProcessingResult<TargetType> = RawObjectDataProcessor.

    process(
      externalData,
      {

        nameForLogging: "Example",
        subtype: RawObjectDataProcessor.ObjectSubtypes.fixedSchema,

        properties: {
          alpha1: {

            type: Object,
            isUndefinedForbidden: true,
            isNullForbidden: true,

            properties: {

              alpha2: {
                type: Number,
                isUndefinedForbidden: true,
                isNullForbidden: true,
                numbersSet: RawObjectDataProcessor.NumbersSets.anyRealNumber
              },

              bravo2: {
                type: String
                isUndefinedForbidden: true,
                isNullForbidden: true,
              }

            }

          }

        }
      }
    );

Обязательность свойств

В случае ECMAScript, понятие обязательности (requirement) свойств расплывчато ввиду наличия двух пустых типов — undefined и null, причём отсутствие какого-либо свойства или элемента в целом не равносильно его наличию со явно указанным undefined в качестве значения. Что значит «свойство обязательно»? Оно не должно иметь значения undefined или null? А может, ни того, не другого?

Между прочим, по этой же причине расплывчатыми являются и такие родственные понятия, как «опциональное свойство» или «подстановка значения по умолчанию» (в каких случаях эта постановка осуществляется?).

До версии 1.8 библиотеки YDEE, в спецификации свойств объектных данных required: true означал запрет на undefined, но не на] null — по умолчанию null был запрещён, а снять этот запрет можно было указав nullable: true. Может быть, такой программный интерфейс и лаконичный, но не слишком интуитивный, а это — множественные трещины в поддерживаемости кода.

Начиная с версии 1.8, разрешения/запреты на undefined и на null необходимо указывать явно и отдельно, но единообразным способом:

Разрешение/запрет	Случай с undefined	Случай с null
Полный запрет	`isUndefinedForbidden: true`	`isNullForbidden: true`
Условный запрет	`undefinedForbiddenIf: ConditionAssociatedWithProperty`	`nullForbiddenIf: ConditionAssociatedWithProperty`
Подстановка значения по умолчанию	`undefinedValueSubstitution: NonEmptyValue`	`nullValueSubstitution: NonEmptyValue`
Трансформация в другой пустой тип	`mustTransformUndefinedToNull: true`	`mustTransformNullToUndefined: true`
Полное разрешение	`isUndefinedForbidden: false`	`isNullForbidden: false`

Также, если isUndefinedForbidden/isNullForbidden указано значение false (полное разрешение), то можно дополнительно через mustBeUndefinedIf/mustBeNullIf соответственно указать, когда значение должно быть пустым.

Полный запрет пустых значений

Укажите isUndefinedForbidden: true, чтобы запретить свойства со значениями undefined, будь то явный undefined или просто отсутствие свойства.
Укажите isNullForbidden: true чтобы запретить свойства со значением null.

type ValidData = { alpha: number; };

const validDataSpecification: RawObjectDataProcessor.ObjectDataSpecification = {
  nameForLogging: "ValidData",
  subtype: RawObjectDataProcessor.ObjectSubtypes.fixedSchema,
  properties: {
    alpha: {
      type: Number,
      numbersSet: RawObjectDataProcessor.NumbersSets.anyRealNumber,
      isUndefinedForbidden: true,
      isNullForbidden: true
    }
  }
};

Возьмём для примера объект с единственным свойством alpha, которое может иметь только числовые значения, но никакие другие, в частности undefined и null не допускаются ни при каких условиях.

const processingResult: RawObjectDataProcessor.ProcessingResult<ValidData> = RawObjectDataProcessor.
    process({}, validDataSpecification);

В данном случае исходный объект невалиден, потому что отсутствует свойство alpha. Это не эквивалентно тому, что был бы явно указан undefined, тем не менее если бы мы попробовали обратиться к свойству alpha у исходного объекта, то возвращённым значением было бы undefined, а это не допускается запретом isUndefinedForbidden: true.

const processingResult: RawObjectDataProcessor.ProcessingResult<ValidData> = RawObjectDataProcessor.
    process({ alpha: undefined}, validDataSpecification);

В данном случае исходный объект тоже невалиден, потому что свойство alpha хотя и указано, но указанным значением является явный undefined, что также не удовлетворяет ограничению isUndefinedForbidden: true.

const processingResult: RawObjectDataProcessor.ProcessingResult<ValidData> = RawObjectDataProcessor.
    process({ alpha: 7 }, validDataSpecification);

А вот здесь всё нормально: значением свойства alpha является число, что соответствует установленным ограничениям для данного свойства.

RawObjectDataProcessor — Типовые сценарии

Объекты фиксированной структуры

Обязательность свойств

Полный запрет пустых значений

`RawObjectDataProcessor` — Типовые сценарии