Fix: freezing arrays returned by public methods (#1736)

This is a fix that prevents changing arrays after they have been
assigned upon building an Endpoint, however, it could be potentially
breaking, therefore I'm addressing it to v19.

CHANGELOG.md

@@ -9,6 +9,9 @@
   - `zod`: 3.23.0.
 - The deprecated ~~`withMeta()`~~ is removed:
   - See the changes to [v18.5.0](#v1850) on details.
+- Several public methods and properties exposing arrays from class instances made readonly and frozen:
+  - On `Endpoint`: `.getMethods()`, `.getMimeTypes()`, `.getResponses()`, `.getScopes()`, `.getTags()`,
+  - On `DependsOnMethod`: `.pairs`, `.siblingMethods`.
 
 ## Version 18
 

src/depends-on-method.ts

@@ -3,16 +3,20 @@ import { AbstractEndpoint } from "./endpoint";
 import { Method } from "./method";
 
 export class DependsOnMethod {
-  public readonly pairs: [Method, AbstractEndpoint][];
+  public readonly pairs: ReadonlyArray<[Method, AbstractEndpoint]>;
   public readonly firstEndpoint: AbstractEndpoint | undefined;
-  public readonly siblingMethods: Method[];
+  public readonly siblingMethods: ReadonlyArray<Method>;
 
   constructor(endpoints: Partial<Record<Method, AbstractEndpoint>>) {
-    this.pairs = toPairs(endpoints).filter(
-      (pair): pair is [Method, AbstractEndpoint] =>
-        pair !== undefined && pair[1] !== undefined,
+    this.pairs = Object.freeze(
+      toPairs(endpoints).filter(
+        (pair): pair is [Method, AbstractEndpoint] =>
+          pair !== undefined && pair[1] !== undefined,
+      ),
     );
     this.firstEndpoint = head(this.pairs)?.[1];
-    this.siblingMethods = tail(this.pairs).map(([method]) => method);
+    this.siblingMethods = Object.freeze(
+      tail(this.pairs).map(([method]) => method),
+    );
   }
 }

src/documentation-helpers.ts

@@ -99,7 +99,7 @@ interface ReqResDepictHelperCommonProps
     "serializer" | "getRef" | "makeRef" | "path" | "method"
   > {
   schema: z.ZodTypeAny;
-  mimeTypes: string[];
+  mimeTypes: ReadonlyArray<string>;
   composition: "inline" | "components";
   description?: string;
 }

src/documentation.ts

@@ -229,7 +229,7 @@ export class Documentation extends OpenApiBuilder {
             const scopes = ["oauth2", "openIdConnect"].includes(
               securitySchema.type,
             )
-              ? endpoint.getScopes()
+              ? endpoint.getScopes().slice()
               : [];
             this.addSecurityScheme(name, securitySchema);
             return { name, scopes };

src/endpoint.ts

@@ -47,19 +47,21 @@ export abstract class AbstractEndpoint {
     response: Response;
     logger: AbstractLogger;
     config: CommonConfig;
-    siblingMethods?: Method[];
+    siblingMethods?: ReadonlyArray<Method>;
   }): Promise<void>;
   public abstract getDescription(
     variant: DescriptionVariant,
   ): string | undefined;
-  public abstract getMethods(): Method[];
+  public abstract getMethods(): ReadonlyArray<Method>;
   public abstract getSchema(variant: IOVariant): IOSchema;
   public abstract getSchema(variant: ResponseVariant): z.ZodTypeAny;
-  public abstract getMimeTypes(variant: MimeVariant): string[];
-  public abstract getResponses(variant: ResponseVariant): NormalizedResponse[];
+  public abstract getMimeTypes(variant: MimeVariant): ReadonlyArray<string>;
+  public abstract getResponses(
+    variant: ResponseVariant,
+  ): ReadonlyArray<NormalizedResponse>;
   public abstract getSecurity(): LogicalContainer<Security>;
-  public abstract getScopes(): string[];
-  public abstract getTags(): string[];
+  public abstract getScopes(): ReadonlyArray<string>;
+  public abstract getTags(): ReadonlyArray<string>;
   public abstract getOperationId(method: Method): string | undefined;
 }
 
@@ -71,15 +73,18 @@ export class Endpoint<
   TAG extends string,
 > extends AbstractEndpoint {
   readonly #descriptions: Record<DescriptionVariant, string | undefined>;
-  readonly #methods: Method[];
+  readonly #methods: ReadonlyArray<Method>;
   readonly #middlewares: AnyMiddlewareDef[];
-  readonly #mimeTypes: Record<MimeVariant, string[]>;
-  readonly #responses: Record<ResponseVariant, NormalizedResponse[]>;
+  readonly #mimeTypes: Record<MimeVariant, ReadonlyArray<string>>;
+  readonly #responses: Record<
+    ResponseVariant,
+    ReadonlyArray<NormalizedResponse>
+  >;
   readonly #handler: Handler<z.output<IN>, z.input<OUT>, OPT>;
   readonly #resultHandler: AnyResultHandlerDefinition;
   readonly #schemas: { input: IN; output: OUT };
-  readonly #scopes: SCO[];
-  readonly #tags: TAG[];
+  readonly #scopes: ReadonlyArray<SCO>;
+  readonly #tags: ReadonlyArray<TAG>;
   readonly #getOperationId: (method: Method) => string | undefined;
 
   constructor({
@@ -112,9 +117,9 @@ export class Endpoint<
     this.#resultHandler = resultHandler;
     this.#middlewares = middlewares;
     this.#getOperationId = getOperationId;
-    this.#methods = methods;
-    this.#scopes = scopes;
-    this.#tags = tags;
+    this.#methods = Object.freeze(methods);
+    this.#scopes = Object.freeze(scopes);
+    this.#tags = Object.freeze(tags);
     this.#descriptions = { long, short };
     this.#schemas = { input: inputSchema, output: outputSchema };
     for (const [variant, schema] of Object.entries(this.#schemas)) {
@@ -126,14 +131,18 @@ export class Endpoint<
       );
     }
     this.#responses = {
-      positive: normalizeApiResponse(
-        resultHandler.getPositiveResponse(outputSchema),
-        { mimeTypes: [mimeJson], statusCodes: [defaultStatusCodes.positive] },
+      positive: Object.freeze(
+        normalizeApiResponse(resultHandler.getPositiveResponse(outputSchema), {
+          mimeTypes: [mimeJson],
+          statusCodes: [defaultStatusCodes.positive],
+        }),
+      ),
+      negative: Object.freeze(
+        normalizeApiResponse(resultHandler.getNegativeResponse(), {
+          mimeTypes: [mimeJson],
+          statusCodes: [defaultStatusCodes.negative],
+        }),
       ),
-      negative: normalizeApiResponse(resultHandler.getNegativeResponse(), {
-        mimeTypes: [mimeJson],
-        statusCodes: [defaultStatusCodes.negative],
-      }),
     };
     for (const [variant, responses] of Object.entries(this.#responses)) {
       assert(
@@ -144,21 +153,27 @@ export class Endpoint<
       );
     }
     this.#mimeTypes = {
-      input: hasUpload(inputSchema)
-        ? [mimeMultipart]
-        : hasRaw(inputSchema)
-          ? [mimeRaw]
-          : [mimeJson],
-      positive: this.#responses.positive.flatMap(({ mimeTypes }) => mimeTypes),
-      negative: this.#responses.negative.flatMap(({ mimeTypes }) => mimeTypes),
+      input: Object.freeze(
+        hasUpload(inputSchema)
+          ? [mimeMultipart]
+          : hasRaw(inputSchema)
+            ? [mimeRaw]
+            : [mimeJson],
+      ),
+      positive: Object.freeze(
+        this.#responses.positive.flatMap(({ mimeTypes }) => mimeTypes),
+      ),
+      negative: Object.freeze(
+        this.#responses.negative.flatMap(({ mimeTypes }) => mimeTypes),
+      ),
     };
   }
 
   public override getDescription(variant: DescriptionVariant) {
     return this.#descriptions[variant];
   }
 
-  public override getMethods(): Method[] {
+  public override getMethods() {
     return this.#methods;
   }
 
@@ -190,11 +205,11 @@ export class Endpoint<
     );
   }
 
-  public override getScopes(): SCO[] {
+  public override getScopes() {
     return this.#scopes;
   }
 
-  public override getTags(): TAG[] {
+  public override getTags() {
     return this.#tags;
   }
 

src/integration.ts

@@ -93,7 +93,7 @@ export class Integration {
     { method: Method; path: string },
     Partial<Record<IOKind, string>> & {
       isJson: boolean;
-      tags: string[];
+      tags: ReadonlyArray<string>;
     }
   >();
   protected paths: string[] = [];

src/routing-walker.ts

@@ -12,7 +12,7 @@ export interface RoutingWalkerParams {
     endpoint: AbstractEndpoint,
     path: string,
     method: Method | AuxMethod,
-    siblingMethods?: Method[],
+    siblingMethods?: ReadonlyArray<Method>,
   ) => void;
   onStatic?: (path: string, handler: StaticHandler) => void;
   parentPath?: string;