@sigmaott/base-next 1.0.6

package/src/modules/api-party/module.ts

@@ -0,0 +1,259 @@
+import { relative } from 'pathe'
+import { defu } from 'defu'
+import { camelCase, pascalCase } from 'scule'
+import { addImportsSources, addServerHandler, addTemplate, createResolver, defineNuxtModule, tryResolveModule, useLogger } from '@nuxt/kit'
+import type { OpenAPI3, OpenAPITSOptions } from 'openapi-typescript'
+import type { QueryObject } from 'ufo'
+import { generateTypes } from './openapi'
+
+export interface Endpoint {
+  url: string
+  token?: string
+  query?: QueryObject
+  headers?: Record<string, string>
+  cookies?: boolean
+  allowedUrls?: string[]
+  schema?: string | URL | OpenAPI3 | (() => Promise<OpenAPI3>)
+  openAPITS?: OpenAPITSOptions
+}
+
+export interface ModuleOptions {
+  /**
+   * API endpoints
+   *
+   * @remarks
+   * Each key represents an endpoint ID, which is used to generate the composables. The value is an object with the following properties:
+   * - `url`: The URL of the API endpoint
+   * - `token`: The API token to use for the endpoint (optional)
+   * - `query`: Query parameters to send with each request (optional)
+   * - `headers`: Headers to send with each request (optional)
+   * - `cookies`: Whether to send cookies with each request (optional)
+   * - `allowedUrls`: A list of allowed URLs to change the [backend URL at runtime](https://nuxt-api-party.byjohann.dev/guide/dynamic-backend-url) (optional)
+   * - `schema`: A URL, file path, object, or async function pointing to an [OpenAPI Schema](https://swagger.io/resources/open-api) used to [generate types](/guide/openapi-types) (optional)
+   * - `openAPITS`: [Configuration options](https://openapi-ts.pages.dev/node/#options) for `openapi-typescript`. Options defined here will override the global `openAPITS`
+   *
+   * @example
+   * export default defineNuxtConfig({
+   *   apiParty: {
+   *     endpoints: {
+   *       jsonPlaceholder: {
+   *         url: 'https://jsonplaceholder.typicode.com'
+   *         headers: {
+   *           Authorization: `Basic ${Buffer.from('foo:bar').toString('base64')}`
+   *         }
+   *       }
+   *     }
+   *   }
+   * })
+   *
+   * @default {}
+   */
+  endpoints?: Record<string, Endpoint>
+
+  /**
+   * Allow client-side requests besides server-side ones
+   *
+   * @remarks
+   * By default, API requests are only made on the server-side. This option allows you to make requests on the client-side as well. Keep in mind that this will expose your API credentials to the client.
+   *
+   * @example
+   * useJsonPlaceholderData('/posts/1', { client: true })
+   *
+   * @default false
+   */
+  allowClient?: boolean
+
+  /**
+   * Global options for openapi-typescript
+   */
+  openAPITS?: OpenAPITSOptions
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'nuxt-api-party',
+    configKey: 'apiParty',
+    compatibility: {
+      nuxt: '^3',
+    },
+  },
+  defaults: {
+    endpoints: {},
+    allowClient: false,
+    openAPITS: {},
+  },
+  async setup(options, nuxt) {
+    const moduleName = 'nuxt-api-party'
+    const logger = useLogger(moduleName)
+    const getRawComposableName = (endpointId: string) => `$${camelCase(endpointId)}`
+    const getDataComposableName = (endpointId: string) => `use${pascalCase(endpointId)}Data`
+
+    if (
+      Object.keys(options.endpoints!).length === 0
+      && !nuxt.options.runtimeConfig.apiParty
+    )
+      logger.error('Missing any API endpoint configuration. Please set `apiParty` module options in `nuxt.config.ts`.')
+
+    // Private runtime config
+    nuxt.options.runtimeConfig.apiParty = defu(
+      nuxt.options.runtimeConfig.apiParty,
+      options,
+    )
+
+    const resolvedOptions = nuxt.options.runtimeConfig.apiParty as Required<ModuleOptions>
+
+    // Write options to public runtime config if client requests are enabled
+    nuxt.options.runtimeConfig.public.apiParty = defu(
+      nuxt.options.runtimeConfig.public.apiParty,
+      resolvedOptions.allowClient
+        ? resolvedOptions
+        : {
+            // Only expose cookies endpoint option to the client
+            endpoints: Object.fromEntries(
+              Object.entries(resolvedOptions.endpoints).map(
+                ([endpointId, endpoint]) => [endpointId, { cookies: endpoint.cookies }],
+              ),
+            ),
+            allowClient: false,
+          },
+    )
+
+    // Transpile runtime
+    const { resolve } = createResolver(import.meta.url)
+    nuxt.options.build.transpile.push(resolve('runtime'))
+
+    const relativeTo = (path: string) => relative(
+      resolve(nuxt.options.rootDir, nuxt.options.buildDir, 'module'),
+      resolve(path),
+    )
+
+    const endpointKeys = Object.keys(resolvedOptions.endpoints)
+    const schemaEndpoints = Object.fromEntries(
+      Object.entries(resolvedOptions.endpoints)
+        .filter(([, endpoint]) => 'schema' in endpoint),
+    )
+    const schemaEndpointIds = Object.keys(schemaEndpoints)
+    const hasOpenAPIPkg = await tryResolveModule('openapi-typescript', [nuxt.options.rootDir])
+
+    if (schemaEndpointIds.length && !hasOpenAPIPkg) {
+      logger.warn('OpenAPI types generation is enabled, but the `openapi-typescript` package is not found. Please install it to enable endpoint types generation.')
+      schemaEndpointIds.length = 0
+    }
+
+    // Add Nuxt server route to proxy the API request server-side
+    addServerHandler({
+      route: '/api/__api_party/:endpointId',
+      method: 'post',
+      handler: resolve('runtime/server/handler'),
+    })
+
+    nuxt.hook('nitro:config', (config) => {
+      // Inline local server handler dependencies into Nitro bundle
+      // Needed to circumvent "cannot find module" error in `server.ts` for the `utils` import
+      config.externals ||= {}
+      config.externals.inline ||= []
+      config.externals.inline.push(...[
+        resolve('runtime/utils'),
+        resolve('runtime/formData'),
+        resolve('runtime/server/$api'),
+      ])
+
+      // Provide `#nuxt-api-party/server` module alias for Nitro
+      config.alias ||= {}
+      config.alias[`#${moduleName}/server`] = resolve(nuxt.options.buildDir, `module/${moduleName}-nitro`)
+
+      config.virtual ||= {}
+      config.virtual[`#${moduleName}/server`] = () => `
+import { _$api } from '${resolve('runtime/server/$api')}'
+${endpointKeys.map(i => `
+export const ${getRawComposableName(i)} = (...args) => _$api('${i}', ...args)
+`.trimStart()).join('')}`.trimStart()
+
+      if (schemaEndpointIds.length) {
+        config.typescript ||= {}
+        config.typescript.tsConfig ||= {}
+        config.typescript.tsConfig.include ||= []
+        config.typescript.tsConfig.include.push(`./module/${moduleName}-schema.d.ts`)
+      }
+
+      // Add Nitro auto-imports for generated composables
+      config.imports = defu(config.imports, {
+        presets: [{
+          from: `#${moduleName}/server`,
+          imports: endpointKeys.map(i => getRawComposableName(i)),
+        }],
+      })
+    })
+
+    // Add Nuxt auto-imports for generated composables
+    addImportsSources({
+      from: resolve(nuxt.options.buildDir, `module/${moduleName}.mjs`),
+      imports: endpointKeys.flatMap(i => [getRawComposableName(i), getDataComposableName(i)]),
+    })
+
+    // Add `#nuxt-api-party` module alias for generated composables
+    nuxt.options.alias[`#${moduleName}`] = resolve(nuxt.options.buildDir, `module/${moduleName}`)
+
+    // Add module template for generated composables
+    addTemplate({
+      filename: `module/${moduleName}.mjs`,
+      getContents() {
+        return `
+import { _$api } from '${resolve('runtime/composables/$api')}'
+import { _useApiData } from '${resolve('runtime/composables/useApiData')}'
+${endpointKeys.map(i => `
+export const ${getRawComposableName(i)} = (...args) => _$api('${i}', ...args)
+export const ${getDataComposableName(i)} = (...args) => _useApiData('${i}', ...args)
+`.trimStart()).join('')}`.trimStart()
+      },
+    })
+
+    // Add types for Nuxt auto-imports and the `#nuxt-api-party` module alias
+    addTemplate({
+      filename: `module/${moduleName}.d.ts`,
+      getContents() {
+        return `
+// Generated by ${moduleName}
+import type { $Api, $OpenApi, ApiFetchOptions } from '${relativeTo('runtime/composables/$api')}'
+import type { UseApiData, UseOpenApiData, UseApiDataOptions } from '${relativeTo('runtime/composables/useApiData')}'
+
+${schemaEndpointIds.map(i => `
+import type { paths as ${pascalCase(i)}Paths } from '#${moduleName}/${i}'
+`.trimStart()).join('').trimEnd()}
+
+export type { $Api, $OpenApi, ApiFetchOptions, UseApiData, UseOpenApiData, UseApiDataOptions }
+
+${endpointKeys.map(i => `
+export declare const ${getRawComposableName(i)}: ${schemaEndpointIds.includes(i) ? `$OpenApi<${pascalCase(i)}Paths>` : '$Api'}
+export declare const ${getDataComposableName(i)}: ${schemaEndpointIds.includes(i) ? `UseOpenApiData<${pascalCase(i)}Paths>` : 'UseApiData'}
+`.trimStart()).join('').trimEnd()}
+`.trimStart()
+      },
+    })
+
+    // Add types for Nitro auto-imports and the `#nuxt-api-party/server` module alias
+    addTemplate({
+      filename: `module/${moduleName}-nitro.d.ts`,
+      async getContents() {
+        return `
+// Generated by ${moduleName}
+export { ${endpointKeys.map(i => getRawComposableName(i)).join(', ')} } from './${moduleName}'
+`.trimStart()
+      },
+    })
+
+    // Add type references for endpoints with OpenAPI schemas
+    if (schemaEndpointIds.length) {
+      addTemplate({
+        filename: `module/${moduleName}-schema.d.ts`,
+        async getContents() {
+          return await generateTypes(schemaEndpoints, resolvedOptions.openAPITS)
+        },
+      })
+
+      nuxt.hook('prepare:types', ({ references }) => {
+        references.push({ path: resolve(nuxt.options.buildDir, `module/${moduleName}-schema.d.ts`) })
+      })
+    }
+  },
+})

package/src/modules/api-party/openapi.ts

@@ -0,0 +1,74 @@
+import { resolve } from 'pathe'
+import { useNuxt } from '@nuxt/kit'
+import type { OpenAPI3, OpenAPITSOptions } from 'openapi-typescript'
+import type { Endpoint } from './module'
+
+export async function generateTypes(
+  endpoints: Record<string, Endpoint>,
+  globalOpenAPIOptions: OpenAPITSOptions,
+) {
+  let runningCount = 0
+
+  // openapi-typescript uses `process.exit()` to handle errors
+  process.on('exit', () => {
+    if (runningCount > 0)
+      throw new Error('Failed to generate OpenAPI types')
+  })
+
+  const openapiTS = await resolveOpenAPIImports()
+  const schemas = await Promise.all(
+    Object.keys(endpoints).map(async (id) => {
+      let types = ''
+
+      const { openAPITS: openAPIOptions = {} } = endpoints[id]
+      const schema = await resolveSchema(endpoints[id])
+      runningCount++
+
+      try {
+        types = await openapiTS(schema, {
+          commentHeader: '',
+          ...globalOpenAPIOptions,
+          ...openAPIOptions,
+        })
+      }
+      catch {
+        // TODO: Use `Record<string, never>`?
+        types = `
+export type paths = Record<string, any>
+export type webhooks = Record<string, any>
+export type components = Record<string, any>
+export type external = Record<string, any>
+export type operations = Record<string, any>
+        `.trimStart()
+      }
+      finally {
+        runningCount--
+      }
+
+      return `
+declare module '#nuxt-api-party/${id}' {
+${types.replace(/^/gm, '  ').trimEnd()}
+}`.trimStart()
+    }),
+  )
+
+  return schemas.join('\n\n')
+}
+
+async function resolveSchema({ schema }: Endpoint): Promise<string | URL | OpenAPI3> {
+  const nuxt = useNuxt()
+
+  if (typeof schema === 'function')
+    return await schema()
+
+  // Parse file path and fix it
+  if (typeof schema === 'string' && !schema.match(/^https?:\/\//))
+    schema = resolve(nuxt.options.rootDir, schema)
+
+  return schema!
+}
+
+async function resolveOpenAPIImports() {
+  const openapiTS = await import('openapi-typescript')
+  return openapiTS.default || openapiTS
+}

package/src/modules/api-party/runtime/composables/$api.ts

@@ -0,0 +1,157 @@
+import { hash } from 'ohash'
+import type { NitroFetchOptions } from 'nitropack'
+import axios from 'axios'
+import { headersToObject, resolvePath, serializeMaybeEncodedBody } from '../utils'
+import { isFormData } from '../formData'
+import type { ModuleOptions } from '../../module'
+import { CACHE_KEY_PREFIX } from '../constants'
+import type { AllPaths, EndpointFetchOptions, GETPaths, GETPlainPaths, HttpMethod, IgnoreCase, OpenApiRequestOptions, OpenApiResponse, PathItemObject } from '../types'
+import { useNuxtApp, useRequestHeaders, useRuntimeConfig } from '#imports'
+import { addInterceptor } from '@/api/axios'
+
+export const service = axios.create({
+  baseURL: window.__NUXT__.config.public.apiBase,
+})
+addInterceptor(service, res => res.data)
+export interface BaseApiFetchOptions {
+  /**
+   * Skip the Nuxt server proxy and fetch directly from the API.
+   * Requires `allowClient` to be enabled in the module options as well.
+   * @default true
+   */
+  client?: boolean
+  /**
+   * Cache the response for the same request.
+   * You can customize the cache key with the `key` option.
+   * @default false
+   */
+  cache?: boolean
+  /**
+   * By default, a cache key will be generated from the request options.
+   * With this option, you can provide a custom cache key.
+   * @default undefined
+   */
+  key?: string
+}
+
+export type ApiFetchOptions = Omit<NitroFetchOptions<string>, 'body' | 'cache'> & {
+  pathParams?: Record<string, string>
+  body?: string | Record<string, any> | FormData | null
+}
+
+export type $Api = <T = any>(
+  path: string,
+  opts?: ApiFetchOptions & BaseApiFetchOptions,
+) => Promise<T>
+
+export interface $OpenApi<Paths extends Record<string, PathItemObject>> {
+  <P extends GETPlainPaths<Paths>>(
+    path: P,
+    opts: BaseApiFetchOptions & Omit<OpenApiRequestOptions<Paths[`/${P}`]>, 'method'>
+  ): Promise<OpenApiResponse<Paths[`/${P}`]['get']>>
+  <P extends GETPaths<Paths>>(
+    path: P,
+    opts: BaseApiFetchOptions & Omit<OpenApiRequestOptions<Paths[`/${P}`]>, 'method'>
+  ): Promise<OpenApiResponse<Paths[`/${P}`]['get']>>
+  <P extends AllPaths<Paths>, M extends IgnoreCase<keyof Paths[`/${P}`] & HttpMethod>>(
+    path: P,
+    opts: BaseApiFetchOptions & OpenApiRequestOptions<Paths[`/${P}`], M> & { method: M }
+  ): Promise<OpenApiResponse<Paths[`/${P}`][Lowercase<M>]>>
+}
+
+export function _$api<T = any>(
+  endpointId: string,
+  path: string,
+  opts: ApiFetchOptions & BaseApiFetchOptions = {},
+) {
+  const nuxt = useNuxtApp()
+  const { apiParty } = useRuntimeConfig().public
+  const promiseMap = (nuxt._promiseMap = nuxt._promiseMap || new Map()) as Map<string, Promise<T>>
+
+  const {
+    pathParams,
+    query,
+    headers,
+    method,
+    body,
+    client = true,
+    cache = false,
+    key,
+    ...fetchOptions
+  } = opts
+
+  const _key = key === undefined
+    ? CACHE_KEY_PREFIX + hash([
+      endpointId,
+      path,
+      pathParams,
+      query,
+      method,
+      ...(isFormData(body) ? [] : [body]),
+    ])
+    : CACHE_KEY_PREFIX + key
+
+  if (client && !apiParty.allowClient)
+    throw new Error('Client-side API requests are disabled. Set "allowClient: true" in the module options to enable them.')
+
+  if ((nuxt.isHydrating || cache) && _key in nuxt.payload.data)
+    return Promise.resolve(nuxt.payload.data[_key])
+
+  if (promiseMap.has(_key))
+    return promiseMap.get(_key)!
+
+  const endpoints = (apiParty as unknown as ModuleOptions).endpoints || {}
+  const endpoint = endpoints[endpointId]
+
+  const clientFetcher = () => service.request<T>({
+    baseURL: endpoint.url,
+    ...(fetchOptions as any),
+    url: resolvePath(path, pathParams),
+    method,
+    params: {
+      ...endpoint.query,
+      ...query,
+    },
+    headers: {
+      ...(endpoint.token && { Authorization: `Bearer ${endpoint.token}` }),
+      ...endpoint.headers,
+      ...headersToObject(headers),
+    },
+    data: body,
+  }) as Promise<T>
+
+  const serverFetcher = async () =>
+    (await globalThis.$fetch<T>(`/api/__api_party/${endpointId}`, {
+      ...fetchOptions,
+      method: 'POST',
+      body: {
+        path: resolvePath(path, pathParams),
+        query,
+        headers: {
+          ...headersToObject(headers),
+          ...(endpoint.cookies && useRequestHeaders(['cookie'])),
+        },
+        method,
+        body: await serializeMaybeEncodedBody(body),
+      } satisfies EndpointFetchOptions,
+    })) as T
+
+  const request = (client ? clientFetcher() : serverFetcher())
+    .then((response) => {
+      if (process.server || cache)
+        nuxt.payload.data[_key] = response
+      promiseMap.delete(_key)
+      return response
+    })
+    // Invalidate cache if request fails
+    .catch((error) => {
+      if (_key in nuxt.payload.data)
+        delete nuxt.payload.data[_key]
+      promiseMap.delete(_key)
+      throw error
+    }) as Promise<T>
+
+  promiseMap.set(_key, request)
+
+  return request
+}