Skip to content

Commit

Permalink
Обновил Readme.md, релиз
Browse files Browse the repository at this point in the history
  • Loading branch information
@cvaize
cvaize committed Mar 25, 2022
1 parent 4d52ae1 commit 22ab89c
Show file tree
Hide file tree
Showing 3 changed files with 253 additions and 15 deletions.
263 changes: 250 additions & 13 deletions Readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,255 @@
### В данный момент ведется разработка!!! Не используйте до выхода версии 1.0.

# Инструменты для декларативного программирования
Назначение данного инструмента облегчить типизацию, создавать схемы, которые можно будет использовать для проверки типов в процессе работы (runtime) JS. Данные инструменты, на данный момент, заточены на работу с Typescript языком, для облегчения типизации данных и написание тестов.
Назначение данного инструмента облегчить типизацию, гарантировать надежность и четкое соблюдение типов посредством создания схем, которые можно будет использовать для проверки типов в процессе работы (runtime) JS. Инструмент занимает всего 2.1кб `build/index.esm.min.js`, в зависимостях только `lodash`. Поддерживаемые форматы: esm, cjs, umd. Инструмент написан на TypeScript.

## Использование
Установка: `npm i declaration-tools`

Использование:
```js
// node.js
// ESM формат
import {makeSchema, checkSchema} from 'declaration-tools'
// Commonjs формат
const {makeSchema, checkSchema} = require('declaration-tools')

const data = [
{
"id": 116,
"group_id": 1,
"created_at": "2022-03-03 09:33:03",
"updated_at": "2022-03-07 07:48:14",
"addresses": [
{
"home": "123",
"street": "a123"
}
],
"full_addresses": [
"awd 123",
"123123 aws"
],
"categories": [
1,
24,
22
],
"dynamic": [
{
"home": "123",
"street": "a123"
},
24,
"123"
],
"extension_attributes": {
"is_subscribed": false
}
},
{
"id": 117,
"group_id": 1,
"created_at": "2022-03-03 09:33:03",
"addresses": [
{
"home": "123",
"street": "a123"
}
],
"full_addresses": [
"awd 123",
"123123 aws"
],
"categories": 22,
"dynamic": "12313",
"extension_attributes": {
"is_subscribed": false
}
},
8124,
"1231"
];
const schema = makeSchema(data);
// Добавление нового типа в массив, чтобы увидеть ответ ошибки
data.push(true);
const errors = checkSchema(schema, data);

console.log('schema = ', schema)
console.log('errors = ', errors)
```
```shell
$ node node.js
schema = { schema: { array: { object: [Object], number: {}, string: {} } } }
errors = [ { key: 'schema.array.boolean', type: 'type' } ]
```
## Формат схемы
Схема представляет собой объект с ключами, ключи являются возможными типами данных.
Для создания типов на основе различных JSON данные уже есть инструменты, такие как [quicktype.io](https://quicktype.io/).
Например, вот такие данные:
`tests/data/users.json`
```json
[
{
"id": 116,
"group_id": 1,
"created_at": "2022-03-03 09:33:03",
"updated_at": "2022-03-07 07:48:14",
"addresses": [
{
"home": "123",
"street": "a123"
}
],
"full_addresses": [
"awd 123",
"123123 aws"
],
"categories": [
1,
24,
22
],
"dynamic": [
{
"home": "123",
"street": "a123"
},
24,
"123"
],
"extension_attributes": {
"is_subscribed": false
}
},
{
"id": 117,
"group_id": 1,
"created_at": "2022-03-03 09:33:03",
"addresses": [
{
"home": "123",
"street": "a123"
}
],
"full_addresses": [
"awd 123",
"123123 aws"
],
"categories": 22,
"dynamic": "12313",
"extension_attributes": {
"is_subscribed": false
}
},
8124,
"1231"
]
```
## Применение:
В проектах с неконтролируемым развитием API, а так же в сложных API разработчик будет писать простые тесты в 3-4 строчки, а так же использовать проверку в runtime, для своевременного определения не состыковок между ожидаемыми данными и пришедшими с API.
преобразуются в схему: `tests/schemas/users.ts`
```typescript
import { Schema } from '../../src';

## Алгоритм использования:
export const usersSchema: Schema = {
schema: {
array: {
object: {
id: {
number: {},
},
group_id: {
number: {},
},
created_at: {
string: {},
},
updated_at: {
string: {},
undefined: {},
},
addresses: {
array: {
object: {
home: {
string: {},
},
street: {
string: {},
},
},
},
},
full_addresses: {
array: {
string: {},
},
},
categories: {
array: {
number: {},
},
number: {},
},
dynamic: {
array: {
object: {
home: {
string: {},
},
street: {
string: {},
},
},
number: {},
string: {},
},
string: {},
},
extension_attributes: {
object: {
is_subscribed: {
boolean: {},
},
},
},
},
number: {},
string: {},
},
},
};

export default usersSchema;
```
## Формат ошибок
Ответ ошибки представляет собой массив с объектами, следовательно, если массив пустой то и ошибок нет.
В объекте ошибки всегда есть ключ "key", чтобы понять по какому пути возникла ошибка, а так же ключ "type", чтобы понять какого рода эта ошибка.
```js
const error = {
key: 'schema.array.boolean',
type: 'type'
}
```
Есть всего 3 типа ошибок добавленных как перечисление.
```typescript
export enum SchemaErrorType {
// Новый ключ. По определенному пути найден ключ объекта, которого нет в схеме
key = 'key',
// Не совпал тип. Ключ со значением undefined, тоже сюда подходит.
// По определенному пути найдены данные с новым типом
type = 'type',
// Нет ключа. По определенному пути должен быть ключ с данными, но его нет
undefined = 'undefined',
}
```
## Применение
В проектах с неконтролируемым развитием API, а так же в сложных API разработчик может писать простые тесты в 3-4 строчки, а так же использовать проверку в runtime, для своевременного определения не состыковок между ожидаемыми данными и пришедшими с API.
## Алгоритм использования
1) Получать данные от API во время тестирования;
2) Создание схемы и типа на основе этих данных с помощью "declaration-tools";
Expand All @@ -17,9 +258,5 @@
5) Поместить в коде проекта функции проверки после получения данных и условие, чтобы эти проверки работали только в проекте во время разработки или тестирования, или на проектах с тестированием на "production";
6) Дополнительно: Отлавливать ошибки теста схемы на тестовой группе на production когда пользователи используют ваше приложение и отправлять отчеты на API логирования.
## Дорожная карта до версии 1.0:

1) Функция определения типа - 1;
2) Функция создания схемы - 1;
3) Функция проверки схемы - 1;
4) Настроить и собрать TS в JS - 0.
## Примечание
Для создания типов на основе различных JSON данные уже есть инструменты, такие как [quicktype.io](https://quicktype.io/). Следовательно, я решил такой инструмент не разрабатывать, если у вас есть идеи, что добавить, то пишите мне на почту: [email protected].
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "declaration-tools",
"version": "0.3.0",
"version": "1.0.0",
"description": "Инструменты для декларативного программирования.",
"main": "build/index.cjs.js",
"module": "build/index.esm.js",
Expand Down
3 changes: 2 additions & 1 deletion src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ export type Schema = {
export enum SchemaErrorType {
// Новый ключ. По определенному пути найден ключ объекта, которого нет в схеме
key = 'key',
// Не совпал тип. Ключ со значением undefined, тоже сюда подходит По определенному пути найдены данные с новым типом
// Не совпал тип. Ключ со значением undefined, тоже сюда подходит.
// По определенному пути найдены данные с новым типом
type = 'type',
// Нет ключа. По определенному пути должен быть ключ с данными, но его нет
undefined = 'undefined',
Expand Down

0 comments on commit 22ab89c

Please sign in to comment.