@kollors/deep-json-server 0.6.0 → 0.7.0

package/src/openapi/document.js

@@ -1,4 +1,4 @@
-import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../constants.js';
+import { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE } from '../constants.js';
 import { validateDatabase } from '../database.js';
 import { getRelationMetadata } from '../relation-metadata.js';
 import { getResourceNames, isObject, singularize, toPascalCase } from '../utils.js';
@@ -85,8 +85,11 @@ const addReverseRelations = (schemas, rawSchemas, resources, componentNames) =>
 };
 
 const createParameters = (maxPageSize) => ({
-  ContentName: { description: 'URI-encoded relative file name', in: 'header', name: 'Content-Name', required: true, schema: { type: 'string' } },
+  ContentDirectory: { description: 'URI-encoded relative storage directory', in: 'header', name: 'Content-Directory', schema: { type: 'string' } },
+  ContentName: { description: 'URI-encoded file name', in: 'header', name: 'Content-Name', required: true, schema: { type: 'string' } },
+  ContentOverride: { description: 'Overwrite an existing file at the same path', in: 'header', name: 'Content-Override', schema: { default: false, type: 'boolean' } },
   Embed: { description: 'Relationship paths to embed', explode: true, in: 'query', name: '_embed', schema: { items: { type: 'string' }, type: 'array' }, style: 'form' },
+  FilePath: { allowReserved: true, description: 'URI-encoded file path relative to the storage directory', in: 'path', name: 'path', required: true, schema: { type: 'string' } },
   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: maxPageSize, minimum: 1, type: 'integer' } },
@@ -100,52 +103,110 @@ const createParameterReference = (name) => ({ $ref: `#/components/parameters/${n
 const createRequestBody = (name) => ({ required: true, ...createJsonContent(createSchemaReference(name)) });
 
 const createFilePaths = () => ({
-  '/_files': {
+  '/_files/download/{path}': {
+    get: {
+      operationId: 'downloadFile',
+      parameters: [createParameterReference('FilePath')],
+      responses: {
+        200: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, description: 'File download' },
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+  },
+  '/_files/metadata/{path}': {
+    get: {
+      operationId: 'getFileMetadata',
+      parameters: [createParameterReference('FilePath')],
+      responses: {
+        200: createResponse('File metadata', createSchemaReference('FileMetadata')),
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+  },
+  '/_files/storage': {
     post: {
       operationId: 'uploadFile',
-      parameters: [createParameterReference('ContentName')],
+      parameters: ['ContentName', 'ContentDirectory', 'ContentOverride'].map(createParameterReference),
       requestBody: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, required: true },
       responses: {
-        201: createResponse('Uploaded', createSchemaReference('UploadedFile')),
+        200: createResponse('Overwritten', createSchemaReference('FileMetadata')),
+        201: createResponse('Created', createSchemaReference('FileMetadata')),
         400: createResponse('Invalid request', createSchemaReference('Error')),
+        409: createResponse('Already exists', createSchemaReference('Error')),
         413: createResponse('File is too large', createSchemaReference('Error')),
         415: createResponse('Unsupported media type', createSchemaReference('Error')),
       },
       tags: ['files'],
     },
   },
-  '/_files/{id}': {
+  '/_files/storage/{path}': {
     delete: {
-      operationId: 'deleteFileById',
-      parameters: [createParameterReference('Id')],
-      responses: { 200: createResponse('Deleted', createSchemaReference('UploadedFile')), 404: createResponse('Not found', createSchemaReference('Error')) },
+      operationId: 'deleteFile',
+      parameters: [createParameterReference('FilePath')],
+      responses: {
+        204: { description: 'Deleted' },
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
       tags: ['files'],
     },
     get: {
-      operationId: 'getFileById',
-      parameters: [createParameterReference('Id')],
+      operationId: 'getFileContent',
+      parameters: [createParameterReference('FilePath')],
       responses: {
         200: { content: { 'application/octet-stream': { schema: { format: 'binary', type: 'string' } } }, description: 'File contents' },
+        400: createResponse('Invalid path', createSchemaReference('Error')),
+        404: createResponse('Not found', createSchemaReference('Error')),
+      },
+      tags: ['files'],
+    },
+    patch: {
+      operationId: 'updateFile',
+      parameters: [createParameterReference('FilePath')],
+      requestBody: createRequestBody('FileUpdate'),
+      responses: {
+        200: createResponse('Updated', createSchemaReference('FileMetadata')),
+        400: createResponse('Invalid request', createSchemaReference('Error')),
         404: createResponse('Not found', createSchemaReference('Error')),
+        409: createResponse('Already exists', createSchemaReference('Error')),
+        413: createResponse('Request is too large', createSchemaReference('Error')),
+        415: createResponse('Unsupported media type', createSchemaReference('Error')),
       },
       tags: ['files'],
     },
   },
 });
 
-const createResourcePaths = (resource, componentName) => {
+const createResourceOperationIds = (resource) => {
   const resourceName = toPascalCase(resource);
 
+  return {
+    create: `post${resourceName}`,
+    get: `get${resourceName}ById`,
+    list: `get${resourceName}`,
+    remove: `delete${resourceName}ById`,
+    replace: `put${resourceName}ById`,
+    update: `patch${resourceName}ById`,
+  };
+};
+
+const createResourcePaths = (resource, componentName) => {
+  const operationIds = createResourceOperationIds(resource);
+
   return {
     [`/${resource}`]: {
       get: {
-        operationId: `get${resourceName}`,
+        operationId: operationIds.list,
         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}`,
+        operationId: operationIds.create,
         requestBody: createRequestBody(`${componentName}Create`),
         responses: { 201: createResponse('Created', createSchemaReference(componentName)), 400: createResponse('Invalid request', createSchemaReference('Error')) },
         tags: [resource],
@@ -153,13 +214,13 @@ const createResourcePaths = (resource, componentName) => {
     },
     [`/${resource}/{id}`]: {
       delete: {
-        operationId: `delete${resourceName}ById`,
+        operationId: operationIds.remove,
         parameters: [createParameterReference('Id')],
         responses: { 200: createResponse('Deleted', createSchemaReference(componentName)), 404: createResponse('Not found', createSchemaReference('Error')) },
         tags: [resource],
       },
       get: {
-        operationId: `get${resourceName}ById`,
+        operationId: operationIds.get,
         parameters: [createParameterReference('Id'), createParameterReference('Embed')],
         responses: {
           200: createResponse('Successful response', createSchemaReference(componentName)),
@@ -169,7 +230,7 @@ const createResourcePaths = (resource, componentName) => {
         tags: [resource],
       },
       patch: {
-        operationId: `patch${resourceName}ById`,
+        operationId: operationIds.update,
         parameters: [createParameterReference('Id')],
         requestBody: createRequestBody(`${componentName}Update`),
         responses: {
@@ -180,7 +241,7 @@ const createResourcePaths = (resource, componentName) => {
         tags: [resource],
       },
       put: {
-        operationId: `put${resourceName}ById`,
+        operationId: operationIds.replace,
         parameters: [createParameterReference('Id')],
         requestBody: createRequestBody(`${componentName}Create`),
         responses: {
@@ -194,14 +255,16 @@ const createResourcePaths = (resource, componentName) => {
   };
 };
 
-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 schemaOwners = new Map([
+    ['Error', 'встроенная схема ошибки'],
+    ...(files
+      ? [
+          ['FileMetadata', 'встроенная схема метаданных файла'],
+          ['FileUpdate', 'встроенная схема изменения файла'],
+        ]
+      : []),
+  ]);
   const operationOwners = new Map();
 
   resources.forEach((resource) => {
@@ -221,7 +284,7 @@ const validateGeneratedNames = (resources, componentNames, files) => {
       schemaOwners.set(schemaName, resource);
     });
 
-    getOperationIds(resource).forEach((operationId) => {
+    Object.values(createResourceOperationIds(resource)).forEach((operationId) => {
       const owner = operationOwners.get(operationId);
 
       if (owner != null) {
@@ -234,12 +297,12 @@ const validateGeneratedNames = (resources, componentNames, files) => {
 };
 
 /**
- * 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.
+ * Builds an OpenAPI document without runtime server addresses.
+ * @param {{ database: Record<string, Array<Record<string, unknown>>>, files?: boolean, maxPageSize?: number, schema?: Record<string, unknown> }} options Source data and schema settings.
  * @returns {Record<string, unknown>} OpenAPI document.
  */
 export function buildOpenapiDocument(options) {
-  const { database, files = false, maxPageSize = MAX_PAGE_SIZE, schema: schemaConfig = {} } = options ?? {};
+  const { database, files = false, maxPageSize = DEFAULT_MAX_PAGE_SIZE, schema: schemaConfig = {} } = options ?? {};
 
   if (typeof files !== 'boolean') {
     throw new Error('Ключ files должен содержать boolean');
@@ -280,9 +343,23 @@ export function buildOpenapiDocument(options) {
   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'],
+      FileMetadata: {
+        properties: {
+          directory: { type: 'string' },
+          downloadUrl: { type: 'string' },
+          metadataUrl: { type: 'string' },
+          mimeType: { type: 'string' },
+          name: { type: 'string' },
+          size: { minimum: 0, type: 'integer' },
+          url: { type: 'string' },
+        },
+        required: ['directory', 'downloadUrl', 'metadataUrl', 'mimeType', 'name', 'size', 'url'],
+        type: 'object',
+      },
+      FileUpdate: {
+        additionalProperties: false,
+        anyOf: [{ required: ['directory'] }, { required: ['name'] }],
+        properties: { directory: { type: 'string' }, name: { type: 'string' } },
         type: 'object',
       },
     }),

package/src/query/filter.js

@@ -10,12 +10,21 @@ const isFilterEqual = (left, right) => {
   }
 
   if (typeof left === 'number' && typeof right === 'string' && NUMBER_PATTERN.test(right)) {
+    // Query parameters are strings, so numeric strings must match stored numbers.
     return left === Number(right);
   }
 
   return typeof right === 'number' && typeof left === 'string' && NUMBER_PATTERN.test(left) && right === Number(left);
 };
 
+const validateLogicalConditions = (operator, value) => {
+  if (!Array.isArray(value) || (operator === 'or' && value.length === 0) || value.some((condition) => !isObject(condition))) {
+    throw createHttpError(400, `Оператор «${operator}» должен содержать ${operator === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
+  }
+
+  return value;
+};
+
 const matchesOperator = (field, operator, expectedValue) => {
   switch (operator) {
     case 'contains':
@@ -191,11 +200,7 @@ const validateCondition = (condition, samples, path) => {
 
   Object.entries(condition).forEach(([key, value]) => {
     if (key === 'and' || key === 'or') {
-      if (!Array.isArray(value) || (key === 'or' && value.length === 0) || value.some((nestedWhere) => !isObject(nestedWhere))) {
-        throw createHttpError(400, `Оператор «${key}» должен содержать ${key === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
-      }
-
-      value.forEach((nestedWhere) => {
+      validateLogicalConditions(key, value).forEach((nestedWhere) => {
         validateWhere(nestedWhere, samples, path);
       });
       return;
@@ -246,11 +251,7 @@ const validateCondition = (condition, samples, path) => {
 export const validateWhere = (where, items, path = '') => {
   Object.entries(where).forEach(([key, condition]) => {
     if (key === 'and' || key === 'or') {
-      if (!Array.isArray(condition) || (key === 'or' && condition.length === 0) || condition.some((nestedWhere) => !isObject(nestedWhere))) {
-        throw createHttpError(400, `Оператор «${key}» должен содержать ${key === 'or' ? 'непустой ' : ''}массив JSON-объектов`);
-      }
-
-      condition.forEach((nestedWhere) => {
+      validateLogicalConditions(key, condition).forEach((nestedWhere) => {
         validateWhere(nestedWhere, items, path);
       });
       return;

package/src/query/pagination.js

@@ -1,4 +1,4 @@
-import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../constants.js';
+import { DEFAULT_MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE } from '../constants.js';
 import { createHttpError } from '../utils.js';
 
 const parsePositiveInteger = (value, name, defaultValue) => {
@@ -19,7 +19,7 @@ const parsePositiveInteger = (value, name, defaultValue) => {
   return number;
 };
 
-export const parsePagination = (query, maxPageSize = MAX_PAGE_SIZE) => {
+export const parsePagination = (query, maxPageSize = DEFAULT_MAX_PAGE_SIZE) => {
   const page = parsePositiveInteger(query._page, '_page', 1);
   const pageSize = parsePositiveInteger(query._perPage, '_perPage', DEFAULT_PAGE_SIZE);
 

package/src/relation-metadata.js

@@ -15,6 +15,7 @@ export const resolveRelationResource = (resourceNames, relation, sourceResource)
 };
 
 export const getRelationMetadata = (key, resourceNames, sourceResource) => {
+  // Relation fields follow the <resource>Id and <resource>Ids conventions.
   const match = key.match(/^(.+)(Id|Ids)$/);
 
   if (match == null) {

package/src/server.js

@@ -1,6 +1,6 @@
 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 { DEFAULT_HOST, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_PAGE_SIZE, DEFAULT_PORT } from './constants.js';
 import { createDatabaseStore, createId, findItem, getCollection } from './database.js';
 import { createFileStore, registerFileRoutes } from './files.js';
 import { resolveSchemaConfig } from './openapi/config.js';
@@ -11,14 +11,15 @@ import { embedItem, parseEmbedPaths, validateEmbedPaths } from './relations.js';
 import { createHttpError, getResourceNames, isObject } from './utils.js';
 
 /** @typedef {Record<string, unknown>} OpenapiDocument */
+/** @typedef {{ fastify: () => import('fastify').FastifyInstance, openapi: () => Promise<OpenapiDocument> }} ServerFacade */
 
 const CORS_HEADERS = {
-  'Access-Control-Allow-Headers': 'Content-Name, Content-Type',
+  'Access-Control-Allow-Headers': 'Content-Directory, Content-Name, Content-Override, Content-Type',
   'Access-Control-Allow-Methods': 'DELETE, GET, OPTIONS, PATCH, POST, PUT',
   'Access-Control-Allow-Origin': '*',
 };
 
-const getRequestBody = (body) => {
+const getJsonObjectBody = (body) => {
   if (!isObject(body)) {
     throw createHttpError(400, 'Тело запроса должно быть JSON-объектом');
   }
@@ -28,7 +29,7 @@ const getRequestBody = (body) => {
 
 const getSchemaName = (reference) => reference.split('/').at(-1);
 
-const addRequestSchemas = (server, document, resources) => {
+const addRequestSchemas = (fastify, document, resources) => {
   const requestSchemaNames = new Set(
     resources.flatMap((resource) => {
       const resourcePath = document.paths[`/${resource}`];
@@ -39,17 +40,17 @@ const addRequestSchemas = (server, document, resources) => {
   );
 
   requestSchemaNames.forEach((schemaName) => {
-    server.addSchema({ $id: schemaName, ...document.components.schemas[schemaName] });
+    fastify.addSchema({ $id: schemaName, ...document.components.schemas[schemaName] });
   });
 };
 
-const registerResourceRoutes = (server, store, resource, document, maxPageSize) => {
+const registerResourceRoutes = (fastify, 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(resourcePath, async (request) => {
+  fastify.get(resourcePath, async (request) => {
     const collection = getCollection(store.database, resource);
     const where = parseWhere(request.query);
     const embedPaths = parseEmbedPaths(request.query._embed);
@@ -68,7 +69,7 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
     return paginateItems(sortedItems, pagination.page, pagination.pageSize);
   });
 
-  server.get(itemPath, async (request) => {
+  fastify.get(itemPath, async (request) => {
     const collection = getCollection(store.database, resource);
     const item = findItem(collection, request.params.id);
     const embedPaths = parseEmbedPaths(request.query._embed);
@@ -82,10 +83,10 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
     return embedItem(store.database, item, resource, embedPaths);
   });
 
-  server.post(resourcePath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request, reply) => {
+  fastify.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) };
+      const createdItem = { ...getJsonObjectBody(request.body), id: createId(collection) };
 
       collection.push(createdItem);
 
@@ -95,7 +96,7 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
     return reply.code(201).send(item);
   });
 
-  server.put(itemPath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request) =>
+  fastify.put(itemPath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request) =>
     store.update((database) => {
       const collection = getCollection(database, resource);
       const currentItem = findItem(collection, request.params.id);
@@ -104,7 +105,7 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
         throw createHttpError(404, 'Запись не найдена');
       }
 
-      const item = { ...getRequestBody(request.body), id: currentItem.id };
+      const item = { ...getJsonObjectBody(request.body), id: currentItem.id };
 
       collection.splice(collection.indexOf(currentItem), 1, item);
 
@@ -112,7 +113,7 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
     }),
   );
 
-  server.patch(itemPath, { schema: { body: { $ref: `${updateSchemaName}#` } } }, async (request) =>
+  fastify.patch(itemPath, { schema: { body: { $ref: `${updateSchemaName}#` } } }, async (request) =>
     store.update((database) => {
       const collection = getCollection(database, resource);
       const currentItem = findItem(collection, request.params.id);
@@ -121,7 +122,7 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
         throw createHttpError(404, 'Запись не найдена');
       }
 
-      const item = { ...currentItem, ...getRequestBody(request.body), id: currentItem.id };
+      const item = { ...currentItem, ...getJsonObjectBody(request.body), id: currentItem.id };
 
       collection.splice(collection.indexOf(currentItem), 1, item);
 
@@ -129,7 +130,7 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
     }),
   );
 
-  server.delete(itemPath, async (request) =>
+  fastify.delete(itemPath, async (request) =>
     store.update((database) => {
       const collection = getCollection(database, resource);
       const currentItem = findItem(collection, request.params.id);
@@ -146,21 +147,21 @@ const registerResourceRoutes = (server, store, resource, document, maxPageSize)
 };
 
 /**
- * Creates a Deep JSON Server facade.
- * @param {import('./config.js').DeepJsonServerConfig} options Server options.
+ * Creates lazy Fastify and OpenAPI accessors from one configuration.
+ * @param {import('./config.js').DeepJsonServerConfig} config Server configuration.
  * @param {{ files?: boolean }} [features] Optional feature switches.
- * @returns {Promise<{ fastify: () => import('fastify').FastifyInstance, openapi: () => Promise<OpenapiDocument> }>} Server facade.
+ * @returns {Promise<ServerFacade>} Server facade.
  */
-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;
+export async function createServer(config, features = {}) {
+  const normalizedConfig = normalizeServerConfig(config);
+  const filesEnabled = features.files ?? normalizedConfig.files != null;
+  const { logger = true, maxFileSize = DEFAULT_MAX_FILE_SIZE, maxPageSize = DEFAULT_MAX_PAGE_SIZE } = normalizedConfig.server;
+  const store = await createDatabaseStore(normalizedConfig.database);
+  const schema = await resolveSchemaConfig(normalizedConfig.database.schema);
+  const fileStore = filesEnabled && normalizedConfig.files != null ? await createFileStore(normalizedConfig.files) : undefined;
   let fastifyInstance;
 
-  if (filesEnabled && config.files == null) {
+  if (filesEnabled && normalizedConfig.files == null) {
     throw new Error('Для файловых маршрутов укажите секцию config.files');
   }
 
@@ -172,45 +173,46 @@ export async function createServer(options, features = {}) {
       schema,
     });
 
-  const fastify = () => {
+  const getFastify = () => {
     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 fastify = Fastify({ logger });
+    const originalListen = fastify.listen.bind(fastify);
 
-    server.listen = (...args) => listen(...(args.length === 0 ? [{ host: config.server.host ?? DEFAULT_HOST, port: config.server.port ?? DEFAULT_PORT }] : args));
+    // Calling fastify().listen() without arguments uses config defaults.
+    fastify.listen = (...args) => originalListen(...(args.length === 0 ? [{ host: normalizedConfig.server.host ?? DEFAULT_HOST, port: normalizedConfig.server.port ?? DEFAULT_PORT }] : args));
 
-    addRequestSchemas(server, document, resources);
+    addRequestSchemas(fastify, document, resources);
 
-    server.addHook('onRequest', async (_request, reply) => {
+    fastify.addHook('onRequest', async (_request, reply) => {
       Object.entries(CORS_HEADERS).forEach(([header, value]) => {
         reply.header(header, value);
       });
     });
 
-    server.addHook('preHandler', async (request) => {
+    fastify.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 }));
+    fastify.options('/', async (_request, reply) => reply.code(204).send());
+    fastify.options('/*', async (_request, reply) => reply.code(204).send());
+    fastify.get('/', async () => ({ resources }));
 
     resources.forEach((resource) => {
-      registerResourceRoutes(server, store, resource, document, maxPageSize);
+      registerResourceRoutes(fastify, store, resource, document, maxPageSize);
     });
 
     if (fileStore != null) {
-      registerFileRoutes(server, { maxFileSize, store: fileStore });
+      registerFileRoutes(fastify, { maxFileSize, store: fileStore });
     }
 
-    server.setErrorHandler((error, request, reply) => {
+    fastify.setErrorHandler((error, request, reply) => {
       const statusCode = Number.isInteger(error.statusCode) ? error.statusCode : 500;
 
       if (statusCode === 500) {
@@ -220,7 +222,7 @@ export async function createServer(options, features = {}) {
       return reply.code(statusCode).send({ error: error.message });
     });
 
-    fastifyInstance = server;
+    fastifyInstance = fastify;
 
     return fastifyInstance;
   };
@@ -231,18 +233,18 @@ export async function createServer(options, features = {}) {
     const document = createOpenapi({
       database: store.database.data,
       files: filesEnabled,
-      host: config.server.host,
+      host: normalizedConfig.server.host,
       maxPageSize,
-      port: config.server.port,
+      port: normalizedConfig.server.port,
       schema,
     });
 
-    if (config.openapi.path != null) {
-      await writeOpenapi(document, config.openapi.path);
+    if (normalizedConfig.openapi.path != null) {
+      await writeOpenapi(document, normalizedConfig.openapi.path);
     }
 
     return document;
   };
 
-  return { fastify, openapi };
+  return { fastify: getFastify, openapi };
 }

package/src/utils.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import { resolve } from 'node:path';
 import pluralize from 'pluralize';
 
@@ -11,6 +12,35 @@ export const createHttpError = (statusCode, message) => {
   return error;
 };
 
+/** @returns {<T>(operation: () => T | Promise<T>) => Promise<T>} Serialized operation scheduler. */
+export const createSerialQueue = () => {
+  let queue = Promise.resolve();
+
+  return (operation) => {
+    const pendingOperation = queue.then(operation);
+
+    // Keep the queue usable after a failed operation.
+    queue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+};
+
+/**
+ * Creates a random ID that is not currently in use.
+ * @param {(id: string) => boolean} isUsed Checks whether an ID already exists.
+ * @returns {string} Unique ID.
+ */
+export const createUniqueId = (isUsed) => {
+  let id;
+
+  do {
+    id = randomBytes(8).toString('base64url');
+  } while (isUsed(id));
+
+  return id;
+};
+
 export const getResourceNames = (data) => Object.keys(data);
 export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 export const isSafeKey = (key) => !UNSAFE_KEYS.has(key);

package/types/index.d.ts

@@ -2,10 +2,20 @@
 /** @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 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 OpenapiConfig = import('./src/config.js').OpenapiConfig;
+export type ServerConfig = import('./src/config.js').ServerConfig;
+export type FileMetadata = import('./src/files.js').FileMetadata;
+export type FileUpdate = import('./src/files.js').FileUpdate;
 export type OpenapiDocument = import('./src/server.js').OpenapiDocument;
+export type ServerFacade = import('./src/server.js').ServerFacade;
 export { createServer } from './src/server.js';