NodeU Code Documentation

@nodeu/code is a Node.js/TypeScript package that reduces backend development boilerplate by 80% through modular, type-safe abstractions. The package is organized into several layers, each providing specific functionality for building robust web applications.

Benefits

• 80% Boilerplate Reduction: Pre-built abstractions for common backend patterns
• Type Safety: Full TypeScript support with comprehensive type definitions
• Modularity: Mix and match components as needed
• Testability: In-memory implementations for easy testing
• Extensibility: Abstract base classes for custom implementation

Index

Layer	Description
Types	Core TypeScript interfaces and error classes that provide type safety across the entire package.
HTTP	HTTP request/response abstractions including handlers, builders, controllers, routes, and parameter extraction.
Middleware	Authentication, authorization, validation, and cross-cutting concerns middleware.
Service	Business logic abstractions including base services, caching, event handling, and job queues.
Adapters	Data access abstractions for repositories, queries, transactions, connections, and migrations.
Utilities	Common helper functions for data manipulation, validation, and transformation.

Installation

npm install @nodeu/code

Quick Start

const express = require('express');
const {
  RequestHandler,
  ResponseBuilder,
  RouteBuilder,
  ControllerRegistry,
  JWTHandler,
  SchemaValidator,
  ErrorHandler,
  BaseService,
  InMemoryRepository,
  CacheManager,
  EventEmitter,
} = require("@nodeu/code");

// 1. Define your data models
class User {
  constructor(id, name, email) {
    this.id = id;
    this.name = name;
    this.email = email;
  }
}

// 2. Create repository
class UserRepository extends InMemoryRepository {
  async findByEmail(email) {
    const users = await this.findAll();
    return users.find(user => user.email === email);
  }
}

// 3. Create service
class UserService extends BaseService {
  constructor(repository, cache, eventEmitter) {
    super(repository);
    this.cache = cache;
    this.eventEmitter = eventEmitter;
  }

  async findById(id) {
    // Check cache first
    let user = await this.cache.get(`user:${id}`);
    if (!user) {
      user = await super.findById(id);
      if (user) {
        await this.cache.set(`user:${id}`, user, 300); // Cache for 5 minutes
      }
    }
    return user;
  }

  async create(data) {
    const user = await super.create(data);
    await this.eventEmitter.emit('user.created', user);
    return user;
  }
}

// 4. Create request handlers
class GetUserHandler extends RequestHandler {
  async execute() {
    const userId = this.params.id;
    const user = await this.service.findById(userId);

    if (!user) {
      return this.notFound('User not found');
    }

    return this.ok(user);
  }
}

class CreateUserHandler extends RequestHandler {
  async execute() {
    const userData = this.body;
    const existingUser = await this.service.repository.findByEmail(userData.email);

    if (existingUser) {
      return this.conflict('User with this email already exists');
    }

    const user = await this.service.create(userData);
    return this.created(user);
  }
}

class GetUsersHandler extends RequestHandler {
  async execute() {
    const { page = 1, limit = 10 } = this.query;
    const users = await this.service.list({ offset: (page - 1) * limit, limit: parseInt(limit) });
    const total = await this.service.count();

    return this.ok({
      users,
      pagination: {
        page: parseInt(page),
        limit: parseInt(limit),
        total,
        pages: Math.ceil(total / limit)
      }
    });
  }
}

// 5. Set up validation schema
const createUserSchema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 2 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email']
};

// 6. Initialize components
const app = express();
app.use(express.json());

// Initialize dependencies
const userRepository = new UserRepository();
const cacheManager = new CacheManager();
const eventEmitter = new EventEmitter();
const userService = new UserService(userRepository, cacheManager, eventEmitter);

// Set up middleware
const jwtHandler = new JWTHandler({ secret: 'your-secret-key' });
const userValidation = SchemaValidator.custom(createUserSchema, (data, schema) => {
  // Simple validation - in real app, use a proper validator
  const errors = [];
  if (!data.name || data.name.length < 2) errors.push('Name is required and must be at least 2 characters');
  if (!data.email || !data.email.includes('@')) errors.push('Valid email is required');

  return {
    valid: errors.length === 0,
    data: data,
    errors
  };
});

// Set up routes
const routeBuilder = new RouteBuilder();
routeBuilder
  .get('/users', (req, res) => {
    const handler = new GetUsersHandler();
    handler.setQuery(req.query);
    handler.setService(userService);
    return handler.execute();
  })
  .get('/users/:id', (req, res) => {
    const handler = new GetUserHandler();
    handler.setParams(req.params);
    handler.setService(userService);
    return handler.execute();
  })
  .post('/users', (req, res) => {
    const handler = new CreateUserHandler();
    handler.setBody(req.body);
    handler.setService(userService);
    return handler.execute();
  });

// Register routes with middleware
const registry = new ControllerRegistry();
registry.register({
  getRoutes: () => routeBuilder.build().map(route => ({
    ...route,
    middleware: route.path.includes('/users') && route.method === 'POST'
      ? [userValidation.handle.bind(userValidation)]
      : []
  }))
});

// Apply middleware and routes
app.use('/api', jwtHandler.handle.bind(jwtHandler));
app.use('/api', (req, res, next) => {
  // Simple route matching - in real app, use a proper router
  const routes = registry.getAllRoutes();
  const route = routes.find(r => {
    const pathRegex = new RegExp('^' + r.path.replace(/:\w+/g, '([^/]+)') + '$');
    return r.method === req.method && pathRegex.test(req.path.replace('/api', ''));
  });

  if (route) {
    // Apply route middleware
    if (route.middleware) {
      let index = 0;
      const nextMiddleware = () => {
        if (index < route.middleware.length) {
          route.middleware[index++](req, res, nextMiddleware);
        } else {
          // Execute handler
          route.handler(req, res).then(result => {
            res.status(result.status).json(result.data || { error: result.error });
          }).catch(next);
        }
      };
      nextMiddleware();
    } else {
      route.handler(req, res).then(result => {
        res.status(result.status).json(result.data || { error: result.error });
      }).catch(next);
    }
  } else {
    res.status(404).json({ error: 'Route not found' });
  }
});

// Error handling
const errorHandler = new ErrorHandler(true);
app.use(errorHandler.handle.bind(errorHandler));

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

// Event listeners
eventEmitter.on('user.created', (user) => {
  console.log(`New user created: ${user.name} (${user.email})`);
});

module.exports = app;

Authors

• Girish Kor
• NodeU
• Npm