create-elseware-nodejs-app 1.0.0

package/README.md

@@ -0,0 +1 @@
+# create-elseware-app

package/bin/elseware.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import("../dist/index.js");

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+// src/create.ts
+import path2 from "path";
+import fs2 from "fs";
+
+// src/prompts.ts
+import inquirer from "inquirer";
+async function getProjectOptions(projectNameFromArg) {
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "name",
+      message: "Project name:",
+      default: projectNameFromArg,
+      validate: (input) => Boolean(input) || "Project name is required"
+    },
+    {
+      type: "input",
+      name: "version",
+      message: "Initial version:",
+      default: "1.0.0"
+    },
+    {
+      type: "input",
+      name: "description",
+      message: "Project description:",
+      default: "Elseware NodeJS application"
+    }
+  ]);
+  return answers;
+}
+
+// src/generator.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// utils/logger.ts
+var logger = {
+  success: (msg) => console.log(`\u2705 ${msg}`),
+  info: (msg) => console.log(`\u2139\uFE0F ${msg}`),
+  warn: (msg) => console.log(`\u26A0\uFE0F ${msg}`),
+  error: (msg) => console.error(`\u274C ${msg}`)
+};
+
+// src/generator.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+async function generateProject({ targetDir, options }) {
+  const templateDir = path.resolve(__dirname, "../templates/base");
+  fs.mkdirSync(targetDir, { recursive: true });
+  copyRecursive(templateDir, targetDir);
+  updatePackageJson(targetDir, options);
+}
+function copyRecursive(src, dest) {
+  for (const entry of fs.readdirSync(src)) {
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function updatePackageJson(targetDir, options) {
+  const pkgPath = path.join(targetDir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    throw new Error("package.json not found in template");
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  pkg.name = options.name;
+  pkg.version = options.version;
+  pkg.description = options.description;
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  logger.success("package.json configured");
+}
+
+// src/create.ts
+async function createProject(projectName2) {
+  const options = await getProjectOptions(projectName2);
+  const targetDir = path2.resolve(process.cwd(), options.name);
+  if (fs2.existsSync(targetDir)) {
+    throw new Error(`Directory "${options.name}" already exists`);
+  }
+  logger.info(`Creating Elseware app: ${options.name}`);
+  await generateProject({
+    targetDir,
+    options
+  });
+  logger.success("Project created successfully!");
+  logger.info("Next steps:");
+  logger.info(`  cd ${options.name}`);
+  logger.info("  npm install");
+  logger.info("  npm run dev");
+}
+
+// src/index.ts
+var [, , projectName] = process.argv;
+async function bootstrap() {
+  try {
+    await createProject(projectName);
+    return;
+  } catch (error) {
+    logger.error("Failed to execute command");
+    if (error instanceof Error) {
+      logger.error(error.message);
+    }
+    process.exit(1);
+  }
+}
+bootstrap();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-elseware-nodejs-app",
+  "version": "1.0.0",
+  "description": "CLI to scaffold Elseware NodeJS applications",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "create-elseware-nodejs-app": "bin/elseware.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "sync-template": "tsx src/sync-template.ts",
+    "release": "npm publish --access public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elsewaretechnologies/elseware-npm-cli.git"
+  },
+  "author": "Dhanushka Sandakelum",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/elsewaretechnologies/elseware-npm-cli/issues"
+  },
+  "homepage": "https://github.com/elsewaretechnologies/elseware-npm-cli#readme",
+  "dependencies": {
+    "inquirer": "^12.11.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/base/.env.example

@@ -0,0 +1,7 @@
+NODE_ENV=development
+PORT=4000
+
+DATABASE_URL=mongodb://localhost:27017/elseware-nodejs-template-test-db
+JWT_SECRET=super-secret-key
+
+LOG_LEVEL=info

package/templates/base/README.md

@@ -0,0 +1,41 @@
+# elseware-nodejs-template
+
+Production-ready Node.js REST API template.
+
+## Features
+
+- Express + ESM
+- Clean architecture
+- Jest testing
+- Env validation
+- Scalable structure
+
+## Run
+
+npm install  
+npm run dev
+
+## Test
+
+npm test
+
+## Architecture
+
+### Hybrid Pattern for APIs
+
+To quickly implment generic REST APIs, we can use APIFactory without concerning **service layer**. But for the APIs that require complex **data layer** validations, we can use **service layer**.
+
+- Use ApiFactory for “simple CRUD”
+- Use Services for “business logic”
+- Mixing them is not a smell — it’s a strength.
+
+```javascript
+// Simple
+export const getUsers = ApiFactory.getAll(UserModel);
+
+// Complex
+export const createUser = asyncHandler(async (req, res) => {
+  const user = await userService.createUser(req.body);
+  ApiResponse.created(res, user);
+});
+```

package/templates/base/eslint.config.js

@@ -0,0 +1,73 @@
+import js from "@eslint/js";
+import globals from "globals";
+import jestPlugin from "eslint-plugin-jest";
+import tseslint from "typescript-eslint";
+
+export default [
+  // Base JS rules (real bugs)
+  js.configs.recommended,
+
+  // TypeScript-aware rules
+  ...tseslint.configs.recommended,
+
+  {
+    files: ["**/*.ts"],
+    languageOptions: {
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        ...globals.node,
+        ...globals.es2022,
+      },
+    },
+    rules: {
+      // =============================
+      // Formatting (DISABLED)
+      // =============================
+      indent: "off",
+      "comma-dangle": "off",
+      quotes: "off",
+      semi: "off",
+
+      // =============================
+      // TypeScript-specific safety
+      // =============================
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { argsIgnorePattern: "^_" },
+      ],
+
+      "@typescript-eslint/no-explicit-any": "warn",
+
+      "@typescript-eslint/consistent-type-imports": [
+        "warn",
+        { prefer: "type-imports" },
+      ],
+
+      "@typescript-eslint/no-floating-promises": "error",
+
+      "@typescript-eslint/await-thenable": "error",
+
+      // =============================
+      // Node / backend
+      // =============================
+      "no-console": "off",
+    },
+  },
+
+  // Jest tests
+  {
+    files: ["**/*.test.ts"],
+    plugins: {
+      jest: jestPlugin,
+    },
+    languageOptions: {
+      globals: globals.jest,
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+    },
+  },
+];

package/templates/base/jest.config.js

@@ -0,0 +1,5 @@
+export default {
+  testEnvironment: "node",
+  verbose: true,
+  transform: {},
+};

package/templates/base/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "elseware-nodejs-template",
+  "version": "1.0.0",
+  "description": "Sample elseware App for NodeJs",
+  "type": "module",
+  "main": "server.ts",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "NODE_ENV=test node --experimental-vm-modules ./node_modules/.bin/jest",
+    "coverage": "NODE_ENV=test node --experimental-vm-modules ./node_modules/.bin/jest --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "dotenv": "^17.2.3",
+    "elseware-nodejs": "^1.0.3",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "joi": "^18.0.2",
+    "mongoose": "^9.0.2",
+    "pino": "^10.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "@types/supertest": "^6.0.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jest": "^28.14.0",
+    "globals": "^16.5.0",
+    "jest": "^29.7.0",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.7.4",
+    "supertest": "^7.1.4",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.51.0"
+  }
+}

package/templates/base/src/app.ts

@@ -0,0 +1,24 @@
+import express, { Application } from "express";
+import { AppError, GlobalErrorHandler } from "elseware-nodejs";
+import helmet from "helmet";
+
+import routes from "./routes/index.js";
+import { env } from "./configs/env.js";
+
+const app: Application = express();
+
+app.use(helmet());
+
+app.use(express.json());
+
+app.use("/api/v1", routes);
+
+// Unhandled routes
+app.use((req, _res, next) => {
+  next(new AppError(`Route ${req.originalUrl} not found`, 404));
+});
+
+// Global error middleware
+app.use(GlobalErrorHandler(env.NODE_ENV === "production"));
+
+export default app;

package/templates/base/src/configs/database.ts

@@ -0,0 +1,4 @@
+import { connectMongoDB } from "elseware-nodejs";
+import { env } from "./env.js";
+
+export const connectDatabase = () => connectMongoDB({ uri: env.DATABASE_URL });

package/templates/base/src/configs/env.ts

@@ -0,0 +1,26 @@
+import Joi from "joi";
+import { loadEnv, logger } from "elseware-nodejs";
+
+export interface EnvConfig {
+  NODE_ENV: "development" | "production" | "test";
+  PORT: number;
+  DATABASE_URL: string;
+  JWT_SECRET: string;
+  LOG_LEVEL: string;
+}
+
+const schema = Joi.object<EnvConfig>({
+  NODE_ENV: Joi.string()
+    .valid("development", "production", "test")
+    .default("development"),
+  PORT: Joi.number().default(4000),
+  DATABASE_URL: Joi.string().required(),
+  JWT_SECRET: Joi.string().required(),
+  LOG_LEVEL: Joi.string().default("info"),
+}).unknown(true);
+
+const value = loadEnv(schema);
+
+logger.success("Configurations passed");
+
+export const env: EnvConfig = value;

package/templates/base/src/controllers/health.controller.ts

@@ -0,0 +1,14 @@
+import type { Request, Response } from "express";
+import { ApiResponse } from "elseware-nodejs";
+
+export const healthCheck = (_req: Request, res: Response): Response => {
+  return ApiResponse.ok(
+    res,
+    {
+      status: "ok",
+      service: "elseware-nodejs-template",
+      timestamp: new Date().toISOString(),
+    },
+    "Service is healthy"
+  );
+};

package/templates/base/src/controllers/post.controller.ts

@@ -0,0 +1,27 @@
+import { APIFactory } from "elseware-nodejs";
+
+import { PostModel } from "../models/post.model.js";
+
+/**
+ * SIMPLE CRUD → APIFactory (no service needed)
+ */
+export const getPosts = APIFactory.getAll(PostModel, {
+  message: "Posts fetched successfully",
+});
+
+export const getPostById = APIFactory.getOne(PostModel, {
+  notFoundMessage: "Post not found",
+});
+
+export const createPost = APIFactory.createOne(PostModel, {
+  message: "Post created successfully",
+});
+
+export const updatePost = APIFactory.updateOne(PostModel, {
+  message: "Post updated successfully",
+  notFoundMessage: "Post not found",
+});
+
+export const deletePost = APIFactory.deleteOne(PostModel, {
+  notFoundMessage: "Post not found",
+});

package/templates/base/src/controllers/user.controller.ts

@@ -0,0 +1,33 @@
+import { asyncHandler, ApiResponse } from "elseware-nodejs";
+
+import { userService } from "../services/user.service.js";
+
+/**
+ * COMPLEX CRUD → service needed
+ */
+export const createUser = asyncHandler(async (req, res) => {
+  const user = await userService.create(req.body);
+  ApiResponse.created(res, user, "User created successfully");
+});
+
+export const getUsers = asyncHandler(async (_req, res) => {
+  const users = await userService.findAll();
+  ApiResponse.ok(res, users, "Users fetched successfully", {
+    count: users.length,
+  });
+});
+
+export const getUserById = asyncHandler(async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  ApiResponse.ok(res, user);
+});
+
+export const updateUser = asyncHandler(async (req, res) => {
+  const user = await userService.updateById(req.params.id, req.body);
+  ApiResponse.ok(res, user);
+});
+
+export const deleteUser = asyncHandler(async (req, res) => {
+  await userService.deleteById(req.params.id);
+  ApiResponse.noContent(res);
+});

package/templates/base/src/models/post.model.ts

@@ -0,0 +1,26 @@
+import mongoose, { Schema, InferSchemaType } from "mongoose";
+
+const postSchema = new Schema(
+  {
+    title: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    content: {
+      type: String,
+      required: true,
+    },
+    published: {
+      type: Boolean,
+      default: false,
+    },
+  },
+  {
+    timestamps: true,
+  }
+);
+
+export type Post = InferSchemaType<typeof postSchema>;
+
+export const PostModel = mongoose.model<Post>("Post", postSchema);

package/templates/base/src/models/user.model.ts

@@ -0,0 +1,25 @@
+import mongoose, { Schema, InferSchemaType } from "mongoose";
+
+const userSchema = new Schema(
+  {
+    email: {
+      type: String,
+      required: true,
+      unique: true,
+      lowercase: true,
+      trim: true,
+    },
+    name: {
+      type: String,
+      default: "Anonymous",
+      trim: true,
+    },
+  },
+  {
+    timestamps: true,
+  }
+);
+
+export type User = InferSchemaType<typeof userSchema>;
+
+export const UserModel = mongoose.model<User>("User", userSchema);

package/templates/base/src/routes/health.routes.ts

@@ -0,0 +1,8 @@
+import { Router } from "express";
+import { healthCheck } from "../controllers/health.controller.js";
+
+const router = Router();
+
+router.get("/", healthCheck);
+
+export default router;

package/templates/base/src/routes/index.ts

@@ -0,0 +1,12 @@
+import { Router } from "express";
+import healthRoutes from "./health.routes.js";
+import userRoutes from "./user.routes.js";
+import postRoutes from "./post.routes.js";
+
+const router = Router();
+
+router.use("/health", healthRoutes);
+router.use("/users", userRoutes);
+router.use("/posts", postRoutes);
+
+export default router;

package/templates/base/src/routes/post.routes.ts

@@ -0,0 +1,18 @@
+import { Router } from "express";
+import {
+  getPosts,
+  getPostById,
+  createPost,
+  updatePost,
+  deletePost,
+} from "../controllers/post.controller.js";
+
+const router = Router();
+
+router.post("/", createPost);
+router.get("/", getPosts);
+router.get("/:id", getPostById);
+router.put("/:id", updatePost);
+router.delete("/:id", deletePost);
+
+export default router;

package/templates/base/src/routes/user.routes.ts

@@ -0,0 +1,18 @@
+import { Router } from "express";
+import {
+  createUser,
+  getUsers,
+  getUserById,
+  updateUser,
+  deleteUser,
+} from "../controllers/user.controller.js";
+
+const router = Router();
+
+router.post("/", createUser);
+router.get("/", getUsers);
+router.get("/:id", getUserById);
+router.put("/:id", updateUser);
+router.delete("/:id", deleteUser);
+
+export default router;

package/templates/base/src/server.ts

@@ -0,0 +1,20 @@
+import { logger } from "elseware-nodejs";
+
+import app from "./app.js";
+import { env } from "./configs/env.js";
+import { connectDatabase } from "./configs/database.js";
+
+const startServer = async (): Promise<void> => {
+  logger.configure({
+    timestamp: true,
+    enabled: env.NODE_ENV !== "production",
+  });
+
+  await connectDatabase();
+
+  app.listen(env.PORT, () => {
+    logger.success(`App running on port ${env.PORT} as ${env.NODE_ENV} mode`);
+  });
+};
+
+startServer();

package/templates/base/src/services/user.service.ts

@@ -0,0 +1,39 @@
+import type { UpdateQuery } from "mongoose";
+import { BaseService, CrudService, AppError } from "elseware-nodejs";
+
+import { UserModel, type User } from "../models/user.model.js";
+
+class UserService extends BaseService<User> implements CrudService<User> {
+  constructor() {
+    super(UserModel, "user");
+  }
+
+  /**
+   * Override create with domain-specific logic
+   */
+  override async create(data: Partial<User>): Promise<User> {
+    const existing = await UserModel.findOne({
+      email: data.email,
+    });
+
+    if (existing) {
+      throw new AppError("User already exists", 400, {
+        code: "USER_ALREADY_EXISTS",
+      });
+    }
+
+    return super.create(data);
+  }
+
+  /**
+   * Optional: override update if needed later
+   */
+  override async updateById(
+    id: string,
+    data: UpdateQuery<User>
+  ): Promise<User> {
+    return super.updateById(id, data);
+  }
+}
+
+export const userService = new UserService();

package/templates/base/tests/health.test.js

@@ -0,0 +1,9 @@
+import request from "supertest";
+import app from "../src/app.js";
+
+describe("Health API", () => {
+  it("returns ok", async () => {
+    const res = await request(app).get("/api/health");
+    expect(res.statusCode).toBe(200);
+  });
+});

package/templates/base/tests/user.test.js

@@ -0,0 +1,13 @@
+import request from "supertest";
+import app from "../src/app.js";
+
+describe("User API", () => {
+  it("creates a user", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .send({ email: "test@mail.com" });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.body.email).toBe("test@mail.com");
+  });
+});

package/templates/base/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noImplicitAny": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/base-package.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "description": "Sample elseware App for NodeJs",
+  "type": "module",
+  "main": "server.ts",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "NODE_ENV=test node --experimental-vm-modules ./node_modules/.bin/jest",
+    "coverage": "NODE_ENV=test node --experimental-vm-modules ./node_modules/.bin/jest --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "license": "ISC"
+}