@kollors/deep-json-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kollors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# Deep JSON Server
+
+[English](README.md) | [Русский](README.ru.md)
+
+A small JSON REST mock server with CRUD, pagination, deep filters and recursive relationship embedding. It keeps the database in one readable JSON file and infers soft relations from conventional keys such as `countryId`, `genreIds` and `publisherIds`.
+
+## Installation
+
+```bash
+npm install --save-dev @kollors/deep-json-server
+```
+
+Add a script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "mock": "deep-json-server mock/database.json --port 4001"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run mock
+```
+
+The default address is `http://127.0.0.1:4001`. You can also pass `--host` and `--port`, or set the `HOST` and `PORT` environment variables.
+
+## Example database
+
+This example is based on a movie catalog. It intentionally has no clothes resource. The genre names are real film genres, while `Gangster film` demonstrates a self-referencing subgenre.
+
+```json
+{
+  "countries": [
+    { "id": "1", "isArchived": false, "name": "Russia" },
+    { "id": "2", "isArchived": false, "name": "United States" }
+  ],
+  "genres": [
+    { "id": "1", "isArchived": false, "name": "Crime", "parentIds": [] },
+    { "id": "2", "isArchived": false, "name": "Gangster film", "parentIds": ["1"] },
+    { "id": "3", "isArchived": false, "name": "Drama", "parentIds": [] },
+    { "id": "4", "isArchived": false, "name": "Comedy", "parentIds": [] }
+  ],
+  "movies": [
+    {
+      "actors": [
+        { "genreIds": ["2", "3"], "id": "movie-1-actor-1", "userId": "1" },
+        { "genreIds": ["3"], "id": "movie-1-actor-2", "userId": "2" }
+      ],
+      "coverSrc": "https://image.tmdb.org/t/p/w500/3bhkrj58Vtu7enYsRolD1fZdja1.jpg",
+      "description": "The story of the Corleone family and the transfer of power from one generation to the next.",
+      "id": "1",
+      "isArchived": false,
+      "publisherIds": ["2"],
+      "title": "The Godfather"
+    },
+    {
+      "actors": [],
+      "coverSrc": "https://image.tmdb.org/t/p/w500/eWdyYQreja6JGCzqHWXpWHDrrPo.jpg",
+      "description": "The adventures of a concierge and his young assistant in a famous European hotel.",
+      "id": "2",
+      "isArchived": false,
+      "publisherIds": ["1"],
+      "title": "The Grand Budapest Hotel"
+    }
+  ],
+  "publishers": [
+    { "id": "1", "isArchived": false, "name": "A24" },
+    { "id": "2", "isArchived": false, "name": "Paramount Pictures" }
+  ],
+  "users": [
+    {
+      "bornAt": "1989-01-25",
+      "countryId": "1",
+      "fullName": "Alexander Petrov",
+      "id": "1",
+      "isArchived": false
+    },
+    {
+      "bornAt": "1984-09-05",
+      "countryId": "1",
+      "fullName": "Yulia Peresild",
+      "id": "2",
+      "isArchived": false
+    }
+  ]
+}
+```
+
+Every top-level array becomes a REST resource:
+
+```text
+GET    /movies
+GET    /movies/:id
+POST   /movies
+PUT    /movies/:id
+PATCH  /movies/:id
+DELETE /movies/:id
+```
+
+`POST` generates a string ID. `PUT`, `PATCH` and `DELETE` persist their changes in the JSON file.
+
+## Pagination and sorting
+
+```http
+GET /movies?_page=1&_per_page=10&_sort=-id,title
+```
+
+Without `_page`, a GET collection returns an array. With `_page`, it returns:
+
+```json
+{
+  "data": [],
+  "first": 1,
+  "items": 0,
+  "last": 1,
+  "next": null,
+  "pages": 1,
+  "prev": null
+}
+```
+
+Prefix a sort field with `-` for descending order.
+
+## Filters
+
+Pass a JSON object through `_where`:
+
+```http
+GET /movies?_where={"title":{"contains":"father"}}
+```
+
+Nested objects and arrays can be filtered at any depth. Conditions in one object use `AND` by default:
+
+```json
+{
+  "actors": { "some": { "userId": { "eq": "1" } } },
+  "title": { "contains": "father" }
+}
+```
+
+Logical operators are also available:
+
+```json
+{
+  "or": [
+    { "title": { "contains": "father" } },
+    { "actors": { "some": { "userId": { "eq": "2" } } } }
+  ]
+}
+```
+
+Supported field operators: `contains`, `endsWith`, `eq`, `every`, `gt`, `gte`, `in`, `lt`, `lte`, `ne`, `none`, `not`, `some` and `startsWith`.
+
+Simple query parameters are supported too:
+
+```http
+GET /movies?title:contains=father
+```
+
+## Relationships
+
+Use `_embed` to replace IDs with related records:
+
+```http
+GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
+```
+
+The response contains actors, each actor's user and genres, the user's country, and publishers. Embedding can follow any number of levels:
+
+```http
+GET /movies/1?_embed=actors.user.country
+GET /genres/2?_embed=parents.parents
+```
+
+Reverse relationships work as well:
+
+```http
+GET /countries/1?_embed=users
+```
+
+Relations are inferred by convention:
+
+- `countryId` points to `countries`;
+- `userId` points to `users` when the requested relation is `user`;
+- `genreIds` points to `genres`;
+- `publisherIds` points to `publishers`;
+- `parentIds` points back to the current resource when `_embed=parents` is requested.
+
+They are soft references: the server resolves them when requested but does not enforce referential integrity when data is written.
+
+## Programmatic API
+
+```js
+import { createServer, startServer } from '@kollors/deep-json-server';
+
+const server = await createServer({ databasePath: 'mock/database.json', logger: false });
+
+const response = await server.inject({ method: 'GET', url: '/movies' });
+
+await server.close();
+
+await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
+```
+
+`createServer()` is useful for tests because it returns a Fastify instance without opening a network port.

package/README.ru.md

@@ -0,0 +1,209 @@
+# Deep JSON Server
+
+[Русский](README.ru.md) | [English](README.md)
+
+Небольшой JSON REST mock-сервер с CRUD, пагинацией, глубокой фильтрацией и рекурсивной загрузкой связей. База данных хранится в одном читаемом JSON-файле, а мягкие связи определяются по соглашениям о нейминге ключей: `countryId`, `genreIds`, `publisherIds` и так далее.
+
+## Установка
+
+```bash
+npm install --save-dev @kollors/deep-json-server
+```
+
+Добавьте команду в `package.json`:
+
+```json
+{
+  "scripts": {
+    "mock": "deep-json-server mock/database.json --port 4001"
+  }
+}
+```
+
+Запустите сервер:
+
+```bash
+npm run mock
+```
+
+По умолчанию сервер доступен по адресу `http://127.0.0.1:4001`. Адрес и порт можно задать через `--host` и `--port` либо переменные окружения `HOST` и `PORT`.
+
+## Пример базы данных
+
+Пример основан на каталоге фильмов. В нём намеренно нет сущности одежды. Используются реальные жанры фильмов, а `Гангстерский фильм` демонстрирует связь с родительским жанром.
+
+```json
+{
+  "countries": [
+    { "id": "1", "isArchived": false, "name": "Россия" },
+    { "id": "2", "isArchived": false, "name": "США" }
+  ],
+  "genres": [
+    { "id": "1", "isArchived": false, "name": "Криминал", "parentIds": [] },
+    { "id": "2", "isArchived": false, "name": "Гангстерский фильм", "parentIds": ["1"] },
+    { "id": "3", "isArchived": false, "name": "Драма", "parentIds": [] },
+    { "id": "4", "isArchived": false, "name": "Комедия", "parentIds": [] }
+  ],
+  "movies": [
+    {
+      "actors": [
+        { "genreIds": ["2", "3"], "id": "movie-1-actor-1", "userId": "1" },
+        { "genreIds": ["3"], "id": "movie-1-actor-2", "userId": "2" }
+      ],
+      "coverSrc": "https://image.tmdb.org/t/p/w500/3bhkrj58Vtu7enYsRolD1fZdja1.jpg",
+      "description": "История семьи Корлеоне и передачи власти от одного поколения другому.",
+      "id": "1",
+      "isArchived": false,
+      "publisherIds": ["2"],
+      "title": "Крёстный отец"
+    },
+    {
+      "actors": [],
+      "coverSrc": "https://image.tmdb.org/t/p/w500/eWdyYQreja6JGCzqHWXpWHDrrPo.jpg",
+      "description": "Приключения консьержа и его юного помощника в знаменитом европейском отеле.",
+      "id": "2",
+      "isArchived": false,
+      "publisherIds": ["1"],
+      "title": "Отель «Гранд Будапешт»"
+    }
+  ],
+  "publishers": [
+    { "id": "1", "isArchived": false, "name": "A24" },
+    { "id": "2", "isArchived": false, "name": "Paramount Pictures" }
+  ],
+  "users": [
+    {
+      "bornAt": "1989-01-25",
+      "countryId": "1",
+      "fullName": "Александр Петров",
+      "id": "1",
+      "isArchived": false
+    },
+    {
+      "bornAt": "1984-09-05",
+      "countryId": "1",
+      "fullName": "Юлия Пересильд",
+      "id": "2",
+      "isArchived": false
+    }
+  ]
+}
+```
+
+Каждый массив верхнего уровня становится REST-ресурсом:
+
+```text
+GET    /movies
+GET    /movies/:id
+POST   /movies
+PUT    /movies/:id
+PATCH  /movies/:id
+DELETE /movies/:id
+```
+
+`POST` генерирует строковый ID. `PUT`, `PATCH` и `DELETE` сохраняют изменения в JSON-файле.
+
+## Пагинация и сортировка
+
+```http
+GET /movies?_page=1&_per_page=10&_sort=-id,title
+```
+
+Без `_page` GET-запрос к коллекции возвращает массив. С `_page` возвращается объект:
+
+```json
+{
+  "data": [],
+  "first": 1,
+  "items": 0,
+  "last": 1,
+  "next": null,
+  "pages": 1,
+  "prev": null
+}
+```
+
+Префикс `-` перед полем включает сортировку по убыванию.
+
+## Фильтры
+
+Передайте JSON-объект через `_where`:
+
+```http
+GET /movies?_where={"title":{"contains":"отец"}}
+```
+
+Можно фильтровать вложенные объекты и массивы на любой глубине. Условия внутри одного объекта по умолчанию объединяются через `AND`:
+
+```json
+{
+  "actors": { "some": { "userId": { "eq": "1" } } },
+  "title": { "contains": "отец" }
+}
+```
+
+Доступны логические операторы:
+
+```json
+{
+  "or": [
+    { "title": { "contains": "отец" } },
+    { "actors": { "some": { "userId": { "eq": "2" } } } }
+  ]
+}
+```
+
+Поддерживаются операторы полей: `contains`, `endsWith`, `eq`, `every`, `gt`, `gte`, `in`, `lt`, `lte`, `ne`, `none`, `not`, `some` и `startsWith`.
+
+Также можно использовать простые query-параметры:
+
+```http
+GET /movies?title:contains=отец
+```
+
+## Связи
+
+Используйте `_embed`, чтобы заменить ID связанными записями:
+
+```http
+GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
+```
+
+Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Глубина вложения не ограничена:
+
+```http
+GET /movies/1?_embed=actors.user.country
+GET /genres/2?_embed=parents.parents
+```
+
+Поддерживаются и обратные связи:
+
+```http
+GET /countries/1?_embed=users
+```
+
+Связи определяются по неймингу:
+
+- `countryId` ссылается на `countries`;
+- `userId` ссылается на `users`, если запрошена связь `user`;
+- `genreIds` ссылается на `genres`;
+- `publisherIds` ссылается на `publishers`;
+- `parentIds` ссылается на тот же ресурс, если запрошена связь `_embed=parents`.
+
+Это мягкие ссылки: сервер загружает их по запросу, но не проверяет ссылочную целостность при записи данных.
+
+## Программный API
+
+```js
+import { createServer, startServer } from '@kollors/deep-json-server';
+
+const server = await createServer({ databasePath: 'mock/database.json', logger: false });
+
+const response = await server.inject({ method: 'GET', url: '/movies' });
+
+await server.close();
+
+await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
+```
+
+`createServer()` удобен для тестов: он возвращает экземпляр Fastify, не открывая сетевой порт.

package/index.js

@@ -0,0 +1,589 @@
+#!/usr/bin/env node
+
+import Fastify from 'fastify';
+import { JSONFilePreset } from 'lowdb/node';
+import { randomBytes } from 'node:crypto';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+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', '_per_page', '_sort', '_where']);
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+const CORS_HEADERS = {
+  'Access-Control-Allow-Headers': 'Content-Type',
+  'Access-Control-Allow-Methods': 'DELETE, GET, OPTIONS, PATCH, POST, PUT',
+  'Access-Control-Allow-Origin': '*',
+};
+
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isSafeKey = (key) => !UNSAFE_KEYS.has(key);
+const toArray = (value) => (Array.isArray(value) ? value : [value]);
+
+const createHttpError = (statusCode, message) => {
+  const error = new Error(message);
+
+  error.statusCode = statusCode;
+
+  return error;
+};
+
+const isEqual = (left, right) => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => isEqual(value, right[index]));
+  }
+
+  if (isObject(left) && isObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+
+    return leftKeys.length === rightKeys.length && leftKeys.every((key) => isSafeKey(key) && Object.hasOwn(right, key) && isEqual(left[key], right[key]));
+  }
+
+  return false;
+};
+
+const compareValues = (left, right) => {
+  if (Object.is(left, right)) {
+    return 0;
+  }
+
+  if (left == null) {
+    return 1;
+  }
+
+  if (right == null) {
+    return -1;
+  }
+
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left - right;
+  }
+
+  return String(left).localeCompare(String(right), undefined, { numeric: true, sensitivity: 'base' });
+};
+
+const getValueByPath = (value, path) => path.split('.').reduce((currentValue, key) => {
+  return isSafeKey(key) && currentValue != null ? currentValue[key] : undefined;
+}, value);
+
+const matchesOperator = (field, operator, expectedValue) => {
+  switch (operator) {
+    case 'contains':
+      return typeof field === 'string'
+        ? field.toLowerCase().includes(String(expectedValue).toLowerCase())
+        : Array.isArray(field) && field.some((value) => isEqual(value, expectedValue));
+    case 'endsWith':
+      return typeof field === 'string' && field.toLowerCase().endsWith(String(expectedValue).toLowerCase());
+    case 'eq':
+      return isEqual(field, expectedValue);
+    case 'every':
+      return Array.isArray(field) && field.every((value) => matchesValue(value, expectedValue));
+    case 'gt':
+      return field != null && field > expectedValue;
+    case 'gte':
+      return field != null && field >= expectedValue;
+    case 'in': {
+      const expectedValues = toArray(expectedValue);
+
+      return Array.isArray(field)
+        ? field.some((value) => expectedValues.some((expectedItem) => isEqual(value, expectedItem)))
+        : expectedValues.some((expectedItem) => isEqual(field, expectedItem));
+    }
+    case 'lt':
+      return field != null && field < expectedValue;
+    case 'lte':
+      return field != null && field <= expectedValue;
+    case 'ne':
+      return !isEqual(field, expectedValue);
+    case 'none':
+      return Array.isArray(field) && !field.some((value) => matchesValue(value, expectedValue));
+    case 'not':
+      return !matchesValue(field, expectedValue);
+    case 'some':
+      return Array.isArray(field) && field.some((value) => matchesValue(value, expectedValue));
+    case 'startsWith':
+      return typeof field === 'string' && field.toLowerCase().startsWith(String(expectedValue).toLowerCase());
+    default:
+      return false;
+  }
+};
+
+function matchesValue(field, condition) {
+  if (!isObject(condition)) {
+    return isEqual(field, condition);
+  }
+
+  const conditionEntries = Object.entries(condition);
+  const operatorEntries = conditionEntries.filter(([operator]) => FIELD_OPERATORS.has(operator));
+  const nestedEntries = conditionEntries.filter(([key]) => !FIELD_OPERATORS.has(key));
+
+  if (!operatorEntries.every(([operator, expectedValue]) => matchesOperator(field, operator, expectedValue))) {
+    return false;
+  }
+
+  if (nestedEntries.length === 0) {
+    return true;
+  }
+
+  return isObject(field) && matchesWhere(field, Object.fromEntries(nestedEntries));
+}
+
+function matchesWhere(value, where) {
+  if (!isObject(value) || !isObject(where)) {
+    return false;
+  }
+
+  return Object.entries(where).every(([key, condition]) => {
+    if (key === 'and') {
+      return Array.isArray(condition) && condition.every((nestedWhere) => matchesWhere(value, nestedWhere));
+    }
+
+    if (key === 'or') {
+      return Array.isArray(condition) && condition.length > 0 && condition.some((nestedWhere) => matchesWhere(value, nestedWhere));
+    }
+
+    if (key === 'not') {
+      return isObject(condition) && !matchesWhere(value, condition);
+    }
+
+    return isSafeKey(key) && matchesValue(value[key], condition);
+  });
+}
+
+const parsePrimitive = (value) => {
+  if (value === 'true') {
+    return true;
+  }
+
+  if (value === 'false') {
+    return false;
+  }
+
+  if (value === 'null') {
+    return null;
+  }
+
+  return value;
+};
+
+const parseFilterKey = (key) => {
+  const colonIndex = key.lastIndexOf(':');
+
+  if (colonIndex !== -1) {
+    const path = key.slice(0, colonIndex);
+    const operator = key.slice(colonIndex + 1);
+
+    return FIELD_OPERATORS.has(operator) ? { operator, path } : undefined;
+  }
+
+  const legacyOperator = key.match(/^(.*)_([a-zA-Z]+)$/);
+
+  if (legacyOperator?.[1] != null && legacyOperator[2] != null && FIELD_OPERATORS.has(legacyOperator[2])) {
+    return { operator: legacyOperator[2], path: legacyOperator[1] };
+  }
+
+  return { operator: 'eq', path: key };
+};
+
+const setWhereOperator = (where, path, operator, value) => {
+  const keys = path.split('.').filter(Boolean);
+
+  if (keys.length === 0 || keys.some((key) => !isSafeKey(key))) {
+    return;
+  }
+
+  const fieldKey = keys.pop();
+  let currentValue = where;
+
+  keys.forEach((key) => {
+    currentValue[key] = isObject(currentValue[key]) ? currentValue[key] : {};
+    currentValue = currentValue[key];
+  });
+
+  currentValue[fieldKey] = isObject(currentValue[fieldKey]) ? currentValue[fieldKey] : {};
+  currentValue[fieldKey][operator] = operator === 'in' && typeof value === 'string' ? value.split(',').map((item) => parsePrimitive(item.trim())) : parsePrimitive(value);
+};
+
+const parseWhere = (query) => {
+  const rawWhere = toArray(query._where).at(-1);
+
+  if (rawWhere != null) {
+    try {
+      const where = JSON.parse(rawWhere);
+
+      if (!isObject(where)) {
+        throw new Error();
+      }
+
+      return where;
+    } catch {
+      throw createHttpError(400, 'Параметр _where должен содержать JSON-объект');
+    }
+  }
+
+  const where = {};
+
+  Object.entries(query).forEach(([key, rawValue]) => {
+    if (RESERVED_QUERY_KEYS.has(key)) {
+      return;
+    }
+
+    const filterKey = parseFilterKey(key);
+
+    if (filterKey == null) {
+      return;
+    }
+
+    toArray(rawValue).forEach((value) => setWhereOperator(where, filterKey.path, filterKey.operator, value));
+  });
+
+  return where;
+};
+
+const singularize = (value) => {
+  if (value === 'clothes') {
+    return value;
+  }
+
+  if (value.endsWith('ies')) {
+    return `${value.slice(0, -3)}y`;
+  }
+
+  return value.endsWith('s') ? value.slice(0, -1) : value;
+};
+
+const getResourceNames = (database) => Object.entries(database.data).filter(([, value]) => Array.isArray(value)).map(([resource]) => resource);
+
+const resolveResource = (database, relation, sourceResource) => {
+  const resourceNames = getResourceNames(database);
+  const resource = resourceNames.find((resourceName) => resourceName === relation) ?? resourceNames.find((resourceName) => singularize(resourceName) === relation);
+
+  if (resource != null) {
+    return resource;
+  }
+
+  return ['child', 'children', 'parent', 'parents'].includes(relation) && resourceNames.includes(sourceResource) ? sourceResource : undefined;
+};
+
+const getRelationKeys = (...names) => [...new Set(names.flatMap((name) => [`${name}Id`, `${name}Ids`]))];
+
+const findLocalRelation = (item, relation, targetResource) => {
+  const relationKey = getRelationKeys(relation, singularize(relation), targetResource, singularize(targetResource)).find((key) => Object.hasOwn(item, key));
+
+  if (relationKey == null) {
+    return undefined;
+  }
+
+  return { ids: toArray(item[relationKey]).filter((id) => id != null), isMany: relationKey.endsWith('Ids') || Array.isArray(item[relationKey]) };
+};
+
+const hasReference = (value, relationKeys, id) => {
+  if (Array.isArray(value)) {
+    return value.some((item) => hasReference(item, relationKeys, id));
+  }
+
+  if (!isObject(value)) {
+    return false;
+  }
+
+  return Object.entries(value).some(([key, nestedValue]) => {
+    if (!isSafeKey(key)) {
+      return false;
+    }
+
+    if (relationKeys.includes(key)) {
+      return toArray(nestedValue).some((nestedId) => isEqual(nestedId, id));
+    }
+
+    return hasReference(nestedValue, relationKeys, id);
+  });
+};
+
+const findRelatedValue = (database, item, sourceResource, relation, targetResource) => {
+  const targetItems = database.data[targetResource];
+  const localRelation = findLocalRelation(item, relation, targetResource);
+
+  if (!Array.isArray(targetItems)) {
+    return undefined;
+  }
+
+  if (localRelation != null) {
+    const relatedItems = localRelation.ids.map((id) => targetItems.find((targetItem) => isObject(targetItem) && isEqual(targetItem.id, id))).filter((targetItem) => targetItem != null);
+
+    return localRelation.isMany ? relatedItems : relatedItems[0] ?? null;
+  }
+
+  if (item.id == null) {
+    return undefined;
+  }
+
+  const reverseRelationKeys = getRelationKeys(singularize(sourceResource));
+
+  if (relation === 'child' || relation === 'children') {
+    reverseRelationKeys.push('parentId', 'parentIds');
+  }
+
+  return targetItems.filter((targetItem) => hasReference(targetItem, reverseRelationKeys, item.id));
+};
+
+const embedPath = (database, item, sourceResource, [relation, ...nestedRelations]) => {
+  if (relation == null || !isSafeKey(relation)) {
+    return item;
+  }
+
+  const currentValue = item[relation];
+  const nestedSourceResource = resolveResource(database, relation, sourceResource) ?? relation;
+
+  if (Array.isArray(currentValue)) {
+    return nestedRelations.length === 0 ? item : { ...item, [relation]: currentValue.map((value) => (isObject(value) ? embedPath(database, value, nestedSourceResource, nestedRelations) : value)) };
+  }
+
+  if (isObject(currentValue)) {
+    return nestedRelations.length === 0 ? item : { ...item, [relation]: embedPath(database, currentValue, nestedSourceResource, nestedRelations) };
+  }
+
+  const targetResource = resolveResource(database, relation, sourceResource);
+
+  if (targetResource == null) {
+    return item;
+  }
+
+  const relatedValue = findRelatedValue(database, item, sourceResource, relation, targetResource);
+
+  if (relatedValue == null || nestedRelations.length === 0) {
+    return relatedValue === undefined ? item : { ...item, [relation]: relatedValue };
+  }
+
+  return {
+    ...item,
+    [relation]: Array.isArray(relatedValue)
+      ? relatedValue.map((value) => embedPath(database, value, targetResource, nestedRelations))
+      : embedPath(database, relatedValue, targetResource, nestedRelations),
+  };
+};
+
+const parseEmbedPaths = (embed) => toArray(embed)
+  .flatMap((value) => (typeof value === 'string' ? value.split(',') : []))
+  .map((path) => path.split('.').filter(Boolean))
+  .filter((path) => path.length > 0 && path.every(isSafeKey));
+
+const embedItem = (database, item, resource, embedPaths) => embedPaths.reduce((embeddedItem, path) => embedPath(database, embeddedItem, resource, path), item);
+
+const sortItems = (items, sort) => {
+  const sortRules = typeof sort === 'string' ? sort.split(',').filter(Boolean) : [];
+
+  if (sortRules.length === 0) {
+    return [...items];
+  }
+
+  return [...items].sort((left, right) => {
+    for (const sortRule of sortRules) {
+      const isDescending = sortRule.startsWith('-');
+      const path = isDescending ? sortRule.slice(1) : sortRule;
+      const comparison = compareValues(getValueByPath(left, path), getValueByPath(right, path));
+
+      if (comparison !== 0) {
+        return isDescending ? -comparison : comparison;
+      }
+    }
+
+    return 0;
+  });
+};
+
+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));
+  const safePage = Math.max(1, Math.min(Number.isFinite(page) ? Math.floor(page) : 1, pages));
+  const offset = (safePage - 1) * safePageSize;
+
+  return {
+    data: items.slice(offset, offset + safePageSize),
+    first: 1,
+    items: items.length,
+    last: pages,
+    next: safePage < pages ? safePage + 1 : null,
+    pages,
+    prev: safePage > 1 ? safePage - 1 : null,
+  };
+};
+
+const getCollection = (database, resource) => {
+  const collection = isSafeKey(resource) ? database.data[resource] : undefined;
+
+  if (!Array.isArray(collection)) {
+    throw createHttpError(404, 'Ресурс не найден');
+  }
+
+  return collection;
+};
+
+const getRequestBody = (body) => {
+  if (!isObject(body)) {
+    throw createHttpError(400, 'Тело запроса должно быть JSON-объектом');
+  }
+
+  return body;
+};
+
+const findItem = (collection, id) => collection.find((item) => isObject(item) && String(item.id) === id);
+const resolveDatabasePath = (databasePath) => {
+  if (typeof databasePath !== 'string' || databasePath === '') {
+    throw new Error('Укажите путь к JSON-базе данных');
+  }
+
+  return resolve(databasePath);
+};
+
+export async function createServer({ databasePath, logger = true } = {}) {
+  const database = await JSONFilePreset(resolveDatabasePath(databasePath), {});
+  const server = Fastify({ logger });
+
+  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.options('/', async(_request, reply) => reply.code(204).send());
+  server.options('/*', async(_request, reply) => reply.code(204).send());
+
+  server.get('/', async() => ({ resources: getResourceNames(database) }));
+
+  server.get('/:resource', async(request) => {
+    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 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._per_page));
+  });
+
+  server.get('/:resource/:id', async(request) => {
+    const item = findItem(getCollection(database, request.params.resource), request.params.id);
+
+    if (item == null) {
+      throw createHttpError(404, 'Запись не найдена');
+    }
+
+    return embedItem(database, item, request.params.resource, parseEmbedPaths(request.query._embed));
+  });
+
+  server.post('/:resource', async(request, reply) => {
+    const collection = getCollection(database, request.params.resource);
+    const item = { ...getRequestBody(request.body), id: randomBytes(8).toString('base64url') };
+
+    collection.push(item);
+    await database.write();
+
+    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);
+
+    if (currentItem == null) {
+      throw createHttpError(404, 'Запись не найдена');
+    }
+
+    const item = { ...getRequestBody(request.body), id: request.params.id };
+    const itemIndex = collection.indexOf(currentItem);
+
+    collection.splice(itemIndex, 1, item);
+    await database.write();
+
+    return item;
+  });
+
+  server.patch('/:resource/:id', async(request) => {
+    const collection = getCollection(database, request.params.resource);
+    const currentItem = findItem(collection, request.params.id);
+
+    if (currentItem == null) {
+      throw createHttpError(404, 'Запись не найдена');
+    }
+
+    const item = { ...currentItem, ...getRequestBody(request.body), id: request.params.id };
+    const itemIndex = collection.indexOf(currentItem);
+
+    collection.splice(itemIndex, 1, item);
+    await database.write();
+
+    return item;
+  });
+
+  server.delete('/:resource/:id', async(request) => {
+    const collection = getCollection(database, request.params.resource);
+    const currentItem = findItem(collection, request.params.id);
+
+    if (currentItem == null) {
+      throw createHttpError(404, 'Запись не найдена');
+    }
+
+    collection.splice(collection.indexOf(currentItem), 1);
+    await database.write();
+
+    return currentItem;
+  });
+
+  server.setErrorHandler((error, request, reply) => {
+    const statusCode = Number.isInteger(error.statusCode) ? error.statusCode : 500;
+
+    if (statusCode === 500) {
+      request.log.error(error);
+    }
+
+    return reply.code(statusCode).send({ error: error.message });
+  });
+
+  return server;
+}
+
+export async function startServer({ databasePath, host = '127.0.0.1', logger = true, port = 4001 } = {}) {
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('Порт должен быть целым числом от 1 до 65535');
+  }
+
+  const resolvedDatabasePath = resolveDatabasePath(databasePath);
+  const server = await createServer({ databasePath: resolvedDatabasePath, logger });
+
+  await server.listen({ host, port });
+  server.log.info({ database: resolvedDatabasePath }, 'Deep JSON Server запущен');
+
+  return server;
+}
+
+const getCliOption = (argumentsList, ...names) => {
+  const optionIndex = argumentsList.findIndex((argument) => names.includes(argument));
+
+  return optionIndex === -1 ? undefined : argumentsList[optionIndex + 1];
+};
+
+const runCli = async() => {
+  const [databaseArgument, ...cliArguments] = process.argv.slice(2);
+
+  if (databaseArgument == null || databaseArgument.startsWith('-')) {
+    throw new Error('Укажите путь к базе данных: deep-json-server database.json');
+  }
+
+  await startServer({
+    databasePath: databaseArgument,
+    host: getCliOption(cliArguments, '--host', '-h') ?? process.env.HOST ?? '127.0.0.1',
+    port: Number(getCliOption(cliArguments, '--port', '-p') ?? process.env.PORT ?? 4001),
+  });
+};
+
+if (process.argv[1] != null && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await runCli();
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kollors/deep-json-server",
+  "version": "0.1.0",
+  "description": "JSON mock server with deep filters and recursive relationship embedding",
+  "type": "module",
+  "bin": {
+    "deep-json-server": "index.js"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "LICENSE",
+    "README.md",
+    "README.ru.md"
+  ],
+  "scripts": {
+    "check": "node --check index.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "fastify": "^5.12.1",
+    "lowdb": "^7.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kollors/deep-json-server.git"
+  },
+  "homepage": "https://github.com/kollors/deep-json-server#readme",
+  "bugs": {
+    "url": "https://github.com/kollors/deep-json-server/issues"
+  },
+  "keywords": [
+    "api",
+    "deep-filter",
+    "json",
+    "mock",
+    "relations",
+    "rest"
+  ],
+  "author": "kollors",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}