Швидкий старт

Від порожньої теки до типізованого REST-ендпоїнту менш ніж за п'ять хвилин.

Встановіть CLI, створіть проєкт, згенеруйте модель і її CRUD-маршрути, а потім звертайтеся до ендпоїнтів через curl. Усе нижче припускає типовий SQLite — поведінка рантайму ідентична для всіх діалектів.

Створення та запуск

bun add -g @hopak/cli
hopak new my-app           # SQLite by default (zero-install)
cd my-app
hopak dev

Хочете Postgres або MySQL від початку? Оберіть діалект на етапі створення — драйвер встановиться, hopak.config.ts налаштується, а .env.example вже міститиме DATABASE_URL:

hopak new my-app --db postgres
hopak new my-app --db mysql
hopak new my-app --db sqlite   # explicit opt-in (default)

Ви вже всередині проєкту? Змініть діалект:

hopak use postgres         # installs `postgres` driver, patches config, updates .env.example
hopak use mysql            # installs `mysql2`, etc.
hopak use sqlite           # back to default

Сервер на http://localhost:3000. Згенеруйте модель і її REST-файли двома командами (hopak generate model/crud) — і ви отримаєте валідацію, JSON-серіалізацію, статичні файли. Жодної рантайм-магії, кожен маршрут — у вихідному коді.

Створіть REST-ресурс

Мета: виставити GET/POST /api/posts та GET/PUT/PATCH/DELETE /api/posts/:id.

1. Згенеруйте файли моделі та CRUD-маршрутів:

hopak generate model post
hopak generate crud post

Перша команда створює app/models/post.ts. Друга створює два файли маршрутів — app/routes/api/posts.ts (list + create) і app/routes/api/posts/[id].ts (read + replace + patch + delete). Відкрийте будь-який файл — уся REST-поверхня там, як звичайний код, який можна читати й редагувати. Нічого не синтезується під час виконання.

2. Додайте поля до моделі:

// app/models/post.ts
import { model, text, boolean } from '@hopak/core';

export default model('post', {
  title: text().required().min(3),
  content: text().required(),
  published: boolean().default(false),
});

3. Запустіть сервер:

hopak dev

Під час першого запуску Hopak створює файл SQLite за шляхом .hopak/data.db і виконує CREATE TABLE IF NOT EXISTS для кожної моделі. Команду безпечно повторювати — hopak sync робить те саме явно, якщо ви хочете розділити синхронізацію схеми та запуск сервера (зручно для CI чи свіжої бази Postgres / MySQL).

4. Спробуйте з іншого термінала:

curl -X POST http://localhost:3000/api/posts \
  -H 'content-type: application/json' \
  -d '{"title":"Hello","content":"World"}'

Очікувана відповідь (201 Created):

{ "id": 1, "title": "Hello", "content": "World", "published": false,
  "createdAt": "...", "updatedAt": "..." }

5. Отримайте список:

curl http://localhost:3000/api/posts
# → { "items": [...], "total": 1, "limit": 20, "offset": 0 }

curl 'http://localhost:3000/api/posts?limit=5&offset=10'
# pagination via query string; limit defaults to 20, max 100

6. Перевірте, що зареєстровано:

hopak check
# ✓ Models   1 loaded (post)
# ✓ Routes   6 file route(s)

Шість ендпоїнтів із двох згенерованих файлів: list, read, create, replace, patch, delete — усі з пагінацією та валідацією. Сегмент множини (/api/posts) береться з pluralize('post') — нестандартні форми множини оброблено (story → stories, box → boxes). Не потрібні ендпоїнти для певної моделі? Просто не запускайте для неї hopak generate crud — модель усе одно стане таблицею, ви лише не експонуєте HTTP-маршрути.

Далі: Структура проєкту.