@furystack/rest-service 10.0.23 → 10.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/rest-service",
-  "version": "10.0.23",
+  "version": "10.0.24",
   "description": "Repository implementation for FuryStack",
   "type": "module",
   "scripts": {
@@ -37,11 +37,11 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "dependencies": {
-    "@furystack/core": "^15.0.22",
+    "@furystack/core": "^15.0.23",
     "@furystack/inject": "^12.0.19",
-    "@furystack/repository": "^10.0.22",
-    "@furystack/rest": "^8.0.22",
-    "@furystack/security": "^6.0.22",
+    "@furystack/repository": "^10.0.23",
+    "@furystack/rest": "^8.0.23",
+    "@furystack/security": "^6.0.23",
     "@furystack/utils": "^8.1.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -49,8 +49,8 @@
     "semaphore-async-await": "^1.5.1"
   },
   "devDependencies": {
-    "@furystack/rest-client-fetch": "^8.0.22",
-    "@types/node": "^24.0.3",
+    "@furystack/rest-client-fetch": "^8.0.23",
+    "@types/node": "^24.0.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },

package/src/api-manager.ts

@@ -10,11 +10,13 @@ import { match } from 'path-to-regexp'
 import { ErrorAction } from './actions/error-action.js'
 import { NotFoundAction } from './actions/not-found-action.js'
 import { addCorsHeaders } from './add-cors-header.js'
+import { CreateGetSchemaAction } from './endpoint-generators/create-get-schema-action.js'
+import { CreateGetSwaggerJsonAction } from './endpoint-generators/create-get-swagger-json-action.js'
 import { HttpUserContext } from './http-user-context.js'
 import type { CorsOptions } from './models/cors-options.js'
 import { readPostBody } from './read-post-body.js'
 import type { RequestAction } from './request-action-implementation.js'
-import type { OnRequest } from './server-manager.js'
+import type { OnRequest, ServerApi } from './server-manager.js'
 import { ServerManager } from './server-manager.js'
 import './server-response-extensions.js'
 
@@ -25,13 +27,57 @@ export type RestApiImplementation<T extends RestApi> = {
 }
 
 export interface ImplementApiOptions<T extends RestApi> {
+  /**
+   * The structure of the implemented API.
+   */
   api: RestApiImplementation<T>
+  /**
+   * The Injector instance to use for dependency injection in the API actions.
+   */
   injector: Injector
+  /**
+   * The host name for the API Server. If not provided, the default host (ServerManager.DEFAULT_HOST) will be used.
+   */
   hostName?: string
+  /**
+   * The root path for the API. This will be prepended to all API paths.
+   */
   root: string
+  /**
+   * The port on which the API server will listen.
+   */
   port: number
+  /**
+   * CORS options to configure Cross-Origin Resource Sharing for the API.
+   */
   cors?: CorsOptions
+  /**
+   * An optional function to deserialize query parameters from the URL.
+   * This function should take a query string (e.g., "?key=value") and return an object with the parsed parameters.
+   * If not provided, the default deserialization will be used.
+   */
   deserializeQueryParams?: (param: string) => any
+  /**
+   * Adds an additional 'GET /schema' endpoint that returns the schema definitions of the API.
+   * Also adds a 'GET /swagger.json' endpoint that returns the API schema in OpenAPI 3.0 (Swagger) format.
+   */
+  enableGetSchema?: boolean
+
+  /**
+   * Optional name for the API, used in the generated schema.
+   * This can be useful for documentation or identification purposes.
+   */
+  name?: string
+  /**
+   * Optional description for the API, used in the generated schema.
+   * This can provide additional context or information about the API's purpose.
+   */
+  description?: string
+  /**
+   * Optional version for the API, used in the generated schema.
+   * This can help in versioning the API and tracking changes over time.
+   */
+  version?: string
 }
 
 export type NewCompiledApiEntry = {
@@ -92,12 +138,27 @@ export class ApiManager implements Disposable {
     cors,
     injector,
     deserializeQueryParams,
+    enableGetSchema,
+    name,
+    description,
+    version,
   }: ImplementApiOptions<T>) {
-    const supportedMethods = this.getSuportedMethods(api)
+    const extendedApi: typeof api = enableGetSchema
+      ? {
+          ...api,
+          GET: {
+            ...api.GET,
+            '/schema': CreateGetSchemaAction(api, name, description, version),
+            '/swagger.json': CreateGetSwaggerJsonAction(api, name, description, version),
+          },
+        }
+      : api
+
+    const supportedMethods = this.getSuportedMethods(extendedApi)
     const rootApiPath = PathHelper.normalize(root)
     const server = await this.serverManager.getOrCreate({ hostName, port })
-    const compiledApi = this.compileApi(api, root)
-    server.apis.push({
+    const compiledApi = this.compileApi(extendedApi, root)
+    const serverApi = {
       shouldExec: (msg) =>
         this.shouldExecRequest({
           ...msg,
@@ -118,7 +179,9 @@ export class ApiManager implements Disposable {
           hostName,
           deserializeQueryParams,
         }),
-    })
+    } satisfies ServerApi
+    server.apis.push(serverApi)
+    return serverApi
   }
 
   public shouldExecRequest(options: {

package/src/authenticate.ts

@@ -7,7 +7,7 @@ import { JsonResult } from './request-action-implementation.js'
 export const Authenticate =
   () =>
   <T extends { result: unknown }>(action: RequestAction<T>): RequestAction<T> => {
-    return async (args: RequestActionOptions<T>): Promise<ActionResult<T>> => {
+    const wrapped = async (args: RequestActionOptions<T>): Promise<ActionResult<T>> => {
       const { injector } = args
       const authenticated = await isAuthenticated(injector)
       if (!authenticated) {
@@ -20,4 +20,8 @@ export const Authenticate =
       }
       return (await action(args)) as ActionResult<T>
     }
+
+    wrapped.isAuthenticated = true
+
+    return wrapped
   }

package/src/endpoint-generators/create-get-schema-action.ts

@@ -0,0 +1,29 @@
+import { RequestError } from '@furystack/rest'
+import type { RestApiImplementation } from '../api-manager.js'
+import { getSchemaFromApi } from '../get-schema-from-api.js'
+import { JsonResult, type RequestAction } from '../request-action-implementation.js'
+
+export type GetSchemaResult = ReturnType<typeof getSchemaFromApi>
+
+/**
+ * Creates a GET action that returns the schema of the provided API.
+ * The schema is returned in JSON format when the request's Accept header includes 'application/schema+json'.
+ * If the Accept header does not match, a 406 Not Acceptable error is thrown.
+ *
+ * @param api - The API implementation from which to extract the schema.
+ * @returns A RequestAction that handles the GET request for the schema.
+ */
+export const CreateGetSchemaAction = <T extends RestApiImplementation<any>>(
+  api: T,
+  name = 'FuryStack API',
+  description = 'API documentation generated from FuryStack API schema',
+  version = '1.0.0',
+): RequestAction<{ result: GetSchemaResult }> => {
+  const schema = getSchemaFromApi({ api, name, description, version })
+  return async ({ request }) => {
+    if (request.headers.accept?.includes('application/schema+json')) {
+      return JsonResult(schema, 200)
+    }
+    throw new RequestError('The requested content type is not supported. Please use "application/schema+json".', 406)
+  }
+}

package/src/endpoint-generators/create-get-swagger-json-action.ts

@@ -0,0 +1,26 @@
+import { type ApiEndpointDefinition, type SwaggerDocument } from '@furystack/rest'
+import type { RestApiImplementation } from '../api-manager.js'
+import { getSchemaFromApi } from '../get-schema-from-api.js'
+import { JsonResult, type RequestAction } from '../request-action-implementation.js'
+import { generateSwaggerJsonFromApiSchema } from '../swagger/generate-swagger-json.js'
+
+export type GetSchemaResult = Record<string, ApiEndpointDefinition>
+
+/**
+ * Generates a RequestAction that retrieves the Swagger JSON schema from a FuryStack API implementation.
+ *
+ * @param api - The API implementation from which to extract the schema.
+ * @returns A RequestAction that handles the GET request for the schema.
+ */
+export const CreateGetSwaggerJsonAction = <T extends RestApiImplementation<any>>(
+  api: T,
+  name = 'FuryStack API',
+  description = 'API documentation generated from FuryStack API schema',
+  version = '1.0.0',
+): RequestAction<{ result: GetSchemaResult | SwaggerDocument }> => {
+  const { endpoints } = getSchemaFromApi({ api, name, description, version })
+  const swaggerJson = generateSwaggerJsonFromApiSchema({ api: endpoints, title: name, description, version })
+  return async () => {
+    return JsonResult(swaggerJson, 200)
+  }
+}

package/src/endpoint-generators/index.ts

@@ -1,5 +1,6 @@
 export * from './create-delete-endpoint.js'
 export * from './create-get-collection-endpoint.js'
 export * from './create-get-entity-endpoint.js'
+export * from './create-get-schema-action.js'
 export * from './create-patch-endpoint.js'
 export * from './create-post-endpoint.js'

package/src/endpoint-generators/with-schema-and-swagger-action.ts

@@ -0,0 +1,11 @@
+import type { RestApi, SwaggerDocument } from '@furystack/rest'
+
+/**
+ * Extends a RestApi with endpoints for both schema.json and swagger.json
+ */
+export type WithSchemaAndSwaggerAction<T extends RestApi> = T & {
+  GET: {
+    '/schema': { result: Record<string, any>; headers: { accept: 'application/schema+json' } }
+    '/swagger.json': { result: SwaggerDocument; headers: { accept: 'application/swagger+json' } }
+  }
+}

package/src/get-schema-from-api.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import type { RestApiImplementation } from './api-manager.js'
+import { defaultSchema, getSchemaFromApi } from './get-schema-from-api.js'
+import { JsonResult, type RequestAction } from './request-action-implementation.js'
+import validationSchema from './validate.integration.spec.schema.json' with { type: 'json' }
+import { Validate } from './validate.js'
+
+const ExampleAction: RequestAction<any> = async () => {
+  return JsonResult({ success: true })
+}
+
+describe('getSchemaFromApi', () => {
+  it('Should return the default schema from the API', () => {
+    const Api = {
+      GET: {
+        '/example': ExampleAction,
+      },
+    } as const satisfies RestApiImplementation<any>
+
+    const schema = getSchemaFromApi({
+      api: Api,
+      name: 'Test API',
+      description: 'Test API Description',
+      version: '1.0.0',
+    })
+    expect(schema).toEqual({
+      name: 'Test API',
+      description: 'Test API Description',
+      version: '1.0.0',
+      endpoints: {
+        '/example': {
+          isAuthenticated: false,
+          path: '/example',
+          method: 'GET',
+          schema: defaultSchema,
+          schemaName: 'default',
+        },
+      },
+    })
+  })
+
+  it('Should return the attached schema from the validation', () => {
+    const Api = {
+      GET: {
+        '/validate-query': Validate({
+          schema: validationSchema,
+          schemaName: 'ValidateQuery',
+        })(async () => JsonResult({ success: true })),
+      },
+    } as const satisfies RestApiImplementation<any>
+
+    const schema = getSchemaFromApi({
+      api: Api,
+      name: 'Test API',
+      description: 'Test API Description',
+      version: '1.0.0',
+    })
+    expect(schema).toEqual({
+      name: 'Test API',
+      description: 'Test API Description',
+      version: '1.0.0',
+      endpoints: {
+        '/validate-query': {
+          isAuthenticated: false,
+          path: '/validate-query',
+          method: 'GET',
+          schema: validationSchema,
+          schemaName: 'ValidateQuery',
+        },
+      },
+    })
+  })
+})

package/src/get-schema-from-api.ts

@@ -0,0 +1,74 @@
+import type { ApiEndpointDefinition, ApiEndpointSchema, Method, RestApi, Schema } from '@furystack/rest'
+import type { RestApiImplementation } from './api-manager.js'
+import type { RequestAction } from './request-action-implementation.js'
+
+export const defaultSchema: Schema = {
+  definitions: {
+    default: {
+      type: 'object',
+      properties: {
+        headers: {
+          type: 'object',
+          additionalProperties: true,
+        },
+        query: {
+          type: 'object',
+          additionalProperties: true,
+        },
+        body: {
+          type: 'object',
+          additionalProperties: true,
+        },
+        url: {
+          type: 'object',
+          additionalProperties: true,
+        },
+      },
+      required: [],
+      description: 'Default schema for API endpoints',
+      additionalProperties: true,
+    },
+  },
+}
+
+const defaultSchemaName = 'default'
+
+const getDefinitionFromAction = (method: Method, path: string, action: RequestAction<any>): ApiEndpointDefinition => {
+  return {
+    method,
+    path,
+    schema: 'schema' in action && typeof action.schema === 'object' ? action.schema : defaultSchema,
+    schemaName: 'schemaName' in action && typeof action.schemaName === 'string' ? action.schemaName : defaultSchemaName,
+    isAuthenticated:
+      'isAuthenticated' in action && typeof action.isAuthenticated === 'boolean' ? action.isAuthenticated : false,
+  }
+}
+
+export const getSchemaFromApi = <T extends RestApiImplementation<RestApi>>({
+  api,
+  name = 'FuryStack API',
+  description = 'API documentation generated from FuryStack API schema',
+  version = '1.0.0',
+}: {
+  api: T
+  name?: string
+  description?: string
+  version?: string
+}): ApiEndpointSchema => {
+  const endpoints: Record<string, ApiEndpointDefinition> = {}
+
+  Object.entries(api).forEach(([method, endpointList]) => {
+    Object.entries(endpointList as Record<string, RequestAction<any>>).forEach(([url, requestAction]) => {
+      if (method && url && requestAction) {
+        endpoints[url] = getDefinitionFromAction(method as Method, url, requestAction)
+      }
+    })
+  })
+
+  return {
+    name,
+    description,
+    version,
+    endpoints,
+  }
+}

package/src/index.ts

@@ -1,18 +1,19 @@
-export * from './helpers.js'
+export * from './actions/index.js'
 export * from './add-cors-header.js'
 export * from './api-manager.js'
-export * from './actions/index.js'
 export * from './authenticate.js'
 export * from './authorize.js'
+export * from './endpoint-generators/index.js'
+export * from './get-schema-from-api.js'
+export * from './helpers.js'
 export * from './http-authentication-settings.js'
 export * from './http-user-context.js'
-export * from './server-manager.js'
-export * from './server-response-extensions.js'
-export * from './models/index.js'
-export * from './endpoint-generators/index.js'
-export * from './schema-validator/index.js'
-export * from './request-action-implementation.js'
-export * from './validate.js'
 export * from './mime-types.js'
+export * from './models/index.js'
 export * from './read-post-body.js'
+export * from './request-action-implementation.js'
+export * from './schema-validator/index.js'
+export * from './server-manager.js'
+export * from './server-response-extensions.js'
 export * from './static-server-manager.js'
+export * from './validate.js'

package/src/swagger/generate-swagger-json.spec.ts

@@ -0,0 +1,239 @@
+import type { ApiEndpointDefinition, ParameterObject, ReferenceObject, ResponseObject } from '@furystack/rest'
+import { describe, expect, it } from 'vitest'
+import { generateSwaggerJsonFromApiSchema } from './generate-swagger-json.js'
+
+describe('generateSwaggerJsonFromApiSchema', () => {
+  it('Should generate a basic Swagger document with correct OpenAPI structure', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/test': {
+        method: 'GET',
+        path: '/api/test',
+        isAuthenticated: false,
+        schemaName: 'Test',
+        schema: { type: 'object', properties: { id: { type: 'string' } } },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check basic structure
+    expect(result.openapi).toBe('3.1.0')
+    expect(result.info.title).toBe('FuryStack API')
+    expect(result.info.version).toBe('1.0.0')
+
+    // Check security scheme is defined correctly for cookie-based auth
+    expect(result.components?.securitySchemes?.cookieAuth).toEqual({
+      type: 'apiKey',
+      in: 'cookie',
+      name: 'session',
+    })
+  })
+
+  it('Should convert API endpoints to OpenAPI paths correctly', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/users': {
+        method: 'GET',
+        path: '/api/users',
+        isAuthenticated: true,
+        schemaName: 'UserCollection',
+        schema: { type: 'array', items: { type: 'object' } },
+      },
+      '/api/users/:id': {
+        method: 'GET',
+        path: '/api/users/:id',
+        isAuthenticated: true,
+        schemaName: 'User',
+        schema: { type: 'object', properties: { id: { type: 'string' } } },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check paths
+    expect(result.paths?.['/api/users']).toBeDefined()
+    expect(result.paths?.['/api/users/{id}']).toBeDefined()
+
+    // Check methods
+    expect(result.paths?.['/api/users']?.get).toBeDefined()
+    expect(result.paths?.['/api/users/{id}']?.get).toBeDefined()
+
+    // Check security - should use cookieAuth for authenticated endpoints
+    expect(result.paths?.['/api/users']?.get?.security).toEqual([{ cookieAuth: [] }])
+    expect(result.paths?.['/api/users/{id}']?.get?.security).toEqual([{ cookieAuth: [] }])
+  })
+
+  it('Should extract path parameters correctly', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/users/:userId/posts/:postId': {
+        method: 'GET',
+        path: '/api/users/:userId/posts/:postId',
+        isAuthenticated: false,
+        schemaName: 'Post',
+        schema: { type: 'object' },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check path parameters
+    const parameters = result.paths?.['/api/users/{userId}/posts/{postId}']?.get?.parameters as ParameterObject[]
+    expect(parameters).toHaveLength(2)
+    expect(parameters?.[0].name).toBe('userId')
+    expect(parameters?.[0].in).toBe('path')
+    expect(parameters?.[0].required).toBe(true)
+    expect(parameters?.[1].name).toBe('postId')
+    expect(parameters?.[1].in).toBe('path')
+    expect(parameters?.[1].required).toBe(true)
+  })
+
+  it('Should handle different HTTP methods correctly', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/resource-get': {
+        method: 'GET',
+        path: '/api/resource-get',
+        isAuthenticated: false,
+        schemaName: 'Resource',
+        schema: { type: 'object' },
+      },
+      '/api/resource-post': {
+        method: 'POST',
+        path: '/api/resource-post',
+        isAuthenticated: true,
+        schemaName: 'ResourceInput',
+        schema: { type: 'object' },
+      },
+      '/api/resource-put/:id': {
+        method: 'PUT',
+        path: '/api/resource-put/:id',
+        isAuthenticated: true,
+        schemaName: 'ResourceUpdate',
+        schema: { type: 'object' },
+      },
+      '/api/resource-delete/:id': {
+        method: 'DELETE',
+        path: '/api/resource-delete/:id',
+        isAuthenticated: true,
+        schemaName: 'ResourceDelete',
+        schema: { type: 'object' },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check multiple methods
+    expect(result.paths?.['/api/resource-get'].get).toBeDefined()
+    expect(result.paths?.['/api/resource-post'].post).toBeDefined()
+    expect(result.paths?.['/api/resource-put/{id}'].put).toBeDefined()
+    expect(result.paths?.['/api/resource-delete/{id}'].delete).toBeDefined()
+
+    // Verify security is applied correctly based on isAuthenticated
+    expect(result.paths?.['/api/resource-get'].get?.security).toEqual([])
+    expect(result.paths?.['/api/resource-post'].post?.security).toEqual([{ cookieAuth: [] }])
+  })
+
+  it('Should include schemas in components', () => {
+    const testSchema = {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+    }
+
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/test': {
+        method: 'GET',
+        path: '/api/test',
+        isAuthenticated: false,
+        schemaName: 'TestModel',
+        schema: testSchema,
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check schema is included in components
+    expect(result.components?.schemas?.TestModel).toEqual(testSchema)
+  })
+
+  it('Should handle responses with correct status codes and content types', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/test': {
+        method: 'GET',
+        path: '/api/test',
+        isAuthenticated: false,
+        schemaName: 'Test',
+        schema: { type: 'object' },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check response structure
+    const responses = result.paths?.['/api/test'].get?.responses as Record<string, ResponseObject>
+
+    const response200 = responses?.['200']
+    expect(response200).toBeDefined()
+    expect(response200.description).toBe('Successful operation')
+    expect((response200.content?.['application/json']?.schema as ReferenceObject).$ref).toBe(
+      '#/components/schemas/Test',
+    )
+    expect(responses?.['401']).toBeDefined()
+    expect(responses?.['500']).toBeDefined()
+    expect(responses?.['401'].description).toBe('Unauthorized')
+    expect(responses?.['500'].description).toBe('Internal server error')
+  })
+
+  it('Should use empty path object if it does not exist - for code coverage', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/test': {
+        method: 'GET',
+        path: '/api/test',
+        isAuthenticated: false,
+        schemaName: 'Test',
+        schema: { type: 'object' },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // This test is mainly for coverage, checking that the path initialization logic works
+    expect(result.paths?.['/api/test']).toBeDefined()
+  })
+
+  it('Should handle endpoints without schemas', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/no-schema': {
+        method: 'GET',
+        path: '/api/no-schema',
+        isAuthenticated: false,
+        schemaName: 'EmptySchema',
+        schema: null as any,
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Should still create the path without errors
+    expect(result.paths?.['/api/no-schema']).toBeDefined()
+    expect(result.paths?.['/api/no-schema'].get).toBeDefined()
+  })
+
+  it('Should use operationId based on method and path', () => {
+    const api: Record<string, ApiEndpointDefinition> = {
+      '/api/users/:id/profile': {
+        method: 'GET',
+        path: '/api/users/:id/profile',
+        isAuthenticated: false,
+        schemaName: 'UserProfile',
+        schema: { type: 'object' },
+      },
+    }
+
+    const result = generateSwaggerJsonFromApiSchema({ api })
+
+    // Check operationId format
+    expect(result.paths?.['/api/users/{id}/profile'].get?.operationId).toBe('get_api_users_id_profile')
+  })
+})