@kollors/deep-json-server 0.3.2 → 0.5.0

package/src/openapi/document.js

@@ -0,0 +1,331 @@
+import { DEFAULT_HOST, DEFAULT_PAGE_SIZE, DEFAULT_PORT, 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) => {
+  if (Array.isArray(schema.oneOf)) {
+    return { ...schema, oneOf: schema.oneOf.map((nestedSchema) => addForwardRelations(nestedSchema, resources, componentNames, sourceResource)) };
+  }
+
+  if (schema.type === 'array') {
+    return { ...schema, items: addForwardRelations(schema.items ?? {}, resources, componentNames, sourceResource) };
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties)) {
+    return schema;
+  }
+
+  const properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, addForwardRelations(value, resources, componentNames, sourceResource)]));
+
+  Object.keys(schema.properties).forEach((key) => {
+    const relation = getRelationMetadata(key, resources, sourceResource);
+
+    if (relation != null) {
+      const relationSchema = createSchemaReference(componentNames[relation.targetResource]);
+
+      properties[relation.relationName] = relation.isMany ? { items: relationSchema, type: 'array' } : relationSchema;
+    }
+  });
+
+  return { ...schema, properties };
+};
+
+const collectRelations = (schema, resources, sourceResource, relations = []) => {
+  if (Array.isArray(schema.oneOf)) {
+    schema.oneOf.forEach((nestedSchema) => {
+      collectRelations(nestedSchema, resources, sourceResource, relations);
+    });
+    return relations;
+  }
+
+  if (schema.type === 'array') {
+    collectRelations(schema.items ?? {}, resources, sourceResource, relations);
+    return relations;
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties)) {
+    return relations;
+  }
+
+  Object.entries(schema.properties).forEach(([key, value]) => {
+    const relation = getRelationMetadata(key, resources, sourceResource);
+
+    if (relation != null) {
+      relations.push(relation);
+    }
+
+    collectRelations(value, resources, sourceResource, relations);
+  });
+
+  return relations;
+};
+
+const addReverseRelations = (schemas, rawSchemas, resources, componentNames) => {
+  resources.forEach((sourceResource) => {
+    collectRelations(rawSchemas[sourceResource], resources, sourceResource).forEach(({ reverseRelationName, targetResource }) => {
+      const targetComponentName = componentNames[targetResource];
+      const targetSchema = schemas[targetComponentName];
+
+      if (targetSchema.type === 'object' && isObject(targetSchema.properties) && !Object.hasOwn(targetSchema.properties, reverseRelationName)) {
+        schemas[targetComponentName] = {
+          ...targetSchema,
+          properties: {
+            ...targetSchema.properties,
+            [reverseRelationName]: { items: createSchemaReference(componentNames[sourceResource]), type: 'array' },
+          },
+        };
+      }
+    });
+  });
+};
+
+const createParameters = () => ({
+  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' } },
+  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' } },
+});
+
+const createJsonContent = (schema) => ({ content: { 'application/json': { schema } } });
+const createResponse = (description, schema) => ({ description, ...(schema != null && createJsonContent(schema)) });
+const createParameterReference = (name) => ({ $ref: `#/components/parameters/${name}` });
+const createRequestBody = (name) => ({ required: true, ...createJsonContent(createSchemaReference(name)) });
+
+const createFilePaths = () => ({
+  '/_files': {
+    post: {
+      operationId: 'uploadFile',
+      parameters: [createParameterReference('ContentName')],
+      requestBody: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, required: true },
+      responses: {
+        201: createResponse('Uploaded', createSchemaReference('UploadedFile')),
+        400: createResponse('Invalid request', createSchemaReference('Error')),
+        413: createResponse('File is too large', createSchemaReference('Error')),
+        415: createResponse('Unsupported media type', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+  },
+  '/_files/{id}': {
+    delete: {
+      operationId: 'deleteFileById',
+      parameters: [createParameterReference('Id')],
+      responses: { 200: createResponse('Deleted', createSchemaReference('UploadedFile')), 404: createResponse('Not found', createSchemaReference('Error')) },
+      tags: ['files'],
+    },
+    get: {
+      operationId: 'getFileById',
+      parameters: [createParameterReference('Id')],
+      responses: {
+        200: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, description: 'File contents' },
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+  },
+});
+
+const createResourcePaths = (resource, componentName) => {
+  const resourceName = toPascalCase(resource);
+
+  return {
+    [`/${resource}`]: {
+      get: {
+        operationId: `get${resourceName}`,
+        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}`,
+        requestBody: createRequestBody(`${componentName}Create`),
+        responses: { 201: createResponse('Created', createSchemaReference(componentName)), 400: createResponse('Invalid request', createSchemaReference('Error')) },
+        tags: [resource],
+      },
+    },
+    [`/${resource}/{id}`]: {
+      delete: {
+        operationId: `delete${resourceName}ById`,
+        parameters: [createParameterReference('Id')],
+        responses: { 200: createResponse('Deleted', createSchemaReference(componentName)), 404: createResponse('Not found', createSchemaReference('Error')) },
+        tags: [resource],
+      },
+      get: {
+        operationId: `get${resourceName}ById`,
+        parameters: [createParameterReference('Id'), createParameterReference('Embed')],
+        responses: {
+          200: createResponse('Successful response', createSchemaReference(componentName)),
+          400: createResponse('Invalid query', createSchemaReference('Error')),
+          404: createResponse('Not found', createSchemaReference('Error')),
+        },
+        tags: [resource],
+      },
+      patch: {
+        operationId: `patch${resourceName}ById`,
+        parameters: [createParameterReference('Id')],
+        requestBody: createRequestBody(`${componentName}Update`),
+        responses: {
+          200: createResponse('Updated', createSchemaReference(componentName)),
+          400: createResponse('Invalid request', createSchemaReference('Error')),
+          404: createResponse('Not found', createSchemaReference('Error')),
+        },
+        tags: [resource],
+      },
+      put: {
+        operationId: `put${resourceName}ById`,
+        parameters: [createParameterReference('Id')],
+        requestBody: createRequestBody(`${componentName}Create`),
+        responses: {
+          200: createResponse('Replaced', createSchemaReference(componentName)),
+          400: createResponse('Invalid request', createSchemaReference('Error')),
+          404: createResponse('Not found', createSchemaReference('Error')),
+        },
+        tags: [resource],
+      },
+    },
+  };
+};
+
+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 operationOwners = new Map();
+
+  resources.forEach((resource) => {
+    const componentName = componentNames[resource];
+
+    if (componentName === '') {
+      throw new Error(`Не удалось сформировать имя OpenAPI-схемы для ресурса «${resource}». Укажите $schema.${resource}.name`);
+    }
+
+    [componentName, `${componentName}Create`, `${componentName}Update`, `${componentName}Page`].forEach((schemaName) => {
+      const owner = schemaOwners.get(schemaName);
+
+      if (owner != null) {
+        throw new Error(`Имя OpenAPI-схемы «${schemaName}» используется ресурсами «${owner}» и «${resource}». Укажите уникальный $schema.${resource}.name`);
+      }
+
+      schemaOwners.set(schemaName, resource);
+    });
+
+    getOperationIds(resource).forEach((operationId) => {
+      const owner = operationOwners.get(operationId);
+
+      if (owner != null) {
+        throw new Error(`operationId «${operationId}» используется ресурсами «${owner}» и «${resource}». Переименуйте один из ресурсов`);
+      }
+
+      operationOwners.set(operationId, resource);
+    });
+  });
+};
+
+/**
+ * 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.
+ * @returns {Record<string, unknown>} OpenAPI document.
+ */
+export function createOpenApiDocument(database, schemaConfig = {}, { files = false, host = DEFAULT_HOST, port = DEFAULT_PORT } = {}) {
+  validateDatabase(database);
+
+  if (!isObject(schemaConfig)) {
+    throw new Error('Схема базы данных должна содержать JSON-объект');
+  }
+
+  const resources = getResourceNames(database);
+  const resourceConfigs = validateSchemaConfig(schemaConfig, resources);
+  const componentNames = Object.fromEntries(
+    resources.map((resource) => {
+      const resourceConfig = isObject(resourceConfigs[resource]) ? resourceConfigs[resource] : {};
+      const componentName = typeof resourceConfig.name === 'string' && resourceConfig.name !== '' ? resourceConfig.name : toPascalCase(singularize(resource));
+
+      return [resource, componentName];
+    }),
+  );
+
+  validateGeneratedNames(resources, componentNames, files);
+
+  const rawSchemas = Object.fromEntries(
+    resources.map((resource) => {
+      const resourceConfig = isObject(resourceConfigs[resource]) ? resourceConfigs[resource] : {};
+      const inferredSchema = database[resource].length === 0 ? { properties: { id: { type: 'string' } }, type: 'object' } : inferObjectSchema(database[resource]);
+      const configuredSchema = mergeSchemaOverrides(inferredSchema, { properties: isObject(resourceConfig.properties) ? resourceConfig.properties : {} });
+
+      return [resource, applyConfiguredFields(ensureGeneratedIdSchema(configuredSchema), resource, resourceConfig)];
+    }),
+  );
+  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'],
+        type: 'object',
+      },
+    }),
+  };
+
+  resources.forEach((resource) => {
+    const componentName = componentNames[resource];
+    const rawSchema = rawSchemas[resource];
+
+    schemas[componentName] = addForwardRelations(rawSchema, resources, componentNames, resource);
+    schemas[`${componentName}Create`] = omitId(rawSchema, true);
+    schemas[`${componentName}Update`] = omitId(rawSchema, false);
+    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' },
+      },
+      required: ['data', 'first', 'items', 'last', 'next', 'pages', 'prev'],
+      type: 'object',
+    };
+  });
+
+  addReverseRelations(schemas, rawSchemas, resources, componentNames);
+
+  return {
+    components: { parameters: createParameters(), 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

@@ -0,0 +1,25 @@
+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 });
+  const resolvedOutputPath = resolve(outputPath);
+
+  await mkdir(dirname(resolvedOutputPath), { recursive: true });
+  await writeFile(resolvedOutputPath, stringify(document, { aliasDuplicateObjects: false, lineWidth: 0 }), 'utf8');
+
+  return document;
+}

package/src/openapi/inference.js

@@ -0,0 +1,187 @@
+import { isObject } from '../utils.js';
+
+export const mergeSchemas = (schemas) => {
+  const uniqueSchemas = [...new Map(schemas.map((schema) => [JSON.stringify(schema), schema])).values()];
+  const nullable = uniqueSchemas.some((schema) => schema.type === 'null');
+  const nonNullSchemas = uniqueSchemas.filter((schema) => schema.type !== 'null');
+
+  if (nonNullSchemas.length === 0) {
+    return { nullable: true };
+  }
+
+  if (nonNullSchemas.length === 1) {
+    return nullable ? { ...nonNullSchemas[0], nullable: true } : nonNullSchemas[0];
+  }
+
+  return { oneOf: nonNullSchemas, ...(nullable && { nullable: true }) };
+};
+
+export const mergeSchemaOverrides = (schema, overrides) => {
+  if (!isObject(overrides)) {
+    return schema;
+  }
+
+  const result = { ...schema, ...overrides };
+
+  if (Object.hasOwn(overrides, 'type') && !Object.hasOwn(overrides, 'oneOf')) {
+    delete result.oneOf;
+  }
+
+  if (isObject(schema.properties) || isObject(overrides.properties)) {
+    const properties = isObject(schema.properties) ? { ...schema.properties } : {};
+
+    Object.entries(isObject(overrides.properties) ? overrides.properties : {}).forEach(([key, value]) => {
+      properties[key] = mergeSchemaOverrides(properties[key] ?? {}, value);
+    });
+
+    result.properties = properties;
+  }
+
+  if (isObject(schema.items) && isObject(overrides.items)) {
+    result.items = mergeSchemaOverrides(schema.items, overrides.items);
+  }
+
+  return result;
+};
+
+export const applyRequiredFields = (schema, path, requiredFields) => {
+  if (Array.isArray(schema.oneOf)) {
+    return { ...schema, oneOf: schema.oneOf.map((nestedSchema) => applyRequiredFields(nestedSchema, path, requiredFields)) };
+  }
+
+  if (schema.type === 'array') {
+    return { ...schema, items: applyRequiredFields(schema.items ?? {}, path, requiredFields) };
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties)) {
+    return schema;
+  }
+
+  const properties = Object.fromEntries(
+    Object.entries(schema.properties).map(([key, value]) => {
+      const fieldPath = path === '' ? key : `${path}.${key}`;
+
+      return [key, applyRequiredFields(value, fieldPath, requiredFields)];
+    }),
+  );
+  const required = Object.keys(properties).filter((key) => {
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+
+    return (path === '' && key === 'id') || requiredFields.has(fieldPath);
+  });
+  const result = { ...schema, properties };
+
+  delete result.required;
+
+  return required.length === 0 ? result : { ...result, required };
+};
+
+export const inferSchema = (values) => {
+  const schemas = [];
+  const arrays = values.filter(Array.isArray);
+  const objects = values.filter(isObject);
+
+  if (arrays.length > 0) {
+    const items = arrays.flat();
+
+    schemas.push({ items: items.length === 0 ? {} : inferSchema(items), type: 'array' });
+  }
+
+  if (objects.length > 0) {
+    schemas.push(inferObjectSchema(objects));
+  }
+
+  values
+    .filter((value) => !Array.isArray(value) && !isObject(value))
+    .forEach((value) => {
+      if (value === null) {
+        schemas.push({ type: 'null' });
+      } else if (typeof value === 'number') {
+        schemas.push({ type: Number.isInteger(value) ? 'integer' : 'number' });
+      } else {
+        schemas.push({ type: typeof value });
+      }
+    });
+
+  return mergeSchemas(schemas);
+};
+
+export function inferObjectSchema(values) {
+  const keys = [...new Set(values.flatMap((value) => Object.keys(value)))].sort((left, right) => (left === 'id' ? -1 : right === 'id' ? 1 : left.localeCompare(right)));
+  const properties = Object.fromEntries(
+    keys.map((key) => {
+      const fieldValues = values.filter((value) => Object.hasOwn(value, key)).map((value) => value[key]);
+
+      return [key, inferSchema(fieldValues)];
+    }),
+  );
+
+  return { properties, type: 'object' };
+}
+
+export const ensureGeneratedIdSchema = (schema) => {
+  const idSchema = schema.properties?.id ?? {};
+  const idSchemas = Array.isArray(idSchema.oneOf) ? idSchema.oneOf : [idSchema];
+  const properties = {
+    ...schema.properties,
+    id: idSchemas.some(({ type }) => type === 'string') ? idSchema : { oneOf: [...idSchemas, { type: 'string' }] },
+  };
+
+  return { ...schema, properties };
+};
+
+export const getSchemasAtPath = (schema, keys) => {
+  if (Array.isArray(schema.oneOf)) {
+    return schema.oneOf.flatMap((nestedSchema) => getSchemasAtPath(nestedSchema, keys));
+  }
+
+  if (schema.type === 'array') {
+    return getSchemasAtPath(schema.items ?? {}, keys);
+  }
+
+  if (keys.length === 0) {
+    return [schema];
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties) || !Object.hasOwn(schema.properties, keys[0])) {
+    return [];
+  }
+
+  return getSchemasAtPath(schema.properties[keys[0]], keys.slice(1));
+};
+
+export const updateSchemasAtPath = (schema, keys, update) => {
+  if (Array.isArray(schema.oneOf)) {
+    return { ...schema, oneOf: schema.oneOf.map((nestedSchema) => updateSchemasAtPath(nestedSchema, keys, update)) };
+  }
+
+  if (schema.type === 'array') {
+    return { ...schema, items: updateSchemasAtPath(schema.items ?? {}, keys, update) };
+  }
+
+  if (keys.length === 0) {
+    return update(schema);
+  }
+
+  if (schema.type !== 'object' || !isObject(schema.properties) || !Object.hasOwn(schema.properties, keys[0])) {
+    return schema;
+  }
+
+  return {
+    ...schema,
+    properties: {
+      ...schema.properties,
+      [keys[0]]: updateSchemasAtPath(schema.properties[keys[0]], keys.slice(1), update),
+    },
+  };
+};
+
+export const omitId = (schema, keepRequired) => {
+  const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).filter(([key]) => key !== 'id'));
+  const required = keepRequired ? schema.required?.filter((key) => key !== 'id') : undefined;
+  const result = { ...schema, properties };
+
+  delete result.required;
+
+  return required?.length > 0 ? { ...result, required } : result;
+};