@brickflow/http 0.0.14 → 0.0.16

package/README.md

@@ -1,406 +1,390 @@
-# `@brickflow/http`
+# @brickflow/http
 
-Nuxt HTTP module and typed client with:
+Минимальный HTTP-пакет для brickflow:
 
-- `NuxtApp.$http`
-- `useHttp()` auto-import
-- request/response middleware
-- retry and timeout support
-- optional client cache via IndexedDB
-- typed URL literals for `get`, `post`, and `useHttp`
+- `createHttp` для низкоуровневых `GET`/`POST`
+- `createUseHttp` для Nuxt state-обёртки с cache, SSR и ручным `fetch`
+- `defineGet` для типизированных endpoint-фабрик
+- `createUseCase` для DI-паттерна в доменных модулях
 
-## Install
+Актуальные примеры в репозитории лежат в `apps/playground`.
 
-```bash
-pnpm add @brickflow/http
-```
+## Exports
 
-## Nuxt Setup
+Рекомендуемый импорт:
 
 ```ts
-export default defineNuxtConfig({
-  modules: ['@brickflow/http'],
-})
+import { createHttp, createUseHttp, createUseCase, defineGet } from '@brickflow/http'
 ```
 
-With options:
+Из пакета также экспортируются:
+
+- `createURL`
+- `hashData`
+- типы `HttpClient`, `HttpConfig`, `HttpEndpoint`, `HttpKey`, `HttpParam`, `HttpResponse`, `HttpResponseData`
+- Nuxt-типы `UseHttpFn`, `UseHttpOptions`, `UseHttpResult`
+
+Сабпуть `@brickflow/http/nuxt` остаётся доступным, но в текущей кодовой базе `playground` использует импорты из корня.
+
+## Типизация API
+
+Пакет не знает схему вашего API заранее. Её нужно объявить в проекте через `declare module '@brickflow/http'`.
+
+Актуальный пример из `apps/playground/types/http.d.ts`:
 
 ```ts
-export default defineNuxtConfig({
-  modules: ['@brickflow/http'],
-  brickflowHttp: {
-    baseURL: 'https://api.example.com',
-    cache: true,
-    cacheDbName: 'smart-cache-v2',
-    cacheStoreName: 'data',
-    cacheTtlMs: 1000 * 60 * 60 * 24 * 7,
-    clientEnvHeader: true,
-    defaultHeaders: {
-      'X-App-Version': '1.0.0',
-    },
-    disableCacheInDev: true,
-    requestTimeoutMs: 80000,
-    retry: {
-      delay: 300,
-      retries: 3,
-    },
-  },
-})
-```
+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 HttpConfig<TKey extends HttpKey = HttpKey> {
+    ignore?: (data: HttpResponseData<TKey>) => boolean
+  }
 
-## Defaults
+  interface HttpEndpoint extends Convention {}
+}
 
-`brickflowHttp` defaults:
+export {}
+```
 
-| Option              | Default            |
-| ------------------- | ------------------ |
-| `baseURL`           | `''`               |
-| `cache`             | `true`             |
-| `cacheDbName`       | `'smart-cache-v2'` |
-| `cacheStoreName`    | `'data'`           |
-| `cacheTtlMs`        | `604800000`        |
-| `clientEnvHeader`   | `true`             |
-| `defaultHeaders`    | `{}`               |
-| `disableCacheInDev` | `true`             |
-| `requestTimeoutMs`  | `80000`            |
-| `retry.delay`       | `300`              |
-| `retry.retries`     | `3`                |
+Что это даёт:
 
-Runtime behavior:
+- `HttpKey` становится union из endpoint-ключей
+- `httpClient.get('/products')` получает корректный тип ответа
+- `createGet<Params>()('/products')` наследует тот же контракт
+- `HttpConfig` можно расширять своими полями, как в playground через `ignore`
 
-- `X-Requested-With: XMLHttpRequest` is added automatically
-- in dev, `Client-Env: development` is added when `clientEnvHeader` is enabled
-- `5xx` and `451` responses with `{ status: 'error' }` trigger Nuxt `showError()`
+Если нужен типизированный `error` в `UseHttpResult`, дополнительно расширьте `HttpErrorMap`. По умолчанию `error` имеет тип `never`, а разделение между `data` и `error` зависит только от runtime `isError`.
 
-## Basic Usage
+## createHttp
 
-Use `$http` in components, composables, or plugins:
+Актуальный пример из `apps/playground/plugins/01.di.ts`:
 
 ```ts
-const { $http } = useNuxtApp()
+import { createHttp } from '@brickflow/http'
 
-const response = await $http.get<{ id: string; name: string }>('/user', {
-  params: {
-    id: '42',
+import { handlePlaygroundResponse } from '~/core/http-error'
+
+const httpClient = createHttp({
+  baseURL: 'https://dummyjson.com',
+  headers: {
+    'X-Playground-Http': 'playground-runtime',
   },
+  onResponse: handlePlaygroundResponse,
 })
-
-if ('status' in response.data && response.data.status === 'error') {
-  console.error(response.data.message)
-} else {
-  console.log(response.data.name)
-}
 ```
 
-POST:
+Поддерживаемые опции:
 
-```ts
-const { $http } = useNuxtApp()
+- `baseURL: string`
+- `arrayMode?: 'json' | 'repeat'`
+- `fetch?: typeof fetch`
+- `headers?: Record<string, string | undefined> | (() => Record<string, string | undefined>)`
+- `onResponse?: (response) => void | Promise<void>`
+- `timeout?: number`
+
+### GET
 
-const response = await $http.post<{ ok: true }>(
-  '/posts',
-  {
-    title: 'Hello',
+```ts
+const response = await httpClient.get('/products', {
+  params: {
+    limit: 10,
   },
-  {
-    params: {
-      draft: true,
-    },
+  retry: {
+    delay: 300,
+    retries: 3,
   },
-)
+})
 ```
 
-## `useHttp()`
+Особенности:
 
-`useHttp()` is auto-imported and returns:
+- query строится из `params`
+- `GET` поддерживает retry для `429` и `5xx`
+- delay экспоненциальный: `delay * 2 ** attempt`
+- `signal` можно передать как один `AbortSignal` или массив `AbortSignal[]`
 
-- `data`
-- `error`
-- `pending`
-- `pendingCache`
-- `hasFirstData`
-- `hasFreshData`
-- `fetch()`
-
-Basic example:
+### POST
 
 ```ts
-const users = await useHttp<Array<{ id: string; name: string }>>({
-  server: true,
-  url: '/users',
-})
+const { data } = await httpClient.post('/api/http-error-demo')
 ```
 
-With params:
+Для `POST`:
 
-```ts
-const users = await useHttp<Array<{ id: string; name: string }>, { page: number }>({
-  initParams: {
-    page: 1,
-  },
-  url: '/users',
-})
+- `Record<string, unknown>` сериализуется в JSON
+- `FormData` отправляется как есть
+- retry нет
+- если response не JSON, пакет вернёт пустой объект в `data`
 
-await users.fetch({
-  page: 2,
-})
-```
+### Расширение `HttpConfig`
+
+Так как `HttpConfig` расширяемый, можно прокидывать свои поля в запрос и читать их в `onResponse`.
 
-With side effects:
+Пример из playground:
 
 ```ts
-const profile = await useHttp<{ id: string; name: string }>({
-  effect(payload, { cached }) {
-    if (!cached) {
-      console.log('fresh profile payload', payload)
-    }
-  },
-  url: '/profile',
+httpClient.get('/products', {
+  ignore: (data) => data?.limit === 20,
 })
 ```
 
-## Typed Routes
-
-If you want `'/users'` and other URL literals to infer `params`, `data`, `error`, and `body` automatically, extend the global `BrickflowHttpRouteMap`.
-
-Create a declaration file, for example `types/brickflow-http.d.ts`:
-
 ```ts
-import type { HttpErrorPayload } from '@brickflow/http'
-
-declare global {
-  interface BrickflowHttpRouteMap {
-    '/api/user': {
-      data: { id: string; name: string }
-      error: HttpErrorPayload & { code?: 'NOT_FOUND' }
-      params: { id: string }
-    }
-    '/api/posts': {
-      data: Array<{ id: string; title: string }>
-      params: { page?: number }
-    }
-    '/api/posts/create': {
-      body: { title: string }
-      data: { id: string }
-    }
-  }
+export function handlePlaygroundResponse(
+  response: Parameters<NonNullable<CreateHttpOptions['onResponse']>>[0],
+): void {
+  console.log(response.config.ignore?.(response.data))
 }
-
-export {}
 ```
 
-After that, `$http` and `useHttp()` infer types from the URL literal automatically.
+## createUseHttp
 
-Typed `get`:
+В `apps/playground/core/http.ts` app-level инстанс создаётся один раз:
 
 ```ts
-const { $http } = useNuxtApp()
+import { createUseHttp, defineGet } from '@brickflow/http'
 
-const response = await $http.get('/api/user', {
-  params: {
-    id: '42',
-  },
+import { dbDeleteKeysWithPart, dbGet, dbSafeSet } from './indexdb'
+
+const CACHE_DB_NAME = 'smart-cache-v2'
+const CACHE_STORE_NAME = 'playground-http'
+
+const useHttp = createUseHttp({
+  getCache: () => ({
+    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: () => false,
 })
+
+export const createGet = defineGet(useHttp)
 ```
 
-Typed `post`:
+Зависимости:
 
-```ts
-const { $http } = useNuxtApp()
+- `getHttpClient` обязательно
+- `getCache` опционально
+- `isDev` опционально
+- `isError` опционально
+- `ttl` опционально
+- `channelName` опционально
 
-await $http.post('/api/posts/create', {
-  title: 'New post',
-})
-```
+`createUseHttp` возвращает функцию `useHttp(options)`, которая создаёт реактивное состояние запроса:
 
-Typed `useHttp` without generics:
+- `data`
+- `error`
+- `pending`
+- `pendingCache`
+- `hasFirstData`
+- `hasFreshData`
+- `fetch(params?, { signal? })`
 
-```ts
-const posts = await useHttp({
-  initParams: {
-    page: 1,
-  },
-  url: '/api/posts',
-})
+### Опции useHttp
 
-await posts.fetch({
-  page: 2,
-})
-```
+- `url`
+- `initParams`
+- `mapParams`
+- `effect`
+- `isError`
+- `lazy`
+- `server`
 
-## Strict Client
+`effect(data, config)` вызывается и для cache, и для fresh-response:
 
-`$http` keeps a fallback overload for plain `string`, so unknown URLs are still allowed.
+- `config.cached === true` для cache
+- `config.cached === false` для сети
+- `config.params` содержит уже применённые params
 
-If you want to forbid unknown URLs completely:
+## defineGet
+
+`defineGet` связывает app-level `useHttp` с endpoint-фабриками:
 
 ```ts
-import { createStrictHttpClient } from '@brickflow/http'
+const useHttp = createUseHttp({ ... })
 
-const { $http } = useNuxtApp()
-const strictHttp = createStrictHttpClient($http)
+export const createGet = defineGet(useHttp)
+```
 
-await strictHttp.get('/api/user', {
-  params: { id: '42' },
-})
+Дальше в домене можно описывать запросы коротко и типизированно:
 
-// TypeScript error
-await strictHttp.get('/api/unknown')
+```ts
+products: createGet<{
+  limit: number
+}>()('/products')
 ```
 
-If you want typed overloads on a standalone client while keeping the plain `string` fallback:
+`defineGet` поддерживает два слоя настроек:
 
-```ts
-import { createHttpClient, createTypedHttpClient } from '@brickflow/http'
+1. Базовые настройки endpoint-а при объявлении:
 
-const http = createTypedHttpClient(
-  createHttpClient({
-    baseURL: 'https://api.example.com',
+```ts
+const products = createGet<{ limit: number }>()('/products', {
+  mapParams: (params) => ({
+    limit: params?.limit ?? 10,
   }),
-)
+})
 ```
 
-## Dynamic Base URL
-
-Standalone client supports a dynamic resolver:
+2. Runtime-опции при вызове:
 
 ```ts
-const tenantStore = useTenantStore()
-
-const http = createHttpClient({
-  baseURL: () => tenantStore.apiBaseUrl,
+const productsHttp = await products({
+  initParams: { limit: 20 },
+  lazy: true,
+  server: false,
 })
 ```
 
-In Nuxt, the better option is request middleware, because it works for both `$http` and `useHttp()`:
+Если `effect`, `mapParams` или `isError` указаны и при объявлении, и при вызове, пакет объединяет их так:
+
+- `effect` вызывает оба обработчика
+- `isError` из runtime имеет приоритет
+- `mapParams` из runtime имеет приоритет
+
+## createUseCase
+
+В playground доменный модуль собирается через `createUseCase`:
 
 ```ts
-import { addHttpRequestMiddleware } from '@brickflow/http'
+import { createUseCase } from '@brickflow/http'
 
-export default defineNuxtPlugin(() => {
-  const apiBaseUrl = useState('api-base-url', () => 'https://dummyjson.com')
+import { createGet } from '~/core/http'
 
-  addHttpRequestMiddleware((request) => {
-    if (request.url.startsWith('/products') || request.url.startsWith('/test')) {
-      request.baseURL = apiBaseUrl.value
-    }
-  })
+export default createUseCase()(({ httpClient }) => {
+  return {
+    async apiError() {
+      const { data } = await httpClient.post('/api/http-error-demo')
+      return data
+    },
+
+    products: createGet<{
+      limit: number
+    }>()('/products'),
+  }
 })
 ```
 
-Then the same request code can stay relative:
-
-```ts
-const products = await useHttp({
-  url: '/products',
-})
+Это даёт простой контракт для DI: use-case получает `httpClient`, а внутри может смешивать:
 
-const { $http } = useNuxtApp()
-await $http.get('/test')
-```
+- прямые mutation/one-shot запросы через `httpClient`
+- stateful GET-запросы через `createGet`
 
-The playground app contains a live example that switches the same typed requests between:
+## Использование в компоненте
 
-- direct `https://dummyjson.com`
-- local proxy `/api/dummyjson`
+Актуальный пример из `apps/playground/pages/index.vue`:
 
-See:
+```vue
+<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>
+```
 
-- [apps/playground/app/pages/index.vue](/Users/andrii/Lab/personal/brickme/apps/playground/app/pages/index.vue:1)
-- [apps/playground/app/plugins/http-middleware.ts](/Users/andrii/Lab/personal/brickme/apps/playground/app/plugins/http-middleware.ts:1)
+Типичный сценарий:
 
-## Global Middleware
+1. Создать request-state через `await endpoint({ ...options })`
+2. Если `lazy: true`, вызвать `fetch()` вручную
+3. Читать `data`, `error`, `pending`, `pendingCache`
 
-Register middleware once and it will run for every request or response:
+Пример с параметрами:
 
 ```ts
-import { addHttpRequestMiddleware, addHttpResponseMiddleware } from '@brickflow/http'
-
-export default defineNuxtPlugin(() => {
-  addHttpRequestMiddleware((request) => {
-    request.headers.set('X-App-Version', '1.0.0')
-  })
+const productsHttp = await app.$di.product.products({
+  initParams: {
+    limit: 10,
+  },
+  lazy: true,
+})
 
-  addHttpResponseMiddleware((response, request) => {
-    if (response.status >= 500) {
-      console.error('HTTP error', request.url, response.status)
-    }
-  })
+await productsHttp.fetch({
+  limit: 30,
 })
 ```
 
-Request middleware can mutate:
+## Cache и синхронизация между вкладками
 
-- `baseURL`
-- `url`
-- `method`
-- `headers`
-- `body`
-- `params`
-- `signal`
-- `credentials`
+Если передан `getCache`, `createUseHttp`:
 
-Response middleware receives:
+- сначала пробует отдать cache
+- вызывает `effect(..., { cached: true })` для cache-ответа
+- затем делает сетевой запрос
+- сохраняет успешный ответ в cache
+- при изменении хеша удаляет связанные cache-ключи через `deleteKeysWithPart`
 
-- `response`
-- `request`
+Дополнительно пакет использует `BroadcastChannel` и синхронизирует свежие успешные GET-ответы между вкладками.
 
-You can remove middleware later:
+По умолчанию:
 
-```ts
-import { addHttpRequestMiddleware, removeHttpRequestMiddleware } from '@brickflow/http'
+- `ttl = 7 дней`
+- `channelName = 'http-tab-sync'`
 
-const middleware = (request: Parameters<typeof addHttpRequestMiddleware>[0]) => {
-  request.headers.set('X-Debug', '1')
-}
+## SSR
 
-addHttpRequestMiddleware(middleware)
-removeHttpRequestMiddleware(middleware)
-```
+Если вызвать endpoint с `server: true`, на сервере пакет использует `useLazyAsyncData`, сохраняет результат в `useState` и переиспользует его на клиенте после гидрации.
 
-## Standalone Client
+Это полезно для страниц, где нужен первый ответ уже в SSR, но тот же контракт `data / pending / fetch` должен остаться и на клиенте.
 
-You can use the client outside Nuxt injection:
+## Вспомогательные функции
 
 ```ts
-import { createHttpClient } from '@brickflow/http'
+import { createURL, hashData } from '@brickflow/http'
+```
 
-const http = createHttpClient({
-  baseURL: 'https://api.example.com',
-  requestTimeoutMs: 10000,
-  retry: {
-    delay: 250,
-    retries: 2,
-  },
-})
+- `createURL(url, params)` строит query string
+- `hashData(data)` считает SHA-1 через `crypto.subtle`, а без него использует fallback-хеш
 
-const response = await http.get<{ ok: true }>('/health')
-```
+## Когда что использовать
 
-With custom headers:
+`createHttp`:
 
-```ts
-const http = createHttpClient({
-  baseURL: async () => `https://${tenant.value}.api.example.com`,
-  createHeaders: async () => {
-    return {
-      Authorization: `Bearer ${token}`,
-    }
-  },
-})
-```
+- POST/мутации
+- one-shot запросы
+- когда не нужен reactive state
 
-## Exports
+`createUseHttp` + `defineGet`:
+
+- SSR-friendly GET
+- cache и `pendingCache`
+- повторное использование endpoint-описаний
+- ручной `fetch()`
+
+`createUseCase`:
 
-Main exports:
-
-- default Nuxt module
-- `createHttpClient`
-- `createTypedHttpClient`
-- `createStrictHttpClient`
-- `defineHttpRoutes`
-- `addHttpRequestMiddleware`
-- `addHttpResponseMiddleware`
-- `removeHttpRequestMiddleware`
-- `removeHttpResponseMiddleware`
-- public TypeScript types for client, config, middleware, payloads, and typed route maps
+- доменные модули с DI
+- единый контракт для доступа к `httpClient`