@kollors/deep-json-server 0.1.1 → 0.2.0

package/src/openapi.js

@@ -0,0 +1,258 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { stringify } from 'yaml';
+import { getResourceNames, isObject, singularize, toPascalCase } from './utils.js';
+
+const readJson = async(path, label) => {
+  const value = JSON.parse(await readFile(resolve(path), 'utf8'));
+
+  if (!isObject(value)) {
+    throw new Error(`${label} должен содержать JSON-объект`);
+  }
+
+  return value;
+};
+
+const mergeSchemas = (schemas) => {
+  const uniqueSchemas = [...new Map(schemas.map((schema) => [JSON.stringify(schema), schema])).values()];
+  const nullable = uniqueSchemas.some((schema) => schema.type === 'null');
+  const nonNullSchemas = uniqueSchemas.filter((schema) => schema.type !== 'null');
+
+  if (nonNullSchemas.length === 0) {
+    return { nullable: true };
+  }
+
+  if (nonNullSchemas.length === 1) {
+    return nullable ? { ...nonNullSchemas[0], nullable: true } : nonNullSchemas[0];
+  }
+
+  return { oneOf: nonNullSchemas, ...(nullable && { nullable: true }) };
+};
+
+const inferSchema = (values, path, options) => {
+  if (values.every(Array.isArray)) {
+    const items = values.flat();
+
+    return { items: items.length === 0 ? {} : inferSchema(items, path, options), type: 'array' };
+  }
+
+  if (values.every(isObject)) {
+    return inferObjectSchema(values, path, options);
+  }
+
+  const schemas = values.map((value) => {
+    if (value === null) {
+      return { type: 'null' };
+    }
+
+    if (typeof value === 'number') {
+      return { type: Number.isInteger(value) ? 'integer' : 'number' };
+    }
+
+    const schema = { type: typeof value };
+    const format = options.formats[path];
+
+    return typeof value === 'string' && format != null ? { ...schema, format } : schema;
+  });
+
+  return mergeSchemas(schemas);
+};
+
+function inferObjectSchema(values, path, options) {
+  const keys = [...new Set(values.flatMap((value) => Object.keys(value)))].sort((left, right) => left === 'id' ? -1 : right === 'id' ? 1 : left.localeCompare(right));
+  const properties = Object.fromEntries(keys.map((key) => {
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+    const fieldValues = values.filter((value) => Object.hasOwn(value, key)).map((value) => value[key]);
+
+    return [key, inferSchema(fieldValues, fieldPath, options)];
+  }));
+  const required = keys.filter((key) => {
+    const fieldPath = path === '' ? key : `${path}.${key}`;
+
+    return !options.optional.has(fieldPath) && values.every((value) => Object.hasOwn(value, key));
+  });
+
+  return { properties, type: 'object', ...(required.length > 0 && { required }) };
+}
+
+const resolveRelationResource = (resources, relation, sourceResource) => {
+  const resource = resources.find((resourceName) => resourceName === relation) ?? resources.find((resourceName) => singularize(resourceName) === relation);
+
+  if (resource != null) {
+    return resource;
+  }
+
+  return ['child', 'children', 'parent', 'parents'].includes(relation) ? sourceResource : undefined;
+};
+
+const addRelationSchemas = (schema, resources, componentNames, sourceResource) => {
+  if (schema.type === 'array') {
+    return { ...schema, items: addRelationSchemas(schema.items, resources, componentNames, sourceResource) };
+  }
+
+  if (schema.type !== 'object' || schema.properties == null) {
+    return schema;
+  }
+
+  const properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, addRelationSchemas(value, resources, componentNames, sourceResource)]));
+
+  Object.keys(schema.properties).forEach((key) => {
+    const match = key.match(/^(.+)(Id|Ids)$/);
+
+    if (match == null) {
+      return;
+    }
+
+    const [, relation, suffix] = match;
+    const targetResource = resolveRelationResource(resources, suffix === 'Ids' ? `${relation}s` : relation, sourceResource);
+
+    if (targetResource == null) {
+      return;
+    }
+
+    const relationName = suffix === 'Ids' ? `${relation}s` : relation;
+    const reference = { $ref: `#/components/schemas/${componentNames[targetResource]}` };
+
+    properties[relationName] = suffix === 'Ids' ? { items: reference, type: 'array' } : reference;
+  });
+
+  return { ...schema, properties };
+};
+
+const omitId = (schema, keepRequired) => {
+  const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).filter(([key]) => key !== 'id'));
+  const required = keepRequired ? schema.required?.filter((key) => key !== 'id') : undefined;
+
+  const result = { ...schema, properties };
+
+  delete result.required;
+
+  return required?.length > 0 ? { ...result, required } : result;
+};
+
+const createParameters = () => ({
+  Embed: { description: 'Comma-separated relationship paths to embed', in: 'query', name: '_embed', schema: { type: 'string' } },
+  Id: { in: 'path', name: 'id', required: true, schema: { type: 'string' } },
+  Page: { in: 'query', name: '_page', schema: { minimum: 1, type: 'integer' } },
+  PerPage: { in: 'query', name: '_per_page', schema: { 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' } },
+});
+
+const jsonContent = (schema) => ({ content: { 'application/json': { schema } } });
+const response = (description, schema) => ({ description, ...(schema != null && jsonContent(schema)) });
+const reference = (name) => ({ $ref: `#/components/schemas/${name}` });
+const parameter = (name) => ({ $ref: `#/components/parameters/${name}` });
+
+const createResourcePaths = (resource, componentName) => {
+  const tag = componentName;
+  const listSchema = { oneOf: [{ items: reference(componentName), type: 'array' }, reference(`${componentName}Page`)] };
+  const body = (name) => ({ required: true, ...jsonContent(reference(name)) });
+
+  return {
+    [`/${resource}`]: {
+      get: {
+        operationId: `get${toPascalCase(resource)}`,
+        parameters: ['Page', 'PerPage', 'Sort', 'Where', 'Embed'].map(parameter),
+        responses: { 200: response('Successful response', listSchema), 400: response('Invalid query', reference('Error')) },
+        tags: [tag],
+      },
+      post: {
+        operationId: `create${componentName}`,
+        requestBody: body(`${componentName}Create`),
+        responses: { 201: response('Created', reference(componentName)), 400: response('Invalid request', reference('Error')) },
+        tags: [tag],
+      },
+    },
+    [`/${resource}/{id}`]: {
+      delete: {
+        operationId: `delete${componentName}`,
+        parameters: [parameter('Id')],
+        responses: { 200: response('Deleted', reference(componentName)), 404: response('Not found', reference('Error')) },
+        tags: [tag],
+      },
+      get: {
+        operationId: `get${componentName}ById`,
+        parameters: [parameter('Id'), parameter('Embed')],
+        responses: { 200: response('Successful response', reference(componentName)), 404: response('Not found', reference('Error')) },
+        tags: [tag],
+      },
+      patch: {
+        operationId: `update${componentName}`,
+        parameters: [parameter('Id')],
+        requestBody: body(`${componentName}Update`),
+        responses: { 200: response('Updated', reference(componentName)), 404: response('Not found', reference('Error')) },
+        tags: [tag],
+      },
+      put: {
+        operationId: `replace${componentName}`,
+        parameters: [parameter('Id')],
+        requestBody: body(`${componentName}Create`),
+        responses: { 200: response('Replaced', reference(componentName)), 404: response('Not found', reference('Error')) },
+        tags: [tag],
+      },
+    },
+  };
+};
+
+export function createOpenApiDocument(database, schemaConfig = {}) {
+  if (!isObject(database) || !isObject(schemaConfig)) {
+    throw new Error('База данных и её схема должны содержать JSON-объекты');
+  }
+
+  const resources = getResourceNames(database);
+  const componentNames = Object.fromEntries(resources.map((resource) => [resource, toPascalCase(singularize(resource))]));
+  const schemas = {
+    Error: { properties: { error: { type: 'string' } }, required: ['error'], type: 'object' },
+  };
+
+  resources.forEach((resource) => {
+    const componentName = componentNames[resource];
+    const resourceConfig = isObject(schemaConfig[resource]) ? schemaConfig[resource] : {};
+    const options = {
+      formats: isObject(resourceConfig.formats) ? resourceConfig.formats : {},
+      optional: new Set(Array.isArray(resourceConfig.optional) ? resourceConfig.optional : []),
+    };
+    const values = database[resource].filter(isObject);
+    const rawSchema = values.length === 0 ? { additionalProperties: true, type: 'object' } : inferObjectSchema(values, '', options);
+    const responseSchema = addRelationSchemas(rawSchema, resources, componentNames, resource);
+
+    schemas[componentName] = responseSchema;
+    schemas[`${componentName}Create`] = omitId(rawSchema, true);
+    schemas[`${componentName}Update`] = omitId(rawSchema, false);
+    schemas[`${componentName}Page`] = {
+      properties: {
+        data: { items: reference(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' },
+      },
+      required: ['data', 'first', 'items', 'last', 'next', 'pages', 'prev'],
+      type: 'object',
+    };
+  });
+
+  return {
+    components: { parameters: createParameters(), 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: Array.isArray(schemaConfig.$servers) ? schemaConfig.$servers : [{ url: 'http://127.0.0.1:4001' }],
+    tags: resources.map((resource) => ({ name: componentNames[resource] })),
+  };
+}
+
+export async function generateOpenApi({ databasePath, outputPath, schemaPath }) {
+  const database = await readJson(databasePath, 'База данных');
+  const schemaConfig = await readJson(schemaPath, 'Схема базы данных');
+  const document = createOpenApiDocument(database, schemaConfig);
+  const resolvedOutputPath = resolve(outputPath);
+
+  await mkdir(dirname(resolvedOutputPath), { recursive: true });
+  await writeFile(resolvedOutputPath, stringify(document, { lineWidth: 0 }), 'utf8');
+
+  return document;
+}

package/src/query.js

@@ -0,0 +1,233 @@
+import { createHttpError, isEqual, isObject, isSafeKey, toArray } from './utils.js';
+
+const FIELD_OPERATORS = new Set(['contains', 'endsWith', 'eq', 'every', 'gt', 'gte', 'in', 'lt', 'lte', 'ne', 'none', 'not', 'some', 'startsWith']);
+const RESERVED_QUERY_KEYS = new Set(['_embed', '_page', '_per_page', '_sort', '_where']);
+
+const compareValues = (left, right) => {
+  if (Object.is(left, right)) {
+    return 0;
+  }
+
+  if (left == null) {
+    return 1;
+  }
+
+  if (right == null) {
+    return -1;
+  }
+
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left - right;
+  }
+
+  return String(left).localeCompare(String(right), undefined, { numeric: true, sensitivity: 'base' });
+};
+
+const getValueByPath = (value, path) => path.split('.').reduce((currentValue, key) => {
+  return isSafeKey(key) && currentValue != null ? currentValue[key] : undefined;
+}, value);
+
+const matchesOperator = (field, operator, expectedValue) => {
+  switch (operator) {
+    case 'contains':
+      return typeof field === 'string'
+        ? field.toLowerCase().includes(String(expectedValue).toLowerCase())
+        : Array.isArray(field) && field.some((value) => isEqual(value, expectedValue));
+    case 'endsWith':
+      return typeof field === 'string' && field.toLowerCase().endsWith(String(expectedValue).toLowerCase());
+    case 'eq':
+      return isEqual(field, expectedValue);
+    case 'every':
+      return Array.isArray(field) && field.every((value) => matchesValue(value, expectedValue));
+    case 'gt':
+      return field != null && field > expectedValue;
+    case 'gte':
+      return field != null && field >= expectedValue;
+    case 'in': {
+      const expectedValues = toArray(expectedValue);
+
+      return Array.isArray(field)
+        ? field.some((value) => expectedValues.some((expectedItem) => isEqual(value, expectedItem)))
+        : expectedValues.some((expectedItem) => isEqual(field, expectedItem));
+    }
+    case 'lt':
+      return field != null && field < expectedValue;
+    case 'lte':
+      return field != null && field <= expectedValue;
+    case 'ne':
+      return !isEqual(field, expectedValue);
+    case 'none':
+      return Array.isArray(field) && !field.some((value) => matchesValue(value, expectedValue));
+    case 'not':
+      return !matchesValue(field, expectedValue);
+    case 'some':
+      return Array.isArray(field) && field.some((value) => matchesValue(value, expectedValue));
+    case 'startsWith':
+      return typeof field === 'string' && field.toLowerCase().startsWith(String(expectedValue).toLowerCase());
+    default:
+      return false;
+  }
+};
+
+function matchesValue(field, condition) {
+  if (!isObject(condition)) {
+    return isEqual(field, condition);
+  }
+
+  const conditionEntries = Object.entries(condition);
+  const operatorEntries = conditionEntries.filter(([operator]) => FIELD_OPERATORS.has(operator));
+  const nestedEntries = conditionEntries.filter(([key]) => !FIELD_OPERATORS.has(key));
+
+  if (!operatorEntries.every(([operator, expectedValue]) => matchesOperator(field, operator, expectedValue))) {
+    return false;
+  }
+
+  return nestedEntries.length === 0 || isObject(field) && matchesWhere(field, Object.fromEntries(nestedEntries));
+}
+
+function matchesWhere(value, where) {
+  if (!isObject(value) || !isObject(where)) {
+    return false;
+  }
+
+  return Object.entries(where).every(([key, condition]) => {
+    if (key === 'and') {
+      return Array.isArray(condition) && condition.every((nestedWhere) => matchesWhere(value, nestedWhere));
+    }
+
+    if (key === 'or') {
+      return Array.isArray(condition) && condition.length > 0 && condition.some((nestedWhere) => matchesWhere(value, nestedWhere));
+    }
+
+    if (key === 'not') {
+      return isObject(condition) && !matchesWhere(value, condition);
+    }
+
+    return isSafeKey(key) && matchesValue(value[key], condition);
+  });
+}
+
+const parsePrimitive = (value) => {
+  if (value === 'true') {
+    return true;
+  }
+
+  if (value === 'false') {
+    return false;
+  }
+
+  return value === 'null' ? null : value;
+};
+
+const parseFilterKey = (key) => {
+  const colonIndex = key.lastIndexOf(':');
+
+  if (colonIndex !== -1) {
+    const path = key.slice(0, colonIndex);
+    const operator = key.slice(colonIndex + 1);
+
+    return FIELD_OPERATORS.has(operator) ? { operator, path } : undefined;
+  }
+
+  const legacyOperator = key.match(/^(.*)_([a-zA-Z]+)$/);
+
+  if (legacyOperator?.[1] != null && legacyOperator[2] != null && FIELD_OPERATORS.has(legacyOperator[2])) {
+    return { operator: legacyOperator[2], path: legacyOperator[1] };
+  }
+
+  return { operator: 'eq', path: key };
+};
+
+const setWhereOperator = (where, path, operator, value) => {
+  const keys = path.split('.').filter(Boolean);
+
+  if (keys.length === 0 || keys.some((key) => !isSafeKey(key))) {
+    return;
+  }
+
+  const fieldKey = keys.pop();
+  let currentValue = where;
+
+  keys.forEach((key) => {
+    currentValue[key] = isObject(currentValue[key]) ? currentValue[key] : {};
+    currentValue = currentValue[key];
+  });
+
+  currentValue[fieldKey] = isObject(currentValue[fieldKey]) ? currentValue[fieldKey] : {};
+  currentValue[fieldKey][operator] = operator === 'in' && typeof value === 'string' ? value.split(',').map((item) => parsePrimitive(item.trim())) : parsePrimitive(value);
+};
+
+export const parseWhere = (query) => {
+  const rawWhere = toArray(query._where).at(-1);
+
+  if (rawWhere != null) {
+    try {
+      const where = JSON.parse(rawWhere);
+
+      if (!isObject(where)) {
+        throw new Error();
+      }
+
+      return where;
+    } catch {
+      throw createHttpError(400, 'Параметр _where должен содержать JSON-объект');
+    }
+  }
+
+  const where = {};
+
+  Object.entries(query).forEach(([key, rawValue]) => {
+    if (RESERVED_QUERY_KEYS.has(key)) {
+      return;
+    }
+
+    const filterKey = parseFilterKey(key);
+
+    if (filterKey != null) {
+      toArray(rawValue).forEach((value) => setWhereOperator(where, filterKey.path, filterKey.operator, value));
+    }
+  });
+
+  return where;
+};
+
+export const paginateItems = (items, page, pageSize) => {
+  const safePageSize = Number.isFinite(pageSize) && pageSize > 0 ? Math.floor(pageSize) : 10;
+  const pages = Math.max(1, Math.ceil(items.length / safePageSize));
+  const safePage = Math.max(1, Math.min(Number.isFinite(page) ? Math.floor(page) : 1, pages));
+  const offset = (safePage - 1) * safePageSize;
+
+  return {
+    data: items.slice(offset, offset + safePageSize),
+    first: 1,
+    items: items.length,
+    last: pages,
+    next: safePage < pages ? safePage + 1 : null,
+    pages,
+    prev: safePage > 1 ? safePage - 1 : null,
+  };
+};
+
+export const sortItems = (items, sort) => {
+  const sortRules = typeof sort === 'string' ? sort.split(',').filter(Boolean) : [];
+
+  if (sortRules.length === 0) {
+    return [...items];
+  }
+
+  return [...items].sort((left, right) => {
+    for (const sortRule of sortRules) {
+      const isDescending = sortRule.startsWith('-');
+      const path = isDescending ? sortRule.slice(1) : sortRule;
+      const comparison = compareValues(getValueByPath(left, path), getValueByPath(right, path));
+
+      if (comparison !== 0) {
+        return isDescending ? -comparison : comparison;
+      }
+    }
+
+    return 0;
+  });
+};
+
+export { matchesWhere };

package/src/relations.js

@@ -0,0 +1,116 @@
+import { getResourceNames, isEqual, isObject, isSafeKey, singularize, toArray } from './utils.js';
+
+const resolveResource = (database, relation, sourceResource) => {
+  const resourceNames = getResourceNames(database.data);
+  const resource = resourceNames.find((resourceName) => resourceName === relation) ?? resourceNames.find((resourceName) => singularize(resourceName) === relation);
+
+  if (resource != null) {
+    return resource;
+  }
+
+  return ['child', 'children', 'parent', 'parents'].includes(relation) && resourceNames.includes(sourceResource) ? sourceResource : undefined;
+};
+
+const getRelationKeys = (...names) => [...new Set(names.flatMap((name) => [`${name}Id`, `${name}Ids`]))];
+
+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) => isEqual(nestedId, id));
+    }
+
+    return hasReference(nestedValue, relationKeys, id);
+  });
+};
+
+const findRelatedValue = (database, item, sourceResource, relation, targetResource) => {
+  const targetItems = database.data[targetResource];
+  const localRelation = findLocalRelation(item, relation, targetResource);
+
+  if (!Array.isArray(targetItems)) {
+    return undefined;
+  }
+
+  if (localRelation != null) {
+    const relatedItems = localRelation.ids.map((id) => targetItems.find((targetItem) => isObject(targetItem) && isEqual(targetItem.id, 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]) => {
+  if (relation == null || !isSafeKey(relation)) {
+    return item;
+  }
+
+  const currentValue = item[relation];
+  const nestedSourceResource = resolveResource(database, relation, sourceResource) ?? relation;
+
+  if (Array.isArray(currentValue)) {
+    return nestedRelations.length === 0 ? item : { ...item, [relation]: currentValue.map((value) => (isObject(value) ? embedPath(database, value, nestedSourceResource, nestedRelations) : value)) };
+  }
+
+  if (isObject(currentValue)) {
+    return nestedRelations.length === 0 ? item : { ...item, [relation]: embedPath(database, currentValue, nestedSourceResource, nestedRelations) };
+  }
+
+  const targetResource = resolveResource(database, relation, sourceResource);
+
+  if (targetResource == null) {
+    return item;
+  }
+
+  const relatedValue = findRelatedValue(database, item, sourceResource, relation, targetResource);
+
+  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))
+      : embedPath(database, relatedValue, targetResource, nestedRelations),
+  };
+};
+
+export const parseEmbedPaths = (embed) => toArray(embed)
+  .flatMap((value) => (typeof value === 'string' ? value.split(',') : []))
+  .map((path) => path.split('.').filter(Boolean))
+  .filter((path) => path.length > 0 && path.every(isSafeKey));
+
+export const embedItem = (database, item, resource, embedPaths) => embedPaths.reduce((embeddedItem, path) => embedPath(database, embeddedItem, resource, path), item);