@e22m4u/js-repository-json-schema 0.0.1

package/.c8rc

@@ -0,0 +1,9 @@
+{
+  "all": true,
+  "include": [
+    "src/**/*.js"
+  ],
+  "exclude": [
+    "src/**/*.spec.js"
+  ]
+}

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

package/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+max_line_length = 80

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+npm run lint:fix
+npm run format
+npm run test
+npm run build:cjs
+
+git add -A

package/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "extension": ["js"],
+  "spec": "src/**/*.spec.js"
+}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "bracketSpacing": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Mikhail Evstropov <e22m4u@yandex.ru>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+## @e22m4u/js-repository-json-schema
+
+Модуль генерации *JSON Schema (Draft 2020-12)* для
+[@e22m4u/js-repository](http://www.npmjs.com/package/@e22m4u/js-repository)
+
+## Содержание
+
+- [Установка](#установка)
+- [Использование](#использование)
+- [Параметры](#параметры)
+- [Тесты](#тесты)
+- [Лицензия](#лицензия)
+
+## Установка
+
+```bash
+npm install @e22m4u/js-repository-json-schema
+```
+
+Модуль поддерживает ESM и CommonJS стандарты.
+
+*ESM*
+
+```js
+import {JsonSchemaGenerator} from '@e22m4u/js-repository-json-schema';
+```
+
+*CommonJS*
+
+```js
+const {JsonSchemaGenerator} = require('@e22m4u/js-repository-json-schema');
+```
+
+## Использование
+
+Определение простой модели и генерация для нее JSON-схемы.
+
+```js
+import {DataType, DatabaseSchema} from '@e22m4u/js-repository';
+import {JsonSchemaGenerator} from '@e22m4u/js-repository-json-schema';
+
+// создание схемы БД, определение источника данных и модели
+const dbs = new DatabaseSchema();
+
+dbs.defineModel({
+  name: 'user',
+  properties: {
+    firstName: {
+      type: DataType.STRING,
+      required: true,      // поле будет добавлено в массив "required"
+    },
+    age: {
+      type: DataType.NUMBER,
+      default: 18,         // будет добавлено поле "default"
+    },
+    isActive: DataType.BOOLEAN,
+  },
+});
+
+// получение генератора из сервис-контейнера
+const generator = dbs.getService(JsonSchemaGenerator);
+
+// генерация JSON-схемы по названию модели
+const schema = generator.genSchema('user');
+
+console.log(schema);
+// {
+//   "type": "object",
+//   "properties": {
+//     "firstName": {
+//       "type": "string",
+//       "example": ""
+//     },
+//     "age": {
+//       "type": "number",
+//       "default": 18
+//     },
+//     "isActive": {
+//       "type": "boolean",
+//       "example": false
+//     }
+//   },
+//   "required": [
+//     "firstName"
+//   ]
+// }
+```
+
+*i. Если для модели определен источник данных, то генератор автоматически
+добавит первичный ключ (*id*), если он не был описан вручную.*
+
+## Параметры
+
+Метод `genSchema` принимает второй необязательный аргумент с настройками схемы.
+
+```js
+const schema = generator.genSchema('user', {
+  // исключить определенные свойства
+  // (например, пароли или внутренние ключи)
+  excludeProperties: ['password', 'internalToken'],
+  
+  // пользовательская фабрика для генерации $ref ссылок
+  // по умолчанию modelName => ({ $ref: `#/components/schemas/${modelName}` })
+  refFactory: (modelName) => ({$ref: `#/components/schemas/${modelName}Input`}),
+  
+  // тип первичных и внешних ключей по умолчанию
+  // "number" или "string" (по умолчанию "number")
+  defaultPrimaryKeyType: 'string',
+});
+```
+
+## Тесты
+
+```bash
+npm run test
+```
+
+## Лицензия
+
+MIT

package/build-cjs.js

@@ -0,0 +1,16 @@
+import * as esbuild from 'esbuild';
+import packageJson from './package.json' with {type: 'json'};
+
+await esbuild.build({
+  entryPoints: ['src/index.js'],
+  outfile: 'dist/cjs/index.cjs',
+  format: 'cjs',
+  platform: 'node',
+  target: ['node18'],
+  bundle: true,
+  keepNames: true,
+  external: [
+    ...Object.keys(packageJson.peerDependencies || {}),
+    ...Object.keys(packageJson.dependencies || {}),
+  ],
+});

package/eslint.config.js

@@ -0,0 +1,41 @@
+import globals from 'globals';
+import eslintJs from '@eslint/js';
+import eslintJsdocPlugin from 'eslint-plugin-jsdoc';
+import eslintMochaPlugin from 'eslint-plugin-mocha';
+import eslintImportPlugin from 'eslint-plugin-import';
+import eslintPrettierConfig from 'eslint-config-prettier';
+import eslintChaiExpectPlugin from 'eslint-plugin-chai-expect';
+
+export default [{
+  languageOptions: {
+    globals: {
+      ...globals.node,
+      ...globals.es2021,
+      ...globals.mocha,
+    },
+  },
+  plugins: {
+    'jsdoc': eslintJsdocPlugin,
+    'mocha': eslintMochaPlugin,
+    'import': eslintImportPlugin,
+    'chai-expect': eslintChaiExpectPlugin,
+  },
+  rules: {
+    ...eslintJs.configs.recommended.rules,
+    ...eslintPrettierConfig.rules,
+    ...eslintImportPlugin.flatConfigs.recommended.rules,
+    ...eslintMochaPlugin.configs.recommended.rules,
+    ...eslintChaiExpectPlugin.configs['recommended-flat'].rules,
+    ...eslintJsdocPlugin.configs['flat/recommended-error'].rules,
+    "curly": "error",
+    'no-duplicate-imports': 'error',
+    'import/export': 0,
+    'jsdoc/reject-any-type': 0,
+    'jsdoc/reject-function-type': 0,
+    'jsdoc/require-param-description': 0,
+    'jsdoc/require-returns-description': 0,
+    'jsdoc/require-property-description': 0,
+    'jsdoc/tag-lines': ['error', 'any', {startLines: 1}],
+  },
+  files: ['src/**/*.js'],
+}];

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@e22m4u/js-repository-json-schema",
+  "version": "0.0.1",
+  "description": "Модуль генерации JSON Schema для @e22m4u/js-repository",
+  "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
+  "license": "MIT",
+  "keywords": [
+    "repository",
+    "json-schema"
+  ],
+  "homepage": "https://gitverse.ru/e22m4u/js-repository-json-schema",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitverse.ru/e22m4u/js-repository-json-schema.git"
+  },
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "module": "./src/index.js",
+  "main": "./dist/cjs/index.cjs",
+  "exports": {
+    "types": "./src/index.d.ts",
+    "import": "./src/index.js",
+    "require": "./dist/cjs/index.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "tsc && eslint ./src",
+    "lint:fix": "tsc && eslint ./src --fix",
+    "format": "prettier --write \"./src/**/*.js\"",
+    "test": "npm run lint && c8 --reporter=text-summary mocha --bail",
+    "test:coverage": "npm run lint && c8 --reporter=text mocha --bail",
+    "build:cjs": "rimraf ./dist/cjs && node build-cjs.js",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@e22m4u/js-format": "~0.4.0",
+    "@e22m4u/js-service": "~0.6.2"
+  },
+  "peerDependencies": {
+    "@e22m4u/js-repository": "~0.8.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "~21.0.2",
+    "@commitlint/config-conventional": "~21.0.2",
+    "@eslint/js": "~9.39.2",
+    "@types/chai": "~5.2.3",
+    "@types/mocha": "~10.0.10",
+    "@types/node": "~25.9.2",
+    "c8": "~11.0.0",
+    "chai": "~6.2.2",
+    "esbuild": "~0.28.0",
+    "eslint": "~9.39.2",
+    "eslint-config-prettier": "~10.1.8",
+    "eslint-plugin-chai-expect": "~4.1.0",
+    "eslint-plugin-import": "~2.32.0",
+    "eslint-plugin-jsdoc": "~63.0.2",
+    "eslint-plugin-mocha": "~11.3.0",
+    "globals": "~17.6.0",
+    "husky": "~9.1.7",
+    "mocha": "~11.7.6",
+    "prettier": "~3.8.3",
+    "rimraf": "~6.1.3",
+    "typescript": "~6.0.3"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './json-schema-generator.js';

package/src/index.js

@@ -0,0 +1 @@
+export * from './json-schema-generator.js';

package/src/json-schema-generator.d.ts

@@ -0,0 +1,40 @@
+import {Service} from '@e22m4u/js-service';
+
+/**
+ * Структура, которую возвращает генератор.
+ */
+interface JsonSchema {
+  type?: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  example?: unknown;
+  default?: unknown;
+  $ref?: string;
+  allOf?: JsonSchema[];
+}
+
+/**
+ * Опции, которые принимает метод.
+ */
+interface JsonSchemaGeneratorOptions {
+  excludeProperties?: string[];
+  refFactory?: (modelName: string) => {$ref: string};
+  defaultPrimaryKeyType?: 'number' | 'string';
+}
+
+/**
+ * Json schema generator.
+ */
+export class JsonSchemaGenerator extends Service {
+  /**
+   * Сгенерировать JSON Schema для указанной модели.
+   *
+   * @param modelName Название модели
+   * @param options   Опции генерации
+   */
+  genSchema(
+    modelName: string,
+    options?: JsonSchemaGeneratorOptions,
+  ): JsonSchema;
+}

package/src/json-schema-generator.js

@@ -0,0 +1,377 @@
+import {Service} from '@e22m4u/js-service';
+import {InvalidArgumentError} from '@e22m4u/js-format';
+
+import {
+  DataType,
+  singularize,
+  RelationType,
+  DefinitionRegistry,
+  ModelDefinitionUtils,
+  DEFAULT_PRIMARY_KEY_PROPERTY_NAME,
+} from '@e22m4u/js-repository';
+
+/**
+ * Сервис генерации JSON Schema (OpenAPI/Swagger совместимой)
+ * на основе определений моделей репозитория.
+ */
+export class JsonSchemaGenerator extends Service {
+  /**
+   * Сгенерировать JSON Schema для указанной модели.
+   *
+   * @param   {string}   modelName                       Название модели
+   * @param   {object}   [options]                       Опции генерации
+   * @param   {string[]} [options.excludeProperties]     Массив свойств для исключения из схемы
+   * @param   {Function} [options.refFactory]            Функция для создания $ref строк
+   * @param   {string}   [options.defaultPrimaryKeyType] Тип по умолчанию для Primary Key и Foreign Key ('number' или 'string')
+   * @returns {object}   JSON Schema
+   */
+  genSchema(modelName, options = {}) {
+    // modelName
+    if (!modelName || typeof modelName !== 'string') {
+      throw new InvalidArgumentError(
+        'Parameter "modelName" must be a non-empty String, but %v was given.',
+        modelName,
+      );
+    }
+    // options
+    if (
+      options === null ||
+      typeof options !== 'object' ||
+      Array.isArray(options)
+    ) {
+      throw new InvalidArgumentError(
+        'Parameter "options" must be an Object, but %v was given.',
+        options,
+      );
+    }
+    // проверка опций и инициализация
+    // значений по умолчанию
+    this._validateOptions(options);
+    const opts = this._normalizeOptions(options);
+    // получение определения модели из реестра
+    const registry = this.getService(DefinitionRegistry);
+    const modelDef = registry.getModel(modelName);
+    // базовый каркас схемы
+    const schema = {
+      type: 'object',
+      properties: {},
+    };
+    const requiredFields = [];
+    const propertiesDef = modelDef.properties || {};
+    // обработка неявного первичного ключа (primary key)
+    this._injectImplicitPrimaryKeyIfNeeded(
+      modelDef,
+      propertiesDef,
+      schema,
+      opts,
+    );
+    // обработка явно заданных свойств модели
+    for (const [propName, propDef] of Object.entries(propertiesDef)) {
+      if (opts.excludeProperties.includes(propName)) {
+        continue;
+      }
+      schema.properties[propName] = this._mapPropertyToSchema(propDef, opts);
+      // если свойство явно помечено как обязательное (и не имеет default)
+      if (propDef && typeof propDef === 'object' && propDef.required) {
+        requiredFields.push(propName);
+      }
+    }
+    // обработка неявных внешних ключей от связей
+    // (foreign keys & discriminators)
+    this._injectImplicitForeignKeys(modelDef, propertiesDef, schema, opts);
+    // добавление массива required, если есть обязательные поля
+    if (requiredFields.length > 0) {
+      schema.required = requiredFields;
+    }
+    // обработка наследования (иерархия моделей)
+    // если у модели есть базовая модель, мы не разворачиваем её свойства,
+    // а используем allOf с ссылкой ($ref) на родительскую схему
+    if (modelDef.base) {
+      return {
+        allOf: [opts.refFactory(modelDef.base), schema],
+      };
+    }
+    return schema;
+  }
+
+  /**
+   * Проверка опций генератора.
+   * 
+   * @param {object} options
+   * @private
+   */
+  _validateOptions(options) {
+    // excludeProperties
+    if (options.excludeProperties !== undefined) {
+      if (!Array.isArray(options.excludeProperties)) {
+        throw new InvalidArgumentError(
+          'Option "excludeProperties" must be an Array, but %v was given.',
+          options.excludeProperties,
+        );
+      }
+      // excludeProperties[n]
+      options.excludeProperties.forEach((propertyName, index) => {
+        if (!propertyName || typeof propertyName !== 'string') {
+          throw new InvalidArgumentError(
+            'Element %d of the option "excludeProperties" ' +
+              'must be a non-empty String, but %v was given.',
+            index,
+            propertyName,
+          );
+        }
+      });
+    }
+    // refFactory
+    if (
+      options.refFactory !== undefined &&
+      typeof options.refFactory !== 'function'
+    ) {
+      throw new InvalidArgumentError(
+        'Option "refFactory" must be a Function, but %v was given.',
+        options.refFactory,
+      );
+    }
+    // defaultPrimaryKeyType
+    if (
+      options.defaultPrimaryKeyType !== undefined &&
+      !['string', 'number'].includes(options.defaultPrimaryKeyType)
+    ) {
+      throw new InvalidArgumentError(
+        'Option "defaultPrimaryKeyType" allows "number" ' +
+          'or "string" value, but %v was given.',
+        options.defaultPrimaryKeyType,
+      );
+    }
+  }
+
+  /**
+   * Нормализация опций генератора.
+   *
+   * @param   {object} options
+   * @returns {object}
+   * @private
+   */
+  _normalizeOptions(options) {
+    return {
+      excludeProperties: options.excludeProperties || [],
+      refFactory:
+        options.refFactory ||
+        (modelName => ({$ref: `#/components/schemas/${modelName}`})),
+      defaultPrimaryKeyType: options.defaultPrimaryKeyType || 'number',
+    };
+  }
+
+  /**
+   * Преобразование определения свойства
+   * репозитория в JSON Schema объект.
+   *
+   * @param   {string|object} propDef Определение свойства
+   * @param   {object}        opts    Настройки генератора
+   * @returns {object}
+   * @private
+   */
+  _mapPropertyToSchema(propDef, opts) {
+    // если передана краткая форма (просто строка DataType)
+    if (typeof propDef === 'string') {
+      return this._createSchemaByType(propDef);
+    }
+    if (!propDef || typeof propDef !== 'object') {
+      return {};
+    }
+    // если это вложенный объект, ссылающийся на другую модель
+    if (propDef.type === DataType.OBJECT && propDef.model) {
+      return opts.refFactory(propDef.model);
+    }
+    // если это массив элементов, ссылающихся на другую модель
+    if (propDef.type === DataType.ARRAY && propDef.itemModel) {
+      return {
+        type: 'array',
+        items: opts.refFactory(propDef.itemModel),
+      };
+    }
+    // получение базовой схемы с учетом типа
+    const schema = this._createSchemaByType(propDef.type);
+    // если это массив примитивов (itemType)
+    if (propDef.type === DataType.ARRAY && propDef.itemType) {
+      schema.items = this._createSchemaByType(propDef.itemType);
+    }
+    // установка реального default, если он задан,
+    // то example удаляется, чтобы не дублировать логику
+    if (propDef.default !== undefined) {
+      schema.default =
+        typeof propDef.default === 'function'
+          ? propDef.default()
+          : propDef.default;
+      delete schema.example;
+    }
+    return schema;
+  }
+
+  /**
+   * Создание примитивной схемы в зависимости от типа данных.
+   * Добавляет 'example' с пустым значением для Swagger.
+   *
+   * @param   {string} dataType Тип данных
+   * @returns {object}
+   * @private
+   */
+  _createSchemaByType(dataType) {
+    switch (dataType) {
+      case DataType.STRING:
+        return {type: 'string', example: ''};
+      case DataType.NUMBER:
+        return {type: 'number', example: 0};
+      case DataType.BOOLEAN:
+        return {type: 'boolean', example: false};
+      case DataType.ARRAY:
+        return {type: 'array', example: []};
+      case DataType.OBJECT:
+        return {type: 'object', example: {}};
+      case DataType.ANY:
+        return {example: ''}; // any type
+      default:
+        // фолбэк для нераспознанных типов
+        // (например, если передали 'string' напрямую)
+        return {type: dataType, example: dataType === 'number' ? 0 : ''};
+    }
+  }
+
+  /**
+   * Добавление неявного первичного ключа, если он не был задан
+   * в свойствах текущей модели и если модель не наследуется
+   * от другой.
+   *
+   * @param {object} modelDef
+   * @param {object} propertiesDef
+   * @param {object} schema
+   * @param {object} opts
+   * @private
+   */
+  _injectImplicitPrimaryKeyIfNeeded(modelDef, propertiesDef, schema, opts) {
+    // если источник данных не указан,
+    // неявный первичный ключ генерировать не нужно
+    if (!modelDef.datasource) {
+      return;
+    }
+    // если модель наследуется, то предполагается,
+    // что первичный ключ определен у родителя
+    if (modelDef.base) {
+      return;
+    }
+    // поиск явно заданного первичного ключа в свойствах
+    const hasExplicitPk = Object.values(propertiesDef).some(
+      prop => prop && typeof prop === 'object' && prop.primaryKey,
+    );
+    // если явного первичного ключа нет и поле "id" (стандартное) не описано
+    if (!hasExplicitPk && !propertiesDef[DEFAULT_PRIMARY_KEY_PROPERTY_NAME]) {
+      if (!opts.excludeProperties.includes(DEFAULT_PRIMARY_KEY_PROPERTY_NAME)) {
+        schema.properties[DEFAULT_PRIMARY_KEY_PROPERTY_NAME] =
+          this._createSchemaByType(opts.defaultPrimaryKeyType);
+      }
+    }
+  }
+
+  /**
+   * Инъекция свойств для хранения внешних ключей и дискриминаторов,
+   * которые возникают из-за связей (relations), но не описаны явно
+   * в properties.
+   *
+   * @param {object} modelDef
+   * @param {object} propertiesDef
+   * @param {object} schema
+   * @param {object} opts
+   * @private
+   */
+  _injectImplicitForeignKeys(modelDef, propertiesDef, schema, opts) {
+    const relations = modelDef.relations || {};
+    for (const [relName, relDef] of Object.entries(relations)) {
+      // определение типа ключа для текущей связи
+      const foreignKeyDataType = this._resolveForeignKeyDataType(relDef, opts);
+      // обработка связи belongsTo
+      // (хранит foreign key и, опционально, discriminator)
+      if (relDef.type === RelationType.BELONGS_TO) {
+        const foreignKey = relDef.foreignKey || `${relName}Id`;
+        // внешний ключ
+        if (
+          !propertiesDef[foreignKey] &&
+          !opts.excludeProperties.includes(foreignKey)
+        ) {
+          schema.properties[foreignKey] = this._createSchemaByType(
+            foreignKeyDataType,
+          );
+        }
+        // дискриминатор (для полиморфных связей)
+        if (relDef.polymorphic) {
+          const discriminator = relDef.discriminator || `${relName}Type`;
+          if (
+            !propertiesDef[discriminator] &&
+            !opts.excludeProperties.includes(discriminator)
+          ) {
+            schema.properties[discriminator] = this._createSchemaByType(
+              DataType.STRING,
+            );
+          }
+        }
+      }
+      // обработка связи referencesMany
+      // (хранит массив foreign keys)
+      else if (relDef.type === RelationType.REFERENCES_MANY) {
+        const singularRelName = singularize(relName);
+        const foreignKey = relDef.foreignKey || `${singularRelName}Ids`;
+        if (
+          !propertiesDef[foreignKey] &&
+          !opts.excludeProperties.includes(foreignKey)
+        ) {
+          schema.properties[foreignKey] = {
+            type: 'array',
+            items: this._createSchemaByType(foreignKeyDataType),
+            example: [],
+          };
+        }
+      }
+      // связи HAS_ONE и HAS_MANY не хранят внешний ключ
+      // в текущей таблице/модели, поэтому игнорируются
+    }
+  }
+
+  /**
+   * Пытается определить тип первичного ключа целевой модели.
+   * Если связь полиморфная или тип ключа ANY, то возвращает
+   * тип по умолчанию (opts.defaultPrimaryKeyType).
+   *
+   * @param   {object} relDef Определение связи
+   * @param   {object} opts   Настройки генератора
+   * @returns {string} Тип данных (DataType)
+   * @private
+   */
+  _resolveForeignKeyDataType(relDef, opts) {
+    // если целевая модель не указана (например, полиморфная связь)
+    if (!relDef.model) {
+      return opts.defaultPrimaryKeyType;
+    }
+    const registry = this.getService(DefinitionRegistry);
+    // если целевая модель еще не зарегистрирована
+    if (!registry.hasModel(relDef.model)) {
+      throw new InvalidArgumentError(
+        'Model %v must be registered before generating a JSON Schema.',
+        relDef.model,
+      );
+    }
+    const utils = this.getService(ModelDefinitionUtils);
+    try {
+      // попытка получить имя первичного ключа и его тип
+      const pkName = utils.getPrimaryKeyAsPropertyName(relDef.model);
+      const pkType = utils.getDataTypeByPropertyName(relDef.model, pkName);
+      // если тип определен и это не ANY,
+      // то используется данный тип
+      if (pkType && pkType !== DataType.ANY) {
+        return pkType;
+      }
+    } catch {
+      // ошибки игнорируются (например, циклическое наследование)
+      // и просто провал к типу по умолчанию
+    }
+    // во всех остальных случаях используется значение по умолчанию
+    return opts.defaultPrimaryKeyType;
+  }
+}

package/src/json-schema-generator.spec.js

@@ -0,0 +1,77 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {JsonSchemaGenerator} from './json-schema-generator.js';
+
+import {
+  DataType,
+  DatabaseSchema,
+  DEFAULT_PRIMARY_KEY_PROPERTY_NAME,
+} from '@e22m4u/js-repository';
+
+describe('JsonSchemaGenerator', function () {
+  describe('genSchema', function () {
+    it('should require the parameter "modelName" to be a non-empty String', function () {
+      const throwable = v => () => {
+        const dbs = new DatabaseSchema();
+        dbs.defineModel({name: 'model'});
+        const S = dbs.getService(JsonSchemaGenerator);
+        S.genSchema(v);
+      };
+      const error = s =>
+        format(
+          'Parameter "modelName" must be a non-empty String, but %s was given.',
+          s,
+        );
+      expect(throwable('')).to.throw(error('""'));
+      expect(throwable(10)).to.throw(error('10'));
+      expect(throwable(0)).to.throw(error('0'));
+      expect(throwable(true)).to.throw(error('true'));
+      expect(throwable(false)).to.throw(error('false'));
+      expect(throwable([])).to.throw(error('Array'));
+      expect(throwable({})).to.throw(error('Object'));
+      expect(throwable(undefined)).to.throw(error('undefined'));
+      expect(throwable(null)).to.throw(error('null'));
+      throwable('model')();
+    });
+
+    it('should inject a primary key at the beginning of the properties object', function () {
+      const dbs = new DatabaseSchema();
+      dbs.defineDatasource({name: 'memory', adapter: 'memory'});
+      dbs.defineModel({
+        name: 'modelWithDbAndProps',
+        datasource: 'memory',
+        properties: {
+          firstName: DataType.STRING,
+          age: DataType.NUMBER,
+        },
+      });
+      const S = dbs.getService(JsonSchemaGenerator);
+      const schema = S.genSchema('modelWithDbAndProps');
+      const propertyKeys = Object.keys(schema.properties);
+      expect(propertyKeys[0]).to.be.eq(DEFAULT_PRIMARY_KEY_PROPERTY_NAME);
+      expect(propertyKeys[1]).to.be.eq('firstName');
+      expect(propertyKeys[2]).to.be.eq('age');
+    });
+
+    it('should inject a primary key if a datasource is defined', function () {
+      const dbs = new DatabaseSchema();
+      dbs.defineDatasource({name: 'memory', adapter: 'memory'});
+      dbs.defineModel({name: 'modelWithDb', datasource: 'memory'});
+      const S = dbs.getService(JsonSchemaGenerator);
+      const schema = S.genSchema('modelWithDb');
+      expect(schema.properties).to.have.property(
+        DEFAULT_PRIMARY_KEY_PROPERTY_NAME,
+      );
+    });
+
+    it('should not inject a primary key if a datasource is not defined', function () {
+      const dbs = new DatabaseSchema();
+      dbs.defineModel({name: 'modelWithoutDb'});
+      const S = dbs.getService(JsonSchemaGenerator);
+      const schema = S.genSchema('modelWithoutDb');
+      expect(schema.properties).to.not.have.property(
+        DEFAULT_PRIMARY_KEY_PROPERTY_NAME,
+      );
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "es2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "allowJs": true,
+    "types": ["node"]
+  },
+  "include": [
+    "./src/**/*.ts",
+    "./src/**/*.js"
+  ]
+}