spiceflow 1.17.12 → 1.18.0

package/src/client/fetch.ts

@@ -0,0 +1,447 @@
+// Type-safe fetch-like client for Spiceflow. Uses a familiar fetch(path, options)
+// interface instead of the proxy-based chainable API.
+import type { AnySpiceflow, Spiceflow } from '../spiceflow.ts'
+import type { ExtractParamsFromPath } from '../types.ts'
+
+import type { SpiceflowClient } from './types.ts'
+import type { ReplaceGeneratorWithAsyncGenerator } from './types.ts'
+import { SpiceflowFetchError } from './errors.ts'
+
+import {
+  processHeaders,
+  buildQueryString,
+  serializeBody,
+  parseResponseData,
+  executeWithRetries,
+} from './shared.ts'
+
+// ─── Type utilities ──────────────────────────────────────────────────────────
+
+type HttpMethodLower =
+  | 'get'
+  | 'post'
+  | 'put'
+  | 'delete'
+  | 'patch'
+  | 'options'
+  | 'head'
+  | 'connect'
+  | 'subscribe'
+
+// Navigate the nested ClientRoutes tree given a path string.
+// Reverses what CreateClient does: `/users/:id` → Routes['users'][':id']
+type NavigateRoutes<Routes, Path extends string> =
+  Path extends `/${infer Rest}`
+    ? Rest extends ''
+      ? 'index' extends keyof Routes
+        ? Routes['index']
+        : never
+      : _NavigateRoutes<Routes, Rest>
+    : _NavigateRoutes<Routes, Path>
+
+type _NavigateRoutes<Routes, Path extends string> =
+  Path extends `${infer Segment}/${infer Rest}`
+    ? Segment extends keyof Routes
+      ? _NavigateRoutes<Routes[Segment], Rest>
+      : never
+    : Path extends keyof Routes
+      ? Routes[Path]
+      : never
+
+type RouteAtPath<
+  Routes extends Record<string, any>,
+  Path extends string,
+> = NavigateRoutes<Routes, Path>
+
+type MethodsAtPath<
+  Routes extends Record<string, any>,
+  Path extends string,
+> = Extract<keyof RouteAtPath<Routes, Path>, HttpMethodLower>
+
+type AllowedMethod<
+  Routes extends Record<string, any>,
+  Path extends string,
+> = Uppercase<MethodsAtPath<Routes, Path>> | MethodsAtPath<Routes, Path>
+
+type RouteInfoForMethod<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = Lowercase<Method> extends keyof RouteAtPath<Routes, Path>
+  ? RouteAtPath<Routes, Path>[Lowercase<Method>]
+  : never
+
+// ─── Options type ────────────────────────────────────────────────────────────
+
+// Params option: required if path has :params, omitted otherwise
+type ParamsOption<Path extends string> =
+  ExtractParamsFromPath<Path> extends undefined
+    ? { params?: Record<string, string> }
+    : { params: ExtractParamsFromPath<Path> }
+
+// Query option: typed from route schema if available
+type QueryOption<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = RouteInfoForMethod<Routes, Path, Method> extends {
+  query: infer Q
+}
+  ? undefined extends Q
+    ? { query?: Record<string, unknown> }
+    : { query: Q }
+  : { query?: Record<string, unknown> }
+
+// Body option: typed from route schema, only for non-GET/HEAD/SUBSCRIBE methods
+type BodyOption<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = Lowercase<Method> extends 'get' | 'head' | 'subscribe'
+  ? {}
+  : RouteInfoForMethod<Routes, Path, Method> extends {
+        request: infer Body
+      }
+    ? undefined extends Body
+      ? { body?: unknown }
+      : { body: Body }
+    : { body?: unknown }
+
+// Check if options has any required fields
+type HasRequiredFields<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> =
+  // params required?
+  ExtractParamsFromPath<Path> extends undefined
+    ? // query required?
+      RouteInfoForMethod<Routes, Path, Method> extends { query: infer Q }
+      ? undefined extends Q
+        ? // body required?
+          Lowercase<Method> extends 'get' | 'head' | 'subscribe'
+          ? false
+          : RouteInfoForMethod<Routes, Path, Method> extends {
+                request: infer Body
+              }
+            ? undefined extends Body
+              ? false
+              : true
+            : false
+        : true
+      : // body required?
+        Lowercase<Method> extends 'get' | 'head' | 'subscribe'
+        ? false
+        : RouteInfoForMethod<Routes, Path, Method> extends {
+              request: infer Body
+            }
+          ? undefined extends Body
+            ? false
+            : true
+          : false
+    : true
+
+type FetchOptionsTyped<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = {
+  method?: Method
+  headers?: RequestInit['headers']
+  signal?: AbortSignal
+} & ParamsOption<Path> &
+  QueryOption<Routes, Path, Method> &
+  BodyOption<Routes, Path, Method>
+
+type FetchOptionsFallback = {
+  method?: string
+  body?: BodyInit | Record<string, unknown> | null
+  query?: Record<string, unknown>
+  params?: Record<string, string>
+  headers?: RequestInit['headers']
+  signal?: AbortSignal
+  [key: string]: unknown
+}
+
+type FetchOptions<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = [RouteAtPath<Routes, Path>] extends [never]
+  ? FetchOptionsFallback
+  : FetchOptionsTyped<Routes, Path, Method>
+
+// ─── Response type ───────────────────────────────────────────────────────────
+
+type FetchResultData<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = [RouteAtPath<Routes, Path>] extends [never]
+  ? any
+  : RouteInfoForMethod<Routes, Path, Method> extends {
+        response: infer Res extends Record<number, unknown>
+      }
+    ? ReplaceGeneratorWithAsyncGenerator<Res>[200]
+    : any
+
+type FetchResultError<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = [RouteAtPath<Routes, Path>] extends [never]
+  ? SpiceflowFetchError<number, any>
+  : RouteInfoForMethod<Routes, Path, Method> extends {
+        response: infer Res extends Record<number, unknown>
+      }
+    ? Exclude<keyof Res, 200> extends never
+      ? SpiceflowFetchError<number, any>
+      : {
+          [Status in keyof Res]: SpiceflowFetchError<Status, Res[Status]>
+        }[Exclude<keyof Res, 200>]
+    : SpiceflowFetchError<number, any>
+
+type FetchResult<
+  Routes extends Record<string, any>,
+  Path extends string,
+  Method extends string,
+> = FetchResultError<Routes, Path, Method> | FetchResultData<Routes, Path, Method>
+
+// ─── Public type ─────────────────────────────────────────────────────────────
+
+// Resolves options for a given App/Path/Method combination.
+// Returns the appropriate options type, or FetchOptionsFallback for unknown paths.
+type ResolveOptions<
+  App extends AnySpiceflow,
+  Path extends string,
+  Method extends string,
+> = App extends {
+  _types: { ClientRoutes: infer Routes extends Record<string, any> }
+}
+  ? FetchOptions<Routes, Path, Method>
+  : FetchOptionsFallback
+
+// Resolves the result type for a given App/Path/Method combination.
+type ResolveResult<
+  App extends AnySpiceflow,
+  Path extends string,
+  Method extends string,
+> = App extends {
+  _types: { ClientRoutes: infer Routes extends Record<string, any> }
+}
+  ? FetchResult<Routes, Path, Method>
+  : SpiceflowFetchError<number, any> | any
+
+// Check if options are required for a given App/Path/Method
+type IsOptionsRequired<
+  App extends AnySpiceflow,
+  Path extends string,
+  Method extends string,
+> = App extends {
+  _types: { ClientRoutes: infer Routes extends Record<string, any> }
+}
+  ? [RouteAtPath<Routes, Path>] extends [never]
+    ? false
+    : HasRequiredFields<Routes, Path, Method>
+  : false
+
+export interface SpiceflowFetch<App extends AnySpiceflow> {
+  // Overload: options required when route demands params/query/body
+  <const Path extends string, const Method extends string = 'GET'>(
+    ...args: IsOptionsRequired<App, Path, Method> extends true
+      ? [path: Path, options: ResolveOptions<App, Path, Method>]
+      : [path: Path, options?: ResolveOptions<App, Path, Method>]
+  ): Promise<ResolveResult<App, Path, Method>>
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+export function createSpiceflowFetch<const App extends AnySpiceflow>(
+  domain: App | string,
+  config: SpiceflowClient.Config &
+    (App extends Spiceflow<any, any, infer Singleton, any, any, any, any>
+      ? { state?: Singleton['state'] }
+      : {}) = {} as any,
+): SpiceflowFetch<App> {
+  let baseUrl: string
+  let instance: AnySpiceflow | undefined
+
+  if (typeof domain === 'string') {
+    baseUrl = domain.endsWith('/') ? domain.slice(0, -1) : domain
+  } else {
+    baseUrl = 'http://e.ly'
+    instance = domain
+
+    if (typeof window !== 'undefined') {
+      console.warn(
+        'Spiceflow instance server found on client side, this is not recommended for security reason. Use generic type instead.',
+      )
+    }
+  }
+
+  if ((config as any).state && !instance) {
+    throw new Error('State is only available when using a Spiceflow instance')
+  }
+
+  const spiceflowFetch = async (
+    path: string,
+    options: any = {},
+  ): Promise<any> => {
+    let {
+      fetch: fetcher = fetch,
+      headers: configHeaders,
+      onRequest,
+      onResponse,
+      retries = 0,
+    } = config as SpiceflowClient.Config
+
+    const {
+      method: rawMethod = 'GET',
+      body,
+      query,
+      params,
+      headers: optionHeaders,
+      signal,
+      ...restInit
+    } = options
+
+    const methodUpper = rawMethod.toUpperCase()
+    const isGetOrHead =
+      methodUpper === 'GET' ||
+      methodUpper === 'HEAD' ||
+      methodUpper === 'SUBSCRIBE'
+
+    // Resolve path params (replace :param with values)
+    // Sort by key length descending to avoid :id replacing inside :id2
+    let resolvedPath = path
+    if (params && typeof params === 'object') {
+      const entries = Object.entries(params).sort(
+        ([a], [b]) => b.length - a.length,
+      )
+      for (const [key, value] of entries) {
+        if (key === '*') {
+          resolvedPath = resolvedPath.split('*').join(String(value))
+        } else {
+          resolvedPath = resolvedPath.split(`:${key}`).join(String(value))
+        }
+      }
+    }
+
+    const queryString = buildQueryString(query)
+
+    // Support absolute URLs — skip baseUrl concatenation
+    const isAbsoluteUrl = /^https?:\/\//i.test(resolvedPath)
+    const url = isAbsoluteUrl
+      ? resolvedPath + queryString
+      : baseUrl + resolvedPath + queryString
+
+    let headers = processHeaders(configHeaders, resolvedPath, {
+      method: methodUpper,
+      signal,
+    })
+    headers = {
+      ...headers,
+      ...processHeaders(optionHeaders, resolvedPath, {
+        method: methodUpper,
+        signal,
+      }),
+    }
+
+    let fetchInit: RequestInit = {
+      method: methodUpper,
+      headers,
+      signal,
+      ...restInit,
+    }
+
+    // Apply onRequest hooks (first pass, before body serialization)
+    if (onRequest) {
+      const hooks = Array.isArray(onRequest) ? onRequest : [onRequest]
+      for (const hook of hooks) {
+        const temp = await hook(resolvedPath, fetchInit)
+        if (typeof temp === 'object') {
+          fetchInit = {
+            ...fetchInit,
+            ...temp,
+            headers: {
+              ...fetchInit.headers,
+              ...processHeaders(temp.headers, resolvedPath, fetchInit),
+            },
+          }
+        }
+      }
+    }
+
+    // Ensure GET/HEAD has no body before serialization
+    if (isGetOrHead) delete fetchInit.body
+
+    // Serialize body
+    if (!isGetOrHead && body !== undefined) {
+      fetchInit.body = body
+      await serializeBody({ body, fetchInit, isGetOrHead })
+    }
+
+    if (isGetOrHead) {
+      delete fetchInit.body
+    }
+
+    // Add x-spiceflow-agent header
+    ;(fetchInit.headers as Record<string, string>)['x-spiceflow-agent'] =
+      'spiceflow-client'
+
+    // Apply onRequest hooks (second pass, after body serialization — matches proxy client behavior)
+    if (onRequest) {
+      const hooks = Array.isArray(onRequest) ? onRequest : [onRequest]
+      for (const hook of hooks) {
+        const temp = await hook(resolvedPath, fetchInit)
+        if (typeof temp === 'object') {
+          fetchInit = {
+            ...fetchInit,
+            ...temp,
+            headers: {
+              ...fetchInit.headers,
+              ...processHeaders(temp.headers, resolvedPath, fetchInit),
+            } as Record<string, string>,
+          }
+        }
+      }
+    }
+
+    // Execute request with retries
+    const executeRequest = () =>
+      executeWithRetries({
+        url,
+        fetchInit,
+        fetcher: fetcher || fetch,
+        instance,
+        state: (config as any).state,
+        retries,
+      })
+
+    const response = await executeRequest()
+
+    // Process onResponse hooks
+    if (onResponse) {
+      const hooks = Array.isArray(onResponse) ? onResponse : [onResponse]
+      for (const hook of hooks) {
+        await hook(response.clone())
+      }
+    }
+
+    // Parse response
+    const { data, error } = await parseResponseData({
+      response,
+      executeRequest,
+      retries,
+    })
+
+    if (error) {
+      error.response = response
+      return error
+    }
+
+    return data
+  }
+
+  return spiceflowFetch as any
+}

package/src/client/index.ts

@@ -1,6 +1,4 @@
 import type { AnySpiceflow, Spiceflow } from '../spiceflow.ts'
-import superjson from 'superjson'
-import { EventSourceParserStream } from 'eventsource-parser/stream'
 
 import type { SpiceflowClient } from './types.ts'
 
@@ -10,6 +8,25 @@ import { SpiceflowFetchError } from './errors.ts'
 
 import { parseStringifiedValue } from './utils.ts'
 
+import {
+  isServer,
+  isFile,
+  hasFile,
+  createNewFile,
+  processHeaders,
+  streamSSEResponse,
+  tryParsingSSEJson,
+  superjsonDeserialize,
+  TextDecoderStream,
+  isAbortError,
+  type SSEEvent,
+} from './shared.ts'
+
+export { streamSSEResponse, TextDecoderStream }
+
+export { createSpiceflowFetch } from './fetch.ts'
+export type { SpiceflowFetch } from './fetch.ts'
+
 const method = [
   'get',
   'post',
@@ -22,222 +39,6 @@ const method = [
   'subscribe',
 ] as const
 
-const isServer = typeof FileList === 'undefined'
-
-const isFile = (v: any) => {
-  if (isServer) return v instanceof Blob
-
-  return v instanceof FileList || v instanceof File
-}
-
-// FormData is 1 level deep
-const hasFile = (obj: Record<string, any>) => {
-  if (!obj) return false
-
-  for (const key in obj) {
-    if (isFile(obj[key])) return true
-
-    if (Array.isArray(obj[key]) && (obj[key] as unknown[]).find(isFile))
-      return true
-  }
-
-  return false
-}
-
-const createNewFile = (v: File) =>
-  isServer
-    ? v
-    : new Promise<File>((resolve) => {
-        const reader = new FileReader()
-
-        reader.onload = () => {
-          const file = new File([reader.result!], v.name, {
-            lastModified: v.lastModified,
-            type: v.type,
-          })
-          resolve(file)
-        }
-
-        reader.readAsArrayBuffer(v)
-      })
-
-const processHeaders = (
-  h: SpiceflowClient.Config['headers'],
-  path: string,
-  options: RequestInit = {},
-  headers: Record<string, string> = {},
-): Record<string, string> => {
-  if (Array.isArray(h)) {
-    for (const value of h)
-      if (!Array.isArray(value))
-        headers = processHeaders(value, path, options, headers)
-      else {
-        const key = value[0]
-        if (typeof key === 'string')
-          headers[key.toLowerCase()] = value[1] as string
-        else
-          for (const [k, value] of key)
-            headers[k.toLowerCase()] = value as string
-      }
-
-    return headers
-  }
-
-  if (!h) return headers
-
-  switch (typeof h) {
-    case 'function':
-      if (typeof Headers !== 'undefined' && h instanceof Headers)
-        return processHeaders(h, path, options, headers)
-
-      const v = h(path, options)
-      if (v) return processHeaders(v, path, options, headers)
-      return headers
-
-    case 'object':
-      if (typeof Headers !== 'undefined' && h instanceof Headers) {
-        h.forEach((value, key) => {
-          headers[key.toLowerCase()] = value
-        })
-        return headers
-      }
-
-      for (const [key, value] of Object.entries(h))
-        headers[key.toLowerCase()] = value as string
-
-      return headers
-
-    default:
-      return headers
-  }
-}
-
-interface SSEEvent {
-  event?: string
-  data: any
-  id?: string
-}
-
-export class TextDecoderStream extends TransformStream<Uint8Array, string> {
-  constructor() {
-    const decoder = new TextDecoder('utf-8', {
-      fatal: true,
-      ignoreBOM: true,
-    })
-    super({
-      transform(
-        chunk: Uint8Array,
-        controller: TransformStreamDefaultController<string>,
-      ) {
-        const decoded = decoder.decode(chunk, { stream: true })
-        if (decoded.length > 0) {
-          controller.enqueue(decoded)
-        }
-      },
-      flush(controller: TransformStreamDefaultController<string>) {
-        const output = decoder.decode()
-        if (output.length > 0) {
-          controller.enqueue(output)
-        }
-      },
-    })
-  }
-}
-
-function isAbortError(error: unknown): error is Error {
-  return (
-    (error instanceof Error || error instanceof DOMException) &&
-    (error.name === 'AbortError' ||
-      error.name === 'ResponseAborted' || // Next.js
-      error.name === 'TimeoutError')
-  )
-}
-
-export async function* streamSSEResponse({
-  response,
-  map,
-  executeRequest,
-  maxRetries = 0,
-}: {
-  response: Response
-  map: (x: SSEEvent) => any
-  executeRequest?: () => Promise<Response>
-  maxRetries?: number
-}): AsyncGenerator<SSEEvent> {
-  let currentResponse = response
-  let retriesLeft = maxRetries
-
-  while (true) {
-    const body = currentResponse.body
-    if (!body) return
-
-    const eventStream = body
-      .pipeThrough(new TextDecoderStream())
-      .pipeThrough(new EventSourceParserStream())
-
-    let reader = eventStream.getReader()
-
-    try {
-      while (true) {
-        const { done, value: event } = await reader.read()
-        if (done) return
-
-        if (event?.event === 'error') {
-          const error = superjsonDeserialize(event.data)
-          throw new SpiceflowFetchError(500, error)
-        }
-
-        if (event) {
-          yield map({ ...event, data: event.data })
-        }
-      }
-    } catch (error) {
-      if (isAbortError(error)) {
-        return
-      }
-
-      if (
-        executeRequest &&
-        error instanceof SpiceflowFetchError &&
-        error.status >= 500 &&
-        retriesLeft > 0
-      ) {
-        retriesLeft--
-        const backoffMs = Math.min(
-          1000 * 2 ** (maxRetries - retriesLeft - 1),
-          10000,
-        )
-        await new Promise((resolve) => setTimeout(resolve, backoffMs))
-
-        try {
-          currentResponse = await executeRequest()
-          if (currentResponse.status >= 500) {
-            if (retriesLeft === 0) {
-              throw error
-            }
-            continue
-          }
-        } catch (retryError) {
-          if (retriesLeft === 0) {
-            throw retryError
-          }
-          continue
-        }
-      } else {
-        throw error
-      }
-    }
-  }
-}
-
-function tryParsingSSEJson(data: string): any {
-  try {
-    return superjsonDeserialize(JSON.parse(data))
-  } catch (error) {
-    return data
-  }
-}
-
 const createProxy = (
   domain: string,
   config: SpiceflowClient.Config & { state?: any },
@@ -603,14 +404,3 @@ export const createSpiceflowClient = <const App extends AnySpiceflow>(
 
   return createProxy('http://e.ly', config || {}, [], domain)
 }
-
-function superjsonDeserialize(data: any) {
-  if (data?.__superjsonMeta) {
-    const { __superjsonMeta, ...rest } = data
-    return superjson.deserialize({
-      json: rest,
-      meta: __superjsonMeta,
-    })
-  }
-  return data
-}