@pulzar/core

Pulzar - Next-generation Node.js framework

Ultra-Fast • Edge-First • Zero-Reflection • Production-Ready

Next-generation TypeScript framework for ultra-fast web applications

Built on Fastify with zero-reflection dependency injection, GraphQL, WebSockets, events, and edge runtime support

Documentation • Quick Start • Examples • API Reference • Discord

✨ Why Pulzar Core?

Pulzar Core is a production-ready TypeScript framework that combines the speed of Fastify with modern development patterns. Built for developers who need blazing-fast performance without sacrificing developer experience.

🎯 Key Features

• 🚄 Ultra-Fast Performance - Built on Fastify, one of the fastest Node.js frameworks
• 💉 Zero-Reflection DI - Lightning-fast dependency injection without runtime reflection
• 🔐 Advanced Authentication - JWT, OAuth2, session-based auth with role-based access control
• 🌐 GraphQL Ready - Built-in Mercurius integration with automatic schema generation
• 📡 Real-time Events - Kafka, NATS, Redis event streaming with schema validation
• 🌊 WebSocket Support - Full WebSocket gateway with uWS integration
• ⚡ Edge Runtime - Deploy to Cloudflare Workers, Vercel Edge, and Deno Deploy
• 🔍 OpenAPI Generation - Automatic API documentation from TypeScript types
• 🔄 Hot Reload - Development mode with instant code updates
• 📊 Observability - OpenTelemetry tracing, metrics, and structured logging
• 🧪 Testing Utils - Comprehensive testing utilities and mocking helpers

🚀 Quick Start

Installation

npm install @pulzar/core
# or
yarn add @pulzar/core
# or
pnpm add @pulzar/core

Basic Usage

import { Pulzar, Controller, Get, Injectable } from "@pulzar/core";

@Injectable()
class UserService {
  getUsers() {
    return [
      { id: 1, name: "Alice" },
      { id: 2, name: "Bob" },
    ];
  }
}

@Controller("/api/users")
class UserController {
  constructor(private userService: UserService) {}

  @Get("/")
  async getUsers() {
    return this.userService.getUsers();
  }
}

const app = new Pulzar({
  controllers: [UserController],
  providers: [UserService],
});

app.listen(3000, () => {
  console.log("🚀 Server running at http://localhost:3000");
});

With Authentication

import { JWTGuard, RequireAuth, RequireRoles } from "@pulzar/core";

@Controller("/api/admin")
class AdminController {
  @Get("/users")
  @RequireAuth()
  @RequireRoles("admin")
  async getUsers() {
    return await this.userService.getUsers();
  }
}

const app = new Pulzar({
  auth: {
    jwt: {
      secret: process.env.JWT_SECRET,
      algorithm: "HS256",
    },
  },
});

🏗️ Architecture & Features

💉 Dependency Injection

Pulzar uses zero-reflection DI for maximum performance:

import { Injectable, Inject, Singleton, RequestScoped } from "@pulzar/core";

@Injectable({ scope: "singleton" })
class DatabaseService {
  query(sql: string) {
    return { result: "data" };
  }
}

@Injectable({ scope: "request" })
class UserService {
  constructor(
    @Inject("DatabaseService") private db: DatabaseService,
    @Inject("LOGGER") private logger: Logger
  ) {}

  async getUser(id: string) {
    this.logger.info(`Getting user ${id}`);
    return this.db.query(`SELECT * FROM users WHERE id = ?`);
  }
}

🔐 Authentication & Authorization

Comprehensive auth system with multiple strategies:

import { JWTGuard, SessionGuard, OAuth2Guard } from "@pulzar/core";

// JWT Authentication
const jwtGuard = new JWTGuard({
  secret: process.env.JWT_SECRET,
  algorithm: "HS256",
  issuer: "your-app",
});

// Session-based Authentication
const sessionGuard = new SessionGuard({
  store: new RedisSessionStore(),
  secret: process.env.SESSION_SECRET,
  maxAge: 24 * 60 * 60 * 1000, // 24 hours
});

// OAuth2 Integration
@Controller("/auth")
class AuthController {
  @Post("/login")
  async login(@Body() credentials: LoginDto) {
    const user = await this.authService.validateUser(credentials);
    return this.jwtGuard.signToken(user);
  }

  @Get("/profile")
  @RequireAuth()
  async getProfile(@CurrentUser() user: User) {
    return user;
  }
}

📡 Event System

Powerful event streaming with multiple adapters:

import { EventBus, Event, EventHandler } from "@pulzar/core";

@Event("user.created")
class UserCreatedEvent {
  constructor(
    public readonly userId: string,
    public readonly email: string
  ) {}
}

@EventHandler(UserCreatedEvent)
class SendWelcomeEmailHandler {
  async handle(event: UserCreatedEvent) {
    await this.emailService.sendWelcomeEmail(event.email);
  }
}

// Emit events
await this.eventBus.emit(new UserCreatedEvent("123", "[e-mail]"));

// Configure adapters
const app = new Pulzar({
  events: {
    adapter: "kafka", // or 'nats', 'redis', 'memory'
    kafka: {
      brokers: ["localhost:9092"],
      clientId: "pulzar-app",
    },
  },
});

🌐 GraphQL Integration

Built-in GraphQL support with automatic schema generation:

import { Resolver, Query, Mutation, Args } from "@pulzar/core";

@Resolver()
class UserResolver {
  constructor(private userService: UserService) {}

  @Query(() => [User])
  async users() {
    return this.userService.findAll();
  }

  @Mutation(() => User)
  async createUser(@Args("input") input: CreateUserInput) {
    return this.userService.create(input);
  }
}

const app = new Pulzar({
  graphql: {
    path: "/graphql",
    playground: true,
    introspection: true,
  },
});

🌊 WebSocket Gateway

Real-time communication with WebSocket support:

import { WebSocketGateway, Subscribe, Emit } from "@pulzar/core";

@WebSocketGateway("/ws")
class ChatGateway {
  @Subscribe("message")
  handleMessage(client: WebSocket, data: any) {
    // Broadcast to all clients
    this.broadcast("message", data);
  }

  @Emit("user-joined")
  onUserJoin(userId: string) {
    return { userId, timestamp: new Date() };
  }
}

⚡ Edge Runtime Support

Deploy to edge environments:

import { EdgeAdapter } from "@pulzar/core/edge";

// Cloudflare Workers
export default EdgeAdapter.cloudflare(app);

// Vercel Edge Functions
export default EdgeAdapter.vercel(app);

// Deno Deploy
export default EdgeAdapter.deno(app);

🔧 Configuration

Environment Configuration

import { Config } from "@pulzar/core";

@Config()
class AppConfig {
  @Env("PORT", { default: 3000 })
  port: number;

  @Env("DATABASE_URL", { required: true })
  databaseUrl: string;

  @Env("JWT_SECRET", { required: true })
  jwtSecret: string;

  @Env("REDIS_URL", { default: "redis://localhost:6379" })
  redisUrl: string;
}

Application Setup

import { Pulzar } from "@pulzar/core";

const app = new Pulzar({
  // Core configuration
  port: 3000,
  host: "0.0.0.0",

  // Database
  database: {
    url: process.env.DATABASE_URL,
    type: "postgresql",
  },

  // Authentication
  auth: {
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "1d",
    },
    session: {
      store: "redis",
      secret: process.env.SESSION_SECRET,
    },
  },

  // Events
  events: {
    adapter: "kafka",
    kafka: {
      brokers: ["localhost:9092"],
    },
  },

  // GraphQL
  graphql: {
    path: "/graphql",
    playground: process.env.NODE_ENV === "development",
  },

  // WebSockets
  websockets: {
    path: "/ws",
    cors: true,
  },

  // OpenAPI
  openapi: {
    title: "My API",
    version: "1.0.0",
    path: "/docs",
  },

  // Observability
  tracing: {
    enabled: true,
    serviceName: "my-app",
  },
});

📦 Exports

Core Exports

// Main framework
export * from "@pulzar/core";

// Edge runtime adapters
export * from "@pulzar/core/edge";

// Testing utilities
export * from "@pulzar/core/testing";

Available Modules

• HTTP: Fastify adapter, routing, middleware
• DI: Dependency injection, decorators, scanning
• Auth: JWT, sessions, OAuth2, guards
• Events: Event bus, adapters (Kafka, NATS, Redis)
• GraphQL: Mercurius integration, resolvers
• WebSockets: Gateway, adapters (uWS, native)
• OpenAPI: Schema generation, Swagger UI
• Database: ORM integration, migrations
• Validation: Zod integration, custom validators
• Logging: Structured logging, OpenTelemetry
• Testing: Mocking, utilities, helpers

🧪 Testing

Comprehensive testing utilities included:

import { createTestApp, MockService } from "@pulzar/core/testing";

describe("UserController", () => {
  let app: TestApp;
  let userService: MockService<UserService>;

  beforeEach(async () => {
    app = await createTestApp({
      controllers: [UserController],
      providers: [
        {
          provide: UserService,
          useClass: MockService,
        },
      ],
    });

    userService = app.get(UserService);
  });

  it("should get users", async () => {
    userService.getUsers.mockResolvedValue([{ id: 1, name: "Alice" }]);

    const response = await app.inject({
      method: "GET",
      url: "/api/users",
    });

    expect(response.statusCode).toBe(200);
    expect(response.json()).toEqual([{ id: 1, name: "Alice" }]);
  });
});

🚀 Performance

Pulzar Core is built for speed:

• Fastify Foundation: Up to 30,000 req/sec
• Zero-Reflection DI: No runtime overhead
• Optimized Bundling: Tree-shakeable modules
• Edge Ready: Sub-100ms cold starts
• Memory Efficient: Minimal footprint

Benchmarks

# Basic HTTP
│ Stat      │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg     │ Stdev   │ Max      │
├───────────┼───────┼───────┼───────┼───────┼─────────┼─────────┼──────────┤
│ Req/Sec   │ 28,191│ 30,207│ 30,975│ 31,135│ 29,967  │ 1,012.46│ 31,135   │
│ Latency   │ 2ms   │ 3ms   │ 5ms   │ 6ms   │ 3.32ms  │ 1.12ms  │ 25ms     │

🔗 Ecosystem

Pulzar Core works great with:

• @pulzar/cli - Development CLI tools
• @pulzar/plugins - Additional integrations
• Prisma - Database ORM
• Zod - Schema validation
• Vitest - Testing framework

📖 Documentation

• Getting Started - Installation and first steps
• API Reference - Complete API documentation
• Examples - Real-world examples
• Deployment - Production deployment guides
• Migration Guide - Migrating from other frameworks

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

git clone https://github.com/pulzar-framework/pulzar.git
cd pulzar
npm install
npm run build
npm test

📄 License

MIT © Pulzar Team

🙏 Acknowledgments

Built with ❤️ by the Pulzar team and powered by:

• Fastify - Fast and low overhead web framework
• TypeScript - Language and tooling
• Zod - Schema validation
• OpenTelemetry - Observability

⭐ Star us on GitHub • 💬 Join Discord • 🐦 Follow on Twitter

Made with ❤️ for the developer community