@mattrika/server-utils 0.0.0-stage → 1.0.1

package/index.cjs.js

@@ -0,0 +1,582 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var pino = require('pino');
+var httpException = require('hono/http-exception');
+var zodOpenapi = require('@hono/zod-openapi');
+var crypto = require('crypto');
+var argon2 = require('@node-rs/argon2');
+var httpStatusCodes = require('stoker/http-status-codes');
+var jwt = require('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.HTTPException) {
+        childLogger.warn({
+          res: {
+            status: err.status
+          },
+          error: err.message
+        }, 'HTTP error');
+        throw err;
+      }
+      childLogger.error({
+        err
+      }, 'Unhandled server error');
+      throw err;
+    }
+  };
+};
+
+const zPagination = zodOpenapi.z.object({
+  page: zodOpenapi.z.coerce.number().optional(),
+  size: zodOpenapi.z.coerce.number().optional()
+});
+const zCommonQuery = zodOpenapi.z.object({
+  search: zodOpenapi.z.string().optional(),
+  orderBy: zodOpenapi.z.string().optional(),
+  sortOrder: zodOpenapi.z.enum(['asc', 'desc']).optional()
+}).extend(zPagination.shape);
+const zId = zodOpenapi.z.object({
+  id: zodOpenapi.z.string()
+});
+const zIds = zodOpenapi.z.object({
+  ids: zodOpenapi.z.array(zodOpenapi.z.string()).min(1)
+});
+const zPassword = zodOpenapi.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 = zodOpenapi.z.object({});
+const zFile = zodOpenapi.z.object({
+  file: zodOpenapi.z.instanceof(File).openapi({
+    type: 'string',
+    format: 'binary'
+  }).optional(),
+  files: zodOpenapi.z.array(zodOpenapi.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 = zodOpenapi.z.object({
+  page: zodOpenapi.z.number(),
+  size: zodOpenapi.z.number(),
+  totalItems: zodOpenapi.z.number(),
+  totalPages: zodOpenapi.z.number()
+});
+function ApiResponse(dataSchema, description) {
+  return {
+    content: {
+      'application/json': {
+        schema: zodOpenapi.z.object({
+          data: dataSchema,
+          message: zodOpenapi.z.string(),
+          success: zodOpenapi.z.boolean(),
+          error: zodOpenapi.z.any().optional(),
+          meta: zodOpenapi.z.any().optional()
+        })
+      }
+    },
+    description
+  };
+}
+function ApiListResponse(dataSchema, description) {
+  return {
+    content: {
+      'application/json': {
+        schema: zodOpenapi.z.object({
+          data: dataSchema,
+          message: zodOpenapi.z.string(),
+          success: zodOpenapi.z.boolean(),
+          error: zodOpenapi.z.any().optional(),
+          meta: zodOpenapi.z.any().optional(),
+          pagination: zResponsePagination
+        })
+      }
+    },
+    description
+  };
+}
+// 1. Base Stream Schema
+const zStreamResponse = zodOpenapi.z.object({
+  body: zodOpenapi.z.custom(val => val instanceof ReadableStream, {
+    message: 'Body must be a ReadableStream'
+  }),
+  headers: zodOpenapi.z.object({
+    'Content-Type': zodOpenapi.z.string().default('application/octet-stream'),
+    'Content-Disposition': zodOpenapi.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: zodOpenapi.z.object({
+          format: zodOpenapi.z.literal('binary'),
+          type: zodOpenapi.z.literal('string')
+        })
+      }
+    },
+    description
+  };
+}
+
+function throwHttpError(error, defaultMessage = 'Something went wrong') {
+  const code = error instanceof Error ? Number.isNaN(error.cause) ? httpStatusCodes.INTERNAL_SERVER_ERROR : error.cause : httpStatusCodes.INTERNAL_SERVER_ERROR;
+  throw new httpException.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) : httpStatusCodes.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}`
+  }, httpStatusCodes.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 jwt.sign(payload, this.secret, this.alg);
+  }
+  async decode(token) {
+    return await jwt.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 jwt.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: httpStatusCodes.UNPROCESSABLE_ENTITY
+    }));
+  }
+}
+
+exports.ApiListResponse = ApiListResponse;
+exports.ApiPdfResponse = ApiPdfResponse;
+exports.ApiResponse = ApiResponse;
+exports.CryptoService = CryptoService;
+exports.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
+exports.MAX_PAGE_SIZE = MAX_PAGE_SIZE;
+exports.StreamResponse = StreamResponse;
+exports.TokenUtil = TokenUtil;
+exports.buildPaginationResponse = buildPaginationResponse;
+exports.ensureDirExists = ensureDirExists;
+exports.isProductionAppEnvironment = isProductionAppEnvironment;
+exports.isUniqueViolationPg = isUniqueViolationPg;
+exports.notFoundFn = notFoundFn;
+exports.onErrorFn = onErrorFn;
+exports.pinoLogger = pinoLogger;
+exports.pinoLoggerMiddleware = pinoLoggerMiddleware;
+exports.safeRequestBody = safeRequestBody;
+exports.safeResponseBody = safeResponseBody;
+exports.throwHttpError = throwHttpError;
+exports.validationHook = validationHook;
+exports.zCommonQuery = zCommonQuery;
+exports.zEmpty = zEmpty;
+exports.zFile = zFile;
+exports.zId = zId;
+exports.zIds = zIds;
+exports.zPagination = zPagination;
+exports.zPassword = zPassword;
+exports.zResponsePagination = zResponsePagination;
+exports.zStreamResponse = zStreamResponse;

package/index.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './index.cjs.js';
+export { _default as default } from './index.cjs.default.js';

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";