@kollors/deep-json-server 0.5.0 → 0.6.0

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/pagination.js

@@ -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/server.js

@@ -1,12 +1,16 @@
 import Fastify from 'fastify';
+import { normalizeServerConfig } from './config.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 { createFileStore, registerFileRoutes } from './files.js';
+import { resolveSchemaConfig } from './openapi/config.js';
+import { buildOpenapiDocument } from './openapi/document.js';
+import { createOpenapi, writeOpenapi } 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';
+import { createHttpError, getResourceNames, isObject } from './utils.js';
+
+/** @typedef {Record<string, unknown>} OpenapiDocument */
 
 const CORS_HEADERS = {
   'Access-Control-Allow-Headers': 'Content-Name, Content-Type',
@@ -142,97 +146,103 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
 };
 
 /**
- * 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.
+ * Creates a Deep JSON Server facade.
+ * @param {import('./config.js').DeepJsonServerConfig} options Server options.
+ * @param {{ files?: boolean }} [features] Optional feature switches.
+ * @returns {Promise<{ fastify: () => import('fastify').FastifyInstance, openapi: () => Promise<OpenapiDocument> }>} Server facade.
  */
-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('Максимальный размер страницы должен быть положительным целым числом');
+export async function createServer(options, features = {}) {
+  const config = normalizeServerConfig(options);
+  const filesEnabled = features.files ?? config.files != null;
+  const { logger = true, maxFileSize = DEFAULT_MAX_FILE_SIZE, maxPageSize = MAX_PAGE_SIZE } = config.server;
+  const store = await createDatabaseStore(config.database);
+  const schema = await resolveSchemaConfig(config.database.schema);
+  const fileStore = filesEnabled && config.files != null ? await createFileStore(config.files) : undefined;
+  let fastifyInstance;
+
+  if (filesEnabled && config.files == null) {
+    throw new Error('Для файловых маршрутов укажите секцию config.files');
   }
 
-  if (!Number.isInteger(maxFileSize) || maxFileSize < 1) {
-    throw new Error('Максимальный размер файла должен быть положительным целым числом');
-  }
+  const buildDocument = () =>
+    buildOpenapiDocument({
+      database: store.database.data,
+      files: filesEnabled,
+      maxPageSize,
+      schema,
+    });
+
+  const fastify = () => {
+    if (fastifyInstance != null) {
+      return fastifyInstance;
+    }
+
+    const document = buildDocument();
+    const resources = getResourceNames(store.database.data);
+    const server = Fastify({ logger });
+    const listen = server.listen.bind(server);
 
-  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 });
+    server.listen = (...args) => listen(...(args.length === 0 ? [{ host: config.server.host ?? DEFAULT_HOST, port: config.server.port ?? DEFAULT_PORT }] : args));
 
-  addRequestSchemas(server, document, resources);
+    addRequestSchemas(server, document, resources);
 
-  server.addHook('onRequest', async (_request, reply) => {
-    Object.entries(CORS_HEADERS).forEach(([header, value]) => {
-      reply.header(header, value);
+    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.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 }));
+    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);
-  });
+    resources.forEach((resource) => {
+      registerResourceRoutes(server, store, resource, document, maxPageSize);
+    });
 
-  if ((filesDirectoryPath == null) !== (filesMetadataPath == null)) {
-    throw new Error('Для файловых маршрутов укажите filesDirectoryPath и filesMetadataPath');
-  }
+    if (fileStore != null) {
+      registerFileRoutes(server, { maxFileSize, store: fileStore });
+    }
 
-  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;
 
-  server.setErrorHandler((error, request, reply) => {
-    const statusCode = Number.isInteger(error.statusCode) ? error.statusCode : 500;
+      if (statusCode === 500) {
+        request.log.error(error);
+      }
 
-    if (statusCode === 500) {
-      request.log.error(error);
-    }
+      return reply.code(statusCode).send({ error: error.message });
+    });
 
-    return reply.code(statusCode).send({ error: error.message });
-  });
+    fastifyInstance = server;
 
-  return server;
-}
+    return 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 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 openapi = async () => {
+    await store.read();
 
-  const resolvedDatabasePath = resolveDatabasePath(databasePath);
-  const server = await createServer({ databasePath: resolvedDatabasePath, filesDirectoryPath, filesMetadataPath, logger, maxFileSize, maxPageSize, schemaPath });
+    const document = createOpenapi({
+      database: store.database.data,
+      files: filesEnabled,
+      host: config.server.host,
+      maxPageSize,
+      port: config.server.port,
+      schema,
+    });
+
+    if (config.openapi.path != null) {
+      await writeOpenapi(document, config.openapi.path);
+    }
 
-  await server.listen({ host, port });
-  server.log.info({ database: resolvedDatabasePath }, 'Deep JSON Server запущен');
+    return document;
+  };
 
-  return server;
+  return { fastify, openapi };
 }

package/types/index.d.ts

@@ -1,2 +1,11 @@
-export { createOpenApiDocument, generateOpenApi } from './src/openapi/index.js';
-export { createServer, startServer } from './src/server.js';
+/** @typedef {import('./src/config.js').DeepJsonServerConfig} DeepJsonServerConfig */
+/** @typedef {import('./src/config.js').DatabaseConfig} DatabaseConfig */
+/** @typedef {import('./src/config.js').FilesConfig} FilesConfig */
+/** @typedef {import('./src/config.js').MemoryFile} MemoryFile */
+/** @typedef {import('./src/server.js').OpenapiDocument} OpenapiDocument */
+export type DeepJsonServerConfig = import('./src/config.js').DeepJsonServerConfig;
+export type DatabaseConfig = import('./src/config.js').DatabaseConfig;
+export type FilesConfig = import('./src/config.js').FilesConfig;
+export type MemoryFile = import('./src/config.js').MemoryFile;
+export type OpenapiDocument = import('./src/server.js').OpenapiDocument;
+export { createServer } from './src/server.js';

package/types/src/config.d.ts

@@ -0,0 +1,86 @@
+export type DatabaseData = Record<string, Array<Record<string, unknown>>>;
+export type DatabaseSchema = Record<string, unknown>;
+export type DatabaseConfig = {
+    data: DatabaseData;
+    path?: never;
+    schema?: DatabaseSchema | string;
+} | {
+    data?: never;
+    path: string;
+    schema?: DatabaseSchema | string;
+};
+export type MemoryFile = {
+    content: Uint8Array;
+    id: string;
+    mimeType: string;
+    name: string;
+};
+export type FilesConfig = {
+    data: MemoryFile[];
+    directory?: never;
+    metadata?: never;
+} | {
+    data?: never;
+    directory: string;
+    metadata: string;
+};
+export type DeepJsonServerConfig = {
+    /**
+     * Database source and optional schema.
+     */
+    database: DatabaseConfig;
+    /**
+     * Binary-file storage.
+     */
+    files?: FilesConfig;
+    /**
+     * Generated OpenAPI file.
+     */
+    openapi?: {
+        path?: string;
+    };
+    /**
+     * Runtime settings.
+     */
+    server?: {
+        host?: string;
+        logger?: boolean | Record<string, unknown>;
+        maxFileSize?: number;
+        maxPageSize?: number;
+        port?: number;
+    };
+};
+/**
+ * @param {DeepJsonServerConfig} config Server configuration.
+ * @param {string} [directoryPath] Base directory for relative paths.
+ * @returns {{ database: DatabaseConfig, files?: FilesConfig, openapi: { path?: string }, server: { host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number } }} Normalized configuration.
+ */
+export declare const normalizeServerConfig: (config: DeepJsonServerConfig, directoryPath?: string) => {
+    database: DatabaseConfig;
+    files?: FilesConfig;
+    openapi: {
+        path?: string;
+    };
+    server: {
+        host?: string;
+        logger?: boolean | Record<string, unknown>;
+        maxFileSize?: number;
+        maxPageSize?: number;
+        port?: number;
+    };
+};
+/** @param {string} configPath Configuration module path. */
+export declare function readServerConfig(configPath: string): Promise<{
+    database: DatabaseConfig;
+    files?: FilesConfig;
+    openapi: {
+        path?: string;
+    };
+    server: {
+        host?: string;
+        logger?: boolean | Record<string, unknown>;
+        maxFileSize?: number;
+        maxPageSize?: number;
+        port?: number;
+    };
+}>;

package/types/src/database.d.ts

@@ -1,8 +1,11 @@
 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>;
+/**
+ * @param {import('./config.js').DatabaseConfig} config Database source.
+ * @returns {Promise<any>} Internal database store.
+ */
+export declare const createDatabaseStore: (config: import('./config.js').DatabaseConfig) => 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

@@ -1,5 +1,24 @@
-export declare const registerFileRoutes: (server: any, { directoryPath, maxFileSize, metadataPath }: {
-    directoryPath: any;
+/** @param {import('./config.js').FilesConfig} config File storage configuration. */
+export declare const createFileStore: (config: import('./config.js').FilesConfig) => Promise<{
+    get: (id: any) => Promise<void>;
+    remove: (id: any) => Promise<void>;
+    upload: ({ maxFileSize, mimeType, name, stream }: {
+        maxFileSize: any;
+        mimeType: any;
+        name: any;
+        stream: any;
+    }) => Promise<void>;
+} | {
+    get: (id: any) => Promise<void>;
+    remove: (id: any) => Promise<void>;
+    upload: ({ maxFileSize, mimeType, name, stream }: {
+        maxFileSize: any;
+        mimeType: any;
+        name: any;
+        stream: any;
+    }) => Promise<void>;
+}>;
+export declare const registerFileRoutes: (server: any, { maxFileSize, store }: {
     maxFileSize: any;
-    metadataPath: any;
-}) => Promise<void>;
+    store: any;
+}) => void;

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

@@ -1,3 +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>;
+export declare const resolveSchemaConfig: (schema: any) => Promise<any>;

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

@@ -1,12 +1,11 @@
 /**
- * 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 3.0 document from resolved server data.
+ * @param {{ database: Record<string, Array<Record<string, unknown>>>, files?: boolean, maxPageSize?: number, schema?: Record<string, unknown> }} options Document options.
  * @returns {Record<string, unknown>} OpenAPI document.
  */
-export declare function createOpenApiDocument(database: Record<string, Array<Record<string, unknown>>>, schemaConfig?: Record<string, unknown>, { files, host, port }?: {
+export declare function buildOpenapiDocument(options: {
+    database: Record<string, Array<Record<string, unknown>>>;
     files?: boolean;
-    host?: string;
-    port?: number;
+    maxPageSize?: number;
+    schema?: Record<string, unknown>;
 }): Record<string, unknown>;

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

@@ -1,14 +1,9 @@
-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>>;
+export declare const createOpenapi: ({ database, files, host, maxPageSize, port, schema }: {
+    database: any;
+    files: any;
+    host?: string | undefined;
+    maxPageSize: any;
+    port?: number | undefined;
+    schema: any;
+}) => Record<string, unknown>;
+export declare const writeOpenapi: (document: any, outputPath: any) => Promise<void>;

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

@@ -4,10 +4,5 @@ export declare const parsePagination: (query: any, maxPageSize?: number) => {
 };
 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;
+    total: any;
 };

package/types/src/server.d.ts

@@ -1,30 +1,13 @@
+export type OpenapiDocument = Record<string, unknown>;
 /**
- * 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.
+ * Creates a Deep JSON Server facade.
+ * @param {import('./config.js').DeepJsonServerConfig} options Server options.
+ * @param {{ files?: boolean }} [features] Optional feature switches.
+ * @returns {Promise<{ fastify: () => import('fastify').FastifyInstance, openapi: () => Promise<OpenapiDocument> }>} Server facade.
  */
-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>;
+export declare function createServer(options: import('./config.js').DeepJsonServerConfig, features?: {
+    files?: boolean;
+}): Promise<{
+    fastify: () => import('fastify').FastifyInstance;
+    openapi: () => Promise<OpenapiDocument>;
+}>;