@bymax-one/nest-core 1.5.2 → 1.6.0

package/dist/openapi/index.mjs

@@ -324,7 +324,7 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.document.ts
+// src/openapi/openapi.shape.ts
 var OPERATION_METHODS = [
   "get",
   "post",
@@ -335,21 +335,26 @@ var OPERATION_METHODS = [
   "options",
   "trace"
 ];
-var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
-var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
-var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
   }
   return value;
 }
-function mergeAbsent(existing, additions) {
-  return { ...additions, ...existing };
-}
 function operationsOf(item) {
   return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
 }
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.document.ts
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
+function mergeAbsent(existing, additions) {
+  return { ...additions, ...existing };
+}
 function mergeResponses(existing, additions) {
   const merged = new Map(Object.entries(existing));
   for (const [status, value] of Object.entries(additions)) {
@@ -375,21 +380,24 @@ function withoutDisabledRoutes(paths, options, routes) {
   });
   return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
 }
-function ownRouteSecurity(path, method, options, routes) {
+function inheritsRequirement(document, openapi) {
+  if (document.security === void 0) {
+    return openapi.security.length > 0;
+  }
+  return Array.isArray(document.security) && document.security.length > 0;
+}
+function ownRouteSecurity(path, method, options, routes, inherits) {
   if (method !== "get") {
     return void 0;
   }
   if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
     return [{ [METRICS_SCHEME_NAME]: [] }];
   }
-  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+  if (inherits && (routes.isHealth(path) || routes.isMetrics(path))) {
     return [];
   }
   return void 0;
 }
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
 function coreResponses(path, options, routes) {
   const responses = {};
   if (options.envelope.enabled) {
@@ -423,7 +431,7 @@ function mergeFragment(operation, fragment) {
   }
   return merged;
 }
-function augmentOperation(operation, path, method, options, routes, contributions) {
+function augmentOperation(operation, path, method, options, routes, contributions, inherits) {
   const declaredByDocument = operation["security"] !== void 0;
   let result = { ...operation };
   for (const fragment of fragmentsFor(result["operationId"], contributions)) {
@@ -432,7 +440,7 @@ function augmentOperation(operation, path, method, options, routes, contribution
   if (!declaredByDocument) {
     const override = options.openapi.operationSecurity[operationKey(method, path)];
     const describedByLibrary = result["security"] !== void 0;
-    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes, inherits));
     if (security !== void 0) {
       result["security"] = security;
     }
@@ -507,12 +515,20 @@ function assertOverridesMatch(paths, openapi) {
     `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
   );
 }
-function augmentPaths(paths, options, routes, contributions) {
+function augmentPaths(paths, options, routes, contributions, inherits) {
   return Object.fromEntries(
     Object.entries(paths).map(([path, item]) => {
       const augmented = operationsOf(item).map(([method, operation]) => [
         method,
-        augmentOperation(asRecord(operation), path, method, options, routes, contributions)
+        augmentOperation(
+          asRecord(operation),
+          path,
+          method,
+          options,
+          routes,
+          contributions,
+          inherits
+        )
       ]);
       return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
     })
@@ -550,7 +566,15 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
   assertOverridesMatch(served, openapi);
-  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes, contributions) };
+  const paths = document.paths === void 0 ? {} : {
+    paths: augmentPaths(
+      served,
+      options,
+      routes,
+      contributions,
+      inheritsRequirement(document, openapi)
+    )
+  };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
   return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }

package/dist/pagination/index.cjs

@@ -19,6 +19,12 @@ function coercePositiveInt(value, fallback) {
 function clampPageToLimit(page, limit) {
   return Math.min(page, Math.floor(Number.MAX_SAFE_INTEGER / limit) + 1);
 }
+function clampPageToOffset(page, limit, maxOffset) {
+  if (maxOffset === void 0 || !Number.isSafeInteger(maxOffset) || maxOffset < 0) {
+    return page;
+  }
+  return Math.min(page, Math.floor(maxOffset / limit) + 1);
+}
 function clampLimit(rawLimit, options) {
   const defaultLimit = coercePositiveInt(options?.defaultLimit, DEFAULT_LIMIT);
   const maxLimit = coercePositiveInt(options?.maxLimit, DEFAULT_MAX_LIMIT);
@@ -29,7 +35,11 @@ function clampLimit(rawLimit, options) {
 function normalizePageQuery(raw, options) {
   const limit = clampLimit(raw.limit, options);
   return {
-    page: clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+    page: clampPageToOffset(
+      clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+      limit,
+      options?.maxOffset
+    ),
     limit
   };
 }

package/dist/pagination/index.d.cts

@@ -51,14 +51,43 @@ interface PageResult<T> {
  * Options are per-call and never retained between calls.
  *
  * @param raw - The untrusted page and limit values from the request.
- * @param options - Per-call `defaultLimit` (default `20`) and `maxLimit`
- *   (default `100`) overrides.
+ * @param options - Per-call `defaultLimit` (default `20`), `maxLimit` (default
+ *   `100`) and `maxOffset` (absent by default) overrides. `maxLimit` bounds how
+ *   many rows a request reads; `maxOffset` bounds how far in it starts, which is
+ *   the half an offset-paginated database pays for.
  * @returns A clamped, safe query ready to hand to a repository.
  */
+/**
+ * Options for {@link normalizePageQuery}: the shared limit bounds, plus the one
+ * that only means anything to offset pagination.
+ *
+ * Declared here rather than beside the shared bounds so it cannot reach the
+ * cursor normalizer, which takes {@link PaginationLimitOptions} and has no
+ * offset to bound. An option that type-checks on a function that ignores it is
+ * worse than a missing one — it reads as configured and does nothing.
+ */
+interface PageQueryOptions extends PaginationLimitOptions {
+    /**
+     * Hard cap applied to the repository offset the query drives,
+     * `(page - 1) * limit`. Absent by default, which bounds nothing beyond
+     * arithmetic safety.
+     *
+     * `maxLimit` bounds how many rows a request reads; this bounds how far in it
+     * starts, which is the half that costs on an offset-paginated database — a
+     * `SELECT … OFFSET 20000000000` is a twenty-byte request that scans a table.
+     * Set it wherever the page index reaches SQL and the dataset has a knowable
+     * ceiling. There is deliberately no default: legitimate deep paging exists,
+     * and a silent cap would change the rows a working query returns.
+     *
+     * `0` is meaningful and means "the first page only". Any other value that is
+     * not a non-negative safe integer is read as absent.
+     */
+    maxOffset?: number;
+}
 declare function normalizePageQuery(raw: {
     page?: unknown;
     limit?: unknown;
-}, options?: PaginationLimitOptions): PageQuery;
+}, options?: PageQueryOptions): PageQuery;
 /**
  * Assemble a {@link PageResult} from a page of items and the total count.
  *

package/dist/pagination/index.d.ts

@@ -51,14 +51,43 @@ interface PageResult<T> {
  * Options are per-call and never retained between calls.
  *
  * @param raw - The untrusted page and limit values from the request.
- * @param options - Per-call `defaultLimit` (default `20`) and `maxLimit`
- *   (default `100`) overrides.
+ * @param options - Per-call `defaultLimit` (default `20`), `maxLimit` (default
+ *   `100`) and `maxOffset` (absent by default) overrides. `maxLimit` bounds how
+ *   many rows a request reads; `maxOffset` bounds how far in it starts, which is
+ *   the half an offset-paginated database pays for.
  * @returns A clamped, safe query ready to hand to a repository.
  */
+/**
+ * Options for {@link normalizePageQuery}: the shared limit bounds, plus the one
+ * that only means anything to offset pagination.
+ *
+ * Declared here rather than beside the shared bounds so it cannot reach the
+ * cursor normalizer, which takes {@link PaginationLimitOptions} and has no
+ * offset to bound. An option that type-checks on a function that ignores it is
+ * worse than a missing one — it reads as configured and does nothing.
+ */
+interface PageQueryOptions extends PaginationLimitOptions {
+    /**
+     * Hard cap applied to the repository offset the query drives,
+     * `(page - 1) * limit`. Absent by default, which bounds nothing beyond
+     * arithmetic safety.
+     *
+     * `maxLimit` bounds how many rows a request reads; this bounds how far in it
+     * starts, which is the half that costs on an offset-paginated database — a
+     * `SELECT … OFFSET 20000000000` is a twenty-byte request that scans a table.
+     * Set it wherever the page index reaches SQL and the dataset has a knowable
+     * ceiling. There is deliberately no default: legitimate deep paging exists,
+     * and a silent cap would change the rows a working query returns.
+     *
+     * `0` is meaningful and means "the first page only". Any other value that is
+     * not a non-negative safe integer is read as absent.
+     */
+    maxOffset?: number;
+}
 declare function normalizePageQuery(raw: {
     page?: unknown;
     limit?: unknown;
-}, options?: PaginationLimitOptions): PageQuery;
+}, options?: PageQueryOptions): PageQuery;
 /**
  * Assemble a {@link PageResult} from a page of items and the total count.
  *

package/dist/pagination/index.mjs

@@ -17,6 +17,12 @@ function coercePositiveInt(value, fallback) {
 function clampPageToLimit(page, limit) {
   return Math.min(page, Math.floor(Number.MAX_SAFE_INTEGER / limit) + 1);
 }
+function clampPageToOffset(page, limit, maxOffset) {
+  if (maxOffset === void 0 || !Number.isSafeInteger(maxOffset) || maxOffset < 0) {
+    return page;
+  }
+  return Math.min(page, Math.floor(maxOffset / limit) + 1);
+}
 function clampLimit(rawLimit, options) {
   const defaultLimit = coercePositiveInt(options?.defaultLimit, DEFAULT_LIMIT);
   const maxLimit = coercePositiveInt(options?.maxLimit, DEFAULT_MAX_LIMIT);
@@ -27,7 +33,11 @@ function clampLimit(rawLimit, options) {
 function normalizePageQuery(raw, options) {
   const limit = clampLimit(raw.limit, options);
   return {
-    page: clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+    page: clampPageToOffset(
+      clampPageToLimit(coercePositiveInt(raw.page, MINIMUM), limit),
+      limit,
+      options?.maxOffset
+    ),
     limit
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",