ebely 0.0.2 → 0.0.4

package/clone/tests/ebely/generated.ts

@@ -0,0 +1,552 @@
+// AUTO-GENERATED by ebely (generateClient) — НЕ редактировать вручную.
+// Источник: Test Backend (oRPC) v1.0.0
+// Режим клиента: test
+// Перегенерация: pnpm run client:generate
+
+import { BaseStore, ApiResponse, HookRegistry } from "ebely"
+import type { BeforeHook, AfterHook } from "ebely"
+import { ebely } from "./ebely"
+
+type RequestInput = {
+  path?: Record<string, string>
+  query?: Record<string, string | number | boolean | undefined>
+  body?: unknown
+}
+
+type RequestFn = (req: {
+  method: string
+  path: string
+  opKey: string
+  input?: RequestInput
+}) => Promise<{ status: number; body: unknown }>
+
+export type CreateUserArgs = {
+  /** Заголовки, которые будут добавляться ко всем запросам этого пользователя. */
+  headers?: Record<string, string>
+}
+
+export type WorldApi = {
+    "posts": {
+      "list": (input?: {}) => Promise<ApiResponse<{ 200: Array<{
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        }> }>>
+      "create": (input: { body: {
+          "title": string
+          "content": string
+        } }) => Promise<ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>>
+      "get": (input: { path: { "id": string } }) => Promise<ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>>
+      "update": (input: { path: { "id": string }; body?: {
+          "title"?: string
+          "content"?: string
+        } }) => Promise<ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>>
+      "delete": (input: { path: { "id": string } }) => Promise<ApiResponse<{ 200: {
+          "success": boolean
+        } }>>
+    }
+    "auth": {
+      "register": (input: { body: {
+          "email": string
+          "password": string
+        } }) => Promise<ApiResponse<{ 200: {
+          "email": string
+          "password": string
+        } }>>
+      "confirm": (input: { body: {
+          "code": string
+        } }) => Promise<ApiResponse<{ 200: {
+          "code": string
+        } }>>
+    }
+    "admin": {
+      "clearDatabase": (input?: {}) => Promise<ApiResponse<{ 200: {
+          "success": boolean
+        } }>>
+    }
+}
+
+type EbelyHookTree<Store extends BaseStore> = {
+    "posts": {
+      "list": {
+        before(fn: BeforeHook<Store, undefined>): void
+        after(fn: AfterHook<Store, undefined, Array<{
+        "id": string
+        "title": string
+        "content": string
+        "createdAt": string
+        "updatedAt": string
+      }>>): void
+      }
+      "create": {
+        before(fn: BeforeHook<Store, {
+          "title": string
+          "content": string
+        }>): void
+        after(fn: AfterHook<Store, {
+          "title": string
+          "content": string
+        }, {
+        "id": string
+        "title": string
+        "content": string
+        "createdAt": string
+        "updatedAt": string
+      }>): void
+      }
+      "get": {
+        before(fn: BeforeHook<Store, undefined>): void
+        after(fn: AfterHook<Store, undefined, {
+        "id": string
+        "title": string
+        "content": string
+        "createdAt": string
+        "updatedAt": string
+      }>): void
+      }
+      "update": {
+        before(fn: BeforeHook<Store, {
+          "title"?: string
+          "content"?: string
+        }>): void
+        after(fn: AfterHook<Store, {
+          "title"?: string
+          "content"?: string
+        }, {
+        "id": string
+        "title": string
+        "content": string
+        "createdAt": string
+        "updatedAt": string
+      }>): void
+      }
+      "delete": {
+        before(fn: BeforeHook<Store, undefined>): void
+        after(fn: AfterHook<Store, undefined, {
+        "success": boolean
+      }>): void
+      }
+    }
+    "auth": {
+      "register": {
+        before(fn: BeforeHook<Store, {
+          "email": string
+          "password": string
+        }>): void
+        after(fn: AfterHook<Store, {
+          "email": string
+          "password": string
+        }, {
+        "email": string
+        "password": string
+      }>): void
+      }
+      "confirm": {
+        before(fn: BeforeHook<Store, {
+          "code": string
+        }>): void
+        after(fn: AfterHook<Store, {
+          "code": string
+        }, {
+        "code": string
+      }>): void
+      }
+    }
+    "admin": {
+      "clearDatabase": {
+        before(fn: BeforeHook<Store, undefined>): void
+        after(fn: AfterHook<Store, undefined, {
+        "success": boolean
+      }>): void
+      }
+    }
+}
+
+/**
+ * Тип регистратора хуков для ЭТОГО бэкенда. Объявите хуки в отдельном
+ * файле и положите одной переменной в конфиг (`EbelyConfig.hooks`).
+ * Передайте СВОЙ класс store параметром, чтобы `ctx` был типизирован:
+ *
+ *   import type { UserStore } from './userStore'
+ *   export const hooks: Hooks<UserStore> = (h) => {
+ *     h.posts.create.after(({ response, ctx }) => { … })
+ *   }
+ *
+ * (Параметр НЕ выводится из `ebely.userStore` намеренно: это создало
+ * бы цикл типов `ebely` ⇄ `Hooks`, т.к. `hooks` лежит внутри `ebely`.)
+ */
+export type Hooks<Store extends BaseStore = BaseStore> = (
+  h: EbelyHookTree<Store>,
+) => void
+
+/**
+ * База `World` — это сконфигурированный `ebely.worldStore` (или пустой
+ * `BaseStore`, если не задан). Поэтому `world.<сценарий>()` и
+ * `world.get/set` доступны и типизированы ровно как у пользователя,
+ * только область — весь мир. Тип берётся из `ebely` тем же приёмом, что
+ * и `Store` (никаких рантайм-условий — см. ARCHITECTURE.md §8).
+ */
+type ConfiguredWorldStore =
+  typeof ebely extends { worldStore: new () => infer I extends BaseStore }
+    ? I
+    : BaseStore
+const WorldStoreBase = ((ebely as { worldStore?: new () => BaseStore })
+  .worldStore ?? BaseStore) as new () => ConfiguredWorldStore
+
+export class World<
+  Store extends BaseStore = InstanceType<typeof ebely.userStore>,
+> extends WorldStoreBase {
+  /**
+   * Общий реестр хуков. Регистрация — статическая (один раз из конфига),
+   * но `ctx` подставляется в момент запроса = store конкретного юзера.
+   */
+  private hookRegistry = new HookRegistry()
+
+  constructor(
+    public args: {
+      /** URL бэкенда. Если не задан — берётся ebely.url из конфига. */
+      url?: string
+      /** Класс-хранилище. Если не задан — берётся ebely.userStore. */
+      store?: new () => Store
+    } = {},
+  ) {
+    super()
+    const registrar = (ebely as { hooks?: (h: unknown) => void }).hooks
+    if (registrar) registrar(this.buildHookTree())
+    // world-store ходит АНОНИМНЫМ клиентом (без per-user заголовков);
+    // ctx хуков для таких вызовов = сам world.
+    ;(this as unknown as { api: unknown }).api = this.buildApiTree(
+      this.makeRequest({ headers: {}, store: this }),
+    )
+  }
+
+  /** Базовый URL с учётом server.url из схемы. */
+  private baseUrl(): string {
+    return (this.args.url ?? ebely.url).replace(/\/$/, '') + "/api"
+  }
+
+  private buildHookTree(): EbelyHookTree<Store> {
+    const r = this.hookRegistry
+    return {
+      "posts": {
+        "list": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "posts.list", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "posts.list", fn }),
+        },
+        "create": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "posts.create", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "posts.create", fn }),
+        },
+        "get": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "posts.get", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "posts.get", fn }),
+        },
+        "update": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "posts.update", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "posts.update", fn }),
+        },
+        "delete": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "posts.delete", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "posts.delete", fn }),
+        },
+      },
+      "auth": {
+        "register": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "auth.register", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "auth.register", fn }),
+        },
+        "confirm": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "auth.confirm", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "auth.confirm", fn }),
+        },
+      },
+      "admin": {
+        "clearDatabase": {
+          before: (fn: BeforeHook<Store>) => r.before({ key: "admin.clearDatabase", fn }),
+          after: (fn: AfterHook<Store>) => r.after({ key: "admin.clearDatabase", fn }),
+        },
+      },
+    } as unknown as EbelyHookTree<Store>
+  }
+
+  /**
+   * Создаёт `request`, замкнутый на заголовки и `store` (он же `ctx`
+   * хуков). Один и тот же движок и для пользователя, и для world.
+   */
+  private makeRequest(cfg: {
+    headers: Record<string, string>
+    store: BaseStore
+  }): RequestFn {
+    const baseUrl = this.baseUrl()
+    const registry = this.hookRegistry
+    const { headers: baseHeaders, store } = cfg
+
+    return async (req): Promise<{ status: number; body: unknown }> => {
+      const { method, path, opKey, input } = req
+
+      const hookReq = {
+        method,
+        path,
+        pathParams: { ...(input?.path ?? {}) },
+        query: { ...(input?.query ?? {}) },
+        body: input?.body,
+        headers: { ...baseHeaders },
+      }
+      await registry.runBefore({ key: opKey, request: hookReq, ctx: store })
+
+      let resolvedPath = path
+      for (const [k, v] of Object.entries(hookReq.pathParams)) {
+        resolvedPath = resolvedPath.replace(
+          `{${k}}`,
+          encodeURIComponent(String(v)),
+        )
+      }
+
+      const url = new URL(baseUrl + resolvedPath)
+      for (const [k, v] of Object.entries(hookReq.query)) {
+        if (v !== undefined) url.searchParams.set(k, String(v))
+      }
+
+      const hasBody = hookReq.body !== undefined
+      const response = await fetch(url, {
+        method,
+        headers: {
+          ...(hasBody ? { 'content-type': 'application/json' } : {}),
+          ...hookReq.headers,
+        },
+        body: hasBody ? JSON.stringify(hookReq.body) : undefined,
+      })
+
+      const text = await response.text()
+      let data: unknown
+      try {
+        data = text ? JSON.parse(text) : undefined
+      } catch {
+        data = text
+      }
+
+      await registry.runAfter({
+        key: opKey,
+        request: hookReq,
+        response: { status: response.status, body: data },
+        ctx: store,
+      })
+
+      return { status: response.status, body: data }
+    }
+  }
+
+  /** Дерево типизированных вызовов эндпоинтов поверх одного `request`. */
+  private buildApiTree(request: RequestFn) {
+    return {
+      "posts": {
+
+        /** List all posts */
+        "list": async (input?: {}): Promise<ApiResponse<{ 200: Array<{
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        }> }>> => {
+          const res = await request({
+            method: "GET",
+            path: "/posts",
+            opKey: "posts.list",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: Array<{
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        }> }>
+        },
+
+        /** Create a post */
+        "create": async (input: { body: {
+          "title": string
+          "content": string
+        } }): Promise<ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>> => {
+          const res = await request({
+            method: "POST",
+            path: "/posts",
+            opKey: "posts.create",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>
+        },
+
+        /** Get a single post by id */
+        "get": async (input: { path: { "id": string } }): Promise<ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>> => {
+          const res = await request({
+            method: "GET",
+            path: "/posts/{id}",
+            opKey: "posts.get",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>
+        },
+
+        /** Update a post */
+        "update": async (input: { path: { "id": string }; body?: {
+          "title"?: string
+          "content"?: string
+        } }): Promise<ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>> => {
+          const res = await request({
+            method: "PATCH",
+            path: "/posts/{id}",
+            opKey: "posts.update",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "id": string
+          "title": string
+          "content": string
+          "createdAt": string
+          "updatedAt": string
+        } }>
+        },
+
+        /** Delete a post */
+        "delete": async (input: { path: { "id": string } }): Promise<ApiResponse<{ 200: {
+          "success": boolean
+        } }>> => {
+          const res = await request({
+            method: "DELETE",
+            path: "/posts/{id}",
+            opKey: "posts.delete",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "success": boolean
+        } }>
+        },
+      },
+      "auth": {
+
+        /** Register (stub: echoes input) */
+        "register": async (input: { body: {
+          "email": string
+          "password": string
+        } }): Promise<ApiResponse<{ 200: {
+          "email": string
+          "password": string
+        } }>> => {
+          const res = await request({
+            method: "POST",
+            path: "/auth/register",
+            opKey: "auth.register",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "email": string
+          "password": string
+        } }>
+        },
+
+        /** Confirm registration code (stub: echoes input) */
+        "confirm": async (input: { body: {
+          "code": string
+        } }): Promise<ApiResponse<{ 200: {
+          "code": string
+        } }>> => {
+          const res = await request({
+            method: "POST",
+            path: "/auth/confirm",
+            opKey: "auth.confirm",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "code": string
+        } }>
+        },
+      },
+      "admin": {
+
+        /** Wipe all in-memory data */
+        "clearDatabase": async (input?: {}): Promise<ApiResponse<{ 200: {
+          "success": boolean
+        } }>> => {
+          const res = await request({
+            method: "POST",
+            path: "/admin/clear-database",
+            opKey: "admin.clearDatabase",
+            input: input as RequestInput,
+          })
+          return new ApiResponse(res) as unknown as ApiResponse<{ 200: {
+          "success": boolean
+        } }>
+        },
+      },
+    }
+  }
+
+  /**
+   * Создаёт «пользователя» — изолированный набор типизированных вызовов
+   * эндпоинтов, который под капотом ходит fetch-запросами. `store.api`
+   * указывает на то же дерево, поэтому методы-сценарии этого store
+   * (`fullRegister` и т.п.) ходят от лица именно этого пользователя.
+   */
+  createUser(userArgs: CreateUserArgs = {}) {
+    const StoreClass =
+      this.args.store ?? (ebely.userStore as unknown as new () => Store)
+    const store = new StoreClass()
+    const tree = this.buildApiTree(
+      this.makeRequest({ headers: { ...userArgs.headers }, store }),
+    )
+    ;(store as unknown as { api: unknown }).api = tree
+    return Object.assign(store, tree)
+  }
+}

package/clone/tests/ebely/handlers.ts

@@ -0,0 +1,19 @@
+// Переиспользуемые именованные хендлеры. Типизируются библиотечными
+// дженериками `BeforeHook` / `AfterHook` (привязаны к твоему `UserStore`),
+// поэтому один хендлер можно вешать на разные endpoint'ы из `hooks.ts`.
+
+import type { AfterHook, BeforeHook } from 'ebely'
+import type { UserStore } from './userStore'
+
+/** Логирует любой ответ: метод, путь, статус, тело. */
+export const logResponse: AfterHook<UserStore> = ({ request, response }) => {
+  console.log(
+    `[${request.method}] ${request.path} → ${response.status}`,
+    response.body,
+  )
+}
+
+/** Подставляет общий заголовок трассировки в любой запрос. */
+export const withTrace: BeforeHook<UserStore> = ({ request }) => {
+  request.headers['x-trace'] = 'demo'
+}

package/clone/tests/ebely/hooks.ts

@@ -0,0 +1,28 @@
+// Хуки before/after для этого бэкенда. Файл ПОЛНОСТЬЮ типизирован: тип
+// `Hooks` экспортирует сгенерированный клиент (`generated.ts`), поэтому
+// `h.posts.create` автокомплитится, `response.body.id` типизирован, а
+// `ctx` — это твой `UserStore`.
+//
+// Регистрировать можно где угодно (это просто функция) — кладётся одной
+// переменной в конфиг (`ebely.ts`). Вызывается один раз при `new World()`.
+// Важно: `ctx` внутри хука — store КОНКРЕТНОГО пользователя, сделавшего
+// запрос, поэтому запись в переменные не «течёт» между пользователями.
+
+import type { Hooks } from './generated'
+import type { UserStore } from './userStore'
+import { logResponse } from './handlers'
+
+export const hooks: Hooks<UserStore> = (h) => {
+  // после создания поста — сохранить id в переменные ИМЕННО этого юзера
+  h.posts.create.after(({ response, ctx }) => {
+    ctx.set({ key: 'lastPostId', value: response.body.id })
+  })
+
+  // перед получением поста — подставить заголовок (before может править запрос)
+  h.posts.get.before(({ request }) => {
+    request.headers['x-trace'] = 'demo'
+  })
+
+  // несколько хуков на один endpoint складываются в очередь
+  h.posts.create.after(logResponse)
+}

package/clone/tests/ebely/userStore.ts

@@ -0,0 +1,56 @@
+// Внутренние переменные и СЦЕНАРИИ одного пользователя.
+//
+// Второй дженерик `BaseStore<Vars, WorldApi>` даёт `this.api` —
+// типизированное дерево вызовов эндпоинтов ОТ ЛИЦА ЭТОГО пользователя
+// (его заголовки, его переменные, его `ctx` в хуках). Поэтому
+// многошаговую подготовку (регистрация → подтверждение по коду) можно
+// спрятать за одним методом `fullRegister`, а в тестах звать его одной
+// строкой. `WorldApi` — `import type` → рантайм-цикла нет (как hooks.ts).
+
+import { BaseStore } from "ebely"
+import type { WorldApi } from "./generated"
+
+export type InternalVariable = {
+    email: string
+    password: string
+    accessToken: string
+    deviceId: string
+    telegramUsername: string
+    createdPosts: { postId: string; date: string }[]
+    lastPostId: string
+}
+
+export class UserStore extends BaseStore<InternalVariable, WorldApi> {
+    /** Пример производного метода: id первого созданного поста. */
+    public getFirstPostId(): string | undefined {
+        const createdPosts = this.get({ key: "createdPosts" })
+        return createdPosts?.[0]?.postId
+    }
+
+    /**
+     * Сценарий: полная регистрация одним вызовом. Под капотом — серия
+     * эндпоинтов (register → confirm), как было бы в реальном флоу с
+     * кодом из письма. Тест зовёт это одной строкой и не дублирует шаги.
+     */
+    public async fullRegister(args: {
+        email: string
+        password: string
+    }): Promise<void> {
+        const { email, password } = args
+
+        const registered = await this.api.auth.register({
+            body: { email, password },
+        })
+        registered.assert(200, { email })
+
+        // «код из письма» — здесь просто заглушка (бэкенд его не проверяет)
+        const confirmed = await this.api.auth.confirm({
+            body: { code: "0000" },
+        })
+        confirmed.assert(200)
+
+        this.set({ key: "email", value: email })
+        this.set({ key: "password", value: password })
+        this.set({ key: "accessToken", value: `token-for-${email}` })
+    }
+}

package/clone/tests/ebely/worldStore.ts

@@ -0,0 +1,26 @@
+// Внутренние переменные и СЦЕНАРИИ уровня WORLD — то же, что
+// `userStore.ts`, но область не «один пользователь», а весь мир.
+// Экземпляр этого класса и есть `world` (генерируемый `World` наследует
+// его), поэтому всё объявленное здесь доступно как `world.<...>()`.
+//
+// `this.api` здесь — АНОНИМНЫЙ клиент (без per-user заголовков): сценарии
+// подготовки/очистки бьют по бэкенду «от имени мира». `WorldApi`
+// импортируется как `import type` → рантайм-цикла нет (см. hooks.ts /
+// ARCHITECTURE.md §8).
+
+import { BaseStore } from "ebely"
+import type { WorldApi } from "./generated"
+
+export type WorldVariable = {
+    /** Сколько раз за прогон чистили базу — пример world-переменной. */
+    resets: number
+}
+
+export class WorldStore extends BaseStore<WorldVariable, WorldApi> {
+    /** Сценарий: очистить базу одним вызовом `world.clearDatabase()`. */
+    public async clearDatabase(): Promise<void> {
+        const res = await this.api.admin.clearDatabase()
+        res.assert(200, { success: true })
+        this.set({ key: "resets", value: (this.get({ key: "resets" }) ?? 0) + 1 })
+    }
+}