@exyconn/nodejs

A production-ready, reusable Node.js backend foundation package with Express, logging, and standardized API responses.


Features

- 🚀 Instance-based Express App Factory - Create multiple independent server instances
- 📝 Type-safe API Responses - Standardized, consistent response helpers
- 🔧 Config-driven - Type-safe environment loading with Zod validation
- 📊 Centralized Logger - Winston-based logging with multiple transports
- 🛡️ Built-in Security - Helmet, CORS, and rate limiting configured
- 🗄️ MongoDB Support - Easy database connection management
- 📦 Zero Global State - Each instance is completely independent
- ⚡ Modern TypeScript - Full type safety and IntelliSense support
- 🏥 Health Checks - Kubernetes-ready liveness and readiness probes
- 📈 Observability - Request ID, distributed tracing, Prometheus metrics
- ⏰ Background Jobs - Queue-based job processing with retry strategies

Installation

``bash
npm install @exyconn/nodejs


or

yarn add @exyconn/nodejs

or

pnpm add @exyconn/nodejs
`

$3

`bash
npm install express
`

Quick Start

`typescript
import { createApp, successRes, HttpStatus } from "@exyconn/nodejs";

// Create an app instance
const app = createApp({
port: 3000,
environment: "development",
appName: "my-api",
});

// Add routes - Direct Express methods (no need for app.app)
app.get("/api/users", (req, res) => {
const users = [
{ id: 1, name: "John Doe" },
{ id: 2, name: "Jane Doe" },
];
successRes(res, users, "Users fetched successfully");
});

app.post("/api/users", (req, res) => {
const newUser = { id: 1, ...req.body };
successRes(res, newUser, "User created successfully");
});

// Start the server
app.start().then(info => {
console.log(🚀 Server running at ${info.url});
});
`

Multiple Instances

Run multiple independent servers in the same process:

`typescript
import { createApp } from "@exyconn/nodejs";

// API Server
const apiServer = createApp({
port: 3000,
appName: "api-server",
});

// Admin Server
const adminServer = createApp({
port: 4000,
appName: "admin-server",
});

// Start both servers
Promise.all([apiServer.start(), adminServer.start()]).then(([api, admin]) => {
console.log(API Server: ${api.url});
console.log(Admin Server: ${admin.url});
});
`

Configuration

$3

`typescript
import { createApp } from "@exyconn/nodejs";

const app = createApp({
// Server
port: 3000,
environment: "production",
serverUrl: "https://api.example.com",
appName: "my-api",
apiPrefix: "/api/v1",

// Body Parsing
jsonParser: true,
jsonLimit: "10mb",
urlEncodedParser: true,
urlEncodedLimit: "10mb",

// Trust Proxy (for reverse proxies like nginx)
trustProxy: true,

// CORS
cors: {
developmentOrigins: ["http://localhost:3000", "http://localhost:5173"],
productionOrigins: ["https://app.example.com"],
credentials: true,
},

// Rate Limiting
rateLimit: {
windowMs: 15 60 1000, // 15 minutes
max: 100, // 100 requests per window
},

// MongoDB
mongodb: {
uri: "mongodb://localhost:27017/mydb",
maxPoolSize: 10,
},

// Logger
logger: {
level: "info",
console: true,
file: true,
filePath: "./logs",
},

// Security
security: {
helmet: true,
},

// Graceful Shutdown
gracefulShutdown: true,
shutdownTimeout: 30000,
});
`

$3

| Option | Type | Default | Description |
| ------------- | ------------------------------------------------------ | ------------------------- | ------------------------------- |
| port | number | 3000 | Server port |
| environment | 'development' \| 'production' \| 'staging' \| 'test' | 'development' | Environment mode |
| serverUrl | string | 'http://localhost:3000' | Deployed server URL |
| appName | string | 'exyconn-app' | Application name (used in logs) |
| apiPrefix | string | '/api' | API prefix for routes |
| cors | CorsConfig \| boolean | true | CORS configuration |
| rateLimit | RateLimitConfig \| boolean | true | Rate limiting configuration |
| mongodb | MongoDBConfig | undefined | MongoDB configuration |
| logger | LoggerConfig | See defaults | Logger configuration |
| security | SecurityConfig | See defaults | Security middleware config |

API Response Helpers

$3

`typescript
import {
successRes,
successResArr,
createRes,
updateRes,
deleteRes,
paginatedRes,
noContent,
acceptedRes,
} from "@exyconn/nodejs";

// Single item
app.get("/user/:id", (req, res) => {
const user = { id: 1, name: "John" };
successRes(res, user, "User fetched successfully");
});

// Array of items
app.get("/users", (req, res) => {
const users = [{ id: 1 }, { id: 2 }];
successResArr(res, users, "Users listed successfully");
});

// Created resource (201)
app.post("/users", (req, res) => {
const newUser = { id: 1, ...req.body };
createRes(res, newUser, "User created successfully");
});

// Updated resource
app.put("/users/:id", (req, res) => {
const updated = { id: 1, ...req.body };
updateRes(res, updated, "User updated successfully");
});

// Deleted resource
app.delete("/users/:id", (req, res) => {
deleteRes(res, "User deleted successfully");
});

// Paginated response
app.get("/posts", (req, res) => {
const posts = [{ id: 1 }, { id: 2 }];
paginatedRes(res, posts, 1, 10, 100, "Posts listed");
});

// No content (204)
app.patch("/users/:id/read", (req, res) => {
noContent(res);
});
`

$3

`typescript
import {
badRequest,
unauthorized,
forbidden,
notFound,
conflict,
validationError,
tooManyRequests,
errorRes,
serviceUnavailable,
} from "@exyconn/nodejs";

// Bad Request (400)
badRequest(res, "Invalid input data");

// Unauthorized (401)
unauthorized(res, "Please login to continue");

// Forbidden (403)
forbidden(res, "You do not have permission");

// Not Found (404)
notFound(res, "User not found");

// Conflict (409)
conflict(res, "Email already exists");

// Validation Error (422)
validationError(res, [
{ field: "email", message: "Invalid email format" },
{ field: "password", message: "Password too short" },
]);

// Too Many Requests (429)
tooManyRequests(res, "Rate limit exceeded", 60);

// Internal Server Error (500)
errorRes(res, "Something went wrong");

// Service Unavailable (503)
serviceUnavailable(res, "Service temporarily unavailable", 300);
`

$3

All responses follow this consistent format:

`json
{
"success": true,
"statusCode": 200,
"message": "Operation completed successfully",
"data": { ... },
"timestamp": "2024-01-15T10:30:00.000Z",
"path": "/api/users"
}
`

Paginated responses include pagination metadata:

`json
{
"success": true,
"statusCode": 200,
"message": "Data listed successfully",
"data": [...],
"pagination": {
"page": 1,
"limit": 10,
"total": 100,
"totalPages": 10,
"hasNextPage": true,
"hasPrevPage": false,
"nextPage": 2,
"prevPage": null
},
"timestamp": "2024-01-15T10:30:00.000Z"
}
`

Logger

`typescript
import { createLogger, createConsoleLogger } from "@exyconn/nodejs";

// Create a configured logger
const logger = createLogger(
{
level: "debug",
console: true,
file: true,
filePath: "./logs",
},
"development",
"my-app"
);

// Use the logger
logger.info("Server started", { port: 3000 });
logger.error("Database connection failed", { error: err.message });
logger.debug("Processing request", { userId: 123 });

// Create child logger with context
const userLogger = logger.child({ module: "users" });
userLogger.info("User created", { userId: 1 });
`

MongoDB Connection

`typescript
import { createApp } from "@exyconn/nodejs";

const app = createApp({
port: 3000,
mongodb: {
uri: "mongodb://localhost:27017/mydb",
maxPoolSize: 10,
},
});

// Connect to database
await app.connectDatabase();

// Check connection status
if (app.isDatabaseConnected()) {
console.log("Database connected!");
}

// Disconnect when done
await app.disconnectDatabase();
`

HTTP Status Codes

`typescript
import { HttpStatus, getStatusText, isSuccess, isError } from "@exyconn/nodejs";

// Use status codes
res.status(HttpStatus.OK).json({ ... });
res.status(HttpStatus.CREATED).json({ ... });
res.status(HttpStatus.NOT_FOUND).json({ ... });

// Get status text
getStatusText(200); // "OK"
getStatusText(404); // "Not Found"

// Check status categories
isSuccess(200); // true
isError(404); // true
isClientError(400); // true
isServerError(500); // true
`

Utility Functions

$3

`typescript
import {
isValidEmail,
isValidUrl,
isValidObjectId,
isValidUuid,
isValidPhone,
isStrongPassword,
isEmpty,
} from "@exyconn/nodejs";

isValidEmail("user@example.com"); // true
isValidUrl("https://example.com"); // true
isValidObjectId("507f1f77bcf86cd799439011"); // true
isValidUuid("550e8400-e29b-41d4-a716-446655440000"); // true
isValidPhone("+1234567890"); // true
isStrongPassword("MyP@ssw0rd!"); // true
isEmpty(""); // true
isEmpty([]); // true
isEmpty({}); // true
`

$3

`typescript
import {
sleep,
retry,
generateUuid,
deepClone,
pick,
omit,
chunk,
unique,
capitalize,
camelCase,
formatBytes,
formatDuration,
} from "@exyconn/nodejs";

// Async utilities
await sleep(1000);
const result = await retry(fetchData, { maxAttempts: 3 });

// Object utilities
const id = generateUuid();
const clone = deepClone(obj);
const picked = pick(user, ["id", "name"]);
const omitted = omit(user, ["password"]);

// Array utilities
const chunks = chunk([1, 2, 3, 4, 5], 2); // [[1,2], [3,4], [5]]
const uniqueItems = unique([1, 1, 2, 2, 3]); // [1, 2, 3]

// String utilities
capitalize("hello"); // "Hello"
camelCase("hello_world"); // "helloWorld"

// Formatting
formatBytes(1024); // "1 KB"
formatDuration(3661000); // "1h 1m"
`

Enums & Constants

`typescript
import {
HttpMethod,
ContentType,
UserRole,
RecordStatus,
SuccessMessages,
ErrorMessages,
PaginationDefaults,
} from "@exyconn/nodejs";

// HTTP Methods
HttpMethod.GET; // "GET"
HttpMethod.POST; // "POST"

// Content Types
ContentType.JSON; // "application/json"

// Roles & Status
UserRole.ADMIN; // "admin"
RecordStatus.ACTIVE; // "active"

// Messages
SuccessMessages.CREATED; // "Resource created successfully"
ErrorMessages.NOT_FOUND; // "Resource not found"

// Defaults
PaginationDefaults.LIMIT; // 10
PaginationDefaults.MAX_LIMIT; // 100
`

Graceful Shutdown

The package handles graceful shutdown automatically when gracefulShutdown: true:

- Listens for SIGTERM, SIGINT, and SIGUSR2 signals
- Stops accepting new connections
- Waits for existing requests to complete
- Disconnects database connections
- Exits cleanly

`typescript
const app = createApp({
port: 3000,
gracefulShutdown: true,
shutdownTimeout: 30000, // Force exit after 30 seconds
});
`

Environment Configuration

Type-safe environment variable loading with Zod validation:

`typescript
import {
loadEnv,
requireEnv,
getEnv,
parseEnvNumber,
parseEnvBoolean,
parseEnvArray,
baseEnvSchema,
databaseEnvSchema,
createAppEnvSchema,
} from "@exyconn/nodejs";

// Load and validate environment variables
loadEnv(); // Loads from .env file

// Get required environment variables (throws if missing)
const apiKey = requireEnv("API_KEY");

// Get optional environment variables with defaults
const port = getEnv("PORT", "3000");

// Parse typed values
const maxRetries = parseEnvNumber("MAX_RETRIES", 3);
const debugMode = parseEnvBoolean("DEBUG", false);
const allowedHosts = parseEnvArray("ALLOWED_HOSTS"); // comma-separated

// Create validated config with Zod schema
const envSchema = createAppEnvSchema({
API_KEY: z.string().min(1),
FEATURE_FLAG: z.boolean().default(false),
});

const config = envSchema.parse(process.env);
`

Health Checks

Kubernetes-ready health check endpoints:

`typescript
import {
createHealthHandler,
createLivenessHandler,
createReadinessHandler,
setupHealthRoutes,
createMongoHealthChecker,
createRedisHealthChecker,
createMemoryHealthChecker,
} from "@exyconn/nodejs";

const app = createApp({ port: 3000 });

// Quick setup - adds /health, /health/live, /health/ready
setupHealthRoutes(app.express, {
mongo: createMongoHealthChecker(mongoConnection),
memory: createMemoryHealthChecker(512), // 512MB threshold
});

// Or manual setup
app.get(
"/health",
createHealthHandler({
database: createMongoHealthChecker(mongoConnection),
cache: createRedisHealthChecker(redisClient),
})
);

app.get("/health/live", createLivenessHandler());
app.get(
"/health/ready",
createReadinessHandler({
database: createMongoHealthChecker(mongoConnection),
})
);
`

Observability

Request ID, distributed tracing, and Prometheus metrics:

`typescript
import {
// Request ID
generateRequestId,
generateShortId,
requestIdMiddleware,

// Tracing
tracingMiddleware,
parseTraceParent,
generateTraceParent,

// Metrics
incrementCounter,
setGauge,
observeHistogram,
startTimer,
getPrometheusMetrics,
requestMetricsMiddleware,
createMetricsHandler,
} from "@exyconn/nodejs";

const app = createApp({ port: 3000 });

// Add request ID to all requests
app.use(requestIdMiddleware());

// Add distributed tracing (W3C Trace Context)
app.use(tracingMiddleware());

// Add request metrics
app.use(requestMetricsMiddleware());

// Expose Prometheus metrics endpoint
app.get("/metrics", createMetricsHandler());

// Custom metrics
incrementCounter("api_calls", { endpoint: "/users" });
setGauge("active_connections", 42);

const stopTimer = startTimer("request_duration");
// ... do work
stopTimer({ endpoint: "/users" }); // Records duration
`

Background Jobs

Background job processing with queue abstraction:

`typescript
import {
createQueue,
createScheduler,
JobPriority,
RetryStrategy,
} from "@exyconn/nodejs";

// Create a job queue
const emailQueue = createQueue<{ to: string; subject: string }>({
name: "email-queue",
concurrency: 5,
defaultRetries: 3,
retryStrategy: RetryStrategy.EXPONENTIAL,
});

// Add event handlers
emailQueue.onJobComplete((job, result) => {
console.log(Email sent to ${job.data.to});
});

emailQueue.onJobFailed((job, error) => {
console.error(Failed to send email: ${error.message});
});

// Add jobs to queue
await emailQueue.add({
to: "user@example.com",
subject: "Welcome!",
});

// Add with priority
await emailQueue.add(
{ to: "vip@example.com", subject: "VIP Welcome!" },
{ priority: JobPriority.HIGH }
);

// Add delayed job
await emailQueue.add(
{ to: "user@example.com", subject: "Reminder" },
{ delay: 60000 } // 1 minute delay
);

// Create a scheduler for recurring jobs
const scheduler = createScheduler();

scheduler.schedule("cleanup-job", 60000, async () => {
// Runs every 60 seconds
await cleanupOldRecords();
});

scheduler.schedule("daily-report", 86400000, async () => {
// Runs every 24 hours
await generateDailyReport();
});

// Start/stop scheduler
scheduler.start("cleanup-job");
scheduler.stop("cleanup-job");
`

TypeScript Support

The package is written in TypeScript and provides full type definitions:

`typescript
import type {
AppConfig,
AppInstance,
ApiResponse,
PaginatedResponse,
Logger,
TypedRequest,
TypedResponse,
} from "@exyconn/nodejs";

// Typed request body
interface CreateUserBody {
name: string;
email: string;
}

app.post("/users", (req: TypedRequest, res) => {
const { name, email } = req.body; // Fully typed!
// ...
});
``

License

MIT © Exyconn

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Support

- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions