A1sDS — структуры как явный контракт данных

// Намерение: Создает структуру из произвольного количества пар ключ-значение (до 20).
// Граница: Обязательных параметров нет; все параметры необязательны (40).
// Результат: Structure.

// A1sDS.Of("name", "John", "age", 30) -> {name: "John", age: 30}
    // A1sDS.Of("x", 10, "y", 20, "color", "red") -> {x: 10, y: 20, color: "red"}

// Намерение: Создает фиксированную (неизменяемую) структуру из пар ключ-значение (до 20).
// Граница: Обязательных параметров нет; все параметры необязательны (40).
// Результат: FixedStructure.

// Константы = A1sDS.OfFixed("PI", 3.14159, "E", 2.71828);
    // Константы.PI = 3; // Ошибка! Изменение запрещено

// Намерение: Создает структуру из массива или строки ключей, заполняя все одним значением.
// Граница: Обязательные параметры: Keys, DefaultValue
// Результат: Structure.

// A1sDS.OfKeys("x,y,z", 0) -> {x: 0, y: 0, z: 0}

// Намерение: Создает структуру из QueryString (URL параметров): "name=John&age=30".
// Граница: Обязательные параметры: QueryString
// Результат: Structure.

// A1sDS.OfQueryString("name=John&age=30&city=New%20York")
// -> {name: "John", age: "30", city: "New York"}

// Намерение: Создает структуру из строки ключей или массива ключей и массива значений, объединяя их попарно (Zip).
// Граница: Обязательные параметры: Ключи, Значения
// Результат: Structure.

A1sDS.Zip("x,y,z", A1sAR.Of(1, 2, 3)) -> {x: 1, y: 2, z: 3}
    A1sDS.Zip(A1sAR.Of("a","b"), A1sAR.Of(10,20)) -> {a: 10, b: 20}

// Намерение: Применяет патч (набор изменений) к существующей структуре. Обновляет значения существующих ключей и добавляет новые.
// Граница: Обязательные параметры: Target, Keys, Values
// Результат: Structure.

Options = A1sDS.Of("x", 10, "y", 25);
    A1sDS.Patch(Options, "y,z", A1sAR.Of(20, 30));
    // Результат: {x: 10, y: 20, z: 30} — y обновлен, z добавлен

// Намерение: Выбирает из структуры только указанные ключи (Picker).
// Граница: Обязательные параметры: SourceStruct, KeysString
// Результат: Structure.

user = A1sDS.Of("name", "John", "age", 30, "password", "secret");
  public = A1sDS.Pick(user, "name,age");
  // -> {name: "John", age: 30}

// Намерение: Исключает из структуры указанные ключи.
// Граница: Обязательные параметры: SourceStruct, ExcludeKeysString
// Результат: Structure.

user = A1sDS.Of("name", "John", "age", 30, "password", "secret");
  safe = A1sDS.Omit(user, "password");
  // -> {name: "John", age: 30}

// Намерение: Создает новую структуру с переименованными ключами.
// Граница: Обязательные параметры: SourceStruct, RenameMap
// Результат: Structure.

user = A1sDS.Of("first_name", "John", "last_name", "Doe");
  map = A1sDS.Of("first_name", "имя", "last_name", "фамилия");
  result = A1sDS.Rename(user, map);
  // -> {имя: "John", фамилия: "Doe"}

// Намерение: Переименовывает ключи в каждой структуре массива по схеме маппинга. Поля из схемы — переименовываются. Остальные поля копируются без изменений. Чистая операция над данными — не знает о метаданных конфигурации. Используется транслятором DSL когда имена полей источника (JSON/CSV) отличаются от имён реквизитов ТЧ документа или справочника. Вызывается ДО LoadRows / LoadTabRows.
// Граница: Обязательные параметры: МассивСтруктур, СхемаПолей
// Результат: Array.

// DSL:
  //   ROWS "Продукция"
  //     MAP source.item AS Номенклатура  ENSURE "Номенклатура"
  //     MAP source.unit AS ЕдиницаИзмерения
  //     MAP source.qty  AS Количество
  //
  // Транслятор генерирует:
  Переименованные
          = A1sDS.RenameFields(
                  МассивИзJSON,
                  A1sDS.Of(
                          "item", "Номенклатура",
                          "unit", "ЕдиницаИзмерения",
                          "qty",  "Количество"));  //▶️
  A1sDocs.LoadRows(Dok, "Продукция", Переименованные);  //▶️

  // Поля не попавшие в схему (например "price") копируются как есть.

// Намерение: Возвращает значение по ключу из Структуры; если ключа нет — вставляет умолчание и возвращает его.
// Граница: Обязательные параметры: Struct, Key, DefaultValue
// Результат: Variant.

Prefs = Новый Структура;
    Dark  = A1sDS.GetOrInsert(Prefs, "useDarkmode", Истина); // запишет Истина один раз

// Намерение: Ленивая версия: если ключ отсутствует — вычисляет выражение строкой, вставляет и возвращает.
// Граница: Обязательные параметры: Struct, Key, ValueExpr
// Результат: Variant.

Cache = Новый Структура;
    // Компилируем дорогую регулярку лишь однажды:
    Rx = A1sDS.GetOrInsertEval(Cache, "rxINN", "Новый РегулярноеВыражение(""^\d{10}(\d{2})?$"")");

// Намерение: Вставляет умолчание по «пути ключей» в Структуре (создаёт промежуточные узлы) и возвращает конечное значение.
// Граница: Обязательные параметры: Struct, Path, DefaultValue
// Результат: Variant.

Prefs = Новый Структура;
    // Создаст: ui = { theme = { dark = Истина } }
    A1sDS.GetOrInsertPath(Prefs, "ui.theme.dark", Истина);

// Намерение: Создает структуру, объединив данные с заданными значениями по умолчанию.
// Граница: Обязательные параметры: SourceStruct, DefaultsStruct
// Результат: Structure.

config = A1sDS.Of("host", "localhost");
  defaults = A1sDS.Of("host", "127.0.0.1", "port", 8080);
  result = A1sDS.Defaults(config, defaults);
  // -> {host: "localhost", port: 8080}

// Намерение: Объединяет структуры слева направо; значения более поздних источников перекрывают предыдущие.
// Граница: Обязательные параметры: БазоваяСтруктура, Знач Источник
// Результат: Structure.

@example.1.A1sDS.Merge {
Параметризованная фабричная функция (ПФФ) для DTO
------------------------------------------------
Function NewPostingDTO(Overrides = Undefined) Export

   Base = A1sDS.Of(
       "AccountDr",  ChartOfAccounts.Main.EmptyRef(),
       "AccountCr",  ChartOfAccounts.Main.EmptyRef(),
       "Amount",     0,
       "Description", ""
   );

   Return A1sDS.Merge(Base, Overrides);

EndFunction

/ Использование
Posting = NewPostingDTO(A1sDS.Of(
   "AccountDr", Account41,
   "AccountCr", Account62,
   "Amount",    1000
));
------------------------------------------------
}
@example.2.A1sDS.Merge {
Конфигурация с дефолтами
------------------------------------------------
// … пример сокращён; полная сигнатура и контракт сохранены

// Намерение: Объединяет структуры и возвращает фиксированную неизменяемую структуру.
// Граница: Обязательные параметры: Base
// Результат: FixedStructure.

@example.1.A1sDS.MergeFixed {
ПФФ с возвратом фиксированного DTO
------------------------------------------------
Function NewAPIRequestDTO(Overrides = Undefined) Export

   Base = A1sDS.Of(
       "Method",  "GET",
       "Timeout", 30,
       "Headers", A1sDS.Of("Accept", "application/json")
   );

   // Возвращаем защищенный DTO
   Return A1sDS.MergeFixed(Base, Overrides);

EndFunction

/ Использование
Request = NewAPIRequestDTO(A1sDS.Of("Method", "POST"));
/ Request.Timeout = 60; // Ошибка - объект защищен!
------------------------------------------------
}

// Намерение: Объединяет до 8 структур, значения последующих перезаписывают предыдущие.
// Граница: Обязательные параметры: Структура1
// Результат: Structure.

// s1 = A1sDS.Of("a", 1, "b", 2);
// s2 = A1sDS.Of("b", 3, "c", 4);
// A1sDS.Concatenate(s1, s2) -> {a: 1, b: 3, c: 4}

// Намерение: Создаёт поверхностную копию структуры.
// Граница: Обязательные параметры: Source
// Результат: Structure.

Данные = A1sDS.Copy(Source);

// Намерение: Глубокое копирование структуры (рекурсивно копирует вложенные структуры).
// Граница: Обязательные параметры: ИсходнаяСтруктура
// Результат: Structure.

// nested = A1sDS.Of("inner", A1sDS.Of("value", 42));
// copy = A1sDS.DeepCopy(nested);

// Намерение: Заполняет значения в существующей структуре (In-Place). Мутирует переданный объект. Не создает копию.
// Граница: Обязательные параметры: TargetStruct, Value
// Результат: —.

Струк = Новый Структура("a,b,c");
A1sDS.Fill(Струк, 0); // Струк теперь {a:0, b:0, c:0}

// Для конвейерных вызовов используй A1sDS.On():
// A1sDS.On(Струк).Fill(0).Insert("Итог", 100);

// Намерение: Преобразует структуру в фиксированную.
// Граница: Обязательные параметры: Знач Структура
// Результат: FixedStructure.

Результат = A1sDS.ToFixed(Знач Структура);

// Намерение: Глубокий сброс структуры. Вложенные структуры создаются пустыми, примитивы — в дефолт.
// Граница: Обязательные параметры: SourceStruct
// Результат: Structure.

Данные = A1sDS.ResetDeep(SourceStruct);

// Намерение: Превращает вложенную структуру в плоскую, соединяя ключи через разделитель.
// Граница: Обязательные параметры: NestedStruct
// Результат: Structure.

// nested = A1sDS.Of("ui", A1sDS.Of("theme", A1sDS.Of("dark", True)));
// A1sDS.FlattenKeys(nested) -> {"ui_theme_dark": True}

// Намерение: Собирает плоскую структуру во вложенную, разделяя ключи по разделителю.
// Граница: Обязательные параметры: FlatStruct
// Результат: Structure.

// flat = A1sDS.Of("user_profile_name", "John", "user_profile_address_city", "NY", "order_id", 456);
// A1sDS.NestKeys(flat) -> {user: {profile: {name: "John", address: {city: "NY"}}}, order: {id: 456}}

// Намерение: Проверяет наличие ключа в структуре.
// Граница: Обязательные параметры: Структура, Ключ
// Результат: Boolean.

// struct = A1sDS.Of("name", "John");
// A1sDS.HasKey(struct, "name") -> Истина
// A1sDS.HasKey(struct, "age") -> Ложь

// Намерение: Проверяет, что структура содержит все перечисленные ключи.
// Граница: Обязательные параметры: Struct, KeysString
// Результат: Boolean.

// user = A1sDS.Of("name", "John", "age", 30);
// A1sDS.HasKeys(user, "name,age") -> Истина
// A1sDS.HasKeys(user, "name,email") -> Ложь

// Намерение: Проверяет, пуста ли структура (нет свойств).
// Граница: Обязательные параметры: Структура
// Результат: Boolean.

// A1sDS.IsEmpty(Новый Структура()) -> Истина
// A1sDS.IsEmpty(A1sDS.Of("x", 1)) -> Ложь

// Намерение: Возвращает массив ключей структуры.
// Граница: Обязательные параметры: Структура
// Результат: Array.

// struct = A1sDS.Of("name", "John", "age", 30);
// A1sDS.GetKeys(struct) -> ["name", "age"]

// Намерение: Возвращает массив значений структуры.
// Граница: Обязательные параметры: Структура
// Результат: Array.

// struct = A1sDS.Of("name", "John", "age", 30);
// A1sDS.GetValues(struct) -> ["John", 30]

// Намерение: Сравнивает две структуры на полное совпадение (ключи и значения) с рекурсией.
// Граница: Обязательные параметры: Struct1, Struct2
// Результат: Boolean.

// s1 = A1sDS.Of("a", 1, "b", 2);
// s2 = A1sDS.Of("b", 2, "a", 1);
// A1sDS.Equals(s1, s2) -> Истина

// Намерение: Группирует массив структур по значению указанного ключа и агрегирует значения другого ключа.
// Граница: Обязательные параметры: ArrayOfStructs, GroupByKey, AggregateByKey
// Результат: Structure.

// sales = A1sAR.Of(
//   A1sDS.Of("product", "A", "amount", 10),
//   A1sDS.Of("product", "B", "amount", 5),
//   A1sDS.Of("product", "A", "amount", 7)
// );
// A1sDS.GroupBy(sales, "product", "amount") -> {A: 17, B: 5}

// Намерение: Возвращает структуру с ключами, которые есть во всех переданных структурах (пересечение до 8 структур).
// Граница: Обязательные параметры: Структура1
// Результат: Structure.

// s1 = A1sDS.Of("a", 1, "b", 2); s2 = A1sDS.Of("b", 3, "c", 4);
// A1sDS.Intersection(s1, s2) -> {b: 3}

// Намерение: Возвращает структуру с ключами из первой структуры, которых нет в остальных структурах (разность до 8 структур).
// Граница: Обязательные параметры: Структура1
// Результат: Structure.

// s1 = A1sDS.Of("a", 1, "b", 2); s2 = A1sDS.Of("b", 3, "c", 4);
// A1sDS.Difference(s1, s2) -> {a: 1}

// Намерение: Глубокая очистка и нормализация данных для JSON (Top-Tier Enterprise). Превращает 1C-специфичные типы в JSON-совместимые: - UUID/Ссылки -> String (через XMLString для чистого UID) - СписокЗначений -> Array - Соответствие -> Structure (Graceful Degrade для ключей) - ТаблицаЗначений -> Array of Objects (Graceful Degrade для колонок) - ДеревоЗначений -> Recursive Array with "Children" - ФиксированнаяСтруктура/Массив -> Обычные (разворачивает)
// Граница: Обязательные параметры: Data
// Результат: Arbitrary.

Mixed = ПолучитьСмешанныеДанные();
JSON = A1sDS.Sanitize(Mixed).ToJSON();

// Намерение: Вспомогательная функция для рекурсивного обхода ДереваЗначений. Превращает строки дерева в Структуры и вызывает себя для дочерних строк.
// Граница: Обязательные параметры: СтрокиДерева, Колонки
// Результат: Array.

Массив = A1sDS.SanitizeTreeRows(СтрокиДерева, Колонки);

// Намерение: Сериализует подготовленные данные в JSON-строку.
// Граница: Обязательные параметры: СтруктураВJSON
// Результат: String.

Текст = A1sDS.ToJSON(СтруктураВJSON);

// Намерение: Самотест модуля A1sDS с примерами использования.
// Граница: Параметров нет.
// Результат: Boolean.

Успешно = A1sDS.SelfTest();

// Намерение: Создаёт Fluent-обёртку A1sDP_DS для цепочки операций над структурой.
// Граница: Обязательных параметров нет; все параметры необязательны (1).
// Результат: DataProcessorObject.A1sDP_DS.

ИСПОЛЬЗОВАНИЯ (для документации)
============================================
@example.1.A1sDS.On — Базовое создание структуры {
------------------------------------------------
// БЫЛО (традиционный подход)
Пользователь = Новый Структура;
Пользователь.Вставить("Имя", "Иван");
Пользователь.Вставить("Возраст", 30);
Пользователь.Вставить("Город", "Москва");
Пользователь.Вставить("Активен", Истина);

// СТАЛО (fluent-стиль)
Пользователь = A1sDS.On()
    .Set("Имя", "Иван")
    .Set("Возраст", 30)
    .Set("Город", "Москва")
    .Set("Активен", Истина)
    .Value();
------------------------------------------------
}
@example.2.A1sDS.On — Фильтрация данных API {
------------------------------------------------
// Получили ответ от API с лишними полями
APIОтвет = ПолучитьДанныеОтСервиса();

// Убираем секретные данные и переименовываем
Публичные = A1sDS.On(APIОтвет)
// … пример сокращён; полная сигнатура и контракт сохранены