@kollors/deep-json-server 0.3.2 → 0.5.0

package/src/server.js

@@ -1,27 +1,19 @@
 import Fastify from 'fastify';
-import { JSONFilePreset } from 'lowdb/node';
-import { randomBytes } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { matchesWhere, paginateItems, parsePagination, parseWhere, sortItems, validateWhere } from './query.js';
-import { embedItem, parseEmbedPaths } from './relations.js';
-import { createHttpError, getResourceNames, isObject, isSafeKey, resolveDatabasePath, validateDatabase } from './utils.js';
+import { DEFAULT_HOST, DEFAULT_MAX_FILE_SIZE, DEFAULT_PORT, MAX_PAGE_SIZE } from './constants.js';
+import { createDatabaseStore, createId, findItem, getCollection } from './database.js';
+import { registerFileRoutes } from './files.js';
+import { readSchemaConfig } from './openapi/config.js';
+import { createOpenApiDocument } from './openapi/index.js';
+import { matchesWhere, paginateItems, parsePagination, parseWhere, sortItems, validateWhere } from './query/index.js';
+import { embedItem, parseEmbedPaths, validateEmbedPaths } from './relations.js';
+import { createHttpError, getResourceNames, isObject, resolveDatabasePath } from './utils.js';
 
 const CORS_HEADERS = {
-  'Access-Control-Allow-Headers': 'Content-Type',
+  'Access-Control-Allow-Headers': 'Content-Name, Content-Type',
   'Access-Control-Allow-Methods': 'DELETE, GET, OPTIONS, PATCH, POST, PUT',
   'Access-Control-Allow-Origin': '*',
 };
 
-const getCollection = (database, resource) => {
-  const collection = isSafeKey(resource) ? database.data[resource] : undefined;
-
-  if (!Array.isArray(collection)) {
-    throw createHttpError(404, 'Ресурс не найден');
-  }
-
-  return collection;
-};
-
 const getRequestBody = (body) => {
   if (!isObject(body)) {
     throw createHttpError(400, 'Тело запроса должно быть JSON-объектом');
@@ -30,97 +22,66 @@ const getRequestBody = (body) => {
   return body;
 };
 
-const findItem = (collection, id) => collection.find((item) => isObject(item) && String(item.id) === id);
-
-const readDatabaseFile = async(databasePath) => {
-  let source;
-
-  try {
-    source = await readFile(databasePath, 'utf8');
-  } catch (error) {
-    if (error?.code === 'ENOENT') {
-      throw new Error(`Файл базы данных не найден: ${databasePath}`);
-    }
-
-    throw error;
-  }
-
-  const data = JSON.parse(source);
-
-  return validateDatabase(data);
-};
-
-export async function createServer({ databasePath, logger = true } = {}) {
-  const resolvedDatabasePath = resolveDatabasePath(databasePath);
-  const initialData = await readDatabaseFile(resolvedDatabasePath);
-  const database = await JSONFilePreset(resolvedDatabasePath, initialData);
-  const server = Fastify({ logger });
-  let databaseWriteQueue = Promise.resolve();
-
-  const readDatabase = async() => {
-    database.data = await readDatabaseFile(resolvedDatabasePath);
-  };
-
-  const updateDatabase = (update) => {
-    const operation = databaseWriteQueue.then(async() => {
-      await readDatabase();
-
-      const result = update();
-
-      await database.write();
-
-      return result;
-    });
+const getSchemaName = (reference) => reference.split('/').at(-1);
 
-    databaseWriteQueue = operation.catch(() => undefined);
+const addRequestSchemas = (server, document, resources) => {
+  const requestSchemaNames = new Set(
+    resources.flatMap((resource) => {
+      const resourcePath = document.paths[`/${resource}`];
+      const itemPath = document.paths[`/${resource}/{id}`];
 
-    return operation;
-  };
+      return [getSchemaName(resourcePath.post.requestBody.content['application/json'].schema.$ref), getSchemaName(itemPath.patch.requestBody.content['application/json'].schema.$ref)];
+    }),
+  );
 
-  server.addHook('onRequest', async(_request, reply) => {
-    Object.entries(CORS_HEADERS).forEach(([header, value]) => reply.header(header, value));
-  });
-
-  server.addHook('preHandler', async(request) => {
-    if (request.method === 'GET') {
-      await readDatabase();
-    }
+  requestSchemaNames.forEach((schemaName) => {
+    server.addSchema({ $id: schemaName, ...document.components.schemas[schemaName] });
   });
+};
 
-  server.options('/', async(_request, reply) => reply.code(204).send());
-  server.options('/*', async(_request, reply) => reply.code(204).send());
-  server.get('/', async() => ({ resources: getResourceNames(database.data) }));
+const registerResourceRoutes = (server, store, resource, document, maxPageSize) => {
+  const resourcePath = `/${resource}`;
+  const itemPath = `/${resource}/:id`;
+  const createSchemaName = getSchemaName(document.paths[resourcePath].post.requestBody.content['application/json'].schema.$ref);
+  const updateSchemaName = getSchemaName(document.paths[`/${resource}/{id}`].patch.requestBody.content['application/json'].schema.$ref);
 
-  server.get('/:resource', async(request) => {
-    const collection = getCollection(database, request.params.resource);
+  server.get(resourcePath, async (request) => {
+    const collection = getCollection(store.database, resource);
     const where = parseWhere(request.query);
     const embedPaths = parseEmbedPaths(request.query._embed);
+    const pagination = parsePagination(request.query, maxPageSize);
+
+    validateEmbedPaths(store.database, resource, collection, embedPaths);
+
     const relationIndexes = new Map();
-    const embeddedItems = collection.map((item) => embedItem(database, item, request.params.resource, embedPaths, relationIndexes));
-    const pagination = parsePagination(request.query);
+    const embeddedItems = collection.map((item) => embedItem(store.database, item, resource, embedPaths, relationIndexes));
 
     validateWhere(where, embeddedItems);
 
     const filteredItems = embeddedItems.filter((item) => matchesWhere(item, where));
-    const sortedItems = sortItems(filteredItems, request.query._sort);
+    const sortedItems = sortItems(filteredItems, request.query._sort, embeddedItems);
 
     return paginateItems(sortedItems, pagination.page, pagination.pageSize);
   });
 
-  server.get('/:resource/:id', async(request) => {
-    const item = findItem(getCollection(database, request.params.resource), request.params.id);
+  server.get(itemPath, async (request) => {
+    const collection = getCollection(store.database, resource);
+    const item = findItem(collection, request.params.id);
+    const embedPaths = parseEmbedPaths(request.query._embed);
 
     if (item == null) {
       throw createHttpError(404, 'Запись не найдена');
     }
 
-    return embedItem(database, item, request.params.resource, parseEmbedPaths(request.query._embed));
+    validateEmbedPaths(store.database, resource, collection, embedPaths);
+
+    return embedItem(store.database, item, resource, embedPaths);
   });
 
-  server.post('/:resource', async(request, reply) => {
-    const item = await updateDatabase(() => {
-      const collection = getCollection(database, request.params.resource);
-      const createdItem = { ...getRequestBody(request.body), id: randomBytes(8).toString('base64url') };
+  server.post(resourcePath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request, reply) => {
+    const item = await store.update((database) => {
+      const collection = getCollection(database, resource);
+      const createdItem = { ...getRequestBody(request.body), id: createId(collection) };
 
       collection.push(createdItem);
 
@@ -130,9 +91,9 @@ export async function createServer({ databasePath, logger = true } = {}) {
     return reply.code(201).send(item);
   });
 
-  server.put('/:resource/:id', async(request) => {
-    return updateDatabase(() => {
-      const collection = getCollection(database, request.params.resource);
+  server.put(itemPath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request) =>
+    store.update((database) => {
+      const collection = getCollection(database, resource);
       const currentItem = findItem(collection, request.params.id);
 
       if (currentItem == null) {
@@ -144,12 +105,12 @@ export async function createServer({ databasePath, logger = true } = {}) {
       collection.splice(collection.indexOf(currentItem), 1, item);
 
       return item;
-    });
-  });
+    }),
+  );
 
-  server.patch('/:resource/:id', async(request) => {
-    return updateDatabase(() => {
-      const collection = getCollection(database, request.params.resource);
+  server.patch(itemPath, { schema: { body: { $ref: `${updateSchemaName}#` } } }, async (request) =>
+    store.update((database) => {
+      const collection = getCollection(database, resource);
       const currentItem = findItem(collection, request.params.id);
 
       if (currentItem == null) {
@@ -161,12 +122,12 @@ export async function createServer({ databasePath, logger = true } = {}) {
       collection.splice(collection.indexOf(currentItem), 1, item);
 
       return item;
-    });
-  });
+    }),
+  );
 
-  server.delete('/:resource/:id', async(request) => {
-    return updateDatabase(() => {
-      const collection = getCollection(database, request.params.resource);
+  server.delete(itemPath, async (request) =>
+    store.update((database) => {
+      const collection = getCollection(database, resource);
       const currentItem = findItem(collection, request.params.id);
 
       if (currentItem == null) {
@@ -176,9 +137,62 @@ export async function createServer({ databasePath, logger = true } = {}) {
       collection.splice(collection.indexOf(currentItem), 1);
 
       return currentItem;
+    }),
+  );
+};
+
+/**
+ * Creates a Fastify server without opening a network port.
+ * @param {{ databasePath: string, filesDirectoryPath?: string, filesMetadataPath?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, schemaPath?: string }} options Server options.
+ * @returns {Promise<import('fastify').FastifyInstance>} Fastify server.
+ */
+export async function createServer(options) {
+  const { databasePath, filesDirectoryPath, filesMetadataPath, logger = true, maxFileSize = DEFAULT_MAX_FILE_SIZE, maxPageSize = MAX_PAGE_SIZE, schemaPath } = options ?? {};
+
+  if (!Number.isInteger(maxPageSize) || maxPageSize < 1) {
+    throw new Error('Максимальный размер страницы должен быть положительным целым числом');
+  }
+
+  if (!Number.isInteger(maxFileSize) || maxFileSize < 1) {
+    throw new Error('Максимальный размер файла должен быть положительным целым числом');
+  }
+
+  const store = await createDatabaseStore(databasePath);
+  const schemaConfig = await readSchemaConfig(schemaPath);
+  const document = createOpenApiDocument(store.database.data, schemaConfig);
+  const resources = getResourceNames(store.database.data);
+  const server = Fastify({ logger });
+
+  addRequestSchemas(server, document, resources);
+
+  server.addHook('onRequest', async (_request, reply) => {
+    Object.entries(CORS_HEADERS).forEach(([header, value]) => {
+      reply.header(header, value);
     });
   });
 
+  server.addHook('preHandler', async (request) => {
+    if (request.method === 'GET') {
+      await store.read();
+    }
+  });
+
+  server.options('/', async (_request, reply) => reply.code(204).send());
+  server.options('/*', async (_request, reply) => reply.code(204).send());
+  server.get('/', async () => ({ resources }));
+
+  resources.forEach((resource) => {
+    registerResourceRoutes(server, store, resource, document, maxPageSize);
+  });
+
+  if ((filesDirectoryPath == null) !== (filesMetadataPath == null)) {
+    throw new Error('Для файловых маршрутов укажите filesDirectoryPath и filesMetadataPath');
+  }
+
+  if (filesDirectoryPath != null) {
+    await registerFileRoutes(server, { directoryPath: filesDirectoryPath, maxFileSize, metadataPath: filesMetadataPath });
+  }
+
   server.setErrorHandler((error, request, reply) => {
     const statusCode = Number.isInteger(error.statusCode) ? error.statusCode : 500;
 
@@ -192,13 +206,30 @@ export async function createServer({ databasePath, logger = true } = {}) {
   return server;
 }
 
-export async function startServer({ databasePath, host = '127.0.0.1', logger = true, port = 4001 } = {}) {
-  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-    throw new Error('Порт должен быть целым числом от 1 до 65535');
+/**
+ * Creates and starts a Fastify server.
+ * @param {{ databasePath: string, filesDirectoryPath?: string, filesMetadataPath?: string, host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number, schemaPath?: string }} options Server options.
+ * @returns {Promise<import('fastify').FastifyInstance>} Listening Fastify server.
+ */
+export async function startServer(options) {
+  const {
+    databasePath,
+    filesDirectoryPath,
+    filesMetadataPath,
+    host = DEFAULT_HOST,
+    logger = true,
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    maxPageSize = MAX_PAGE_SIZE,
+    port = DEFAULT_PORT,
+    schemaPath,
+  } = options ?? {};
+
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new Error('Порт должен быть целым числом от 0 до 65535');
   }
 
   const resolvedDatabasePath = resolveDatabasePath(databasePath);
-  const server = await createServer({ databasePath: resolvedDatabasePath, logger });
+  const server = await createServer({ databasePath: resolvedDatabasePath, filesDirectoryPath, filesMetadataPath, logger, maxFileSize, maxPageSize, schemaPath });
 
   await server.listen({ host, port });
   server.log.info({ database: resolvedDatabasePath }, 'Deep JSON Server запущен');

package/src/utils.js

@@ -1,6 +1,4 @@
-import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import pluralize from 'pluralize';
 
 const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
@@ -14,25 +12,10 @@ export const createHttpError = (statusCode, message) => {
 };
 
 export const getResourceNames = (data) => Object.keys(data);
-export const isMainModule = (filePath, moduleUrl) => filePath != null && realpathSync(resolve(filePath)) === fileURLToPath(moduleUrl);
 export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 export const isSafeKey = (key) => !UNSAFE_KEYS.has(key);
 export const toArray = (value) => (Array.isArray(value) ? value : [value]);
 
-export const validateDatabase = (data) => {
-  if (!isObject(data)) {
-    throw new Error('База данных должна содержать JSON-объект');
-  }
-
-  const invalidResource = Object.entries(data).find(([, value]) => !Array.isArray(value));
-
-  if (invalidResource != null) {
-    throw new Error(`Ресурс «${invalidResource[0]}» должен содержать JSON-массив`);
-  }
-
-  return data;
-};
-
 export const isEqual = (left, right) => {
   if (Object.is(left, right)) {
     return true;
@@ -60,6 +43,12 @@ export const resolveDatabasePath = (databasePath) => {
   return resolve(databasePath);
 };
 
+export const isIdEqual = (left, right) => left != null && right != null && String(left) === String(right);
 export const singularize = (value) => pluralize.singular(value);
 
-export const toPascalCase = (value) => value.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`).join('');
+export const toPascalCase = (value) =>
+  value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('');

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export { createOpenApiDocument, generateOpenApi } from './src/openapi/index.js';
+export { createServer, startServer } from './src/server.js';

package/types/src/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+export declare const DEFAULT_PAGE_SIZE = 10;
+export declare const DEFAULT_PORT = 4001;
+export declare const MAX_PAGE_SIZE = 1000;

package/types/src/database.d.ts

@@ -0,0 +1,8 @@
+export declare const validateDatabase: (data: any) => any;
+export declare const readJsonObject: (path: any, label: any) => Promise<any>;
+export declare const readDatabaseFile: (databasePath: any) => Promise<any>;
+/** @returns {Promise<any>} Internal LowDB-backed store. */
+export declare const createDatabaseStore: (databasePath: any) => Promise<any>;
+export declare const getCollection: (database: any, resource: any) => any[];
+export declare const findItem: (collection: any, id: any) => any;
+export declare const createId: (collection: any) => any;

package/types/src/files.d.ts

@@ -0,0 +1,5 @@
+export declare const registerFileRoutes: (server: any, { directoryPath, maxFileSize, metadataPath }: {
+    directoryPath: any;
+    maxFileSize: any;
+    metadataPath: any;
+}) => Promise<void>;

package/types/src/openapi/config.d.ts

@@ -0,0 +1,3 @@
+export declare const validateSchemaConfig: (schemaConfig: any, resources: any) => any;
+export declare const applyConfiguredFields: (schema: any, resource: any, resourceConfig: any) => any;
+export declare const readSchemaConfig: (schemaPath: any) => Promise<any>;

package/types/src/openapi/document.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function createOpenApiDocument(database: Record<string, Array<Record<string, unknown>>>, schemaConfig?: Record<string, unknown>, { files, host, port }?: {
+    files?: boolean;
+    host?: string;
+    port?: number;
+}): Record<string, unknown>;

package/types/src/openapi/index.d.ts

@@ -0,0 +1,14 @@
+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 declare function generateOpenApi({ databasePath, files, host, outputPath, port, schemaPath }: {
+    databasePath: string;
+    files?: boolean;
+    host?: string;
+    outputPath: string;
+    port?: number;
+    schemaPath?: string;
+}): Promise<Record<string, unknown>>;

package/types/src/openapi/inference.d.ts

@@ -0,0 +1,9 @@
+export declare const mergeSchemas: (schemas: any) => any;
+export declare const mergeSchemaOverrides: (schema: any, overrides: any) => any;
+export declare const applyRequiredFields: (schema: any, path: any, requiredFields: any) => any;
+export declare const inferSchema: (values: any) => any;
+export declare function inferObjectSchema(values: any): any;
+export declare const ensureGeneratedIdSchema: (schema: any) => any;
+export declare const getSchemasAtPath: (schema: any, keys: any) => any;
+export declare const updateSchemasAtPath: (schema: any, keys: any, update: any) => any;
+export declare const omitId: (schema: any, keepRequired: any) => any;

package/types/src/query/filter.d.ts

@@ -0,0 +1,3 @@
+export declare function matchesWhere(value: any, where: any): any;
+export declare const parseWhere: (query: any) => any;
+export declare const validateWhere: (where: any, items: any, path?: string) => void;

package/types/src/query/index.d.ts

@@ -0,0 +1,3 @@
+export { matchesWhere, parseWhere, validateWhere } from './filter.js';
+export { paginateItems, parsePagination } from './pagination.js';
+export { sortItems } from './sort.js';

package/types/src/query/pagination.d.ts

@@ -0,0 +1,13 @@
+export declare const parsePagination: (query: any, maxPageSize?: number) => {
+    page: any;
+    pageSize: any;
+};
+export declare const paginateItems: (items: any, page: any, pageSize: any) => {
+    data: any;
+    first: number;
+    items: any;
+    last: number;
+    next: any;
+    pages: number;
+    prev: number | null;
+};

package/types/src/query/sort.d.ts

@@ -0,0 +1 @@
+export declare const sortItems: (items: any, sort: any, validationItems?: any) => any[];

package/types/src/relation-metadata.d.ts

@@ -0,0 +1,9 @@
+export declare const getRelationKeys: (...names: any[]) => string[];
+export declare const resolveRelationResource: (resourceNames: any, relation: any, sourceResource: any) => any;
+export declare const getRelationMetadata: (key: any, resourceNames: any, sourceResource: any) => {
+    isMany: boolean;
+    relationName: any;
+    reverseRelationName: any;
+    sourceResource: any;
+    targetResource: any;
+} | undefined;

package/types/src/relations.d.ts

@@ -0,0 +1,3 @@
+export declare const parseEmbedPaths: (embed: any) => any[];
+export declare const validateEmbedPaths: (database: any, resource: any, items: any, embedPaths: any) => void;
+export declare const embedItem: (database: any, item: any, resource: any, embedPaths: any, indexes?: Map<any, any>) => any;

package/types/src/server.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Creates a Fastify server without opening a network port.
+ * @param {{ databasePath: string, filesDirectoryPath?: string, filesMetadataPath?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, schemaPath?: string }} options Server options.
+ * @returns {Promise<import('fastify').FastifyInstance>} Fastify server.
+ */
+export declare function createServer(options: {
+    databasePath: string;
+    filesDirectoryPath?: string;
+    filesMetadataPath?: string;
+    logger?: boolean | Record<string, unknown>;
+    maxFileSize?: number;
+    maxPageSize?: number;
+    schemaPath?: string;
+}): Promise<import('fastify').FastifyInstance>;
+/**
+ * Creates and starts a Fastify server.
+ * @param {{ databasePath: string, filesDirectoryPath?: string, filesMetadataPath?: string, host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number, schemaPath?: string }} options Server options.
+ * @returns {Promise<import('fastify').FastifyInstance>} Listening Fastify server.
+ */
+export declare function startServer(options: {
+    databasePath: string;
+    filesDirectoryPath?: string;
+    filesMetadataPath?: string;
+    host?: string;
+    logger?: boolean | Record<string, unknown>;
+    maxFileSize?: number;
+    maxPageSize?: number;
+    port?: number;
+    schemaPath?: string;
+}): Promise<import('fastify').FastifyInstance>;

package/types/src/utils.d.ts

@@ -0,0 +1,10 @@
+export declare const createHttpError: (statusCode: any, message: any) => Error;
+export declare const getResourceNames: (data: any) => string[];
+export declare const isObject: (value: any) => boolean;
+export declare const isSafeKey: (key: any) => boolean;
+export declare const toArray: (value: any) => any[];
+export declare const isEqual: (left: any, right: any) => any;
+export declare const resolveDatabasePath: (databasePath: any) => any;
+export declare const isIdEqual: (left: any, right: any) => boolean;
+export declare const singularize: (value: any) => any;
+export declare const toPascalCase: (value: any) => any;