Build fast backends with zero bloat

Clone the framework and link it:

# Clone & build
git clone https://github.com/your-org/velocity-framework.git
cd velocity-framework
bun install && bun run build && bun run sync

# Create your project
mkdir my-app && cd my-app && bun init
terminal

Required tsconfig.json:

{ "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true, "target": "ESNext", "module": "ESNext", "moduleResolution": "bundler" } }
tsconfig.json

import { VeloApplication } from '@velocity/framework';

export const velo = new VeloApplication({
  port: 5000,
  globalPrefix: '/api',
  cors: { origin: '*' },
  rateLimit: { max: 100, window: 60_000 },
  security: true,
  shutdown: { timeout: 10_000, auto: true },
});
velo.ts

export const db = DB({ type: 'sqlite', database: ':memory:', filename: ':memory:' });
db.ts

@Entity('users')
export class User {
  @PrimaryKey() id: number;
  @Column() name: string;
  @Column({ unique: true }) email: string;
  constructor() { this.id = 0; this.name = ''; this.email = ''; }
}
src/entities/user.entity.ts

Supported: 'sqlite', 'postgresql', 'mysql'. For multiple databases: @Entity('posts', 'pgDb').

@Controller('/users')
export class UserController {
  @Get('/')
  async list() { return { users: await db.User.findAll() }; }

  @Get('/:id')
  async getById(param: any) { return db.User.findById(param.id); }

  @Post('/')
  async create(body: any) { return db.User.create(body); }

  @Delete('/:id')
  async remove(param: any) { await db.User.delete(param.id); }
}
src/controllers/user.controller.ts

Nest controllers: @Controller('/profile', { scope: 'UserController' })

@Service()
export class AuthService {
  createToken(id: number) { return `token-${id}`; }
}

@Controller('/auth')
export class AuthController {
  constructor(private auth: AuthService) {}

  @Post('/login')
  login(body: any) { return { token: this.auth.createToken(body.id) }; }
}
Constructor injection

Singletons by default. Scope with @Service({ scope: 'ControllerName' }).

async function main() {
  await velo.scan(path.join(__dirname, 'src'), { databases: { db } });
  await velo.listen();
}
main.ts

Filter: { include: ['UserController'], exclude: ['MetricsController'] }

Manual velo.register() is still available for tests and dynamic cases.

// Guard: return false = 403
@Guards((req) => !!req.headers['authorization'])

// Middleware: classic (req, res, next)
@Middlewares((req, res, next) => { console.log(req.url); next(); })

// Global hooks
velo.onRequest((req) => { ... });
velo.onResponse((req, res) => { ... });
velo.onError((err, req, res) => { res.status(500).json({ error: err.message }); });
Guards, middleware, hooks

@Validate(Validator.createSchema({ name: Joi.string().required() }))  // Joi
@Validate(z.object({ name: z.string() }))                          // Zod
@Validate((body) => { if(!body.name) throw Error('!'); return body; }) // Function
Validation options

// Enable in config
session: { secret: 'key', maxAge: 3600 }

// In handlers
login(body, session) { session.set({ userId: body.id }); }
me(session) { return session.data; }
logout(session) { session.destroy(); }

// Cookies
res.setCookie('token', 'val', { httpOnly: true, signed: true });
Sessions & cookies

// File uploads
@Upload({ maxSize: 5_242_880 })
upload(req) { return req.files.avatar; }

// WebSocket
@WebSocket('/chat')
class Chat { @Command('msg') handle(ws, d) { ws.send(...); } }

// Background worker
@Go() async run(@Channel('jobs') ch) { for await(const j of ch) { ... } }

// HTTP functions
@Fn() greet(name) { return { hi: name }; }  // GET /.greet("Alice")

// Scheduling
@Every(60_000) tick() { ... }
@Cron('0 * * * *') hourly() { ... }
More features

velo.cluster(4);  // instead of velo.listen()

// Cross-worker shared state (Bun only)
class M extends SharedState {
  @Field('counter') hits!: SharedCounter;
  @Field('hashmap', { capacity: 4096 }) ips!: SharedHashMap;
}

// Inject via DI, use atomic ops
this.m.hits.add(1);  // ~68ns, all workers see it
Cluster + shared memory

npm run velogen -- all ./my-app
terminal

@Suite('User API')
class Tests {
  @BeforeEach
  setup() { this.app = TestUtils.createTestApp(); this.app.register(UserController); }

  @Test('lists users')
  async list() {
    const { status } = await TestUtils.makeRequest(this.app, { method: 'GET', path: '/users' });
    expect(status).toBe(200);
  }
}
Decorator-based tests

TestUtils.makeRequest runs in-process — no network, no server startup.