@kollors/deep-json-server 0.7.0 → 0.8.0

package/src/relations.js

@@ -1,173 +0,0 @@
-import { getRelationKeys, resolveRelationResource } from './relation-metadata.js';
-import { createHttpError, getResourceNames, isIdEqual, isObject, isSafeKey, singularize, toArray } from './utils.js';
-
-const findLocalRelation = (item, relation, targetResource) => {
-  const relationKey = getRelationKeys(relation, singularize(relation), targetResource, singularize(targetResource)).find((key) => Object.hasOwn(item, key));
-
-  if (relationKey == null) {
-    return undefined;
-  }
-
-  return { ids: toArray(item[relationKey]).filter((id) => id != null), isMany: relationKey.endsWith('Ids') || Array.isArray(item[relationKey]) };
-};
-
-const hasReference = (value, relationKeys, id) => {
-  if (Array.isArray(value)) {
-    return value.some((item) => hasReference(item, relationKeys, id));
-  }
-
-  if (!isObject(value)) {
-    return false;
-  }
-
-  return Object.entries(value).some(([key, nestedValue]) => {
-    if (!isSafeKey(key)) {
-      return false;
-    }
-
-    if (relationKeys.includes(key)) {
-      return toArray(nestedValue).some((nestedId) => isIdEqual(nestedId, id));
-    }
-
-    return hasReference(nestedValue, relationKeys, id);
-  });
-};
-
-const getResourceIndex = (database, resource, indexes) => {
-  if (!indexes.has(resource)) {
-    const index = new Map();
-
-    database.data[resource].forEach((item) => {
-      if (isObject(item) && item.id != null && !index.has(item.id)) {
-        index.set(String(item.id), item);
-      }
-    });
-
-    indexes.set(resource, index);
-  }
-
-  return indexes.get(resource);
-};
-
-const findRelatedValue = (database, item, sourceResource, relation, targetResource, indexes) => {
-  const targetItems = database.data[targetResource];
-  const localRelation = findLocalRelation(item, relation, targetResource);
-
-  if (!Array.isArray(targetItems)) {
-    return undefined;
-  }
-
-  if (localRelation != null) {
-    const targetIndex = getResourceIndex(database, targetResource, indexes);
-    const relatedItems = localRelation.ids.map((id) => targetIndex.get(String(id))).filter((targetItem) => targetItem != null);
-
-    return localRelation.isMany ? relatedItems : (relatedItems[0] ?? null);
-  }
-
-  if (item.id == null) {
-    return undefined;
-  }
-
-  const reverseRelationKeys = getRelationKeys(singularize(sourceResource));
-
-  if (relation === 'child' || relation === 'children') {
-    reverseRelationKeys.push('parentId', 'parentIds');
-  }
-
-  return targetItems.filter((targetItem) => hasReference(targetItem, reverseRelationKeys, item.id));
-};
-
-const embedPath = (database, item, sourceResource, [relation, ...nestedRelations], indexes) => {
-  if (relation == null || !isSafeKey(relation)) {
-    return item;
-  }
-
-  const currentValue = item[relation];
-  const targetResource = resolveRelationResource(getResourceNames(database.data), relation, sourceResource);
-  const nestedSourceResource = targetResource ?? relation;
-  const localRelation = targetResource == null ? undefined : findLocalRelation(item, relation, targetResource);
-
-  if (localRelation == null) {
-    if (Array.isArray(currentValue)) {
-      return nestedRelations.length === 0
-        ? item
-        : { ...item, [relation]: currentValue.map((value) => (isObject(value) ? embedPath(database, value, nestedSourceResource, nestedRelations, indexes) : value)) };
-    }
-
-    if (isObject(currentValue)) {
-      return nestedRelations.length === 0 ? item : { ...item, [relation]: embedPath(database, currentValue, nestedSourceResource, nestedRelations, indexes) };
-    }
-  }
-
-  if (targetResource == null) {
-    return item;
-  }
-
-  const relatedValue = findRelatedValue(database, item, sourceResource, relation, targetResource, indexes);
-
-  if (relatedValue == null || nestedRelations.length === 0) {
-    return relatedValue === undefined ? item : { ...item, [relation]: relatedValue };
-  }
-
-  return {
-    ...item,
-    [relation]: Array.isArray(relatedValue)
-      ? relatedValue.map((value) => embedPath(database, value, targetResource, nestedRelations, indexes))
-      : embedPath(database, relatedValue, targetResource, nestedRelations, indexes),
-  };
-};
-
-export const parseEmbedPaths = (embed) => {
-  if (embed == null) {
-    return [];
-  }
-
-  const values = toArray(embed);
-
-  if (values.some((value) => typeof value !== 'string')) {
-    throw createHttpError(400, 'Параметр _embed должен содержать строковые пути связей');
-  }
-
-  return values
-    .flatMap((value) => value.split(','))
-    .map((path) => {
-      const keys = path.split('.');
-
-      if (keys.some((key) => key === '' || !isSafeKey(key))) {
-        throw createHttpError(400, `Недопустимый путь связи «${path}»`);
-      }
-
-      return keys;
-    });
-};
-
-const getNestedSamples = (samples, relation) =>
-  samples.flatMap((sample) => {
-    if (!isObject(sample) || !Object.hasOwn(sample, relation)) {
-      return [];
-    }
-
-    return toArray(sample[relation]).filter(isObject);
-  });
-
-const validateEmbedPath = (database, sourceResource, samples, [relation, ...nestedRelations], path = '') => {
-  const relationPath = path === '' ? relation : `${path}.${relation}`;
-  const targetResource = resolveRelationResource(getResourceNames(database.data), relation, sourceResource);
-  const nestedSamples = targetResource == null ? getNestedSamples(samples, relation) : database.data[targetResource];
-
-  if (targetResource == null && nestedSamples.length === 0) {
-    throw createHttpError(400, `Неизвестный путь связи «${relationPath}»`);
-  }
-
-  if (nestedRelations.length > 0) {
-    validateEmbedPath(database, targetResource ?? relation, nestedSamples, nestedRelations, relationPath);
-  }
-};
-
-export const validateEmbedPaths = (database, resource, items, embedPaths) => {
-  embedPaths.forEach((path) => {
-    validateEmbedPath(database, resource, items, path);
-  });
-};
-
-export const embedItem = (database, item, resource, embedPaths, indexes = new Map()) => embedPaths.reduce((embeddedItem, path) => embedPath(database, embeddedItem, resource, path, indexes), item);

package/src/server.js

@@ -1,250 +0,0 @@
-import Fastify from 'fastify';
-import { normalizeServerConfig } from './config.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';
-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 } 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-Directory, Content-Name, Content-Override, Content-Type',
-  'Access-Control-Allow-Methods': 'DELETE, GET, OPTIONS, PATCH, POST, PUT',
-  'Access-Control-Allow-Origin': '*',
-};
-
-const getJsonObjectBody = (body) => {
-  if (!isObject(body)) {
-    throw createHttpError(400, 'Тело запроса должно быть JSON-объектом');
-  }
-
-  return body;
-};
-
-const getSchemaName = (reference) => reference.split('/').at(-1);
-
-const addRequestSchemas = (fastify, document, resources) => {
-  const requestSchemaNames = new Set(
-    resources.flatMap((resource) => {
-      const resourcePath = document.paths[`/${resource}`];
-      const itemPath = document.paths[`/${resource}/{id}`];
-
-      return [getSchemaName(resourcePath.post.requestBody.content['application/json'].schema.$ref), getSchemaName(itemPath.patch.requestBody.content['application/json'].schema.$ref)];
-    }),
-  );
-
-  requestSchemaNames.forEach((schemaName) => {
-    fastify.addSchema({ $id: schemaName, ...document.components.schemas[schemaName] });
-  });
-};
-
-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);
-
-  fastify.get(resourcePath, async (request) => {
-    const collection = getCollection(store.database, resource);
-    const where = parseWhere(request.query);
-    const embedPaths = parseEmbedPaths(request.query._embed);
-    const pagination = parsePagination(request.query, maxPageSize);
-
-    validateEmbedPaths(store.database, resource, collection, embedPaths);
-
-    const relationIndexes = new Map();
-    const embeddedItems = collection.map((item) => embedItem(store.database, item, resource, embedPaths, relationIndexes));
-
-    validateWhere(where, embeddedItems);
-
-    const filteredItems = embeddedItems.filter((item) => matchesWhere(item, where));
-    const sortedItems = sortItems(filteredItems, request.query._sort, embeddedItems);
-
-    return paginateItems(sortedItems, pagination.page, pagination.pageSize);
-  });
-
-  fastify.get(itemPath, async (request) => {
-    const collection = getCollection(store.database, resource);
-    const item = findItem(collection, request.params.id);
-    const embedPaths = parseEmbedPaths(request.query._embed);
-
-    if (item == null) {
-      throw createHttpError(404, 'Запись не найдена');
-    }
-
-    validateEmbedPaths(store.database, resource, collection, embedPaths);
-
-    return embedItem(store.database, item, resource, embedPaths);
-  });
-
-  fastify.post(resourcePath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request, reply) => {
-    const item = await store.update((database) => {
-      const collection = getCollection(database, resource);
-      const createdItem = { ...getJsonObjectBody(request.body), id: createId(collection) };
-
-      collection.push(createdItem);
-
-      return createdItem;
-    });
-
-    return reply.code(201).send(item);
-  });
-
-  fastify.put(itemPath, { schema: { body: { $ref: `${createSchemaName}#` } } }, async (request) =>
-    store.update((database) => {
-      const collection = getCollection(database, resource);
-      const currentItem = findItem(collection, request.params.id);
-
-      if (currentItem == null) {
-        throw createHttpError(404, 'Запись не найдена');
-      }
-
-      const item = { ...getJsonObjectBody(request.body), id: currentItem.id };
-
-      collection.splice(collection.indexOf(currentItem), 1, item);
-
-      return item;
-    }),
-  );
-
-  fastify.patch(itemPath, { schema: { body: { $ref: `${updateSchemaName}#` } } }, async (request) =>
-    store.update((database) => {
-      const collection = getCollection(database, resource);
-      const currentItem = findItem(collection, request.params.id);
-
-      if (currentItem == null) {
-        throw createHttpError(404, 'Запись не найдена');
-      }
-
-      const item = { ...currentItem, ...getJsonObjectBody(request.body), id: currentItem.id };
-
-      collection.splice(collection.indexOf(currentItem), 1, item);
-
-      return item;
-    }),
-  );
-
-  fastify.delete(itemPath, async (request) =>
-    store.update((database) => {
-      const collection = getCollection(database, resource);
-      const currentItem = findItem(collection, request.params.id);
-
-      if (currentItem == null) {
-        throw createHttpError(404, 'Запись не найдена');
-      }
-
-      collection.splice(collection.indexOf(currentItem), 1);
-
-      return currentItem;
-    }),
-  );
-};
-
-/**
- * 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<ServerFacade>} Server facade.
- */
-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 && normalizedConfig.files == null) {
-    throw new Error('Для файловых маршрутов укажите секцию config.files');
-  }
-
-  const buildDocument = () =>
-    buildOpenapiDocument({
-      database: store.database.data,
-      files: filesEnabled,
-      maxPageSize,
-      schema,
-    });
-
-  const getFastify = () => {
-    if (fastifyInstance != null) {
-      return fastifyInstance;
-    }
-
-    const document = buildDocument();
-    const resources = getResourceNames(store.database.data);
-    const fastify = Fastify({ logger });
-    const originalListen = fastify.listen.bind(fastify);
-
-    // 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(fastify, document, resources);
-
-    fastify.addHook('onRequest', async (_request, reply) => {
-      Object.entries(CORS_HEADERS).forEach(([header, value]) => {
-        reply.header(header, value);
-      });
-    });
-
-    fastify.addHook('preHandler', async (request) => {
-      if (request.method === 'GET') {
-        await store.read();
-      }
-    });
-
-    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(fastify, store, resource, document, maxPageSize);
-    });
-
-    if (fileStore != null) {
-      registerFileRoutes(fastify, { maxFileSize, store: fileStore });
-    }
-
-    fastify.setErrorHandler((error, request, reply) => {
-      const statusCode = Number.isInteger(error.statusCode) ? error.statusCode : 500;
-
-      if (statusCode === 500) {
-        request.log.error(error);
-      }
-
-      return reply.code(statusCode).send({ error: error.message });
-    });
-
-    fastifyInstance = fastify;
-
-    return fastifyInstance;
-  };
-
-  const openapi = async () => {
-    await store.read();
-
-    const document = createOpenapi({
-      database: store.database.data,
-      files: filesEnabled,
-      host: normalizedConfig.server.host,
-      maxPageSize,
-      port: normalizedConfig.server.port,
-      schema,
-    });
-
-    if (normalizedConfig.openapi.path != null) {
-      await writeOpenapi(document, normalizedConfig.openapi.path);
-    }
-
-    return document;
-  };
-
-  return { fastify: getFastify, openapi };
-}

package/src/utils.js

@@ -1,84 +0,0 @@
-import { randomBytes } from 'node:crypto';
-import { resolve } from 'node:path';
-import pluralize from 'pluralize';
-
-const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
-
-export const createHttpError = (statusCode, message) => {
-  const error = new Error(message);
-
-  error.statusCode = statusCode;
-
-  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);
-export const toArray = (value) => (Array.isArray(value) ? value : [value]);
-
-export const isEqual = (left, right) => {
-  if (Object.is(left, right)) {
-    return true;
-  }
-
-  if (Array.isArray(left) && Array.isArray(right)) {
-    return left.length === right.length && left.every((value, index) => isEqual(value, right[index]));
-  }
-
-  if (isObject(left) && isObject(right)) {
-    const leftKeys = Object.keys(left);
-    const rightKeys = Object.keys(right);
-
-    return leftKeys.length === rightKeys.length && leftKeys.every((key) => isSafeKey(key) && Object.hasOwn(right, key) && isEqual(left[key], right[key]));
-  }
-
-  return false;
-};
-
-export const resolveDatabasePath = (databasePath) => {
-  if (typeof databasePath !== 'string' || databasePath === '') {
-    throw new Error('Укажите путь к JSON-базе данных');
-  }
-
-  return resolve(databasePath);
-};
-
-export const isIdEqual = (left, right) => left != null && right != null && String(left) === String(right);
-export const singularize = (value) => pluralize.singular(value);
-
-export const toPascalCase = (value) =>
-  value
-    .split(/[^a-zA-Z0-9]+/)
-    .filter(Boolean)
-    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
-    .join('');

package/types/index.d.ts

@@ -1,21 +0,0 @@
-/** @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/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';

package/types/src/config.d.ts

@@ -1,73 +0,0 @@
-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;
-    directory?: string;
-    mimeType: string;
-    name: string;
-};
-export type FilesConfig = {
-    data: MemoryFile[];
-    directory?: never;
-    metadata?: never;
-} | {
-    data?: never;
-    directory: string;
-    metadata: string;
-};
-export type OpenapiConfig = {
-    path?: string;
-};
-export type ServerConfig = {
-    host?: string;
-    logger?: boolean | Record<string, unknown>;
-    maxFileSize?: number;
-    maxPageSize?: number;
-    port?: number;
-};
-export type DeepJsonServerConfig = {
-    /**
-     * Database source and optional schema.
-     */
-    database: DatabaseConfig;
-    /**
-     * Binary-file storage.
-     */
-    files?: FilesConfig;
-    /**
-     * Generated OpenAPI file.
-     */
-    openapi?: OpenapiConfig;
-    /**
-     * Runtime settings.
-     */
-    server?: ServerConfig;
-};
-export type NormalizedServerConfig = {
-    database: DatabaseConfig;
-    files?: FilesConfig;
-    openapi: OpenapiConfig;
-    server: ServerConfig;
-};
-/**
- * Validates configuration and resolves relative paths.
- * @param {DeepJsonServerConfig} config Server configuration.
- * @param {string} [directoryPath] Base directory for relative paths.
- * @returns {NormalizedServerConfig} Normalized configuration.
- */
-export declare const normalizeServerConfig: (config: DeepJsonServerConfig, directoryPath?: string) => NormalizedServerConfig;
-/**
- * Loads an ES module config and resolves paths from its directory.
- * @param {string} configPath Configuration module path.
- * @returns {Promise<NormalizedServerConfig>} Normalized configuration.
- */
-export declare function readServerConfig(configPath: string): Promise<NormalizedServerConfig>;

package/types/src/database.d.ts

@@ -1,33 +0,0 @@
-export type DatabaseContainer = {
-    data: import('./config.js').DatabaseData;
-};
-export type DatabaseStore = {
-    /**
-     * Current database container.
-     */
-    database: DatabaseContainer;
-    /**
-     * Resolved database file path.
-     */
-    path?: string;
-    /**
-     * Returns current data and reloads disk-backed sources.
-     */
-    read: () => Promise<import('./config.js').DatabaseData>;
-    /**
-     * Runs a serialized update.
-     */
-    update: <T>(operation: (database: DatabaseContainer) => T) => Promise<T>;
-};
-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>;
-/**
- * Creates a disk- or memory-backed database with serialized updates.
- * @param {import('./config.js').DatabaseConfig} config Database source.
- * @returns {Promise<DatabaseStore>} Database store.
- */
-export declare const createDatabaseStore: (config: import('./config.js').DatabaseConfig) => Promise<DatabaseStore>;
-export declare const getCollection: (database: any, resource: any) => any[];
-export declare const findItem: (collection: any, id: any) => any;
-export declare const createId: (collection: any) => string;