Агент функціональності

інформація

Агент функціональності призначений для надання бізнес-схемі переліку можливостей для опису обробників бізнес-схеми. Функціональність поділена на простори імен, в які входить цільовий функціонал.

Структура агента

Доступ до функціональності агента може бути отриманий наступним чином на прикладі опису кінцевого маршруту документа "Маршрутизатор":

import { setRouter } from "@x-fiber/proton";
 
export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: { 
    GET: {
      scope: "private:user",
      params: [
        {
            name: 'userId',
            scope: 'required',
        }  
      ],
      handler: async (request, agents, context) => {
        agents.fnAgent // .{namespace}.{namespace-method}
      },
    },
  },
});

Наразі доступні наступні простори імен:

Простір	Призначення
`discovery`	Робота з конфігураційними змінними
`logger`	Робота з логуванням
`utils`	Загальні, допоміжні функції
`scrambler`	Робота з шифруванням, дешифруванням та хешуванням
`sessions`	Робота з сесіями
`exception`	Робота з виключеннями
`permissions`	Робота з правами доступу
`scheduler`	Робота з планувальником задач
`fileStorage`	Робота з файловим сховищем
`ws`	Організація роботи з `ws` подіями
`broker`	Організація роботи з брокером повідомлень `broker`
`cache`	Кешування даних

discovery

інформація

Простір імен discovery призначений для організації роботи з конфігураційними даними. Простір імен надає можливість отримувати конфігураційні дані здійснюючи перевірку на тип відповідної конфігураційної змінної.

getMandatory

Метод для отримання конфігураційної змінної заданого типу, або, в разі її відсутності - виклик помилки.

type ConfigParameter = string | boolean | number | (string | boolean | number)[]
type ExtendedObject = Record<string, ExtendedObject | ConfigParameter>

type KeyConfigLiteralBuilder<
    T,
    F extends ConfigParameter
> = T extends Record<string, unknown>
    ? {
        [K in keyof T]: T[K] extends F
            ? `${string & K}`
            : K extends string
                ? `${string & K}.${KeyConfigLiteralBuilder<T[K], F>}`
                : never;
    }[keyof T]
    : string;

type getMandatory<T, C extends ExtendedObject = ExtendedObject> = (
    name: KeyConfigLiteralBuilder<C, T>
) => T;

де:

Тип функції: Синхронна.
Типи даних:
- ConfigParameter - Перелік можливих типів даних конфігурації.
- ExtendedObject - Тип обʼєкта, який передбачає будь-яку кількість вкладенностей, але кінцевим значенням повинен бути тип ConfigParameter.
- KeyConfigLiteralBuilder - Тип який аналізує тип конфігурації та надає відповідні шляхи доступу до можливих змінних.
- T - Тип даних конфігураційної змінної.
- C - Тип обʼєкта конфігурації, який має структуру ExtendedObject
Аргументи:
1. Шлях доступу до змінної, який будується на основі структури типу конфігурації.
Результат:
- Повернення змінної з типом даних T або виклик помилки throw e

import { setRouter } from "@x-fiber/proton";

export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: {
    GET: {
      scope: "private:user",
      params: [
        {
          name: 'userId',
          scope: 'required',
        }
      ],
      handler: async (request, agents, context) => {
        const { discovery } = agents.fnAgent;

        type Config = {
          integrations: {
            system1: {
              enable: boolean;
              path: string;
              fallbackPath: string;
            };
          };
          urls: {
            callbackUrl: string;
            robinUrls: string[]
          };
          retryNumber: number;
          certificatePath: string
        };

        const path = discovery.getMandatory<string, Config>("integrations.system1.path"); 
        console.log(path) // string environment or throw e
      },
    },
  },
});

getString

Метод для отримання конфігураційної змінної строкового типу або, в разі її відсутності - повернення значення за замовчуванням.

type ConfigParameter = string | boolean | number | (string | boolean | number)[]
type ExtendedObject = Record<string, ExtendedObject | ConfigParameter>

type KeyConfigLiteralBuilder<
    T,
    F extends ConfigParameter
> = T extends Record<string, unknown>
    ? {
        [K in keyof T]: T[K] extends F
            ? `${string & K}`
            : K extends string
                ? `${string & K}.${KeyConfigLiteralBuilder<T[K], F>}`
                : never;
    }[keyof T]
    : string;

type getString<C extends ExtendedObject = ExtendedObject> = (
        name: KeyConfigLiteralBuilder<C, string>,
        def: string
) => string;

де:

Тип функції: Синхронна.
Типи даних:
- ConfigParameter - Перелік можливих типів даних конфігурації.
- ExtendedObject - Тип обʼєкта, який передбачає будь-яку кількість вкладенностей, але кінцевим значенням повинен бути тип ConfigParameter.
- KeyConfigLiteralBuilder - Тип який аналізує тип конфігурації та надає відповідні шляхи доступу до можливих змінних.
- C - Тип обʼєкта конфігурації, який має структуру ExtendedObject
Аргументи:
1. Шлях доступу до змінної, який будується на основі структури типу конфігурації.
2. Значення за замовчуванням, яке буде повернуто, в разі відсутності змінної або даних в змінній.
Результат:
- Повернення змінної зі строковим типом або значення за замовчуванням

import { setRouter } from "@x-fiber/proton";

export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: {
    GET: {
      scope: "private:user",
      params: [
        {
          name: 'userId',
          scope: 'required',
        }
      ],
      handler: async (request, agents, context) => {
        const { discovery } = agents.fnAgent;

        type Config = {
          integrations: {
            system1: {
              enable: boolean;
              path: string;
              fallbackPath: string;
            };
          };
          urls: {
            callbackUrl: string;
            robinUrls: string[]
          };
          retryNumber: number;
          certificatePath: string
        };

        const url = discovery.getString<Config>("integrations.urls.callbackUrl", 'v1/result-callback'); 
        console.log(url) // string environment or 'v1/result-callback'
      },
    },
  },
});

getNumber

Метод для отримання конфігураційної змінної числового типу або, в разі її відсутності - повернення значення за замовчуванням.

type ConfigParameter = string | boolean | number | (string | boolean | number)[]
type ExtendedObject = Record<string, ExtendedObject | ConfigParameter>

type KeyConfigLiteralBuilder<
    T,
    F extends ConfigParameter
> = T extends Record<string, unknown>
    ? {
        [K in keyof T]: T[K] extends F
            ? `${string & K}`
            : K extends string
                ? `${string & K}.${KeyConfigLiteralBuilder<T[K], F>}`
                : never;
    }[keyof T]
    : string;

type getNumber<C extends ExtendedObject = ExtendedObject> = (
        name: KeyConfigLiteralBuilder<C, number>,
        def: number
) => string;

де:

Тип функції: Синхронна.
Типи даних:
- ConfigParameter - Перелік можливих типів даних конфігурації.
- ExtendedObject - Тип обʼєкта, який передбачає будь-яку кількість вкладенностей, але кінцевим значенням повинен бути тип ConfigParameter.
- KeyConfigLiteralBuilder - Тип який аналізує тип конфігурації та надає відповідні шляхи доступу до можливих змінних.
- C - Тип обʼєкта конфігурації, який має структуру ExtendedObject
Аргументи:
1. Шлях доступу до змінної, який будується на основі структури типу конфігурації.
2. Значення за замовчуванням, яке буде повернуто, в разі відсутності змінної або даних в змінній.
Результат:
- Повернення змінної з числовим типом або значення за замовчуванням

import { setRouter } from "@x-fiber/proton";

export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: {
    GET: {
      scope: "private:user",
      handler: async (request, agents, context) => {
        const { discovery } = agents.fnAgent;

        type Config = {
          integrations: {
            system1: {
              enable: boolean;
              path: string;
              fallbackPath: string;
            };
          };
          urls: {
            callbackUrl: string;
            robinUrls: string[]
          };
          retryNumber: number;
          certificatePath: string
        };

        const retryNumber = discovery.getNumber<Config>("integrations.retryNumber", 4); 
        console.log(retryNumber) // number environment or 4
      },
    },
  },
});

getBoolean

Метод для отримання конфігураційної змінної булевого типу або, в разі її відсутності - повернення значення за замовчуванням.

type ConfigParameter = string | boolean | number | (string | boolean | number)[]
type ExtendedObject = Record<string, ExtendedObject | ConfigParameter>

type KeyConfigLiteralBuilder<
    T,
    F extends ConfigParameter
> = T extends Record<string, unknown>
    ? {
        [K in keyof T]: T[K] extends F
            ? `${string & K}`
            : K extends string
                ? `${string & K}.${KeyConfigLiteralBuilder<T[K], F>}`
                : never;
    }[keyof T]
    : string;

type getBoolean<C extends ExtendedObject = ExtendedObject> = (
        name: KeyConfigLiteralBuilder<C, boolean>,
        def: boolean
) => string;

де:

Тип функції: Синхронна.
Типи даних:
- ConfigParameter - Перелік можливих типів даних конфігурації.
- ExtendedObject - Тип обʼєкта, який передбачає будь-яку кількість вкладенностей, але кінцевим значенням повинен бути тип ConfigParameter.
- KeyConfigLiteralBuilder - Тип який аналізує тип конфігурації та надає відповідні шляхи доступу до можливих змінних.
- C - Тип обʼєкта конфігурації, який має структуру ExtendedObject
Аргументи:
1. Шлях доступу до змінної, який будується на основі структури типу конфігурації.
2. Значення за замовчуванням, яке буде повернуто, в разі відсутності змінної або даних в змінній.
Результат:
- Повернення змінної з числовим типом або значення за замовчуванням

import { setRouter } from "@x-fiber/proton";

export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: {
    GET: {
      scope: "private:user",
      params: [
        {
          name: 'userId',
          scope: 'required',
        }
      ],
      handler: async (request, agents, context) => {
        const { discovery } = agents.fnAgent;

        type Config = {
          integrations: {
            system1: {
              enable: boolean;
              path: string;
              fallbackPath: string;
            };
          };
          urls: {
            callbackUrl: string;
            robinUrls: string[]
          };
          retryNumber: number;
          certificatePath: string
        };

        const isEnable = discovery.getBoolean<Config>("integrations.system1.enable", false); 
        console.log(isEnable) // boolean environment or false
      },
    },
  },
});

getArray

type ConfigParameter = string | boolean | number | (string | boolean | number)[]
type ExtendedObject = Record<string, ExtendedObject | ConfigParameter>

type KeyConfigLiteralBuilder<
    T,
    F extends ConfigParameter
> = T extends Record<string, unknown>
    ? {
        [K in keyof T]: T[K] extends F
            ? `${string & K}`
            : K extends string
                ? `${string & K}.${KeyConfigLiteralBuilder<T[K], F>}`
                : never;
    }[keyof T]
    : string;

type getArray<T, C extends ExtendedObject = ExtendedObject> = (
        name: KeyConfigLiteralBuilder<C, Array<T>>,
        def: Array<T>
) => Array<T>;

де:

Тип функції: Синхронна.
Типи даних:
- ConfigParameter - Перелік можливих типів даних конфігурації.
- ExtendedObject - Тип обʼєкта, який передбачає будь-яку кількість вкладенностей, але кінцевим значенням повинен бути тип ConfigParameter.
- KeyConfigLiteralBuilder - Тип який аналізує тип конфігурації та надає відповідні шляхи доступу до можливих змінних.
- T - Тип даних елементу масиву.
- C - Тип обʼєкта конфігурації, який має структуру ExtendedObject
Аргументи:
1. Шлях доступу до змінної, який будується на основі структури типу конфігурації.
2. Значення за замовчуванням, яке буде повернуто, в разі відсутності змінної або даних в змінній.
Результат:
- Повернення змінної з масивом значень або значення за замовчуванням

import { setRouter } from "@x-fiber/proton";

export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: {
    GET: {
      scope: "private:user",
      params: [
        {
          name: 'userId',
          scope: 'required',
        }
      ],
      handler: async (request, agents, context) => {
        const { discovery } = agents.fnAgent;

        type Config = {
          integrations: {
            system1: {
              enable: boolean;
              path: string;
              fallbackPath: string;
            };
          };
          urls: {
            callbackUrl: string;
            robinUrls: string[]
          };
          retryNumber: number;
          certificatePath: string
        };

        const urls = discovery.getArray<string, Config>("integrations.urls.robinUrls", []); 
        console.log(urls) // string[] environment or []
      },
    },
  },
});

getBuffer

Метод призначений для отримання буфера файлу або null або виклику помилки throw e в залежності від типу ознаки.

type ConfigParameter = string | boolean | number | (string | boolean | number)[]
type ExtendedObject = Record<string, ExtendedObject | ConfigParameter>

type KeyConfigLiteralBuilder<
    T,
    F extends ConfigParameter
> = T extends Record<string, unknown>
    ? {
        [K in keyof T]: T[K] extends F
            ? `${string & K}`
            : K extends string
                ? `${string & K}.${KeyConfigLiteralBuilder<T[K], F>}`
                : never;
    }[keyof T]
    : string;

type getBuffer<C extends ExtendedObject = ExtendedObject> = (
        name: KeyConfigLiteralBuilder<C, string>,
        err?: boolean
) => Promise<Buffer | null>;

де:

Тип функції: Асинхронна.
Типи даних:
- ConfigParameter - Перелік можливих типів даних конфігурації.
- ExtendedObject - Тип обʼєкта, який передбачає будь-яку кількість вкладенностей, але кінцевим значенням повинен бути тип ConfigParameter.
- KeyConfigLiteralBuilder - Тип який аналізує тип конфігурації та надає відповідні шляхи доступу до можливих змінних.
- C - Тип обʼєкта конфігурації, який має структуру ExtendedObject
Аргументи:
1. Шлях доступу до змінної, який будується на основі структури типу конфігурації.
2. Ознака дії, в разі відсутності файлу або невірного шляху до файлу, якщо false - повертати null, якщо true - викликати помилку.
Результат:
- Повернення буфера файлу або null або відбувається викликання помилки в разі ознаки err - true та відсутності файлу.

import { setRouter } from "@x-fiber/proton";

export const BusUsersAggRouter = setRouter<'getOne'>({
  getOne: {
    GET: {
      scope: "private:user",
      params: [
        {
          name: 'userId',
          scope: 'required',
        }
      ],
      handler: async (request, agents, context) => {
        const { discovery } = agents.fnAgent;

        type Config = {
          integrations: {
            system1: {
              enable: boolean;
              path: string;
              fallbackPath: string;
            };
          };
          urls: {
            callbackUrl: string;
            robinUrls: string[]
          };
          retryNumber: number;
          certificatePath: string
        };

        const cert = await iscovery.getBuffer<Config>("integrations.certificatePath", false); 
        console.log(cert) // buffer environment or 'null'
      },
    },
  },
});

`logger`

інформація

Простір імен logger призначений для організації роботи з логуванням. Логування здійснюється в відповідністю до рівня. Рівень логування та тип транспорту визначається конфігураційними параметрами.

небезпека

Опис переліку функцій простору імен logger знаходиться в активній розробці.

`utils`

інформація

Простір імен utils призначений для опису допоміжних загальних функцій, такий як uuid v4(), який надає унікальний ідентифікатор.

небезпека

Опис переліку допоміжних функцій простору імен utils знаходиться в активній розробці.

`scrambler`

інформація

Простір імен scrambler надає перелік методів шифрування, дешифрування чи хешування. Окрім цього простір імен надає можливість перевірки збігу хешів тощо.

небезпека

Опис переліку функцій простору імен scrambler знаходиться в активній розробці.

`sessions`

інформація

Простір імен sessions надає перелік методів по роботі з сесіями, ці методи полягають в можливості створити, закрити, оновити та інших можливостях роботи з сесіями.

небезпека

Опис переліку функцій простору імен sessions знаходиться в активній розробці.

`exception`

інформація

Простір імен exception надає перелік методів для генерації виключень. Різні типи виключень дозволяють генерувати та обробляти виключення ядром обчислень по різному.

небезпека

Опис переліку функцій простору імен exception знаходиться в активній розробці.

`permissions`

інформація

Простір імен permissions надає перелік методів для роботи з правами доступу. X-Fiber описує модель прав доступу через атрибути ролі. Так у відповідної ролі є набір атрибутів - доступні дії, представлення, події, тощо. В перспективі X-Fiber додасть також умови для організацію та власний атрибутивний склад. Таким чином простір імен permissions дозволяє створити роль, яка описує перелік атрибутів доступу.

небезпека

Опис переліку функцій простору імен permissions знаходиться в активній розробці.

`scheduler`

інформація

Простір імен scheduler надає перелік методів для прослуховування подій звʼязаних з виконанням дій, а також перелік методів по організації роботи з задачами планувальника задач.

небезпека

Опис переліку функцій простору імен scheduler знаходиться в активній розробці.

`fileStorage`

інформація

Простір імен fileStorage надає два простори імен - для організації роботи файлів, які зберігаються в памʼяті роботи вер-сервера, та організації роботи файлів, які зберігаються в Redis сховищі даних. Простір імен дозволяє організувати роботу з файлами.

небезпека

Опис переліку функцій простору імен fileStorage знаходиться в активній розробці.

`ws`

інформація

Простір імен ws надає перелік методів для генерації ws подій.

небезпека

Опис переліку функцій простору імен ws знаходиться в активній розробці.

`broker`

інформація

Простір імен broker надає перелік методів для генерації повідомлень, які відносяться до брокера повідомлень.

небезпека

Опис переліку функцій простору імен broker знаходиться в активній розробці.

`cache`

інформація

Простір імен cache надає перелік методів по роботі з кешуванням

небезпека

Опис переліку функцій простору імен cache знаходиться в активній розробці.

Агент функціональності

Структура агента​

discovery​

getMandatory​

getString​

getNumber​

getBoolean​

getArray​

getBuffer​

logger​

utils​

scrambler​

sessions​

exception​

permissions​

scheduler​

fileStorage​

ws​

broker​

cache​

Структура агента

discovery

getMandatory

getString

getNumber

getBoolean

getArray

getBuffer

`logger`

`utils`

`scrambler`

`sessions`

`exception`

`permissions`

`scheduler`

`fileStorage`

`ws`

`broker`

`cache`