import {
  BaseApplication,       // Your app extends this
  BaseController,        // Controllers extend this
  DefaultCRUDRepository, // Repositories extend this
  BaseEntity,            // Models extend this
  BaseDataSource,        // DataSources extend this
} from '@venizia/ignis';

// models/user.model.ts
import { BaseEntity, model, generateIdColumnDefs, generateTzColumnDefs } from '@venizia/ignis';
import { pgTable, text } from 'drizzle-orm/pg-core';

@model({
  type: 'entity',
  settings: {
    hiddenProperties: ['password'],
  },
})
export class User extends BaseEntity<typeof User.schema> {
  static override schema = pgTable('User', {
    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
    ...generateTzColumnDefs(),
    username: text('username').notNull().unique(),
    email: text('email').notNull().unique(),
    password: text('password'),
  });

  static override relations = () => [];
}

// datasources/postgres.datasource.ts
import { BaseDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';

interface IDSConfigs {
  host: string;
  port: number;
  database: string;
  user: string;
  password: string;
}

@datasource({ driver: 'node-postgres' })
export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
  constructor() {
    super({
      name: PostgresDataSource.name,
      config: {
        host: process.env.DB_HOST!,
        port: +(process.env.DB_PORT ?? 5432),
        database: process.env.DB_NAME!,
        user: process.env.DB_USER!,
        password: process.env.DB_PASSWORD!,
      },
      // Schema is auto-discovered from @repository bindings
    });
  }

  override configure(): ValueOrPromise<void> {
    const schema = this.getSchema();
    this.pool = new Pool(this.settings);
    this.connector = drizzle({ client: this.pool, schema });
  }

  override getConnectionString() {
    const { host, port, user, password, database } = this.settings;
    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
  }
}

// repositories/user.repository.ts
import { PersistableRepository, repository } from '@venizia/ignis';
import { User } from '../models/user.model';
import { PostgresDataSource } from '../datasources/postgres.datasource';

@repository({ model: User, dataSource: PostgresDataSource })
export class UserRepository extends PersistableRepository<typeof User.schema> {
  // No constructor needed -- DataSource is auto-injected at param[0]
}

// controllers/user.controller.ts
import {
  BaseController, controller, get, post,
  inject, jsonContent, jsonResponse, HTTP, TRouteContext,
} from '@venizia/ignis';
import { z } from '@hono/zod-openapi';
import { UserRepository } from '../repositories/user.repository';

@controller({ path: '/users' })
export class UserController extends BaseController {
  constructor(
    @inject({ key: 'repositories.UserRepository' }) private userRepo: UserRepository,
  ) {
    super({ scope: UserController.name });
  }

  override binding() {}

  @get({
    configs: {
      path: '/',
      responses: jsonResponse({
        schema: z.array(z.object({ id: z.string(), username: z.string(), email: z.string() })),
      }),
    },
  })
  async listUsers(context: TRouteContext) {
    const users = await this.userRepo.find({ filter: {} });
    return context.json(users, 200);
  }

  @post({
    configs: {
      path: '/',
      request: {
        body: jsonContent({
          description: 'New user data',
          schema: z.object({ username: z.string(), email: z.string(), password: z.string() }),
        }),
      },
      responses: jsonResponse({
        schema: z.object({ count: z.number(), data: z.any() }),
      }),
    },
  })
  async createUser(context: TRouteContext) {
    const body = context.req.valid<{ username: string; email: string; password: string }>('json');
    const result = await this.userRepo.create({ data: body });
    return context.json(result, 200);
  }
}

// application.ts
import {
  BaseApplication, IApplicationConfigs, IApplicationInfo,
  HealthCheckComponent, SwaggerComponent, ValueOrPromise,
} from '@venizia/ignis';
import { PostgresDataSource } from './datasources/postgres.datasource';
import { UserRepository } from './repositories/user.repository';
import { UserController } from './controllers/user.controller';

const configs: IApplicationConfigs = {
  host: 'localhost',
  port: 3000,
  path: { base: '/api', isStrict: true },
};

export class Application extends BaseApplication {
  constructor() {
    super({ scope: Application.name, config: configs });
    this.init();
  }

  getAppInfo(): IApplicationInfo {
    return { name: 'My App', version: '1.0.0', description: 'My Ignis application' };
  }

  staticConfigure() {}

  preConfigure(): ValueOrPromise<void> {
    // Register components
    this.component(HealthCheckComponent);
    this.component(SwaggerComponent);

    // Register datasources, repositories, and controllers
    this.dataSource(PostgresDataSource);
    this.repository(UserRepository);
    this.controller(UserController);
  }

  postConfigure(): ValueOrPromise<void> {}

  setupMiddlewares(): ValueOrPromise<void> {
    // Add CORS, body limit, etc.
  }
}

// index.ts
import { Application } from './application';

const app = new Application();
app.start();

protected async registerDynamicBindings<T extends IConfigurable>(opts: {
  namespace: TBindingNamespace;
  onBeforeConfigure?: (opts: { binding: Binding<T> }) => Promise<void>;
  onAfterConfigure?: (opts: { binding: Binding<T>; instance: T }) => Promise<void>;
}): Promise<void>;

// In preConfigure() or postConfigure():
this.registerPostStartHook({
  identifier: 'warmup-cache',
  hook: async () => {
    const cacheService = this.get<CacheService>({ key: 'services.CacheService' });
    await cacheService.warmup();
    console.log('Cache warmed up');
  },
});

this.registerPostStartHook({
  identifier: 'register-cron-jobs',
  hook: async () => {
    const cronService = this.get<CronService>({ key: 'services.CronService' });
    cronService.startAll();
  },
});

staticConfigure() {
  // Serve files from ./public directory at all unmatched routes
  this.static({ folderPath: './public' });

  // Or serve at a specific path
  this.static({ restPath: '/assets/*', folderPath: './static-assets' });
}

// Bun (default)
Bun.serve({ port, hostname, fetch: server.fetch });

// Node.js (requires @hono/node-server)
import { serve } from '@hono/node-server';
serve({ fetch: server.fetch, port, hostname });

interface IApplicationConfigs {
  host?: string;           // Server host (default: 'localhost' or APP_ENV_SERVER_HOST env)
  port?: number;           // Server port (default: 3000 or PORT/APP_ENV_SERVER_PORT env)

  path: {
    base: string;          // Base path for all routes (e.g., '/api')
    isStrict: boolean;     // When true, '/users' and '/users/' are different routes
  };

  requestId?: {
    isStrict: boolean;     // Enforce request ID on all requests
  };

  favicon?: string;        // Emoji favicon (default: fire emoji)

  error?: {
    rootKey: string;       // Wrap error responses in this key (e.g., 'error')
  };

  asyncContext?: {
    enable: boolean;       // Enable Hono async context storage (default: true)
  };

  bootOptions?: IBootOptions;  // Convention-based auto-discovery options

  debug?: {
    shouldShowRoutes?: boolean;  // Print all registered routes on startup
  };
}

interface IApplicationInfo {
  name: string;
  version: string;
  description: string;
  author?: { name: string; email: string; url?: string };
}

abstract class BaseController extends AbstractController {
  // Register routes -- override this method
  abstract binding(): ValueOrPromise<void>;

  // Imperative route definition
  defineRoute({ configs, handler, hook? });

  // Fluent two-step route definition
  bindRoute({ configs }).to({ handler });

  // JSX/HTML route definition (server-side rendering)
  defineJSXRoute({ configs, handler });

  // Get the router for this controller
  getRouter(): OpenAPIHono;
}

@controller({ path: '/products' })
class ProductController extends BaseController {
  constructor(
    @inject({ key: 'repositories.ProductRepository' }) private productRepo: ProductRepository,
    @inject({ key: 'services.InventoryService' }) private inventoryService: InventoryService,
  ) {
    super({ scope: ProductController.name });
  }

  override binding() {} // decorator routes are auto-registered

  @get({
    configs: {
      path: '/',
      description: 'List all products with pagination',
      responses: jsonResponse({
        schema: z.array(z.object({
          id: z.number(),
          name: z.string(),
          price: z.number(),
          category: z.string(),
        })),
        description: 'Array of products',
      }),
    },
  })
  async list(context: TRouteContext) {
    const products = await this.productRepo.find({
      filter: { order: ['createdAt DESC'], limit: 20 },
    });
    return context.json(products, 200);
  }

  @get({
    configs: {
      path: '/{id}',
      request: {
        params: z.object({ id: z.string().pipe(z.coerce.number()) }),
      },
      responses: jsonResponse({
        schema: z.object({
          id: z.number(),
          name: z.string(),
          price: z.number(),
          stock: z.number(),
        }),
      }),
    },
  })
  async getById(context: TRouteContext) {
    const { id } = context.req.valid<{ id: number }>('param');
    const product = await this.productRepo.findById({ id });
    if (!product) {
      return context.json({ message: 'Product not found' }, 404);
    }
    return context.json(product, 200);
  }

  @post({
    configs: {
      path: '/',
      authenticate: { strategies: ['jwt'] },
      request: {
        body: jsonContent({
          schema: z.object({
            name: z.string().min(1).max(255),
            price: z.number().positive(),
            category: z.string(),
            description: z.string().optional(),
          }),
          description: 'New product data',
        }),
      },
      responses: jsonResponse({
        schema: z.object({ count: z.number(), data: z.any() }),
      }),
    },
  })
  async create(context: TRouteContext) {
    const data = context.req.valid<{
      name: string;
      price: number;
      category: string;
      description?: string;
    }>('json');
    const result = await this.productRepo.create({ data });
    return context.json(result, 200);
  }
}

override binding() {
  this.defineRoute({
    configs: {
      path: '/',
      method: 'get',
      description: 'List products',
      responses: jsonResponse({ schema: z.array(ProductSchema) }),
    },
    handler: async (context) => {
      const products = await this.productRepo.find({ filter: {} });
      return context.json(products, 200);
    },
  });

  this.defineRoute({
    configs: {
      path: '/{id}',
      method: 'delete',
      authenticate: { strategies: ['jwt'] },
      authorize: { action: 'delete', resource: 'Product' },
      request: { params: idParamsSchema({ idType: 'number' }) },
      responses: jsonResponse({ schema: z.object({ count: z.number() }) }),
    },
    handler: async (context) => {
      const { id } = context.req.valid<{ id: number }>('param');
      const result = await this.productRepo.deleteById({ id });
      return context.json(result, 200);
    },
  });
}

override binding() {
  this.bindRoute({
    configs: {
      path: '/{id}',
      method: 'get',
      request: { params: idParamsSchema({ idType: 'number' }) },
      responses: jsonResponse({ schema: ProductSchema }),
    },
  }).to({
    handler: async (context) => {
      const { id } = context.req.valid<{ id: number }>('param');
      const product = await this.productRepo.findById({ id });
      return context.json(product, 200);
    },
  });
}

import { rateLimiter } from 'hono/rate-limiter';
import { cors } from 'hono/cors';

@post({
  configs: {
    path: '/upload',
    middleware: [
      rateLimiter({ windowMs: 60_000, limit: 10 }),
      cors({ origin: 'https://myapp.com' }),
    ],
    authenticate: { strategies: ['jwt'] },
    // ...
  },
})
async uploadFile(context: TRouteContext) { /* ... */ }

@post({
  configs: {
    path: '/',
    request: {
      body: jsonContent({
        schema: z.object({
          email: z.string().email('Invalid email format'),
          age: z.number().int().min(18, 'Must be at least 18'),
          role: z.enum(['admin', 'user', 'moderator']),
        }),
      }),
      query: z.object({
        dryRun: z.string().optional().transform(v => v === 'true'),
      }),
      headers: z.object({
        'x-api-key': z.string().min(1),
      }),
    },
    responses: jsonResponse({ schema: UserSchema }),
  },
})
async createUser(context: TRouteContext) {
  const body = context.req.valid<{ email: string; age: number; role: string }>('json');
  const { dryRun } = context.req.valid<{ dryRun?: boolean }>('query');
  const apiKey = context.req.valid<{ 'x-api-key': string }>('header');
  // All validated -- proceed safely
}

async myHandler(context: TRouteContext) {
  // Request data
  const body = context.req.valid<MyType>('json');
  const params = context.req.valid<{ id: number }>('param');
  const query = context.req.valid<{ page: number }>('query');

  // Raw request access
  const url = context.req.url;
  const method = context.req.method;
  const path = context.req.path;
  const userAgent = context.req.header('user-agent');
  const allHeaders = context.req.raw.headers;

  // Authenticated user (set by auth middleware)
  const currentUser = context.get('auth.current.user');
  const auditUserId = context.get('audit.user.id');

  // Set response headers
  context.header('X-Custom-Header', 'value');
  context.header('Cache-Control', 'no-store');

  // Response types
  return context.json({ data: 'value' }, 200);
  return context.text('plain text', 200);
  return context.html('<h1>Hello</h1>');
  return context.redirect('/other-page');
  return context.body(null, 204);  // No content
}

@post({
  configs: {
    path: '/upload',
    authenticate: { strategies: ['jwt'] },
    responses: jsonResponse({ schema: z.object({ filename: z.string(), size: z.number() }) }),
  },
})
async upload(context: TRouteContext) {
  const body = await context.req.parseBody();
  const file = body['file'];

  if (file instanceof File) {
    const buffer = await file.arrayBuffer();
    // Process file...
    return context.json({ filename: file.name, size: file.size }, 200);
  }

  return context.json({ message: 'No file provided' }, 400);
}

@get({
  configs: {
    path: '/stream',
    responses: { 200: { description: 'Streamed response' } },
  },
})
async streamData(context: TRouteContext) {
  return context.body(
    new ReadableStream({
      start(controller) {
        controller.enqueue(new TextEncoder().encode('chunk 1\n'));
        setTimeout(() => {
          controller.enqueue(new TextEncoder().encode('chunk 2\n'));
          controller.close();
        }, 1000);
      },
    }),
    200,
    { 'Content-Type': 'text/plain' },
  );
}

this.defineJSXRoute({
  configs: {
    path: '/profile',
    method: 'get',
    description: 'User profile page',
    authenticate: { strategies: ['jwt'] },
  },
  handler: (context) => {
    const user = context.get('auth.current.user');
    return context.html(<ProfilePage user={user} />);
  },
});

interface IAuthRouteConfig extends HonoRouteConfig {
  path: string;
  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
  description?: string;
  tags?: string[];

  // Authentication
  authenticate?: {
    strategies?: ('jwt' | 'basic')[];
    mode?: 'any' | 'all';
  };

  // Authorization (Casbin RBAC)
  authorize?: IAuthorizationSpec | IAuthorizationSpec[];

  // Request schema validation
  request?: {
    body?: ContentConfig;
    query?: ZodSchema;
    params?: ZodSchema;
    headers?: ZodSchema;
  };

  // Response schema
  responses: Record<number | string, ResponseConfig>;

  // Additional Hono middleware
  middleware?: MiddlewareHandler[];
}

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

const UserCrudController = ControllerFactory.defineCrudController({
  entity: User,
  repository: { name: 'UserRepository' },
  controller: {
    name: 'UserCrudController',
    basePath: '/users',
    isStrict: {
      path: true,            // Strict path matching
      requestSchema: true,   // Strict Zod request validation
    },
  },
  authenticate: { strategies: ['jwt'] },
  authorize: { action: 'manage', resource: 'User' },
  routes: {
    find: { authenticate: { skip: true } },      // Public read -- also skips authorization
    findById: { authenticate: { skip: true } },   // Public read
    count: { authenticate: { skip: true } },       // Public read
    create: {
      request: { body: CustomCreateSchema },       // Override request body schema
    },
    deleteById: {
      authorize: { action: 'delete', resource: 'User' },  // Override authorization
    },
  },
});

routes: {
  create: {
    request: { body: CustomCreateSchema },           // Custom request body
    response: { schema: CustomResponseSchema },      // Custom response schema
  },
  find: {
    request: { query: CustomFilterQuerySchema },     // Custom query params
    response: { headers: { 'X-Total': { description: 'Total count', schema: { type: 'string' } } } },
  },
}

// Zero boilerplate -- DataSource auto-injected from @repository metadata
@repository({ model: User, dataSource: PostgresDataSource })
export class UserRepository extends PersistableRepository<typeof User.schema> {
  // No constructor needed!
}

// Or with explicit @inject for more control
@repository({ model: User, dataSource: PostgresDataSource })
export class UserRepository extends PersistableRepository<typeof User.schema> {
  constructor(
    @inject({ key: 'datasources.PostgresDataSource' }) dataSource: PostgresDataSource,
  ) {
    super(dataSource);
  }

  // Custom methods
  async findByEmail(email: string) {
    return this.findOne({ filter: { where: { email } } });
  }

  async findActiveUsers() {
    return this.find({
      filter: {
        where: { status: 'active' },
        order: ['createdAt DESC'],
      },
    });
  }
}

// Simple count
const { count } = await repo.count({ where: { status: 'active' } });

// Count with complex conditions
const { count } = await repo.count({
  where: {
    and: [
      { role: { inq: ['admin', 'moderator'] } },
      { createdAt: { gte: new Date('2024-01-01') } },
      { or: [{ isVerified: true }, { score: { gt: 100 } }] },
    ],
  },
});

// Count within a transaction
const { count } = await repo.count({
  where: { status: 'pending' },
  options: { transaction: tx },
});

const emailTaken = await repo.existsWith({
  where: { email: 'john@example.com' },
});

if (emailTaken) {
  throw new Error('Email already in use');
}

// Basic find with filter
const users = await repo.find({
  filter: {
    where: { status: 'active' },
    fields: ['id', 'name', 'email'],
    order: ['createdAt DESC'],
    limit: 20,
    skip: 0,
  },
});

// Find with pagination range info
const { data, range } = await repo.find({
  filter: { where: { status: 'active' }, limit: 20, skip: 40 },
  options: { shouldQueryRange: true },
});
// data = User[] (the 20 records)
// range = { start: 40, end: 59, total: 150 }

// Find with relation inclusion (uses Query API)
const usersWithPosts = await repo.find({
  filter: {
    where: { isActive: true },
    include: [
      { relation: 'posts', scope: { where: { isPublished: true }, limit: 5 } },
    ],
  },
});

// Find all (bypass default filter for admin views)
const allUsers = await repo.find({
  filter: {},
  options: { shouldSkipDefaultFilter: true },
});

// Find with transaction
const users = await repo.find({
  filter: { where: { batchId: currentBatch } },
  options: { transaction: tx },
});

// Find with debug logging
const users = await repo.find({
  filter: { where: { status: 'active' } },
  options: { log: { use: true, level: 'debug' } },
});

const user = await repo.findOne({
  filter: {
    where: { email: 'john@example.com' },
    fields: ['id', 'name', 'email'],
    include: [{ relation: 'profile' }],
  },
});
// Returns User | null

const user = await repo.findById({
  id: 42,
  filter: {
    fields: ['id', 'name', 'email'],
    include: [{ relation: 'posts' }],
  },
});
// Returns User | null
// Equivalent to: findOne({ filter: { where: { id: 42 }, fields: [...], include: [...] } })

// Create and return the created record (default: shouldReturn = true)
const { count, data } = await repo.create({
  data: { username: 'john', email: 'john@example.com', role: 'user' },
});
// count = 1, data = { id: 1, username: 'john', ... }

// Create without returning data (faster -- skips RETURNING clause)
const { count } = await repo.create({
  data: { username: 'john', email: 'john@example.com' },
  options: { shouldReturn: false },
});
// count = 1, data = null

// Create within a transaction
const { data: user } = await repo.create({
  data: { username: 'john', email: 'john@example.com' },
  options: { transaction: tx },
});

// Bulk create and return all records
const { count, data } = await repo.createAll({
  data: [
    { username: 'john', email: 'john@example.com' },
    { username: 'jane', email: 'jane@example.com' },
    { username: 'bob', email: 'bob@example.com' },
  ],
});
// count = 3, data = [{ id: 1, ... }, { id: 2, ... }, { id: 3, ... }]

// Bulk create without returning (faster for large inserts)
const { count } = await repo.createAll({
  data: largeDataArray,
  options: { shouldReturn: false },
});

// Update by ID and return the updated record
const { count, data } = await repo.updateById({
  id: 42,
  data: { email: 'new@example.com', status: 'verified' },
});
// count = 1, data = { id: 42, email: 'new@example.com', ... }

// Update JSON fields using dot notation
const { data } = await repo.updateById({
  id: 42,
  data: {
    'metadata.theme': 'dark',
    'metadata.notifications.email': false,
  },
});

// Update all matching records
const { count, data } = await repo.updateAll({
  data: { status: 'inactive' },
  where: { lastLoginAt: { lt: new Date('2024-01-01') } },
});
// count = 25, data = [...25 updated records...]

// updateBy is an alias for updateAll
const { count } = await repo.updateBy({
  data: { isNotified: true },
  where: { role: 'subscriber' },
  options: { shouldReturn: false },
});

// SAFETY: Empty where throws an error to prevent accidental mass updates
// Use force: true to explicitly allow it
const { count } = await repo.updateAll({
  data: { version: 2 },
  where: {},
  options: { force: true },
});

// Delete by ID (returns deleted record)
const { count, data } = await repo.deleteById({ id: 42 });
// count = 1, data = { id: 42, username: 'john', ... }

// Delete all matching records
const { count, data } = await repo.deleteAll({
  where: { status: 'inactive' },
});

// deleteBy is an alias for deleteAll
const { count } = await repo.deleteBy({
  where: { expiresAt: { lt: new Date() } },
  options: { shouldReturn: false },
});

// SAFETY: Empty where throws an error. Use force: true to allow.
const { count } = await repo.deleteAll({
  where: {},
  options: { force: true, shouldReturn: false },
});

interface TFilter<T> {
  where?: TWhere<T>;       // Query conditions
  fields?: TFields;        // Column selection
  include?: TInclusion[];  // Relation loading
  order?: string[];        // Sorting (e.g., ['createdAt DESC', 'name ASC'])
  limit?: number;          // Max results (default: 10)
  skip?: number;           // Offset
  offset?: number;         // Alias for skip
}

// Query nested JSON fields using dot notation
const users = await repo.find({
  filter: {
    where: {
      'metadata.theme': 'dark',
      'settings.notifications.email': true,
      'preferences.items[0].enabled': { eq: true },
      'metadata.score': { gt: 50, lte: 100 },
    },
  },
});

const products = await repo.find({
  filter: {
    order: [
      'createdAt DESC',
      'metadata.priority DESC',
      'data.nested.score ASC',
    ],
  },
});

// Array format -- include only these columns
const users = await repo.find({
  filter: { fields: ['id', 'name', 'email'] },
});

// Object format -- include/exclude
const users = await repo.find({
  filter: { fields: { id: true, name: true, password: false } },
});

// Simple inclusion
const users = await repo.find({
  filter: {
    include: [{ relation: 'posts' }],
  },
});

// With nested filter (scope)
const users = await repo.find({
  filter: {
    include: [{
      relation: 'posts',
      scope: {
        where: { isPublished: true },
        limit: 5,
        order: ['createdAt DESC'],
        include: [{ relation: 'comments' }],  // Nested relations
      },
    }],
  },
});

// Skip default filter on a specific relation
const users = await repo.find({
  filter: {
    include: [{
      relation: 'archivedPosts',
      shouldSkipDefaultFilter: true,  // Show soft-deleted posts
    }],
  },
});

const result = await repo.find({
  filter: { where: { status: 'active' }, limit: 10, skip: 20 },
  options: { shouldQueryRange: true },
});

// result.data = User[] (the 10 records)
// result.range = { start: 20, end: 29, total: 150 }

// Admin panel showing all records (including soft-deleted)
const allUsers = await repo.find({
  filter: {},
  options: { shouldSkipDefaultFilter: true },
});

// Data migration or cleanup script
const deletedUsers = await repo.find({
  filter: { where: { isDeleted: true } },
  options: { shouldSkipDefaultFilter: true },
});

// Export all data for backup
const everything = await repo.find({
  filter: {},
  options: { shouldSkipDefaultFilter: true, shouldQueryRange: true },
});

interface IExtraOptions {
  transaction?: ITransaction;          // Use within a transaction
  shouldReturn?: boolean;              // Return data after create/update/delete (default: true)
  shouldQueryRange?: boolean;          // Return { data, range: { total, start, end } }
  shouldSkipDefaultFilter?: boolean;   // Bypass model's default filter
  log?: { use: boolean; level?: TLogLevel }; // Enable operation logging
}

@model({
  settings: { hiddenProperties: ['password', 'secretToken'] },
})
export class User extends BaseEntity<typeof User.schema> { ... }

// All repository queries automatically exclude 'password' and 'secretToken'
const user = await userRepo.findById({ id: 1 });
// user.password === undefined (never selected from DB)

// Hidden fields are excluded from:
// - find() / findOne() / findById() SELECT queries
// - create() RETURNING clauses
// - updateById() / updateAll() RETURNING clauses
// - deleteById() / deleteAll() RETURNING clauses
// - Included relation queries (applied recursively)

@model({
  settings: { defaultFilter: { where: { isDeleted: false } } },
})
export class User extends BaseEntity<typeof User.schema> { ... }

// All queries automatically add WHERE is_deleted = false
const users = await userRepo.find({ filter: {} });

// The default filter merges with user-provided filters:
const activeAdmins = await userRepo.find({
  filter: { where: { role: 'admin' } },
});
// SQL: WHERE is_deleted = false AND role = 'admin'

// Bypass when needed (e.g., admin panel showing all records)
const allUsers = await userRepo.find({
  filter: {},
  options: { shouldSkipDefaultFilter: true },
});

// Input data:
{ name: 'John', 'metadata.settings.theme': 'dark', 'metadata.version': 2 }

// Generates SQL:
// UPDATE users SET
//   name = 'John',
//   metadata = jsonb_set(jsonb_set("metadata", '{settings,theme}', '"dark"'::jsonb, true), '{version}', '2'::jsonb, true)
// WHERE id = 42

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

@model({
  type: 'entity',
  settings: {
    hiddenProperties: ['password', 'secretToken'],
    defaultFilter: { where: { isDeleted: false } },
  },
})
export class User extends BaseEntity<typeof User.schema> {
  static override schema = pgTable('User', {
    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
    ...generateTzColumnDefs({
      deleted: { enable: true, columnName: 'deleted_at', withTimezone: true },
    }),
    ...generateUserAuditColumnDefs(),
    username: text('username').notNull().unique(),
    email: text('email').notNull().unique(),
    password: text('password'),
    secretToken: text('secret_token'),
    role: text('role').default('user'),
    isDeleted: boolean('is_deleted').default(false),
    metadata: jsonb('metadata').$type<{ theme?: string; score?: number }>(),
  });

  static override relations = () => [
    { name: 'posts', type: 'many', schema: Post.schema, metadata: { fields: [Post.schema.authorId], references: [User.schema.id] } },
    { name: 'profile', type: 'one', schema: Profile.schema, metadata: { fields: [Profile.schema.userId], references: [User.schema.id] } },
  ];

  static TABLE_NAME = 'User';
}

@model({
  type: 'entity',                          // Entity type identifier
  settings: {
    hiddenProperties: ['password'],        // Excluded from all queries at SQL level
    defaultFilter: { where: { isDeleted: false } },  // Auto-applied to all queries
  },
})

const entity = new User();

entity.getSchema({ type: 'select' });  // Zod schema for SELECT results -- all fields as returned from DB
entity.getSchema({ type: 'create' });  // Zod schema for INSERT data -- required/optional based on column definitions
entity.getSchema({ type: 'update' });  // Zod schema for UPDATE data -- all fields optional (partial)

static override relations = () => [
  {
    name: 'posts',
    type: 'many',          // RelationTypes.MANY
    schema: Post.schema,
    metadata: {
      fields: [Post.schema.authorId],
      references: [User.schema.id],
    },
  },
  {
    name: 'profile',
    type: 'one',            // RelationTypes.ONE
    schema: Profile.schema,
    metadata: {
      fields: [Profile.schema.userId],
      references: [User.schema.id],
    },
  },
];

// Auto-incrementing integer ID (default)
...generateIdColumnDefs()
// Column: id integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY

// Auto-incrementing integer ID (explicit)
...generateIdColumnDefs({ id: { dataType: 'number' } })

// UUID string ID (uses crypto.randomUUID() by default)
...generateIdColumnDefs({ id: { dataType: 'string' } })

// Custom string ID generator
...generateIdColumnDefs({
  id: { dataType: 'string', generator: () => mySnowflakeGenerator() },
})

// BigInt ID (as JavaScript number)
...generateIdColumnDefs({ id: { dataType: 'big-number', numberMode: 'number' } })

// BigInt ID (as JavaScript bigint)
...generateIdColumnDefs({ id: { dataType: 'big-number', numberMode: 'bigint' } })

// With custom sequence options
...generateIdColumnDefs({
  id: { dataType: 'number', sequenceOptions: { startWith: 1000, increment: 1 } },
})

// Default: createdAt + modifiedAt (with timezone, defaultNow)
...generateTzColumnDefs()
// Columns: created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
//          modified_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL (auto-updates via $onUpdate)

// With deletedAt for soft delete
...generateTzColumnDefs({
  deleted: { enable: true, columnName: 'deleted_at', withTimezone: true },
})
// Adds: deleted_at TIMESTAMP WITH TIME ZONE (nullable)

// Disable modifiedAt
...generateTzColumnDefs({
  modified: { enable: false },
})
// Only creates: created_at

// Custom column names
...generateTzColumnDefs({
  created: { columnName: 'date_created', withTimezone: false },
  modified: { enable: true, columnName: 'date_modified', withTimezone: false },
})

// Default: integer columns
...generateUserAuditColumnDefs()
// Columns: created_by integer, modified_by integer
// Auto-populated from context.get('audit.user.id') on create/update

// String IDs
...generateUserAuditColumnDefs({
  created: { dataType: 'string', columnName: 'created_by', allowAnonymous: true },
  modified: { dataType: 'string', columnName: 'modified_by', allowAnonymous: true },
})

// Default discriminator name ('principal')
...generatePrincipalColumnDefs({ polymorphicIdType: 'number' })
// Columns: principal_id integer NOT NULL, principal_type text

// Custom discriminator
...generatePrincipalColumnDefs({
  discriminator: 'owner',
  polymorphicIdType: 'string',
  defaultPolymorphic: 'user',
})
// Columns: owner_id text NOT NULL, owner_type text DEFAULT 'user'

...generateDataTypeColumnDefs()
// Columns:
//   data_type text          -- type discriminator
//   n_value double precision -- numeric values
//   t_value text            -- text values
//   b_value bytea           -- binary values
//   j_value jsonb           -- JSON values
//   bo_value boolean        -- boolean values

// With defaults
...generateDataTypeColumnDefs({
  defaultValue: { dataType: 'text', tValue: 'default' },
})

abstract class BaseDataSource<Settings, Schema> extends AbstractDataSource {
  // Implemented by subclass
  abstract configure(): ValueOrPromise<void>;
  abstract getConnectionString(): ValueOrPromise<string>;

  // Auto-discovers schema from @repository bindings
  getSchema(): Schema;

  // Check if any repositories reference this datasource
  hasDiscoverableModels(): boolean;

  // Transaction support
  beginTransaction(opts?: ITransactionOptions): Promise<ITransaction>;
}

@datasource({ driver: 'node-postgres' })
export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
  constructor() {
    super({
      name: PostgresDataSource.name,
      config: {
        host: process.env.DB_HOST!,
        port: +(process.env.DB_PORT ?? 5432),
        database: process.env.DB_NAME!,
        user: process.env.DB_USER!,
        password: process.env.DB_PASSWORD!,
        // pg Pool options:
        max: 20,                        // max pool connections
        idleTimeoutMillis: 30000,       // close idle clients after 30s
        connectionTimeoutMillis: 5000,  // timeout connecting after 5s
      },
    });
  }

  override configure(): ValueOrPromise<void> {
    const schema = this.getSchema();  // Auto-discovers from repositories
    this.pool = new Pool(this.settings);
    this.connector = drizzle({ client: this.pool, schema });
  }

  override getConnectionString() {
    const { host, port, user, password, database } = this.settings;
    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
  }
}

const tx = await dataSource.beginTransaction({
  isolationLevel: 'READ COMMITTED',  // default
});

try {
  await userRepo.create({
    data: { username: 'john', email: 'john@example.com' },
    options: { transaction: tx },
  });

  await auditRepo.create({
    data: { action: 'user_created', userId: newUser.id },
    options: { transaction: tx },
  });

  await tx.commit();
} catch (error) {
  await tx.rollback();
  throw error;
}

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

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

  async createUser(data: CreateUserInput) {
    const tx = await this.userRepo.dataSource.beginTransaction();
    try {
      const { data: user } = await this.userRepo.create({
        data,
        options: { transaction: tx },
      });

      await this.auditRepo.create({
        data: { action: 'user_created', userId: user.id },
        options: { transaction: tx },
      });

      await tx.commit();
      return user;
    } catch (error) {
      await tx.rollback();
      throw error;
    }
  }

  async deactivateInactiveUsers() {
    const cutoff = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000); // 90 days
    const { count } = await this.userRepo.updateBy({
      data: { status: 'inactive' },
      where: { lastLoginAt: { lt: cutoff }, status: 'active' },
    });
    this.logger.info('Deactivated %d inactive users', count);
    return { count };
  }
}

this.service(UserService);

import { HealthCheckComponent, HealthCheckBindingKeys, IHealthCheckOptions } from '@venizia/ignis';

// Optional: customize path (default: /health)
this.bind<IHealthCheckOptions>({ key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS }).toValue({
  restOptions: { path: '/health-check' },
});
this.component(HealthCheckComponent);

import { SwaggerComponent, SwaggerBindingKeys, ISwaggerOptions } from '@venizia/ignis';

this.bind<ISwaggerOptions>({ key: SwaggerBindingKeys.SWAGGER_OPTIONS }).toValue({
  restOptions: {
    base: { path: '/doc' },
    doc: { path: '/openapi.json' },
    ui: { path: '/explorer', type: 'scalar' },  // 'scalar' or 'swagger'
  },
  explorer: { openapi: '3.0.0' },
});
this.component(SwaggerComponent);

import {
  AuthenticateComponent, AuthenticateBindingKeys,
  Authentication, AuthenticationStrategyRegistry,
  JWTAuthenticationStrategy, BasicAuthenticationStrategy,
  IJWTTokenServiceOptions, IBasicTokenServiceOptions,
  TAuthenticationRestOptions,
} from '@venizia/ignis';

// 1. Configure JWT options
this.bind<IJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
  jwtSecret: process.env.JWT_SECRET!,           // Secret for signing JWTs
  applicationSecret: process.env.APP_SECRET!,   // Secret for AES encrypting payload fields
  headerAlgorithm: 'HS256',                     // JWT signing algorithm (default: HS256)
  aesAlgorithm: 'aes-256-cbc',                 // Payload encryption algorithm (default: aes-256-cbc)
  getTokenExpiresFn: () => 86400,               // Token expiration in seconds (24 hours)
});

// 2. Configure Basic auth options (optional)
this.bind<IBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTIONS }).toValue({
  verifyCredentials: async ({ credentials, context }) => {
    const user = await userRepo.findOne({
      filter: { where: { username: credentials.username } },
    });
    if (user && await verifyPassword(credentials.password, user.password)) {
      return { userId: user.id, roles: user.roles };
    }
    return null;
  },
});

// 3. Optionally enable auth controller (sign-in, sign-up, change-password)
this.bind<TAuthenticationRestOptions>({ key: AuthenticateBindingKeys.REST_OPTIONS }).toValue({
  useAuthController: true,
  controllerOpts: {
    restPath: '/auth',
    payload: {
      signIn: { request: { schema: SignInSchema }, response: { schema: TokenSchema } },
      signUp: { request: { schema: SignUpSchema }, response: { schema: UserSchema } },
    },
  },
});

// 4. Register the component
this.component(AuthenticateComponent);

// 5. Register strategies
AuthenticationStrategyRegistry.getInstance().register({
  container: this,
  strategies: [
    { name: Authentication.STRATEGY_JWT, strategy: JWTAuthenticationStrategy },
    { name: Authentication.STRATEGY_BASIC, strategy: BasicAuthenticationStrategy },
  ],
});

// Generate a token
const token = await jwtTokenService.generate({
  payload: {
    userId: user.id,
    roles: [{ id: 1, identifier: 'admin', priority: 1 }],
    email: user.email,
  },
});

// Verify a token
const payload = await jwtTokenService.verify({
  type: 'Bearer',
  token: 'eyJhbGciOiJ...',
});
// payload = { userId: '...', roles: [...], email: '...' }

@get({
  configs: {
    path: '/profile',
    authenticate: { strategies: ['jwt'], mode: 'any' },
    responses: jsonResponse({ schema: UserProfileSchema }),
  },
})
async getProfile(context: TRouteContext) {
  const user = context.get('auth.current.user');
  // user = { userId: '...', roles: [...], ... }

  const auditId = context.get('audit.user.id');
  // auditId = user.userId (set automatically for UserAuditEnricher)

  // ...
}

// Controller-level (via ControllerFactory)
const UserController = ControllerFactory.defineCrudController({
  authenticate: { strategies: ['jwt'] },  // Applied to ALL routes
  routes: {
    find: { authenticate: { skip: true } },  // Override: public
  },
});

// Route-level (via decorators)
@controller({ path: '/products' })
class ProductController extends BaseController {
  @get({
    configs: {
      path: '/',
      // No authenticate -- public route
      responses: jsonResponse({ schema: z.array(ProductSchema) }),
    },
  })
  async list(c: TRouteContext) { /* ... */ }

  @post({
    configs: {
      path: '/',
      authenticate: { strategies: ['jwt'] },  // Protected route
      responses: jsonResponse({ schema: ProductSchema }),
    },
  })
  async create(c: TRouteContext) { /* ... */ }
}

import {
  AuthorizeComponent, AuthorizeBindingKeys, IAuthorizeOptions,
  CasbinAuthorizationEnforcer,
} from '@venizia/ignis';

this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
  enforcer: CasbinAuthorizationEnforcer,
  alwaysAllowRoles: ['superadmin'],         // Roles that bypass all authorization
  casbinOptions: {
    model: '/path/to/model.conf',           // Casbin model file
    adapter: myAdapter,                     // e.g., FileAdapter, PostgresAdapter
  },
});
this.component(AuthorizeComponent);

@get({
  configs: {
    path: '/admin/users',
    authenticate: { strategies: ['jwt'] },
    authorize: { action: 'read', resource: 'User' },
    responses: jsonResponse({ schema: z.array(UserSchema) }),
  },
})
async listUsers(context: TRouteContext) { /* ... */ }

// Multiple authorization specs (all must pass)
@del({
  configs: {
    path: '/admin/users/{id}',
    authenticate: { strategies: ['jwt'] },
    authorize: [
      { action: 'delete', resource: 'User' },
      { action: 'manage', resource: 'Admin' },
    ],
    // ...
  },
})
async deleteUser(context: TRouteContext) { /* ... */ }

import {
  StaticAssetComponent, StaticAssetComponentBindingKeys,
  StaticAssetStorageTypes, TStaticAssetsComponentOptions,
} from '@venizia/ignis';
import { MinioHelper, DiskHelper } from '@venizia/ignis-helpers';

// MinIO backend
this.bind<TStaticAssetsComponentOptions>({
  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
}).toValue({
  staticAsset: {
    controller: { name: 'AssetController', basePath: '/assets' },
    storage: StaticAssetStorageTypes.MINIO,
    helper: new MinioHelper({
      endPoint: 'localhost',
      port: 9000,
      accessKey: 'minioadmin',
      secretKey: 'minioadmin',
      useSSL: false,
    }),
  },
});
this.component(StaticAssetComponent);

// Disk backend
this.bind<TStaticAssetsComponentOptions>({
  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
}).toValue({
  staticAsset: {
    controller: { name: 'AssetController', basePath: '/assets' },
    storage: StaticAssetStorageTypes.DISK,
    helper: new DiskHelper({ basePath: './uploads' }),
  },
});