@kollors/deep-json-server 0.3.0 → 0.3.2

package/README.md

@@ -8,6 +8,8 @@ A small JSON REST mock server with CRUD, pagination, deep filters and recursive
 
 ## Installation
 
+Node.js 20 or newer is required.
+
 ```bash
 npm install --save-dev @kollors/deep-json-server
 ```
@@ -33,7 +35,7 @@ The default address is `http://127.0.0.1:4001`. You can also pass `--host` and `
 
 ## Example database
 
-This example is based on a movie catalog. The genre names are real film genres, while `Gangster film` demonstrates a self-referencing subgenre.
+This example is based on a movie catalog. `Gangster film` demonstrates a relationship with a parent genre.
 
 ```json
 {
@@ -104,7 +106,7 @@ PATCH  /movies/:id
 DELETE /movies/:id
 ```
 
-`POST` generates a string ID. `PUT`, `PATCH` and `DELETE` persist their changes in the JSON file.
+`POST` generates a string ID, while `PUT` and `PATCH` preserve the stored ID type. All write operations — `POST`, `PUT`, `PATCH` and `DELETE` — persist their changes in the JSON file. The database file must exist before startup and contain a JSON object whose every top-level property is an array of resource records.
 
 ## Pagination and sorting
 
@@ -112,7 +114,7 @@ DELETE /movies/:id
 GET /movies?_page=1&_perPage=10&_sort=-id,title
 ```
 
-Without `_page`, a GET collection returns an array. With `_page`, it returns:
+A GET collection always returns a page object. `_page` defaults to `1`, and `_perPage` defaults to `10`:
 
 ```json
 {
@@ -126,6 +128,8 @@ Without `_page`, a GET collection returns an array. With `_page`, it returns:
 }
 ```
 
+Both pagination parameters must be positive integers. Invalid values return `400` instead of being silently corrected.
+
 Prefix a sort field with `-` for descending order.
 
 ## Filters
@@ -164,6 +168,8 @@ Simple query parameters are supported too:
 GET /movies?title:contains=father
 ```
 
+Simple filter values recognize JSON primitives: numbers, `true`, `false` and `null`. Values with leading zeroes, such as `001`, remain strings. Unknown operators, invalid logical conditions and filter paths that do not exist in a non-empty resource return `400`.
+
 ## Relationships
 
 Use `_embed` to replace IDs with related records:
@@ -195,6 +201,8 @@ Relations are inferred by convention:
 
 They are soft references: the server resolves them when requested but does not enforce referential integrity when data is written.
 
+An explicit `...Id` or `...Ids` field is the source of truth. If a record also contains an outdated embedded value, `_embed` replaces it with the current related record. Relationship lookups use lazy per-request ID indexes, so each referenced resource is indexed only when needed.
+
 ## OpenAPI generation
 
 Create a small configuration file next to the database, for example `mock/database-schema.json`:
@@ -229,7 +237,27 @@ Generate an OpenAPI 3.0.3 file and exit:
 deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml --host 127.0.0.1 --port 4001
 ```
 
-The generator infers resources and field types from all database records. Every inferred field is optional by default, while the top-level resource record's primary key `id` is always required. Add other required fields to `required`; nested fields use dot paths such as `actors.userId`. The `formats` object adds OpenAPI formats such as `date` and `uri`.
+The generator infers resources and field types from all database records. Every inferred field is optional by default, while a top-level `id` present in the resulting resource schema is always required. Add other required fields to `required`; nested fields use dot paths such as `actors.userId`. The `formats` object adds OpenAPI formats such as `date` and `uri`.
+
+Different value types are inferred independently and combined through `oneOf`. Configuration is validated before generation: `$info`, resource and schema names, and the structure of `properties` are validated, while paths from `required` and `formats` must exist in the resulting schema.
+
+Use `properties` to describe fields that cannot be inferred, particularly for an empty resource. Explicit properties are merged with inferred properties:
+
+```json
+{
+  "$schema": {
+    "reviews": {
+      "properties": {
+        "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "text": { "type": "string" }
+      },
+      "required": ["rating"]
+    }
+  }
+}
+```
+
+An empty resource still receives a required string `id` property because IDs created by the server are strings. Generation stops with an actionable error when resources produce duplicate schema names or operation IDs; use an explicit `name` to resolve schema-name collisions.
 
 `$info` becomes the OpenAPI `info` object, while resource settings live under `$schema`. The OpenAPI `servers` entry is generated automatically from `--host` and `--port`, their `HOST` and `PORT` environment variable equivalents, or the default `http://127.0.0.1:4001`.
 

package/README.ru.md

@@ -8,6 +8,8 @@
 
 ## Установка
 
+Требуется Node.js 20 или новее.
+
 ```bash
 npm install --save-dev @kollors/deep-json-server
 ```
@@ -33,7 +35,7 @@ npm run mock
 
 ## Пример базы данных
 
-Пример основан на каталоге фильмов. В нём намеренно нет сущности одежды. Используются реальные жанры фильмов, а `Гангстерский фильм` демонстрирует связь с родительским жанром.
+Пример основан на каталоге фильмов. `Гангстерский фильм` демонстрирует связь с родительским жанром.
 
 ```json
 {
@@ -104,7 +106,7 @@ PATCH  /movies/:id
 DELETE /movies/:id
 ```
 
-`POST` генерирует строковый ID. `PUT`, `PATCH` и `DELETE` сохраняют изменения в JSON-файле.
+`POST` генерирует строковый ID, а `PUT` и `PATCH` сохраняют исходный тип ID. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — сохраняют изменения в JSON-файле. Файл базы должен существовать до запуска и содержать JSON-объект, каждое свойство верхнего уровня которого является массивом записей отдельного ресурса.
 
 ## Пагинация и сортировка
 
@@ -112,7 +114,7 @@ DELETE /movies/:id
 GET /movies?_page=1&_perPage=10&_sort=-id,title
 ```
 
-Без `_page` GET-запрос к коллекции возвращает массив. С `_page` возвращается объект:
+GET-запрос к коллекции всегда возвращает объект страницы. По умолчанию `_page` равен `1`, а `_perPage` — `10`:
 
 ```json
 {
@@ -126,6 +128,8 @@ GET /movies?_page=1&_perPage=10&_sort=-id,title
 }
 ```
 
+Оба параметра пагинации должны быть положительными целыми числами. При некорректном значении сервер возвращает `400`, а не исправляет его автоматически.
+
 Префикс `-` перед полем включает сортировку по убыванию.
 
 ## Фильтры
@@ -164,6 +168,8 @@ GET /movies?_where={"title":{"contains":"отец"}}
 GET /movies?title:contains=отец
 ```
 
+В простых фильтрах распознаются JSON-примитивы: числа, `true`, `false` и `null`. Значения с ведущими нулями, например `001`, остаются строками. Неизвестные операторы, некорректные логические условия и отсутствующие в непустом ресурсе пути фильтра возвращают `400`.
+
 ## Связи
 
 Используйте `_embed`, чтобы заменить ID связанными записями:
@@ -195,6 +201,8 @@ GET /countries/1?_embed=users
 
 Это мягкие ссылки: сервер загружает их по запросу, но не проверяет ссылочную целостность при записи данных.
 
+Явное поле `...Id` или `...Ids` считается источником истины. Если в записи также сохранено устаревшее вложенное значение, `_embed` заменяет его актуальной связанной записью. Для поиска связей лениво создаются ID-индексы только используемых в текущем запросе ресурсов.
+
 ## Генерация OpenAPI
 
 Создайте рядом с базой небольшой файл конфигурации, например `mock/database-schema.json`:
@@ -229,7 +237,27 @@ GET /countries/1?_embed=users
 deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml --host 127.0.0.1 --port 4001
 ```
 
-Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а первичный ключ `id` корневой записи ресурса всегда обязательный. Остальные обязательные поля перечисляются в `required`; для вложенных полей используются пути через точку, например `actors.userId`. Объект `formats` добавляет форматы OpenAPI, например `date` и `uri`.
+Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня, присутствующее в итоговой схеме ресурса, всегда обязательное. Остальные обязательные поля перечисляются в `required`; для вложенных полей используются пути через точку, например `actors.userId`. Объект `formats` добавляет форматы OpenAPI, например `date` и `uri`.
+
+Разные типы значений определяются независимо и объединяются через `oneOf`. Перед генерацией проверяются `$info`, имена ресурсов и схем, а также структура `properties`; пути из `required` и `formats` должны существовать в итоговой схеме.
+
+Используйте `properties`, чтобы описать поля, которые невозможно определить автоматически, особенно у пустого ресурса. Явно заданные свойства объединяются с найденными автоматически:
+
+```json
+{
+  "$schema": {
+    "reviews": {
+      "properties": {
+        "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "text": { "type": "string" }
+      },
+      "required": ["rating"]
+    }
+  }
+}
+```
+
+Пустой ресурс всё равно получает обязательное строковое поле `id`, поскольку сервер создаёт строковые ID. При совпадении имён схем или `operationId` генерация завершается понятной ошибкой; коллизию имён схем можно устранить с помощью явного `name`.
 
 `$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. Поле `servers` в OpenAPI формируется автоматически из параметров `--host` и `--port`, соответствующих переменных окружения `HOST` и `PORT` или адреса по умолчанию `http://127.0.0.1:4001`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kollors/deep-json-server",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "JSON mock server with deep filters and recursive relationship embedding",
   "type": "module",
   "bin": {

package/src/openapi.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { stringify } from 'yaml';
-import { getResourceNames, isObject, singularize, toPascalCase } from './utils.js';
+import { getResourceNames, isObject, singularize, toPascalCase, validateDatabase } from './utils.js';
 
 const readJson = async(path, label) => {
   const value = JSON.parse(await readFile(resolve(path), 'utf8'));
@@ -45,50 +45,105 @@ const mergeSchemas = (schemas) => {
   return { oneOf: nonNullSchemas, ...(nullable && { nullable: true }) };
 };
 
-const inferSchema = (values, path, options) => {
-  if (values.every(Array.isArray)) {
-    const items = values.flat();
+const mergeSchemaOverrides = (schema, overrides) => {
+  if (!isObject(overrides)) {
+    return schema;
+  }
+
+  const result = { ...schema, ...overrides };
+
+  if (Object.hasOwn(overrides, 'type') && !Object.hasOwn(overrides, 'oneOf')) {
+    delete result.oneOf;
+  }
+
+  if (isObject(schema.properties) || isObject(overrides.properties)) {
+    const properties = isObject(schema.properties) ? { ...schema.properties } : {};
+
+    Object.entries(isObject(overrides.properties) ? overrides.properties : {}).forEach(([key, value]) => {
+      properties[key] = mergeSchemaOverrides(properties[key] ?? {}, value);
+    });
+
+    result.properties = properties;
+  }
+
+  if (isObject(schema.items) && isObject(overrides.items)) {
+    result.items = mergeSchemaOverrides(schema.items, overrides.items);
+  }
+
+  return result;
+};
+
+const applyRequiredFields = (schema, path, requiredFields) => {
+  if (Array.isArray(schema.oneOf)) {
+    return { ...schema, oneOf: schema.oneOf.map((nestedSchema) => applyRequiredFields(nestedSchema, path, requiredFields)) };
+  }
+
+  if (schema.type === 'array') {
+    return { ...schema, items: applyRequiredFields(schema.items ?? {}, path, requiredFields) };
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties)) {
+    return schema;
+  }
+
+  const properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => {
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+
+    return [key, applyRequiredFields(value, fieldPath, requiredFields)];
+  }));
+  const required = Object.keys(properties).filter((key) => {
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+
+    return path === '' && key === 'id' || requiredFields.has(fieldPath);
+  });
+  const result = { ...schema, properties };
+
+  delete result.required;
+
+  return required.length === 0 ? result : { ...result, required };
+};
+
+const inferSchema = (values) => {
+  const schemas = [];
+  const arrays = values.filter(Array.isArray);
+  const objects = values.filter(isObject);
+
+  if (arrays.length > 0) {
+    const items = arrays.flat();
 
-    return { items: items.length === 0 ? {} : inferSchema(items, path, options), type: 'array' };
+    schemas.push({ items: items.length === 0 ? {} : inferSchema(items), type: 'array' });
   }
 
-  if (values.every(isObject)) {
-    return inferObjectSchema(values, path, options);
+  if (objects.length > 0) {
+    schemas.push(inferObjectSchema(objects));
   }
 
-  const schemas = values.map((value) => {
+  values.filter((value) => !Array.isArray(value) && !isObject(value)).forEach((value) => {
     if (value === null) {
-      return { type: 'null' };
+      schemas.push({ type: 'null' });
+      return;
     }
 
     if (typeof value === 'number') {
-      return { type: Number.isInteger(value) ? 'integer' : 'number' };
+      schemas.push({ type: Number.isInteger(value) ? 'integer' : 'number' });
+      return;
     }
 
-    const schema = { type: typeof value };
-    const format = options.formats[path];
-
-    return typeof value === 'string' && format != null ? { ...schema, format } : schema;
+    schemas.push({ type: typeof value });
   });
 
   return mergeSchemas(schemas);
 };
 
-function inferObjectSchema(values, path, options) {
+function inferObjectSchema(values) {
   const keys = [...new Set(values.flatMap((value) => Object.keys(value)))].sort((left, right) => left === 'id' ? -1 : right === 'id' ? 1 : left.localeCompare(right));
   const properties = Object.fromEntries(keys.map((key) => {
-    const fieldPath = path === '' ? key : `${path}.${key}`;
     const fieldValues = values.filter((value) => Object.hasOwn(value, key)).map((value) => value[key]);
 
-    return [key, inferSchema(fieldValues, fieldPath, options)];
+    return [key, inferSchema(fieldValues)];
   }));
-  const required = keys.filter((key) => {
-    const fieldPath = path === '' ? key : `${path}.${key}`;
 
-    return path === '' && key === 'id' || options.required.has(fieldPath);
-  });
-
-  return { properties, type: 'object', ...(required.length > 0 && { required }) };
+  return { properties, type: 'object' };
 }
 
 const resolveRelationResource = (resources, relation, sourceResource) => {
@@ -102,6 +157,10 @@ const resolveRelationResource = (resources, relation, sourceResource) => {
 };
 
 const addRelationSchemas = (schema, resources, componentNames, sourceResource) => {
+  if (Array.isArray(schema.oneOf)) {
+    return { ...schema, oneOf: schema.oneOf.map((nestedSchema) => addRelationSchemas(nestedSchema, resources, componentNames, sourceResource)) };
+  }
+
   if (schema.type === 'array') {
     return { ...schema, items: addRelationSchemas(schema.items, resources, componentNames, sourceResource) };
   }
@@ -135,6 +194,147 @@ const addRelationSchemas = (schema, resources, componentNames, sourceResource) =
   return { ...schema, properties };
 };
 
+const getSchemasAtPath = (schema, keys) => {
+  if (Array.isArray(schema.oneOf)) {
+    return schema.oneOf.flatMap((nestedSchema) => getSchemasAtPath(nestedSchema, keys));
+  }
+
+  if (schema.type === 'array') {
+    return getSchemasAtPath(schema.items ?? {}, keys);
+  }
+
+  if (keys.length === 0) {
+    return [schema];
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties) || !Object.hasOwn(schema.properties, keys[0])) {
+    return [];
+  }
+
+  return getSchemasAtPath(schema.properties[keys[0]], keys.slice(1));
+};
+
+const updateSchemasAtPath = (schema, keys, update) => {
+  if (Array.isArray(schema.oneOf)) {
+    return { ...schema, oneOf: schema.oneOf.map((nestedSchema) => updateSchemasAtPath(nestedSchema, keys, update)) };
+  }
+
+  if (schema.type === 'array') {
+    return { ...schema, items: updateSchemasAtPath(schema.items ?? {}, keys, update) };
+  }
+
+  if (keys.length === 0) {
+    return update(schema);
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties) || !Object.hasOwn(schema.properties, keys[0])) {
+    return schema;
+  }
+
+  return {
+    ...schema,
+    properties: {
+      ...schema.properties,
+      [keys[0]]: updateSchemasAtPath(schema.properties[keys[0]], keys.slice(1), update),
+    },
+  };
+};
+
+const validateSchemaOverride = (schema, path) => {
+  if (!isObject(schema)) {
+    throw new Error(`OpenAPI-схема свойства «${path}» должна содержать JSON-объект`);
+  }
+
+  if (schema.properties != null) {
+    if (!isObject(schema.properties)) {
+      throw new Error(`properties свойства «${path}» должен содержать JSON-объект`);
+    }
+
+    Object.entries(schema.properties).forEach(([key, value]) => validateSchemaOverride(value, `${path}.${key}`));
+  }
+
+  if (schema.items != null) {
+    validateSchemaOverride(schema.items, `${path}[]`);
+  }
+
+  if (schema.oneOf != null) {
+    if (!Array.isArray(schema.oneOf) || schema.oneOf.length === 0) {
+      throw new Error(`oneOf свойства «${path}» должен содержать непустой массив`);
+    }
+
+    schema.oneOf.forEach((value, index) => validateSchemaOverride(value, `${path}.oneOf[${index}]`));
+  }
+};
+
+const validateSchemaConfig = (schemaConfig, resources) => {
+  if (Object.hasOwn(schemaConfig, '$info')) {
+    if (!isObject(schemaConfig.$info) || !['title', 'version'].every((key) => typeof schemaConfig.$info[key] === 'string' && schemaConfig.$info[key].trim() !== '')) {
+      throw new Error('$info должен содержать непустые строковые поля title и version');
+    }
+  }
+
+  if (Object.hasOwn(schemaConfig, '$schema') && !isObject(schemaConfig.$schema)) {
+    throw new Error('$schema должен содержать JSON-объект');
+  }
+
+  const resourceConfigs = schemaConfig.$schema ?? {};
+
+  Object.entries(resourceConfigs).forEach(([resource, resourceConfig]) => {
+    if (!resources.includes(resource)) {
+      throw new Error(`В $schema указан неизвестный ресурс «${resource}»`);
+    }
+
+    if (!isObject(resourceConfig)) {
+      throw new Error(`Настройки ресурса «${resource}» должны содержать JSON-объект`);
+    }
+
+    if (resourceConfig.name != null && (typeof resourceConfig.name !== 'string' || resourceConfig.name.trim() === '')) {
+      throw new Error(`$schema.${resource}.name должен содержать непустую строку`);
+    }
+
+    if (resourceConfig.required != null && (!Array.isArray(resourceConfig.required) || resourceConfig.required.some((path) => typeof path !== 'string' || path === ''))) {
+      throw new Error(`$schema.${resource}.required должен содержать массив непустых строк`);
+    }
+
+    if (resourceConfig.formats != null && (!isObject(resourceConfig.formats) || Object.entries(resourceConfig.formats).some(([path, format]) => path === '' || typeof format !== 'string' || format === ''))) {
+      throw new Error(`$schema.${resource}.formats должен содержать JSON-объект с непустыми строковыми путями и форматами`);
+    }
+
+    if (resourceConfig.properties != null) {
+      if (!isObject(resourceConfig.properties)) {
+        throw new Error(`$schema.${resource}.properties должен содержать JSON-объект`);
+      }
+
+      Object.entries(resourceConfig.properties).forEach(([key, value]) => validateSchemaOverride(value, `${resource}.${key}`));
+    }
+  });
+
+  return resourceConfigs;
+};
+
+const applyConfiguredFields = (schema, resource, resourceConfig) => {
+  const requiredFields = Array.isArray(resourceConfig.required) ? resourceConfig.required : [];
+  const formats = isObject(resourceConfig.formats) ? resourceConfig.formats : {};
+
+  [...requiredFields, ...Object.keys(formats)].forEach((path) => {
+    if (getSchemasAtPath(schema, path.split('.')).length === 0) {
+      throw new Error(`Путь «${path}» из настроек ресурса «${resource}» отсутствует в итоговой схеме`);
+    }
+  });
+
+  const schemaWithFormats = Object.entries(formats).reduce((result, [path, format]) => {
+    const schemas = getSchemasAtPath(result, path.split('.'));
+
+    if (!schemas.some((nestedSchema) => nestedSchema.type === 'string')) {
+      throw new Error(`Формат «${format}» для пути «${resource}.${path}» можно применить только к строковому полю`);
+    }
+
+    return updateSchemasAtPath(result, path.split('.'), (nestedSchema) => nestedSchema.type === 'string' ? { ...nestedSchema, format } : nestedSchema);
+  }, schema);
+
+  return applyRequiredFields(schemaWithFormats, '', new Set(requiredFields));
+};
+
 const omitId = (schema, keepRequired) => {
   const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).filter(([key]) => key !== 'id'));
   const required = keepRequired ? schema.required?.filter((key) => key !== 'id') : undefined;
@@ -149,8 +349,8 @@ const omitId = (schema, keepRequired) => {
 const createParameters = () => ({
   Embed: { description: 'Relationship paths to embed', explode: true, in: 'query', name: '_embed', schema: { items: { type: 'string' }, type: 'array' }, style: 'form' },
   Id: { in: 'path', name: 'id', required: true, schema: { type: 'string' } },
-  Page: { in: 'query', name: '_page', required: true, schema: { minimum: 1, type: 'integer' } },
-  PerPage: { in: 'query', name: '_perPage', required: true, schema: { minimum: 1, type: 'integer' } },
+  Page: { in: 'query', name: '_page', required: false, schema: { default: 1, minimum: 1, type: 'integer' } },
+  PerPage: { in: 'query', name: '_perPage', required: false, schema: { default: 10, minimum: 1, type: 'integer' } },
   Sort: { description: 'Comma-separated fields; prefix with - for descending order', in: 'query', name: '_sort', schema: { type: 'string' } },
   Where: { description: 'JSON-encoded deep filter', in: 'query', name: '_where', schema: { type: 'string' } },
 });
@@ -210,19 +410,63 @@ const createResourcePaths = (resource, componentName) => {
   };
 };
 
+const getOperationIds = (resource) => {
+  const resourceName = toPascalCase(resource);
+
+  return [`get${resourceName}`, `post${resourceName}`, `delete${resourceName}ById`, `get${resourceName}ById`, `patch${resourceName}ById`, `put${resourceName}ById`];
+};
+
+const validateGeneratedNames = (resources, componentNames) => {
+  const schemaOwners = new Map([['Error', 'встроенная схема ошибки']]);
+  const operationOwners = new Map();
+
+  resources.forEach((resource) => {
+    const componentName = componentNames[resource];
+
+    if (componentName === '') {
+      throw new Error(`Не удалось сформировать имя OpenAPI-схемы для ресурса «${resource}». Укажите $schema.${resource}.name`);
+    }
+
+    [componentName, `${componentName}Create`, `${componentName}Update`, `${componentName}Page`].forEach((schemaName) => {
+      const owner = schemaOwners.get(schemaName);
+
+      if (owner != null) {
+        throw new Error(`Имя OpenAPI-схемы «${schemaName}» используется ресурсами «${owner}» и «${resource}». Укажите уникальный $schema.${resource}.name`);
+      }
+
+      schemaOwners.set(schemaName, resource);
+    });
+
+    getOperationIds(resource).forEach((operationId) => {
+      const owner = operationOwners.get(operationId);
+
+      if (owner != null) {
+        throw new Error(`operationId «${operationId}» используется ресурсами «${owner}» и «${resource}». Переименуйте один из ресурсов`);
+      }
+
+      operationOwners.set(operationId, resource);
+    });
+  });
+};
+
 export function createOpenApiDocument(database, schemaConfig = {}, { host = '127.0.0.1', port = 4001 } = {}) {
-  if (!isObject(database) || !isObject(schemaConfig)) {
-    throw new Error('База данных и её схема должны содержать JSON-объекты');
+  validateDatabase(database);
+
+  if (!isObject(schemaConfig)) {
+    throw new Error('Схема базы данных должна содержать JSON-объект');
   }
 
   const resources = getResourceNames(database);
-  const resourceConfigs = isObject(schemaConfig.$schema) ? schemaConfig.$schema : {};
+  const resourceConfigs = validateSchemaConfig(schemaConfig, resources);
   const componentNames = Object.fromEntries(resources.map((resource) => {
     const resourceConfig = isObject(resourceConfigs[resource]) ? resourceConfigs[resource] : {};
     const componentName = typeof resourceConfig.name === 'string' && resourceConfig.name !== '' ? resourceConfig.name : toPascalCase(singularize(resource));
 
     return [resource, componentName];
   }));
+
+  validateGeneratedNames(resources, componentNames);
+
   const schemas = {
     Error: { properties: { error: { type: 'string' } }, required: ['error'], type: 'object' },
   };
@@ -230,12 +474,9 @@ export function createOpenApiDocument(database, schemaConfig = {}, { host = '127
   resources.forEach((resource) => {
     const componentName = componentNames[resource];
     const resourceConfig = isObject(resourceConfigs[resource]) ? resourceConfigs[resource] : {};
-    const options = {
-      formats: isObject(resourceConfig.formats) ? resourceConfig.formats : {},
-      required: new Set(Array.isArray(resourceConfig.required) ? resourceConfig.required : []),
-    };
     const values = database[resource].filter(isObject);
-    const rawSchema = values.length === 0 ? { additionalProperties: true, type: 'object' } : inferObjectSchema(values, '', options);
+    const inferredSchema = values.length === 0 ? { properties: { id: { type: 'string' } }, type: 'object' } : inferObjectSchema(values);
+    const rawSchema = applyConfiguredFields(mergeSchemaOverrides(inferredSchema, { properties: isObject(resourceConfig.properties) ? resourceConfig.properties : {} }), resource, resourceConfig);
     const responseSchema = addRelationSchemas(rawSchema, resources, componentNames, resource);
 
     schemas[componentName] = responseSchema;

package/src/query.js

@@ -2,6 +2,19 @@ import { createHttpError, isEqual, isObject, isSafeKey, toArray } from './utils.
 
 const FIELD_OPERATORS = new Set(['contains', 'endsWith', 'eq', 'every', 'gt', 'gte', 'in', 'lt', 'lte', 'ne', 'none', 'not', 'some', 'startsWith']);
 const RESERVED_QUERY_KEYS = new Set(['_embed', '_page', '_perPage', '_sort', '_where']);
+const NUMBER_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+
+const isFilterEqual = (left, right) => {
+  if (isEqual(left, right)) {
+    return true;
+  }
+
+  if (typeof left === 'number' && typeof right === 'string' && NUMBER_PATTERN.test(right)) {
+    return left === Number(right);
+  }
+
+  return typeof right === 'number' && typeof left === 'string' && NUMBER_PATTERN.test(left) && right === Number(left);
+};
 
 const compareValues = (left, right) => {
   if (Object.is(left, right)) {
@@ -32,11 +45,11 @@ const matchesOperator = (field, operator, expectedValue) => {
     case 'contains':
       return typeof field === 'string'
         ? field.toLowerCase().includes(String(expectedValue).toLowerCase())
-        : Array.isArray(field) && field.some((value) => isEqual(value, expectedValue));
+        : Array.isArray(field) && field.some((value) => isFilterEqual(value, expectedValue));
     case 'endsWith':
       return typeof field === 'string' && field.toLowerCase().endsWith(String(expectedValue).toLowerCase());
     case 'eq':
-      return isEqual(field, expectedValue);
+      return isFilterEqual(field, expectedValue);
     case 'every':
       return Array.isArray(field) && field.every((value) => matchesValue(value, expectedValue));
     case 'gt':
@@ -47,15 +60,15 @@ const matchesOperator = (field, operator, expectedValue) => {
       const expectedValues = toArray(expectedValue);
 
       return Array.isArray(field)
-        ? field.some((value) => expectedValues.some((expectedItem) => isEqual(value, expectedItem)))
-        : expectedValues.some((expectedItem) => isEqual(field, expectedItem));
+        ? field.some((value) => expectedValues.some((expectedItem) => isFilterEqual(value, expectedItem)))
+        : expectedValues.some((expectedItem) => isFilterEqual(field, expectedItem));
     }
     case 'lt':
       return field != null && field < expectedValue;
     case 'lte':
       return field != null && field <= expectedValue;
     case 'ne':
-      return !isEqual(field, expectedValue);
+      return !isFilterEqual(field, expectedValue);
     case 'none':
       return Array.isArray(field) && !field.some((value) => matchesValue(value, expectedValue));
     case 'not':
@@ -71,7 +84,7 @@ const matchesOperator = (field, operator, expectedValue) => {
 
 function matchesValue(field, condition) {
   if (!isObject(condition)) {
-    return isEqual(field, condition);
+    return isFilterEqual(field, condition);
   }
 
   const conditionEntries = Object.entries(condition);
@@ -108,6 +121,10 @@ function matchesWhere(value, where) {
 }
 
 const parsePrimitive = (value) => {
+  if (typeof value !== 'string') {
+    return value;
+  }
+
   if (value === 'true') {
     return true;
   }
@@ -116,7 +133,11 @@ const parsePrimitive = (value) => {
     return false;
   }
 
-  return value === 'null' ? null : value;
+  if (value === 'null') {
+    return null;
+  }
+
+  return NUMBER_PATTERN.test(value) && Number.isFinite(Number(value)) ? Number(value) : value;
 };
 
 const parseFilterKey = (key) => {
@@ -126,7 +147,11 @@ const parseFilterKey = (key) => {
     const path = key.slice(0, colonIndex);
     const operator = key.slice(colonIndex + 1);
 
-    return FIELD_OPERATORS.has(operator) ? { operator, path } : undefined;
+    if (!FIELD_OPERATORS.has(operator)) {
+      throw createHttpError(400, `Неизвестный оператор «${operator}» в фильтре «${key}»`);
+    }
+
+    return { operator, path };
   }
 
   const legacyOperator = key.match(/^(.*)_([a-zA-Z]+)$/);
@@ -139,10 +164,10 @@ const parseFilterKey = (key) => {
 };
 
 const setWhereOperator = (where, path, operator, value) => {
-  const keys = path.split('.').filter(Boolean);
+  const keys = path.split('.');
 
-  if (keys.length === 0 || keys.some((key) => !isSafeKey(key))) {
-    return;
+  if (keys.some((key) => key === '' || !isSafeKey(key))) {
+    throw createHttpError(400, `Недопустимый путь фильтра «${path}»`);
   }
 
   const fieldKey = keys.pop();
@@ -191,6 +216,120 @@ export const parseWhere = (query) => {
   return where;
 };
 
+const validateCondition = (condition, samples, path) => {
+  if (!isObject(condition)) {
+    return;
+  }
+
+  Object.entries(condition).forEach(([key, value]) => {
+    if (key === 'and' || key === 'or') {
+      if (!Array.isArray(value) || key === 'or' && value.length === 0 || value.some((nestedWhere) => !isObject(nestedWhere))) {
+        throw createHttpError(400, `Оператор «${key}» должен содержать ${key === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
+      }
+
+      value.forEach((nestedWhere) => validateWhere(nestedWhere, samples, path));
+      return;
+    }
+
+    if (FIELD_OPERATORS.has(key)) {
+      if (['every', 'none', 'some'].includes(key)) {
+        if (samples.length > 0 && !samples.some(Array.isArray)) {
+          throw createHttpError(400, `Оператор «${key}» в фильтре «${path}» можно применить только к массиву`);
+        }
+
+        const nestedSamples = samples.flatMap((sample) => Array.isArray(sample) ? sample : []);
+
+        validateCondition(value, nestedSamples, `${path}.${key}`);
+      } else if (key === 'not') {
+        validateCondition(value, samples, `${path}.not`);
+      } else if (['endsWith', 'startsWith'].includes(key) && samples.length > 0 && !samples.some((sample) => typeof sample === 'string')) {
+        throw createHttpError(400, `Оператор «${key}» в фильтре «${path}» можно применить только к строке`);
+      } else if (key === 'contains' && samples.length > 0 && !samples.some((sample) => typeof sample === 'string' || Array.isArray(sample))) {
+        throw createHttpError(400, `Оператор «contains» в фильтре «${path}» можно применить только к строке или массиву`);
+      }
+
+      return;
+    }
+
+    if (!isSafeKey(key)) {
+      throw createHttpError(400, `Недопустимый путь фильтра «${path}.${key}»`);
+    }
+
+    const objectSamples = samples.filter(isObject);
+
+    if (samples.length > 0 && objectSamples.length === 0) {
+      throw createHttpError(400, `Неизвестный оператор или вложенное поле «${path}.${key}»`);
+    }
+
+    const nestedSamples = objectSamples.filter((sample) => Object.hasOwn(sample, key)).map((sample) => sample[key]);
+
+    if (objectSamples.length > 0 && nestedSamples.length === 0) {
+      throw createHttpError(400, `Неизвестное поле фильтра «${path}.${key}»`);
+    }
+
+    validateCondition(value, nestedSamples, `${path}.${key}`);
+  });
+};
+
+export const validateWhere = (where, items, path = '') => {
+  Object.entries(where).forEach(([key, condition]) => {
+    if (key === 'and' || key === 'or') {
+      if (!Array.isArray(condition) || key === 'or' && condition.length === 0 || condition.some((nestedWhere) => !isObject(nestedWhere))) {
+        throw createHttpError(400, `Оператор «${key}» должен содержать ${key === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
+      }
+
+      condition.forEach((nestedWhere) => validateWhere(nestedWhere, items, path));
+      return;
+    }
+
+    if (key === 'not') {
+      if (!isObject(condition)) {
+        throw createHttpError(400, 'Оператор «not» должен содержать JSON-объект');
+      }
+
+      validateWhere(condition, items, path);
+      return;
+    }
+
+    if (!isSafeKey(key)) {
+      throw createHttpError(400, `Недопустимый путь фильтра «${path === '' ? key : `${path}.${key}`}»`);
+    }
+
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+    const objectItems = items.filter(isObject);
+    const samples = objectItems.filter((item) => Object.hasOwn(item, key)).map((item) => item[key]);
+
+    if (objectItems.length > 0 && samples.length === 0) {
+      throw createHttpError(400, `Неизвестное поле фильтра «${fieldPath}»`);
+    }
+
+    validateCondition(condition, samples, fieldPath);
+  });
+};
+
+const parsePositiveInteger = (value, name, defaultValue) => {
+  if (value == null) {
+    return defaultValue;
+  }
+
+  if (Array.isArray(value) || !/^[1-9]\d*$/.test(String(value))) {
+    throw createHttpError(400, `Параметр ${name} должен быть положительным целым числом`);
+  }
+
+  const number = Number(value);
+
+  if (!Number.isSafeInteger(number)) {
+    throw createHttpError(400, `Параметр ${name} должен быть положительным целым числом`);
+  }
+
+  return number;
+};
+
+export const parsePagination = (query) => ({
+  page: parsePositiveInteger(query._page, '_page', 1),
+  pageSize: parsePositiveInteger(query._perPage, '_perPage', 10),
+});
+
 export const paginateItems = (items, page, pageSize) => {
   const safePageSize = Number.isFinite(pageSize) && pageSize > 0 ? Math.floor(pageSize) : 10;
   const pages = Math.max(1, Math.ceil(items.length / safePageSize));

package/src/relations.js

@@ -45,7 +45,23 @@ const hasReference = (value, relationKeys, id) => {
   });
 };
 
-const findRelatedValue = (database, item, sourceResource, relation, targetResource) => {
+const getResourceIndex = (database, resource, indexes) => {
+  if (!indexes.has(resource)) {
+    const index = new Map();
+
+    database.data[resource].forEach((item) => {
+      if (isObject(item) && item.id != null && !index.has(item.id)) {
+        index.set(item.id, item);
+      }
+    });
+
+    indexes.set(resource, index);
+  }
+
+  return indexes.get(resource);
+};
+
+const findRelatedValue = (database, item, sourceResource, relation, targetResource, indexes) => {
   const targetItems = database.data[targetResource];
   const localRelation = findLocalRelation(item, relation, targetResource);
 
@@ -54,7 +70,8 @@ const findRelatedValue = (database, item, sourceResource, relation, targetResour
   }
 
   if (localRelation != null) {
-    const relatedItems = localRelation.ids.map((id) => targetItems.find((targetItem) => isObject(targetItem) && isEqual(targetItem.id, id))).filter((targetItem) => targetItem != null);
+    const targetIndex = getResourceIndex(database, targetResource, indexes);
+    const relatedItems = localRelation.ids.map((id) => targetIndex.get(id)).filter((targetItem) => targetItem != null);
 
     return localRelation.isMany ? relatedItems : relatedItems[0] ?? null;
   }
@@ -72,29 +89,31 @@ const findRelatedValue = (database, item, sourceResource, relation, targetResour
   return targetItems.filter((targetItem) => hasReference(targetItem, reverseRelationKeys, item.id));
 };
 
-const embedPath = (database, item, sourceResource, [relation, ...nestedRelations]) => {
+const embedPath = (database, item, sourceResource, [relation, ...nestedRelations], indexes) => {
   if (relation == null || !isSafeKey(relation)) {
     return item;
   }
 
   const currentValue = item[relation];
-  const nestedSourceResource = resolveResource(database, relation, sourceResource) ?? relation;
+  const targetResource = resolveResource(database, relation, sourceResource);
+  const nestedSourceResource = targetResource ?? relation;
+  const localRelation = targetResource == null ? undefined : findLocalRelation(item, relation, targetResource);
 
-  if (Array.isArray(currentValue)) {
-    return nestedRelations.length === 0 ? item : { ...item, [relation]: currentValue.map((value) => (isObject(value) ? embedPath(database, value, nestedSourceResource, nestedRelations) : value)) };
-  }
+  if (localRelation == null) {
+    if (Array.isArray(currentValue)) {
+      return nestedRelations.length === 0 ? item : { ...item, [relation]: currentValue.map((value) => (isObject(value) ? embedPath(database, value, nestedSourceResource, nestedRelations, indexes) : value)) };
+    }
 
-  if (isObject(currentValue)) {
-    return nestedRelations.length === 0 ? item : { ...item, [relation]: embedPath(database, currentValue, nestedSourceResource, nestedRelations) };
+    if (isObject(currentValue)) {
+      return nestedRelations.length === 0 ? item : { ...item, [relation]: embedPath(database, currentValue, nestedSourceResource, nestedRelations, indexes) };
+    }
   }
 
-  const targetResource = resolveResource(database, relation, sourceResource);
-
   if (targetResource == null) {
     return item;
   }
 
-  const relatedValue = findRelatedValue(database, item, sourceResource, relation, targetResource);
+  const relatedValue = findRelatedValue(database, item, sourceResource, relation, targetResource, indexes);
 
   if (relatedValue == null || nestedRelations.length === 0) {
     return relatedValue === undefined ? item : { ...item, [relation]: relatedValue };
@@ -103,8 +122,8 @@ const embedPath = (database, item, sourceResource, [relation, ...nestedRelations
   return {
     ...item,
     [relation]: Array.isArray(relatedValue)
-      ? relatedValue.map((value) => embedPath(database, value, targetResource, nestedRelations))
-      : embedPath(database, relatedValue, targetResource, nestedRelations),
+      ? relatedValue.map((value) => embedPath(database, value, targetResource, nestedRelations, indexes))
+      : embedPath(database, relatedValue, targetResource, nestedRelations, indexes),
   };
 };
 
@@ -113,4 +132,4 @@ export const parseEmbedPaths = (embed) => toArray(embed)
   .map((path) => path.split('.').filter(Boolean))
   .filter((path) => path.length > 0 && path.every(isSafeKey));
 
-export const embedItem = (database, item, resource, embedPaths) => embedPaths.reduce((embeddedItem, path) => embedPath(database, embeddedItem, resource, path), item);
+export const embedItem = (database, item, resource, embedPaths, indexes = new Map()) => embedPaths.reduce((embeddedItem, path) => embedPath(database, embeddedItem, resource, path, indexes), item);

package/src/server.js

@@ -1,9 +1,10 @@
 import Fastify from 'fastify';
 import { JSONFilePreset } from 'lowdb/node';
 import { randomBytes } from 'node:crypto';
-import { matchesWhere, paginateItems, parseWhere, sortItems } from './query.js';
+import { readFile } from 'node:fs/promises';
+import { matchesWhere, paginateItems, parsePagination, parseWhere, sortItems, validateWhere } from './query.js';
 import { embedItem, parseEmbedPaths } from './relations.js';
-import { createHttpError, getResourceNames, isObject, isSafeKey, resolveDatabasePath } from './utils.js';
+import { createHttpError, getResourceNames, isObject, isSafeKey, resolveDatabasePath, validateDatabase } from './utils.js';
 
 const CORS_HEADERS = {
   'Access-Control-Allow-Headers': 'Content-Type',
@@ -31,16 +32,59 @@ const getRequestBody = (body) => {
 
 const findItem = (collection, id) => collection.find((item) => isObject(item) && String(item.id) === id);
 
+const readDatabaseFile = async(databasePath) => {
+  let source;
+
+  try {
+    source = await readFile(databasePath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`Файл базы данных не найден: ${databasePath}`);
+    }
+
+    throw error;
+  }
+
+  const data = JSON.parse(source);
+
+  return validateDatabase(data);
+};
+
 export async function createServer({ databasePath, logger = true } = {}) {
-  const database = await JSONFilePreset(resolveDatabasePath(databasePath), {});
+  const resolvedDatabasePath = resolveDatabasePath(databasePath);
+  const initialData = await readDatabaseFile(resolvedDatabasePath);
+  const database = await JSONFilePreset(resolvedDatabasePath, initialData);
   const server = Fastify({ logger });
+  let databaseWriteQueue = Promise.resolve();
+
+  const readDatabase = async() => {
+    database.data = await readDatabaseFile(resolvedDatabasePath);
+  };
+
+  const updateDatabase = (update) => {
+    const operation = databaseWriteQueue.then(async() => {
+      await readDatabase();
+
+      const result = update();
+
+      await database.write();
+
+      return result;
+    });
+
+    databaseWriteQueue = operation.catch(() => undefined);
+
+    return operation;
+  };
 
   server.addHook('onRequest', async(_request, reply) => {
     Object.entries(CORS_HEADERS).forEach(([header, value]) => reply.header(header, value));
   });
 
-  server.addHook('preHandler', async() => {
-    await database.read();
+  server.addHook('preHandler', async(request) => {
+    if (request.method === 'GET') {
+      await readDatabase();
+    }
   });
 
   server.options('/', async(_request, reply) => reply.code(204).send());
@@ -51,12 +95,16 @@ export async function createServer({ databasePath, logger = true } = {}) {
     const collection = getCollection(database, request.params.resource);
     const where = parseWhere(request.query);
     const embedPaths = parseEmbedPaths(request.query._embed);
-    const embeddedItems = collection.map((item) => embedItem(database, item, request.params.resource, embedPaths));
+    const relationIndexes = new Map();
+    const embeddedItems = collection.map((item) => embedItem(database, item, request.params.resource, embedPaths, relationIndexes));
+    const pagination = parsePagination(request.query);
+
+    validateWhere(where, embeddedItems);
+
     const filteredItems = embeddedItems.filter((item) => matchesWhere(item, where));
     const sortedItems = sortItems(filteredItems, request.query._sort);
-    const page = request.query._page == null ? undefined : Number(request.query._page);
 
-    return page == null ? sortedItems : paginateItems(sortedItems, page, Number(request.query._perPage));
+    return paginateItems(sortedItems, pagination.page, pagination.pageSize);
   });
 
   server.get('/:resource/:id', async(request) => {
@@ -70,59 +118,65 @@ export async function createServer({ databasePath, logger = true } = {}) {
   });
 
   server.post('/:resource', async(request, reply) => {
-    const collection = getCollection(database, request.params.resource);
-    const item = { ...getRequestBody(request.body), id: randomBytes(8).toString('base64url') };
+    const item = await updateDatabase(() => {
+      const collection = getCollection(database, request.params.resource);
+      const createdItem = { ...getRequestBody(request.body), id: randomBytes(8).toString('base64url') };
+
+      collection.push(createdItem);
 
-    collection.push(item);
-    await database.write();
+      return createdItem;
+    });
 
     return reply.code(201).send(item);
   });
 
   server.put('/:resource/:id', async(request) => {
-    const collection = getCollection(database, request.params.resource);
-    const currentItem = findItem(collection, request.params.id);
+    return updateDatabase(() => {
+      const collection = getCollection(database, request.params.resource);
+      const currentItem = findItem(collection, request.params.id);
 
-    if (currentItem == null) {
-      throw createHttpError(404, 'Запись не найдена');
-    }
+      if (currentItem == null) {
+        throw createHttpError(404, 'Запись не найдена');
+      }
 
-    const item = { ...getRequestBody(request.body), id: request.params.id };
+      const item = { ...getRequestBody(request.body), id: currentItem.id };
 
-    collection.splice(collection.indexOf(currentItem), 1, item);
-    await database.write();
+      collection.splice(collection.indexOf(currentItem), 1, item);
 
-    return item;
+      return item;
+    });
   });
 
   server.patch('/:resource/:id', async(request) => {
-    const collection = getCollection(database, request.params.resource);
-    const currentItem = findItem(collection, request.params.id);
+    return updateDatabase(() => {
+      const collection = getCollection(database, request.params.resource);
+      const currentItem = findItem(collection, request.params.id);
 
-    if (currentItem == null) {
-      throw createHttpError(404, 'Запись не найдена');
-    }
+      if (currentItem == null) {
+        throw createHttpError(404, 'Запись не найдена');
+      }
 
-    const item = { ...currentItem, ...getRequestBody(request.body), id: request.params.id };
+      const item = { ...currentItem, ...getRequestBody(request.body), id: currentItem.id };
 
-    collection.splice(collection.indexOf(currentItem), 1, item);
-    await database.write();
+      collection.splice(collection.indexOf(currentItem), 1, item);
 
-    return item;
+      return item;
+    });
   });
 
   server.delete('/:resource/:id', async(request) => {
-    const collection = getCollection(database, request.params.resource);
-    const currentItem = findItem(collection, request.params.id);
+    return updateDatabase(() => {
+      const collection = getCollection(database, request.params.resource);
+      const currentItem = findItem(collection, request.params.id);
 
-    if (currentItem == null) {
-      throw createHttpError(404, 'Запись не найдена');
-    }
+      if (currentItem == null) {
+        throw createHttpError(404, 'Запись не найдена');
+      }
 
-    collection.splice(collection.indexOf(currentItem), 1);
-    await database.write();
+      collection.splice(collection.indexOf(currentItem), 1);
 
-    return currentItem;
+      return currentItem;
+    });
   });
 
   server.setErrorHandler((error, request, reply) => {

package/src/utils.js

@@ -13,12 +13,26 @@ export const createHttpError = (statusCode, message) => {
   return error;
 };
 
-export const getResourceNames = (data) => Object.entries(data).filter(([, value]) => Array.isArray(value)).map(([resource]) => resource);
+export const getResourceNames = (data) => Object.keys(data);
 export const isMainModule = (filePath, moduleUrl) => filePath != null && realpathSync(resolve(filePath)) === fileURLToPath(moduleUrl);
 export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 export const isSafeKey = (key) => !UNSAFE_KEYS.has(key);
 export const toArray = (value) => (Array.isArray(value) ? value : [value]);
 
+export const validateDatabase = (data) => {
+  if (!isObject(data)) {
+    throw new Error('База данных должна содержать JSON-объект');
+  }
+
+  const invalidResource = Object.entries(data).find(([, value]) => !Array.isArray(value));
+
+  if (invalidResource != null) {
+    throw new Error(`Ресурс «${invalidResource[0]}» должен содержать JSON-массив`);
+  }
+
+  return data;
+};
+
 export const isEqual = (left, right) => {
   if (Object.is(left, right)) {
     return true;