@kollors/deep-json-server 0.5.0 → 0.7.0

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_MAX_PAGE_SIZE, DEFAULT_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,15 @@ const addReverseRelations = (schemas, rawSchemas, resources, componentNames) =>
   });
 };
 
-const createParameters = () => ({
-  ContentName: { description: 'URI-encoded relative file name', in: 'header', name: 'Content-Name', required: true, schema: { type: 'string' } },
+const createParameters = (maxPageSize) => ({
+  ContentDirectory: { description: 'URI-encoded relative storage directory', in: 'header', name: 'Content-Directory', schema: { type: 'string' } },
+  ContentName: { description: 'URI-encoded file name', in: 'header', name: 'Content-Name', required: true, schema: { type: 'string' } },
+  ContentOverride: { description: 'Overwrite an existing file at the same path', in: 'header', name: 'Content-Override', schema: { default: false, type: 'boolean' } },
   Embed: { description: 'Relationship paths to embed', explode: true, in: 'query', name: '_embed', schema: { items: { type: 'string' }, type: 'array' }, style: 'form' },
+  FilePath: { allowReserved: true, description: 'URI-encoded file path relative to the storage directory', in: 'path', name: 'path', required: true, schema: { type: 'string' } },
   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' } },
 });
@@ -116,52 +103,110 @@ const createParameterReference = (name) => ({ $ref: `#/components/parameters/${n
 const createRequestBody = (name) => ({ required: true, ...createJsonContent(createSchemaReference(name)) });
 
 const createFilePaths = () => ({
-  '/_files': {
+  '/_files/download/{path}': {
+    get: {
+      operationId: 'downloadFile',
+      parameters: [createParameterReference('FilePath')],
+      responses: {
+        200: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, description: 'File download' },
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+  },
+  '/_files/metadata/{path}': {
+    get: {
+      operationId: 'getFileMetadata',
+      parameters: [createParameterReference('FilePath')],
+      responses: {
+        200: createResponse('File metadata', createSchemaReference('FileMetadata')),
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+  },
+  '/_files/storage': {
     post: {
       operationId: 'uploadFile',
-      parameters: [createParameterReference('ContentName')],
+      parameters: ['ContentName', 'ContentDirectory', 'ContentOverride'].map(createParameterReference),
       requestBody: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, required: true },
       responses: {
-        201: createResponse('Uploaded', createSchemaReference('UploadedFile')),
+        200: createResponse('Overwritten', createSchemaReference('FileMetadata')),
+        201: createResponse('Created', createSchemaReference('FileMetadata')),
         400: createResponse('Invalid request', createSchemaReference('Error')),
+        409: createResponse('Already exists', createSchemaReference('Error')),
         413: createResponse('File is too large', createSchemaReference('Error')),
         415: createResponse('Unsupported media type', createSchemaReference('Error')),
       },
       tags: ['files'],
     },
   },
-  '/_files/{id}': {
+  '/_files/storage/{path}': {
     delete: {
-      operationId: 'deleteFileById',
-      parameters: [createParameterReference('Id')],
-      responses: { 200: createResponse('Deleted', createSchemaReference('UploadedFile')), 404: createResponse('Not found', createSchemaReference('Error')) },
+      operationId: 'deleteFile',
+      parameters: [createParameterReference('FilePath')],
+      responses: {
+        204: { description: 'Deleted' },
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
       tags: ['files'],
     },
     get: {
-      operationId: 'getFileById',
-      parameters: [createParameterReference('Id')],
+      operationId: 'getFileContent',
+      parameters: [createParameterReference('FilePath')],
       responses: {
         200: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, description: 'File contents' },
+        400: createResponse('Invalid path', createSchemaReference('Error')),
         404: createResponse('Not found', createSchemaReference('Error')),
       },
       tags: ['files'],
     },
+    patch: {
+      operationId: 'updateFile',
+      parameters: [createParameterReference('FilePath')],
+      requestBody: createRequestBody('FileUpdate'),
+      responses: {
+        200: createResponse('Updated', createSchemaReference('FileMetadata')),
+        400: createResponse('Invalid request', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+        409: createResponse('Already exists', createSchemaReference('Error')),
+        413: createResponse('Request is too large', createSchemaReference('Error')),
+        415: createResponse('Unsupported media type', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
   },
 });
 
-const createResourcePaths = (resource, componentName) => {
+const createResourceOperationIds = (resource) => {
   const resourceName = toPascalCase(resource);
 
+  return {
+    create: `post${resourceName}`,
+    get: `get${resourceName}ById`,
+    list: `get${resourceName}`,
+    remove: `delete${resourceName}ById`,
+    replace: `put${resourceName}ById`,
+    update: `patch${resourceName}ById`,
+  };
+};
+
+const createResourcePaths = (resource, componentName) => {
+  const operationIds = createResourceOperationIds(resource);
+
   return {
     [`/${resource}`]: {
       get: {
-        operationId: `get${resourceName}`,
+        operationId: operationIds.list,
         parameters: ['Page', 'PerPage', 'Sort', 'Where', 'Embed'].map(createParameterReference),
         responses: { 200: createResponse('Successful response', createSchemaReference(`${componentName}Page`)), 400: createResponse('Invalid query', createSchemaReference('Error')) },
         tags: [resource],
       },
       post: {
-        operationId: `post${resourceName}`,
+        operationId: operationIds.create,
         requestBody: createRequestBody(`${componentName}Create`),
         responses: { 201: createResponse('Created', createSchemaReference(componentName)), 400: createResponse('Invalid request', createSchemaReference('Error')) },
         tags: [resource],
@@ -169,13 +214,13 @@ const createResourcePaths = (resource, componentName) => {
     },
     [`/${resource}/{id}`]: {
       delete: {
-        operationId: `delete${resourceName}ById`,
+        operationId: operationIds.remove,
         parameters: [createParameterReference('Id')],
         responses: { 200: createResponse('Deleted', createSchemaReference(componentName)), 404: createResponse('Not found', createSchemaReference('Error')) },
         tags: [resource],
       },
       get: {
-        operationId: `get${resourceName}ById`,
+        operationId: operationIds.get,
         parameters: [createParameterReference('Id'), createParameterReference('Embed')],
         responses: {
           200: createResponse('Successful response', createSchemaReference(componentName)),
@@ -185,7 +230,7 @@ const createResourcePaths = (resource, componentName) => {
         tags: [resource],
       },
       patch: {
-        operationId: `patch${resourceName}ById`,
+        operationId: operationIds.update,
         parameters: [createParameterReference('Id')],
         requestBody: createRequestBody(`${componentName}Update`),
         responses: {
@@ -196,7 +241,7 @@ const createResourcePaths = (resource, componentName) => {
         tags: [resource],
       },
       put: {
-        operationId: `put${resourceName}ById`,
+        operationId: operationIds.replace,
         parameters: [createParameterReference('Id')],
         requestBody: createRequestBody(`${componentName}Create`),
         responses: {
@@ -210,14 +255,16 @@ const createResourcePaths = (resource, componentName) => {
   };
 };
 
-const getOperationIds = (resource) => {
-  const resourceName = toPascalCase(resource);
-
-  return [`get${resourceName}`, `post${resourceName}`, `delete${resourceName}ById`, `get${resourceName}ById`, `patch${resourceName}ById`, `put${resourceName}ById`];
-};
-
 const validateGeneratedNames = (resources, componentNames, files) => {
-  const schemaOwners = new Map([['Error', 'встроенная схема ошибки'], ...(files ? [['UploadedFile', 'встроенная схема файла']] : [])]);
+  const schemaOwners = new Map([
+    ['Error', 'встроенная схема ошибки'],
+    ...(files
+      ? [
+          ['FileMetadata', 'встроенная схема метаданных файла'],
+          ['FileUpdate', 'встроенная схема изменения файла'],
+        ]
+      : []),
+  ]);
   const operationOwners = new Map();
 
   resources.forEach((resource) => {
@@ -237,7 +284,7 @@ const validateGeneratedNames = (resources, componentNames, files) => {
       schemaOwners.set(schemaName, resource);
     });
 
-    getOperationIds(resource).forEach((operationId) => {
+    Object.values(createResourceOperationIds(resource)).forEach((operationId) => {
       const owner = operationOwners.get(operationId);
 
       if (owner != null) {
@@ -250,15 +297,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 document without runtime server addresses.
+ * @param {{ database: Record<string, Array<Record<string, unknown>>>, files?: boolean, maxPageSize?: number, schema?: Record<string, unknown> }} options Source data and schema settings.
  * @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 = DEFAULT_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-объект');
   }
@@ -288,9 +343,23 @@ export function createOpenApiDocument(database, schemaConfig = {}, { files = fal
   const schemas = {
     Error: { properties: { error: { type: 'string' } }, required: ['error'], type: 'object' },
     ...(files && {
-      UploadedFile: {
-        properties: { id: { type: 'string' }, mimeType: { type: 'string' }, name: { type: 'string' }, size: { minimum: 0, type: 'integer' }, url: { type: 'string' } },
-        required: ['id', 'mimeType', 'name', 'size', 'url'],
+      FileMetadata: {
+        properties: {
+          directory: { type: 'string' },
+          downloadUrl: { type: 'string' },
+          metadataUrl: { type: 'string' },
+          mimeType: { type: 'string' },
+          name: { type: 'string' },
+          size: { minimum: 0, type: 'integer' },
+          url: { type: 'string' },
+        },
+        required: ['directory', 'downloadUrl', 'metadataUrl', 'mimeType', 'name', 'size', 'url'],
+        type: 'object',
+      },
+      FileUpdate: {
+        additionalProperties: false,
+        anyOf: [{ required: ['directory'] }, { required: ['name'] }],
+        properties: { directory: { type: 'string' }, name: { type: 'string' } },
         type: 'object',
       },
     }),
@@ -306,14 +375,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 +385,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' }] : [])],
   };
 }

package/src/openapi/index.js

@@ -1,25 +1,36 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { stringify } from 'yaml';
-import { readDatabaseFile } from '../database.js';
-import { readSchemaConfig } from './config.js';
-import { createOpenApiDocument } from './document.js';
-
-export { createOpenApiDocument } from './document.js';
-
-/**
- * Generates an OpenAPI YAML file.
- * @param {{ databasePath: string, files?: boolean, host?: string, outputPath: string, port?: number, schemaPath?: string }} options Generation options.
- * @returns {Promise<Record<string, unknown>>} Generated OpenAPI document.
- */
-export async function generateOpenApi({ databasePath, files = false, host, outputPath, port, schemaPath }) {
-  const database = await readDatabaseFile(databasePath);
-  const schemaConfig = await readSchemaConfig(schemaPath);
-  const document = createOpenApiDocument(database, schemaConfig, { files, host, port });
+import { DEFAULT_HOST, DEFAULT_PORT } from '../constants.js';
+import { buildOpenapiDocument } from './document.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}`;
+};
+
+export const createOpenapi = ({ database, files, host = DEFAULT_HOST, maxPageSize, port = DEFAULT_PORT, schema }) => {
+  const document = buildOpenapiDocument({ database, files, maxPageSize, schema });
+
+  document.servers = [{ url: getServerUrl(host, port) }];
+
+  return document;
+};
+
+export const writeOpenapi = async (document, outputPath) => {
   const resolvedOutputPath = resolve(outputPath);
 
   await mkdir(dirname(resolvedOutputPath), { recursive: true });
   await writeFile(resolvedOutputPath, stringify(document, { aliasDuplicateObjects: false, lineWidth: 0 }), 'utf8');
-
-  return document;
-}
+};

package/src/query/filter.js

@@ -10,12 +10,21 @@ const isFilterEqual = (left, right) => {
   }
 
   if (typeof left === 'number' && typeof right === 'string' && NUMBER_PATTERN.test(right)) {
+    // Query parameters are strings, so numeric strings must match stored numbers.
     return left === Number(right);
   }
 
   return typeof right === 'number' && typeof left === 'string' && NUMBER_PATTERN.test(left) && right === Number(left);
 };
 
+const validateLogicalConditions = (operator, value) => {
+  if (!Array.isArray(value) || (operator === 'or' && value.length === 0) || value.some((condition) => !isObject(condition))) {
+    throw createHttpError(400, `Оператор «${operator}» должен содержать ${operator === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
+  }
+
+  return value;
+};
+
 const matchesOperator = (field, operator, expectedValue) => {
   switch (operator) {
     case 'contains':
@@ -191,11 +200,7 @@ const validateCondition = (condition, samples, path) => {
 
   Object.entries(condition).forEach(([key, value]) => {
     if (key === 'and' || key === 'or') {
-      if (!Array.isArray(value) || (key === 'or' && value.length === 0) || value.some((nestedWhere) => !isObject(nestedWhere))) {
-        throw createHttpError(400, `Оператор «${key}» должен содержать ${key === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
-      }
-
-      value.forEach((nestedWhere) => {
+      validateLogicalConditions(key, value).forEach((nestedWhere) => {
         validateWhere(nestedWhere, samples, path);
       });
       return;
@@ -246,11 +251,7 @@ const validateCondition = (condition, samples, path) => {
 export const validateWhere = (where, items, path = '') => {
   Object.entries(where).forEach(([key, condition]) => {
     if (key === 'and' || key === 'or') {
-      if (!Array.isArray(condition) || (key === 'or' && condition.length === 0) || condition.some((nestedWhere) => !isObject(nestedWhere))) {
-        throw createHttpError(400, `Оператор «${key}» должен содержать ${key === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
-      }
-
-      condition.forEach((nestedWhere) => {
+      validateLogicalConditions(key, condition).forEach((nestedWhere) => {
         validateWhere(nestedWhere, items, path);
       });
       return;

package/src/query/pagination.js

@@ -1,4 +1,4 @@
-import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../constants.js';
+import { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE } from '../constants.js';
 import { createHttpError } from '../utils.js';
 
 const parsePositiveInteger = (value, name, defaultValue) => {
@@ -19,7 +19,7 @@ const parsePositiveInteger = (value, name, defaultValue) => {
   return number;
 };
 
-export const parsePagination = (query, maxPageSize = MAX_PAGE_SIZE) => {
+export const parsePagination = (query, maxPageSize = DEFAULT_MAX_PAGE_SIZE) => {
   const page = parsePositiveInteger(query._page, '_page', 1);
   const pageSize = parsePositiveInteger(query._perPage, '_perPage', DEFAULT_PAGE_SIZE);
 
@@ -35,16 +35,10 @@ export const parsePagination = (query, maxPageSize = MAX_PAGE_SIZE) => {
 };
 
 export const paginateItems = (items, page, pageSize) => {
-  const pages = Math.max(1, Math.ceil(items.length / pageSize));
   const offset = (page - 1) * pageSize;
 
   return {
     data: items.slice(offset, offset + pageSize),
-    first: 1,
-    items: items.length,
-    last: pages,
-    next: page < pages ? page + 1 : null,
-    pages,
-    prev: page > 1 ? Math.min(page - 1, pages) : null,
+    total: items.length,
   };
 };

package/src/relation-metadata.js

@@ -15,6 +15,7 @@ export const resolveRelationResource = (resourceNames, relation, sourceResource)
 };
 
 export const getRelationMetadata = (key, resourceNames, sourceResource) => {
+  // Relation fields follow the <resource>Id and <resource>Ids conventions.
   const match = key.match(/^(.+)(Id|Ids)$/);
 
   if (match == null) {