@naturalcycles/backend-lib 9.81.0 → 9.83.0

package/dist/admin/adminMiddleware.d.ts

@@ -31,7 +31,7 @@ export interface RequireAdminCfg {
 /**
  * @deprecated Use `AuthMiddleware`.
  */
-export type AdminMiddleware = (reqPermissions?: string[], cfg?: RequireAdminCfg) => BackendRequestHandler;
+export type AdminMiddleware = (reqPermissions?: readonly string[], cfg?: RequireAdminCfg) => BackendRequestHandler;
 /**
  * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
  */
@@ -44,7 +44,7 @@ export declare function createAdminMiddleware(adminService: BaseAdminService, cf
  *
  * @deprecated Use `AuthService.getLoginRedirectMiddleware`.
  */
-export declare function requireAdminPermissions(adminService: BaseAdminService, reqPermissions?: string[], cfg?: RequireAdminCfg): BackendRequestHandler;
+export declare function requireAdminPermissions(adminService: BaseAdminService, reqPermissions?: readonly string[], cfg?: RequireAdminCfg): BackendRequestHandler;
 /**
  * @deprecated Use `loginHtmlHandler`.
  */

package/dist/admin/base.admin.service.d.ts

@@ -19,8 +19,8 @@ export declare class BaseAdminService {
      * Returns AdminInfo if it has all required permissions.
      * Otherwise returns undefined
      */
-    hasPermissions(req: BackendRequest, reqPermissions?: string[], meta?: AnyObject): Promise<AdminInfo | undefined>;
-    requirePermissions(req: BackendRequest, reqPermissions?: string[], meta?: AnyObject, andComparison?: boolean): Promise<AdminInfo>;
+    hasPermissions(req: BackendRequest, reqPermissions?: readonly string[], meta?: AnyObject): Promise<AdminInfo | undefined>;
+    requirePermissions(req: BackendRequest, reqPermissions?: readonly string[], meta?: AnyObject, andComparison?: boolean): Promise<AdminInfo>;
     /**
      * Doesn't check permissions, nor `authEnabled`. See `checkPermissions`.
      */
@@ -28,7 +28,7 @@ export declare class BaseAdminService {
     /**
      * Doesn't log or throw. See `requireGranted`.
      */
-    checkPermissions(admin: ResolvedAdmin, reqPermissions?: string[], opt?: CheckPermissionsOptions): CheckPermissionsResult;
+    checkPermissions(admin: ResolvedAdmin, reqPermissions?: readonly string[], opt?: CheckPermissionsOptions): CheckPermissionsResult;
     /**
      * Throws 401 if there's no email, 403 if not granted.
      */
@@ -51,7 +51,7 @@ export declare class BaseAdminService {
     /**
      * To be extended.
      */
-    protected onPermissionCheck(req: BackendRequest, email: string, reqPermissions: string[], required: boolean, granted: boolean, meta?: AnyObject): Promise<void>;
+    protected onPermissionCheck(req: BackendRequest, email: string, reqPermissions: readonly string[], required: boolean, granted: boolean, meta?: AnyObject): Promise<void>;
     /**
      * Install it on POST /admin/login url
      *
@@ -113,7 +113,7 @@ export interface CheckPermissionsResult {
     email?: string;
     isAdmin: boolean;
     granted: boolean;
-    reqPermissions: string[];
-    grantedPermissions: string[];
+    reqPermissions: readonly string[];
+    grantedPermissions: readonly string[];
     authDisabled: boolean;
 }

package/dist/auth/auth.service.d.ts

@@ -27,7 +27,7 @@ export declare class AuthService<CTX = AnyObject> {
      * Returns the granted permissions (all of the subject's if alwaysAuthorized),
      * or `{ subject: 'authDisabled', permissions: [] }` if auth is disabled.
      */
-    require(resolved: ResolvedAuth | undefined, reqPermissions?: string[], opt?: AuthCheckOptions<CTX>): PermissionInfo;
+    require(resolved: ResolvedAuth | undefined, reqPermissions?: readonly string[], opt?: AuthCheckOptions<CTX>): PermissionInfo;
     private checkSubject;
     private assertAuthenticated;
     private authRequiredData;
@@ -67,9 +67,9 @@ export interface AuthCheck {
     subject: string;
     granted: boolean;
     alwaysAuthorized: boolean;
-    reqPermissions: string[];
+    reqPermissions: readonly string[];
     /** The granted permissions, or reqPermissions if denied */
-    checkedPermissions: string[];
+    checkedPermissions: readonly string[];
 }
 export interface AuthLoginRedirectMiddlewareCfg<CTX> extends AuthMiddlewareCfg<CTX> {
     loginHtmlPath: string;

package/dist/db/httpDB.d.ts

@@ -19,10 +19,10 @@ export declare class HttpDB extends BaseCommonDB implements CommonDB {
     getTables(): Promise<string[]>;
     getTableSchema<ROW extends ObjectWithId>(table: string): Promise<JsonSchema<ROW>>;
     resetCache(table?: string): Promise<void>;
-    getByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], opt?: CommonDBOptions): Promise<ROW[]>;
+    getByIds<ROW extends ObjectWithId>(table: string, ids: readonly ROW['id'][], opt?: CommonDBOptions): Promise<ROW[]>;
     runQuery<ROW extends ObjectWithId>(query: DBQuery<ROW>, opt?: CommonDBOptions): Promise<RunQueryResult<ROW>>;
     runQueryCount<ROW extends ObjectWithId>(query: DBQuery<ROW>, opt?: CommonDBOptions): Promise<number>;
-    saveBatch<ROW extends ObjectWithId>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
-    deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number>;
+    saveBatch<ROW extends ObjectWithId>(table: string, rows: readonly ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    deleteByIds(table: string, ids: readonly string[], opt?: CommonDBOptions): Promise<number>;
     deleteByQuery<ROW extends ObjectWithId>(query: DBQuery<ROW>, opt?: CommonDBOptions): Promise<number>;
 }

package/dist/db/httpDB.js

@@ -15,6 +15,8 @@ export class HttpDB extends BaseCommonDB {
         transactions: false,
         patchByQuery: false,
         increment: false,
+        // httpDBRequestHandler's options schema strips readAt
+        timeMachine: false,
     };
     constructor(cfg) {
         super();

package/dist/express/getDefaultRouter.d.ts

@@ -2,4 +2,4 @@ import type { BackendRequestHandler, BackendRouter } from '../server/server.mode
 /**
  * Convenience method.
  */
-export declare function getDefaultRouter(defaultHandlers?: BackendRequestHandler[]): BackendRouter;
+export declare function getDefaultRouter(defaultHandlers?: readonly BackendRequestHandler[]): BackendRouter;

package/dist/server/serverStatsMiddleware.js

@@ -2,7 +2,7 @@ import { _mb } from '@naturalcycles/js-lib';
 import { _sum } from '@naturalcycles/js-lib/array/array.util.js';
 import { _sortBy } from '@naturalcycles/js-lib/array/sort.js';
 import { _ms } from '@naturalcycles/js-lib/datetime/time.util.js';
-import { _percentile } from '@naturalcycles/js-lib/math/math.util.js';
+import { _percentiles } from '@naturalcycles/js-lib/math/math.util.js';
 import { NumberStack } from '@naturalcycles/js-lib/math/stack.util.js';
 import { _get, _mapValues } from '@naturalcycles/js-lib/object/object.util.js';
 import { htmlEscape } from '@naturalcycles/js-lib/string/escape.js';
@@ -31,6 +31,7 @@ export const serverStatsHTMLHandler = (req, res) => {
         s.pc = _mapValues(s.stack.percentiles(percentiles), (_k, v) => Math.round(v), { mutate: true });
     });
     const allLatencies = _stringMapValues(serverStatsMap).flatMap(s => s.stack.items);
+    const allPercentiles = _percentiles(allLatencies, percentiles);
     const all2xx = _sum(_stringMapValues(serverStatsMap).flatMap(s => s['2xx']));
     const all4xx = _sum(_stringMapValues(serverStatsMap).flatMap(s => s['4xx']));
     const all5xx = _sum(_stringMapValues(serverStatsMap).flatMap(s => s['5xx']));
@@ -55,7 +56,7 @@ export const serverStatsHTMLHandler = (req, res) => {
         `<td align="right"><pre>${all2xx}</pre></td>`,
         `<td align="right"><pre>${all4xx}</pre></td>`,
         `<td align="right"><pre>${all5xx}</pre></td>`,
-        ...percentiles.map(pc => `<td align="right"><pre>${Math.round(_percentile(allLatencies, pc))}</pre></td>`),
+        ...percentiles.map(pc => `<td align="right"><pre>${Math.round(allPercentiles[pc])}</pre></td>`),
         `</tr>`,
         ..._sortBy(_stringMapEntries(serverStatsMap), ([_, stat]) => _get(stat, sortBy), {
             dir: asc ? 'asc' : 'desc',

package/dist/upload/getUploadedFiles.d.ts

@@ -37,7 +37,7 @@ export interface UploadedFile {
     /** Content-Transfer-Encoding of the file part. */
     encoding: string;
     /** File contents. */
-    data: Buffer;
+    data: Buffer<ArrayBuffer>;
     /** Size of `data` in bytes. */
     size: NumberOfBytes;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.81.0",
+  "version": "9.83.0",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",
@@ -76,7 +76,7 @@
     "directory": "packages/backend-lib"
   },
   "engines": {
-    "node": ">=24.10.0"
+    "node": ">=26.12.1"
   },
   "description": "Standard library for making Express.js based backend services",
   "author": "Natural Cycles Team",

package/src/admin/adminMiddleware.ts

@@ -42,7 +42,7 @@ export interface RequireAdminCfg {
  * @deprecated Use `AuthMiddleware`.
  */
 export type AdminMiddleware = (
-  reqPermissions?: string[],
+  reqPermissions?: readonly string[],
   cfg?: RequireAdminCfg,
 ) => BackendRequestHandler
 
@@ -70,7 +70,7 @@ export function createAdminMiddleware(
  */
 export function requireAdminPermissions(
   adminService: BaseAdminService,
-  reqPermissions: string[] = [],
+  reqPermissions: readonly string[] = [],
   cfg: RequireAdminCfg = {},
 ): BackendRequestHandler {
   const {

package/src/admin/base.admin.service.ts

@@ -70,7 +70,7 @@ export class BaseAdminService {
    */
   async hasPermissions(
     req: BackendRequest,
-    reqPermissions: string[] = [],
+    reqPermissions: readonly string[] = [],
     meta: AnyObject = {},
   ): Promise<AdminInfo | undefined> {
     if (!this.cfg.authEnabled) return adminInfoDisabled()
@@ -93,7 +93,7 @@ export class BaseAdminService {
 
   async requirePermissions(
     req: BackendRequest,
-    reqPermissions: string[] = [],
+    reqPermissions: readonly string[] = [],
     meta: AnyObject = {},
     andComparison = true,
   ): Promise<AdminInfo> {
@@ -128,7 +128,7 @@ export class BaseAdminService {
    */
   checkPermissions(
     admin: ResolvedAdmin,
-    reqPermissions: string[] = [],
+    reqPermissions: readonly string[] = [],
     opt: CheckPermissionsOptions = {},
   ): CheckPermissionsResult {
     const { andComparison = true } = opt
@@ -254,7 +254,7 @@ export class BaseAdminService {
   protected async onPermissionCheck(
     req: BackendRequest,
     email: string,
-    reqPermissions: string[],
+    reqPermissions: readonly string[],
     required: boolean,
     granted: boolean,
     meta: AnyObject = {},
@@ -366,7 +366,7 @@ export interface CheckPermissionsResult {
   email?: string
   isAdmin: boolean
   granted: boolean
-  reqPermissions: string[]
-  grantedPermissions: string[]
+  reqPermissions: readonly string[]
+  grantedPermissions: readonly string[]
   authDisabled: boolean
 }

package/src/admin/secureHeaderMiddleware.ts

@@ -34,7 +34,7 @@ export function createSecureHeaderMiddleware(cfg: SecureHeaderMiddlewareCfg): Ad
 
 function requireSecureHeaderOrAdmin(
   cfg: SecureHeaderMiddlewareCfg,
-  reqPermissions?: string[],
+  reqPermissions?: readonly string[],
 ): BackendRequestHandler {
   const { secureHeaderKey = 'Authorization', secureHeaderValue } = cfg
 

package/src/auth/auth.service.ts

@@ -34,7 +34,7 @@ export class AuthService<CTX = AnyObject> {
 
   private createHandler(
     cfg: AuthMiddlewareCfg<CTX>,
-    reqPermissions: string[] = [],
+    reqPermissions: readonly string[] = [],
     loginHref?: string,
   ): BackendRequestHandler {
     const {
@@ -100,7 +100,7 @@ export class AuthService<CTX = AnyObject> {
    */
   require(
     resolved: ResolvedAuth | undefined,
-    reqPermissions: string[] = [],
+    reqPermissions: readonly string[] = [],
     opt: AuthCheckOptions<CTX> = {},
   ): PermissionInfo {
     if (!this.cfg.authEnabled) return { subject: 'authDisabled', permissions: [] }
@@ -120,9 +120,9 @@ export class AuthService<CTX = AnyObject> {
 
   private checkSubject(
     resolved: AuthenticatedAuth,
-    reqPermissions: string[],
+    reqPermissions: readonly string[],
     opt: AuthCheckOptions<CTX>,
-  ): string[] | undefined {
+  ): readonly string[] | undefined {
     const { subject, permissions, alwaysAuthorized = false } = resolved
     const { andComparison = true, ctx } = opt
 
@@ -160,8 +160,8 @@ export class AuthService<CTX = AnyObject> {
 
   private assertGranted(
     subject: string,
-    grantedPermissions: string[] | undefined,
-    reqPermissions: string[],
+    grantedPermissions: readonly string[] | undefined,
+    reqPermissions: readonly string[],
   ): asserts grantedPermissions is string[] {
     _assert(grantedPermissions, `Permissions required: [${reqPermissions.join(', ')}]`, {
       permissionsRequired: reqPermissions,
@@ -175,8 +175,8 @@ export class AuthService<CTX = AnyObject> {
    * undefined - not granted.
    */
   private getGrantedPermissions(
-    permissions: string[] | undefined,
-    reqPermissions: string[],
+    permissions: readonly string[] | undefined,
+    reqPermissions: readonly string[],
     andComparison: boolean,
   ): string[] | undefined {
     if (!permissions) return
@@ -242,9 +242,9 @@ export interface AuthCheck {
   subject: string
   granted: boolean
   alwaysAuthorized: boolean
-  reqPermissions: string[]
+  reqPermissions: readonly string[]
   /** The granted permissions, or reqPermissions if denied */
-  checkedPermissions: string[]
+  checkedPermissions: readonly string[]
 }
 
 export interface AuthLoginRedirectMiddlewareCfg<CTX> extends AuthMiddlewareCfg<CTX> {

package/src/db/httpDB.ts

@@ -30,6 +30,8 @@ export class HttpDB extends BaseCommonDB implements CommonDB {
     transactions: false,
     patchByQuery: false,
     increment: false,
+    // httpDBRequestHandler's options schema strips readAt
+    timeMachine: false,
   }
 
   constructor(public cfg: HttpDBCfg) {
@@ -61,7 +63,7 @@ export class HttpDB extends BaseCommonDB implements CommonDB {
 
   override async getByIds<ROW extends ObjectWithId>(
     table: string,
-    ids: ROW['id'][],
+    ids: readonly ROW['id'][],
     opt?: CommonDBOptions,
   ): Promise<ROW[]> {
     return await this.fetcher.put(`getByIds`, {
@@ -99,7 +101,7 @@ export class HttpDB extends BaseCommonDB implements CommonDB {
 
   override async saveBatch<ROW extends ObjectWithId>(
     table: string,
-    rows: ROW[],
+    rows: readonly ROW[],
     opt?: CommonDBSaveOptions<ROW>,
   ): Promise<void> {
     await this.fetcher.putVoid(`saveBatch`, {
@@ -111,7 +113,11 @@ export class HttpDB extends BaseCommonDB implements CommonDB {
     })
   }
 
-  override async deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number> {
+  override async deleteByIds(
+    table: string,
+    ids: readonly string[],
+    opt?: CommonDBOptions,
+  ): Promise<number> {
     return await this.fetcher.put(`deleteByIds`, {
       json: {
         table,

package/src/express/createDefaultApp.ts

@@ -147,7 +147,10 @@ export async function createDefaultApp(cfg: DefaultAppCfg): Promise<BackendAppli
   return app
 }
 
-function useHandlers(app: BackendApplication, handlers: BackendRequestHandlerCfg[] = []): void {
+function useHandlers(
+  app: BackendApplication,
+  handlers: readonly BackendRequestHandlerCfg[] = [],
+): void {
   handlers
     .map<BackendRequestHandlerWithPath>(cfg => {
       if (typeof cfg === 'function') {

package/src/express/getDefaultRouter.ts

@@ -4,7 +4,9 @@ import type { BackendRequestHandler, BackendRouter } from '../server/server.mode
 /**
  * Convenience method.
  */
-export function getDefaultRouter(defaultHandlers: BackendRequestHandler[] = []): BackendRouter {
+export function getDefaultRouter(
+  defaultHandlers: readonly BackendRequestHandler[] = [],
+): BackendRouter {
   const router = Router()
 
   // Use default handlers

package/src/server/compressionMiddleware.ts

@@ -413,7 +413,7 @@ function compressSync(method: string, body: Buffer, opts: CodecOptions): Buffer
 function addListeners(
   stream: any,
   on: (type: string, listener: (...args: any[]) => void) => void,
-  listeners: [string, (...args: any[]) => void][],
+  listeners: readonly [string, (...args: any[]) => void][],
 ): void {
   for (const [type, listener] of listeners) {
     on.call(stream, type, listener)

package/src/server/serverStatsMiddleware.ts

@@ -2,7 +2,7 @@ import { _mb } from '@naturalcycles/js-lib'
 import { _sum } from '@naturalcycles/js-lib/array/array.util.js'
 import { _sortBy } from '@naturalcycles/js-lib/array/sort.js'
 import { _ms } from '@naturalcycles/js-lib/datetime/time.util.js'
-import { _percentile } from '@naturalcycles/js-lib/math/math.util.js'
+import { _percentiles } from '@naturalcycles/js-lib/math/math.util.js'
 import { NumberStack } from '@naturalcycles/js-lib/math/stack.util.js'
 import { _get, _mapValues } from '@naturalcycles/js-lib/object/object.util.js'
 import { htmlEscape } from '@naturalcycles/js-lib/string/escape.js'
@@ -51,6 +51,7 @@ export const serverStatsHTMLHandler: BackendRequestHandler = (req, res) => {
     s.pc = _mapValues(s.stack.percentiles(percentiles), (_k, v) => Math.round(v), { mutate: true })
   })
   const allLatencies = _stringMapValues(serverStatsMap).flatMap(s => s.stack.items)
+  const allPercentiles = _percentiles(allLatencies, percentiles)
   const all2xx = _sum(_stringMapValues(serverStatsMap).flatMap(s => s['2xx']))
   const all4xx = _sum(_stringMapValues(serverStatsMap).flatMap(s => s['4xx']))
   const all5xx = _sum(_stringMapValues(serverStatsMap).flatMap(s => s['5xx']))
@@ -79,7 +80,7 @@ export const serverStatsHTMLHandler: BackendRequestHandler = (req, res) => {
     `<td align="right"><pre>${all4xx}</pre></td>`,
     `<td align="right"><pre>${all5xx}</pre></td>`,
     ...percentiles.map(
-      pc => `<td align="right"><pre>${Math.round(_percentile(allLatencies, pc))}</pre></td>`,
+      pc => `<td align="right"><pre>${Math.round(allPercentiles[pc]!)}</pre></td>`,
     ),
     `</tr>`,
     ..._sortBy(_stringMapEntries(serverStatsMap), ([_, stat]) => _get(stat, sortBy) as string, {

package/src/upload/getUploadedFiles.ts

@@ -136,7 +136,7 @@ export interface UploadedFile {
   /** Content-Transfer-Encoding of the file part. */
   encoding: string
   /** File contents. */
-  data: Buffer
+  data: Buffer<ArrayBuffer>
   /** Size of `data` in bytes. */
   size: NumberOfBytes
 }

package/src/validation/validateRequest.util.ts

@@ -31,7 +31,7 @@ const REDACTED = 'REDACTED'
 /**
  * Mutates error
  */
-function redact(redactPaths: string[], obj: any, error: Error): void {
+function redact(redactPaths: readonly string[], obj: any, error: Error): void {
   redactPaths
     .map(path => _get(obj, path) as string)
     .filter(Boolean)