js-repository

@e22m4u/js-repository

Абстракция для работы с базами данных для Node.js

• Установка
• Введение
• Пример
• Источник данных
• Модель данных
• Репозиторий
• Фильтрация
• Связи
• Тесты

Установка

npm install @e22m4u/js-repository

Опционально устанавливаем адаптер. Например, если используется MongoDB, то для подключения потребуется установить адаптер mongodb как отдельную зависимость.

npm install @e22m4u/js-repository-mongodb-adapter

Доступные адаптеры

	описание
memory	виртуальная база в памяти процесса (не требует установки)
mongodb	MongoDB - система управления NoSQL базами (установка)

Введение

Источник, модель и репозиторий. Модуль позволяет спроектировать систему связанных данных с помощью источников и моделей. Источник описывает способ подключения к базе и место хранения данных, а модель структуру документа и связи между коллекциями. Непосредственно чтение и запись осуществляется репозиториями, которые можно получить после объявления моделей.

flowchart LR
  
A[Источник данных]-->B[Модель A]-->D[Репозиторий А]
A[Источник данных]-->C[Модель Б]-->E[Репозиторий Б]

Пример

Перед началом работы с коллекцией нужно определить источник и модель данных. Определения хранятся в экземпляре класса Schema, и первым шагом будет создание данного экземпляра.

import {Schema} from '@e22m4u/js-repository';

const schema = new Schema();

Интерфейс Schema имеет три основных метода:

• defineDatasource(datasourceDef: object): this - добавить источник
• defineModel(modelDef: object): this - добавить модель
• getRepository(modelName: string): Repository - получить репозиторий

Далее определяется источник и выбранный адаптер. Количество источников зависит от числа используемых баз данных.

schema.defineDatasource({
  name: 'myMemory', // название нового источника
  adapter: 'memory', // выбранный адаптер
});

Теперь добавим модель отражающую структуру документа. Представим коллекцию city с двумя полями, где строковое поле name в качестве названия города, и population как численность населения.

schema.defineModel({
  name: 'city', // название модели
  datasource: 'myMemory', // выбранный источник
  properties: {
    name: DataType.STRING, // поле типа "string"
    population: DataType.NUMBER, // поле типа "number"
  },
});

Модель гарантирует, что тип указанных полей будет проверен перед записью в коллекцию. Осталось получить репозиторий данной модели для чтения и записи документов.

// получаем репозиторий модели "city"
const cityRep = schema.getRepository('city');

// добавляем новый документ
const city = await cityRep.create({
  name: 'Moscow',
  population: 11980000,
});

// выводим результат
console.log(city);
// {
//   "id": 1,
//   "name": "Moscow",
//   "population": 11980000
// }

Последующие обращения к методу getRepository с названием модели city будут возвращать все тот же экземпляр репозитория данной модели по принципу «одиночки».

Источник данных

Каждый источник имеет свое уникальное название и выбранный адаптер. Экземпляр класса Schema имеет метод defineDatasource с помощью которого объявляется новый источник.

import {Schema} from '@e22m4u/js-repository';

const schema = new Schema();

schema.defineDatasource({
  name: 'datasource1', // название нового источника
  adapter: 'memory', // выбранный адаптер
});

Если адаптер имеет параметры, то они передаются с объектом определения источника.

schema.defineDatasource({
  name: 'datasource2',
  adapter: 'mongodb',
  // настройки адаптера "mongodb"
  host: '127.0.0.1',
  port: 27017,
  database: 'data'
});

Параметры источника:

• name: string уникальное название
• adapter: string выбранный адаптер
• параметры адаптера (если имеются)

Адаптер «memory»

Встроенный адаптер memory хранит данные в памяти процесса, не требует установки и отлично подходит для тестов и прототипирования.

import {Schema} from '@e22m4u/js-repository';

const schema = new Schema();

schema.defineDatasource({
  name: 'myMemory',
  adapter: 'memory', // адаптер "memory"
});

schema.defineModel({
  name: 'fruit',
  datasource: 'myMemory',
  properties: {
    name: DataType.STRING,
    description: DataType.STRING,
  },
});

const fruitRep = schema.getRepository('fruit');

const pineapple = fruitRep.create({
  name: 'Pineapple',
  description: 'A tropical fruit'
});

console.log(pineapple);
// {
//   "id": 1,
//   "name": "Pineapple",
//   "description": "A tropical fruit"
// }

Адаптер memory использует автоинкрементные идентификаторы типа number, но может принимать и строковые ключи, если их значение явно указано в документе.

// ...

const banana = fruitRep.create({
  id: 'fruit-1', // ключ типа "string"
  name: 'Banana',
  description: 'An edible fruit'
});

console.log(banana);
// {
//   "id": "fruit-1",
//   "name": 'Banana',
//   "description": "An edible fruit"
// }

Модель данных

Модель описывает структуру документа определенной коллекции. Экземпляр класса Schema имеет метод defineModel с помощью которого объявляется новая модель.

// объявление модели "region"
schema.defineModel({
  name: 'region', // название модели
  properties: { // поля модели
    name: DataType.STRING,
    population: DataType.NUMBER,
  },
});

// документ "region" может выглядеть так
// {
//   "id": 1,
//   "name": "Asia",
//   "population": 4753079727
// }

Параметры модели

• name: string название модели (обязательно)
• base: string название наследуемой модели
• tableName: string название коллекции в базе
• datasource: string выбранный источник данных
• properties: object определения полей модели
• relations: object определения связей (см. Связи)

Название модели

Название должно быть уникальным, так как оно используется для определения связей и соответствует названию коллекции в базе. При необходимости можно явно задать название коллекции параметром tableName, если оно не соответствует названию модели.

schema.defineModel({
  name: 'city', // название модели
  tableName: 'CITIES', // название коллекции
});

Источник данных

Если модель отражает реальную коллекцию базы, а не является частью другой, то указав название источника в параметре datasource можно получить репозиторий модели методом getRepository по ее названию.

// модель "city"
schema.defineModel({
  name: 'city',
  datasource: 'myDatasource', // выбранный источник
});

// репозиторий модели "city"
const cityRep = schema.getRepository('city');
// await cityRep.create({name: 'St. Petersburg'});
// ...

Поля документа

Параметр properties принимает объект, ключи которого являются именами полей, а значением тип поля или объект с дополнительными параметрами. Эти настройки используются для проверки данных перед сохранением в базу и установки значений по умолчанию (если имеются).

schema.defineModel({
  name: 'city',
  properties: {
    name: DataType.STRING, // поле "name" типа "string"
    population: { // поле "population" типа "number"
      type: DataType.NUMBER,
      default: 0, // значение по умолчанию
    },
  },
});

Параметры поля

• type: string тип допустимого значения (обязательно)
• itemType: string тип элемента массива (для type: 'array')
• model: string модель объекта (для type: 'object')
• primaryKey: boolean объявить поле первичным ключом
• columnName: string переопределение названия колонки
• columnType: string тип колонки (определяется адаптером)
• required: boolean объявить поле обязательным
• default: any значение по умолчанию

Типы данных

• DataType.ANY разрешено любое значение
• DataType.STRING только значение типа string
• DataType.NUMBER только значение типа number
• DataType.BOOLEAN только значение типа boolean
• DataType.ARRAY только значение типа array
• DataType.OBJECT только значение типа object

Когда требуется указать значение по умолчанию, установить флаг required или объявить более сложный тип допустимого значения, то вместо базового определения используется объект с расширенными настройками.

schema.defineModel({
  name: 'place',
  properties: {
    // базовое определение поля "name"
    name: DataType.STRING,
    // расширенное определение поля "location"
    // с дополнительными параметрами "model"
    // и "required"
    location: {
      type: DataType.OBJECT,
      model: 'latLng',
      required: true,
    },
    // расширенное определение поля "keywords"
    // с дополнительными параметрами "itemType"
    // и "default"
    keywords: {
      type: DataType.ARRAY,
      itemType: DataType.STRING,
      default: () => [],
    },
  },
});

Наследование

Модель может наследовать поля и связи используя параметр base, куда передается название базовой модели. При этом наследуемые настройки можно переопределять не затрагивая родителя.

// модель "area"
schema.defineModel({
  name: 'area',
  properties: {
    name: DataType.STRING,
    population: DataType.NUMBER,
  },
});

// модель "city"
schema.defineModel({
  name: 'city',
  base: 'area', // базовая модель
  properties: {
    timezone: DataType.STRING,
  },
});

// документ "city" может выглядеть так
// {
//   "id": 1,
//   "name": "Moscow", <= унаследовано
//   "population": 11980000, <= унаследовано
//   "timezone": "Europe/Moscow"
// }

Репозиторий

Объявление модели имеет необязательный параметр datasource, который указывает на источник хранения данных. Наличие источника позволяет получить репозиторий по названию такой модели. Репозиторий, в свою очередь, предоставляет интерфейс для чтения и записи данных этой модели.

import {Schema} from '@e22m4u/js-repository';

const schema = new Schema();

// объявление источника "myMemory"
schema.defineDatasource({
  name: 'myMemory',
  adapter: 'memory',
});

// объявление модели "city"
schema.defineModel({
  name: 'city',
  datasource: 'myMemory', // источник данных
  properties: {
    name: DataType.STRING,
    population: DataType.NUMBER,
  },
});

// получение репозитория модели "city"
const cityRep = schema.getRepository('city');

// записываем новый документ "city"
const city = await cityRep.create({
  name: 'Moscow',
  population: 11980000
});

// выводим результат
console.log(city);
// {
//   "id": 1,
//   "name": "Moscow",
//   "population": 11980000
// }

Методы

• create(data, filter = undefined) добавить новый документ
• replaceById(id, data, filter = undefined) заменить весь документ
• patchById(id, data, filter = undefined) частично обновить документ
• patch(data, where = undefined) обновить все документы или по условию
• find(filter = undefined) найти все документы или по условию
• findOne(filter = undefined) найти первый документ или по условию
• findById(id, filter = undefined) найти документ по идентификатору
• delete(where = undefined) удалить все документы или по условию
• deleteById(id) удалить документ по идентификатору
• exists(id) проверить существование по идентификатору
• count(where = undefined) подсчет всех документов или по условию

Параметры

• id идентификатор (первичный ключ)
• data объект отражающий состав документа
• where параметры выборки (см. Фильтрация)
• filter параметры возвращаемого результата (см. Фильтрация)

Фильтрация

Некоторые методы репозитория опционально принимают параметр where для условий выборки и/или параметр filter управляющий возвращаемым значением.

where

Рассмотрим применение параметра where на примере метода patch, который выполняет поиск и обновление документов по определенному условию.

Сигнатура метода patch(data, where = undefined) указывает на два параметра, где первый принимает объект данных, а второй является опциональным объектом выборки.

// вызов метода `patch`
await rep.patch(
  // обновить значения полей
  // "hidden" и "updatedAt"
  {
    hidden: true,
    updatedAt: new Date().toISOString(),
  },
  // только в тех документах, где поле "type"
  // равно значению "article", а "publishedAt"
  // содержит дату более раннюю, чем указана
  // в операторе "lte"
  {
    type: 'article',
    publishedAt: {
      lte: '2023-12-02T14:00:00.000Z',
    }
  },
);

Второй аргумент метода patch предыдущего листинга содержит условия выборки по которым будет выполнен поиск и обновление документов. Полный список возможных операторов сравнения приводится ниже.

{foo: 'bar'} поиск по значению поля foo
{foo: {eq: 'bar'}} оператор равенства eq
{foo: {neq: 'bar'}} оператор неравенства neq
{foo: {gt: 5}} оператор "больше" gt
{foo: {lt: 10}} оператор "меньше" lt
{foo: {gte: 5}} оператор "больше или равно" gte
{foo: {lte: 10}} оператор "меньше или равно" lte
{foo: {inq: ['bar', 'baz']}} равенство одного из значений inq
{foo: {nin: ['bar', 'baz']}} исключение значений массива nin
{foo: {between: [5, 10]}} оператор диапазона between
{foo: {exists: true}} оператор наличия значения exists
{foo: {like: 'bar'}} оператор поиска подстроки like
{foo: {ilike: 'BaR'}} регистронезависимая версия ilike
{foo: {nlike: 'bar'}} оператор исключения подстроки nlike
{foo: {nilike: 'BaR'}} регистронезависимая версия nilike
{foo: {regexp: 'ba.+'}} оператор регулярного выражения regexp
{foo: {regexp: 'ba.+', flags: 'i'}} флаги регулярного выражения

filter

Методы репозитория асинхронны и возвращают Promise с некоторым значением. Параметр filter позволяет влиять на это значение более широким образом, чем просто ограничение для затрагиваемых данных. Ниже представлен список опциональных полей объекта filter, одним из которых является where (рассматривался ранее).

• where объект выборки
• order указание порядка
• limit ограничение количества документов
• skip пропуск документов
• fields выбор необходимых полей документа
• include включение связанных данных в результат (см. Связи)

order

Документы могут быть отсортированы по указанным полям и в нужном направлении, где ASC - по умолчанию, и DESC - в обратном порядке.

// на примере метода "find"
const result = await rep.find({
  // упорядочить по полю "featured"
  order: 'featured',
  // по полю "featured" в обратном порядке
  order: 'featured DESC',
  // по нескольким полям в разных направлениях
  order: ['featured ASC', 'publishedAt DESC', 'id'],
});

limit и skip

При использовании метода find может потребоваться комбинация параметров limit и skip для механизма пагинации.

// первый параметр метода `find` принимает
// объект настроек возвращаемого результата
const result = await rep.find({
  limit: 12, // вернуть не более 14и документов
  skip: 24,  // пропустить 24 документа выборки
});

fields

Сократить объем документа можно параметром fields указав необходимый набор полей.

// на примере метода "find"
const result = await rep.find({
  // включить в результат только поле "title"
  fields: 'title',
  // или поле "title", "createdAt" и "featured" 
  fields: ['title', 'createdAt', 'featured'],
  // первичный ключ указывать не обязательно
});

Связи

WIP

Тесты

npm run test

Лицензия

MIT