@terreno/api 0.9.1 → 0.9.3

package/dist/api.d.ts

@@ -19,6 +19,26 @@ export declare function addPopulateToQuery(builtQuery: mongoose.Query<any[], any
  * @returns The sum of `a` and `b`
  */
 export type RESTMethod = "list" | "create" | "read" | "update" | "delete";
+/**
+ * Interface for the vendored @wesleytodd/openapi Express middleware.
+ * Provides methods for building OpenAPI documentation from Express routes.
+ */
+export interface OpenApiMiddleware {
+    /** The middleware itself is callable as Express middleware. */
+    (req: express.Request, res: express.Response, next: express.NextFunction): void;
+    /** Register a path-level OpenAPI schema, returning an Express middleware that attaches the schema to the route. */
+    path: (schema?: Record<string, unknown>) => express.RequestHandler;
+    /** Register or retrieve an OpenAPI component definition (schemas, responses, parameters, etc). */
+    component: (type: string, name?: string, description?: Record<string, unknown>) => OpenApiMiddleware | {
+        $ref: string;
+    } | Record<string, unknown> | undefined;
+    /** Shorthand for component("schemas", ...) */
+    schema: (name?: string, description?: Record<string, unknown>) => OpenApiMiddleware | {
+        $ref: string;
+    } | Record<string, unknown> | undefined;
+    /** The generated OpenAPI document */
+    document: Record<string, unknown>;
+}
 /**
  * This is the main configuration.
  * @param T - the base document type. This should not include Mongoose models, just the types of the object.
@@ -55,7 +75,7 @@ export interface ModelRouterOptions<T> {
      * You can transform the given query params by returning different values.
      * If the query is acceptable as-is, return `query` as-is.
      */
-    queryFilter?: (user?: User, query?: Record<string, any>) => Record<string, any> | null | Promise<Record<string, any> | null>;
+    queryFilter?: (user?: User, query?: Record<string, unknown>) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
     /**
      * Transformers allow data to be transformed before actions are executed,
      * and serialized before being returned to the user.
@@ -83,9 +103,7 @@ export interface ModelRouterOptions<T> {
      * list queries. Accepts any Mongoose-style queries, and runs for all user types.
      *    defaultQueryParams: \{hidden: false\} // By default, don't show objects with hidden=true
      * These can be overridden by the user if not disallowed by queryFilter. */
-    defaultQueryParams?: {
-        [key: string]: any;
-    };
+    defaultQueryParams?: Record<string, unknown>;
     /**
      * Manages Mongoose populations before returning from all methods (list, read, create, etc).
      * For each population:
@@ -109,14 +127,14 @@ export interface ModelRouterOptions<T> {
      *  or 500. */
     maxLimit?: number;
     /** Custom route setup function. Receives the router and optionally the full options (including openApi). */
-    endpoints?: (router: any, options?: Partial<ModelRouterOptions<T>>) => void;
+    endpoints?: (router: express.Router, options?: Partial<ModelRouterOptions<T>>) => void;
     /**
      * Hook that runs after `transformer.transform` but before the object is created.
      * Can update the body fields based on the request or the user.
      * Return null to return a generic 403 error. Throw an APIError to return a 400 with specific
      * error information.
      */
-    preCreate?: (value: any, request: express.Request) => T | Promise<T> | null;
+    preCreate?: (value: Partial<T> | (Partial<T> | undefined)[] | null | undefined, request: express.Request) => T | Promise<T> | null;
     /**
      * Hook that runs after `transformer.transform` but before changes are made for update operations.
      * Can update the body fields based on the request or the user.
@@ -185,17 +203,17 @@ export interface ModelRouterOptions<T> {
     /**
      * The OpenAPI generator for this server. This is used to generate the OpenAPI documentation.
      */
-    openApi?: any;
+    openApi?: OpenApiMiddleware;
     /**
      * Overwrite parts of the configuration for the OpenAPI generator.
      * This will be merged with the generated configuration.
      */
     openApiOverwrite?: {
-        get?: any;
-        list?: any;
-        create?: any;
-        update?: any;
-        delete?: any;
+        get?: Record<string, unknown>;
+        list?: Record<string, unknown>;
+        create?: Record<string, unknown>;
+        update?: Record<string, unknown>;
+        delete?: Record<string, unknown>;
     };
     /**
      * Overwrite parts of the model properties for the OpenAPI generator.
@@ -203,7 +221,7 @@ export interface ModelRouterOptions<T> {
      * This is useful if you add custom properties to the model during serialize, for example,
      * that you want to be documented and typed in the SDK.
      */
-    openApiExtraModelProperties?: any;
+    openApiExtraModelProperties?: Record<string, unknown>;
     /**
      * Enable runtime validation of request bodies against the OpenAPI schema.
      * When enabled, requests that don't match the documented schema will return 400 errors.

package/dist/errors.js

@@ -112,7 +112,13 @@ var APIError = /** @class */ (function (_super) {
             _this.meta.fields = fields;
         }
         _this.error = error;
-        logger_1.logger.error("APIError(".concat(status, "): ").concat(title, " ").concat(detail ? detail : "").concat(((_a = data.error) === null || _a === void 0 ? void 0 : _a.stack) ? "\n".concat((_b = data.error) === null || _b === void 0 ? void 0 : _b.stack) : ""));
+        var logMessage = "APIError(".concat(status, "): ").concat(title, " ").concat(detail ? detail : "").concat(((_a = data.error) === null || _a === void 0 ? void 0 : _a.stack) ? "\n".concat((_b = data.error) === null || _b === void 0 ? void 0 : _b.stack) : "");
+        if (data.disableExternalErrorTracking) {
+            logger_1.logger.warn(logMessage);
+        }
+        else {
+            logger_1.logger.error(logMessage);
+        }
         return _this;
     }
     return APIError;

package/dist/expressServer.d.ts

@@ -6,7 +6,7 @@ import { type UserModel as UserMongooseModel } from "./auth";
 import { type GitHubAuthOptions } from "./githubAuth";
 import { type LoggingOptions } from "./logger";
 export declare function setupEnvironment(): void;
-export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<any>>) => void;
+export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<unknown>>) => void;
 export declare function logRequests(req: any, res: any, next: any): void;
 export declare function createRouter(rootPath: string, addRoutes: AddRoutes, middleware?: any[]): any[];
 export declare function createRouterWithAuth(rootPath: string, addRoutes: (router: Router) => void, middleware?: any[]): any[];

package/dist/openApi.d.ts

@@ -1,3 +1,4 @@
+import type express from "express";
 import type { Model } from "mongoose";
 import type { ModelRouterOptions } from "./api";
 export declare const apiErrorContent: {
@@ -52,9 +53,9 @@ export declare const defaultOpenApiErrorResponses: {
         description: string;
     };
 };
-export declare function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
-export declare function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
-export declare function createOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
-export declare function patchOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
-export declare function deleteOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
+export declare function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
+export declare function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
+export declare function createOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
+export declare function patchOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
+export declare function deleteOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): express.RequestHandler;
 export declare function readOpenApiMiddleware<T>(options: Partial<ModelRouterOptions<T>>, properties: any, required: string[], queryParameters: any): any;

package/dist/openApi.test.js

@@ -292,7 +292,8 @@ function addRoutes(router, options) {
     }); });
 });
 function addRoutesPopulate(router, options) {
-    options === null || options === void 0 ? void 0 : options.openApi.component("schemas", "LimitedUser", {
+    var _a;
+    (_a = options === null || options === void 0 ? void 0 : options.openApi) === null || _a === void 0 ? void 0 : _a.component("schemas", "LimitedUser", {
         properties: {
             email: {
                 description: "LimitedUser's email",

package/dist/openApiBuilder.d.ts

@@ -209,7 +209,7 @@ export declare class OpenApiMiddlewareBuilder {
      *
      * @param options - Router options containing the OpenAPI path configuration
      */
-    constructor(options: Partial<ModelRouterOptions<any>>);
+    constructor(options: Partial<ModelRouterOptions<unknown>>);
     /**
      * Sets the tags for the OpenAPI operation.
      *
@@ -484,4 +484,4 @@ export declare class OpenApiMiddlewareBuilder {
  * router.get("/analytics/stats", statsMiddleware, getStatsHandler);
  * ```
  */
-export declare function createOpenApiBuilder(options: Partial<ModelRouterOptions<any>>): OpenApiMiddlewareBuilder;
+export declare function createOpenApiBuilder(options: Partial<ModelRouterOptions<unknown>>): OpenApiMiddlewareBuilder;

package/dist/openApiEtag.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/openApiEtag.test.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var node_crypto_1 = __importDefault(require("node:crypto"));
+var openApiEtag_1 = require("./openApiEtag");
+var buildRequest = function (options) {
+    if (options === void 0) { options = {}; }
+    var ifNoneMatch = options.ifNoneMatch, _a = options.method, method = _a === void 0 ? "GET" : _a, _b = options.path, path = _b === void 0 ? "/openapi.json" : _b;
+    return {
+        get: function (header) {
+            return header === "If-None-Match" ? ifNoneMatch : undefined;
+        },
+        method: method,
+        path: path,
+    };
+};
+var buildResponse = function () {
+    var originalJson = (0, bun_test_1.mock)(function (body) { return ({ body: body }); });
+    var resObject = {
+        json: originalJson,
+    };
+    var set = (0, bun_test_1.mock)(function () { return resObject; });
+    var status = (0, bun_test_1.mock)(function () { return resObject; });
+    var end = (0, bun_test_1.mock)(function () { return resObject; });
+    resObject.set = set;
+    resObject.status = status;
+    resObject.end = end;
+    return {
+        end: end,
+        originalJson: originalJson,
+        res: resObject,
+        set: set,
+        status: status,
+    };
+};
+(0, bun_test_1.describe)("openApiEtagMiddleware", function () {
+    (0, bun_test_1.it)("skips non-openapi requests", function () {
+        var req = buildRequest({ method: "POST", path: "/health" });
+        var _a = buildResponse(), res = _a.res, originalJson = _a.originalJson;
+        var next = (0, bun_test_1.mock)(function () { });
+        (0, openApiEtag_1.openApiEtagMiddleware)(req, res, next);
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+        (0, bun_test_1.expect)(res.json).toBe(originalJson);
+    });
+    (0, bun_test_1.it)("sets ETag and returns json body when no matching If-None-Match header is provided", function () {
+        var req = buildRequest();
+        var _a = buildResponse(), res = _a.res, originalJson = _a.originalJson, set = _a.set, status = _a.status, end = _a.end;
+        var next = (0, bun_test_1.mock)(function () { });
+        var body = { openapi: "3.0.0", paths: { "/todos": { get: {} } } };
+        (0, openApiEtag_1.openApiEtagMiddleware)(req, res, next);
+        var result = res.json(body);
+        var expectedEtag = "\"".concat(node_crypto_1.default.createHash("sha256").update(JSON.stringify(body)).digest("hex").substring(0, 16), "\"");
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+        (0, bun_test_1.expect)(set).toHaveBeenCalledWith("ETag", expectedEtag);
+        (0, bun_test_1.expect)(originalJson).toHaveBeenCalledWith(body);
+        (0, bun_test_1.expect)(status).toHaveBeenCalledTimes(0);
+        (0, bun_test_1.expect)(end).toHaveBeenCalledTimes(0);
+        (0, bun_test_1.expect)(result).toEqual({ body: body });
+    });
+    (0, bun_test_1.it)("returns 304 when If-None-Match matches generated ETag", function () {
+        var body = { openapi: "3.0.0", paths: { "/users": { post: {} } } };
+        var etag = "\"".concat(node_crypto_1.default.createHash("sha256").update(JSON.stringify(body)).digest("hex").substring(0, 16), "\"");
+        var req = buildRequest({ ifNoneMatch: etag });
+        var _a = buildResponse(), res = _a.res, originalJson = _a.originalJson, set = _a.set, status = _a.status, end = _a.end;
+        var next = (0, bun_test_1.mock)(function () { });
+        (0, openApiEtag_1.openApiEtagMiddleware)(req, res, next);
+        var result = res.json(body);
+        (0, bun_test_1.expect)(next).toHaveBeenCalledTimes(1);
+        (0, bun_test_1.expect)(set).toHaveBeenCalledWith("ETag", etag);
+        (0, bun_test_1.expect)(status).toHaveBeenCalledWith(304);
+        (0, bun_test_1.expect)(end).toHaveBeenCalledTimes(1);
+        (0, bun_test_1.expect)(originalJson).toHaveBeenCalledTimes(0);
+        (0, bun_test_1.expect)(result).toBe(res);
+    });
+});

package/dist/populate.d.ts

@@ -7,9 +7,9 @@ export type PopulatePath = {
 export declare const fixMixedFields: (schema: any, properties: Record<string, any>) => void;
 export declare function getOpenApiSpecForModel(model: any, { populatePaths, extraModelProperties, }?: {
     populatePaths?: PopulatePath[];
-    extraModelProperties?: any;
+    extraModelProperties?: Record<string, unknown>;
 }): {
-    properties: any;
+    properties: Record<string, unknown>;
     required: string[];
 };
 export declare function unpopulate<T>(doc: Document<T>, path: string): Document<T>;

package/package.json

@@ -77,6 +77,9 @@
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "name": "@terreno/api",
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
     "mongoose": "^8.0.0"
   },
@@ -100,5 +103,5 @@
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.9.1"
+  "version": "0.9.3"
 }

package/src/api.ts

@@ -72,6 +72,30 @@ const COMPLEX_QUERY_PARAMS = ["$and", "$or"];
  */
 export type RESTMethod = "list" | "create" | "read" | "update" | "delete";
 
+/**
+ * Interface for the vendored @wesleytodd/openapi Express middleware.
+ * Provides methods for building OpenAPI documentation from Express routes.
+ */
+export interface OpenApiMiddleware {
+  /** The middleware itself is callable as Express middleware. */
+  (req: express.Request, res: express.Response, next: express.NextFunction): void;
+  /** Register a path-level OpenAPI schema, returning an Express middleware that attaches the schema to the route. */
+  path: (schema?: Record<string, unknown>) => express.RequestHandler;
+  /** Register or retrieve an OpenAPI component definition (schemas, responses, parameters, etc). */
+  component: (
+    type: string,
+    name?: string,
+    description?: Record<string, unknown>
+  ) => OpenApiMiddleware | {$ref: string} | Record<string, unknown> | undefined;
+  /** Shorthand for component("schemas", ...) */
+  schema: (
+    name?: string,
+    description?: Record<string, unknown>
+  ) => OpenApiMiddleware | {$ref: string} | Record<string, unknown> | undefined;
+  /** The generated OpenAPI document */
+  document: Record<string, unknown>;
+}
+
 /**
  * This is the main configuration.
  * @param T - the base document type. This should not include Mongoose models, just the types of the object.
@@ -110,8 +134,8 @@ export interface ModelRouterOptions<T> {
    */
   queryFilter?: (
     user?: User,
-    query?: Record<string, any>
-  ) => Record<string, any> | null | Promise<Record<string, any> | null>;
+    query?: Record<string, unknown>
+  ) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
   /**
    * Transformers allow data to be transformed before actions are executed,
    * and serialized before being returned to the user.
@@ -137,7 +161,7 @@ export interface ModelRouterOptions<T> {
    * list queries. Accepts any Mongoose-style queries, and runs for all user types.
    *    defaultQueryParams: \{hidden: false\} // By default, don't show objects with hidden=true
    * These can be overridden by the user if not disallowed by queryFilter. */
-  defaultQueryParams?: {[key: string]: any};
+  defaultQueryParams?: Record<string, unknown>;
   /**
    * Manages Mongoose populations before returning from all methods (list, read, create, etc).
    * For each population:
@@ -161,14 +185,17 @@ export interface ModelRouterOptions<T> {
    *  or 500. */
   maxLimit?: number; // defaults to 500
   /** Custom route setup function. Receives the router and optionally the full options (including openApi). */
-  endpoints?: (router: any, options?: Partial<ModelRouterOptions<T>>) => void;
+  endpoints?: (router: express.Router, options?: Partial<ModelRouterOptions<T>>) => void;
   /**
    * Hook that runs after `transformer.transform` but before the object is created.
    * Can update the body fields based on the request or the user.
    * Return null to return a generic 403 error. Throw an APIError to return a 400 with specific
    * error information.
    */
-  preCreate?: (value: any, request: express.Request) => T | Promise<T> | null;
+  preCreate?: (
+    value: Partial<T> | (Partial<T> | undefined)[] | null | undefined,
+    request: express.Request
+  ) => T | Promise<T> | null;
   /**
    * Hook that runs after `transformer.transform` but before changes are made for update operations.
    * Can update the body fields based on the request or the user.
@@ -250,17 +277,17 @@ export interface ModelRouterOptions<T> {
   /**
    * The OpenAPI generator for this server. This is used to generate the OpenAPI documentation.
    */
-  openApi?: any;
+  openApi?: OpenApiMiddleware;
   /**
    * Overwrite parts of the configuration for the OpenAPI generator.
    * This will be merged with the generated configuration.
    */
   openApiOverwrite?: {
-    get?: any;
-    list?: any;
-    create?: any;
-    update?: any;
-    delete?: any;
+    get?: Record<string, unknown>;
+    list?: Record<string, unknown>;
+    create?: Record<string, unknown>;
+    update?: Record<string, unknown>;
+    delete?: Record<string, unknown>;
   };
   /**
    * Overwrite parts of the model properties for the OpenAPI generator.
@@ -268,7 +295,7 @@ export interface ModelRouterOptions<T> {
    * This is useful if you add custom properties to the model during serialize, for example,
    * that you want to be documented and typed in the SDK.
    */
-  openApiExtraModelProperties?: any;
+  openApiExtraModelProperties?: Record<string, unknown>;
   /**
    * Enable runtime validation of request bodies against the OpenAPI schema.
    * When enabled, requests that don't match the documented schema will return 400 errors.

package/src/errors.ts

@@ -120,11 +120,14 @@ export class APIError extends Error {
       this.meta.fields = fields;
     }
     this.error = error;
-    logger.error(
-      `APIError(${status}): ${title} ${detail ? detail : ""}${
-        data.error?.stack ? `\n${data.error?.stack}` : ""
-      }`
-    );
+    const logMessage = `APIError(${status}): ${title} ${detail ? detail : ""}${
+      data.error?.stack ? `\n${data.error?.stack}` : ""
+    }`;
+    if (data.disableExternalErrorTracking) {
+      logger.warn(logMessage);
+    } else {
+      logger.error(logMessage);
+    }
   }
 }
 

package/src/expressServer.ts

@@ -42,7 +42,7 @@ export function setupEnvironment(): void {
   }
 }
 
-export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<any>>) => void;
+export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<unknown>>) => void;
 
 const logRequestsFinished = (req: any, res: any, startTime: bigint) => {
   const options = (res.locals.loggingOptions ?? {}) as LoggingOptions;

package/src/openApi.test.ts

@@ -11,7 +11,7 @@ import {Permissions} from "./permissions";
 import {FoodModel, setupDb, UserModel} from "./tests";
 
 function getMessageSummaryOpenApiMiddleware(options: Partial<ModelRouterOptions<any>>): any {
-  return options.openApi.path({
+  return options.openApi!.path({
     parameters: [
       {
         in: "query",
@@ -177,7 +177,7 @@ describe("openApi", () => {
 });
 
 function addRoutesPopulate(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
-  options?.openApi.component("schemas", "LimitedUser", {
+  options?.openApi?.component("schemas", "LimitedUser", {
     properties: {
       email: {
         description: "LimitedUser's email",

package/src/openApi.ts

@@ -1,9 +1,10 @@
+import type express from "express";
 import flatten from "lodash/flatten";
 import merge from "lodash/merge";
 import type {Model} from "mongoose";
 import m2s from "mongoose-to-swagger";
 
-import type {ModelRouterOptions} from "./api";
+import type {ModelRouterOptions, OpenApiMiddleware} from "./api";
 import {logger} from "./logger";
 import {getOpenApiSpecForModel} from "./populate";
 
@@ -43,7 +44,7 @@ export const defaultOpenApiErrorResponses = {
 };
 
 // We repeat this constantly, so we make it a component so we only have to define it once.
-function createAPIErrorComponent(openApi: any) {
+function createAPIErrorComponent(openApi?: OpenApiMiddleware) {
   // Create a schema component called APIError
   openApi?.component("schemas", "APIError", {
     properties: {
@@ -112,7 +113,10 @@ function createAPIErrorComponent(openApi: any) {
   });
 }
 
-export function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) {
+export function getOpenApiMiddleware<T>(
+  model: Model<T>,
+  options: Partial<ModelRouterOptions<T>>
+): express.RequestHandler {
   createAPIErrorComponent(options.openApi);
   if (!options.openApi?.path) {
     // Just log this once rather than for each middleware.
@@ -154,7 +158,10 @@ export function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelR
   );
 }
 
-export function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) {
+export function listOpenApiMiddleware<T>(
+  model: Model<T>,
+  options: Partial<ModelRouterOptions<T>>
+): express.RequestHandler {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -320,7 +327,7 @@ export function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<Model
 export function createOpenApiMiddleware<T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-) {
+): express.RequestHandler {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -372,7 +379,7 @@ export function createOpenApiMiddleware<T>(
 export function patchOpenApiMiddleware<T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-) {
+): express.RequestHandler {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -424,7 +431,7 @@ export function patchOpenApiMiddleware<T>(
 export function deleteOpenApiMiddleware<T>(
   model: Model<T>,
   options: Partial<ModelRouterOptions<T>>
-) {
+): express.RequestHandler {
   if (!options.openApi?.path) {
     return noop;
   }

package/src/openApiBuilder.ts

@@ -283,7 +283,7 @@ export interface OpenApiBuildResult {
  */
 export class OpenApiMiddlewareBuilder {
   /** Router options containing OpenAPI configuration */
-  private options: Partial<ModelRouterOptions<any>>;
+  private options: Partial<ModelRouterOptions<unknown>>;
 
   /** Accumulated OpenAPI configuration from builder methods */
   private config: OpenApiConfig;
@@ -302,7 +302,7 @@ export class OpenApiMiddlewareBuilder {
    *
    * @param options - Router options containing the OpenAPI path configuration
    */
-  constructor(options: Partial<ModelRouterOptions<any>>) {
+  constructor(options: Partial<ModelRouterOptions<unknown>>) {
     this.options = options;
     this.config = {
       responses: {},
@@ -803,7 +803,7 @@ export class OpenApiMiddlewareBuilder {
  * ```
  */
 export function createOpenApiBuilder(
-  options: Partial<ModelRouterOptions<any>>
+  options: Partial<ModelRouterOptions<unknown>>
 ): OpenApiMiddlewareBuilder {
   return new OpenApiMiddlewareBuilder(options);
 }

package/src/openApiEtag.test.ts

@@ -0,0 +1,101 @@
+import {describe, expect, it, mock} from "bun:test";
+import crypto from "node:crypto";
+import type {NextFunction, Request, Response} from "express";
+
+import {openApiEtagMiddleware} from "./openApiEtag";
+
+interface BuildRequestOptions {
+  ifNoneMatch?: string;
+  method?: string;
+  path?: string;
+}
+
+const buildRequest = (options: BuildRequestOptions = {}): Request => {
+  const {ifNoneMatch, method = "GET", path = "/openapi.json"} = options;
+  return {
+    get: (header: string) => {
+      return header === "If-None-Match" ? ifNoneMatch : undefined;
+    },
+    method,
+    path,
+  } as Request;
+};
+
+const buildResponse = (): {
+  originalJson: ReturnType<typeof mock>;
+  res: Response;
+  set: ReturnType<typeof mock>;
+  status: ReturnType<typeof mock>;
+  end: ReturnType<typeof mock>;
+} => {
+  const originalJson = mock((body: unknown) => ({body}));
+  const resObject = {
+    json: originalJson,
+  } as unknown as Response & Record<string, unknown>;
+  const set = mock(() => resObject);
+  const status = mock(() => resObject);
+  const end = mock(() => resObject);
+
+  resObject.set = set;
+  resObject.status = status;
+  resObject.end = end;
+
+  return {
+    end,
+    originalJson,
+    res: resObject,
+    set,
+    status,
+  };
+};
+
+describe("openApiEtagMiddleware", () => {
+  it("skips non-openapi requests", () => {
+    const req = buildRequest({method: "POST", path: "/health"});
+    const {res, originalJson} = buildResponse();
+    const next = mock(() => {}) as NextFunction;
+
+    openApiEtagMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(res.json).toBe(originalJson);
+  });
+
+  it("sets ETag and returns json body when no matching If-None-Match header is provided", () => {
+    const req = buildRequest();
+    const {res, originalJson, set, status, end} = buildResponse();
+    const next = mock(() => {}) as NextFunction;
+    const body = {openapi: "3.0.0", paths: {"/todos": {get: {}}}};
+
+    openApiEtagMiddleware(req, res, next);
+
+    const result = res.json(body) as unknown as {body: typeof body};
+    const expectedEtag = `"${crypto.createHash("sha256").update(JSON.stringify(body)).digest("hex").substring(0, 16)}"`;
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(set).toHaveBeenCalledWith("ETag", expectedEtag);
+    expect(originalJson).toHaveBeenCalledWith(body);
+    expect(status).toHaveBeenCalledTimes(0);
+    expect(end).toHaveBeenCalledTimes(0);
+    expect(result).toEqual({body});
+  });
+
+  it("returns 304 when If-None-Match matches generated ETag", () => {
+    const body = {openapi: "3.0.0", paths: {"/users": {post: {}}}};
+    const etag = `"${crypto.createHash("sha256").update(JSON.stringify(body)).digest("hex").substring(0, 16)}"`;
+    const req = buildRequest({ifNoneMatch: etag});
+    const {res, originalJson, set, status, end} = buildResponse();
+    const next = mock(() => {}) as NextFunction;
+
+    openApiEtagMiddleware(req, res, next);
+
+    const result = res.json(body);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(set).toHaveBeenCalledWith("ETag", etag);
+    expect(status).toHaveBeenCalledWith(304);
+    expect(end).toHaveBeenCalledTimes(1);
+    expect(originalJson).toHaveBeenCalledTimes(0);
+    expect(result).toBe(res);
+  });
+});

package/src/populate.ts

@@ -138,8 +138,8 @@ export function getOpenApiSpecForModel(
   {
     populatePaths,
     extraModelProperties,
-  }: {populatePaths?: PopulatePath[]; extraModelProperties?: any} = {}
-): {properties: any; required: string[]} {
+  }: {populatePaths?: PopulatePath[]; extraModelProperties?: Record<string, unknown>} = {}
+): {properties: Record<string, unknown>; required: string[]} {
   const modelSwagger = m2s(model, {
     props: ["required", "enum"],
   });