Quick Reference Card

A single-page reference for the most commonly used classes, methods, decorators, and operators in IGNIS.

Core Classes

BaseApplication

import { BaseApplication } from '@venizia/ignis';

class MyApp extends BaseApplication {
  constructor() {
    super({ projectRoot: __dirname });
  }
}

const app = new MyApp();
await app.initialize();
await app.start();

Key Methods:

• initialize() - Bootstrap the application
• start() - Start HTTP server
• stop() - Stop server gracefully
• get<T>(key) - Resolve from DI container
• mountControllers() - Register controllers

BaseRestController

import { BaseRestController, controller, get } from '@venizia/ignis';

@controller({ path: '/users' })
class UserController extends BaseRestController {
  constructor() {
    super({ scope: UserController.name, path: '/users' });
  }

  override binding() {}

  @get({ configs: { path: '/:id', responses: { 200: { description: 'User' } } } })
  getUser(c: Context) {
    const id = c.req.param('id');
    return c.json({ id, name: 'John' });
  }
}

Key Properties:

• this.router - OpenAPIHono instance
• this.path - Controller base path
• this.logger - Scoped logger

BaseGrpcController

import { BaseGrpcController, controller, unary, ControllerTransports } from '@venizia/ignis';
import { GreeterService } from '../gen/greeter_connect';

@controller({ path: '/grpc', transport: ControllerTransports.GRPC, service: GreeterService })
class GreeterController extends BaseGrpcController {
  constructor() {
    super({ scope: GreeterController.name, path: '/grpc' });
  }

  override binding() {}

  @unary({ configs: { name: 'sayHello' } })
  async sayHello(request: SayHelloRequest) {
    return { message: `Hello, ${request.name}!` };
  }
}

BaseService

import { BaseService, injectable } from '@venizia/ignis';

@injectable()
class UserService extends BaseService {
  constructor() {
    super({ scope: UserService.name });
  }

  async getUser(id: string) {
    this.logger.info('Getting user', id);
    return this.userRepo.findById(id);
  }
}

Key Properties:

• this.logger - Scoped logger

DefaultCRUDRepository

import { DefaultCRUDRepository } from '@venizia/ignis';
import { User } from '../models';

class UserRepository extends DefaultCRUDRepository<User> {
  constructor() {
    super(User);
  }
}

Key Methods:

• create(data) - Create single entity
• createMany(data[]) - Create multiple entities
• find(filter?) - Find many with filter
• findById(id) - Find by ID
• findOne(filter) - Find single entity
• count(filter?) - Count entities
• update(id, data) - Update by ID
• updateMany(filter, data) - Update multiple
• delete(id) - Delete by ID (soft/hard based on config)
• deleteMany(filter) - Delete multiple

BaseEntity

import { BaseEntity, model } from '@venizia/ignis';
import { integer, text, pgTable } from 'drizzle-orm/pg-core';

@model()
class User extends BaseEntity {
  static readonly tableName = 'users';
  static readonly schema = pgTable(User.tableName, {
    id: integer('id').primaryKey(),
    name: text('name').notNull(),
    email: text('email').notNull().unique(),
  });
}

Key Properties:

• static tableName - Database table name
• static schema - Drizzle schema definition
• static AUTHORIZATION_SUBJECT - Authorization principal (auto-set from @model settings authorize.principal)

Route Decorators

HTTP Methods

Decorator	HTTP Method	Example
@get()	GET	@get({ configs: { path: '/:id' } })
@post()	POST	@post({ configs: { path: '/' } })
@put()	PUT	@put({ configs: { path: '/:id' } })
@patch()	PATCH	@patch({ configs: { path: '/:id' } })
@del()	DELETE	@del({ configs: { path: '/:id' } })

RPC Method Decorators (gRPC)

Decorator	RPC Type	Example
@rpc()	Generic	@rpc({ configs: { name: 'myMethod', method: 'unary' } })
@unary()	Unary	@unary({ configs: { name: 'sayHello' } })
@serverStream()	Server streaming	@serverStream({ configs: { name: 'listItems' } })
@clientStream()	Client streaming	@clientStream({ configs: { name: 'uploadData' } })
@bidiStream()	Bidirectional	@bidiStream({ configs: { name: 'chat' } })

REST Example

@controller({ path: '/users' })
class UserController extends BaseRestController {
  constructor(
    @inject({ key: 'services.UserService' }) private userService: UserService,
  ) {
    super({ scope: UserController.name, path: '/users' });
  }

  override binding() {}

  @post({ configs: { path: '/', responses: { 201: { description: 'Created' } } } })
  async createUser(c: Context) {
    const data = await c.req.json();
    const result = await this.userService.create(data);
    return c.json(result, 201);
  }

  @get({ configs: { path: '/:id', responses: { 200: { description: 'User' } } } })
  async getUser(c: Context) {
    const id = c.req.param('id');
    const result = await this.userService.findById(id);
    return c.json(result);
  }
}

Filter Operators

Comparison Operators

Operator	SQL	Example
eq	=	{ status: { eq: 'active' } }
neq	!=	{ status: { neq: 'deleted' } }
gt	>	{ age: { gt: 18 } }
gte	>=	{ age: { gte: 18 } }
lt	<	{ price: { lt: 100 } }
lte	<=	{ price: { lte: 100 } }

Range Operators

Operator	SQL	Example
between	BETWEEN	{ age: { between: [18, 65] } }
notBetween	NOT BETWEEN	{ age: { notBetween: [0, 18] } }

List Operators

Operator	SQL	Example
in	IN	{ status: { in: ['active', 'pending'] } }
notIn	NOT IN	{ status: { notIn: ['deleted'] } }

Pattern Matching

Operator	SQL	Example
like	LIKE	{ name: { like: '%john%' } }
ilike	ILIKE	{ email: { ilike: '%@gmail.com' } }
notLike	NOT LIKE	{ name: { notLike: '%test%' } }
notILike	NOT ILIKE	{ email: { notILike: '%spam%' } }
startsWith	LIKE 'value%'	{ name: { startsWith: 'John' } }
endsWith	LIKE '%value'	{ email: { endsWith: '@example.com' } }

Null Operators

Operator	SQL	Example
isNull	IS NULL	{ deletedAt: { isNull: true } }
isNotNull	IS NOT NULL	{ email: { isNotNull: true } }

Logical Operators

Operator	SQL	Example
and	AND	{ and: [{ age: { gt: 18 } }, { status: 'active' }] }
or	OR	{ or: [{ role: 'admin' }, { role: 'moderator' }] }
not	NOT	{ not: { status: 'deleted' } }

Array Operators (PostgreSQL)

Operator	SQL	Example
contains	@>	{ tags: { contains: ['typescript'] } }
containedBy	<@	{ tags: { containedBy: ['ts', 'js', 'go'] } }
overlaps	&&	{ tags: { overlaps: ['react', 'vue'] } }

JSON Operators (PostgreSQL)

Operator	Description	Example
jsonPath	Query JSON field	{ metadata: { jsonPath: '$.user.name', eq: 'John' } }

Common Filters

Basic Find

const users = await userRepo.find({
  where: { isActive: true },
  orderBy: { createdAt: 'desc' },
  limit: 10,
  offset: 0,
});

With Multiple Conditions

const users = await userRepo.find({
  where: {
    and: [
      { age: { gte: 18 } },
      { status: { in: ['active', 'pending'] } },
      { email: { endsWith: '@company.com' } }
    ]
  }
});

With Relations

const posts = await postRepo.find({
  where: { published: true },
  include: {
    author: true,
    comments: {
      where: { approved: true },
      limit: 5
    }
  }
});

Selecting Fields

const users = await userRepo.find({
  where: { isActive: true },
  fields: ['id', 'name', 'email'], // Only these fields
});

Dependency Injection

Injectable Decorator

import { injectable } from '@venizia/ignis';

@injectable()
class MyService extends BaseService {
  // ...
}

Inject Decorator

import { inject } from '@venizia/ignis';

class UserController extends BaseRestController {
  constructor(
    @inject({ key: 'services.UserService' })
    private userService: UserService,
  ) {
    super({ scope: UserController.name, path: '/users' });
  }

Manual Resolution

const userService = app.get<UserService>('services.UserService');

Common Imports

Core Framework

import {
  // Application
  BaseApplication,

  // REST Controllers
  BaseRestController,
  controller,

  // gRPC Controllers
  BaseGrpcController,
  ControllerTransports,

  // REST Route Decorators
  get, post, put, patch, del, api,

  // gRPC Route Decorators
  rpc, unary, serverStream, clientStream, bidiStream,

  // Services
  BaseService,

  // Repositories
  DefaultCRUDRepository,

  // Models
  BaseEntity,
  model,

  // DI
  inject,
  injectable,

  // Utilities
  jsonResponse,
  htmlResponse,
  Statuses,
} from '@venizia/ignis';

Helpers

import {
  // Logging
  LoggerFactory,
  ApplicationLogger,

  // Caching
  RedisHelper,

  // Queues
  QueueHelper,

  // Crypto
  hash,
  compare,

  // HTTP
  HTTP,
} from '@venizia/ignis-helpers';
import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
import { CronHelper } from '@venizia/ignis-helpers/cron';
import { MinIOHelper } from '@venizia/ignis-helpers/minio';

Dependency Injection

import { Container, BindingKeys } from '@venizia/ignis-inversion';
import { BindingNamespaces } from '@venizia/ignis';

OpenAPI/Swagger

JSON Response

import { jsonResponse } from '@venizia/ignis';
import { z } from '@hono/zod-openapi';

@get({
  configs: {
    path: '/users/:id',
    responses: jsonResponse({
      description: 'User data',
      schema: z.object({
        id: z.string(),
        name: z.string(),
        email: z.string().email(),
      }),
    }),
  },
})
getUser(c: Context) {
  const id = c.req.param('id');
  return c.json({ id, name: 'John', email: 'john@example.com' });
}

HTML Response

import { htmlResponse } from '@venizia/ignis';

@get({
  configs: {
    path: '/dashboard',
    responses: htmlResponse({
      description: 'Dashboard page',
    }),
  },
})
getDashboard(c: Context) {
  return c.html(<DashboardPage />);
}

Status Codes

Using Statuses

import { Statuses } from '@venizia/ignis';

// Create with status
const order = await orderRepo.create({
  items: [...],
  status: Statuses.PENDING,
});

// Update status
await orderRepo.update(orderId, {
  status: Statuses.COMPLETED,
});

// Check status
if (Statuses.isActive(order.status)) {
  // Process order
}

if (Statuses.isCompleted(order.status)) {
  // Order is done
}

Common Statuses

Status	Value	Category
UNKNOWN	'000_UNKNOWN'	Initial
DRAFT	'001_DRAFT'	Initial
PENDING	'103_PENDING'	Pending
ACTIVATED	'201_ACTIVATED'	Active
RUNNING	'202_RUNNING'	Active
COMPLETED	'303_COMPLETED'	Completed
SUCCESS	'302_SUCCESS'	Completed
CONFIRMED	'305_CONFIRMED'	Completed
SUSPENDED	'402_SUSPENDED'	Inactive
ARCHIVED	'405_ARCHIVED'	Inactive
REFUNDED	'408_REFUNDED'	Inactive
FAIL	'500_FAIL'	Failed
CANCELLED	'505_CANCELLED'	Failed
DELETED	'506_DELETED'	Failed

Middlewares

Built-in Middlewares

import {
  appErrorHandler,
  notFoundHandler,
  RequestSpyMiddleware,
  emojiFavicon,
} from '@venizia/ignis';

const app = new MyApp();

// Request logging and body parsing
const requestSpy = new RequestSpyMiddleware();
app.use(requestSpy.value());

// Emoji favicon
app.use(emojiFavicon({ icon: '🚀' }));

// Error handling (register last)
app.onError(appErrorHandler({ logger: app.logger }));

// 404 handler
app.notFound(notFoundHandler({ logger: app.logger }));

Environment Variables

Loading Environment

import { EnvHelper } from '@venizia/ignis-helpers';

// Load from .env file
EnvHelper.load();

// Get variable
const dbUrl = EnvHelper.get('DATABASE_URL');

// Get with default
const port = EnvHelper.get('PORT', '3000');

// Get required (throws if missing)
const apiKey = EnvHelper.getRequired('API_KEY');

Common Patterns

Controller → Service → Repository

// Controller
@controller({ path: '/users' })
class UserController extends BaseRestController {
  constructor(
    @inject({ key: 'services.UserService' })
    private userService: UserService,
  ) {
    super({ scope: UserController.name, path: '/users' });
  }

  override binding() {}

  @post({ configs: { path: '/', responses: { 201: { description: 'Created' } } } })
  async createUser(c: Context) {
    const data = await c.req.json();
    return c.json(await this.userService.create(data), 201);
  }
}

// Service
class UserService extends BaseService {
  constructor(
    @inject({ key: 'repositories.UserRepository' })
    private userRepo: UserRepository,
  ) {
    super({ scope: UserService.name });
  }

  async create(data: CreateUserDto) {
    // Business logic
    const hashedPassword = await hash({ value: data.password });

    return this.userRepo.create({
      data: {
        ...data,
        password: hashedPassword,
      },
    });
  }
}

// Repository
@repository({ model: User, dataSource: PostgresDataSource })
class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
  // DataSource auto-injected from @repository decorator
}

See Also

• Full Documentation:

  • Base Abstractions - Complete API reference
  • Components - Pre-built features
  • Helpers - Utility helpers
  • Utilities - Pure functions

• Guides:

  • Getting Started - Tutorials and walkthroughs
  • Core Concepts - Architecture deep-dive

• Best Practices:

  • Architectural Patterns
  • Security Guidelines