## @e22m4u/js-data-projection

JavaScript модуль для работы с проекцией данных.

## Содержание

- [Установка](#установка)
- [Схема проекции](#схема-проекции)
  - [Определение правил видимости полей](#определение-правил-видимости-полей)
  - [Определение вложенной схемы](#определение-вложенной-схемы)
  - [Определение правил для областей проекции](#определение-правил-для-областей-проекции)
- [Использование](#использование)
  - [Создание проекции данных с помощью схемы](#создание-проекции-данных-с-помощью-схемы)
  - [Применение схемы к массиву объектов](#применение-схемы-к-массиву-объектов)
  - [Исключение неизвестных полей в строгом режиме](#исключение-неизвестных-полей-в-строгом-режиме)
  - [Применение вложенных схем для сложных структур](#применение-вложенных-схем-для-сложных-структур)
  - [Создание проекции для определенной области видимости](#создание-проекции-для-определенной-области-видимости)
  - [Использование фабричной функции вместо объекта схемы](#использование-фабричной-функции-вместо-объекта-схемы)
  - [Использование фабрики во вложенной схеме](#использование-фабрики-во-вложенной-схеме)
  - [Регистрация именованной схемы и создание проекции](#регистрация-именованной-схемы-и-создание-проекции)
  - [Использование вложенных именованных схем](#использование-вложенных-именованных-схем)
  - [Реализация пользовательской функции разрешения имен](#реализация-пользовательской-функции-разрешения-имен)
- [Тесты](#тесты)
- [Лицензия](#лицензия)

## Установка

```bash
npm install @e22m4u/js-data-projection
```

Модуль поддерживает ESM и CommonJS стандарты.

*ESM*

```js
import {projectData} from '@e22m4u/js-data-projection';
```

*CommonJS*

```js
const {projectData} = require('@e22m4u/js-data-projection');
```

## Схема проекции

#### Определение правил видимости полей

```js
{
  foo: true, // поле доступно
  bar: false // поле скрыто
}
```

#### Определение вложенной схемы

```js
{
  name: true, // поле name доступно
  address: {  // настройки поля address
    select: true, // поле address доступно
    schema: {     // вложенная схема
      city: true,     // поле city доступно
      zip: false      // поле zip скрыто
    }
  }
}
```

#### Определение правил для областей проекции

```js
{
  password: { // настройки поля password
    select: false,  // поле password недоступно по умолчанию
    scopes: {       // настройки для областей проекции
      input: true,     // поле доступно для области 'input'
      output: false    // но скрыто для области 'output'
    }
  }
}
```

## Использование

#### Создание проекции данных с помощью схемы

```js
import {projectData} from '@e22m4u/js-data-projection';

const schema = {
  name: true,
  password: false,
};

const data = {
  name: 'Fedor',       // будет доступно, явное правило
  password: 'pass123', // будет исключено, явное правило
  extra: 10,           // будет доступно в режиме по умолчанию
};

const result = projectData(schema, data);
console.log(result);
// {
//   name: 'Fedor',
//   extra: 10
// }
```

#### Применение схемы к массиву объектов

```js
import {projectData} from '@e22m4u/js-data-projection';

const schema = {
  id: true,
  secret: false,
};

const data = [
  {id: 1, secret: 'A'},
  {id: 2, secret: 'B'},
];

const result = projectData(schema, data);
console.log(result);
// [
//   {id: 1},
//   {id: 2}
// ]
```

#### Исключение неизвестных полей в строгом режиме

```js
import {projectData} from '@e22m4u/js-data-projection';

const schema = {
  name: true,
  password: false,
};

const data = {
  name: 'Fedor',       // будет доступно, явное правило
  password: 'pass123', // будет исключено, явное правило
  extra: 10,           // будет исключено в строгом режиме
};

const result = projectData(schema, data, {
  strict: true, // <= строгий режим
});
console.log(result);
// {
//   name: 'Fedor'
// }
```

#### Применение вложенных схем для сложных структур

```js
import {projectData} from '@e22m4u/js-data-projection';

const schema = {
  id: false,
  name: true,
  city: {
    select: true, // правило видимости поля city
    schema: {     // вложенная схема
      id: false,
      name: true,
    },
  },
};

const data = {
  id: 10, // будет скрыто, явное правило
  name: 'Fedor',
  city: {
    id: 20, // будет скрыто, явное правило
    name: 'Moscow',
  },
};

const result = projectData(schema, data);
console.log(result);
// {
//   name: 'Fedor',
//   city: {
//     name: 'Moscow',
//   }
// }
```

#### Создание проекции для определенной области видимости

```js
import {projectData} from '@e22m4u/js-data-projection';

const schema = {
  name: true,
  password: {
    scopes: {
      input: true,   // правило для области 'input'
      output: false, // правило для области 'output'
    },
  },
};

const data = {
  name: 'Fedor',       // будет доступно, явное правило
  password: 'pass123', // будет доступно в зависимости от области
};

const inputData = projectData(schema, data, {
  scope: 'input', // <= область проекции
});
console.log(inputData);
// {
//   name: 'Fedor',
//   password: 'pass123'
// }

const outputData = projectData(schema, data, {
  scope: 'output', // <= область проекции
});
console.log(outputData);
// {
//   name: 'Fedor'
// }
```

#### Использование фабричной функции вместо объекта схемы

```js
import {projectData} from '@e22m4u/js-data-projection';

// фабрика возвращает объект схемы
const getSchema = () => {
  return {
    id: true,
    hiddenField: false,
  };
};

const data = {
  id: 1,
  hiddenField: 'secret',
};

// передача функции вместо объекта
const result = projectData(getSchema, data);
console.log(result);
// {
//   id: 1
// }
```

#### Использование фабрики во вложенной схеме

```js
import {projectData} from '@e22m4u/js-data-projection';

// фабрика для вложенных данных
const getAddressSchema = () => ({
  city: true,
  zip: false,
});

const userSchema = {
  name: true,
  address: {
    schema: getAddressSchema, // <= использование фабрики
  },
};

const data = {
  name: 'Fedor',
  address: {
    city: 'Moscow',
    zip: 123456,
  },
};

const result = projectData(userSchema, data);
console.log(result);
// {
//   name: 'Fedor',
//   address: {
//     city: 'Moscow'
//   }
// }
```

#### Регистрация именованной схемы и создание проекции

```js
import {DataProjector} from '@e22m4u/js-data-projection';

const projector = new DataProjector();

// регистрация схемы
projector.defineSchema({
  name: 'user', // <= имя схемы
  schema: {
    id: true,
    username: true,
    email: false,
  },
});

const data = {
  id: 10,
  username: 'admin',
  email: 'admin@example.com',
};

// проекция данных по зарегистрированному имени
const result = projector.project('user', data);
console.log(result);
// {
//   id: 10,
//   username: 'admin'
// }
```

#### Использование вложенных именованных схем

```js
import {DataProjector} from '@e22m4u/js-data-projection';

const projector = new DataProjector();

// регистрация схемы "address"
projector.defineSchema({
  name: 'address',
  schema: {
    city: true,
    zip: false,
  },
});

// регистрация схемы "user"
projector.defineSchema({
  name: 'user',
  schema: {
    name: true,
    address: {
      select: true,      // видимость поля address
      schema: 'address', // <= имя вложенной схемы
    },
  },
});

const data = {
  name: 'Fedor',
  address: {
    city: 'Moscow',
    zip: 123456,
  },
};

const result = projector.project('user', data);
console.log(result);
// {
//   name: 'Fedor',
//   address: {
//     city: 'Moscow'
//   }
// }
```

#### Реализация пользовательской функции разрешения имен

```js
import {projectData} from '@e22m4u/js-data-projection';

// функция для разрешения имен
const resolver = name => {
  if (name === 'user') {
    return {id: true, name: true, password: false};
  }
  throw new Error(`Schema "${name}" is not found!`);
};

const data = {
  id: 1,
  name: 'Fedor',
  password: 'pass123',
};

const result = projectData(
  'user', // <= вместо схемы передается имя
  data,
  {resolver}, // <= разрешающая функция
);
console.log(result);
// {
//   id: 1,
//   name: 'Fedor'
// }
```

## Тесты

```bash
npm run test
```

## Лицензия

MIT