Merge pull request #5 from maxholman/feat/v5

feat: enforce type-safe parameters with path param constraints

Author: maxholman

__tests__/parameter-types.test-d.ts

@@ -0,0 +1,37 @@
+import { expectTypeOf } from 'vitest';
+import type { Parameter } from '../lib/parameter.ts';
+import type { ValidParameter } from '../lib/types.ts';
+
+// Test that only matching path param names are allowed
+type PathParams = ValidParameter<'/users/{userId}'>;
+expectTypeOf<Parameter<'userId', 'path'>>().toExtend<PathParams>();
+
+// @ts-expect-error path parameter with wrong name is not allowed
+expectTypeOf<Parameter<'notInRoute', 'path'>>().toExtend<PathParams>();
+
+// Test that query parameters can be any string
+expectTypeOf<Parameter<'anyName', 'query'>>().toExtend<
+  ValidParameter<'/users/{userId}'>
+>();
+
+// Test that header parameters can be any string
+expectTypeOf<Parameter<'X-Custom-Header', 'header'>>().toExtend<
+  ValidParameter<'/users/{userId}'>
+>();
+
+// Test that cookie parameters can be any string
+expectTypeOf<Parameter<'sessionId', 'cookie'>>().toExtend<
+  ValidParameter<'/users/{userId}'>
+>();
+
+// Test multi-param routes
+type MultiParamRoute = ValidParameter<'/users/{userId}/notes/{noteId}'>;
+expectTypeOf<Parameter<'userId', 'path'>>().toExtend<MultiParamRoute>();
+expectTypeOf<Parameter<'noteId', 'path'>>().toExtend<MultiParamRoute>();
+
+// @ts-expect-error path parameter not in route
+expectTypeOf<Parameter<'otherParam', 'path'>>().toExtend<MultiParamRoute>();
+
+// Test that non-path parameters work for any route
+expectTypeOf<Parameter<'limit', 'query'>>().toExtend<MultiParamRoute>();
+expectTypeOf<Parameter<'offset', 'query'>>().toExtend<MultiParamRoute>();

lib/operation.ts

@@ -1,11 +1,10 @@
 import { Construct } from 'constructs';
 import type { oas31 } from 'openapi3-ts';
-import type { Parameter } from './parameter.ts';
 import { RequestBody, type RequestBodyOptions } from './request-body.ts';
 import type { Response } from './response.ts';
 import type { SecurityRequirement } from './security-requirement.ts';
 import type { Tag } from './tag.ts';
-import type { ExtractRouteParams } from './types.ts';
+import type { ValidParameter } from './types.ts';
 import { stripUndefined } from './utils.ts';
 import type { HttpMethod } from './http-method.ts';
 
@@ -15,7 +14,7 @@ export interface OperationOptions<TPath extends string = '/'> {
   description?: string;
   tags?: Set<Tag>;
   deprecated?: boolean;
-  parameters?: Parameter<keyof ExtractRouteParams<TPath>>[];
+  parameters?: ValidParameter<TPath>[];
   security?: SecurityRequirement;
   responses?: {
     [statusCode: string | number]: Response;

lib/parameter.ts

@@ -3,9 +3,12 @@ import type { oas31 } from 'openapi3-ts';
 import type { Api } from './api.ts';
 import type { Schema } from './schema.ts';
 
-interface ParameterOptionsBase<TName extends string | number | symbol> {
+interface ParameterOptionsBase<
+  TName extends string | number | symbol,
+  TIn extends 'query' | 'header' | 'path' | 'cookie',
+> {
   name: TName;
-  in: 'query' | 'header' | 'path' | 'cookie';
+  in: TIn;
   required: boolean;
   description?: string;
   deprecated?: boolean;
@@ -14,8 +17,10 @@ interface ParameterOptionsBase<TName extends string | number | symbol> {
   style?: 'simple';
 }
 
-interface ParameterOptions<TName extends string | number | symbol>
-  extends ParameterOptionsBase<TName> {
+interface ParameterOptions<
+  TName extends string | number | symbol,
+  TIn extends 'query' | 'header' | 'path' | 'cookie',
+> extends ParameterOptionsBase<TName, TIn> {
   schema: Schema;
 }
 
@@ -26,10 +31,11 @@ interface ParameterOptions<TName extends string | number | symbol>
 
 export class Parameter<
   TName extends string | number | symbol = '',
+  TIn extends 'query' | 'header' | 'path' | 'cookie' = 'query',
 > extends Construct {
-  private options: ParameterOptions<TName>;
+  private options: ParameterOptions<TName, TIn>;
 
-  constructor(scope: Api, id: string, options: ParameterOptions<TName>) {
+  constructor(scope: Api, id: string, options: ParameterOptions<TName, TIn>) {
     super(scope, id);
     this.options = options;
   }

lib/path.ts

@@ -3,16 +3,15 @@ import type { oas31 } from 'openapi3-ts';
 import type { Api } from './api.ts';
 import type { HttpMethod } from './http-method.ts';
 import { Operation, type OperationOptions } from './operation.ts';
-import type { Parameter } from './parameter.ts';
 import type { Server } from './server.ts';
 import type { Tag } from './tag.ts';
-import type { ExtractRouteParams } from './types.ts';
+import type { ValidParameter } from './types.ts';
 
 interface PathOptions<TPath extends string> {
   path: TPath;
   summary?: string;
   servers?: Server[];
-  parameters?: Parameter<keyof ExtractRouteParams<TPath>>[];
+  parameters?: ValidParameter<TPath>[];
   tags?: Set<Tag>;
 }
 

lib/types.ts

@@ -1,3 +1,5 @@
+import type { Parameter } from './parameter.ts';
+
 /* eslint-disable @typescript-eslint/no-unused-vars */
 export type ExtractRouteParams<T> = string extends T
   ? Record<string, string>
@@ -6,3 +8,9 @@ export type ExtractRouteParams<T> = string extends T
     : T extends `${infer _Start}{${infer Param}}`
       ? { [k in Param]: string }
       : Record<string, never>;
+
+export type ValidParameter<TPath extends string> =
+  | Parameter<keyof ExtractRouteParams<TPath>, 'path'>
+  | Parameter<string, 'query'>
+  | Parameter<string, 'header'>
+  | Parameter<string, 'cookie'>;