@kollors/deep-json-server 0.6.0 → 0.7.0

package/README.md

@@ -110,7 +110,7 @@ export default {
     schema: { $info: { title: 'Movie API', version: '1.0.0' } },
   },
   files: {
-    data: [{ content: new Uint8Array([1, 2, 3]), id: 'file-1', mimeType: 'application/octet-stream', name: 'example.bin' }],
+    data: [{ content: new Uint8Array([1, 2, 3]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
   },
 };
 ```
@@ -352,33 +352,62 @@ Add `files.directory` and `files.metadata` to the server config, then pass `--fi
 deep-json-server --files server.config.js
 ```
 
-For temporary tests, use `files.data` instead. Each initial record contains `id`, `name`, `mimeType`, and binary `content` as a `Uint8Array`; `size` and `url` are derived automatically. Uploaded files then remain in memory until the process exits.
+For temporary tests, use `files.data` instead. Each initial record contains `name`, `mimeType`, binary `content` as a `Uint8Array`, and an optional `directory`. Uploaded files then remain in memory until the process exits.
 
-Upload one file as the request body. Both headers are required: `Content-Name` contains the relative logical name encoded with `encodeURIComponent`, and `Content-Type` contains the file MIME type:
+Upload one file directly as the request body. `Content-Name` contains the URI-encoded file name, `Content-Type` contains its MIME type, and the optional `Content-Directory` contains the URI-encoded relative directory:
 
 ```http
-POST /_files
-Content-Name: posters%2Fshadows-of-ardenia.jpg
+POST /_files/storage
+Content-Name: shadows-of-ardenia.jpg
+Content-Directory: posters
 Content-Type: image/jpeg
 
 <binary body>
 ```
 
-A successful upload returns status `201`, metadata, and a stable URL:
+A new file returns status `201` and its computed metadata:
 
 ```json
 {
-  "id": "generated-id",
+  "directory": "posters",
+  "downloadUrl": "/_files/download/posters/shadows-of-ardenia.jpg",
+  "metadataUrl": "/_files/metadata/posters/shadows-of-ardenia.jpg",
   "mimeType": "image/jpeg",
-  "name": "posters/shadows-of-ardenia.jpg",
+  "name": "shadows-of-ardenia.jpg",
   "size": 182340,
-  "url": "/_files/generated-id"
+  "url": "/_files/storage/posters/shadows-of-ardenia.jpg"
 }
 ```
 
-`GET /_files/:id` returns the original bytes with status `200`. `DELETE /_files/:id` removes both the binary contents and metadata, and returns the deleted metadata with status `200`. The returned `url` is relative to the mock-server origin. The server creates the configured directories automatically, stores binary contents under generated IDs without relying on the original file name, and keeps the logical names and other metadata in `files.metadata`. The metadata file may be absent initially and is created on the first upload. Do not edit it while the server is running.
+The combination of `directory` and `name` identifies a file. Uploading to an existing path returns `409`. Pass `Content-Override: true` to replace it; a successful replacement returns `200`. The server supports these file routes:
 
-The upload is raw binary rather than `multipart/form-data`, so `XMLHttpRequest.upload.onprogress` can report progress while the browser sends a `File` directly with `xhr.send(file)`. The default maximum size is 100 MiB and can be changed through `server.maxFileSize`. A missing or unsafe `Content-Name` returns `400`, an exceeded limit returns `413`, and a missing, malformed, or Fastify-unsupported `Content-Type` returns `400` or `415`, depending on which validation stage rejects it.
+```text
+POST   /_files/storage      Upload or replace a file
+GET    /_files/storage/*    Return file contents inline
+PATCH  /_files/storage/*    Rename or move a file
+DELETE /_files/storage/*    Delete a file
+
+GET    /_files/metadata/*   Return file metadata as JSON
+GET    /_files/download/*   Download a file as an attachment
+```
+
+Rename, move, or perform both operations with a JSON body. At least one field is required:
+
+```http
+PATCH /_files/storage/posters/shadows-of-ardenia.jpg
+Content-Type: application/json
+
+{
+  "directory": "archive/posters",
+  "name": "ardenia-shadows.jpg"
+}
+```
+
+`PATCH` returns the updated metadata with status `200`; a conflicting destination returns `409`. `DELETE` returns `204` without a response body. A missing file returns `404` on every path-based operation. File paths in URLs are relative to `files.directory`, and all returned URLs are relative to the mock-server origin.
+
+In disk mode, the binary is stored at `<files.directory>/<directory>/<name>`. The metadata file contains only `directory`, `mimeType`, and `name`; `size` is read from the actual file, while response URLs are computed. The server creates directories automatically. The metadata file may be absent initially and is created on the first upload. Do not edit stored files or metadata while the server is running. Metadata created by versions before this path-based API is not compatible with the new format.
+
+The upload is raw binary rather than `multipart/form-data`, so `XMLHttpRequest.upload.onprogress` can report progress while the browser sends a `File` directly with `xhr.send(file)`. The default maximum size is 100 MiB and can be changed through `server.maxFileSize`. Missing or unsafe headers and paths return `400`, an exceeded limit returns `413`, and a missing, malformed, or Fastify-unsupported `Content-Type` returns `400` or `415`, depending on which validation stage rejects it.
 
 ## Database schema and OpenAPI generation
 
@@ -522,7 +551,7 @@ const memoryServer = await createServer({
     schema: { $info: { title: 'Movie API', version: '1.0.0' } },
   },
   files: {
-    data: [{ content: new Uint8Array([1, 2, 3]), id: 'file-1', mimeType: 'application/octet-stream', name: 'example.bin' }],
+    data: [{ content: new Uint8Array([1, 2, 3]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
   },
 });
 

package/README.ru.md

@@ -110,7 +110,7 @@ export default {
     schema: { $info: { title: 'API фильмов', version: '1.0.0' } },
   },
   files: {
-    data: [{ content: new Uint8Array([1, 2, 3]), id: 'file-1', mimeType: 'application/octet-stream', name: 'example.bin' }],
+    data: [{ content: new Uint8Array([1, 2, 3]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
   },
 };
 ```
@@ -352,33 +352,62 @@ GET /countries/1?_embed=users
 deep-json-server --files server.config.js
 ```
 
-Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `id`, `name`, `mimeType` и бинарное `content` в виде `Uint8Array`; `size` и `url` вычисляются автоматически. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
+Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `name`, `mimeType`, бинарное `content` в виде `Uint8Array` и необязательный `directory`. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
 
-Один файл отправляется непосредственно в теле запроса. Оба заголовка обязательны: `Content-Name` содержит относительное логическое имя, закодированное через `encodeURIComponent`, а `Content-Type` — MIME-тип файла:
+Один файл отправляется непосредственно в теле запроса. `Content-Name` содержит URI-кодированное имя файла, `Content-Type` — его MIME-тип, а необязательный `Content-Directory` — URI-кодированный относительный путь к директории:
 
 ```http
-POST /_files
-Content-Name: posters%2Fshadows-of-ardenia.jpg
+POST /_files/storage
+Content-Name: shadows-of-ardenia.jpg
+Content-Directory: posters
 Content-Type: image/jpeg
 
 <binary body>
 ```
 
-Успешная загрузка возвращает статус `201`, метаданные и постоянный URL:
+Новый файл возвращает статус `201` и вычисленные метаданные:
 
 ```json
 {
-  "id": "generated-id",
+  "directory": "posters",
+  "downloadUrl": "/_files/download/posters/shadows-of-ardenia.jpg",
+  "metadataUrl": "/_files/metadata/posters/shadows-of-ardenia.jpg",
   "mimeType": "image/jpeg",
-  "name": "posters/shadows-of-ardenia.jpg",
+  "name": "shadows-of-ardenia.jpg",
   "size": 182340,
-  "url": "/_files/generated-id"
+  "url": "/_files/storage/posters/shadows-of-ardenia.jpg"
 }
 ```
 
-`GET /_files/:id` возвращает исходные байты со статусом `200`, а `DELETE /_files/:id` удаляет бинарное содержимое вместе с метаданными и возвращает удалённые метаданные со статусом `200`. Возвращаемый `url` задаётся относительно адреса mock-сервера. Сервер автоматически создаёт настроенные директории, хранит бинарное содержимое под сгенерированными ID без привязки к исходному имени и записывает логические имена и остальные метаданные в `files.metadata`. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Не редактируйте его во время работы сервера.
+Сочетание `directory` и `name` идентифицирует файл. Повторная загрузка по существующему пути возвращает `409`. Чтобы заменить файл, передайте `Content-Override: true`; успешная перезапись возвращает `200`. Сервер поддерживает следующие файловые маршруты:
 
-Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующий или небезопасный `Content-Name` возвращает `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
+```text
+POST   /_files/storage      Загрузка или перезапись файла
+GET    /_files/storage/*    Просмотр содержимого файла
+PATCH  /_files/storage/*    Переименование или перемещение файла
+DELETE /_files/storage/*    Удаление файла
+
+GET    /_files/metadata/*   Получение метаданных в JSON
+GET    /_files/download/*   Скачивание файла
+```
+
+Для переименования, перемещения либо обеих операций отправьте JSON-объект. Нужно указать хотя бы одно поле:
+
+```http
+PATCH /_files/storage/posters/shadows-of-ardenia.jpg
+Content-Type: application/json
+
+{
+  "directory": "archive/posters",
+  "name": "ardenia-shadows.jpg"
+}
+```
+
+`PATCH` возвращает обновлённые метаданные со статусом `200`; занятый конечный путь возвращает `409`. `DELETE` отвечает статусом `204` без тела. Если файл не найден, любая операция по пути возвращает `404`. Пути в URL задаются относительно `files.directory`, а все возвращаемые URL — относительно адреса mock-сервера.
+
+При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Файл метаданных содержит только `directory`, `mimeType` и `name`; `size` считывается у фактического файла, а URL вычисляются. Сервер автоматически создаёт директории. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Не редактируйте сохранённые файлы или метаданные во время работы сервера. Метаданные, созданные версиями до перехода на адресацию по пути, несовместимы с новым форматом.
+
+Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 
 ## Схема базы данных и генерация OpenAPI
 
@@ -522,7 +551,7 @@ const memoryServer = await createServer({
     schema: { $info: { title: 'API фильмов', version: '1.0.0' } },
   },
   files: {
-    data: [{ content: new Uint8Array([1, 2, 3]), id: 'file-1', mimeType: 'application/octet-stream', name: 'example.bin' }],
+    data: [{ content: new Uint8Array([1, 2, 3]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
   },
 });
 

package/index.js

@@ -2,6 +2,11 @@
 /** @typedef {import('./src/config.js').DatabaseConfig} DatabaseConfig */
 /** @typedef {import('./src/config.js').FilesConfig} FilesConfig */
 /** @typedef {import('./src/config.js').MemoryFile} MemoryFile */
+/** @typedef {import('./src/config.js').OpenapiConfig} OpenapiConfig */
+/** @typedef {import('./src/config.js').ServerConfig} ServerConfig */
+/** @typedef {import('./src/files.js').FileMetadata} FileMetadata */
+/** @typedef {import('./src/files.js').FileUpdate} FileUpdate */
 /** @typedef {import('./src/server.js').OpenapiDocument} OpenapiDocument */
+/** @typedef {import('./src/server.js').ServerFacade} ServerFacade */
 
 export { createServer } from './src/server.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kollors/deep-json-server",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "JSON mock server with deep filters and recursive relationship embedding",
   "type": "module",
   "types": "./types/index.d.ts",
@@ -52,11 +52,18 @@
   },
   "keywords": [
     "api",
+    "crud",
     "deep-filter",
+    "file-upload",
     "json",
+    "json-server",
     "mock",
+    "mock-api",
+    "mock-server",
+    "openapi",
     "relations",
-    "rest"
+    "rest",
+    "rest-api"
   ],
   "author": "kollors",
   "license": "MIT",

package/src/cli.js

@@ -73,10 +73,10 @@ export async function runCli(args = process.argv.slice(2), services = { createSe
   validateModeConfig(config, { files, openapiMode });
 
   const runtimeConfig = { ...config, server: { ...config.server, host, port } };
-  const server = await services.createServer(runtimeConfig, { files });
+  const serverFacade = await services.createServer(runtimeConfig, { files });
 
   if (openapiMode !== 'none') {
-    await server.openapi();
+    await serverFacade.openapi();
     process.stdout.write(`OpenAPI-схема сохранена в ${config.openapi.path}\n`);
   }
 
@@ -84,7 +84,7 @@ export async function runCli(args = process.argv.slice(2), services = { createSe
     return;
   }
 
-  const fastify = server.fastify();
+  const fastify = serverFacade.fastify();
 
   await fastify.listen({ host, port });
   fastify.log.info({ database: 'path' in config.database ? config.database.path : 'memory' }, 'Deep JSON Server запущен');

package/src/config.js

@@ -12,15 +12,18 @@ let configImportIndex = 0;
 /** @typedef {Record<string, Array<Record<string, unknown>>>} DatabaseData */
 /** @typedef {Record<string, unknown>} DatabaseSchema */
 /** @typedef {{ data: DatabaseData, path?: never, schema?: DatabaseSchema | string } | { data?: never, path: string, schema?: DatabaseSchema | string }} DatabaseConfig */
-/** @typedef {{ content: Uint8Array, id: string, mimeType: string, name: string }} MemoryFile */
+/** @typedef {{ content: Uint8Array, directory?: string, mimeType: string, name: string }} MemoryFile */
 /** @typedef {{ data: MemoryFile[], directory?: never, metadata?: never } | { data?: never, directory: string, metadata: string }} FilesConfig */
+/** @typedef {{ path?: string }} OpenapiConfig */
+/** @typedef {{ host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number }} ServerConfig */
 /**
  * @typedef {object} DeepJsonServerConfig
  * @property {DatabaseConfig} database Database source and optional schema.
  * @property {FilesConfig} [files] Binary-file storage.
- * @property {{ path?: string }} [openapi] Generated OpenAPI file.
- * @property {{ host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number }} [server] Runtime settings.
+ * @property {OpenapiConfig} [openapi] Generated OpenAPI file.
+ * @property {ServerConfig} [server] Runtime settings.
  */
+/** @typedef {{ database: DatabaseConfig, files?: FilesConfig, openapi: OpenapiConfig, server: ServerConfig }} NormalizedServerConfig */
 
 const assertKnownKeys = (value, keys, path) => {
   const unknownKey = Object.keys(value).find((key) => !keys.has(key));
@@ -120,9 +123,10 @@ const normalizeFiles = (value, directoryPath) => {
 };
 
 /**
+ * Validates configuration and resolves relative paths.
  * @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.
+ * @returns {NormalizedServerConfig} Normalized configuration.
  */
 export const normalizeServerConfig = (config, directoryPath = '.') => {
   if (!isObject(config)) {
@@ -172,7 +176,11 @@ export const normalizeServerConfig = (config, directoryPath = '.') => {
   };
 };
 
-/** @param {string} configPath Configuration module path. */
+/**
+ * Loads an ES module config and resolves paths from its directory.
+ * @param {string} configPath Configuration module path.
+ * @returns {Promise<NormalizedServerConfig>} Normalized configuration.
+ */
 export async function readServerConfig(configPath) {
   const resolvedConfigPath = resolve(getString(configPath, 'config', true));
   let config;
@@ -180,6 +188,7 @@ export async function readServerConfig(configPath) {
   try {
     const configUrl = pathToFileURL(resolvedConfigPath);
 
+    // Bypass the module cache so repeated reads use the latest config.
     configUrl.searchParams.set('deep-json-server-import', String(configImportIndex++));
     config = (await import(configUrl.href)).default;
   } catch (error) {

package/src/constants.js

@@ -1,5 +1,5 @@
 export const DEFAULT_HOST = '127.0.0.1';
 export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
+export const DEFAULT_MAX_PAGE_SIZE = 1000;
 export const DEFAULT_PAGE_SIZE = 10;
 export const DEFAULT_PORT = 4001;
-export const MAX_PAGE_SIZE = 1000;

package/src/database.js

@@ -1,8 +1,16 @@
-import { randomBytes } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { JSONFilePreset } from 'lowdb/node';
-import { createHttpError, isObject, isSafeKey, resolveDatabasePath } from './utils.js';
+import { createHttpError, createSerialQueue, createUniqueId, isObject, isSafeKey, resolveDatabasePath } from './utils.js';
+
+/** @typedef {{ data: import('./config.js').DatabaseData }} DatabaseContainer */
+/**
+ * @typedef {object} DatabaseStore
+ * @property {DatabaseContainer} database Current database container.
+ * @property {string} [path] Resolved database file path.
+ * @property {() => Promise<import('./config.js').DatabaseData>} read Returns current data and reloads disk-backed sources.
+ * @property {<T>(operation: (database: DatabaseContainer) => T) => Promise<T>} update Runs a serialized update.
+ */
 
 const RESOURCE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
 
@@ -76,7 +84,7 @@ const createDiskDatabaseStore = async (databasePath) => {
   const resolvedDatabasePath = resolveDatabasePath(databasePath);
   const initialData = await readDatabaseFile(resolvedDatabasePath);
   const database = await JSONFilePreset(resolvedDatabasePath, initialData);
-  let writeQueue = Promise.resolve();
+  const schedule = createSerialQueue();
 
   const read = async () => {
     database.data = await readDatabaseFile(resolvedDatabasePath);
@@ -84,8 +92,8 @@ const createDiskDatabaseStore = async (databasePath) => {
     return database.data;
   };
 
-  const update = (operation) => {
-    const pendingOperation = writeQueue.then(async () => {
+  const update = (operation) =>
+    schedule(async () => {
       await read();
 
       const result = operation(database);
@@ -96,21 +104,16 @@ const createDiskDatabaseStore = async (databasePath) => {
       return result;
     });
 
-    writeQueue = pendingOperation.catch(() => undefined);
-
-    return pendingOperation;
-  };
-
   return { database, path: resolvedDatabasePath, read, update };
 };
 
 const createMemoryDatabaseStore = (sourceData) => {
   const database = { data: validateDatabase(structuredClone(sourceData)) };
-  let updateQueue = Promise.resolve();
+  const schedule = createSerialQueue();
 
   const read = async () => database.data;
-  const update = (operation) => {
-    const pendingOperation = updateQueue.then(() => {
+  const update = (operation) =>
+    schedule(() => {
       const draft = { data: structuredClone(database.data) };
       const result = operation(draft);
 
@@ -120,17 +123,13 @@ const createMemoryDatabaseStore = (sourceData) => {
       return result;
     });
 
-    updateQueue = pendingOperation.catch(() => undefined);
-
-    return pendingOperation;
-  };
-
   return { database, read, update };
 };
 
 /**
+ * Creates a disk- or memory-backed database with serialized updates.
  * @param {import('./config.js').DatabaseConfig} config Database source.
- * @returns {Promise<any>} Internal database store.
+ * @returns {Promise<DatabaseStore>} Database store.
  */
 export const createDatabaseStore = async (config) => ('data' in config ? createMemoryDatabaseStore(config.data) : createDiskDatabaseStore(config.path));
 
@@ -146,12 +145,4 @@ export const getCollection = (database, resource) => {
 
 export const findItem = (collection, id) => collection.find((item) => String(item.id) === String(id));
 
-export const createId = (collection) => {
-  let id;
-
-  do {
-    id = randomBytes(8).toString('base64url');
-  } while (findItem(collection, id) != null);
-
-  return id;
-};
+export const createId = (collection) => createUniqueId((id) => findItem(collection, id) != null);