spiceflow 1.1.17 → 1.2.0

package/src/openapi.ts

@@ -12,7 +12,18 @@ import deepClone from 'lodash.clonedeep'
 import { z } from 'zod'
 import zodToJsonSchema from 'zod-to-json-schema'
 
-export const toOpenAPIPath = (path: string) =>
+const extractParamNames = (path: string): string[] => {
+  return path.split('/').reduce((params: string[], segment) => {
+    if (segment.startsWith(':')) {
+      let param = segment.slice(1)
+      if (param.endsWith('?')) param = param.slice(0, -1)
+      params.push(param)
+    }
+    return params
+  }, [])
+}
+
+const toOpenAPIPath = (path: string) =>
   path
     .split('/')
     .map((x) => {
@@ -26,7 +37,7 @@ export const toOpenAPIPath = (path: string) =>
     })
     .join('/')
 
-export const mapProperties = (
+const mapProperties = (
   name: string,
   schema: TypeSchema | string | undefined,
   models: Record<string, TypeSchema>,
@@ -61,7 +72,7 @@ export const mapProperties = (
 
 const mapTypesResponse = (
   types: string[],
-  schema:
+  schema?:
     | string
     | {
         type: string
@@ -90,10 +101,10 @@ const mapTypesResponse = (
   return responses
 }
 
-export const capitalize = (word: string) =>
+const capitalize = (word: string) =>
   word.charAt(0).toUpperCase() + word.slice(1)
 
-export const generateOperationId = (method: string, paths: string) => {
+const generateOperationId = (method: string, paths: string) => {
   let operationId = method.toLowerCase()
 
   if (paths === '/') return operationId + 'Index'
@@ -109,42 +120,73 @@ export const generateOperationId = (method: string, paths: string) => {
   return operationId
 }
 
-export const registerSchemaPath = ({
+const registerSchemaPath = ({
   schema,
-  path,
-  method,
-  hook,
+  route,
   models,
 }: {
   schema: Partial<OpenAPIV3.PathsObject>
-  contentType?: string | string[]
-  path: string
-  method: HTTPMethod
-  hook?: LocalHook<any, any, any, any, any, any, any>
+  route: InternalRoute
   models: Record<string, TypeSchema>
 }) => {
-  if (hook) hook = deepClone(hook)
+  const hook = route.hooks ? deepClone(route.hooks) : undefined
 
-  // TODO if a route uses an async generator, add text/event-stream. if a roue does not add an explicit schema, use all possible content types
-  const contentType = hook?.type ?? [
-    'application/json',
-    // 'multipart/form-data',
-    // 'text/plain',
-  ]
+  let contentTypes = ['application/json']
 
-  path = toOpenAPIPath(path)
+  if (isAsyncGenerator(route.handler) && !route.hooks?.response) {
+    contentTypes = ['text/event-stream']
+  } else if (hook?.type) {
+    contentTypes = Array.isArray(hook.type) ? hook.type : [hook.type]
+  }
 
-  const contentTypes =
-    typeof contentType === 'string'
-      ? [contentType]
-      : contentType ?? ['application/json']
+  const path = toOpenAPIPath(route.path)
 
   const bodySchema = getJsonSchema(hook?.body)
-  const paramsSchema = hook?.params
+  let paramsSchema = hook?.params
+  if (route.path.includes(':') && !paramsSchema) {
+    const paramNames = extractParamNames(route.path)
+    if (paramNames.length) {
+      // Create a schema object with string parameters for each URL param
+      const paramSchemaObject = {}
+      for (const param of paramNames) {
+        paramSchemaObject[param] = z.string()
+      }
+      paramsSchema = z.object(paramSchemaObject)
+    }
+  }
+
   // const headerSchema = hook?.headers
   const querySchema = hook?.query
   let responseSchema = hook?.response as unknown as TypeSchema
-  let openapiResponse: OpenAPIV3.ResponsesObject = {}
+  const defaultResponseSchema: OpenAPIV3.ResponsesObject = {
+    // '500': {
+    //   description: 'Internal Server Error',
+    //   content: {
+    //     'text/plain': {
+    //       schema: {
+    //         type: 'string',
+    //       },
+    //     },
+    //   },
+    // },
+    '200': {
+      description: '',
+      content: {
+        '*/*': {
+          schema: {},
+        },
+      },
+    },
+    default: {
+      description: '',
+      content: {
+        '*/*': {
+          schema: {},
+        },
+      },
+    },
+  }
+  let openapiResponse: OpenAPIV3.ResponsesObject = defaultResponseSchema
 
   if (typeof responseSchema === 'object') {
     const isStatusMap = Object.keys(responseSchema).every(
@@ -162,6 +204,7 @@ export const registerSchemaPath = ({
       } = jsonSchema
 
       openapiResponse = {
+        ...defaultResponseSchema,
         '200': {
           ...rest,
           description: (rest.description as any) || '',
@@ -213,7 +256,7 @@ export const registerSchemaPath = ({
 
             openapiResponse[key] = {
               ...rest,
-              description: rest.description as any || '',
+              description: (rest.description as any) || '',
               content: mapTypesResponse(
                 contentTypes,
                 type === 'object' || type === 'array'
@@ -245,6 +288,7 @@ export const registerSchemaPath = ({
     } = getJsonSchema(models[responseSchema])
 
     openapiResponse = {
+      ...defaultResponseSchema,
       // @ts-ignore
       '200': {
         description: '',
@@ -260,27 +304,42 @@ export const registerSchemaPath = ({
     ...mapProperties('path', paramsSchema, models),
     ...mapProperties('query', querySchema, models),
   ]
-
   schema[path] = {
-    ...(schema[path] ? schema[path] : {}),
-    [method.toLowerCase()]: {
-      ...((paramsSchema || querySchema || bodySchema
-        ? ({ parameters } as any)
-        : {}) satisfies OpenAPIV3.ParameterObject),
-      ...(!isObjEmpty(openapiResponse)
+    // Merge with existing path schema if it exists
+    ...(schema[path] ?? {}),
+    [route.method.toLowerCase()]: {
+      // Add streaming flag for async generators
+      ...(isAsyncGenerator(route.handler) && {
+        'x-fern-streaming': {
+          format: 'sse',
+        },
+      }),
+
+      // Add parameters if any schemas are defined
+      ...(paramsSchema || querySchema || bodySchema
         ? {
-            responses: openapiResponse,
+            parameters,
           }
         : {}),
-      operationId:
-        hook?.detail?.operationId ?? generateOperationId(method, path),
+
+      // Add responses if defined
+      ...(!isObjEmpty(openapiResponse) && {
+        responses: openapiResponse,
+      }),
+
+      // operationId:
+      //   hook?.detail?.operationId ?? generateOperationId(route.method, path),
+
+      // Add any additional details from hook
       ...hook?.detail,
+
+      // Add request body if body schema exists
       ...(bodySchema
         ? {
             requestBody: {
               required: true,
               content: mapTypesResponse(
-                contentTypes,
+                hook.bodyType ? [hook.bodyType] : ['application/json'],
                 typeof bodySchema === 'string'
                   ? {
                       $ref: `#/components/schemas/${bodySchema}`,
@@ -301,20 +360,27 @@ export const registerSchemaPath = ({
  */
 export const openapi = <Path extends string = '/openapi'>({
   path = '/openapi' as Path,
-  documentation = {},
+  ...additional
 }: {
   path?: Path
-  /**
-   * Customize Swagger config, refers to Swagger 2.0 config
-   *
-   * @see https://swagger.io/specification/v2/
-   */
-  documentation?: Omit<
-    Partial<OpenAPIV3.Document>,
-    | 'x-express-openapi-additional-middleware'
-    | 'x-express-openapi-validation-strict'
-  >
-} = {}) => {
+} & Omit<
+  Partial<OpenAPIV3.Document>,
+  | 'x-express-openapi-additional-middleware'
+  | 'x-express-openapi-validation-strict'
+> & {
+    'x-fern-global-headers'?: Array<{
+      header: string
+      name: string
+      optional?: boolean
+    }>
+    'x-fern-version'?: {
+      version: {
+        header: string
+        default: string
+        values: string[]
+      }
+    }
+  } = {}) => {
   const schema = {}
   let totalRoutes = 0
 
@@ -349,12 +415,9 @@ export const openapi = <Path extends string = '/openapi'>({
           ALLOWED_METHODS.forEach((method) => {
             registerSchemaPath({
               schema,
-              hook: route.hooks,
-              method,
-              path: route.path,
+              route: { ...route, method },
               // @ts-ignore
               models: app.definitions?.type,
-              contentType: route.hooks?.type,
             })
           })
           return
@@ -362,12 +425,9 @@ export const openapi = <Path extends string = '/openapi'>({
 
         registerSchemaPath({
           schema,
-          hook: route.hooks,
-          method: route.method,
-          path: route.path,
+          route,
           // @ts-ignore
           models: app.definitions?.type,
-          contentType: route.hooks?.type,
         })
       })
     }
@@ -375,7 +435,7 @@ export const openapi = <Path extends string = '/openapi'>({
     return {
       openapi: '3.1.3',
       ...{
-        ...documentation,
+        ...additional,
         // tags: documentation.tags?.filter(
         // 	(tag) => !excludeTags?.includes(tag?.name),
         // ),
@@ -383,19 +443,19 @@ export const openapi = <Path extends string = '/openapi'>({
           title: 'Spiceflow Documentation',
           description: 'Development documentation',
           version: '0.0.0',
-          ...documentation.info,
+          ...additional.info,
         },
       },
       paths: {
         ...schema,
-        ...documentation.paths,
+        ...additional.paths,
       },
       components: {
-        ...documentation.components,
+        ...additional.components,
         schemas: {
           // @ts-ignore
           ...app.definitions?.type,
-          ...documentation.components?.schemas,
+          ...additional.components?.schemas,
         },
       },
     } satisfies OpenAPIV3.Document
@@ -409,12 +469,22 @@ function getJsonSchema(schema: TypeSchema): JSONSchemaType<any> {
   if (isZodSchema(schema)) {
     let fn = zodToJsonSchema.default ?? zodToJsonSchema
     let jsonSchema = fn(schema, {})
-    return jsonSchema as any
+    const { $schema, ...rest } = jsonSchema
+    return rest as any
   }
 
-  return schema as any
+  const { $schema, ...rest } = schema as any
+  return rest as any
 }
 
 function isObjEmpty(obj: Record<string, any>) {
   return obj === undefined || Object.keys(obj).length === 0
 }
+
+function isAsyncGenerator(fn: any): boolean {
+  return (
+    fn &&
+    typeof fn === 'function' &&
+    fn.constructor?.name === 'AsyncGeneratorFunction'
+  )
+}

package/src/spiceflow.test.ts

@@ -18,6 +18,30 @@ test('dynamic route', async () => {
   expect(res.status).toBe(200)
   expect(await res.json()).toEqual('hi')
 })
+test('handler returns url encoded data', async () => {
+  const params = new URLSearchParams()
+  params.append('name', 'test')
+  params.append('value', '123')
+
+  const res = await new Spiceflow()
+    .post('/form', () => params, {
+      type: 'application/x-www-form-urlencoded',
+    })
+    .handle(
+      new Request('http://localhost/form', {
+        method: 'POST',
+      }),
+    )
+
+  expect(res.status).toBe(200)
+  expect(res.headers.get('content-type')).toBe(
+    'application/x-www-form-urlencoded',
+  )
+  const text = await res.text()
+  const responseParams = new URLSearchParams(text)
+  expect(responseParams.get('name')).toBe('test')
+  expect(responseParams.get('value')).toBe('123')
+})
 test('GET dynamic route', async () => {
   const res = await new Spiceflow()
     .get('/ids/:id', () => 'hi')
@@ -79,7 +103,7 @@ test('onError fires on validation errors', async () => {
 
   expect(res.status).toBe(400)
   expect(errorMessage).toContain('data/name must be string')
-  expect(await res.text()).toBe('Error')
+  expect(await res.text()).toMatchInlineSnapshot(`"Error"`)
 })
 
 test.todo('HEAD uses GET route, does not add body', async () => {
@@ -287,7 +311,7 @@ test('validate body works, request fails', async () => {
     )
   expect(res.status).toBe(422)
   expect(await res.text()).toMatchInlineSnapshot(
-    `"data must have required property 'requiredField'"`,
+    `"{"message":"data must have required property 'requiredField'"}"`,
   )
 })
 
@@ -554,7 +578,7 @@ test('errors inside basPath works', async () => {
     expect(onErrorTriggered).toEqual(['root', 'two', 'nested'])
     expect(onReqTriggered).toEqual(['root', 'two', 'nested'])
     expect(res.status).toBe(500)
-    expect(await res.text()).toBe('error message')
+    expect(await res.text()).toMatchInlineSnapshot(`"{"message":"error message"}"`)
     // expect(await res.json()).toEqual('nested'))
   }
 })

package/src/spiceflow.ts

@@ -7,6 +7,7 @@ export { Type as t }
 import addFormats from 'ajv-formats'
 import {
   ComposeSpiceflowResponse,
+  ContentType,
   CreateClient,
   DefinitionBase,
   ErrorHandler,
@@ -66,6 +67,7 @@ type OnError = (x: { error: any; request: Request }) => AsyncResponse
 export type InternalRoute = {
   method: HTTPMethod
   path: string
+  type: ContentType
   handler: InlineHandler<any, any, any>
   hooks: LocalHook<any, any, any, any, any, any, any>
   validateBody?: ValidateFunction
@@ -111,7 +113,7 @@ export class Spiceflow<
   private onErrorHandlers: OnError[] = []
   private routes: InternalRoute[] = []
   private defaultState: Record<any, any> = {}
-  private topLevelApp?: AnySpiceflow
+  topLevelApp?: AnySpiceflow
 
   /** @internal */
   prefix?: string
@@ -157,6 +159,7 @@ export class Spiceflow<
     const store = this.router.register(path)
     let route: InternalRoute = {
       ...rest,
+      type: hooks?.type || '',
       method: (method || '') as any,
       path: path || '',
       handler: handler!,
@@ -775,9 +778,15 @@ export class Spiceflow<
       if (isResponse(res)) return res
 
       let status = err?.status ?? 500
-      res ||= new Response(err?.message || 'Internal Server Error', {
-        status,
-      })
+      res ||= new Response(
+        JSON.stringify({ message: err?.message || 'Internal Server Error' }),
+        {
+          status,
+          headers: {
+            'content-type': 'application/json',
+          },
+        },
+      )
       return res
     }
 
@@ -794,7 +803,10 @@ export class Spiceflow<
           if (!result && index < middlewares.length) {
             return await next()
           } else if (result) {
-            return await turnHandlerResultIntoResponse(result)
+            return await turnHandlerResultIntoResponse(
+              result,
+              route.internalRoute,
+            )
           }
         }
         if (handlerResponse) {
@@ -816,10 +828,14 @@ export class Spiceflow<
             generator: res,
             request,
             onErrorHandlers,
+            route: route.internalRoute,
           })
           return handlerResponse
         }
-        handlerResponse = await turnHandlerResultIntoResponse(res)
+        handlerResponse = await turnHandlerResultIntoResponse(
+          res,
+          route.internalRoute,
+        )
         return handlerResponse
       } catch (err) {
         handlerResponse = await getResForError(err)
@@ -896,7 +912,7 @@ export class Spiceflow<
     return appsInScope
   }
 
-  async listen(port: number, hostname: string = '127.0.0.1') {
+  async listen(port: number, hostname: string = '0.0.0.0') {
     // @ts-ignore
     if (typeof Bun !== 'undefined') {
       // @ts-ignore
@@ -907,9 +923,12 @@ export class Spiceflow<
         reusePort: true,
         error(error) {
           console.error(error)
-          return new Response('Internal Server Error', {
-            status: 500,
-          })
+          return new Response(
+            JSON.stringify({ message: 'Internal Server Error' }),
+            {
+              status: 500,
+            },
+          )
         },
 
         fetch: async (request) => {
@@ -985,7 +1004,7 @@ export class Spiceflow<
       } catch (error) {
         console.error('Error handling request:', error)
         res.statusCode = 500
-        res.end('Internal Server Error')
+        res.end(JSON.stringify({ message: 'Internal Server Error' }))
       }
     })
 
@@ -1003,16 +1022,18 @@ export class Spiceflow<
     onErrorHandlers,
     generator,
     request,
+    route,
   }: {
     generator: Generator | AsyncGenerator
     onErrorHandlers: OnError[]
     request: Request
+    route: InternalRoute
   }) {
     let init = generator.next()
     if (init instanceof Promise) init = await init
 
     if (init?.done) {
-      return await turnHandlerResultIntoResponse(init.value)
+      return await turnHandlerResultIntoResponse(init.value, route)
     }
     // let errorHandlers = this.routerTree.onErrorHandlers
     let self = this
@@ -1197,7 +1218,10 @@ export function bfs(tree: AnySpiceflow) {
   return nodes
 }
 
-export async function turnHandlerResultIntoResponse(result: any) {
+export async function turnHandlerResultIntoResponse(
+  result: any,
+  route: InternalRoute,
+) {
   // if user returns a promise, await it
   if (result instanceof Promise) {
     result = await result
@@ -1207,6 +1231,52 @@ export async function turnHandlerResultIntoResponse(result: any) {
     return result
   }
 
+  if (route.type) {
+    if (route.type?.includes('multipart/form-data')) {
+      if (!(result instanceof Response)) {
+        throw new Error(
+          `Invalid form data returned from route handler ${
+            route.path
+          } - expected Response but got ${
+            result?.constructor?.name || typeof result
+          }. FormData cannot be returned directly - it must be wrapped in a Response object with the appropriate content-type header.`,
+        )
+      }
+    }
+    if (route.type?.includes('application/x-www-form-urlencoded')) {
+      if (!(result instanceof URLSearchParams)) {
+        throw new Error(
+          `Invalid URL encoded data returned from route handler ${
+            route.path
+          } - expected URLSearchParams but got ${
+            result?.constructor?.name || typeof result
+          }`,
+        )
+      }
+      return new Response(result, {
+        headers: {
+          'content-type': 'application/x-www-form-urlencoded',
+        },
+      })
+    }
+
+    if (route.type?.includes('text/plain')) {
+      if (typeof result !== 'string') {
+        throw new Error(
+          `Invalid text returned from route handler ${
+            route.path
+          } - expected string but got ${
+            result?.constructor?.name || typeof result
+          }`,
+        )
+      }
+      return new Response(result, {
+        headers: {
+          'content-type': 'text/plain',
+        },
+      })
+    }
+  }
   return new Response(JSON.stringify(result ?? null, null, 2), {
     headers: {
       'content-type': 'application/json',