@varmdev/api-kit

api-kit — это универсальный набор для создания типизированных API на TypeScript. Он помогает описывать контракт эндпоинта, валидировать входные данные, держать единый формат ответов, собирать OpenAPI-спецификацию и подключать это к SvelteKit.

Пакет не знает ничего о вашей базе данных, бизнес-логике и конкретной авторизации. Он даёт инфраструктурный слой, а приложение решает, как именно получать пользователя, как проверять права и что делать внутри хендлера.

Что Умеет Пакет

• описывать endpoint как контракт через defineEndpoint;
• валидировать params, query, body и response через Zod;
• стандартизировать успешные и ошибочные JSON-ответы;
• поднимать ApiKitError для ожидаемых HTTP-ошибок;
• накапливать OpenAPI-метаданные и генерировать спецификацию;
• давать typedFetch для клиентского кода;
• давать generateQuerySchema для query-параметров;
• адаптировать всё это под SvelteKit через apiHandler.

Когда Он Полезен

• когда в проекте много endpoint-ов и хочется держать их в одном стиле;
• когда хочется, чтобы типы, валидация и OpenAPI жили из одного описания;
• когда нужно переиспользовать один и тот же подход в нескольких проектах;
• когда SvelteKit нужен только как транспорт, а не как место для всей логики API.

Структура

src/core/
  endpoint.ts      # defineEndpoint и типы endpoint-контракта
  apiRegistry.ts   # OpenAPI registry и генерация документа
  client.ts        # typedFetch и вывод типов endpoint-а
  query.ts         # generateQuerySchema для URL query
  errors.ts        # ApiKitError и преобразование Zod issues
  responses.ts     # success/error response schemas
  cache.ts         # cache policy -> HTTP headers

src/sveltekit/
  apiHandler.ts    # адаптер EndpointDefinition -> SvelteKit RequestHandler

src/core не зависит от SvelteKit. Вся SvelteKit-специфика остаётся в src/sveltekit.

Точки Входа

import { defineEndpoint } from '@varmdev/api-kit/core';
import { createOpenApiRegistry } from '@varmdev/api-kit/apiRegistry';
import { apiHandler } from '@varmdev/api-kit/apiHandler';
import { typedFetch } from '@varmdev/api-kit/client';
import { generateQuerySchema } from '@varmdev/api-kit/query';

Если нужен явный путь для SvelteKit-адаптера:

import { apiHandler } from '@varmdev/api-kit/sveltekit/apiHandler';

Как Это Выглядит

import { z } from 'zod';
import { defineEndpoint } from '@varmdev/api-kit/core';
import { apiHandler } from '@varmdev/api-kit/sveltekit/apiHandler';

const endpoint = defineEndpoint({
  querySchema: z.object({
    q: z.string().optional()
  }),
  responseSchema: z.object({
    items: z.array(z.string())
  }),
  openapi: {
    method: 'GET',
    path: '/api/examples',
    summary: 'Example endpoint',
    tags: ['Examples']
  },
  handler: async ({ query }) => ({
    items: query.q ? [query.q] : []
  })
});

export const GET = apiHandler(endpoint);

Установка

Локально в соседнем репозитории:

bun add @varmdev/api-kit@file:../api-kit

Из npm:

{
  "dependencies": {
    "@varmdev/api-kit": "^0.1.7"
  }
}

Или через npm:

npm install @varmdev/api-kit

Статус

Пакет в ранней версии. API может немного меняться до 1.0.

Разработка

bun install
bun run check
bun run build