@brickflow/http 0.0.15 → 0.0.16

package/README.md

@@ -1,425 +1,390 @@
 # @brickflow/http
 
-Minimal HTTP package used in this repo for:
+Минимальный HTTP-пакет для brickflow:
 
-- low-level HTTP transport via `createHttp`
-- Nuxt async state wrapper via `createUseHttp`
-- reusable endpoint factory via `createGet`
-- project-level typing through `declare module '@brickflow/http'`
+- `createHttp` для низкоуровневых `GET`/`POST`
+- `createUseHttp` для Nuxt state-обёртки с cache, SSR и ручным `fetch`
+- `defineGet` для типизированных endpoint-фабрик
+- `createUseCase` для DI-паттерна в доменных модулях
 
-This package does not know your API schema by default. The schema and error type are configured in the consumer project through `type.d.ts`.
+Актуальные примеры в репозитории лежат в `apps/playground`.
 
 ## Exports
 
-From `@brickflow/http`:
+Рекомендуемый импорт:
+
+```ts
+import { createHttp, createUseHttp, createUseCase, defineGet } from '@brickflow/http'
+```
+
+Из пакета также экспортируются:
 
-- `createHttp`
 - `createURL`
 - `hashData`
-- HTTP types: `HttpClient`, `HttpError`, `HttpKey`, `HttpParam`, `HttpResponse`, `HttpResponseData`, `HttpSuccessData`
+- типы `HttpClient`, `HttpConfig`, `HttpEndpoint`, `HttpKey`, `HttpParam`, `HttpResponse`, `HttpResponseData`
+- Nuxt-типы `UseHttpFn`, `UseHttpOptions`, `UseHttpResult`
 
-From `@brickflow/http/nuxt`:
+Сабпуть `@brickflow/http/nuxt` остаётся доступным, но в текущей кодовой базе `playground` использует импорты из корня.
 
-- `createUseHttp`
-- `createGet`
-- Nuxt types: `UseHttpOptions`, `UseHttpResult`, `UseHttpFn`
+## Типизация API
 
-## 1. Configure API types in `type.d.ts`
+Пакет не знает схему вашего API заранее. Её нужно объявить в проекте через `declare module '@brickflow/http'`.
 
-In this repo the typing is configured in `types/http.d.ts`.
+Актуальный пример из `apps/playground/types/http.d.ts`:
 
 ```ts
-import type { Convention, ConventionKeys } from 'convention'
-
-type BrickHttpError = Exclude<Convention<ConventionKeys>, { status: 'success' }>
-type BrickHttpSchema = {
-  [TKey in ConventionKeys]: Convention<TKey>
+import type { HttpKey, HttpResponseData } from '@brickflow/http'
+
+type Convention = {
+  '/api/http-error-demo': null
+  '/products':
+    | {
+        limit: number
+        products: {
+          category: string
+          id: number
+          price: number
+          rating: number
+          thumbnail: string
+          title: string
+        }[]
+        skip: number
+        total: number
+      }
+    | {
+        message: 'error'
+      }
 }
 
 declare module '@brickflow/http' {
-  interface HttpTypeConfig {
-    endpoints: BrickHttpSchema
-    error: BrickHttpError
+  interface HttpConfig<TKey extends HttpKey = HttpKey> {
+    ignore?: (data: HttpResponseData<TKey>) => boolean
   }
+
+  interface HttpEndpoint extends Convention {}
 }
+
+export {}
 ```
 
-What this gives:
+Что это даёт:
 
-- `HttpKey` becomes your endpoint union
-- `HttpResponseData<'some/endpoint'>` becomes the response type for that endpoint
-- `HttpSuccessData<'some/endpoint'>` becomes response without the configured error branch
-- `UseHttpResult<T, P>['error']` is inferred from `HttpTypeConfig['error']`
+- `HttpKey` становится union из endpoint-ключей
+- `httpClient.get('/products')` получает корректный тип ответа
+- `createGet<Params>()('/products')` наследует тот же контракт
+- `HttpConfig` можно расширять своими полями, как в playground через `ignore`
 
-This is the main place where project typing should live.
+Если нужен типизированный `error` в `UseHttpResult`, дополнительно расширьте `HttpErrorMap`. По умолчанию `error` имеет тип `never`, а разделение между `data` и `error` зависит только от runtime `isError`.
 
-## 2. Create low-level HTTP client
+## createHttp
 
-Real usage from `plugins/01.di.ts`:
+Актуальный пример из `apps/playground/plugins/01.di.ts`:
 
 ```ts
 import { createHttp } from '@brickflow/http'
 
+import { handlePlaygroundResponse } from '~/core/http-error'
+
 const httpClient = createHttp({
-  baseURL: apiUrl,
-  headers: () => ({
-    'Client-Env': config.public.isDev ? 'development' : undefined,
-    'Client-Lang': String(locale.value ?? 'en'),
-    'Client-Socket-Id': socketClient?.io.id || '',
-    'X-Requested-With': 'XMLHttpRequest',
-  }),
-  onResponseError: responseInterceptor,
+  baseURL: 'https://dummyjson.com',
+  headers: {
+    'X-Playground-Http': 'playground-runtime',
+  },
+  onResponse: handlePlaygroundResponse,
 })
 ```
 
-Available options:
+Поддерживаемые опции:
 
-- `baseURL`
-- `fetch`
-- `headers`
-- `onResponseError`
-- `requestInit`
-- `timeout`
+- `baseURL: string`
+- `arrayMode?: 'json' | 'repeat'`
+- `fetch?: typeof fetch`
+- `headers?: Record<string, string | undefined> | (() => Record<string, string | undefined>)`
+- `onResponse?: (response) => void | Promise<void>`
+- `timeout?: number`
 
-`createHttp` returns:
+### GET
 
 ```ts
-interface HttpClient {
-  get(url, config?)
-  post(url, data?, config?)
-}
+const response = await httpClient.get('/products', {
+  params: {
+    limit: 10,
+  },
+  retry: {
+    delay: 300,
+    retries: 3,
+  },
+})
 ```
 
-## 3. Use `HttpClient` directly
+Особенности:
 
-Used in domain methods that do not need cached async state.
+- query строится из `params`
+- `GET` поддерживает retry для `429` и `5xx`
+- delay экспоненциальный: `delay * 2 ** attempt`
+- `signal` можно передать как один `AbortSignal` или массив `AbortSignal[]`
 
-Example from `domains/content/use-case.ts`:
+### POST
 
 ```ts
-async create(title: string, type: string, description?: string) {
-  const { data } = await httpClient.post('content/create', {
-    description,
-    title,
-    type,
-  })
-
-  return data
-}
+const { data } = await httpClient.post('/api/http-error-demo')
 ```
 
-Another example:
+Для `POST`:
+
+- `Record<string, unknown>` сериализуется в JSON
+- `FormData` отправляется как есть
+- retry нет
+- если response не JSON, пакет вернёт пустой объект в `data`
+
+### Расширение `HttpConfig`
+
+Так как `HttpConfig` расширяемый, можно прокидывать свои поля в запрос и читать их в `onResponse`.
+
+Пример из playground:
 
 ```ts
-async updateType(itemId: string, type: string) {
-  const { data } = await httpClient.post('content/update-type', {
-    itemId,
-    type,
-  })
+httpClient.get('/products', {
+  ignore: (data) => data?.limit === 20,
+})
+```
 
-  return data
+```ts
+export function handlePlaygroundResponse(
+  response: Parameters<NonNullable<CreateHttpOptions['onResponse']>>[0],
+): void {
+  console.log(response.config.ignore?.(response.data))
 }
 ```
 
-Use this style when:
+## createUseHttp
 
-- request is one-shot
-- you do not need `pending`, `hasFirstData`, cache, SSR sync, or `fetch()`
+В `apps/playground/core/http.ts` app-level инстанс создаётся один раз:
 
-## 4. Create Nuxt `useHttp`
+```ts
+import { createUseHttp, defineGet } from '@brickflow/http'
 
-In this repo the app-level `useHttp` is created once in `core/util.ts`:
+import { dbDeleteKeysWithPart, dbGet, dbSafeSet } from './indexdb'
 
-```ts
-import { createUseHttp } from '@brickflow/http/nuxt'
+const CACHE_DB_NAME = 'smart-cache-v2'
+const CACHE_STORE_NAME = 'playground-http'
 
 const useHttp = createUseHttp({
   getCache: () => ({
-    deleteKeysWithPart: async (part) => await dbDeleteKeysWithPart(part, 'smart-cache-v2', STORE_NAME),
-    get: async (key) => await dbGet(key, 'smart-cache-v2', STORE_NAME),
-    set: async (key, value, ttl) => await dbSafeSet(key, value, 'smart-cache-v2', STORE_NAME, ttl),
+    deleteKeysWithPart: async (part: string) => await dbDeleteKeysWithPart(part, CACHE_DB_NAME, CACHE_STORE_NAME),
+    get: async <T>(key: string) => await dbGet<T>(key, CACHE_DB_NAME, CACHE_STORE_NAME),
+    set: async <T>(key: string, value: T, ttl: number) =>
+      await dbSafeSet<T>(key, value, CACHE_DB_NAME, CACHE_STORE_NAME, ttl),
   }),
   getHttpClient: () => useNuxtApp().$http,
-  isDev: () => useRuntimeConfig().public.isDev,
+  isDev: () => false,
 })
-```
-
-Dependencies:
-
-- `getHttpClient`
-- `getCache`
-- `isError`
-- `isDev`
-- `ttl`
-- `channelName`
 
-`isError` can be set globally here if your project needs a custom runtime error predicate.
+export const createGet = defineGet(useHttp)
+```
 
-## 5. Bind `createGet` once
+Зависимости:
 
-The package exports `createGet(useHttp)`, which builds typed endpoint helpers on top of your local `useHttp`.
+- `getHttpClient` обязательно
+- `getCache` опционально
+- `isDev` опционально
+- `isError` опционально
+- `ttl` опционально
+- `channelName` опционально
 
-Real usage from `core/util.ts`:
+`createUseHttp` возвращает функцию `useHttp(options)`, которая создаёт реактивное состояние запроса:
 
-```ts
-import { createGet as createHttpGet, createUseHttp } from '@brickflow/http/nuxt'
+- `data`
+- `error`
+- `pending`
+- `pendingCache`
+- `hasFirstData`
+- `hasFreshData`
+- `fetch(params?, { signal? })`
 
-const useHttp = createUseHttp({ ... })
+### Опции useHttp
 
-export const createGet = createHttpGet(useHttp)
-```
+- `url`
+- `initParams`
+- `mapParams`
+- `effect`
+- `isError`
+- `lazy`
+- `server`
 
-After that you can reuse `createGet` in domain files.
+`effect(data, config)` вызывается и для cache, и для fresh-response:
 
-## 6. Create typed GET endpoints
+- `config.cached === true` для cache
+- `config.cached === false` для сети
+- `config.params` содержит уже применённые params
 
-### Without params
+## defineGet
 
-Example from `domains/storage/use-case.ts`:
+`defineGet` связывает app-level `useHttp` с endpoint-фабриками:
 
 ```ts
-plans: createGet()('storage/plans')
-```
-
-### With params
-
-Example from `domains/feed/use-case.ts`:
+const useHttp = createUseHttp({ ... })
 
-```ts
-home: createGet<{
-  category?: 'fresh' | 'popular' | 'recommended' | 'updated'
-  limit: number
-  offset: number
-}>()('feed/home')
+export const createGet = defineGet(useHttp)
 ```
 
-### With `ignore`
-
-Example from `domains/content/use-case.ts`:
+Дальше в домене можно описывать запросы коротко и типизированно:
 
 ```ts
-analytics: createGet<{
-  itemId: string
-  period: '7d' | '28d' | '90d'
-}>()('content/analytics', {
-  ignore(res) {
-    if (res.data.kind === 'no_auth') {
-      return true
-    }
-
-    return false
-  },
-})
+products: createGet<{
+  limit: number
+}>()('/products')
 ```
 
-### With `effect`
+`defineGet` поддерживает два слоя настроек:
 
-Example from `domains/root/use-case.ts`:
+1. Базовые настройки endpoint-а при объявлении:
 
 ```ts
-main: createGet()('root/main', {
-  effect(data, config) {
-    if (data.status === 'error') {
-      return
-    }
-
-    if (!config.cached) {
-      userStore.setUser(data.user)
-      userStore.setRegion(data.region)
-    }
-  },
+const products = createGet<{ limit: number }>()('/products', {
+  mapParams: (params) => ({
+    limit: params?.limit ?? 10,
+  }),
 })
 ```
 
-### With `effect` and success handling
-
-Example from `domains/storage/use-case.ts`:
+2. Runtime-опции при вызове:
 
 ```ts
-current: createGet()('storage/current', {
-  effect(data) {
-    if (data.status === 'success') {
-      storageStore.setCurrentPlan(data.plan)
-    }
-  },
+const productsHttp = await products({
+  initParams: { limit: 20 },
+  lazy: true,
+  server: false,
 })
 ```
 
-## 7. Consume endpoint state in components
+Если `effect`, `mapParams` или `isError` указаны и при объявлении, и при вызове, пакет объединяет их так:
 
-### Create request object
+- `effect` вызывает оба обработчика
+- `isError` из runtime имеет приоритет
+- `mapParams` из runtime имеет приоритет
 
-Example from `components/Search/index.vue`:
+## createUseCase
 
-```ts
-const searchFastHttp = await app.$di.search.fast({
-  lazy: true,
-  server: false,
-})
-```
-
-### Trigger fetch manually
+В playground доменный модуль собирается через `createUseCase`:
 
 ```ts
-await searchFastHttp.fetch({
-  text: searchQuery.value,
-})
-```
+import { createUseCase } from '@brickflow/http'
 
-### Read `data`
+import { createGet } from '~/core/http'
 
-```ts
-const data = searchFastHttp.data
+export default createUseCase()(({ httpClient }) => {
+  return {
+    async apiError() {
+      const { data } = await httpClient.post('/api/http-error-demo')
+      return data
+    },
 
-if (data?.status === 'success') {
-  items.value = data.items
-  users.value = data.users
-}
+    products: createGet<{
+      limit: number
+    }>()('/products'),
+  }
+})
 ```
 
-### Read loading flags
+Это даёт простой контракт для DI: use-case получает `httpClient`, а внутри может смешивать:
 
-Example from `components/ProfileMyGrid/index.vue`:
+- прямые mutation/one-shot запросы через `httpClient`
+- stateful GET-запросы через `createGet`
 
-```vue
-:loading="myContentHttp.pending || myContentHttp.pendingCache"
-```
+## Использование в компоненте
 
-### Use `hasFirstData`
+Актуальный пример из `apps/playground/pages/index.vue`:
 
 ```vue
-v-if="!myContentHttp.pending && myContentHttp.hasFirstData && items.length === 0"
+<script lang="ts" setup>
+  const app = useNuxtApp()
+  const httpProducts = await app.$di.product.products({
+    lazy: true,
+  })
+</script>
+
+<template>
+  <button
+    type="button"
+    @click="httpProducts.fetch()"
+  >
+    {{ httpProducts.hasFirstData }} Action
+  </button>
+
+  {{ httpProducts.data }}
+</template>
 ```
 
-## 8. `effect` semantics
+Типичный сценарий:
 
-`effect` receives the full response payload.
+1. Создать request-state через `await endpoint({ ...options })`
+2. Если `lazy: true`, вызвать `fetch()` вручную
+3. Читать `data`, `error`, `pending`, `pendingCache`
 
-That means:
-
-- it is called for success
-- it is called for error
-- you can branch on `data.status`
-- `config.cached` tells whether the payload came from cache
-- `config.params` contains mapped params used for the request
-
-Example from `pages/profile/[username].vue`:
+Пример с параметрами:
 
 ```ts
-const profileHttp = await app.$di.profile.info({
-  effect(data) {
-    if (data.status === 'error' && data.kind === 'not_found') {
-      showError(createError({
-        fatal: true,
-        statusCode: 404,
-        statusMessage: 'Page Not Found',
-      }))
-    }
-  },
+const productsHttp = await app.$di.product.products({
   initParams: {
-    username: String(profileParam.value),
+    limit: 10,
   },
-  server: true,
+  lazy: true,
 })
-```
-
-## 9. `data` and `error`
 
-`UseHttpResult<T, P>` is split like this:
-
-- `data`: success payload only
-- `error`: configured project error payload only
-
-Internally the split is done by runtime error predicate:
-
-- global `isError` from `createUseHttp(...)`
-- or per-request `isError`
-- fallback: `payload.status === 'error'`
-
-Important:
-
-- runtime error predicate does not reconfigure TypeScript types
-- TypeScript error type comes from `declare module '@brickflow/http'`
-
-## 10. Supported request options
-
-For `useHttp` / `createGet`:
-
-- `url`
-- `initParams`
-- `mapParams`
-- `effect`
-- `ignore`
-- `isError`
-- `lazy`
-- `server`
-
-Example with `initParams`:
-
-```ts
-const myContentHttp = await app.$di.content.my({
-  initParams: {
-    limit: props.limit,
-    offset: 0,
-    order: selectedOrder.value,
-    orderColumn: 'date',
-    type: selectedType.value,
-  },
+await productsHttp.fetch({
+  limit: 30,
 })
 ```
 
-Example with `fetch(...)` overriding params:
+## Cache и синхронизация между вкладками
 
-```ts
-await myContentHttp.fetch({
-  limit: props.limit,
-  offset,
-  order: selectedOrder.value,
-  orderColumn: 'date',
-  type: selectedType.value,
-})
-```
+Если передан `getCache`, `createUseHttp`:
 
-## 11. Cache behavior
+- сначала пробует отдать cache
+- вызывает `effect(..., { cached: true })` для cache-ответа
+- затем делает сетевой запрос
+- сохраняет успешный ответ в cache
+- при изменении хеша удаляет связанные cache-ключи через `deleteKeysWithPart`
 
-When `getCache` is provided, `createUseHttp`:
+Дополнительно пакет использует `BroadcastChannel` и синхронизирует свежие успешные GET-ответы между вкладками.
 
-- tries cached value first
-- calls `effect(..., { cached: true })` for cached payload
-- then performs fresh request
-- stores success response in cache
-- invalidates related keys when response hash changes
+По умолчанию:
 
-In this repo the cache is backed by IndexedDB in `core/util.ts`.
+- `ttl = 7 дней`
+- `channelName = 'http-tab-sync'`
 
-## 12. URL and hash helpers
+## SSR
 
-The package also exports helpers used by the current implementation:
+Если вызвать endpoint с `server: true`, на сервере пакет использует `useLazyAsyncData`, сохраняет результат в `useState` и переиспользует его на клиенте после гидрации.
+
+Это полезно для страниц, где нужен первый ответ уже в SSR, но тот же контракт `data / pending / fetch` должен остаться и на клиенте.
+
+## Вспомогательные функции
 
 ```ts
 import { createURL, hashData } from '@brickflow/http'
 ```
 
-`createURL(url, params)` builds query strings.
-
-`hashData(data)` computes response hash for cache invalidation.
+- `createURL(url, params)` строит query string
+- `hashData(data)` считает SHA-1 через `crypto.subtle`, а без него использует fallback-хеш
 
-## 13. Recommended usage in this repo
+## Когда что использовать
 
-Use `createHttp` when:
+`createHttp`:
 
-- you need direct `get/post`
-- you are writing mutations or one-shot calls
+- POST/мутации
+- one-shot запросы
+- когда не нужен reactive state
 
-Use `createUseHttp` + `createGet` when:
+`createUseHttp` + `defineGet`:
 
-- you need SSR-aware async state
-- you need `pending`, `pendingCache`, `hasFirstData`, `hasFreshData`
-- you need cache integration
-- you want reusable typed endpoint factories in domain modules
+- SSR-friendly GET
+- cache и `pendingCache`
+- повторное использование endpoint-описаний
+- ручной `fetch()`
 
-Use `type.d.ts` when:
+`createUseCase`:
 
-- you want to define endpoint keys
-- you want to define the project-wide error type
-- you want all consumers to infer the same API schema
+- доменные модули с DI
+- единый контракт для доступа к `httpClient`