@kollors/deep-json-server 0.5.0 → 0.6.0

package/src/cli.js

@@ -1,28 +1,38 @@
 import process from 'node:process';
 import { readServerConfig } from './config.js';
 import { DEFAULT_HOST, DEFAULT_PORT } from './constants.js';
-import { generateOpenApi } from './openapi/index.js';
-import { startServer } from './server.js';
+import { createServer } from './server.js';
 
 const HELP_TEXT = `Deep JSON Server
 
 Использование:
-  deep-json-server [--openapi] [--files] <server.config.js>
+  deep-json-server [--files] [--openapi | --openapi-only] <server.config.js>
 
 Параметры:
-  --openapi  Сгенерировать OpenAPI и завершить работу
-  --files    Добавить файловые маршруты в сервер или OpenAPI
-  --help     Показать справку`;
+  --files         Добавить файловые маршруты в сервер и OpenAPI
+  --openapi       Сгенерировать OpenAPI и запустить сервер
+  --openapi-only  Сгенерировать OpenAPI и завершить работу
+  --help          Показать справку`;
 
 const parseArguments = (args) => {
-  const flags = { files: false, openapi: false };
+  const options = { files: false, openapiMode: 'none' };
   let configPath;
 
   args.forEach((argument) => {
     if (argument === '--files') {
-      flags.files = true;
+      options.files = true;
     } else if (argument === '--openapi') {
-      flags.openapi = true;
+      if (options.openapiMode !== 'none') {
+        throw new Error('Параметры --openapi и --openapi-only нельзя использовать одновременно');
+      }
+
+      options.openapiMode = 'generate';
+    } else if (argument === '--openapi-only') {
+      if (options.openapiMode !== 'none') {
+        throw new Error('Параметры --openapi и --openapi-only нельзя использовать одновременно');
+      }
+
+      options.openapiMode = 'only';
     } else if (argument.startsWith('-')) {
       throw new Error(`Неизвестный параметр: ${argument}`);
     } else if (configPath == null) {
@@ -36,55 +46,46 @@ const parseArguments = (args) => {
     throw new Error('Укажите путь к файлу конфигурации');
   }
 
-  return { configPath, ...flags };
+  return { configPath, ...options };
 };
 
-const validateModeConfig = (config, { files, openapi }) => {
-  if (openapi && config.openapiPath == null) {
-    throw new Error('Для --openapi укажите ключ config.openapi.path');
-  }
-
-  if (files && config.filesDirectoryPath == null) {
-    throw new Error('Для --files укажите ключ config.files.directory');
+const validateModeConfig = (config, { files, openapiMode }) => {
+  if (openapiMode !== 'none' && config.openapi.path == null) {
+    throw new Error(`Для --openapi${openapiMode === 'only' ? '-only' : ''} укажите ключ config.openapi.path`);
   }
 
-  if (files && config.filesMetadataPath == null) {
-    throw new Error('Для --files укажите ключ config.files.metadata');
+  if (files && config.files == null) {
+    throw new Error('Для --files укажите секцию config.files');
   }
 };
 
-export async function runCli(args = process.argv.slice(2), services = { generateOpenApi, startServer }) {
+export async function runCli(args = process.argv.slice(2), services = { createServer }) {
   if (args.includes('--help')) {
     process.stdout.write(`${HELP_TEXT}\n`);
     return;
   }
 
-  const { configPath, files, openapi } = parseArguments(args);
+  const { configPath, files, openapiMode } = parseArguments(args);
   const config = await readServerConfig(configPath);
-  const host = config.host ?? process.env.HOST ?? DEFAULT_HOST;
-  const port = config.port ?? Number(process.env.PORT ?? DEFAULT_PORT);
-
-  validateModeConfig(config, { files, openapi });
-
-  if (openapi) {
-    await services.generateOpenApi({
-      databasePath: config.databasePath,
-      files,
-      host,
-      outputPath: config.openapiPath,
-      port,
-      schemaPath: config.schemaPath,
-    });
-    process.stdout.write(`OpenAPI-схема сохранена в ${config.openapiPath}\n`);
+  const host = config.server.host ?? process.env.HOST ?? DEFAULT_HOST;
+  const port = config.server.port ?? Number(process.env.PORT ?? DEFAULT_PORT);
+
+  validateModeConfig(config, { files, openapiMode });
+
+  const runtimeConfig = { ...config, server: { ...config.server, host, port } };
+  const server = await services.createServer(runtimeConfig, { files });
+
+  if (openapiMode !== 'none') {
+    await server.openapi();
+    process.stdout.write(`OpenAPI-схема сохранена в ${config.openapi.path}\n`);
+  }
+
+  if (openapiMode === 'only') {
     return;
   }
 
-  await services.startServer({
-    databasePath: config.databasePath,
-    filesDirectoryPath: files ? config.filesDirectoryPath : undefined,
-    filesMetadataPath: files ? config.filesMetadataPath : undefined,
-    host,
-    port,
-    schemaPath: config.schemaPath,
-  });
+  const fastify = server.fastify();
+
+  await fastify.listen({ host, port });
+  fastify.log.info({ database: 'path' in config.database ? config.database.path : 'memory' }, 'Deep JSON Server запущен');
 }

package/src/config.js

@@ -3,12 +3,25 @@ import { pathToFileURL } from 'node:url';
 import { isObject } from './utils.js';
 
 const CONFIG_KEYS = new Set(['database', 'files', 'openapi', 'server']);
-const DATABASE_KEYS = new Set(['path', 'schema']);
-const FILES_KEYS = new Set(['directory', 'metadata']);
+const DATABASE_KEYS = new Set(['data', 'path', 'schema']);
+const FILES_KEYS = new Set(['data', 'directory', 'metadata']);
 const OPENAPI_KEYS = new Set(['path']);
-const SERVER_KEYS = new Set(['host', 'port']);
+const SERVER_KEYS = new Set(['host', 'logger', 'maxFileSize', 'maxPageSize', 'port']);
 let configImportIndex = 0;
 
+/** @typedef {Record<string, Array<Record<string, unknown>>>} DatabaseData */
+/** @typedef {Record<string, unknown>} DatabaseSchema */
+/** @typedef {{ data: DatabaseData, path?: never, schema?: DatabaseSchema | string } | { data?: never, path: string, schema?: DatabaseSchema | string }} DatabaseConfig */
+/** @typedef {{ content: Uint8Array, id: string, mimeType: string, name: string }} MemoryFile */
+/** @typedef {{ data: MemoryFile[], directory?: never, metadata?: never } | { data?: never, directory: string, metadata: string }} FilesConfig */
+/**
+ * @typedef {object} DeepJsonServerConfig
+ * @property {DatabaseConfig} database Database source and optional schema.
+ * @property {FilesConfig} [files] Binary-file storage.
+ * @property {{ path?: string }} [openapi] Generated OpenAPI file.
+ * @property {{ host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number }} [server] Runtime settings.
+ */
+
 const assertKnownKeys = (value, keys, path) => {
   const unknownKey = Object.keys(value).find((key) => !keys.has(key));
 
@@ -17,9 +30,9 @@ const assertKnownKeys = (value, keys, path) => {
   }
 };
 
-const getObject = (value, path) => {
-  if (value == null) {
-    return {};
+const getObject = (value, path, required = false) => {
+  if (value == null && !required) {
+    return undefined;
   }
 
   if (!isObject(value)) {
@@ -43,55 +56,139 @@ const getString = (value, path, required = false) => {
 
 const resolveConfigPath = (value, directoryPath) => (value == null ? undefined : resolve(directoryPath, value));
 
-export async function readServerConfig(configPath) {
-  const resolvedConfigPath = resolve(getString(configPath, 'config', true));
-  let config;
+const normalizeSchema = (schema, directoryPath) => {
+  if (schema == null) {
+    return undefined;
+  }
 
-  try {
-    const configUrl = pathToFileURL(resolvedConfigPath);
+  if (typeof schema === 'string') {
+    return resolveConfigPath(getString(schema, 'config.database.schema', true), directoryPath);
+  }
 
-    configUrl.searchParams.set('deep-json-server-import', String(configImportIndex++));
-    config = (await import(configUrl.href)).default;
-  } catch (error) {
-    throw new Error(`Не удалось загрузить конфигурацию ${resolvedConfigPath}: ${error.message}`, { cause: error });
+  return getObject(schema, 'config.database.schema', true);
+};
+
+const normalizeDatabase = (value, directoryPath) => {
+  const database = getObject(value, 'config.database', true);
+
+  assertKnownKeys(database, DATABASE_KEYS, 'config.database');
+
+  const hasData = database.data != null;
+  const hasPath = database.path != null;
+
+  if (hasData === hasPath) {
+    throw new Error('Укажите ровно один из ключей config.database.path и config.database.data');
+  }
+
+  const schema = normalizeSchema(database.schema, directoryPath);
+
+  if (hasData) {
+    return { data: getObject(database.data, 'config.database.data', true), schema };
+  }
+
+  return { path: resolveConfigPath(getString(database.path, 'config.database.path', true), directoryPath), schema };
+};
+
+const normalizeFiles = (value, directoryPath) => {
+  const files = getObject(value, 'config.files');
+
+  if (files == null) {
+    return undefined;
+  }
+
+  assertKnownKeys(files, FILES_KEYS, 'config.files');
+
+  const hasData = files.data != null;
+  const hasDiskStorage = files.directory != null || files.metadata != null;
+
+  if (hasData === hasDiskStorage) {
+    throw new Error('Укажите либо config.files.data, либо пару config.files.directory и config.files.metadata');
   }
 
+  if (hasData) {
+    if (!Array.isArray(files.data)) {
+      throw new Error('Ключ config.files.data должен содержать массив');
+    }
+
+    return { data: files.data };
+  }
+
+  return {
+    directory: resolveConfigPath(getString(files.directory, 'config.files.directory', true), directoryPath),
+    metadata: resolveConfigPath(getString(files.metadata, 'config.files.metadata', true), directoryPath),
+  };
+};
+
+/**
+ * @param {DeepJsonServerConfig} config Server configuration.
+ * @param {string} [directoryPath] Base directory for relative paths.
+ * @returns {{ database: DatabaseConfig, files?: FilesConfig, openapi: { path?: string }, server: { host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number } }} Normalized configuration.
+ */
+export const normalizeServerConfig = (config, directoryPath = '.') => {
   if (!isObject(config)) {
-    throw new Error('Конфигурация сервера должна экспортировать JSON-объект через export default');
+    throw new Error('Конфигурация сервера должна содержать JSON-объект');
   }
 
   assertKnownKeys(config, CONFIG_KEYS, 'config');
 
-  const database = getObject(config.database, 'config.database');
-  const files = getObject(config.files, 'config.files');
-  const openapi = getObject(config.openapi, 'config.openapi');
-  const server = getObject(config.server, 'config.server');
+  const database = normalizeDatabase(config.database, directoryPath);
+  const files = normalizeFiles(config.files, directoryPath);
+  const openapi = getObject(config.openapi, 'config.openapi') ?? {};
+  const server = getObject(config.server, 'config.server') ?? {};
 
-  assertKnownKeys(database, DATABASE_KEYS, 'config.database');
-  assertKnownKeys(files, FILES_KEYS, 'config.files');
   assertKnownKeys(openapi, OPENAPI_KEYS, 'config.openapi');
   assertKnownKeys(server, SERVER_KEYS, 'config.server');
 
-  const directoryPath = dirname(resolvedConfigPath);
-  const databasePath = getString(database.path, 'config.database.path', true);
-  const schemaPath = getString(database.schema, 'config.database.schema');
   const openapiPath = getString(openapi.path, 'config.openapi.path');
-  const filesDirectory = getString(files.directory, 'config.files.directory');
-  const filesMetadata = getString(files.metadata, 'config.files.metadata');
   const host = getString(server.host, 'config.server.host');
 
   if (server.port != null && (!Number.isInteger(server.port) || server.port < 0 || server.port > 65_535)) {
     throw new Error('Ключ config.server.port должен быть целым числом от 0 до 65535');
   }
 
+  if (server.maxPageSize != null && (!Number.isInteger(server.maxPageSize) || server.maxPageSize < 1)) {
+    throw new Error('Ключ config.server.maxPageSize должен быть положительным целым числом');
+  }
+
+  if (server.maxFileSize != null && (!Number.isInteger(server.maxFileSize) || server.maxFileSize < 1)) {
+    throw new Error('Ключ config.server.maxFileSize должен быть положительным целым числом');
+  }
+
+  if (server.logger != null && typeof server.logger !== 'boolean' && !isObject(server.logger)) {
+    throw new Error('Ключ config.server.logger должен содержать boolean или JSON-объект');
+  }
+
   return {
-    configPath: resolvedConfigPath,
-    databasePath: resolveConfigPath(databasePath, directoryPath),
-    filesDirectoryPath: resolveConfigPath(filesDirectory, directoryPath),
-    filesMetadataPath: resolveConfigPath(filesMetadata, directoryPath),
-    host,
-    openapiPath: resolveConfigPath(openapiPath, directoryPath),
-    port: server.port,
-    schemaPath: resolveConfigPath(schemaPath, directoryPath),
+    database,
+    files,
+    openapi: { path: resolveConfigPath(openapiPath, directoryPath) },
+    server: {
+      host,
+      logger: server.logger,
+      maxFileSize: server.maxFileSize,
+      maxPageSize: server.maxPageSize,
+      port: server.port,
+    },
   };
+};
+
+/** @param {string} configPath Configuration module path. */
+export async function readServerConfig(configPath) {
+  const resolvedConfigPath = resolve(getString(configPath, 'config', true));
+  let config;
+
+  try {
+    const configUrl = pathToFileURL(resolvedConfigPath);
+
+    configUrl.searchParams.set('deep-json-server-import', String(configImportIndex++));
+    config = (await import(configUrl.href)).default;
+  } catch (error) {
+    throw new Error(`Не удалось загрузить конфигурацию ${resolvedConfigPath}: ${error.message}`, { cause: error });
+  }
+
+  if (!isObject(config)) {
+    throw new Error('Конфигурация сервера должна экспортировать JSON-объект через export default');
+  }
+
+  return normalizeServerConfig(config, dirname(resolvedConfigPath));
 }

package/src/database.js

@@ -72,8 +72,7 @@ export const readJsonObject = async (path, label) => {
 
 export const readDatabaseFile = async (databasePath) => validateDatabase(await readJsonObject(databasePath, 'Файл базы данных'));
 
-/** @returns {Promise<any>} Internal LowDB-backed store. */
-export const createDatabaseStore = async (databasePath) => {
+const createDiskDatabaseStore = async (databasePath) => {
   const resolvedDatabasePath = resolveDatabasePath(databasePath);
   const initialData = await readDatabaseFile(resolvedDatabasePath);
   const database = await JSONFilePreset(resolvedDatabasePath, initialData);
@@ -105,6 +104,36 @@ export const createDatabaseStore = async (databasePath) => {
   return { database, path: resolvedDatabasePath, read, update };
 };
 
+const createMemoryDatabaseStore = (sourceData) => {
+  const database = { data: validateDatabase(structuredClone(sourceData)) };
+  let updateQueue = Promise.resolve();
+
+  const read = async () => database.data;
+  const update = (operation) => {
+    const pendingOperation = updateQueue.then(() => {
+      const draft = { data: structuredClone(database.data) };
+      const result = operation(draft);
+
+      validateDatabase(draft.data);
+      database.data = draft.data;
+
+      return result;
+    });
+
+    updateQueue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+
+  return { database, read, update };
+};
+
+/**
+ * @param {import('./config.js').DatabaseConfig} config Database source.
+ * @returns {Promise<any>} Internal database store.
+ */
+export const createDatabaseStore = async (config) => ('data' in config ? createMemoryDatabaseStore(config.data) : createDiskDatabaseStore(config.path));
+
 export const getCollection = (database, resource) => {
   const collection = isSafeKey(resource) ? database.data[resource] : undefined;
 

package/src/files.js

@@ -2,7 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { createReadStream, createWriteStream } from 'node:fs';
 import { access, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
-import { Transform } from 'node:stream';
+import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createHttpError, isObject } from './utils.js';
 
@@ -123,7 +123,7 @@ const createSizeLimiter = (maxFileSize, onSize) => {
   });
 };
 
-const createFileStore = async ({ directoryPath: sourceDirectoryPath, metadataPath: sourceMetadataPath }) => {
+const createDiskFileStore = async ({ directory: sourceDirectoryPath, metadata: sourceMetadataPath }) => {
   if (typeof sourceDirectoryPath !== 'string' || sourceDirectoryPath.trim() === '') {
     throw new Error('Путь к директории файлов не должен быть пустым');
   }
@@ -168,7 +168,7 @@ const createFileStore = async ({ directoryPath: sourceDirectoryPath, metadataPat
         throw error;
       }
 
-      return { file, path };
+      return { file, stream: createReadStream(path) };
     });
 
   const upload = ({ maxFileSize, mimeType, name, stream }) =>
@@ -237,11 +237,101 @@ const createFileStore = async ({ directoryPath: sourceDirectoryPath, metadataPat
   return { get, remove, upload };
 };
 
-const getDownloadName = (name) => encodeURIComponent(basename(name)).replaceAll("'", '%27');
+const createMemoryFileStore = (sourceFiles) => {
+  const ids = new Set();
+  const storedFiles = sourceFiles.map((sourceFile, index) => {
+    if (
+      !isObject(sourceFile) ||
+      typeof sourceFile.id !== 'string' ||
+      sourceFile.id === '' ||
+      typeof sourceFile.mimeType !== 'string' ||
+      sourceFile.mimeType === '' ||
+      typeof sourceFile.name !== 'string' ||
+      sourceFile.name === '' ||
+      !(sourceFile.content instanceof Uint8Array)
+    ) {
+      throw new Error(`Некорректная запись ${index} в config.files.data`);
+    }
+
+    if (ids.has(sourceFile.id)) {
+      throw new Error(`config.files.data содержит повторяющийся id «${sourceFile.id}»`);
+    }
+
+    ids.add(sourceFile.id);
+
+    const content = Buffer.from(sourceFile.content);
+
+    return {
+      content,
+      file: { id: sourceFile.id, mimeType: sourceFile.mimeType, name: sourceFile.name, size: content.length, url: `/_files/${sourceFile.id}` },
+    };
+  });
+  let operationQueue = Promise.resolve();
+
+  const schedule = (operation) => {
+    const pendingOperation = operationQueue.then(operation);
 
-export const registerFileRoutes = async (server, { directoryPath, maxFileSize, metadataPath }) => {
-  const store = await createFileStore({ directoryPath, metadataPath });
+    operationQueue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+
+  const get = (id) =>
+    schedule(async () => {
+      const storedFile = storedFiles.find(({ file }) => file.id === id);
+
+      if (storedFile == null) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      return { file: storedFile.file, stream: Readable.from([storedFile.content]) };
+    });
+
+  const upload = ({ maxFileSize, mimeType, name, stream }) =>
+    schedule(async () => {
+      const chunks = [];
+      let size = 0;
+
+      for await (const chunk of stream) {
+        const buffer = Buffer.from(chunk);
+
+        size += buffer.length;
+
+        if (size > maxFileSize) {
+          throw createHttpError(413, `Размер файла не должен превышать ${maxFileSize} байт`);
+        }
+
+        chunks.push(buffer);
+      }
+
+      const id = createFileId(storedFiles.map(({ file }) => file));
+      const file = { id, mimeType, name, size, url: `/_files/${id}` };
+
+      storedFiles.push({ content: Buffer.concat(chunks), file });
+
+      return file;
+    });
+
+  const remove = (id) =>
+    schedule(async () => {
+      const index = storedFiles.findIndex(({ file }) => file.id === id);
+
+      if (index === -1) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      return storedFiles.splice(index, 1)[0].file;
+    });
+
+  return { get, remove, upload };
+};
+
+/** @param {import('./config.js').FilesConfig} config File storage configuration. */
+export const createFileStore = async (config) => ('data' in config ? createMemoryFileStore(config.data) : createDiskFileStore(config));
+
+const getDownloadName = (name) => encodeURIComponent(basename(name)).replaceAll("'", '%27');
 
+export const registerFileRoutes = (server, { maxFileSize, store }) => {
   server.register((fileServer, _options, done) => {
     fileServer.removeAllContentTypeParsers();
     fileServer.addContentTypeParser('*', (_request, payload, parserDone) => parserDone(null, payload));
@@ -264,12 +354,12 @@ export const registerFileRoutes = async (server, { directoryPath, maxFileSize, m
     });
 
     fileServer.get('/_files/:id', async (request, reply) => {
-      const { file, path } = await store.get(request.params.id);
+      const { file, stream } = await store.get(request.params.id);
 
       reply.header('Content-Disposition', `inline; filename*=UTF-8''${getDownloadName(file.name)}`);
       reply.type(file.mimeType);
 
-      return reply.send(createReadStream(path));
+      return reply.send(stream);
     });
 
     fileServer.delete('/_files/:id', async (request) => store.remove(request.params.id));

package/src/openapi/config.js

@@ -107,4 +107,18 @@ export const applyConfiguredFields = (schema, resource, resourceConfig) => {
   return applyRequiredFields(schemaWithFormats, '', new Set(requiredFields));
 };
 
-export const readSchemaConfig = async (schemaPath) => (schemaPath == null ? {} : readJsonObject(schemaPath, 'Файл схемы базы данных'));
+export const resolveSchemaConfig = async (schema) => {
+  if (schema == null) {
+    return {};
+  }
+
+  if (typeof schema === 'string') {
+    return readJsonObject(schema, 'Файл схемы базы данных');
+  }
+
+  if (!isObject(schema)) {
+    throw new Error('Схема базы данных должна содержать JSON-объект');
+  }
+
+  return structuredClone(schema);
+};

package/src/openapi/document.js

@@ -1,26 +1,10 @@
-import { DEFAULT_HOST, DEFAULT_PAGE_SIZE, DEFAULT_PORT, MAX_PAGE_SIZE } from '../constants.js';
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../constants.js';
 import { validateDatabase } from '../database.js';
 import { getRelationMetadata } from '../relation-metadata.js';
 import { getResourceNames, isObject, singularize, toPascalCase } from '../utils.js';
 import { applyConfiguredFields, validateSchemaConfig } from './config.js';
 import { ensureGeneratedIdSchema, inferObjectSchema, mergeSchemaOverrides, omitId } from './inference.js';
 
-const getServerUrl = (host, port) => {
-  const serverPort = Number(port);
-
-  if (typeof host !== 'string' || host === '') {
-    throw new Error('Адрес сервера не должен быть пустым');
-  }
-
-  if (!Number.isInteger(serverPort) || serverPort < 1 || serverPort > 65_535) {
-    throw new Error('Порт должен быть целым числом от 1 до 65535');
-  }
-
-  const serverHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
-
-  return `http://${serverHost}:${serverPort}`;
-};
-
 const createSchemaReference = (name) => ({ $ref: `#/components/schemas/${name}` });
 
 const addForwardRelations = (schema, resources, componentNames, sourceResource) => {
@@ -100,12 +84,12 @@ const addReverseRelations = (schemas, rawSchemas, resources, componentNames) =>
   });
 };
 
-const createParameters = () => ({
+const createParameters = (maxPageSize) => ({
   ContentName: { description: 'URI-encoded relative file name', in: 'header', name: 'Content-Name', required: true, schema: { type: 'string' } },
   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: false, schema: { default: 1, minimum: 1, type: 'integer' } },
-  PerPage: { in: 'query', name: '_perPage', required: false, schema: { default: DEFAULT_PAGE_SIZE, maximum: MAX_PAGE_SIZE, minimum: 1, type: 'integer' } },
+  PerPage: { in: 'query', name: '_perPage', required: false, schema: { default: DEFAULT_PAGE_SIZE, maximum: maxPageSize, 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' } },
 });
@@ -250,15 +234,23 @@ const validateGeneratedNames = (resources, componentNames, files) => {
 };
 
 /**
- * Creates an OpenAPI 3.0 document from a database and optional schema configuration.
- * @param {Record<string, Array<Record<string, unknown>>>} database Database contents.
- * @param {Record<string, unknown>} [schemaConfig] Schema configuration.
- * @param {{ files?: boolean, host?: string, port?: number }} [serverOptions] Server address and optional features used in the generated document.
+ * Builds an OpenAPI 3.0 document from resolved server data.
+ * @param {{ database: Record<string, Array<Record<string, unknown>>>, files?: boolean, maxPageSize?: number, schema?: Record<string, unknown> }} options Document options.
  * @returns {Record<string, unknown>} OpenAPI document.
  */
-export function createOpenApiDocument(database, schemaConfig = {}, { files = false, host = DEFAULT_HOST, port = DEFAULT_PORT } = {}) {
+export function buildOpenapiDocument(options) {
+  const { database, files = false, maxPageSize = MAX_PAGE_SIZE, schema: schemaConfig = {} } = options ?? {};
+
+  if (typeof files !== 'boolean') {
+    throw new Error('Ключ files должен содержать boolean');
+  }
+
   validateDatabase(database);
 
+  if (!Number.isInteger(maxPageSize) || maxPageSize < 1) {
+    throw new Error('Максимальный размер страницы должен быть положительным целым числом');
+  }
+
   if (!isObject(schemaConfig)) {
     throw new Error('Схема базы данных должна содержать JSON-объект');
   }
@@ -306,14 +298,9 @@ export function createOpenApiDocument(database, schemaConfig = {}, { files = fal
     schemas[`${componentName}Page`] = {
       properties: {
         data: { items: createSchemaReference(componentName), type: 'array' },
-        first: { type: 'integer' },
-        items: { type: 'integer' },
-        last: { type: 'integer' },
-        next: { nullable: true, type: 'integer' },
-        pages: { type: 'integer' },
-        prev: { nullable: true, type: 'integer' },
+        total: { minimum: 0, type: 'integer' },
       },
-      required: ['data', 'first', 'items', 'last', 'next', 'pages', 'prev'],
+      required: ['data', 'total'],
       type: 'object',
     };
   });
@@ -321,11 +308,10 @@ export function createOpenApiDocument(database, schemaConfig = {}, { files = fal
   addReverseRelations(schemas, rawSchemas, resources, componentNames);
 
   return {
-    components: { parameters: createParameters(), schemas },
+    components: { parameters: createParameters(maxPageSize), schemas },
     info: isObject(schemaConfig.$info) ? schemaConfig.$info : { title: 'Deep JSON Server API', version: '1.0.0' },
     openapi: '3.0.3',
     paths: Object.assign({}, ...resources.map((resource) => createResourcePaths(resource, componentNames[resource])), files ? createFilePaths() : {}),
-    servers: [{ url: getServerUrl(host, port) }],
     tags: [...resources.map((resource) => ({ name: resource })), ...(files ? [{ name: 'files' }] : [])],
   };
 }