## @e22m4u/js-repository

![npm version](https://badge.fury.io/js/@e22m4u%2Fjs-repository.svg)
![license](https://img.shields.io/badge/license-mit-blue.svg)

[Русский](./README.md) | English

<br/>
<div align="center">
  <img alt="logo" src="assets/logo.png"/>
</div>
<br/>
<br/>

An implementation of the Repository pattern for working with databases in
Node.js.

- [Installation](#installation)
- [Importing](#importing)
- [Description](#description)
- [Example](#example)
- [Schema](#schema)
- [Datasource](#datasource)
- [Model](#model)
- [Properties](#properties)
- [Validators](#validators)
  - [Global Validators](#global-validators)
  - [Registering Global Validators](#registering-global-validators)
  - [Local Validators](#local-validators)
- [Transformers](#transformers)
  - [Global Transformers](#global-transformers)
  - [Registering Global Transformers](#registering-global-transformers)
  - [Local Transformers](#local-transformers)
- [Empty Values](#empty-values)
  - [Overriding Empty Values](#overriding-empty-values)
- [Repository](#repository)
  - [create](#repositorycreate)
  - [replaceById](#repositoryreplacebyid)
  - [replaceOrCreate](#repositoryreplaceorcreate)
  - [patchById](#repositorypatchbyid)
  - [patch](#repositorypatch)
  - [find](#repositoryfind)
  - [findOne](#repositoryfindone)
  - [findById](#repositoryfindbyid)
  - [delete](#repositorydelete)
  - [deleteById](#repositorydeletebyid)
  - [exists](#repositoryexists)
  - [count](#repositorycount)
- [Filtering](#filtering)
- [Relations](#relations)
  - [Belongs To](#belongs-to)
  - [Has One](#has-one)
  - [Has Many](#has-many)
  - [References Many](#references-many)
  - [Belongs To (polymorphic)](#belongs-to-polymorphic-version)
  - [Has One (polymorphic)](#has-one-polymorphic-version)
  - [Has Many (polymorphic)](#has-many-polymorphic-version)
- [Extending](#extending)
- [TypeScript](#typescript)
- [Tests](#tests)
- [License](#license)

## Installation

```bash
npm install @e22m4u/js-repository
```

Optionally, install the required adapter.

| adapter   | description                                                                                                                     |
|-----------|---------------------------------------------------------------------------------------------------------------------------------|
| `memory`  | An in-process memory database (no installation required)                                                                        |
| `mongodb` | MongoDB - a NoSQL database management system (*[install](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter)*) |

## Importing

The module supports both ESM and CommonJS standards.

*ESM*

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

*CommonJS*

```js
const {DatabaseSchema} = require('@e22m4u/js-repository');
```

## Description

The module allows you to abstract away from various database interfaces
by presenting them as named *datasources* connected to *models*.
A *Model* describes a database table (or collection), whose columns are the
model's properties. Model properties can have a specific *type* of allowed
value, a set of *validators*, and *transformers* that data passes through
before being written to the database. Additionally, a *model* can define
classic "one-to-one," "one-to-many," and other types of relationships
between models.

Data is read and written directly through a *repository*, which is available
for every model with a declared *datasource*. The repository can filter
queried documents, validate properties according to the model definition,
and embed related data into the query results.

- *Datasource* - defines how to connect to the database.
- *Model* - describes the document structure and relations to other models.
- *Repository* - performs read and write operations for model documents.

```mermaid
flowchart TD

  A[Schema]
  subgraph Databases
    B[Datasource 1]
    C[Datasource 2]
  end
  A-->B
  A-->C

  subgraph Collections
    D[Model A]
    E[Model B]
    F[Model C]
    G[Model D]
  end
  B-->D
  B-->E
  C-->F
  C-->G

  H[Repository A]
  I[Repository B]
  J[Repository C]
  K[Repository D]
  D-->H
  E-->I
  F-->J
  G-->K
```

## Example

This example demonstrates creating a schema instance, declaring a datasource,
and a `country` model. Then, using the model's repository, a new document
(a country) is added to the collection and logged to the console.

```
   Country (country)
┌─────────────────────────┐
│  id: 1                  │
│  name: "Russia"         │
│  population: 143400000  │
└─────────────────────────┘
```

```js
import {DataType} from '@e22m4u/js-repository';
import {DatabaseSchema} from '@e22m4u/js-repository';

// create a DatabaseSchema instance
const dbs = new DatabaseSchema();

// declare the "myDb" datasource
dbs.defineDatasource({
  name: 'myDb',      // name of the new datasource
  adapter: 'memory', // chosen adapter
});

// declare the "country" model
dbs.defineModel({
  name: 'country',    // name of the new model
  datasource: 'myDb', // chosen datasource
  properties: {       // model properties
    name: DataType.STRING,       // type "string"
    population: DataType.NUMBER, // type "number"
  },
})

// get the model's repository
const countryRep = dbs.getRepository('country');

// add a new document to the collection
const country = await countryRep.create({
  name: 'Russia',
  population: 143400000,
});

// log the new document
console.log(country);
// {
//   id: 1,
//   name: 'Russia',
//   population: 143400000,
// }
```

The next block defines a `city` model with a `belongsTo` relation to the
`country` model from the example above. Then, a new city document is created,
linked to the previously created country. After creating the new document, a
query is executed to retrieve this city with its related country included.

```
   Country (country)                  City (city)
┌─────────────────────────┐       ┌─────────────────────────┐
│  id: 1  <───────────────│───┐   │  id: 1                  │
│  name: "Russia"         │   │   │  name: "Moscow"         │
│  population: 143400000  │   └───│─ countryId: 1           │
└─────────────────────────┘       └─────────────────────────┘
```

```js
// declare the "city" model with a relation to "country"
dbs.defineModel({
  name: 'city',
  datasource: 'myDb',
  properties: {
    name: DataType.STRING,
    countryId: DataType.NUMBER,
    // defining the "countryId" foreign key is not strictly necessary,
    // but it is recommended for type validation before writing to the
    // database, as the "memory" adapter creates numeric IDs by default
  },
  relations: {
    // defining the "country" relation allows for automatic inclusion
    // of related documents using the "include" option in repository methods
    country: {
      type: RelationType.BELONGS_TO, // relation type: belongs to...
      model: 'country',              // target model name
      foreignKey: 'countryId',       // foreign key field (optional)
      // if the foreign key follows the `relationName` + `Id` convention,
      // the `foreignKey` option is not required.
    },
  },
});

// get the repository for the "city" model
const cityRep = dbs.getRepository('city');

// create a new city and link it to the country via country.id
const city = await cityRep.create({
  name: 'Moscow',
  countryId: country.id, // use the id from the previously created country
});

console.log(city);
// {
//   id: 1,
//   name: 'Moscow',
//   countryId: 1,
// }

// retrieve the city by its ID, including the related country
const cityWithCountry = await cityRep.findById(city.id, {
  include: 'country',
});

console.log(cityWithCountry);
// {
//   id: 1,
//   name: 'Moscow',
//   countryId: 1,
//   country: {
//     id: 1,
//     name: 'Russia',
//     population: 143400000
//   }
// }
```

## Schema

An instance of the `DatabaseSchema` class stores datasource and model
definitions.

**Methods**

- `defineDatasource(datasourceDef: object): this` - add a datasource
- `defineModel(modelDef: object): this` - add a model
- `getRepository(modelName: string): Repository` - get a repository

**Examples**

Import the class and create a schema instance.

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

const dbs = new DatabaseSchema();
```

Define a new datasource.

```js
dbs.defineDatasource({
  name: 'myDb',      // name of the new datasource
  adapter: 'memory', // chosen adapter
});
```

Define a new model.

```js
dbs.defineModel({
  name: 'product',   // name of the new model
  datasource: 'myDb',// chosen datasource
  properties: {      // model properties
    name: DataType.STRING,
    weight: DataType.NUMBER,
  },
});
```

Get a repository by the model name.

```js
const productRep = dbs.getRepository('product');
```

## Datasource

A datasource stores the name of the selected adapter and its settings.
A new datasource is defined using the `defineDatasource` method of a
`DatabaseSchema` instance.

**Parameters**

- `name: string` a unique name
- `adapter: string` the chosen adapter
- adapter-specific parameters (if any)

**Examples**

Define a new datasource.

```js
dbs.defineDatasource({
  name: 'myDb',      // name of the new datasource
  adapter: 'memory', // chosen adapter
});
```

Passing additional parameters, using the MongoDB adapter as an example
(*[install](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter)*).

```js
dbs.defineDatasource({
  name: 'myDb',
  adapter: 'mongodb',
  // parameters for the "mongodb" adapter
  host: '127.0.0.1',
  port: 27017,
  database: 'myDatabase',
});
```

## Model

Describes the structure of a collection's documents and its relations to
other models. A new model is defined using the `defineModel` method of a
`DatabaseSchema` instance.

**Parameters**

- `name: string` model name (required)
- `base: string` name of the base model to inherit from
- `tableName: string` name of the collection in the database
- `datasource: string` the chosen datasource
- `properties: object` property definitions (see [Properties](#properties))
- `relations: object` relation definitions (see [Relations](#relations))

**Examples**

Define a model with properties of specified types.

```js
dbs.defineModel({
  name: 'user', // name of the new model
  properties: { // model properties
    name: DataType.STRING,
    age: DataType.NUMBER,
  },
});
```

## Properties

The `properties` parameter in a model definition accepts an object where keys
are property names and values are either the property type or an object with
additional parameters.

**Data Types**

- `DataType.ANY` any value is allowed
- `DataType.STRING` only `string` values
- `DataType.NUMBER` only `number` values
- `DataType.BOOLEAN` only `boolean` values
- `DataType.ARRAY` only `array` values
- `DataType.OBJECT` only `object` values

**Parameters**

- `type: string` the allowed value type (required)
- `itemType: string` array item type (for `type: 'array'`)
- `model: string` object model (for `type: 'object'`)
- `primaryKey: boolean` declares the property as a primary key
- `columnName: string` overrides the column name
- `columnType: string` column type (defined by the adapter)
- `required: boolean` declares the property as required
- `default: any` default value
- `validate: string | Function | array | object` see [Validators](#validators)
- `unique: boolean | string` check value for uniqueness

**The `unique` Parameter**

If the `unique` parameter is `true` or `'strict'`, a strict uniqueness
check is performed. In this mode, [empty values](#empty-values) are also
checked, where `null` and `undefined` are considered values that must be
unique.

The `'sparse'` mode only checks values with a payload, excluding
[empty values](#empty-values), the list of which varies depending on the
property type. For example, for a `string` type, empty values are
`undefined`, `null`, and `''` (an empty string).

- `unique: true | 'strict'` strict uniqueness check
- `unique: 'sparse'` exclude [empty values](#empty-values) from the check
- `unique: false | 'nonUnique'` do not check for uniqueness (default)

You can use predefined constants as equivalents for the string values
`strict`, `sparse`, and `nonUnique`.

- `PropertyUniqueness.STRICT`
- `PropertyUniqueness.SPARSE`
- `PropertyUniqueness.NON_UNIQUE`

**Examples**

Short-form property definition.

```js
dbs.defineModel({
  name: 'city',
  properties: { // model properties
    name: DataType.STRING,       // property type "string"
    population: DataType.NUMBER, // property type "number"
  },
});
```

Full-form property definition.

```js
dbs.defineModel({
  name: 'city',
  properties: { // model properties
    name: {
      type: DataType.STRING, // property type "string" (required)
      required: true,        // disallows undefined and null values
    },
    population: {
      type: DataType.NUMBER, // property type "number" (required)
      default: 0,            // default value
    },
    code: {
      type: DataType.NUMBER,             // property type "number" (required)
      unique: PropertyUniqueness.STRICT, // check for uniqueness
    },
  },
});
```

Factory default value. The function's return value will be determined at the
time the document is written.

```js
dbs.defineModel({
  name: 'article',
  properties: { // model properties
    tags: {
      type: DataType.ARRAY,     // property type "array" (required)
      itemType: DataType.STRING,// item type "string"
      default: () => [],        // factory value
    },
    createdAt: {
      type: DataType.STRING, // property type "string" (required)
      default: () => new Date().toISOString(), // factory value
    },
  },
});
```

## Validators

Validators are used to check a property's value before writing it to the
database. Validation occurs immediately after the type check specified in the
model's property definition. [Empty values](#empty-values) bypass validators
as they have no payload.

### Global Validators

The module comes with a set of global validators:

- `regexp` validates against a regular expression,
  *parameter: `string | RegExp` - the regular expression;*

- `maxLength` maximum length for a string or array,
  *parameter: `number` - the maximum length;*

- `minLength` minimum length for a string or array,
  *parameter: `number` - the minimum length;*

The validators below are under development:

- `isLowerCase` checks for lowercase letters only;
- `isUpperCase` checks for uppercase letters only;
- `isEmail` checks for a valid email format;

**Examples**

Using a global validator.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    email: {
      type: DataType.STRING,
      validate: 'isEmail',
    },
  },
});
```

Using global validators as an array.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    email: {
      type: DataType.STRING,
      validate: [
        'isEmail',
        'isLowerCase',
      ],
    },
  },
});
```

Using global validators with arguments.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    name: {
      type: DataType.STRING,
      validate: {
        minLength: 2,
        maxLength: 24,
        regexp: /^[a-zA-Z-']+$/,
      },
    },
  },
});
```

Global validators without parameters can accept any arguments.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    email: {
      type: DataType.STRING,
      validate: {
        maxLength: 100,
        // since the "isEmail" validator has no parameters,
        // its definition allows any value to be passed
        // as an argument
        isEmail: true,
      },
    },
  },
});
```

### Registering Global Validators

A validator is a function that receives the value of the corresponding field
before it is written to the database. If the function returns `false` during
validation, a standard error is thrown. You can replace the standard error
by throwing a custom error directly inside the validation function.

A global validator is registered using the `addValidator` method of the
`PropertyValidatorRegistry` service, which takes the validator name and the
validation function.

**Examples**

Registering a global validator to check UUID format.

```js
import {createError} from 'http-errors';
import {format} from '@e22m4u/js-format';
import {Errorf} from '@e22m4u/js-format';
import {PropertyValidatorRegistry} from '@e22m4u/js-repository';

// get the service instance
const pvr = dbs.getService(PropertyValidatorRegistry);

// regular expressions for different UUID versions
const uuidRegex = {
  any: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
  v4: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
};

// register the global validator "isUuid",
// which accepts a settings object with a "version" property.
pvr.addValidator('isUuid', (value, options, context) => {
  // value   - the value being validated;
  // options - validator parameters;
  // context - information about the property being validated;
  console.log(options);
  // {
  //   version: 'v4'
  // }
  console.log(context);
  // {
  //   validatorName: 'isUuid',
  //   modelName: 'device',
  //   propName: 'deviceId'
  // }

  // empty values are not passed to validators
  // (the condition below will never trigger)
  if (typeof value !== 'string') return false;
  // find the regex for the specified UUID version
  // (from the validator's options)
  const version = options?.version || 'any';
  const regex = uuidRegex[version];
  // if the regex is not found,
  // an internal error is thrown
  if (!regex)
    throw new Errorf(
      'Invalid UUID version %v specified for validator.',
      version,
    );
  // if validation fails, a 400 BadRequest
  // error is thrown
  if (!regex.test(value)) {
    const versionString = version !== 'any' ? ` (version ${version})` : '';
    throw createError(400, format(
      'The property %v of the model %v must be a valid UUID%s.',
      context.propName,
      context.modelName,
      versionString,
    ));
  }
  // on successful validation, return true;
  // otherwise, a standard validation error
  // will be thrown
  return true;
});
```

Using the global validator in a property definition.

```js
// define the "device" model
dbs.defineModel({
  name: 'device',
  properties: {
    deviceId: {
      type: DataType.STRING,
      required: true,
      validate: {
        // the value {version: 'v4'} will be passed as the second
        // argument to the validator function
        isUuid: {version: 'v4'},
      },
    },
  },
});
```

### Local Validators

A validator function can be passed directly in the property definition without
prior registration. To do this, simply pass the function to the `validate`
parameter as a value or as an array element alongside other validators.

**Examples**

Using a local validator to check password strength.

```js
// the `passwordStrength` validator checks password complexity
function passwordStrength(value, options, context) {
  // value   - the value being validated;
  // options - not used;
  // context - information about the property;
  console.log(context);
  // {
  //   validatorName: 'passwordStrength',
  //   modelName: 'user',
  //   propName: 'password'
  // }
  const errors = [];
  if (value.length < 8)
    errors.push('must be at least 8 characters long');
  if (!/\d/.test(value))
    errors.push('must contain at least one number');
  if (!/[a-zA-Z]/.test(value))
    errors.push('must contain at least one letter');
  // if any condition is met,
  // an error is thrown
  if (errors.length > 0)
    throw createError(400, format(
      'Value of the property %v of the model %v %s.',
      context.propName,
      context.modelName,
      errors.join(', '),
    ));
  // on successful validation, return true;
  // otherwise, a standard validation error
  // will be thrown
  return true;
}

// define the "user" model
dbs.defineModel({
  name: 'user',
  properties: {
    password: {
      type: DataType.STRING,
      required: true,
      validate: passwordStrength, // <=
      // or
      // validate: [passwordStrength, ...]
    },
  },
});
```

Using an anonymous validator function to check a slug.

```js
// define the "article" model
dbs.defineModel({
  name: 'article',
  properties: {
    slug: {
      type: DataType.STRING,
      validate: (value) => {
        const re = /^[a-z0-9]+(-[a-z0-9]+)*$/;
        return re.test(value);
      },
    },
  },
});
```

## Transformers

Transformers are used to modify a property's value before type checking and
sending the data to the database. Transformers allow for automatic cleaning
or formatting of data. [Empty values](#empty-values) are not passed to
transformers as they have no payload.

### Global Transformers

The module comes with a set of global transformers:

- `trim` removes whitespace from the beginning and end of a string;
- `toUpperCase` converts a string to uppercase;
- `toLowerCase` converts a string to lowercase;

The transformers below are under development:

- `cut` truncates a string or array to the specified length,
  *parameter: `number` - the maximum length;*

- `truncate` truncates a string and appends an ellipsis,
  *parameter: `number` - the maximum length;*

- `capitalize` converts the first letter of each word to uppercase,
  *parameter: `{firstWordOnly?: boolean}`;*

**Examples**

Using a global transformer.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    username: {
      type: DataType.STRING,
      transform: 'toLowerCase',
    },
  },
});
```

Using global transformers as an array.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    firstName: {
      type: DataType.STRING,
      transform: [
        'trim',
        'capitalize',
      ],
    },
  },
});
```

Using global transformers with arguments.

```js
dbs.defineModel({
  name: 'article',
  properties: {
    annotation: {
      type: DataType.STRING,
      transform: {
        truncate: 200,
        capitalize: {firstWordOnly: true},
      },
    },
  },
});
```

Global transformers without parameters can accept any arguments.

```js
dbs.defineModel({
  name: 'user',
  properties: {
    firstName: {
      type: DataType.STRING,
      transform: {
        cut: 60,
        // since the "trim" transformer has no parameters,
        // its definition allows any value to be passed
        // as an argument
        trim: true,
      },
    },
  },
});
```

### Registering Global Transformers

A transformer is a function that takes a property's value and returns a new
value. The function can be either synchronous or asynchronous (return a
`Promise`).

A global transformer is registered using the `addTransformer` method of the
`PropertyTransformerRegistry` service, which takes the transformer name and
the function itself.

**Examples**

Registering a global transformer to remove HTML tags.

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

// get the service instance
const ptr = dbs.getService(PropertyTransformerRegistry);

// register the global transformer "stripTags"
ptr.addTransformer('stripTags', (value, options, context) => {
  // value   - the value being transformed;
  // options - transformer settings (if provided);
  // context - information about the property;
  console.log(context);
  // {
  //   transformerName: 'stripTags',
  //   modelName: 'comment',
  //   propName: 'text'
  // }
  
  if (typeof value !== 'string')
    return value; // return as is if not a string
  
  return value.replace(/<[^>]*>?/gm, '');
});
```

Using the global transformer in a model definition.

```js
dbs.defineModel({
  name: 'comment',
  properties: {
    text: {
      type: DataType.STRING,
      transform: 'stripTags',
    },
  },
});
```

### Local Transformers

A transformer function can be passed directly in the property definition
without prior registration. To do this, simply pass the function to the
`transform` parameter as a value or as an array element.

**Examples**

Using a local transformer to normalize names.

```js
// function to normalize a name
function normalizeName(value, options, context) {
  // value   - the value being transformed
  // options - not used
  // context - information about the property
  if (!value || typeof value !== 'string') return value;
  return value
    .trim()        // remove leading/trailing whitespace
    .toLowerCase() // convert to lowercase
    .split(' ')    // split into words
    // capitalize the first letter of each word
    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');    // join the array back into a string
}

// define the "user" model
dbs.defineModel({
  name: 'user',
  properties: {
    firstName: {
      type: DataType.STRING,
      transform: normalizeName, // <=
    },
    lastName: {
      type: DataType.STRING,
      transform: normalizeName, // <=
    },
  },
});
```

Using a local asynchronous transformer to hash a password.

```js
import * as bcrypt from 'bcrypt';

// asynchronous function to hash a value
async function hash(value, options, context) {
  // value   - the value being transformed
  // options - not used
  // context - information about the property
  console.log(context);
  // {
  //   transformerName: 'hash',
  //   modelName: 'user',
  //   propName: 'password'
  // }
  const saltRounds = 10;
  return bcrypt.hash(value, saltRounds);
}

// define the "user" model
dbs.defineModel({
  name: 'user',
  properties: {
    password: {
      type: DataType.STRING,
      transform: hash, // <=
      // or
      // transform: [hash, ...]
    },
  },
});
```

Using an anonymous transformer function to correct a slug.

```js
dbs.defineModel({
  name: 'article',
  properties: {
    slug: {
      type: DataType.STRING,
      transform: (value) => {
        if (typeof value !== 'string') return value;
        return value.toLowerCase().replace(/\s+/g, '-');
      },
    },
  },
});
```

## Empty Values

Different property types have their own sets of empty values. These sets are
used to determine if a property's value has a payload. For example, the
`default` parameter in a property definition sets a default value only if the
incoming value is empty. The `required` parameter disallows empty values by
throwing an error. And the `unique` parameter in `sparse` mode allows
duplicate empty values for a unique property, as they are not included in the
uniqueness check.

| type        | empty values              |
|-------------|---------------------------|
| `'any'`     | `undefined`, `null`       |
| `'string'`  | `undefined`, `null`, `''` |
| `'number'`  | `undefined`, `null`, `0`  |
| `'boolean'` | `undefined`, `null`       |
| `'array'`   | `undefined`, `null`, `[]` |
| `'object'`  | `undefined`, `null`, `{}` |

### Overriding Empty Values

The set of empty values for any data type can be overridden. These sets are
managed through a special service provided by the
[@e22m4u/js-empty-values](https://www.npmjs.com/package/@e22m4u/js-empty-values)
module (no installation required).

**EmptyValuesService**

To override empty values, you need to get an instance of the
`EmptyValuesService` class from the schema's container and call the method
that accepts the data type and an array of new values.

Interface:

```ts
class EmptyValuesService {
  /**
   * Set empty values
   * for a specific data type.
   * 
   * @param dataType    The data type.
   * @param emptyValues An array of new empty values.
   */
  setEmptyValuesOf(
    dataType: DataType,
    emptyValues: unknown[],
  ): this;
}
```

**Example**

By default, the value `0` is considered empty for numeric properties. The
following example shows how to change this behavior, leaving only `undefined`
and `null` as empty values.

```js
import {DataType} from '@e22m4u/js-repository';
import {DatabaseSchema} from '@e22m4u/js-repository';
import {EmptyValuesService} from '@e22m4u/js-empty-values';

const dbs = new DatabaseSchema();

// get the service for working with empty values
const emptyValuesService = dbs.getService(EmptyValuesService);

// override empty values for the DataType.NUMBER type
emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
```

After this, the value `0` for properties of type `DataType.NUMBER` will no
longer be considered empty, will pass validator checks, and will not be
replaced by a default value.

## Repository

The repository performs read and write operations for a specific model's data.
It acts as an intermediary between the application's business logic and the
database.

**Methods**

- [`create(data, filter = undefined)`](#repositorycreate) creates a new document;
- [`replaceById(id, data, filter = undefined)`](#repositoryreplacebyid) completely replaces a document;
- [`replaceOrCreate(data, filter = undefined)`](#repositoryreplaceorcreate) replaces or creates a new document;
- [`patchById(id, data, filter = undefined)`](#repositorypatchbyid) partially updates a document;
- [`patch(data, where = undefined)`](#repositorypatch) updates all or matching documents;
- [`find(filter = undefined)`](#repositoryfind) finds all or matching documents;
- [`findOne(filter = undefined)`](#repositoryfindone) finds the first matching document;
- [`findById(id, filter = undefined)`](#repositoryfindbyid) finds a document by its ID;
- [`delete(where = undefined)`](#repositorydelete) deletes all or matching documents;
- [`deleteById(id)`](#repositorydeletebyid) deletes a document by its ID;
- [`exists(id)`](#repositoryexists) checks for existence by ID;
- [`count(where = undefined)`](#repositorycount) counts all or matching documents;

**Arguments**

- `id: number|string` identifier (primary key)
- `data: object` document data (used for writing)
- `where: object` filter conditions (see [Filtering](#filtering))
- `filter: object` query parameters (see [Filtering](#filtering))

**Getting a Repository**

You can get a repository using the `getRepository()` method of a
`DatabaseSchema` instance. The method takes the model name as an argument.
The model must have a defined [datasource](#datasource), as the repository
interacts directly with the database through the adapter specified in the
datasource.

```js
// declare a datasource
dbs.defineDatasource({
  name: 'myDatasource',
  adapter: 'memory', // adapter
});

// declare a model
dbs.defineModel({
  name: 'myModel',
  datasource: 'myDatasource',
  // properties: { ... },
  // relations: { ... }
});

// get the model's repository
const modelRep = dbs.getRepository('myModel');
```

The first time `getRepository('myModel')` is called, a new repository instance
is created and cached. All subsequent calls with the same model name will
return the existing instance.

### repository.create

Creates a new document in the collection based on the provided data. Returns
the created document with an assigned identifier.

Signature:

```ts
create(
  data: WithOptionalId<FlatData, IdName>,
  filter?: ItemFilterClause<FlatData>,
): Promise<FlatData>;
```

**Examples**

Create a new document.

```js
const newProduct = await productRep.create({
  name: 'Laptop',
  price: 1200,
});
console.log(newProduct);
// {
//   id: 1,
//   name: 'Laptop',
//   price: 1200,
// }
```

Create a document, returning only specific fields.

```js
const product = await productRep.create(
  {name: 'Mouse', price: 25},
  {fields: ['id', 'name']},
);
console.log(product);
// {
//   id: 2,
//   name: 'Mouse',
// }
```

Create a document, including related data in the result.

```js
// assumes the Product model has a "category" relation
// (the "include" option only affects the returned result)
const product = await productRep.create(
  {name: 'Keyboard', price: 75, categoryId: 10},
  {include: 'category'},
);
console.log(product);
// {
//   id: 3,
//   name: 'Keyboard',
//   price: 75,
//   categoryId: 10,
//   category: {id: 10, name: 'Electronics'}
// }
```

### repository.replaceById

Completely replaces an existing document by its identifier. All previous data
in the document, except the identifier, is removed. Fields not provided in
`data` will be absent from the final document (unless they have a default
value).

Signature:

```ts
replaceById(
  id: IdType,
  data: WithoutId<FlatData, IdName>,
  filter?: ItemFilterClause<FlatData>,
): Promise<FlatData>;
```

**Examples**

Replace a document by its identifier.

```js
// original document
// {
//   id: 1,
//   name: 'Laptop',
//   price: 1200,
//   inStock: true
// }

const updatedProduct = await productRep.replaceById(1, {
  name: 'Laptop Pro',
  price: 1500,
});
console.log(updatedProduct);
// {
//   id: 1,
//   name: 'Laptop Pro',
//   price: 1500
// }
// the "inStock" property is removed
```

### repository.replaceOrCreate

Replaces an existing document if the provided data includes an identifier that
already exists in the collection. Otherwise, if the identifier is not
provided or not found, it creates a new document.

Signature:

```ts
replaceOrCreate(
  data: WithOptionalId<FlatData, IdName>,
  filter?: ItemFilterClause<FlatData>,
): Promise<FlatData>;
```

**Examples**

Create a new document if `id: 3` does not exist.

```js
const product = await productRep.replaceOrCreate({
  id: 3,
  name: 'Keyboard',
  price: 75,
});
console.log(product);
// {
//   id: 3,
//   name: 'Keyboard',
//   price: 75,
// }
```

Replace an existing document with `id: 1`.

```js
const updatedProduct = await productRep.replaceOrCreate({
  id: 1,
  name: 'Laptop Pro',
  price: 1500,
});
console.log(updatedProduct);
// {
//   id: 1,
//   name: 'Laptop Pro',
//   price: 1500,
// }
```

### repository.patchById

Partially updates an existing document by its identifier, modifying only the
provided fields. The other fields of the document remain unchanged.

Signature:

```ts
patchById(
  id: IdType,
  data: PartialWithoutId<FlatData, IdName>,
  filter?: ItemFilterClause<FlatData>,
): Promise<FlatData>;
```

**Examples**

Partially update a document by its identifier.

```js
// original document with id: 1
// {
//   id: 1,
//   name: 'Laptop Pro',
//   price: 1500
// }

const updatedProduct = await productRep.patchById(1, {
  price: 1450,
});
console.log(updatedProduct);
// {
//   id: 1,
//   name: 'Laptop Pro',
//   price: 1450
// }
```

### repository.patch

Partially updates one or more documents that match the `where` conditions.
Only the provided fields are changed; the rest remain unchanged. Returns the
number of updated documents. If `where` is not specified, it updates all
documents in the collection.

Signature:

```ts
patch(
  data: PartialWithoutId<FlatData, IdName>,
  where?: WhereClause<FlatData>,
): Promise<number>;
```

**Examples**

Update documents based on a condition.

```js
// updates all products with a price less than 30
const updatedCount = await productRep.patch(
  {inStock: false},
  {price: {lt: 30}},
);
```

Update all documents.

```js
// adds or updates the updatedAt field for all documents
const totalCount = await productRep.patch({
  updatedAt: new Date(),
});
```

### repository.find

Finds all documents that match the filter conditions and returns them as an
array. If no filter is specified, it returns all documents in the
collection.

Signature:

```ts
find(filter?: FilterClause<FlatData>): Promise<FlatData[]>;
```

**Examples**

Find all documents.

```js
const allProducts = await productRep.find();
```

Find documents by a `where` condition.

```js
const cheapProducts = await productRep.find({
  where: {price: {lt: 100}},
});
```

Find with sorting and limiting the result set.

```js
const latestProducts = await productRep.find({
  order: 'createdAt DESC',
  limit: 10,
});
```

### repository.findOne

Finds the first document that matches the filter conditions. Returns
`undefined` if no documents are found.

Signature:

```ts
findOne(
  filter?: FilterClause<FlatData>,
): Promise<FlatData | undefined>;
```

**Examples**

Find a single document by a condition.

```js
const expensiveProduct = await productRep.findOne({
  where: {price: {gt: 1000}},
  order: 'price DESC',
});
```

Handling the case where a document is not found.

```js
const product = await productRep.findOne({
  where: {name: 'Non-existent Product'},
});
if (!product) {
  console.log('Product not found.');
}
```

### repository.findById

Finds a single document by its unique identifier. Throws an error if the
document is not found.

Signature:

```ts
findById(
  id: IdType,
  filter?: ItemFilterClause<FlatData>,
): Promise<FlatData>;
```

**Examples**

Find a document by `id`.

```js
try {
  const product = await productRep.findById(1);
  console.log(product);
} catch (error) {
  console.error('Product with id 1 is not found.');
}
```

Find a document including related data.

```js
const product = await productRep.findById(1, {
  include: 'category',
});
```

### repository.delete

Deletes one or more documents that match the `where` conditions. Returns the
number of deleted documents. If `where` is not specified, it deletes all
documents in the collection.

Signature:

```ts
delete(where?: WhereClause<FlatData>): Promise<number>;
```

**Examples**

Delete documents based on a condition.

```js
const deletedCount = await productRep.delete({
  inStock: false,
});
```

Delete all documents.

```js
const totalCount = await productRep.delete();
```

### repository.deleteById

Deletes a single document by its unique identifier. Returns `true` if the
document was found and deleted, otherwise `false`.

Signature:

```ts
deleteById(id: IdType): Promise<boolean>;
```

**Examples**

Delete a document by `id`.

```js
const wasDeleted = await productRep.deleteById(1);
if (wasDeleted) {
  console.log('The document was deleted.');
} else {
  console.log('No document found to delete.');
}
```

### repository.exists

Checks for the existence of a document with the specified identifier.
Returns `true` if the document exists, otherwise `false`.

Signature:

```ts
exists(id: IdType): Promise<boolean>;
```

**Examples**

Check if a document exists by `id`.

```js
const productExists = await productRep.exists(1);
if (productExists) {
  console.log('A document with id 1 exists.');
}
```

### repository.count

Counts the number of documents that match the `where` conditions. If `where`
is not specified, it returns the total number of documents in the collection.

Signature:

```ts
count(where?: WhereClause<FlatData>): Promise<number>;
```

**Examples**

Count documents based on a condition.

```js
const cheapCount = await productRep.count({
  price: {lt: 100},
});
```

Count all documents.

```js
const totalCount = await productRep.count();
```

## Filtering

Some repository methods accept a settings object that affects the returned
result. The `find` method's first parameter has the widest set of these
settings, expecting an object with the options listed below.

- `where: object` conditions to filter documents by their properties;
- `order: string|string[]` sort by specified properties;
- `limit: number` limit the number of documents;
- `skip: number` skip documents (for pagination);
- `fields: string|string[]` select necessary model properties;
- `include: object` include related data in the result;

**Example**

```js
// the "find" repository method is used for the query,
// with a filter object passed as the first argument
const news = await newsRepository.find({
  where: {
    title: {like: '%Moscow%'},
    publishedAt: {gte: '2025-10-15T00:00:00.000Z'},
    tags: {inq: ['world', 'politic']},
    hidden: false,
  },
  order: 'publishedAt DESC',
  limit: 12,
  skip: 24,
  fields: ['title', 'annotation', 'body'],
  include: ['author', 'category'],
})
```

### where

This parameter accepts an object with query conditions and supports the
following set of comparison operators.

- [Search by value (shorthand)](#search-by-value-shorthand)
- [`eq`](#eq-strict-equality) (strict equality)
- [`neq`](#neq-inequality) (inequality)
- [`gt`](#gt-greater-than) (greater than)
- [`lt`](#lt-less-than) (less than)
- [`gte`](#gte-greater-than-or-equal-to) (greater than or equal to)
- [`lte`](#lte-less-than-or-equal-to) (less than or equal to)
- [`inq`](#inq-in-a-list) (in a list)
- [`nin`](#nin-not-in-a-list) (not in a list)
- [`between`](#between-range) (range)
- [`exists`](#exists-property-existence) (property existence)
- [`like`](#like-pattern-matching) (pattern matching)
- [`nlike`](#nlike-excluding-pattern) (excluding pattern)
- [`ilike`](#ilike-case-insensitive-pattern) (case-insensitive pattern)
- [`nilike`](#nilike-case-insensitive-excluding-pattern) (case-insensitive excluding pattern)
- [`regexp`](#regexp-regular-expression) (regular expression)

Conditions can be combined with logical operators:

- [`and`](#and-logical-and) (logical AND)
- [`or`](#or-logical-or) (logical OR)

#### Search by value (shorthand)

Finds documents where the value of the specified property is exactly equal
to the provided value. This is a shorthand for the `{eq: ...}` operator.

```js
// finds all documents where age is 21
const res = await rep.find({
  where: {
    age: 21,
  },
});
```

#### `eq` (strict equality)

Finds documents where the property value is equal to the specified value.

```js
// finds all documents where age is 21
const res = await rep.find({
  where: {
    age: {eq: 21},
  },
});
```

#### `neq` (inequality)

Finds documents where the property value is not equal to the specified value.

```js
// finds all documents where age is not 21
const res = await rep.find({
  where: {
    age: {neq: 21},
  },
});
```

#### `gt` (greater than)

Finds documents where the property value is strictly greater than the
specified value.

```js
// finds documents where age is greater than 30
const res = await rep.find({
  where: {
    age: {gt: 30},
  },
});
```

#### `lt` (less than)

Finds documents where the property value is strictly less than the
specified value.

```js
// finds documents where age is less than 30
const res = await rep.find({
  where: {
    age: {lt: 30},
  },
});
```

#### `gte` (greater than or equal to)

Finds documents where the property value is greater than or equal to the
specified value.

```js
// finds documents where age is greater than or equal to 30
const res = await rep.find({
  where: {
    age: {gte: 30},
  },
});
```

#### `lte` (less than or equal to)

Finds documents where the property value is less than or equal to the
specified value.

```js
// finds documents where age is less than or equal to 30
const res = await rep.find({
  where: {
    age: {lte: 30},
  },
});
```

#### `inq` (in a list)

Finds documents where the property value matches one of the values in the
provided array.

```js
// finds documents where name is 'John' or 'Mary'
const res = await rep.find({
  where: {
    name: {inq: ['John', 'Mary']},
  },
});
```

#### `nin` (not in a list)

Finds documents where the property value is not in the provided array.

```js
// finds all documents except those where name is 'John' or 'Mary'
const res = await rep.find({
  where: {
    name: {nin: ['John', 'Mary']},
  },
});
```

#### `between` (range)

Finds documents where the property value is within the specified range
(inclusive).

```js
// finds documents where age is between 20 and 30, inclusive
const res = await rep.find({
  where: {
    age: {between: [20, 30]},
  },
});
```

#### `exists` (property existence)

Checks for the presence or absence of a property in a document. Does not
check the property's value.

- `true` the property must exist (even if its value is `null`);
- `false` the property must be absent;

```js
// finds documents that have the 'nickname' property
const res1 = await rep.find({
  where: {
    nickname: {exists: true},
  },
});

// finds documents that do not have the 'nickname' property
const res2 = await rep.find({
  where: {
    nickname: {exists: false},
  },
});
```

#### `like` (pattern matching)

Performs a case-sensitive pattern match (see [more details](#pattern-matching-operators)).

```js
// finds {name: 'John Doe'}, but not {name: 'john doe'}
const res = await rep.find({
  where: {
    name: {like: 'John%'},
  },
});
```

#### `nlike` (excluding pattern)

Finds documents that do not match the case-sensitive pattern
(see [more details](#pattern-matching-operators)).

```js
// finds everything except names starting with 'John'
const res = await rep.find({
  where: {
    name: {nlike: 'John%'},
  },
});
```

#### `ilike` (case-insensitive pattern)

Performs a case-insensitive pattern match (see [more details](#pattern-matching-operators)).

```js
// finds both {name: 'John Doe'} and {name: 'john doe'}
const res = await rep.find({
  where: {
    name: {ilike: 'john%'},
  },
});
```

#### `nilike` (case-insensitive excluding pattern)

Finds strings that do not match the pattern, case-insensitively
(see [more details](#pattern-matching-operators)).

```js
// finds everything except names starting with 'John' or 'john'
const res = await rep.find({
  where: {
    name: {nilike: 'john%'},
  },
});
```

#### `regexp` (regular expression)

Finds documents where the string property's value matches the specified
regular expression. Can be passed as a string or a `RegExp` object.

```js
// finds documents where name starts with 'J'
const res1 = await rep.find({
  where: {
    name: {regexp: '^J'},
  },
});

// finds documents where name starts with 'J' or 'j' (case-insensitive)
const res2 = await rep.find({
  where: {
    name: {regexp: '^j', flags: 'i'},
  },
});
```

#### `and` (logical AND)

Combines multiple conditions into an array, requiring every condition to be
met.

```javascript
// finds documents where surname is 'Smith' AND age is 21
const res = await rep.find({
  where: {
    and: [
      {surname: 'Smith'},
      {age: 21}
    ],
  },
});
```

#### `or` (logical OR)

Combines multiple conditions into an array, requiring at least one of them
to be met.

```javascript
// finds documents where name is 'James' OR age is greater than 30
const res = await rep.find({
  where: {
    or: [
      {name: 'James'},
      {age: {gt: 30}}
    ],
  },
});
```

#### Pattern Matching Operators

The `like`, `nlike`, `ilike`, and `nilike` operators are designed for filtering
string properties based on pattern matching, similar to the `LIKE` operator
in SQL. They allow finding values that match a certain structure using
special characters.

**`%`** matches any sequence of zero or more characters:

- `'A%'` finds all strings starting with "A";
- `'%a'` finds all strings ending with "a";
- `'%word%'` finds all strings containing "word" anywhere;

**`_`** matches exactly one of any character:

- `'c_t'` finds "cat", "cot", but not "cart" or "ct";
- `'cat_'` finds "cats", "cat1", but not "cat" or "catch";

To find the literal characters `%` or `_`, they must be escaped with a
backslash `\`:

- `'100\%'` finds the string "100%";
- `'file\_name'` finds the string "file_name";
- `'path\\to'` finds the string "path\to";

### order

This parameter sorts the result set by the specified model properties. You can
specify descending order with the `DESC` postfix.

**Examples**

Sort by the `createdAt` field.

```js
const res = await rep.find({
  order: 'createdAt',
});
```

Sort by the `createdAt` field in descending order.

```js
const res = await rep.find({
  order: 'createdAt DESC',
});
```

Sort by multiple properties in different directions.

```js
const res = await rep.find({
  order: [
    'title',
    'price ASC',
    'featured DESC',
  ],
});
```

*i. The `ASC` sort direction is optional.*

### include

This parameter includes related documents in the method's result. The names
of the included relations must be defined in the current model
(see [Relations](#relations)).

**Examples**

Include a relation by its name.

```js
const res = await rep.find({
  include: 'city',
});
```

Include nested relations.

```js
const res = await rep.find({
  include: {
    city: 'country',
  },
});
```

Include multiple relations using an array.

```js
const res = await rep.find({
  include: [
    'city',
    'address',
    'employees'
  ],
});
```

Using filtering for included documents.

```js
const res = await rep.find({
  include: {
    relation: 'employees', // relation name
    scope: { // filter for "employees" documents
      where: {hidden: false}, // query conditions
      order: 'id', // document order
      limit: 10, // limit the number of documents
      skip: 5, // skip documents
      fields: ['name', 'surname'], // only these fields
      include: 'city', // include relations for "employees"
    },
  },
});
```

## Relations

Relations describe relationships between models, allowing for automatic
embedding of related data using the `include` option in repository methods.
The example below shows automatic relation resolution when using the
`findById` method.

```
         Role (role)
      ┌────────────────────┐
      │  id: 3  <──────────│────┐
      │  name: 'Manager'   │    │
      └────────────────────┘    │
                                │
     User (user)                │
  ┌────────────────────────┐    │
  │  id: 1                 │    │
  │  name: 'John Doe'      │    │
  │  roleId: 3   ──────────│────┘
  │  cityId: 24  ──────────│────┐
  └────────────────────────┘    │
                                │
         City (city)            │
      ┌────────────────────┐    │
      │  id: 24  <─────────│────┘
      │  name: 'Moscow'    │
      └────────────────────┘
```

```js
// query a document from the "users" collection,
// including related data (role and city)
const user = await userRep.findById(1, {
  include: ['role', 'city'],
});

console.log(user);
// {
//   id: 1,
//   name: 'John Doe',
//   roleId: 3,
//   role: {
//     id: 3,
//     name: 'Manager'
//   },
//   cityId: 24,
//   city: {
//     id: 24,
//     name: 'Moscow'
//   }
// }
```

### Defining a Relation

The `relations` property in a model definition accepts an object where keys
are relation names and values are their parameters. The relation name can
then be used in the `include` option of repository methods.

```js
import {
  DataType,
  RelationType,
  DatabaseSchema,
} from '@e22m4u/js-repository';

dbs.defineModel({
  name: 'user',
  datasource: 'memory',
  properties: {
    name: DataType.STRING,
  },
  relations: {
    // relation role -> parameters
    role: {
      type: RelationType.BELONGS_TO,
      model: 'role',
    },
    // relation city -> parameters
    city: {
      type: RelationType.BELONGS_TO,
      model: 'city',
    },
  },
});
```

**Core Parameters**

- `type: string` the relation type (required);
- `model: string` the target model name (required for some types);
- `foreignKey: string` the property in the current model for the target ID;

*i. For Belongs To and References Many types, the `foreignKey` parameter
can be omitted as it's automatically generated based on the relation name.*

**Polymorphic Mode**

- `polymorphic: boolean|string` declares a polymorphic relation;
- `discriminator: string` the property in the current model for the target's name;

*i. Polymorphic mode allows dynamically determining the target model by its
name, which is stored in the document's discriminator property.*

### Relation Types

- [Belongs To](#belongs-to)
  The current model references the target model by its ID.
  `type: "belongsTo"` or `type: RelationType.BELONGS_TO`

- [Has One](#has-one)
  The inverse of `belongsTo` for a "one-to-one" relationship.
  `type: "hasOne"` or `type: RelationType.HAS_ONE`

- [Has Many](#has-many)
  The inverse of `belongsTo` for a "one-to-many" relationship.
  `type: "hasMany"` or `type: RelationType.HAS_MANY`

- [References Many](#references-many)
  The current model references the target model via an array of IDs.
  `type: "referencesMany"` or `type: RelationType.REFERENCES_MANY`

Polymorphic versions:

- [Belongs To (polymorphic)](#belongs-to-polymorphic-version)
- [Has One (polymorphic)](#has-one-polymorphic-version)
- [Has Many (polymorphic)](#has-many-polymorphic-version)

The `type` parameter in a relation definition accepts a string with the type
name. To avoid typos, it's recommended to use the constants from the
`RelationType` object listed below.

- `RelationType.BELONGS_TO`
- `RelationType.HAS_ONE`
- `RelationType.HAS_MANY`
- `RelationType.REFERENCES_MANY`

#### Belongs To

The current model references the target model by its identifier.

```
    Current (user)                  Target (role)
┌─────────────────────────┐       ┌─────────────────────────┐
│   id: 1                 │   ┌───│─> id: 5                 │
│   roleId: 5  ───────────│───┤   │   ...                   │
│   ...                   │   │   └─────────────────────────┘
└─────────────────────────┘   │ 
┌─────────────────────────┐   │   
│   id: 2                 │   │
│   roleId: 5  ───────────│───┘   
│   ...                   │       
└─────────────────────────┘       
```

Relation definition:

```js
dbs.defineModel({
  name: 'user',
  relations: {
    role: { // relation name
      type: RelationType.BELONGS_TO, // current model references target
      model: 'role', // target model name
      foreignKey: 'roleId', // foreign key (optional)
      // if "foreignKey" is not specified, the foreign key property
      // is formed based on the relation name with an "Id" postfix
    },
  },
});
```

Example:

```js
import {
  DataType,
  RelationType,
  DatabaseSchema,
} from '@e22m4u/js-repository';

const dbs = new DatabaseSchema();

// datasource
dbs.defineDatasource({
  name: 'myDb',
  adapter: 'memory',
});

// role model
dbs.defineModel({
  name: 'role',
  datasource: 'myDb',
  properties: {
    name: DataType.STRING,
  },
});

// user model
dbs.defineModel({
  name: 'user',
  datasource: 'myDb',
  properties: {
    name: DataType.STRING,
    roleId: DataType.NUMBER, // optional
  },
  relations: {
    role: {
      type: RelationType.BELONGS_TO,
      model: 'role',
      foreignKey: 'roleId', // optional
    },
  },
});

// create a role
const roleRep = dbs.getRepository('role');
const role = await roleRep.create({
  id: 5,
  name: 'Manager',
});
console.log(role);
// {
//   id: 5,
//   name: 'Manager'
// }

// create a user
const userRep = dbs.getRepository('user');
const user = await userRep.create({
  id: 1,
  name: 'John Doe',
  roleId: role.id,
});
console.log(user);
// {
//   id: 1,
//   name: 'John Doe',
//   roleId: 5
// }

// fetch user with related role ("include" option)
const userWithRole = await userRep.findById(user.id, {include: 'role'});
console.log(userWithRole);
// {
//   id: 1,
//   name: 'John Doe',
//   roleId: 5,
//   role: {
//     id: 5,
//     name: 'Manager'
//   }
// }
```

#### Has One

The inverse of `belongsTo` for a "one-to-one" relationship.

```
    Current (profile)               Target (user)
┌─────────────────────────┐       ┌─────────────────────────┐
│   id: 5  <──────────────│───┐   │   id: 1                 │
│   ...                   │   └───│── profileId: 5          │
└─────────────────────────┘       │   ...                   │
                                  └─────────────────────────┘
```

Relation definition:

```js
// dbs.defineModel({
//   name: 'user',
//   relations: {
//     profile: {
//       type: RelationType.BELONGS_TO,
//       model: 'profile',
//     },
//   },
// });

dbs.defineModel({
  name: 'profile',
  relations: {
    user: { // relation name
      type: RelationType.HAS_ONE, // target model references current
      model: 'user', // target model name
      foreignKey: 'profileId', // foreign key from target to current
    },
  },
});
```

#### Has Many

The inverse of `belongsTo` for a "one-to-many" relationship.

```
    Current (role)                  Target (user)
┌─────────────────────────┐       ┌─────────────────────────┐
│   id: 5  <──────────────│───┐   │   id: 1                 │
│   ...                   │   ├───│── roleId: 5             │
└─────────────────────────┘   │   │   ...                   │
                              │   └─────────────────────────┘
                              │   ┌─────────────────────────┐
                              │   │   id: 2                 │
                              └───│── roleId: 5             │
                                  │   ...                   │
                                  └─────────────────────────┘
```

Relation definition:

```js
// dbs.defineModel({
//   name: 'user',
//   relations: {
//     role: {
//       type: RelationType.BELONGS_TO,
//       model: 'role',
//     },
//   },
// });

dbs.defineModel({
  name: 'role',
  relations: {
    users: { // relation name
      type: RelationType.HAS_MANY, // target model references current
      model: 'user', // target model name
      foreignKey: 'roleId', // foreign key in the target model
    },
  },
});
```

#### References Many

The current model references the target model via an array of identifiers.

```
    Current (article)                 Target (category)
┌─────────────────────────┐       ┌─────────────────────────┐
│   id: 1                 │   ┌───│─> id: 5                 │
│   categoryIds: [5, 6] ──│───┤   │   ...                   │
│   ...                   │   │   └─────────────────────────┘
└─────────────────────────┘   │   ┌─────────────────────────┐
                              └───│─> id: 6                 │
                                  │   ...                   │
                                  └─────────────────────────┘
```

Relation definition:

```js
// dbs.defineModel({name: 'category', ...

dbs.defineModel({
  name: 'article',
  relations: {
    categories: { // relation name
      type: RelationType.REFERENCES_MANY, // relation via array of IDs
      model: 'category', // target model name
      foreignKey: 'categoryIds', // foreign key (optional)
      // if "foreignKey" is not specified, the foreign key property
      // is formed based on the relation name with an "Ids" postfix
    },
  },
});
```

#### Belongs To (polymorphic version)

The current model references a target model by its identifier. The target
model's name is determined by a discriminator property.

```
    Current (file)               ┌──────> Target 1 (letter)
┌─────────────────────────────┐  │    ┌─────────────────────────┐
│   id: 1                     │  │ ┌──│─> id: 10                │
│   referenceType: 'letter'  ─│──┘ │  │   ...                   │
│   referenceId: 10  ─────────│────┘  └─────────────────────────┘
└─────────────────────────────┘
                                 ┌──────> Target 2 (user)
┌─────────────────────────────┐  │    ┌─────────────────────────┐
│   id: 2                     │  │ ┌──│─> id: 5                 │
│   referenceType: 'user'  ───│──┘ │  │   ...                   │
│   referenceId: 5  ──────────│────┘  └─────────────────────────┘
└─────────────────────────────┘
```

Relation definition:

```js
dbs.defineModel({
  name: 'file',
  relations: {
    reference: { // relation name
      type: RelationType.BELONGS_TO, // current model references target
      // polymorphic mode allows storing the target model's name
      // in a discriminator property, which is formed based on
      // the relation name with a "Type" postfix, in this case,
      // the target model's name is stored in "referenceType",
      // and the document's ID is in "referenceId"
      polymorphic: true,
    },
  },
});
```

Relation definition with explicit properties:

```js
dbs.defineModel({
  name: 'file',
  relations: {
    reference: { // relation name
      type: RelationType.BELONGS_TO, // current model references target
      polymorphic: true, // target model name is in a discriminator
      foreignKey: 'referenceId', // property for the target's ID
      discriminator: 'referenceType', // property for the target's name
    },
  },
});
```

#### Has One (polymorphic version)

The inverse of a polymorphic `belongsTo` for a "one-to-one" relationship.

```
    Current (company)  <───────┐      Target (license)
┌─────────────────────────┐    │  ┌─────────────────────────┐
│   id: 10  <─────────────│──┐ │  │   id: 1                 │
│   ...                   │  │ └──│── ownerType: 'company'  │
└─────────────────────────┘  └────│── ownerId: 10           │
                                  └─────────────────────────┘
```

Relation definition specifying the target's relation name:

```js
// dbs.defineModel({
//   name: 'license',
//   relations: {
//     owner: {
//       type: RelationType.BELONGS_TO,
//       polymorphic: true,
//     },
//   },
// });

dbs.defineModel({
  name: 'company',
  relations: {
    license: { // relation name
      type: RelationType.HAS_ONE, // target model references current
      model: 'license', // target model name
      polymorphic: 'owner', // polymorphic relation name in target model
    },
  },
});
```

Relation definition specifying the target model's properties:

```js
// dbs.defineModel({
//   name: 'license',
//   relations: {
//     owner: {
//       type: RelationType.BELONGS_TO,
//       polymorphic: true,
//       foreignKey: 'ownerId',
//       discriminator: 'ownerType',
//     },
//   },
// });

dbs.defineModel({
  name: 'company',
  relations: {
    license: { // relation name
      type: RelationType.HAS_ONE, // target model references current
      model: 'license', // target model name
      polymorphic: true, // current model name is in discriminator
      foreignKey: 'ownerId', // property in target for current's ID
      discriminator: 'ownerType', // property in target for current's name
    },
  },
});
```

#### Has Many (polymorphic version)

The inverse of a polymorphic `belongsTo` for a "one-to-many" relationship.

```
    Current (letter)  <─────────┐      Target (file)
┌──────────────────────────┐    │  ┌────────────────────────────┐
│   id: 10  <──────────────│──┐ │  │   id: 1                    │
│   ...                    │  │ ├──│── referenceType: 'letter'  │
└──────────────────────────┘  ├─│──│── referenceId: 10          │
                              │ │  └────────────────────────────┘
                              │ │  ┌────────────────────────────┐
                              │ │  │   id: 2                    │
                              │ └──│── referenceType: 'letter'  │
                              └────│── referenceId: 10          │
                                   └────────────────────────────┘
```

Relation definition specifying the target's relation name:

```js
// dbs.defineModel({
//   name: 'file',
//   relations: {
//     reference: {
//       type: RelationType.BELONGS_TO,
//       polymorphic: true,
//     },
//   },
// });

dbs.defineModel({
  name: 'letter',
  relations: {
    attachments: { // relation name
      type: RelationType.HAS_MANY, // target model references current
      model: 'file', // target model name
      polymorphic: 'reference', // polymorphic relation name in target
    },
  },
});
```

Relation definition specifying the target model's properties:

```js
// dbs.defineModel({
//   name: 'file',
//   relations: {
//     reference: {
//       type: RelationType.BELONGS_TO,
//       polymorphic: true,
//       foreignKey: 'referenceId',
//       discriminator: 'referenceType',
//     },
//   },
// });

dbs.defineModel({
  name: 'letter',
  relations: {
    attachments: { // relation name
      type: RelationType.HAS_MANY, // target model references current
      model: 'file', // target model name
      polymorphic: true, // current model name is in discriminator
      foreignKey: 'referenceId', // property in target for current's ID
      discriminator: 'referenceType', // property in target for current's name
    },
  },
});
```

## Extending

The `getRepository` method of a `DatabaseSchema` instance checks for an
existing repository for the specified model and returns it. Otherwise, a new
instance is created and cached for subsequent calls.

```js
import {Repository} from '@e22m4u/js-repository';
import {DatabaseSchema} from '@e22m4u/js-repository';

// const dbs = new DatabaseSchema();
// dbs.defineDatasource ...
// dbs.defineModel ...

const rep1 = dbs.getRepository('model');
const rep2 = dbs.getRepository('model');
console.log(rep1 === rep2); // true
```

You can replace the default repository constructor using the `setRepositoryCtor`
method of the `RepositoryRegistry` service, which is available in the
`DatabaseSchema` instance's service container. After that, all new
repositories will be created using the specified constructor instead of the
default one.

```js
import {Repository} from '@e22m4u/js-repository';
import {DatabaseSchema} from '@e22m4u/js-repository';
import {RepositoryRegistry} from '@e22m4u/js-repository';

class MyRepository extends Repository {
  /*...*/
}

// const dbs = new DatabaseSchema();
// dbs.defineDatasource ...
// dbs.defineModel ...

dbs.getService(RepositoryRegistry).setRepositoryCtor(MyRepository);
const rep = dbs.getRepository('model');
console.log(rep instanceof MyRepository); // true
```

*i. Since repository instances are cached, you should replace the
constructor before calling the `getRepository` method.*

## TypeScript

Getting a typed repository with a specified model interface.

```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 ...

// define the "city" model
dbs.defineModel({
  name: 'city',
  datasource: 'myDatasource',
  properties: {
    name: DataType.STRING,
    timeZone: DataType.STRING,
  },
});

// define the "city" interface
interface City {
  id: number;
  name?: string;
  timeZone?: string;
}

// when getting a repository for a model,
// you can specify the document type
const cityRep = dbs.getRepository<City>('city');

// now, repository methods return
// the City type instead of Record<string, unknown>
const city: City = await cityRep.create({
  name: 'Moscow',
  timeZone: 'Europe/Moscow',
});
```

For defining models using TypeScript classes, it is recommended to use the
specialized version of this module,
[@e22m4u/ts-repository](https://www.npmjs.com/package/@e22m4u/ts-repository),
which comes with a set of TypeScript decorators and additional tools for
working in a TypeScript environment.

## Tests

```bash
npm run test
```

## License

MIT