@brickflow/http 0.0.13 → 0.0.14

package/README.md

@@ -0,0 +1,406 @@
+# `@brickflow/http`
+
+Nuxt HTTP module and typed client with:
+
+- `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`
+
+## Install
+
+```bash
+pnpm add @brickflow/http
+```
+
+## Nuxt Setup
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@brickflow/http'],
+})
+```
+
+With options:
+
+```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,
+    },
+  },
+})
+```
+
+## Defaults
+
+`brickflowHttp` defaults:
+
+| 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:
+
+- `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()`
+
+## Basic Usage
+
+Use `$http` in components, composables, or plugins:
+
+```ts
+const { $http } = useNuxtApp()
+
+const response = await $http.get<{ id: string; name: string }>('/user', {
+  params: {
+    id: '42',
+  },
+})
+
+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()
+
+const response = await $http.post<{ ok: true }>(
+  '/posts',
+  {
+    title: 'Hello',
+  },
+  {
+    params: {
+      draft: true,
+    },
+  },
+)
+```
+
+## `useHttp()`
+
+`useHttp()` is auto-imported and returns:
+
+- `data`
+- `error`
+- `pending`
+- `pendingCache`
+- `hasFirstData`
+- `hasFreshData`
+- `fetch()`
+
+Basic example:
+
+```ts
+const users = await useHttp<Array<{ id: string; name: string }>>({
+  server: true,
+  url: '/users',
+})
+```
+
+With params:
+
+```ts
+const users = await useHttp<Array<{ id: string; name: string }>, { page: number }>({
+  initParams: {
+    page: 1,
+  },
+  url: '/users',
+})
+
+await users.fetch({
+  page: 2,
+})
+```
+
+With side effects:
+
+```ts
+const profile = await useHttp<{ id: string; name: string }>({
+  effect(payload, { cached }) {
+    if (!cached) {
+      console.log('fresh profile payload', payload)
+    }
+  },
+  url: '/profile',
+})
+```
+
+## 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 {}
+```
+
+After that, `$http` and `useHttp()` infer types from the URL literal automatically.
+
+Typed `get`:
+
+```ts
+const { $http } = useNuxtApp()
+
+const response = await $http.get('/api/user', {
+  params: {
+    id: '42',
+  },
+})
+```
+
+Typed `post`:
+
+```ts
+const { $http } = useNuxtApp()
+
+await $http.post('/api/posts/create', {
+  title: 'New post',
+})
+```
+
+Typed `useHttp` without generics:
+
+```ts
+const posts = await useHttp({
+  initParams: {
+    page: 1,
+  },
+  url: '/api/posts',
+})
+
+await posts.fetch({
+  page: 2,
+})
+```
+
+## Strict Client
+
+`$http` keeps a fallback overload for plain `string`, so unknown URLs are still allowed.
+
+If you want to forbid unknown URLs completely:
+
+```ts
+import { createStrictHttpClient } from '@brickflow/http'
+
+const { $http } = useNuxtApp()
+const strictHttp = createStrictHttpClient($http)
+
+await strictHttp.get('/api/user', {
+  params: { id: '42' },
+})
+
+// TypeScript error
+await strictHttp.get('/api/unknown')
+```
+
+If you want typed overloads on a standalone client while keeping the plain `string` fallback:
+
+```ts
+import { createHttpClient, createTypedHttpClient } from '@brickflow/http'
+
+const http = createTypedHttpClient(
+  createHttpClient({
+    baseURL: 'https://api.example.com',
+  }),
+)
+```
+
+## Dynamic Base URL
+
+Standalone client supports a dynamic resolver:
+
+```ts
+const tenantStore = useTenantStore()
+
+const http = createHttpClient({
+  baseURL: () => tenantStore.apiBaseUrl,
+})
+```
+
+In Nuxt, the better option is request middleware, because it works for both `$http` and `useHttp()`:
+
+```ts
+import { addHttpRequestMiddleware } from '@brickflow/http'
+
+export default defineNuxtPlugin(() => {
+  const apiBaseUrl = useState('api-base-url', () => 'https://dummyjson.com')
+
+  addHttpRequestMiddleware((request) => {
+    if (request.url.startsWith('/products') || request.url.startsWith('/test')) {
+      request.baseURL = apiBaseUrl.value
+    }
+  })
+})
+```
+
+Then the same request code can stay relative:
+
+```ts
+const products = await useHttp({
+  url: '/products',
+})
+
+const { $http } = useNuxtApp()
+await $http.get('/test')
+```
+
+The playground app contains a live example that switches the same typed requests between:
+
+- direct `https://dummyjson.com`
+- local proxy `/api/dummyjson`
+
+See:
+
+- [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
+
+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')
+  })
+
+  addHttpResponseMiddleware((response, request) => {
+    if (response.status >= 500) {
+      console.error('HTTP error', request.url, response.status)
+    }
+  })
+})
+```
+
+Request middleware can mutate:
+
+- `baseURL`
+- `url`
+- `method`
+- `headers`
+- `body`
+- `params`
+- `signal`
+- `credentials`
+
+Response middleware receives:
+
+- `response`
+- `request`
+
+You can remove middleware later:
+
+```ts
+import { addHttpRequestMiddleware, removeHttpRequestMiddleware } from '@brickflow/http'
+
+const middleware = (request: Parameters<typeof addHttpRequestMiddleware>[0]) => {
+  request.headers.set('X-Debug', '1')
+}
+
+addHttpRequestMiddleware(middleware)
+removeHttpRequestMiddleware(middleware)
+```
+
+## Standalone Client
+
+You can use the client outside Nuxt injection:
+
+```ts
+import { createHttpClient } from '@brickflow/http'
+
+const http = createHttpClient({
+  baseURL: 'https://api.example.com',
+  requestTimeoutMs: 10000,
+  retry: {
+    delay: 250,
+    retries: 2,
+  },
+})
+
+const response = await http.get<{ ok: true }>('/health')
+```
+
+With custom headers:
+
+```ts
+const http = createHttpClient({
+  baseURL: async () => `https://${tenant.value}.api.example.com`,
+  createHeaders: async () => {
+    return {
+      Authorization: `Bearer ${token}`,
+    }
+  },
+})
+```
+
+## Exports
+
+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

package/dist/module.d.mts

@@ -0,0 +1,73 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { HttpRetryConfig } from '../dist/runtime/utils/shared.js';
+export { CreateHttpClientOptions, GetConfig, HttpBaseURL, HttpBaseURLResolver, HttpClient, HttpConfig, HttpErrorPayload, HttpParam, HttpPayload, HttpRequestContext, HttpRequestMiddleware, HttpResponse, HttpResponseMiddleware, HttpRetryConfig, HttpRuntimeConfig, PostConfig } from '../dist/runtime/utils/shared.js';
+export { createHttpClient } from '../dist/runtime/http/client.js';
+export { addHttpRequestMiddleware, addHttpResponseMiddleware, removeHttpRequestMiddleware, removeHttpResponseMiddleware } from '../dist/runtime/utils/middleware.js';
+export { HttpRouteBody, HttpRouteData, HttpRouteDefinition, HttpRouteError, HttpRouteMap, HttpRouteParams, ResolveHttpRoute, StrictTypedHttpClient, TypedGetConfig, TypedHttpClient, TypedHttpResponse, TypedPostConfig, createStrictHttpClient, createTypedHttpClient, defineHttpRoutes } from '../dist/runtime/utils/typed.js';
+
+interface ModuleOptions {
+    /**
+     * Base URL used by the injected Nuxt HTTP client.
+     *
+     * @default ''
+     */
+    baseURL?: string;
+    /**
+     * Enables client-side IndexedDB caching in `useHttp()`.
+     *
+     * @default true
+     */
+    cache?: boolean;
+    /**
+     * IndexedDB database name used for cached responses.
+     *
+     * @default 'smart-cache-v2'
+     */
+    cacheDbName?: 'smart-cache-v2';
+    /**
+     * IndexedDB store name used for cached responses.
+     *
+     * @default 'data'
+     */
+    cacheStoreName?: string;
+    /**
+     * Cache TTL in milliseconds.
+     *
+     * @default 604800000
+     */
+    cacheTtlMs?: number;
+    /**
+     * Adds `Client-Env: development` in dev mode.
+     *
+     * @default true
+     */
+    clientEnvHeader?: boolean;
+    /**
+     * Default headers merged into every request.
+     *
+     * @default {}
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Disables IndexedDB cache when `import.meta.dev` is enabled.
+     *
+     * @default true
+     */
+    disableCacheInDev?: boolean;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * @default 80000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Retry policy for GET requests on retryable responses and network failures.
+     *
+     * @default { delay: 300, retries: 3 }
+     */
+    retry?: HttpRetryConfig;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "configKey": "brickflowHttp",
+  "name": "@brickflow/http",
+  "version": "0.0.14",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,59 @@
+import { defineNuxtModule, createResolver, addPlugin, addImportsDir } from '@nuxt/kit';
+export { createHttpClient } from '../dist/runtime/http/client.js';
+export { addHttpRequestMiddleware, addHttpResponseMiddleware, removeHttpRequestMiddleware, removeHttpResponseMiddleware } from '../dist/runtime/utils/middleware.js';
+export { createStrictHttpClient, createTypedHttpClient, defineHttpRoutes } from '../dist/runtime/utils/typed.js';
+
+const DAY = 1e3 * 60 * 60 * 24;
+const defaultRuntimeConfig = {
+  baseURL: "",
+  cache: true,
+  cacheDbName: "smart-cache-v2",
+  cacheStoreName: "data",
+  cacheTtlMs: DAY * 7,
+  clientEnvHeader: true,
+  defaultHeaders: {},
+  disableCacheInDev: true,
+  requestTimeoutMs: 8e4,
+  retry: {
+    delay: 300,
+    retries: 3
+  }
+};
+const module$1 = defineNuxtModule({
+  defaults: defaultRuntimeConfig,
+  meta: {
+    compatibility: {
+      nuxt: ">=4.0.0"
+    },
+    configKey: "brickflowHttp",
+    name: "@brickflow/http"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const currentConfig = nuxt.options.runtimeConfig.public.brickflowHttp ?? {};
+    nuxt.options.runtimeConfig.public.brickflowHttp = {
+      ...defaultRuntimeConfig,
+      ...currentConfig,
+      ...options,
+      defaultHeaders: {
+        ...defaultRuntimeConfig.defaultHeaders,
+        ...currentConfig.defaultHeaders ?? {},
+        ...options.defaultHeaders ?? {}
+      },
+      retry: {
+        ...defaultRuntimeConfig.retry,
+        ...currentConfig.retry ?? {},
+        ...options.retry ?? {}
+      }
+    };
+    addPlugin(resolver.resolve("./runtime/plugin"));
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    nuxt.hook("prepare:types", ({ references }) => {
+      references.push({
+        path: resolver.resolve("./runtime/types.d.ts")
+      });
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/composables/useHttp.d.ts

@@ -0,0 +1,27 @@
+import { type ShallowReactive } from 'vue';
+import type { HttpRouteData, HttpRouteError, HttpRouteMap, HttpRouteParams, ResolveHttpRoute } from '../utils/typed.js';
+import { type HttpErrorPayload, type HttpParam, type HttpPayload } from '../utils/shared.js';
+type UseHttpState<TData, TError extends HttpErrorPayload, TParams extends HttpParam> = ShallowReactive<{
+    data: null | TData;
+    error: null | TError;
+    fetch: (params?: TParams, opt?: {
+        signal: AbortSignal;
+    }) => Promise<void>;
+    hasFirstData: boolean;
+    hasFreshData: boolean;
+    pending: boolean;
+    pendingCache: boolean;
+}>;
+export declare function useHttp<TUrl extends Extract<keyof HttpRouteMap, string>>(options: {
+    effect?: (payload: HttpPayload<HttpRouteData<ResolveHttpRoute<HttpRouteMap, TUrl>>, HttpRouteError<ResolveHttpRoute<HttpRouteMap, TUrl>>>, config: {
+        cached: boolean;
+        params: HttpRouteParams<ResolveHttpRoute<HttpRouteMap, TUrl>>;
+    }) => undefined | void;
+    initParams?: HttpRouteParams<ResolveHttpRoute<HttpRouteMap, TUrl>>;
+    lazy?: true;
+    mapParams?: <TMapped extends HttpRouteParams<ResolveHttpRoute<HttpRouteMap, TUrl>>>(params?: TMapped) => TMapped;
+    server?: boolean;
+    url: TUrl;
+}): Promise<UseHttpState<HttpRouteData<ResolveHttpRoute<HttpRouteMap, TUrl>>, HttpRouteError<ResolveHttpRoute<HttpRouteMap, TUrl>>, HttpRouteParams<ResolveHttpRoute<HttpRouteMap, TUrl>>>>;
+export {};
+//# sourceMappingURL=useHttp.d.ts.map