@mattrika/server-utils 0.0.0-stage → 1.0.0

package/index.esm.js

@@ -0,0 +1,396 @@
+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 { clamp } from 'es-toolkit';
+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,
+    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
+  });
+}
+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;
+    const logger = c.get('logger');
+    logger.error({
+      err,
+      path: c.req.path,
+      method: c.req.method
+    }, 'Request failed');
+    if (debugLog) {
+      console.error(JSON.stringify(err, undefined, 2));
+    }
+    return c.json({
+      data: null,
+      error: !debugLog ? undefined : err,
+      message: err.cause ?? 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 = clamp(Number(page), 1) || 1;
+  const positivePage = numPage < 1 ? 1 : numPage;
+  const numSize = clamp(Number(size), DEFAULT_PAGE_SIZE);
+  const numTotal = clamp(Number(total), 0);
+  const totalPages = Math.ceil(numTotal / numSize);
+  return {
+    page: positivePage,
+    size: numSize,
+    totalItems: numTotal,
+    totalPages
+  };
+}
+
+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
+    };
+  }
+}
+
+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.0",
+  "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;
+}

package/src/lib/utils/api-response.util.d.ts

@@ -0,0 +1,76 @@
+import { z } from '@hono/zod-openapi';
+import { ZodAny, ZodArray, ZodBoolean, ZodNumber, ZodObject, ZodOptional, ZodString } from 'zod';
+export type ZodSchema = ZodObject<any> | ZodArray<ZodObject<any>>;
+export declare const zResponsePagination: z.ZodObject<{
+    page: z.ZodNumber;
+    size: z.ZodNumber;
+    totalItems: z.ZodNumber;
+    totalPages: z.ZodNumber;
+}, z.core.$strip>;
+export type ResponsePagination = z.infer<typeof zResponsePagination>;
+export declare function ApiResponse<T extends ZodSchema>(dataSchema: T, description: string): {
+    content: {
+        'application/json': {
+            schema: ZodObject<{
+                data: T;
+                message: ZodString;
+                success: ZodBoolean;
+                error: ZodOptional<ZodAny>;
+                meta: ZodOptional<ZodAny>;
+            }>;
+        };
+    };
+    description: string;
+};
+export declare function ApiListResponse<T extends ZodSchema>(dataSchema: T, description: string): {
+    content: {
+        'application/json': {
+            schema: ZodObject<{
+                data: T;
+                message: ZodString;
+                success: ZodBoolean;
+                error: ZodOptional<ZodAny>;
+                meta: ZodOptional<ZodAny>;
+                pagination: ZodObject<{
+                    page: ZodNumber;
+                    size: ZodNumber;
+                    totalItems: ZodNumber;
+                    totalPages: ZodNumber;
+                }>;
+            }>;
+        };
+    };
+    description: string;
+};
+export declare const zStreamResponse: z.ZodObject<{
+    body: z.ZodCustom<ReadableStream<any>, ReadableStream<any>>;
+    headers: z.ZodOptional<z.ZodObject<{
+        'Content-Type': z.ZodDefault<z.ZodString>;
+        'Content-Disposition': z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function StreamResponse(description: string): {
+    content: {
+        'application/octet-stream': {
+            schema: z.ZodObject<{
+                body: z.ZodCustom<ReadableStream<any>, ReadableStream<any>>;
+                headers: z.ZodOptional<z.ZodObject<{
+                    'Content-Type': z.ZodDefault<z.ZodString>;
+                    'Content-Disposition': z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+    };
+    description: string;
+};
+export declare function ApiPdfResponse(description: string): {
+    content: {
+        'application/pdf': {
+            schema: z.ZodObject<{
+                format: z.ZodLiteral<"binary">;
+                type: z.ZodLiteral<"string">;
+            }, z.core.$strip>;
+        };
+    };
+    description: string;
+};

package/src/lib/utils/error.util.d.ts

@@ -0,0 +1,2 @@
+export declare function throwHttpError(error: unknown, defaultMessage?: string): never;
+export declare function isUniqueViolationPg(error: unknown): boolean;

package/src/lib/utils/on-error.d.ts

@@ -0,0 +1,2 @@
+import { ErrorHandler } from 'hono';
+export declare function onErrorFn(debugLog?: boolean): ErrorHandler;

package/src/lib/utils/on-not-found.d.ts

@@ -0,0 +1,2 @@
+import { NotFoundHandler } from 'hono';
+export declare const notFoundFn: NotFoundHandler;

package/src/lib/utils/pagination.util.d.ts

@@ -0,0 +1,2 @@
+import { ResponsePagination } from './api-response.util';
+export declare function buildPaginationResponse(page: number | undefined, size: number | undefined, total: number): ResponsePagination;

package/src/lib/utils/token.util.d.ts

@@ -0,0 +1,10 @@
+import type { SignatureAlgorithm } from 'hono/utils/jwt/jwa';
+import type { JWTPayload } from 'hono/utils/jwt/types';
+export declare class TokenUtil {
+    private alg;
+    private secret;
+    constructor(secret: string, alg?: SignatureAlgorithm);
+    create<T extends JWTPayload>(payload: T, lifeSeconds?: number): Promise<string>;
+    decode<T extends JWTPayload>(token: string): Promise<T | null>;
+    decodeUnexpired<T extends JWTPayload>(token: string): Promise<T | null>;
+}

package/src/lib/utils/validation-hook.d.ts

@@ -0,0 +1,2 @@
+import { Context } from 'hono';
+export declare function validationHook(result: any, _c: Context): void;