docs: updates README.md

README.md

@@ -9,19 +9,20 @@ JavaScript модуль для работы с проекцией данных.
 ## Содержание
 
 - [Установка](#установка)
-- [Функция `projectData`](#функция-projectdata)
+- [Использование](#использование)
   - [Создание проекции](#создание-проекции)
   - [Проекция массива](#проекция-массива)
   - [Строгий режим](#строгий-режим)
   - [Вложенные схемы](#вложенные-схемы)
   - [Область проекции](#область-проекции)
   - [Фабричные функции](#фабричные-функции)
-  - [Именованные схемы](#именованные-схемы)
+  - [Регистрация именованных схем](#регистрация-именованных-схем)
+  - [Применение именованных схем](#применение-именованных-схем)
+  - [Ручное разрешение имен](#ручное-разрешение-имен)
+- [Функция `projectData`](#функция-projectdata)
 - [Класс `DataProjector`](#класс-dataprojector)
   - [Метод `defineSchema`](#метод-defineschema)
-    - [Регистрация именованных схемы](#регистрация-именованных-схем)
   - [Метод `project`](#метод-project)
-    - [Применение именованных схем](#применение-именованных-схем)
 - [Тесты](#тесты)
 - [Лицензия](#лицензия)
 
@@ -31,52 +32,11 @@ JavaScript модуль для работы с проекцией данных.
 npm install @e22m4u/js-data-projection
 ```
 
-## Функция `projectData`
-
-Функция создает проекцию данных на основе переданного объекта схемы.
-Принимает исходные данные и дополнительные опции для управления режимом
-строгости и областью видимости.
-
-**Сигнатура вызова:**
-
-```js
-projectData(schemaOrFactory, data, [options])
-```
-
-**schemaOrFactory**  
-
-*Тип: `object` | `Function` | `string`*
-
-Определяет правила проекции. Принимает:
-- `object`: объект схемы проекции;
-- `Function`: фабрика, возвращающая схему (или имя схемы);
-- `string`: имя для поиска схемы через функцию `resolver`;
-
-**data**  
-
-*Тип: `object` | `object[]` | `any`*
-
-Исходные данные для проекции.
-
-**options** (необязательно)  
-
-*Тип: `object`*
-
-Объект с дополнительными настройками:
-
-- `strict?: boolean`: включает строгий режим;
-- `scope?: string`: имя активной области проекции;
-- `resolver?: Function`: функция для получения схемы по имени;
-
-**Возвращаемое значение:**
-
-Функция возвращает новую структуру, соответствующую исходным данным. Если
-передан объект, результатом будет его копия, содержащая свойства, разрешенные
-правилами схемы с учетом вложенности, строгого режима и активной области
-проекции.
+## Использование
 
-Для массивов возвращается новый список, к каждому элементу которого рекурсивно
-применена схема проекции. Примитивные значения возвращаются без изменений.
+Модуль экспортирует функцию `projectData` для создания проекций
+и класс `DataProjector` с возможностью регистрации и применения
+именованных схем.
 
 #### Создание проекции
 
@@ -328,130 +288,11 @@ console.log(result);
 // }
 ```
 
-#### Именованные схемы
-
-Для использования именованных схем требуется определить функцию для разрешения
-имен. Функция передается в опцию `resolver`, принимает имя схемы в виде строки
-и возвращает объект соответствующей схемы.
-
-```js
-import {projectData} from '@e22m4u/js-data-projection';
-
-// функция для разрешения имен
-const resolver = key => {
-  if (key === 'user') {
-    return {id: true, name: true, password: false};
-  }
-  throw new Error(`Schema "${key}" is not found!`);
-};
-
-const data = {
-  id: 1,
-  name: 'Fedor',
-  password: 'pass123',
-};
-
-const result = projectData(
-  'user', // <= вместо схемы передается имя
-  data,
-  {resolver}, // <= разрешающая функция
-);
-console.log(result);
-// {
-//   id: 1,
-//   name: 'Fedor'
-// }
-```
-
-Именованные схемы могут быть использованы во вложенной структуре.
-Свойство `schema` принимает имя схемы, которое будет передано
-в разрешающую функцию во время создания проекции.
-
-```js
-import {projectData} from '@e22m4u/js-data-projection';
-
-const userSchema = {
-  name: true,
-  address: {
-    schema: 'address', // <= имя вложенной схемы
-  }
-}
-
-// функция для разрешения имен
-const resolver = key => {
-  if (key === 'address') {
-    return {city: true, zip: false};
-  }
-  throw new Error(`Schema "${key}" is not found!`);
-};
-
-const data = {
-  name: 'Fedor',
-  address: {
-    city: 'Moscow',
-    zip: 123456,
-  },
-};
-
-const result = projectData(
-  userSchema,
-  data,
-  {resolver}, // <= разрешающая функция
-);
-console.log(result);
-// {
-//   name: 'Fedor',
-//   address: {
-//     city: 'Moscow'
-//   }
-// }
-```
-
-
-## Класс `DataProjector`
-
-Для централизованного управления схемами и удобной работы в рамках
-сервис-ориентированной архитектуры модуль предоставляет класс `DataProjector`.
-Он позволяет регистрировать именованные схемы в реестре и применять их по имени
-без необходимости вручную передавать функцию `resolver` при каждом вызове.
-
-Создание экземпляра:
-
-```js
-import {DataProjector} from '@e22m4u/js-data-projection';
-
-const projector = new DataProjector();
-```
-
-### Метод `defineSchema`
-
-Регистрирует новую схему в реестре проектора. Метод принимает объект
-определения, содержащий уникальное имя схемы и правила проекции. Возвращает
-текущий экземпляр `DataProjector`, что позволяет использовать цепочки вызовов.
-
-**Сигнатура вызова:**
-
-```js
-defineSchema(schemaDef)
-```
-
-**schemaDef**
-
-*Тип: `{name: string, schema: object}`*
-
-Объект определения схемы, связывающий название схемы с правилами проекции.
-
-- `name: string`: название новой схемы;
-- `schema: object`: объект схемы проекции;
-
-**Возвращаемое значение:**
-
-Текущий экземпляр `DataProjector`.
-
 #### Регистрация именованных схем
 
-Ниже приводится пример регистрации простой схемы под именем `user`. После
-выполнения этого кода схема сохраняется в памяти экземпляра проектора.
+Класс `DataProjector` позволяет сохранять схемы в реестре для их последующего
+использования по имени. Это удобно для переиспользования схем в разных частях
+приложения.
 
 ```js
 import {DataProjector} from '@e22m4u/js-data-projection';
@@ -468,9 +309,9 @@ projector.defineSchema({
 });
 ```
 
-Метод позволяет регистрировать схемы, которые ссылаются друг на друга.
-В примере ниже схема `user` использует схему `address` для проекции
-вложенного объекта.
+Схемы в реестре могут ссылаться друг на друга, что позволяет компоновать
+сложные схемы из более простых. В примере ниже схема `user` использует
+схему `address` как вложенную.
 
 ```js
 import {DataProjector} from '@e22m4u/js-data-projection';
@@ -497,48 +338,10 @@ projector.defineSchema({
 });
 ```
 
-### Метод `project`
-
-Выполняет проекцию данных, используя возможности внутреннего реестра схем. Метод работает аналогично функции `projectData`, но автоматически предоставляет механизм разрешения имен (resolver), связанный с добавленными ранее схемами. Это позволяет передавать в качестве первого аргумента строковое имя зарегистрированной схемы без необходимости указывать функцию `resolver` в опциях вручную.
-
-**Сигнатура вызова:**
-
-```js
-project(schemaOrFactory, data, [options])
-```
-
-**schemaOrFactory**  
-
-*Тип: `object` | `Function` | `string`*
-
-Определяет правила проекции. Принимает:
-- `object`: объект схемы проекции;
-- `Function`: фабрика, возвращающая схему (или имя схемы);
-- `string`: зарегистрированное имя схемы;
-
-**data**  
-
-*Тип: `object` | `object[]` | `any`*
-
-Исходные данные для проекции.
-
-**options** (необязательно)  
-
-*Тип: `object`*
-
-Объект с дополнительными настройками:
-
-- `strict?: boolean`: включает строгий режим;
-- `scope?: string`: имя активной области проекции;
-
-**Возвращаемое значение:**
-
-Метод возвращает проекцию исходных данных в соответствии с переданной схемой
-и настройками.
-
 #### Применение именованных схем
 
-В данном примере вместо передачи объекта схемы используется имя `publicUser`. Проектор находит соответствующее определение в своем реестре и применяет
+В данном примере вместо передачи объекта схемы используется имя `publicUser`.
+Проектор находит соответствующее определение в своем реестре и применяет
 его к указанным данным.
 
 ```js
@@ -546,7 +349,6 @@ import {DataProjector} from '@e22m4u/js-data-projection';
 
 const projector = new DataProjector();
 
-// регистрация схемы
 projector.defineSchema({
   name: 'publicUser',
   schema: {
@@ -571,15 +373,15 @@ console.log(result);
 // }
 ```
 
-Проектор автоматически обрабатывает зависимости между схемами. Когда схема
-`user` применяется к данным, проектор видит ссылку на схему `address` во вложенном поле и использует её для обработки адреса.
+Проектор автоматически разрешает зависимости между схемами. Если в схеме
+указана ссылка на другую именованную схему, проектор найдет её в реестре
+и применит к вложенным данным.
 
 ```js
 import {DataProjector} from '@e22m4u/js-data-projection';
 
 const projector = new DataProjector();
 
-// регистрация вложенной схемы
 projector.defineSchema({
   name: 'address',
   schema: {
@@ -588,7 +390,6 @@ projector.defineSchema({
   },
 });
 
-// регистрация основной схемы
 projector.defineSchema({
   name: 'user',
   schema: {
@@ -608,8 +409,6 @@ const data = {
   },
 };
 
-// при создании проекции схемы 'user', вложенная
-// схема 'address' будет найдена автоматически
 const result = projector.project('user', data);
 console.log(result);
 // {
@@ -620,6 +419,167 @@ console.log(result);
 // }
 ```
 
+#### Ручное разрешение имен
+
+Для ручного разрешения имен используется опция `resolver` функции `projectData`.
+В опцию передается функция, которая принимает имя схемы и должна вернуть
+соответствующий ей объект схемы.
+
+```js
+import {projectData} from '@e22m4u/js-data-projection';
+
+// функция для разрешения имен
+const resolver = key => {
+  if (key === 'user') {
+    return {id: true, name: true, password: false};
+  }
+  throw new Error(`Schema "${key}" is not found!`);
+};
+
+const data = {
+  id: 1,
+  name: 'Fedor',
+  password: 'pass123',
+};
+
+const result = projectData(
+  'user', // <= вместо схемы передается имя
+  data,
+  {resolver}, // <= разрешающая функция
+);
+console.log(result);
+// {
+//   id: 1,
+//   name: 'Fedor'
+// }
+```
+
+## Функция `projectData`
+
+Функция создает проекцию данных на основе переданного объекта схемы.
+Принимает исходные данные и дополнительные опции для управления режимом
+строгости и областью видимости.
+
+**Сигнатура вызова:**
+
+```js
+projectData(schemaOrFactory, data, [options])
+```
+
+**schemaOrFactory**  
+
+*Тип: `object` | `Function` | `string`*
+
+Определяет правила проекции. Принимает:
+- `object`: объект схемы проекции;
+- `Function`: фабрика, возвращающая схему (или имя схемы);
+- `string`: имя для поиска схемы через функцию `resolver`;
+
+**data**  
+
+*Тип: `object` | `object[]` | `any`*
+
+Исходные данные для проекции.
+
+**options** (необязательно)  
+
+*Тип: `object`*
+
+Объект с дополнительными настройками:
+
+- `strict?: boolean`: включает строгий режим;
+- `scope?: string`: имя активной области проекции;
+- `resolver?: Function`: функция для получения схемы по имени;
+
+**Возвращаемое значение:**
+
+Функция возвращает новую структуру, соответствующую исходным данным. Если
+передан объект, результатом будет его копия, содержащая свойства, разрешенные
+правилами схемы с учетом вложенности, строгого режима и активной области
+проекции.
+
+Для массивов возвращается новый список, к каждому элементу которого рекурсивно
+применена схема проекции. Примитивные значения возвращаются без изменений.
+
+## Класс `DataProjector`
+
+Для централизованного управления схемами и удобной работы в рамках
+сервис-ориентированной архитектуры модуль предоставляет класс `DataProjector`.
+Он позволяет регистрировать именованные схемы в реестре и применять их по имени
+без необходимости вручную передавать функцию `resolver` при каждом вызове.
+
+Создание экземпляра:
+
+```js
+import {DataProjector} from '@e22m4u/js-data-projection';
+
+const projector = new DataProjector();
+```
+
+### Метод `defineSchema`
+
+Регистрирует новую схему в реестре проектора. Метод принимает объект
+определения, содержащий уникальное имя схемы и правила проекции. Возвращает
+текущий экземпляр `DataProjector`, что позволяет использовать цепочки вызовов.
+
+**Сигнатура вызова:**
+
+```js
+defineSchema(schemaDef)
+```
+
+**schemaDef**
+
+*Тип: `{name: string, schema: object}`*
+
+Объект определения схемы, связывающий название схемы с правилами проекции.
+
+- `name: string`: название новой схемы;
+- `schema: object`: объект схемы проекции;
+
+**Возвращаемое значение:**
+
+Текущий экземпляр `DataProjector`.
+
+### Метод `project`
+
+Выполняет проекцию данных, используя возможности внутреннего реестра схем. Метод работает аналогично функции `projectData`, но автоматически предоставляет механизм разрешения имен (resolver), связанный с добавленными ранее схемами. Это позволяет передавать в качестве первого аргумента строковое имя зарегистрированной схемы без необходимости указывать функцию `resolver` в опциях вручную.
+
+**Сигнатура вызова:**
+
+```js
+project(schemaOrFactory, data, [options])
+```
+
+**schemaOrFactory**  
+
+*Тип: `object` | `Function` | `string`*
+
+Определяет правила проекции. Принимает:
+- `object`: объект схемы проекции;
+- `Function`: фабрика, возвращающая схему (или имя схемы);
+- `string`: зарегистрированное имя схемы;
+
+**data**  
+
+*Тип: `object` | `object[]` | `any`*
+
+Исходные данные для проекции.
+
+**options** (необязательно)  
+
+*Тип: `object`*
+
+Объект с дополнительными настройками:
+
+- `strict?: boolean`: включает строгий режим;
+- `scope?: string`: имя активной области проекции;
+
+**Возвращаемое значение:**
+
+Метод возвращает проекцию исходных данных в соответствии с переданной схемой
+и настройками.
+
 ## Тесты
 
 ```bash