@mattrika/server-utils 0.0.0-stage → 1.0.1

package/index.esm.js

@@ -0,0 +1,552 @@
+import fs from 'fs';
+import path from 'path';
+import pino from 'pino';
+import { HTTPException } from 'hono/http-exception';
+import { z } from '@hono/zod-openapi';
+import crypto from 'crypto';
+import argon2 from '@node-rs/argon2';
+import { INTERNAL_SERVER_ERROR, NOT_FOUND, UNPROCESSABLE_ENTITY } from 'stoker/http-status-codes';
+import { sign, verify } from 'hono/jwt';
+
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 100;
+
+const MAX_SIZE = 1024 * 1024; // 1MB
+async function safeResponseBody(res) {
+  try {
+    const contentType = res.headers.get('content-type') || '';
+    const disposition = res.headers.get('content-disposition') || '';
+    // ❌ Skip downloads
+    if (disposition.includes('attachment')) {
+      return '[FILE DOWNLOAD SKIPPED]';
+    }
+    // ❌ Skip non-JSON responses
+    if (!contentType.includes('application/json')) {
+      return '[NON-JSON RESPONSE]';
+    }
+    const text = await res.clone().text();
+    if (!text) return undefined;
+    const size = Buffer.byteLength(text, 'utf8');
+    if (size > MAX_SIZE) return `[RESPONSE TOO LARGE: ${Math.round(size / 1024)} KB]`;
+    return JSON.parse(text);
+  } catch {
+    return '[UNREADABLE RESPONSE]';
+  }
+}
+async function safeRequestBody(req) {
+  try {
+    const contentType = req.header('content-type') || '';
+    // ❌ Skip file uploads
+    if (contentType.includes('multipart/form-data')) {
+      return '[FILE UPLOAD SKIPPED]';
+    }
+    if (!contentType.includes('application/json')) {
+      return undefined;
+    }
+    const text = await req.raw.clone().text();
+    if (!text) return undefined;
+    const size = Buffer.byteLength(text, 'utf8');
+    if (size > MAX_SIZE) return `[BODY TOO LARGE: ${Math.round(size / 1024)} KB]`;
+    return JSON.parse(text);
+  } catch {
+    return '[UNREADABLE REQUEST BODY]';
+  }
+}
+function ensureDirExists(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, {
+      recursive: true
+    });
+  }
+}
+
+/**
+ * Checks whether APP_ENV environment variable is set to 'production' or NODE_ENV environment variable is set to 'production', in that order.
+ * @returns boolean
+ */
+function isProductionAppEnvironment() {
+  const appEnv = process?.env?.['APP_ENV'];
+  if (appEnv === 'production') return true;
+  const nodeEnv = process?.env?.['NODE_ENV'];
+  if (nodeEnv === 'production') return true;
+  return false;
+}
+
+const logFilePath = './logs/app.log';
+let transport;
+function pinoLogger() {
+  const isProd = isProductionAppEnvironment();
+  try {
+    // ensure logs folder exists
+    ensureDirExists(logFilePath);
+    transport = isProd ? pino.transport({
+      target: 'pino/file',
+      options: {
+        destination: logFilePath
+      }
+    }) : pino.transport({
+      targets: [{
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          levelFirst: true,
+          translateTime: 'SYS:standard'
+        }
+      }]
+    });
+  } catch (err) {
+    console.error('⚠️ Logger file transport failed, falling back to stdout', err);
+    transport = undefined;
+  }
+  return pino({
+    level: process.env?.['PINO_LOG_LEVEL'] || 'info',
+    timestamp: pino.stdTimeFunctions.isoTime,
+    serializers: {
+      err: pino.stdSerializers.errWithCause
+    },
+    formatters: {
+      bindings: bindings => ({
+        pid: bindings?.['pid'],
+        host: bindings?.['hostname'],
+        node_version: process.version
+      })
+    },
+    redact: {
+      paths: ['req.headers.authorization', 'req.headers.cookie', 'req.body.password', 'req.body.confirmPassword', 'req.body.oldPassword', 'req.body.newPassword', 'req.body.token', 'req.body.refreshToken', 'req.body.accessToken', 'req.body.*.password', 'req.body.*.token', 'req.body.*.refreshToken', 'req.body.*.accessToken', 'res.body.token', 'res.body.refreshToken', 'res.body.accessToken', 'res.body.data.token', 'res.body.data.refreshToken', 'res.body.data.accessToken', 'res.body.*.token', 'res.body.*.refreshToken', 'res.body.*.accessToken'],
+      censor: '[REDACTED]'
+    }
+  }, transport);
+}
+
+const pinoLoggerMiddleware = () => {
+  return async (c, next) => {
+    const start = Date.now();
+    const logger = pinoLogger();
+    const childLogger = logger.child({
+      requestId: c.var['requestId'],
+      req: {
+        method: c.req.method,
+        path: c.req.path,
+        query: c.req.query(),
+        headers: c.req.header(),
+        body: c.req.method !== 'GET' ? await safeRequestBody(c.req) : undefined
+      }
+    });
+    c.set('logger', childLogger);
+    childLogger.info('Incoming request');
+    try {
+      await next();
+      const responseBody = await safeResponseBody(c.res);
+      childLogger.info({
+        res: {
+          status: c.res.status,
+          durationMs: Date.now() - start,
+          body: responseBody
+        }
+      }, 'Request completed');
+    } catch (err) {
+      if (err instanceof HTTPException) {
+        childLogger.warn({
+          res: {
+            status: err.status
+          },
+          error: err.message
+        }, 'HTTP error');
+        throw err;
+      }
+      childLogger.error({
+        err
+      }, 'Unhandled server error');
+      throw err;
+    }
+  };
+};
+
+const zPagination = z.object({
+  page: z.coerce.number().optional(),
+  size: z.coerce.number().optional()
+});
+const zCommonQuery = z.object({
+  search: z.string().optional(),
+  orderBy: z.string().optional(),
+  sortOrder: z.enum(['asc', 'desc']).optional()
+}).extend(zPagination.shape);
+const zId = z.object({
+  id: z.string()
+});
+const zIds = z.object({
+  ids: z.array(z.string()).min(1)
+});
+const zPassword = z.string().min(8).max(128).regex(/[A-Z]/, 'Must contain at least one uppercase letter').regex(/[0-9]/, 'Must contain at least one number').regex(/[^A-Za-z0-9\s]/, 'Must contain at least one special character');
+const zEmpty = z.object({});
+const zFile = z.object({
+  file: z.instanceof(File).openapi({
+    type: 'string',
+    format: 'binary'
+  }).optional(),
+  files: z.array(z.instanceof(File).openapi({
+    type: 'string',
+    format: 'binary'
+  })).optional()
+});
+
+// `argon2.Algorithm` is an ambient `const enum`, so its members cannot be
+// accessed when `isolatedModules` is enabled. Argon2id === 2; typing the
+// literal against the library's own option type keeps it type-safe.
+const ARGON2ID = 2;
+class CryptoService {
+  static async hash(plain) {
+    return argon2.hash(plain, {
+      algorithm: ARGON2ID,
+      memoryCost: 1 << 16,
+      // 64 MB
+      timeCost: 3,
+      parallelism: 1
+    });
+  }
+  static async verify(plain, hash) {
+    return argon2.verify(hash, plain);
+  }
+  static random64chars() {
+    // 32 bytes hex -> 64 hex chars
+    return crypto.randomBytes(32).toString('hex');
+  }
+}
+
+const zResponsePagination = z.object({
+  page: z.number(),
+  size: z.number(),
+  totalItems: z.number(),
+  totalPages: z.number()
+});
+function ApiResponse(dataSchema, description) {
+  return {
+    content: {
+      'application/json': {
+        schema: z.object({
+          data: dataSchema,
+          message: z.string(),
+          success: z.boolean(),
+          error: z.any().optional(),
+          meta: z.any().optional()
+        })
+      }
+    },
+    description
+  };
+}
+function ApiListResponse(dataSchema, description) {
+  return {
+    content: {
+      'application/json': {
+        schema: z.object({
+          data: dataSchema,
+          message: z.string(),
+          success: z.boolean(),
+          error: z.any().optional(),
+          meta: z.any().optional(),
+          pagination: zResponsePagination
+        })
+      }
+    },
+    description
+  };
+}
+// 1. Base Stream Schema
+const zStreamResponse = z.object({
+  body: z.custom(val => val instanceof ReadableStream, {
+    message: 'Body must be a ReadableStream'
+  }),
+  headers: z.object({
+    'Content-Type': z.string().default('application/octet-stream'),
+    'Content-Disposition': z.string().refine(val => val.startsWith('inline; filename="'), {
+      message: 'Must follow format: inline; filename="..."'
+    })
+  }).optional()
+});
+// 2. Generic API Response for ReadableStream
+function StreamResponse(description) {
+  return {
+    content: {
+      'application/octet-stream': {
+        schema: zStreamResponse
+      }
+    },
+    description
+  };
+}
+function ApiPdfResponse(description) {
+  return {
+    content: {
+      'application/pdf': {
+        schema: z.object({
+          format: z.literal('binary'),
+          type: z.literal('string')
+        })
+      }
+    },
+    description
+  };
+}
+
+function throwHttpError(error, defaultMessage = 'Something went wrong') {
+  const code = error instanceof Error ? Number.isNaN(error.cause) ? INTERNAL_SERVER_ERROR : error.cause : INTERNAL_SERVER_ERROR;
+  throw new HTTPException(code, {
+    message: error.message ?? defaultMessage,
+    cause: error
+  });
+}
+function isUniqueViolationPg(error) {
+  const e = error;
+  return e?.code === '23505'; // unique_violation
+}
+
+function toErrorCode(value) {
+  if (value === undefined || value === null || Number.isNaN(value)) {
+    return 500;
+  }
+  return typeof value === 'number' ? Math.max(value, 0) : 500;
+}
+function onErrorFn(debugLog = true) {
+  return async (err, c) => {
+    const statusCode = 'status' in err ? toErrorCode(err.status) : 'cause' in err ? toErrorCode(err.cause) : INTERNAL_SERVER_ERROR;
+    let originalError = err;
+    const seen = new Set([err]);
+    while (originalError.cause instanceof Error && !seen.has(originalError.cause)) {
+      originalError = originalError.cause;
+      seen.add(originalError);
+    }
+    const logger = c.get('logger');
+    logger.error({
+      err,
+      path: c.req.path,
+      method: c.req.method
+    }, 'Request failed');
+    if (debugLog) {
+      console.error(err);
+    }
+    return c.json({
+      data: null,
+      error: !debugLog ? undefined : err,
+      message: originalError.message || err.message,
+      success: false
+    }, statusCode);
+  };
+}
+
+const notFoundFn = c => {
+  return c.json({
+    success: false,
+    error: 'Not Found',
+    data: {},
+    message: `Not Found - ${c.req.path}`
+  }, NOT_FOUND);
+};
+
+function buildPaginationResponse(page, size, total) {
+  const numPage = Number(page);
+  const positivePage = Number.isFinite(numPage) ? Math.max(numPage, 1) : 1;
+  const numSize = Number(size);
+  const positiveSize = Number.isFinite(numSize) && numSize > 0 ? numSize : DEFAULT_PAGE_SIZE;
+  const numTotal = Number(total);
+  const positiveTotal = Number.isFinite(numTotal) ? Math.max(numTotal, 0) : 0;
+  const totalPages = Math.ceil(positiveTotal / positiveSize);
+  return {
+    page: positivePage,
+    size: positiveSize,
+    totalItems: positiveTotal,
+    totalPages
+  };
+}
+
+/**
+ * @module constants
+ * @summary Useful constants
+ * @description
+ * Collection of useful date constants.
+ *
+ * The constants could be imported from `date-fns/constants`:
+ *
+ * ```ts
+ * import { maxTime, minTime } from "./constants/date-fns/constants";
+ *
+ * function isAllowedTime(time) {
+ *   return time <= maxTime && time >= minTime;
+ * }
+ * ```
+ */
+
+
+/**
+ * @constant
+ * @name constructFromSymbol
+ * @summary Symbol enabling Date extensions to inherit properties from the reference date.
+ *
+ * The symbol is used to enable the `constructFrom` function to construct a date
+ * using a reference date and a value. It allows to transfer extra properties
+ * from the reference date to the new date. It's useful for extensions like
+ * [`TZDate`](https://github.com/date-fns/tz) that accept a time zone as
+ * a constructor argument.
+ */
+const constructFromSymbol = Symbol.for("constructDateFrom");
+
+/**
+ * @name constructFrom
+ * @category Generic Helpers
+ * @summary Constructs a date using the reference date and the value
+ *
+ * @description
+ * The function constructs a new date using the constructor from the reference
+ * date and the given value. It helps to build generic functions that accept
+ * date extensions.
+ *
+ * It defaults to `Date` if the passed reference date is a number or a string.
+ *
+ * Starting from v3.7.0, it allows to construct a date using `[Symbol.for("constructDateFrom")]`
+ * enabling to transfer extra properties from the reference date to the new date.
+ * It's useful for extensions like [`TZDate`](https://github.com/date-fns/tz)
+ * that accept a time zone as a constructor argument.
+ *
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The reference date to take constructor from
+ * @param value - The value to create the date
+ *
+ * @returns Date initialized using the given date and value
+ *
+ * @example
+ * import { constructFrom } from "./constructFrom/date-fns";
+ *
+ * // A function that clones a date preserving the original type
+ * function cloneDate<DateType extends Date>(date: DateType): DateType {
+ *   return constructFrom(
+ *     date, // Use constructor from the given date
+ *     date.getTime() // Use the date value to create a new date
+ *   );
+ * }
+ */
+function constructFrom(date, value) {
+  if (typeof date === "function") return date(value);
+
+  if (date && typeof date === "object" && constructFromSymbol in date)
+    return date[constructFromSymbol](value);
+
+  if (date instanceof Date) return new date.constructor(value);
+
+  return new Date(value);
+}
+
+/**
+ * @name toDate
+ * @category Common Helpers
+ * @summary Convert the given argument to an instance of Date.
+ *
+ * @description
+ * Convert the given argument to an instance of Date.
+ *
+ * If the argument is an instance of Date, the function returns its clone.
+ *
+ * If the argument is a number, it is treated as a timestamp.
+ *
+ * If the argument is none of the above, the function returns Invalid Date.
+ *
+ * Starting from v3.7.0, it clones a date using `[Symbol.for("constructDateFrom")]`
+ * enabling to transfer extra properties from the reference date to the new date.
+ * It's useful for extensions like [`TZDate`](https://github.com/date-fns/tz)
+ * that accept a time zone as a constructor argument.
+ *
+ * **Note**: *all* Date arguments passed to any *date-fns* function is processed by `toDate`.
+ *
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ * @typeParam ResultDate - The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.
+ *
+ * @param argument - The value to convert
+ *
+ * @returns The parsed date in the local time zone
+ *
+ * @example
+ * // Clone the date:
+ * const result = toDate(new Date(2014, 1, 11, 11, 30, 30))
+ * //=> Tue Feb 11 2014 11:30:30
+ *
+ * @example
+ * // Convert the timestamp to date:
+ * const result = toDate(1392098430000)
+ * //=> Tue Feb 11 2014 11:30:30
+ */
+function toDate(argument, context) {
+  // [TODO] Get rid of `toDate` or `constructFrom`?
+  return constructFrom(argument, argument);
+}
+
+/**
+ * @name isAfter
+ * @category Common Helpers
+ * @summary Is the first date after the second one?
+ *
+ * @description
+ * Is the first date after the second one?
+ *
+ * @param date - The date that should be after the other one to return true
+ * @param dateToCompare - The date to compare with
+ *
+ * @returns The first date is after the second date
+ *
+ * @example
+ * // Is 10 July 1989 after 11 February 1987?
+ * const result = isAfter(new Date(1989, 6, 10), new Date(1987, 1, 11))
+ * //=> true
+ */
+function isAfter(date, dateToCompare) {
+  return +toDate(date) > +toDate(dateToCompare);
+}
+
+class TokenUtil {
+  alg;
+  secret;
+  constructor(secret, alg = 'HS256') {
+    this.alg = alg;
+    this.secret = secret;
+  }
+  async create(payload, lifeSeconds = 15 * 60) {
+    if (payload.exp === undefined) {
+      // JWT NumericDate claims (`exp`) are seconds since the epoch.
+      payload.exp = Math.floor(Date.now() / 1000) + lifeSeconds;
+    }
+    return await sign(payload, this.secret, this.alg);
+  }
+  async decode(token) {
+    return await verify(token, this.secret, this.alg);
+  }
+  async decodeUnexpired(token) {
+    // Disable Hono's built-in `exp` check so an expired token resolves to
+    // `null` instead of throwing, then validate it here.
+    const {
+      exp,
+      ...rest
+    } = await verify(token, this.secret, {
+      alg: this.alg,
+      exp: false
+    });
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (exp !== undefined && exp <= nowSeconds) return null;
+    return {
+      exp: exp,
+      ...rest
+    };
+  }
+  expiresWithin(exp, seconds) {
+    return isAfter(new Date(), new Date(exp - seconds * 1000));
+  }
+}
+
+function validationHook(result, _c) {
+  if (!result.success) {
+    throwHttpError(new Error('Validation error', {
+      cause: UNPROCESSABLE_ENTITY
+    }));
+  }
+}
+
+export { ApiListResponse, ApiPdfResponse, ApiResponse, CryptoService, DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, StreamResponse, TokenUtil, buildPaginationResponse, ensureDirExists, isProductionAppEnvironment, isUniqueViolationPg, notFoundFn, onErrorFn, pinoLogger, pinoLoggerMiddleware, safeRequestBody, safeResponseBody, throwHttpError, validationHook, zCommonQuery, zEmpty, zFile, zId, zIds, zPagination, zPassword, zResponsePagination, zStreamResponse };

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@mattrika/server-utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattrika/libs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@hono/zod-openapi": "^1.6.3",
+    "@node-rs/argon2": "^2.2.2",
+    "es-toolkit": "^1.52.0",
+    "hono": "^4.13.13",
+    "pino": "^10.4.0",
+    "stoker": "^2.0.1",
+    "zod": "^4.6.7"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
 }

package/src/index.d.ts

@@ -0,0 +1,14 @@
+export * from './lib/constants/common.values';
+export * from './lib/pino-logger/logger.helpers';
+export * from './lib/pino-logger/pino-logger';
+export * from './lib/pino-logger/pino-logger.middleware';
+export * from './lib/predicates/is-prod';
+export * from './lib/schemas/common.schema';
+export * from './lib/services/crypto.service';
+export * from './lib/utils/api-response.util';
+export * from './lib/utils/error.util';
+export * from './lib/utils/on-error';
+export * from './lib/utils/on-not-found';
+export * from './lib/utils/pagination.util';
+export * from './lib/utils/token.util';
+export * from './lib/utils/validation-hook';

package/src/lib/constants/common.values.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_PAGE_SIZE = 20;
+export declare const MAX_PAGE_SIZE = 100;

package/src/lib/pino-logger/logger.helpers.d.ts

@@ -0,0 +1,4 @@
+import type { HonoRequest } from 'hono';
+export declare function safeResponseBody(res: Response): Promise<any>;
+export declare function safeRequestBody(req: HonoRequest): Promise<any>;
+export declare function ensureDirExists(filePath: string): void;

package/src/lib/pino-logger/pino-logger.d.ts

@@ -0,0 +1,2 @@
+import pino from 'pino';
+export declare function pinoLogger(): pino.Logger<never, boolean>;

package/src/lib/pino-logger/pino-logger.middleware.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareHandler } from 'hono';
+export declare const pinoLoggerMiddleware: () => MiddlewareHandler;

package/src/lib/predicates/is-prod.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Checks whether APP_ENV environment variable is set to 'production' or NODE_ENV environment variable is set to 'production', in that order.
+ * @returns boolean
+ */
+export declare function isProductionAppEnvironment(): boolean;

package/src/lib/schemas/common.schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from '@hono/zod-openapi';
+export declare const zPagination: z.ZodObject<{
+    page: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const zCommonQuery: z.ZodObject<{
+    search: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    sortOrder: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    page: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const zId: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const zIds: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const zPassword: z.ZodString;
+export declare const zEmpty: z.ZodObject<{}, z.core.$strip>;
+export declare const zFile: z.ZodObject<{
+    file: z.ZodOptional<z.ZodInstanceOf<File>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodInstanceOf<File>>>;
+}, z.core.$strip>;
+export type CommonQueryParams = z.infer<typeof zCommonQuery>;
+export type PaginationParams = z.infer<typeof zPagination>;

package/src/lib/services/crypto.service.d.ts

@@ -0,0 +1,5 @@
+export declare class CryptoService {
+    static hash(plain: string): Promise<string>;
+    static verify(plain: string, hash: string): Promise<boolean>;
+    static random64chars(): string;
+}