@kollors/deep-json-server 0.2.5 → 0.3.0

package/README.md

@@ -109,7 +109,7 @@ DELETE /movies/:id
 ## Pagination and sorting
 
 ```http
-GET /movies?_page=1&_per_page=10&_sort=-id,title
+GET /movies?_page=1&_perPage=10&_sort=-id,title
 ```
 
 Without `_page`, a GET collection returns an array. With `_page`, it returns:
@@ -201,16 +201,23 @@ Create a small configuration file next to the database, for example `mock/databa
 
 ```json
 {
-  "movies": {
-    "optional": ["description"],
-    "formats": {
-      "coverSrc": "uri"
-    }
+  "$info": {
+    "title": "Movie Catalog API",
+    "version": "1.0.0"
   },
-  "users": {
-    "formats": {
-      "avatarSrc": "uri",
-      "bornAt": "date"
+  "$schema": {
+    "movies": {
+      "required": ["actors", "actors.genreIds", "actors.userId", "publisherIds", "title"],
+      "formats": {
+        "coverSrc": "uri"
+      }
+    },
+    "users": {
+      "required": ["bornAt", "fullName"],
+      "formats": {
+        "avatarSrc": "uri",
+        "bornAt": "date"
+      }
     }
   }
 }
@@ -219,17 +226,21 @@ Create a small configuration file next to the database, for example `mock/databa
 Generate an OpenAPI 3.0.3 file and exit:
 
 ```bash
-deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml
+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. Fields present in every record are required unless listed in `optional`; `formats` adds OpenAPI formats such as `date` and `uri`. Nested fields use dot paths, for example `actors.id`.
+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`.
 
-Use `modelName` when a resource needs an explicit schema name instead of the automatically singularized name:
+`$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`.
+
+Use `name` when a resource needs an explicit schema name instead of the automatically singularized name:
 
 ```json
 {
-  "equipment": {
-    "modelName": "Equipment"
+  "$schema": {
+    "equipment": {
+      "name": "Equipment"
+    }
   }
 }
 ```
@@ -249,7 +260,7 @@ await server.close();
 
 await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
 
-await generateOpenApi({ databasePath: 'mock/database.json', schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
+await generateOpenApi({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001, schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
 ```
 
 `createServer()` is useful for tests because it returns a Fastify instance without opening a network port.

package/README.ru.md

@@ -109,7 +109,7 @@ DELETE /movies/:id
 ## Пагинация и сортировка
 
 ```http
-GET /movies?_page=1&_per_page=10&_sort=-id,title
+GET /movies?_page=1&_perPage=10&_sort=-id,title
 ```
 
 Без `_page` GET-запрос к коллекции возвращает массив. С `_page` возвращается объект:
@@ -201,16 +201,23 @@ GET /countries/1?_embed=users
 
 ```json
 {
-  "movies": {
-    "optional": ["description"],
-    "formats": {
-      "coverSrc": "uri"
-    }
+  "$info": {
+    "title": "API каталога фильмов",
+    "version": "1.0.0"
   },
-  "users": {
-    "formats": {
-      "avatarSrc": "uri",
-      "bornAt": "date"
+  "$schema": {
+    "movies": {
+      "required": ["actors", "actors.genreIds", "actors.userId", "publisherIds", "title"],
+      "formats": {
+        "coverSrc": "uri"
+      }
+    },
+    "users": {
+      "required": ["bornAt", "fullName"],
+      "formats": {
+        "avatarSrc": "uri",
+        "bornAt": "date"
+      }
     }
   }
 }
@@ -219,17 +226,21 @@ GET /countries/1?_embed=users
 Сгенерируйте OpenAPI 3.0.3 и завершите работу:
 
 ```bash
-deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml
+deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml --host 127.0.0.1 --port 4001
 ```
 
-Генератор определяет ресурсы и типы полей по всем записям базы. Поля, присутствующие в каждой записи, считаются обязательными, если они не перечислены в `optional`; `formats` добавляет форматы OpenAPI, например `date` и `uri`. Для вложенных полей используются пути через точку, например `actors.id`.
+Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а первичный ключ `id` корневой записи ресурса всегда обязательный. Остальные обязательные поля перечисляются в `required`; для вложенных полей используются пути через точку, например `actors.userId`. Объект `formats` добавляет форматы OpenAPI, например `date` и `uri`.
 
-Используйте `modelName`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
+`$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. Поле `servers` в OpenAPI формируется автоматически из параметров `--host` и `--port`, соответствующих переменных окружения `HOST` и `PORT` или адреса по умолчанию `http://127.0.0.1:4001`.
+
+Используйте `name`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
 
 ```json
 {
-  "equipment": {
-    "modelName": "Equipment"
+  "$schema": {
+    "equipment": {
+      "name": "Equipment"
+    }
   }
 }
 ```
@@ -249,7 +260,7 @@ await server.close();
 
 await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
 
-await generateOpenApi({ databasePath: 'mock/database.json', schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
+await generateOpenApi({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001, schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
 ```
 
 `createServer()` удобен для тестов: он возвращает экземпляр Fastify, не открывая сетевой порт.

package/package.json

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

package/src/cli.js

@@ -6,7 +6,7 @@ const HELP = `Deep JSON Server
 
 Использование:
   deep-json-server <database.json> [--host <host>] [--port <port>]
-  deep-json-server <database.json> --generate <database-schema.json> <openapi-schema.yaml>
+  deep-json-server <database.json> --generate <database-schema.json> <openapi-schema.yaml> [--host <host>] [--port <port>]
 
 Параметры:
   --generate  Сгенерировать OpenAPI и завершить работу
@@ -53,11 +53,15 @@ export async function runCli(args = process.argv.slice(2)) {
     const schemaPath = args[generateIndex + 1];
     const outputPath = args[generateIndex + 2];
 
-    if (generateIndex !== 1 || schemaPath == null || outputPath == null || args.length !== 4) {
-      throw new Error('Используйте: deep-json-server <database.json> --generate <database-schema.json> <openapi-schema.yaml>');
+    if (generateIndex !== 1 || schemaPath == null || outputPath == null) {
+      throw new Error('Используйте: deep-json-server <database.json> --generate <database-schema.json> <openapi-schema.yaml> [--host <host>] [--port <port>]');
     }
 
-    await generateOpenApi({ databasePath, outputPath, schemaPath });
+    const options = parseServerOptions([databasePath, ...args.slice(4)]);
+    const host = options.host ?? process.env.HOST ?? '127.0.0.1';
+    const port = Number(options.port ?? process.env.PORT ?? 4001);
+
+    await generateOpenApi({ databasePath, host, outputPath, port, schemaPath });
     process.stdout.write(`OpenAPI-схема сохранена в ${outputPath}\n`);
     return;
   }

package/src/openapi.js

@@ -13,6 +13,22 @@ const readJson = async(path, label) => {
   return value;
 };
 
+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 mergeSchemas = (schemas) => {
   const uniqueSchemas = [...new Map(schemas.map((schema) => [JSON.stringify(schema), schema])).values()];
   const nullable = uniqueSchemas.some((schema) => schema.type === 'null');
@@ -69,7 +85,7 @@ function inferObjectSchema(values, path, options) {
   const required = keys.filter((key) => {
     const fieldPath = path === '' ? key : `${path}.${key}`;
 
-    return !options.optional.has(fieldPath) && values.every((value) => Object.hasOwn(value, key));
+    return path === '' && key === 'id' || options.required.has(fieldPath);
   });
 
   return { properties, type: 'object', ...(required.length > 0 && { required }) };
@@ -134,7 +150,7 @@ 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: '_per_page', required: true, schema: { minimum: 1, type: 'integer' } },
+  PerPage: { in: 'query', name: '_perPage', required: true, schema: { 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' } },
 });
@@ -194,15 +210,16 @@ const createResourcePaths = (resource, componentName) => {
   };
 };
 
-export function createOpenApiDocument(database, schemaConfig = {}) {
+export function createOpenApiDocument(database, schemaConfig = {}, { host = '127.0.0.1', port = 4001 } = {}) {
   if (!isObject(database) || !isObject(schemaConfig)) {
     throw new Error('База данных и её схема должны содержать JSON-объекты');
   }
 
   const resources = getResourceNames(database);
+  const resourceConfigs = isObject(schemaConfig.$schema) ? schemaConfig.$schema : {};
   const componentNames = Object.fromEntries(resources.map((resource) => {
-    const resourceConfig = isObject(schemaConfig[resource]) ? schemaConfig[resource] : {};
-    const componentName = typeof resourceConfig.modelName === 'string' && resourceConfig.modelName !== '' ? resourceConfig.modelName : toPascalCase(singularize(resource));
+    const resourceConfig = isObject(resourceConfigs[resource]) ? resourceConfigs[resource] : {};
+    const componentName = typeof resourceConfig.name === 'string' && resourceConfig.name !== '' ? resourceConfig.name : toPascalCase(singularize(resource));
 
     return [resource, componentName];
   }));
@@ -212,10 +229,10 @@ export function createOpenApiDocument(database, schemaConfig = {}) {
 
   resources.forEach((resource) => {
     const componentName = componentNames[resource];
-    const resourceConfig = isObject(schemaConfig[resource]) ? schemaConfig[resource] : {};
+    const resourceConfig = isObject(resourceConfigs[resource]) ? resourceConfigs[resource] : {};
     const options = {
       formats: isObject(resourceConfig.formats) ? resourceConfig.formats : {},
-      optional: new Set(Array.isArray(resourceConfig.optional) ? resourceConfig.optional : []),
+      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);
@@ -244,15 +261,15 @@ export function createOpenApiDocument(database, schemaConfig = {}) {
     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]))),
-    servers: Array.isArray(schemaConfig.$servers) ? schemaConfig.$servers : [{ url: 'http://127.0.0.1:4001' }],
+    servers: [{ url: getServerUrl(host, port) }],
     tags: resources.map((resource) => ({ name: resource })),
   };
 }
 
-export async function generateOpenApi({ databasePath, outputPath, schemaPath }) {
+export async function generateOpenApi({ databasePath, host, outputPath, port, schemaPath }) {
   const database = await readJson(databasePath, 'База данных');
   const schemaConfig = await readJson(schemaPath, 'Схема базы данных');
-  const document = createOpenApiDocument(database, schemaConfig);
+  const document = createOpenApiDocument(database, schemaConfig, { host, port });
   const resolvedOutputPath = resolve(outputPath);
 
   await mkdir(dirname(resolvedOutputPath), { recursive: true });

package/src/query.js

@@ -1,7 +1,7 @@
 import { createHttpError, isEqual, isObject, isSafeKey, toArray } from './utils.js';
 
 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 RESERVED_QUERY_KEYS = new Set(['_embed', '_page', '_perPage', '_sort', '_where']);
 
 const compareValues = (left, right) => {
   if (Object.is(left, right)) {

package/src/server.js

@@ -56,7 +56,7 @@ export async function createServer({ databasePath, logger = true } = {}) {
     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));
+    return page == null ? sortedItems : paginateItems(sortedItems, page, Number(request.query._perPage));
   });
 
   server.get('/:resource/:id', async(request) => {