@e22m4u/js-repository 0.7.0 → 0.8.0

package/.mocharc.json

@@ -1,5 +1,4 @@
 {
-  "extension": ["js", "ts"],
-  "spec": "src/**/*.spec.{js,ts}",
-  "require": ["ts-node/register"]
+  "extension": ["js"],
+  "spec": "src/**/*.spec.js"
 }

package/README.md

@@ -40,7 +40,6 @@
   - [Has One (полиморфная)](#has-one-полиморфная-версия)
   - [Has Many (полиморфная)](#has-many-полиморфная-версия)
 - [Расширение](#расширение)
-- [TypeScript](#typescript)
 - [Тесты](#тесты)
 - [Лицензия](#лицензия)
 
@@ -82,10 +81,10 @@ const {DatabaseSchema} = require('@e22m4u/js-repository');
 Кроме того, *модель* может определять классические связи «один к одному»,
 «один ко многим» и другие типы отношений между моделями.
 
-Непосредственно чтение и запись данных производится с помощью *репозитория*,
+Непосредственно чтение и запись данных производятся с помощью *репозитория*,
 который есть у каждой модели с объявленным *источником данных*. Репозиторий
 может фильтровать запрашиваемые документы, выполнять валидацию свойств
-согласно определению модели, и встраивать связанные данные в результат
+согласно определению модели и встраивать связанные данные в результат
 выборки.
 
 - *Источник данных* - определяет способ подключения к базе
@@ -257,17 +256,36 @@ console.log(cityWithCountry);
 
 ## Схема
 
-Экземпляр класса `DatabaseSchema` хранит определения источников данных и моделей.
+Экземпляр класса `DatabaseSchema` хранит определения источников данных
+и моделей.
 
 **Методы**
 
-- `defineDatasource(datasourceDef: object): this` - добавить источник
-- `defineModel(modelDef: object): this` - добавить модель
-- `getRepository(modelName: string): Repository` - получить репозиторий
+Добавить источник
 
-**Примеры**
+- `defineDatasource(datasourceDef)`
+  - `datasourceDef: object`: определение источника;
+  - результат: `this`;
+
+Добавить модель:
+
+- `defineModel(modelDef)`
+  - `modelDef: object`: определение модели;
+  - результат: `this`;
+
+Получить репозиторий
+
+- `getRepository(modelName)`
+  - `modelName: string` имя модели;
+  - результат: `Repository`;
+
+**Пример**
 
-Импорт класса и создание экземпляра схемы.
+Ниже приводится пошаговый пример настройки модели `product` и получения
+экземпляра репозитория, с помощью которого можно управлять данными этой
+коллекции.
+
+1\. Импорт класса и создание экземпляра схемы.
 
 ```js
 import {DatabaseSchema} from '@e22m4u/js-repository';
@@ -275,7 +293,7 @@ import {DatabaseSchema} from '@e22m4u/js-repository';
 const dbs = new DatabaseSchema();
 ```
 
-Определение нового источника.
+2\. Определение нового источника.
 
 ```js
 dbs.defineDatasource({
@@ -284,7 +302,7 @@ dbs.defineDatasource({
 });
 ```
 
-Определение новой модели.
+3\. Определение новой модели.
 
 ```js
 dbs.defineModel({
@@ -297,7 +315,7 @@ dbs.defineModel({
 });
 ```
 
-Получение репозитория по названию модели.
+4\. Получение репозитория по названию модели.
 
 ```js
 const productRep = dbs.getRepository('product');
@@ -370,7 +388,7 @@ dbs.defineModel({
 ## Свойства
 
 Параметр `properties` находится в определении модели и принимает объект, ключи
-которого являются свойствами этой модели, а значением тип свойства или объект
+которого являются свойствами этой модели, а значениями тип свойства или объект
 с дополнительными параметрами.
 
 **Тип данных**
@@ -396,15 +414,16 @@ dbs.defineModel({
 
 **Параметр `unique`**
 
-Если значением параметра `unique` является `true` или `'strict'`, то выполняется
-строгая проверка на уникальность. В этом режиме [пустые значения](#Пустые-значения)
-так же подлежат проверке, где `null` и `undefined` также считаются значениями,
-которые должны быть уникальными.
+Если значением параметра `unique` является `true` или `'strict'`,
+то выполняется строгая проверка на уникальность. В этом режиме
+[пустые значения](#Пустые-значения) так же подлежат проверке,
+где `null` и `undefined` также считаются значениями, которые
+должны быть уникальными.
 
-Режим `'sparse'` проверяет только значения с полезной нагрузкой, исключая
-[пустые значения](#Пустые-значения), список которых отличается в зависимости
-от типа свойства. Например, для типа `string` пустым значением будет `undefined`,
-`null` и `''` (пустая строка).
+Режим `'sparse'` проверяет только значения с полезной нагрузкой,
+исключая [пустые значения](#Пустые-значения), список которых отличается
+в зависимости от типа свойства. Например, для типа `string` пустыми
+значениями будут `undefined`, `null` и `''` (пустая строка).
 
 - `unique: true | 'strict'` строгая проверка на уникальность
 - `unique: 'sparse'` исключить из проверки [пустые значения](#Пустые-значения)
@@ -503,26 +522,15 @@ dbs.defineModel({
 **EmptyValuesService**
 
 Для переопределения пустых значений необходимо получить экземпляр класса
-`EmptyValuesService` из контейнера схемы и вызвать метод, который принимает
-тип данных и массив новых значений.
-
-Интерфейс:
-
-```ts
-class EmptyValuesService {
-  /**
-   * Установить пустые значения
-   * для определенного типа данных.
-   * 
-   * @param dataType    Тип данных.
-   * @param emptyValues Массив новых пустых значений.
-   */
-  setEmptyValuesOf(
-    dataType: DataType,
-    emptyValues: unknown[],
-  ): this;
-}
-```
+`EmptyValuesService` из контейнера схемы и вызвать метод `setEmptyValuesOf`,
+который принимает тип данных и массив новых значений.
+
+Сигнатура:
+
+- `setEmptyValuesOf(dataType, emptyValues)`
+  - `dataType: DataType`: строковый литерал типа;
+  - `emptyValues: *[]`: массив новых значений;
+  - результат: `this`;
 
 **Пример**
 
@@ -555,24 +563,24 @@ emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
 
 **Методы**
 
-- [`create(data, filter = undefined)`](#repositorycreate) создать новый документ;
-- [`replaceById(id, data, filter = undefined)`](#repositoryreplacebyid) заменить документ полностью;
-- [`replaceOrCreate(data, filter = undefined)`](#repositoryreplaceorcreate) заменить или создать новый;
-- [`patchById(id, data, filter = undefined)`](#repositorypatchbyid) обновить документ частично;
-- [`patch(data, where = undefined)`](#repositorypatch) обновить все документы или по условию;
-- [`find(filter = undefined)`](#repositoryfind) найти все документы или по условию;
-- [`findOne(filter = undefined)`](#repositoryfindone) найти первый документ или по условию;
-- [`findById(id, filter = undefined)`](#repositoryfindbyid) найти документ по идентификатору;
-- [`delete(where = undefined)`](#repositorydelete) удалить все документы или по условию;
+- [`create(data, [filter])`](#repositorycreate) создать новый документ;
+- [`replaceById(id, data, [filter])`](#repositoryreplacebyid) заменить документ полностью;
+- [`replaceOrCreate(data, [filter])`](#repositoryreplaceorcreate) заменить или создать новый;
+- [`patchById(id, data, [filter])`](#repositorypatchbyid) обновить документ частично;
+- [`patch(data, [where])`](#repositorypatch) обновить все документы или по условию;
+- [`find([filter])`](#repositoryfind) найти все документы или по условию;
+- [`findOne([filter])`](#repositoryfindone) найти первый документ или по условию;
+- [`findById(id, [filter])`](#repositoryfindbyid) найти документ по идентификатору;
+- [`delete([where])`](#repositorydelete) удалить все документы или по условию;
 - [`deleteById(id)`](#repositorydeletebyid) удалить документ по идентификатору;
 - [`exists(id)`](#repositoryexists) проверить существование по идентификатору;
-- [`count(where = undefined)`](#repositorycount) подсчет всех документов или по условию;
+- [`count([where])`](#repositorycount) подсчет всех документов или по условию;
 
 **Аргументы**
 
 - `id: number|string` идентификатор (первичный ключ)
 - `data: object` данные документа (используется при записи)
-- `where: object` условия фильтрации (см. [Фильтрация](#Фильтрация))
+- `where: object` условия выборки (см. [`where`](#where))
 - `filter: object` параметры выборки (см. [Фильтрация](#Фильтрация))
 
 **Получение репозитория**
@@ -612,12 +620,10 @@ const modelRep = dbs.getRepository('myModel');
 
 Сигнатура:
 
-```ts
-create(
-  data: WithOptionalId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `create(data, [filter])`
+  - `data: object`: данные нового документа;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -678,13 +684,11 @@ console.log(product);
 
 Сигнатура:
 
-```ts
-replaceById(
-  id: IdType,
-  data: WithoutId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `replaceById(id, data, [filter])`
+  - `id: number|string`: идентификатор документа;
+  - `data: object`: новые данные;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -720,12 +724,10 @@ console.log(updatedProduct);
 
 Сигнатура:
 
-```ts
-replaceOrCreate(
-  data: WithOptionalId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `replaceOrCreate(data, [filter])`
+  - `data: object`: данные документа;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -768,13 +770,11 @@ console.log(updatedProduct);
 
 Сигнатура:
 
-```ts
-patchById(
-  id: IdType,
-  data: PartialWithoutId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `patchById(id, data, [filter])`
+  - `id: number|string`: идентификатор обновляемого документа;
+  - `data: object`: новые данные;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -808,12 +808,10 @@ console.log(updatedProduct);
 
 Сигнатура:
 
-```ts
-patch(
-  data: PartialWithoutId<FlatData, IdName>,
-  where?: WhereClause<FlatData>,
-): Promise<number>;
-```
+- `patch(data, [where])`
+  - `data: object`: новые данные;
+  - `where?: object`: условия выборки (см. [`where`](#where));
+  - результат: `Promise<number>`;
 
 **Примеры**
 
@@ -843,9 +841,9 @@ const totalCount = await productRep.patch({
 
 Сигнатура:
 
-```ts
-find(filter?: FilterClause<FlatData>): Promise<FlatData[]>;
-```
+- `find([filter])`
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object[]>`;
 
 **Примеры**
 
@@ -879,11 +877,9 @@ const latestProducts = await productRep.find({
 
 Сигнатура:
 
-```ts
-findOne(
-  filter?: FilterClause<FlatData>,
-): Promise<FlatData | undefined>;
-```
+- `findOne([filter])`
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object|undefined>`;
 
 **Примеры**
 
@@ -914,12 +910,10 @@ if (!product) {
 
 Сигнатура:
 
-```ts
-findById(
-  id: IdType,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `findById(id, [filter])`
+  - `id: number|string`: идентификатор документа;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object|undefined>`;
 
 **Примеры**
 
@@ -950,9 +944,9 @@ const product = await productRep.findById(1, {
 
 Сигнатура:
 
-```ts
-delete(where?: WhereClause<FlatData>): Promise<number>;
-```
+- `delete([where])`
+  - `where?: object`: условия выборки (см. [`where`](#where));
+  - результат: `Promise<number>`;
 
 **Примеры**
 
@@ -977,9 +971,15 @@ const totalCount = await productRep.delete();
 
 Сигнатура:
 
-```ts
-deleteById(id: IdType): Promise<boolean>;
-```
+- `deleteById(id)`
+  - `id: number|string`: идентификатор документа;
+  - результат: `Promise<boolean>`;
+
+Результат:
+
+- `Promise<boolean>`: логическое значение;
+  - `true`: документ был найден и удален;
+  - `false`: документ не найден;
 
 **Примеры**
 
@@ -1001,9 +1001,15 @@ if (wasDeleted) {
 
 Сигнатура:
 
-```ts
-exists(id: IdType): Promise<boolean>;
-```
+- `exists(id)`
+  - `id: number|string`: идентификатор документа;
+  - результат: `Promise<boolean>`;
+
+Результат:
+
+- `Promise<boolean>`: логическое значение;
+  - `true`: документ с таким идентификатором найден;
+  - `false`: идентификатор не найден;
 
 **Примеры**
 
@@ -1023,9 +1029,9 @@ if (productExists) {
 
 Сигнатура:
 
-```ts
-count(where?: WhereClause<FlatData>): Promise<number>;
-```
+- `count([where])`
+  - `where?: object`: условия выборки (см. [`where`](#where));
+  - результат: `Promise<number>`;
 
 **Примеры**
 
@@ -1045,10 +1051,10 @@ const totalCount = await productRep.count();
 
 ## Фильтрация
 
-Некоторые методы репозитория принимают объект настроек, влияющий
-на возвращаемый результат. Максимально широкий набор таких настроек
-имеет первый параметр метода `find`, где ожидается объект содержащий
-набор опций указанных ниже.
+Некоторые методы репозитория принимают объект настроек возвращаемого
+результата. Максимально широкий набор таких настроек имеет первый
+параметр метода `find`, где ожидается объект, содержащий набор
+опций указанных ниже.
 
 - `where: object` условия фильтрации по свойствам документа;
 - `order: string|string[]` сортировка по указанным свойствам;
@@ -1917,7 +1923,7 @@ dbs.defineModel({
 
 #### Has One (полиморфная версия)
 
-Обратная сторона полиморфная связи `belongsTo` по принципу *"один к одному"*.
+Обратная сторона полиморфной связи `belongsTo` по принципу *"один к одному"*.
 
 ```
     Текущая (company)  <───────┐      Целевая (license)
@@ -1984,7 +1990,7 @@ dbs.defineModel({
 
 #### Has Many (полиморфная версия)
 
-Обратная сторона полиморфная связи `belongsTo` по принципу *"один ко многим"*.
+Обратная сторона полиморфной связи `belongsTo` по принципу *"один ко многим"*.
 
 ```
     Текущая (letter)  <─────────┐      Целевая (file)
@@ -2097,56 +2103,9 @@ const rep = dbs.getRepository('model');
 console.log(rep instanceof MyRepository); // true
 ```
 
-*i. Так как экземпляры репозитория кэшируется, то замену конструктора
+*i. Так как экземпляры репозитория кэшируются, то замену конструктора
 следует выполнять до обращения к методу `getRepository`.*
 
-## TypeScript
-
-Получение типизированного репозитория с указанием интерфейса модели.
-
-```ts
-import {DataType} from '@e22m4u/js-repository';
-import {RelationType} from '@e22m4u/js-repository';
-import {DatabaseSchema} from '@e22m4u/js-repository';
-
-// const dbs = new DatabaseSchema();
-// dbs.defineDatasource ...
-
-// определение модели "city"
-dbs.defineModel({
-  name: 'city',
-  datasource: 'myDatasource',
-  properties: {
-    name: DataType.STRING,
-    timeZone: DataType.STRING,
-  },
-});
-
-// определение интерфейса "city"
-interface City {
-  id: number;
-  name?: string;
-  timeZone?: string;
-}
-
-// при получении репозитория нужной модели
-// можно указать тип документов
-const cityRep = dbs.getRepository<City>('city');
-
-// теперь, методы репозитория возвращают
-// тип City вместо Record<string, unknown>
-const city: City = await cityRep.create({
-  name: 'Moscow',
-  timeZone: 'Europe/Moscow',
-});
-```
-
-Для определения моделей с помощью TypeScript классов,
-рекомендуется использовать специальную версию данного модуля
-[@e22m4u/ts-repository](https://www.npmjs.com/package/@e22m4u/ts-repository),
-поставляемую с набором TypeScript декораторов и дополнительных
-инструментов для работы в TypeScript окружении.
-
 ## Тесты
 
 ```bash