@kollors/deep-json-server 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kollors/deep-json-server",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "JSON mock server with deep filters and recursive relationship embedding",
   "type": "module",
   "types": "./types/index.d.ts",
@@ -52,11 +52,18 @@
   },
   "keywords": [
     "api",
+    "crud",
     "deep-filter",
+    "file-upload",
     "json",
+    "json-server",
     "mock",
+    "mock-api",
+    "mock-server",
+    "openapi",
     "relations",
-    "rest"
+    "rest",
+    "rest-api"
   ],
   "author": "kollors",
   "license": "MIT",

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 serverFacade = await services.createServer(runtimeConfig, { files });
+
+  if (openapiMode !== 'none') {
+    await serverFacade.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 = serverFacade.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,28 @@ 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, directory?: string, mimeType: string, name: string }} MemoryFile */
+/** @typedef {{ data: MemoryFile[], directory?: never, metadata?: never } | { data?: never, directory: string, metadata: string }} FilesConfig */
+/** @typedef {{ path?: string }} OpenapiConfig */
+/** @typedef {{ host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number }} ServerConfig */
+/**
+ * @typedef {object} DeepJsonServerConfig
+ * @property {DatabaseConfig} database Database source and optional schema.
+ * @property {FilesConfig} [files] Binary-file storage.
+ * @property {OpenapiConfig} [openapi] Generated OpenAPI file.
+ * @property {ServerConfig} [server] Runtime settings.
+ */
+/** @typedef {{ database: DatabaseConfig, files?: FilesConfig, openapi: OpenapiConfig, server: ServerConfig }} NormalizedServerConfig */
+
 const assertKnownKeys = (value, keys, path) => {
   const unknownKey = Object.keys(value).find((key) => !keys.has(key));
 
@@ -17,9 +33,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 +59,145 @@ 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),
+  };
+};
+
+/**
+ * Validates configuration and resolves relative paths.
+ * @param {DeepJsonServerConfig} config Server configuration.
+ * @param {string} [directoryPath] Base directory for relative paths.
+ * @returns {NormalizedServerConfig} 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,
+    },
   };
+};
+
+/**
+ * Loads an ES module config and resolves paths from its directory.
+ * @param {string} configPath Configuration module path.
+ * @returns {Promise<NormalizedServerConfig>} Normalized configuration.
+ */
+export async function readServerConfig(configPath) {
+  const resolvedConfigPath = resolve(getString(configPath, 'config', true));
+  let config;
+
+  try {
+    const configUrl = pathToFileURL(resolvedConfigPath);
+
+    // Bypass the module cache so repeated reads use the latest config.
+    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/constants.js

@@ -1,5 +1,5 @@
 export const DEFAULT_HOST = '127.0.0.1';
 export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
+export const DEFAULT_MAX_PAGE_SIZE = 1000;
 export const DEFAULT_PAGE_SIZE = 10;
 export const DEFAULT_PORT = 4001;
-export const MAX_PAGE_SIZE = 1000;

package/src/database.js

@@ -1,8 +1,16 @@
-import { randomBytes } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { JSONFilePreset } from 'lowdb/node';
-import { createHttpError, isObject, isSafeKey, resolveDatabasePath } from './utils.js';
+import { createHttpError, createSerialQueue, createUniqueId, isObject, isSafeKey, resolveDatabasePath } from './utils.js';
+
+/** @typedef {{ data: import('./config.js').DatabaseData }} DatabaseContainer */
+/**
+ * @typedef {object} DatabaseStore
+ * @property {DatabaseContainer} database Current database container.
+ * @property {string} [path] Resolved database file path.
+ * @property {() => Promise<import('./config.js').DatabaseData>} read Returns current data and reloads disk-backed sources.
+ * @property {<T>(operation: (database: DatabaseContainer) => T) => Promise<T>} update Runs a serialized update.
+ */
 
 const RESOURCE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
 
@@ -72,12 +80,11 @@ 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);
-  let writeQueue = Promise.resolve();
+  const schedule = createSerialQueue();
 
   const read = async () => {
     database.data = await readDatabaseFile(resolvedDatabasePath);
@@ -85,8 +92,8 @@ export const createDatabaseStore = async (databasePath) => {
     return database.data;
   };
 
-  const update = (operation) => {
-    const pendingOperation = writeQueue.then(async () => {
+  const update = (operation) =>
+    schedule(async () => {
       await read();
 
       const result = operation(database);
@@ -97,14 +104,35 @@ export const createDatabaseStore = async (databasePath) => {
       return result;
     });
 
-    writeQueue = pendingOperation.catch(() => undefined);
+  return { database, path: resolvedDatabasePath, read, update };
+};
 
-    return pendingOperation;
-  };
+const createMemoryDatabaseStore = (sourceData) => {
+  const database = { data: validateDatabase(structuredClone(sourceData)) };
+  const schedule = createSerialQueue();
 
-  return { database, path: resolvedDatabasePath, read, update };
+  const read = async () => database.data;
+  const update = (operation) =>
+    schedule(() => {
+      const draft = { data: structuredClone(database.data) };
+      const result = operation(draft);
+
+      validateDatabase(draft.data);
+      database.data = draft.data;
+
+      return result;
+    });
+
+  return { database, read, update };
 };
 
+/**
+ * Creates a disk- or memory-backed database with serialized updates.
+ * @param {import('./config.js').DatabaseConfig} config Database source.
+ * @returns {Promise<DatabaseStore>} 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;
 
@@ -117,12 +145,4 @@ export const getCollection = (database, resource) => {
 
 export const findItem = (collection, id) => collection.find((item) => String(item.id) === String(id));
 
-export const createId = (collection) => {
-  let id;
-
-  do {
-    id = randomBytes(8).toString('base64url');
-  } while (findItem(collection, id) != null);
-
-  return id;
-};
+export const createId = (collection) => createUniqueId((id) => findItem(collection, id) != null);