@kollors/deep-json-server 0.4.0 → 0.6.0

package/src/files.js

@@ -0,0 +1,368 @@
+import { randomBytes } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { access, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createHttpError, isObject } from './utils.js';
+
+const createFileId = (files) => {
+  let id;
+
+  do {
+    id = randomBytes(8).toString('base64url');
+  } while (files.some((file) => file.id === id));
+
+  return id;
+};
+
+const validateFileMetadata = (files, metadataPath) => {
+  if (!Array.isArray(files)) {
+    throw new Error(`Файл метаданных ${metadataPath} должен содержать JSON-массив`);
+  }
+
+  const ids = new Set();
+
+  files.forEach((file, index) => {
+    if (
+      !isObject(file) ||
+      typeof file.id !== 'string' ||
+      file.id === '' ||
+      typeof file.mimeType !== 'string' ||
+      file.mimeType === '' ||
+      typeof file.name !== 'string' ||
+      file.name === '' ||
+      !Number.isInteger(file.size) ||
+      file.size < 0 ||
+      file.url !== `/_files/${file.id}`
+    ) {
+      throw new Error(`Некорректная запись ${index} в файле метаданных ${metadataPath}`);
+    }
+
+    if (ids.has(file.id)) {
+      throw new Error(`Файл метаданных ${metadataPath} содержит повторяющийся id «${file.id}»`);
+    }
+
+    ids.add(file.id);
+  });
+
+  return files;
+};
+
+const readMetadata = async (metadataPath) => {
+  try {
+    return validateFileMetadata(JSON.parse(await readFile(metadataPath, 'utf8')), metadataPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return [];
+    }
+
+    throw error;
+  }
+};
+
+const writeMetadata = async (metadataPath, files) => {
+  const temporaryPath = `${metadataPath}.${randomBytes(6).toString('hex')}.tmp`;
+
+  try {
+    await writeFile(temporaryPath, JSON.stringify(files, null, 2), { encoding: 'utf8', flag: 'wx' });
+    await rename(temporaryPath, metadataPath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true });
+    throw error;
+  }
+};
+
+const getContentName = (value) => {
+  if (typeof value !== 'string' || value === '') {
+    throw createHttpError(400, 'Заголовок Content-Name обязателен');
+  }
+
+  let name;
+
+  try {
+    name = decodeURIComponent(value).replaceAll('\\', '/');
+  } catch {
+    throw createHttpError(400, 'Заголовок Content-Name содержит некорректное значение');
+  }
+
+  const parts = name.split('/');
+
+  if (name.startsWith('/') || parts.some((part) => part === '' || part === '.' || part === '..' || part.includes('\0'))) {
+    throw createHttpError(400, 'Заголовок Content-Name должен содержать безопасный относительный путь');
+  }
+
+  return name;
+};
+
+const getMimeType = (value) => {
+  const mimeType = typeof value === 'string' ? value.split(';', 1)[0].trim().toLowerCase() : '';
+
+  if (mimeType === '' || !/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/.test(mimeType)) {
+    throw createHttpError(400, 'Заголовок Content-Type должен содержать корректный MIME-тип');
+  }
+
+  return mimeType;
+};
+
+const createSizeLimiter = (maxFileSize, onSize) => {
+  let size = 0;
+
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      size += chunk.length;
+
+      if (size > maxFileSize) {
+        callback(createHttpError(413, `Размер файла не должен превышать ${maxFileSize} байт`));
+        return;
+      }
+
+      onSize(size);
+      callback(null, chunk);
+    },
+  });
+};
+
+const createDiskFileStore = async ({ directory: sourceDirectoryPath, metadata: sourceMetadataPath }) => {
+  if (typeof sourceDirectoryPath !== 'string' || sourceDirectoryPath.trim() === '') {
+    throw new Error('Путь к директории файлов не должен быть пустым');
+  }
+
+  if (typeof sourceMetadataPath !== 'string' || sourceMetadataPath.trim() === '') {
+    throw new Error('Путь к файлу метаданных не должен быть пустым');
+  }
+
+  const directoryPath = resolve(sourceDirectoryPath);
+  const metadataPath = resolve(sourceMetadataPath);
+  let operationQueue = Promise.resolve();
+
+  await Promise.all([mkdir(directoryPath, { recursive: true }), mkdir(dirname(metadataPath), { recursive: true })]);
+  await readMetadata(metadataPath);
+
+  const schedule = (operation) => {
+    const pendingOperation = operationQueue.then(operation);
+
+    operationQueue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+
+  const get = (id) =>
+    schedule(async () => {
+      const files = await readMetadata(metadataPath);
+      const file = files.find((item) => item.id === id);
+
+      if (file == null) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      const path = join(directoryPath, file.id);
+
+      try {
+        await access(path);
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          throw createHttpError(404, 'Файл не найден');
+        }
+
+        throw error;
+      }
+
+      return { file, stream: createReadStream(path) };
+    });
+
+  const upload = ({ maxFileSize, mimeType, name, stream }) =>
+    schedule(async () => {
+      const files = await readMetadata(metadataPath);
+      const id = createFileId(files);
+      const path = join(directoryPath, id);
+      const temporaryPath = `${path}.upload`;
+      let size = 0;
+
+      try {
+        await pipeline(
+          stream,
+          createSizeLimiter(maxFileSize, (value) => (size = value)),
+          createWriteStream(temporaryPath, { flags: 'wx' }),
+        );
+        await rename(temporaryPath, path);
+
+        const file = { id, mimeType, name, size, url: `/_files/${id}` };
+
+        files.push(file);
+        await writeMetadata(metadataPath, files);
+
+        return file;
+      } catch (error) {
+        await Promise.all([rm(temporaryPath, { force: true }), rm(path, { force: true })]);
+        throw error;
+      }
+    });
+
+  const remove = (id) =>
+    schedule(async () => {
+      const files = await readMetadata(metadataPath);
+      const index = files.findIndex((file) => file.id === id);
+
+      if (index === -1) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      const [file] = files.splice(index, 1);
+      const path = join(directoryPath, file.id);
+      const temporaryPath = `${path}.${randomBytes(6).toString('hex')}.delete`;
+
+      try {
+        await rename(path, temporaryPath);
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          throw createHttpError(404, 'Файл не найден');
+        }
+
+        throw error;
+      }
+
+      try {
+        await writeMetadata(metadataPath, files);
+      } catch (error) {
+        await rename(temporaryPath, path);
+        throw error;
+      }
+
+      await rm(temporaryPath, { force: true }).catch(() => undefined);
+
+      return file;
+    });
+
+  return { get, remove, upload };
+};
+
+const createMemoryFileStore = (sourceFiles) => {
+  const ids = new Set();
+  const storedFiles = sourceFiles.map((sourceFile, index) => {
+    if (
+      !isObject(sourceFile) ||
+      typeof sourceFile.id !== 'string' ||
+      sourceFile.id === '' ||
+      typeof sourceFile.mimeType !== 'string' ||
+      sourceFile.mimeType === '' ||
+      typeof sourceFile.name !== 'string' ||
+      sourceFile.name === '' ||
+      !(sourceFile.content instanceof Uint8Array)
+    ) {
+      throw new Error(`Некорректная запись ${index} в config.files.data`);
+    }
+
+    if (ids.has(sourceFile.id)) {
+      throw new Error(`config.files.data содержит повторяющийся id «${sourceFile.id}»`);
+    }
+
+    ids.add(sourceFile.id);
+
+    const content = Buffer.from(sourceFile.content);
+
+    return {
+      content,
+      file: { id: sourceFile.id, mimeType: sourceFile.mimeType, name: sourceFile.name, size: content.length, url: `/_files/${sourceFile.id}` },
+    };
+  });
+  let operationQueue = Promise.resolve();
+
+  const schedule = (operation) => {
+    const pendingOperation = operationQueue.then(operation);
+
+    operationQueue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+
+  const get = (id) =>
+    schedule(async () => {
+      const storedFile = storedFiles.find(({ file }) => file.id === id);
+
+      if (storedFile == null) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      return { file: storedFile.file, stream: Readable.from([storedFile.content]) };
+    });
+
+  const upload = ({ maxFileSize, mimeType, name, stream }) =>
+    schedule(async () => {
+      const chunks = [];
+      let size = 0;
+
+      for await (const chunk of stream) {
+        const buffer = Buffer.from(chunk);
+
+        size += buffer.length;
+
+        if (size > maxFileSize) {
+          throw createHttpError(413, `Размер файла не должен превышать ${maxFileSize} байт`);
+        }
+
+        chunks.push(buffer);
+      }
+
+      const id = createFileId(storedFiles.map(({ file }) => file));
+      const file = { id, mimeType, name, size, url: `/_files/${id}` };
+
+      storedFiles.push({ content: Buffer.concat(chunks), file });
+
+      return file;
+    });
+
+  const remove = (id) =>
+    schedule(async () => {
+      const index = storedFiles.findIndex(({ file }) => file.id === id);
+
+      if (index === -1) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      return storedFiles.splice(index, 1)[0].file;
+    });
+
+  return { get, remove, upload };
+};
+
+/** @param {import('./config.js').FilesConfig} config File storage configuration. */
+export const createFileStore = async (config) => ('data' in config ? createMemoryFileStore(config.data) : createDiskFileStore(config));
+
+const getDownloadName = (name) => encodeURIComponent(basename(name)).replaceAll("'", '%27');
+
+export const registerFileRoutes = (server, { maxFileSize, store }) => {
+  server.register((fileServer, _options, done) => {
+    fileServer.removeAllContentTypeParsers();
+    fileServer.addContentTypeParser('*', (_request, payload, parserDone) => parserDone(null, payload));
+
+    fileServer.post('/_files', async (request, reply) => {
+      const contentLength = Number(request.headers['content-length']);
+
+      if (Number.isFinite(contentLength) && contentLength > maxFileSize) {
+        throw createHttpError(413, `Размер файла не должен превышать ${maxFileSize} байт`);
+      }
+
+      const file = await store.upload({
+        maxFileSize,
+        mimeType: getMimeType(request.headers['content-type']),
+        name: getContentName(request.headers['content-name']),
+        stream: request.body,
+      });
+
+      return reply.code(201).send(file);
+    });
+
+    fileServer.get('/_files/:id', async (request, reply) => {
+      const { file, stream } = await store.get(request.params.id);
+
+      reply.header('Content-Disposition', `inline; filename*=UTF-8''${getDownloadName(file.name)}`);
+      reply.type(file.mimeType);
+
+      return reply.send(stream);
+    });
+
+    fileServer.delete('/_files/:id', async (request) => store.remove(request.params.id));
+    done();
+  });
+};

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_PAGE_SIZE, 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) => {
@@ -100,11 +84,12 @@ const addReverseRelations = (schemas, rawSchemas, resources, componentNames) =>
   });
 };
 
-const createParameters = () => ({
+const createParameters = (maxPageSize) => ({
+  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' } },
+  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' } },
 });
@@ -114,6 +99,40 @@ const createResponse = (description, schema) => ({ description, ...(schema != nu
 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);
 
@@ -181,8 +200,8 @@ const getOperationIds = (resource) => {
   return [`get${resourceName}`, `post${resourceName}`, `delete${resourceName}ById`, `get${resourceName}ById`, `patch${resourceName}ById`, `put${resourceName}ById`];
 };
 
-const validateGeneratedNames = (resources, componentNames) => {
-  const schemaOwners = new Map([['Error', 'встроенная схема ошибки']]);
+const validateGeneratedNames = (resources, componentNames, files) => {
+  const schemaOwners = new Map([['Error', 'встроенная схема ошибки'], ...(files ? [['UploadedFile', 'встроенная схема файла']] : [])]);
   const operationOwners = new Map();
 
   resources.forEach((resource) => {
@@ -215,15 +234,23 @@ const validateGeneratedNames = (resources, componentNames) => {
 };
 
 /**
- * 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 {{ host?: string, port?: number }} [serverOptions] Server address 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 function createOpenApiDocument(database, schemaConfig = {}, { host = DEFAULT_HOST, port = DEFAULT_PORT } = {}) {
+export function buildOpenapiDocument(options) {
+  const { database, files = false, maxPageSize = 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-объект');
   }
@@ -239,7 +266,7 @@ export function createOpenApiDocument(database, schemaConfig = {}, { host = DEFA
     }),
   );
 
-  validateGeneratedNames(resources, componentNames);
+  validateGeneratedNames(resources, componentNames, files);
 
   const rawSchemas = Object.fromEntries(
     resources.map((resource) => {
@@ -250,7 +277,16 @@ export function createOpenApiDocument(database, schemaConfig = {}, { host = DEFA
       return [resource, applyConfiguredFields(ensureGeneratedIdSchema(configuredSchema), resource, resourceConfig)];
     }),
   );
-  const schemas = { Error: { properties: { error: { type: 'string' } }, required: ['error'], type: 'object' } };
+  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];
@@ -262,14 +298,9 @@ export function createOpenApiDocument(database, schemaConfig = {}, { host = DEFA
     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',
     };
   });
@@ -277,11 +308,10 @@ export function createOpenApiDocument(database, schemaConfig = {}, { host = DEFA
   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]))),
-    servers: [{ url: getServerUrl(host, port) }],
-    tags: resources.map((resource) => ({ name: resource })),
+    paths: Object.assign({}, ...resources.map((resource) => createResourcePaths(resource, componentNames[resource])), files ? createFilePaths() : {}),
+    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, host?: string, outputPath: string, port?: number, schemaPath: string }} options Generation options.
- * @returns {Promise<Record<string, unknown>>} Generated OpenAPI document.
- */
-export async function generateOpenApi({ databasePath, host, outputPath, port, schemaPath }) {
-  const database = await readDatabaseFile(databasePath);
-  const schemaConfig = await readSchemaConfig(schemaPath);
-  const document = createOpenApiDocument(database, schemaConfig, { 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,
   };
 };