vector-framework 1.0.0 → 1.2.0

package/src/openapi/generator.ts

@@ -0,0 +1,359 @@
+import type { RegisteredRouteDefinition } from '../core/router';
+import type { OpenAPIInfoOptions, RouteSchemaDefinition, StandardJSONSchemaCapable } from '../types';
+
+type JsonSchema = Record<string, unknown>;
+
+export interface OpenAPIGenerationOptions {
+  target: string;
+  info?: OpenAPIInfoOptions;
+}
+
+export interface OpenAPIGenerationResult {
+  document: Record<string, unknown>;
+  warnings: string[];
+}
+
+function isJSONSchemaCapable(schema: unknown): schema is StandardJSONSchemaCapable {
+  const standard = (schema as any)?.['~standard'];
+  const converter = standard?.jsonSchema;
+  return (
+    !!standard &&
+    typeof standard === 'object' &&
+    standard.version === 1 &&
+    !!converter &&
+    typeof converter.input === 'function' &&
+    typeof converter.output === 'function'
+  );
+}
+
+function normalizeRoutePathForOpenAPI(path: string): { openapiPath: string; pathParamNames: string[] } {
+  let wildcardCount = 0;
+  const pathParamNames: string[] = [];
+
+  const segments = path.split('/').map((segment) => {
+    const greedyParamMatch = /^:([A-Za-z0-9_]+)\+$/.exec(segment);
+    if (greedyParamMatch?.[1]) {
+      pathParamNames.push(greedyParamMatch[1]);
+      return `{${greedyParamMatch[1]}}`;
+    }
+
+    const paramMatch = /^:([A-Za-z0-9_]+)$/.exec(segment);
+    if (paramMatch?.[1]) {
+      pathParamNames.push(paramMatch[1]);
+      return `{${paramMatch[1]}}`;
+    }
+
+    if (segment === '*') {
+      wildcardCount += 1;
+      const wildcardParamName = wildcardCount === 1 ? 'wildcard' : `wildcard${wildcardCount}`;
+      pathParamNames.push(wildcardParamName);
+      return `{${wildcardParamName}}`;
+    }
+
+    return segment;
+  });
+
+  return {
+    openapiPath: segments.join('/'),
+    pathParamNames,
+  };
+}
+
+function toOpenAPIPath(path: string): string {
+  return normalizeRoutePathForOpenAPI(path).openapiPath;
+}
+
+function createOperationId(method: string, path: string): string {
+  const normalized = `${method.toLowerCase()}_${path}`
+    .replace(/[:{}]/g, '')
+    .replace(/[^A-Za-z0-9_]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return normalized || `${method.toLowerCase()}_operation`;
+}
+
+function inferTagFromPath(path: string): string {
+  const segments = path.split('/').filter(Boolean);
+  for (const segment of segments) {
+    if (!segment.startsWith(':') && segment !== '*') {
+      return segment.toLowerCase();
+    }
+  }
+  return 'default';
+}
+
+function extractPathParamNames(path: string): string[] {
+  return normalizeRoutePathForOpenAPI(path).pathParamNames;
+}
+
+function addMissingPathParameters(operation: Record<string, any>, routePath: string): void {
+  const existingPathNames = new Set(
+    (operation.parameters || []).filter((p: any) => p.in === 'path').map((p: any) => String(p.name))
+  );
+
+  for (const pathName of extractPathParamNames(routePath)) {
+    if (existingPathNames.has(pathName)) continue;
+
+    (operation.parameters ||= []).push({
+      name: pathName,
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    });
+  }
+}
+
+function isNoBodyResponseStatus(status: string): boolean {
+  const numericStatus = Number(status);
+  if (!Number.isInteger(numericStatus)) return false;
+  return (
+    (numericStatus >= 100 && numericStatus < 200) ||
+    numericStatus === 204 ||
+    numericStatus === 205 ||
+    numericStatus === 304
+  );
+}
+
+function getResponseDescription(status: string): string {
+  if (status === '204') return 'No Content';
+  if (status === '205') return 'Reset Content';
+  if (status === '304') return 'Not Modified';
+  const numericStatus = Number(status);
+  if (Number.isInteger(numericStatus) && numericStatus >= 100 && numericStatus < 200) {
+    return 'Informational';
+  }
+  return 'OK';
+}
+
+function convertInputSchema(
+  routePath: string,
+  inputSchema: unknown,
+  target: string,
+  warnings: string[]
+): JsonSchema | null {
+  if (!isJSONSchemaCapable(inputSchema)) {
+    return null;
+  }
+
+  try {
+    return inputSchema['~standard'].jsonSchema.input({ target });
+  } catch (error) {
+    warnings.push(
+      `[OpenAPI] Failed input schema conversion for ${routePath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+    return null;
+  }
+}
+
+function convertOutputSchema(
+  routePath: string,
+  statusCode: string,
+  outputSchema: unknown,
+  target: string,
+  warnings: string[]
+): JsonSchema | null {
+  if (!isJSONSchemaCapable(outputSchema)) {
+    return null;
+  }
+
+  try {
+    return outputSchema['~standard'].jsonSchema.output({ target });
+  } catch (error) {
+    warnings.push(
+      `[OpenAPI] Failed output schema conversion for ${routePath} (${statusCode}): ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+    return null;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function addStructuredInputToOperation(operation: Record<string, any>, inputJSONSchema: JsonSchema): void {
+  if (!isRecord(inputJSONSchema)) return;
+  if (inputJSONSchema.type !== 'object' || !isRecord(inputJSONSchema.properties)) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        'application/json': {
+          schema: inputJSONSchema,
+        },
+      },
+    };
+    return;
+  }
+
+  const rootRequired = new Set<string>(
+    Array.isArray(inputJSONSchema.required) ? (inputJSONSchema.required as string[]) : []
+  );
+  const properties = inputJSONSchema.properties as Record<string, unknown>;
+  const parameters: any[] = Array.isArray(operation.parameters) ? operation.parameters : [];
+
+  const parameterSections: Array<{
+    key: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+  }> = [
+    { key: 'params', in: 'path' },
+    { key: 'query', in: 'query' },
+    { key: 'headers', in: 'header' },
+    { key: 'cookies', in: 'cookie' },
+  ];
+
+  for (const section of parameterSections) {
+    const sectionSchema = properties[section.key];
+    if (!isRecord(sectionSchema)) continue;
+    if (sectionSchema.type !== 'object' || !isRecord(sectionSchema.properties)) continue;
+
+    const sectionRequired = new Set<string>(
+      Array.isArray(sectionSchema.required) ? (sectionSchema.required as string[]) : []
+    );
+
+    for (const [name, schema] of Object.entries(sectionSchema.properties)) {
+      parameters.push({
+        name,
+        in: section.in,
+        required: section.in === 'path' ? true : sectionRequired.has(name),
+        schema: isRecord(schema) ? schema : {},
+      });
+    }
+  }
+
+  if (parameters.length > 0) {
+    const deduped = new Map<string, any>();
+    for (const parameter of parameters) {
+      deduped.set(`${parameter.in}:${parameter.name}`, parameter);
+    }
+    operation.parameters = [...deduped.values()];
+  }
+
+  const bodySchema = properties.body;
+  if (bodySchema) {
+    operation.requestBody = {
+      required: rootRequired.has('body'),
+      content: {
+        'application/json': {
+          schema: isRecord(bodySchema) ? bodySchema : {},
+        },
+      },
+    };
+  }
+}
+
+function addOutputSchemasToOperation(
+  operation: Record<string, any>,
+  routePath: string,
+  routeSchema: RouteSchemaDefinition,
+  target: string,
+  warnings: string[]
+): void {
+  const output = routeSchema.output;
+
+  if (!output) {
+    operation.responses = {
+      200: { description: 'OK' },
+    };
+    return;
+  }
+
+  const responses: Record<string, any> = {};
+
+  // Single output schema shorthand: schema.output = SomeSchema (defaults to 200)
+  if (typeof output === 'object' && output !== null && '~standard' in output) {
+    const outputSchema = convertOutputSchema(routePath, '200', output, target, warnings);
+
+    if (outputSchema) {
+      responses['200'] = {
+        description: 'OK',
+        content: {
+          'application/json': {
+            schema: outputSchema,
+          },
+        },
+      };
+    } else {
+      responses['200'] = { description: 'OK' };
+    }
+  } else {
+    for (const [statusCode, schema] of Object.entries(output as Record<string, unknown>)) {
+      const status = String(statusCode);
+      const outputSchema = convertOutputSchema(routePath, status, schema, target, warnings);
+      const description = getResponseDescription(status);
+
+      if (outputSchema && !isNoBodyResponseStatus(status)) {
+        responses[status] = {
+          description,
+          content: {
+            'application/json': {
+              schema: outputSchema,
+            },
+          },
+        };
+      } else {
+        responses[status] = {
+          description,
+        };
+      }
+    }
+  }
+
+  if (Object.keys(responses).length === 0) {
+    responses['200'] = { description: 'OK' };
+  }
+
+  operation.responses = responses;
+}
+
+export function generateOpenAPIDocument(
+  routes: RegisteredRouteDefinition[],
+  options: OpenAPIGenerationOptions
+): OpenAPIGenerationResult {
+  const warnings: string[] = [];
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  for (const route of routes) {
+    if (route.options.expose === false) continue;
+    if (!route.method || !route.path) continue;
+
+    const method = route.method.toLowerCase();
+    if (method === 'options') continue;
+
+    const openapiPath = toOpenAPIPath(route.path);
+    const operation: Record<string, any> = {
+      operationId: createOperationId(method, openapiPath),
+      tags: [route.options.schema?.tag || inferTagFromPath(route.path)],
+    };
+
+    const inputJSONSchema = convertInputSchema(route.path, route.options.schema?.input, options.target, warnings);
+
+    if (inputJSONSchema) {
+      addStructuredInputToOperation(operation, inputJSONSchema);
+    }
+    addMissingPathParameters(operation, route.path);
+
+    addOutputSchemasToOperation(operation, route.path, route.options.schema || {}, options.target, warnings);
+
+    paths[openapiPath] ||= {};
+    paths[openapiPath][method] = operation;
+  }
+
+  const openapiVersion = options.target === 'openapi-3.0' ? '3.0.3' : '3.1.0';
+
+  const document = {
+    openapi: openapiVersion,
+    info: {
+      title: options.info?.title || 'Vector API',
+      version: options.info?.version || '1.0.0',
+      ...(options.info?.description ? { description: options.info.description } : {}),
+    },
+    paths,
+  };
+
+  return {
+    document,
+    warnings,
+  };
+}

package/src/types/index.ts

@@ -1,4 +1,4 @@
-import type { IRequest } from 'itty-router';
+import type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from './standard-schema';
 
 // Default AuthUser type - users can override this with their own type
 export interface DefaultAuthUser {
@@ -27,13 +27,9 @@ export interface DefaultVectorTypes extends VectorTypes {
 }
 
 // Type helpers
-export type GetAuthType<T extends VectorTypes> = T['auth'] extends undefined
-  ? DefaultAuthUser
-  : T['auth'];
+export type GetAuthType<T extends VectorTypes> = T['auth'] extends undefined ? DefaultAuthUser : T['auth'];
 
-export type GetContextType<T extends VectorTypes> = T['context'] extends undefined
-  ? Record<string, any>
-  : T['context'];
+export type GetContextType<T extends VectorTypes> = T['context'] extends undefined ? Record<string, any> : T['context'];
 
 export type GetCacheType<T extends VectorTypes> = T['cache'] extends undefined ? any : T['cache'];
 
@@ -44,16 +40,39 @@ export type GetMetadataType<T extends VectorTypes> = T['metadata'] extends undef
 // Legacy support - keep AuthUser for backward compatibility
 export type AuthUser = DefaultAuthUser;
 
-export interface VectorRequest<TTypes extends VectorTypes = DefaultVectorTypes>
-  extends Omit<IRequest, 'params'> {
+type DefaultQueryShape = { [key: string]: string | string[] | undefined };
+type DefaultParamsShape = Record<string, string>;
+type DefaultCookiesShape = Record<string, string>;
+
+type BaseVectorRequest = Omit<Request, 'body' | 'json' | 'text' | 'formData' | 'arrayBuffer' | 'blob'>;
+
+type InferValidatedSection<TValidatedInput, TKey extends string, TFallback> = [TValidatedInput] extends [undefined]
+  ? TFallback
+  : TValidatedInput extends Record<string, unknown>
+    ? TKey extends keyof TValidatedInput
+      ? TValidatedInput[TKey]
+      : TFallback
+    : TFallback;
+
+type InferValidatedInputValue<TValidatedInput> = [TValidatedInput] extends [undefined] ? unknown : TValidatedInput;
+
+export type BunRouteHandler = (req: Request) => Response | Promise<Response>;
+export type BunMethodMap = Record<string, BunRouteHandler>;
+export type BunRouteTable = Record<string, BunMethodMap | Response>;
+export type LegacyRouteEntry = [string, RegExp, [BunRouteHandler, ...BunRouteHandler[]], string?];
+
+export interface VectorRequest<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined>
+  extends BaseVectorRequest {
   authUser?: GetAuthType<TTypes>;
   context: GetContextType<TTypes>;
   metadata?: GetMetadataType<TTypes>;
-  content?: any;
-  params?: Record<string, string>;
-  query: { [key: string]: string | string[] | undefined };
+  content?: InferValidatedSection<TValidatedInput, 'body', any>;
+  body?: InferValidatedSection<TValidatedInput, 'body', any>;
+  params?: InferValidatedSection<TValidatedInput, 'params', DefaultParamsShape>;
+  query: InferValidatedSection<TValidatedInput, 'query', DefaultQueryShape>;
   headers: Headers;
-  cookies?: Record<string, string>;
+  cookies?: InferValidatedSection<TValidatedInput, 'cookies', DefaultCookiesShape>;
+  validatedInput?: InferValidatedInputValue<TValidatedInput>;
   startTime?: number;
   [key: string]: any;
 }
@@ -63,6 +82,33 @@ export interface CacheOptions {
   ttl?: number;
 }
 
+export type StandardRouteSchema = StandardSchemaV1<any, any>;
+export type RouteSchemaStatusCode = number | `${number}` | 'default';
+export type RouteSchemaOutputMap = Partial<Record<RouteSchemaStatusCode, StandardRouteSchema>>;
+
+export interface RouteSchemaDefinition<
+  TInput extends StandardRouteSchema | undefined = StandardRouteSchema | undefined,
+  TOutput extends RouteSchemaOutputMap | StandardRouteSchema | undefined =
+    | RouteSchemaOutputMap
+    | StandardRouteSchema
+    | undefined,
+> {
+  input?: TInput;
+  output?: TOutput;
+  tag?: string;
+}
+
+export type InferStandardSchemaInput<TSchema extends StandardRouteSchema> = StandardSchemaV1.InferInput<TSchema>;
+export type InferStandardSchemaOutput<TSchema extends StandardRouteSchema> = StandardSchemaV1.InferOutput<TSchema>;
+export type StandardJSONSchemaCapable = StandardJSONSchemaV1<any, any>;
+
+export type InferRouteInputFromSchemaDefinition<TSchemaDef extends RouteSchemaDefinition | undefined> =
+  TSchemaDef extends { input: infer TInputSchema }
+    ? TInputSchema extends StandardRouteSchema
+      ? InferStandardSchemaOutput<TInputSchema>
+      : undefined
+    : undefined;
+
 export interface RouteOptions<TTypes extends VectorTypes = DefaultVectorTypes> {
   method: string;
   path: string;
@@ -70,9 +116,23 @@ export interface RouteOptions<TTypes extends VectorTypes = DefaultVectorTypes> {
   expose?: boolean; // defaults to true
   cache?: CacheOptions | number;
   rawRequest?: boolean;
+  validate?: boolean; // defaults to validating schema.input unless false
   rawResponse?: boolean;
   responseContentType?: string;
   metadata?: GetMetadataType<TTypes>;
+  schema?: RouteSchemaDefinition;
+}
+
+export interface RouteBooleanDefaults {
+  auth?: boolean;
+  expose?: boolean;
+  rawRequest?: boolean;
+  validate?: boolean;
+  rawResponse?: boolean;
+}
+
+export interface VectorDefaults {
+  route?: RouteBooleanDefaults;
 }
 
 // Legacy config interface - will be deprecated
@@ -88,6 +148,8 @@ export interface VectorConfig<TTypes extends VectorTypes = DefaultVectorTypes> {
   routeExcludePatterns?: string[];
   autoDiscover?: boolean;
   idleTimeout?: number;
+  defaults?: VectorDefaults;
+  openapi?: OpenAPIOptions | boolean;
 }
 
 // New config-driven schema - flat structure
@@ -100,6 +162,7 @@ export interface VectorConfigSchema<TTypes extends VectorTypes = DefaultVectorTy
   routesDir?: string;
   routeExcludePatterns?: string[];
   idleTimeout?: number;
+  defaults?: VectorDefaults;
 
   // Middleware functions
   before?: BeforeMiddlewareHandler<TTypes>[];
@@ -112,6 +175,9 @@ export interface VectorConfigSchema<TTypes extends VectorTypes = DefaultVectorTy
   // CORS configuration
   cors?: CorsOptions | boolean;
 
+  // OpenAPI/docs configuration
+  openapi?: OpenAPIOptions | boolean;
+
   // Custom types for TypeScript
   types?: VectorTypes;
 }
@@ -125,6 +191,25 @@ export interface CorsOptions {
   maxAge?: number;
 }
 
+export interface OpenAPIDocsOptions {
+  enabled?: boolean;
+  path?: string;
+}
+
+export interface OpenAPIInfoOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+}
+
+export interface OpenAPIOptions {
+  enabled?: boolean;
+  path?: string;
+  target?: 'openapi-3.0' | 'draft-2020-12' | 'draft-07' | ({} & string);
+  docs?: boolean | OpenAPIDocsOptions;
+  info?: OpenAPIInfoOptions;
+}
+
 export type BeforeMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
   request: VectorRequest<TTypes>
 ) => Promise<VectorRequest<TTypes> | Response> | VectorRequest<TTypes> | Response;
@@ -135,8 +220,8 @@ export type AfterMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTyp
 ) => Promise<Response> | Response;
 export type MiddlewareHandler = BeforeMiddlewareHandler | AfterMiddlewareHandler;
 
-export type RouteHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
-  request: VectorRequest<TTypes>
+export type RouteHandler<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined> = (
+  request: VectorRequest<TTypes, TValidatedInput>
 ) => Promise<any> | any;
 
 export type ProtectedHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
@@ -145,9 +230,9 @@ export type ProtectedHandler<TTypes extends VectorTypes = DefaultVectorTypes> =
 
 export type CacheHandler = (key: string, factory: () => Promise<any>, ttl: number) => Promise<any>;
 
-export interface RouteDefinition<TTypes extends VectorTypes = DefaultVectorTypes> {
+export interface RouteDefinition<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined> {
   options: RouteOptions<TTypes>;
-  handler: RouteHandler<TTypes>;
+  handler: RouteHandler<TTypes, TValidatedInput>;
 }
 
 export interface GeneratedRoute<TTypes extends VectorTypes = DefaultVectorTypes> {
@@ -156,3 +241,5 @@ export interface GeneratedRoute<TTypes extends VectorTypes = DefaultVectorTypes>
   method: string;
   options: RouteOptions<TTypes>;
 }
+
+export type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 };