@venizia/ignis-docs 0.0.1-1 → 0.0.1-10

package/wiki/get-started/philosophy.md

@@ -2,28 +2,107 @@
 
 Ignis combines the structured, enterprise-grade development experience of **LoopBack 4** with the speed and simplicity of **Hono**.
 
-## The Problem
+## The Landscape
 
-When building REST APIs with Node.js/Bun, developers face a choice:
+When building REST APIs with Node.js/Bun, developers choose from three categories of frameworks, each with genuine strengths:
 
-| Aspect | Minimal Frameworks | Enterprise Frameworks | **Ignis** |
-|--------|-------------------|----------------------|-----------|
-| **Examples** | Express, Hono, Fastify | NestJS, LoopBack | **Ignis** |
-| **Performance** | ⚡ Very fast | 🐌 Slower | ⚡ Very fast (Hono) |
-| **Architecture** | ❌ No structure | ✅ Structured | ✅ Structured |
-| **Learning Curve** | ✅ Easy | ❌ Steep | ✅ Gradual |
-| **Dependency Injection** | ❌ Manual | ✅ Built-in | ✅ Built-in |
-| **Boilerplate** | ✅ Minimal | ❌ Heavy | ✅ Moderate |
-| **Best For** | Prototypes, tiny APIs | Large enterprise apps | Growing APIs, teams |
+### Framework Categories
 
-### Ignis: The Middle Ground
+| Category | Examples | Philosophy |
+|----------|----------|------------|
+| **Minimal** | Express, Hono, Fastify, Koa | Freedom, speed, flexibility |
+| **Enterprise** | NestJS, LoopBack 4, AdonisJS | Structure, patterns, conventions |
+| **Balanced** | Ignis, Ts.ED | Structure with lighter footprint |
 
-Ignis provides the architectural benefits of enterprise frameworks while maintaining Hono's speed:
+## Honest Comparison
 
-- ✅ **Enterprise patterns** (DI, layered architecture) without the bloat
-- ✅ **Hono's performance** - one of the fastest frameworks
-- ✅ **Gradual complexity** - start simple, add structure as you grow
-- ✅ **TypeScript-first** with excellent type safety
+### Performance & Runtime
+
+| Framework | Requests/sec | Startup Time | Memory | Multi-Runtime |
+|-----------|-------------|--------------|--------|---------------|
+| **Hono** | ~150k | ~10ms | ~20MB | ✅ Bun, Node, Deno, CF Workers |
+| **Fastify** | ~80k | ~50ms | ~40MB | Node only |
+| **Express** | ~15k | ~100ms | ~50MB | Node only |
+| **NestJS** | ~25k | ~500ms | ~100MB | Node (Bun experimental) |
+| **LoopBack 4** | ~20k | ~800ms | ~120MB | Node only |
+| **Ignis** | ~140k | ~30ms | ~30MB | ✅ Bun, Node |
+
+*Benchmarks are approximate and vary by use case.*
+
+### Developer Experience
+
+| Aspect | Minimal (Hono/Express) | Enterprise (NestJS/LoopBack) | Ignis |
+|--------|------------------------|------------------------------|-------|
+| **Setup Time** | 5 minutes | 30+ minutes | 10 minutes |
+| **Learning Curve** | Low | High | Medium |
+| **Boilerplate** | Minimal | Heavy | Moderate |
+| **Type Safety** | Manual | Excellent | Excellent |
+| **IDE Support** | Basic | Excellent | Good |
+| **Documentation** | Good | Excellent | Growing |
+
+### Architecture & Patterns
+
+| Pattern | Minimal | Enterprise | Ignis |
+|---------|---------|------------|-------|
+| **Dependency Injection** | ❌ Manual/3rd party | ✅ Built-in (complex) | ✅ Built-in (simple) |
+| **Layered Architecture** | ❌ DIY | ✅ Enforced | ✅ Guided |
+| **Repository Pattern** | ❌ DIY | ✅ Built-in | ✅ Built-in |
+| **Validation** | ❌ 3rd party | ✅ Built-in | ✅ Built-in (Zod) |
+| **OpenAPI/Swagger** | ❌ 3rd party | ✅ Built-in | ✅ Built-in |
+| **Authentication** | ❌ DIY | ✅ Modules available | ✅ Built-in component |
+
+### Ecosystem & Maturity
+
+| Aspect | Minimal (Hono) | Enterprise (NestJS) | Ignis |
+|--------|----------------|---------------------|-------|
+| **Community Size** | Growing fast | Very large | Small |
+| **npm Downloads** | ~500k/week | ~3M/week | New |
+| **Stack Overflow** | Limited | Extensive | Limited |
+| **Third-party Modules** | Middleware-based | Rich ecosystem | Growing |
+| **Production Battle-tested** | Yes | Yes | Emerging |
+| **Corporate Backing** | Cloudflare | Trilon | Independent |
+
+### Flexibility vs Convention
+
+| Aspect | Minimal | Enterprise | Ignis |
+|--------|---------|------------|-------|
+| **Project Structure** | Total freedom | Strict conventions | Guided conventions |
+| **ORM Choice** | Any | TypeORM/Prisma preferred | Drizzle (flexible) |
+| **Testing Approach** | Any | Jest recommended | Any |
+| **Middleware System** | Simple | Complex interceptors | Hono middleware |
+| **Customization** | Unlimited | Plugin-based | Component-based |
+
+## The Middle Ground: Where Ignis Fits
+
+### What Each Approach Excels At
+
+**Minimal Frameworks (Hono, Express, Fastify):**
+- ✅ Maximum performance
+- ✅ Complete freedom in architecture
+- ✅ Fastest prototyping
+- ✅ Smallest bundle size
+- ✅ Edge/serverless deployments
+- ⚠️ Architecture decisions left to developer
+- ⚠️ Patterns must be implemented manually
+
+**Enterprise Frameworks (NestJS, LoopBack):**
+- ✅ Battle-tested patterns
+- ✅ Comprehensive documentation
+- ✅ Large community & ecosystem
+- ✅ Excellent for large teams
+- ✅ Strong conventions prevent chaos
+- ⚠️ Higher resource consumption
+- ⚠️ Steeper learning curve
+- ⚠️ More boilerplate
+
+**Ignis (The Middle Ground):**
+- ✅ Enterprise patterns without the weight
+- ✅ Hono's performance foundation
+- ✅ Gradual complexity adoption
+- ✅ TypeScript-first with Zod validation
+- ⚠️ Smaller community (new framework)
+- ⚠️ Less documentation than mature frameworks
+- ⚠️ Fewer third-party integrations
 
 ## Inspired By The Best
 
@@ -102,17 +181,111 @@ Ignis = LoopBack patterns + Hono performance:
 - Type-safe database operations
 - Automatic validation
 
+## Choose the Right Tool
+
+### Use Hono/Fastify/Express When:
+
+| Scenario | Why It's Better |
+|----------|-----------------|
+| Building a simple webhook handler | No structure overhead needed |
+| Edge/serverless functions | Minimal cold start, tiny bundle |
+| Rapid prototyping | Get something running in minutes |
+| Microservices with 1-5 endpoints | Structure adds unnecessary complexity |
+| You want maximum control | No conventions to follow |
+| Learning web development | Simpler mental model |
+
+### Use NestJS/LoopBack When:
+
+| Scenario | Why It's Better |
+|----------|-----------------|
+| Large team (10+ developers) | Strong conventions prevent chaos |
+| Enterprise with strict standards | Mature, battle-tested, auditable |
+| Need extensive ecosystem | Many official and community modules |
+| Complex microservices architecture | Built-in support for messaging, CQRS |
+| Hiring developers easily | Large talent pool familiar with it |
+| Long-term support is critical | Corporate backing, LTS versions |
+
+### Use Ignis When:
+
+| Scenario | Why It's Better |
+|----------|-----------------|
+| Medium-sized API (10-100 endpoints) | Right balance of structure and speed |
+| Small team wanting patterns | DI without enterprise complexity |
+| Performance is critical | Hono's speed with structure |
+| Coming from LoopBack/NestJS | Familiar patterns, lighter weight |
+| Bun-first development | Native Bun support |
+| Growing project | Start simple, add complexity gradually |
+
 ## The Trade-off
 
-| You Gain | You Give Up |
-|----------|-------------|
-| Clear architecture | ~100 lines setup boilerplate |
-| Built-in DI, validation, docs | Learning curve for patterns |
-| Faster for medium/large projects | Slightly more abstraction than Hono |
-| Easier testing | Initial time investment |
-| Team scalability | Convention over total freedom |
+Every choice has trade-offs. Here's an honest look:
 
-**Bottom line:** If you're building more than a simple API, the structure pays off in maintainability and productivity.
+### What You Gain with Ignis
+
+| Benefit | Compared To |
+|---------|-------------|
+| ~5x faster than NestJS | Enterprise frameworks |
+| Built-in DI, validation, OpenAPI | Minimal frameworks |
+| Structured codebase | DIY architecture |
+| Easier testing with DI | Manual mocking |
+| Team-friendly patterns | Individual coding styles |
+
+### What You Give Up with Ignis
+
+| Trade-off | Compared To |
+|-----------|-------------|
+| ~10% slower than raw Hono | Minimal frameworks |
+| Smaller community | NestJS/Express |
+| Less documentation | Mature frameworks |
+| Learning curve for patterns | No-structure approach |
+| Convention requirements | Total freedom |
+
+### Honest Assessment
+
+| Aspect | Ignis Reality |
+|--------|---------------|
+| **Maturity** | New framework, evolving API |
+| **Community** | Small but growing |
+| **Documentation** | Good but not comprehensive |
+| **Production Use** | Early adopters only |
+| **Breaking Changes** | Possible before v1.0 |
+| **Support** | Community-driven |
+
+**Bottom line:** Ignis is ideal for developers who want enterprise patterns without enterprise overhead. If you need battle-tested stability and extensive community support, consider NestJS. If you need maximum simplicity, stick with Hono.
+
+## Migration Paths
+
+### From Hono to Ignis
+
+If your Hono project grows complex:
+
+```
+1. Add Ignis as dependency
+2. Wrap existing Hono app with Ignis Application
+3. Gradually introduce DI for new features
+4. Migrate routes to controllers over time
+```
+
+### From NestJS to Ignis
+
+If you want better performance:
+
+```
+1. Controllers → Ignis Controllers (similar decorators)
+2. Services → Ignis Services (same pattern)
+3. Repositories → Ignis Repositories (Drizzle instead of TypeORM)
+4. Modules → Ignis Components (simpler structure)
+```
+
+### From Ignis to NestJS
+
+If you outgrow Ignis:
+
+```
+1. Patterns are similar - migration is straightforward
+2. Main changes: ORM, module system, interceptors
+3. DI concepts transfer directly
+```
 
 ## Next Steps
 

package/wiki/get-started/quickstart.md

@@ -265,7 +265,7 @@ export class HelloController extends BaseController {
   })
   sayHello(c: Context) {
     // This looks just like Hono! Because it IS Hono under the hood.
-    return c.json({ message: 'Hello, World!' });
+    return c.json({ message: 'Hello, World!' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
   // You can add more routes here:

package/wiki/public/logo.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 92.27 122.88" style="enable-background:new 0 0 92.27 122.88" xml:space="preserve"><style type="text/css">.st0{fill-rule:evenodd;clip-rule:evenodd;fill:#EC6F59;} .st1{fill-rule:evenodd;clip-rule:evenodd;fill:#FAD15C;}</style><g><path class="st0" d="M18.61,54.89C15.7,28.8,30.94,10.45,59.52,0C42.02,22.71,74.44,47.31,76.23,70.89 c4.19-7.15,6.57-16.69,7.04-29.45c21.43,33.62,3.66,88.57-43.5,80.67c-4.33-0.72-8.5-2.09-12.3-4.13C10.27,108.8,0,88.79,0,69.68 C0,57.5,5.21,46.63,11.95,37.99C12.85,46.45,14.77,52.76,18.61,54.89L18.61,54.89z"/><path class="st1" d="M33.87,92.58c-4.86-12.55-4.19-32.82,9.42-39.93c0.1,23.3,23.05,26.27,18.8,51.14 c3.92-4.44,5.9-11.54,6.25-17.15c6.22,14.24,1.34,25.63-7.53,31.43c-26.97,17.64-50.19-18.12-34.75-37.72 C26.53,84.73,31.89,91.49,33.87,92.58L33.87,92.58z"/></g></svg>

package/wiki/references/base/application.md

@@ -37,11 +37,11 @@ Extends `AbstractApplication` with concrete lifecycle implementations and resour
 
 | Method | DI Binding Key Convention |
 | :--- | :--- |
-| `component(MyComponent)` | `components.MyComponent` |
-| `controller(MyController)` | `controllers.MyController` |
-| `service(MyService)` | `services.MyService` |
-| `repository(MyRepository)`| `repositories.MyRepository` |
-| `dataSource(MyDataSource)`| `datasources.MyDataSource` |
+| `component(MyComponent, opts?)` | `components.MyComponent` (default) or custom key via `opts.binding` |
+| `controller(MyController, opts?)` | `controllers.MyController` (default) or custom key via `opts.binding` |
+| `service(MyService, opts?)` | `services.MyService` (default) or custom key via `opts.binding` |
+| `repository(MyRepository, opts?)`| `repositories.MyRepository` (default) or custom key via `opts.binding` |
+| `dataSource(MyDataSource, opts?)`| `datasources.MyDataSource` (default) or custom key via `opts.binding` |
 
 ### `initialize()` Method Flow
 

package/wiki/references/base/components.md

@@ -1,6 +1,6 @@
 # Deep Dive: Components
 
-Technical reference for `BaseComponent` - creating pluggable, reusable modules in Ignis.
+Technical reference for `BaseComponent`—the foundation for creating reusable, pluggable features in Ignis. Components are powerful containers that can group together multiple providers, services, controllers, repositories, and even entire mini-applications into a single, redistributable module.
 
 **File:** `packages/core/src/base/components/base.ts`
 

package/wiki/references/base/controllers.md

@@ -65,7 +65,7 @@ export class MyFeatureController extends BaseController {
 
   @api({ configs: MyRouteConfig })
   getData(c: TRouteContext<typeof MyRouteConfig>) { // Return type is automatically inferred and validated
-    return c.json({ success: true });
+    return c.json({ success: true }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 ```
@@ -83,7 +83,7 @@ For convenience, `Ignis` provides decorator shortcuts for each HTTP method: Thes
 **Example using `@get` and `@post` with type inference:**
 
 ```typescript
-import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext } from '@venizia/ignis';
+import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext, HTTP } from '@venizia/ignis';
 
 // Define route configs as const for full type inference
 const USER_ROUTES = {
@@ -125,20 +125,20 @@ const USER_ROUTES = {
 
   @get({ configs: USER_ROUTES.listUsers })
   getAllUsers(c: TRouteContext<typeof USER_ROUTES.listUsers>) { // Return type is automatically inferred
-    return c.json([{ id: '1', name: 'John Doe' }]);
+    return c.json([{ id: '1', name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   }
 
   @get({ configs: USER_ROUTES.getUser })
   getUserById(c: TRouteContext<typeof USER_ROUTES.getUser>) { // Return type is automatically inferred
     const { id } = c.req.valid('param'); // id is typed as string
-    return c.json({ id, name: 'John Doe' });
+    return c.json({ id, name: 'John Doe' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
   @post({ configs: USER_ROUTES.createUser })
   createUser(c: TRouteContext<typeof USER_ROUTES.createUser>) { // Return type is automatically inferred
     const { name } = c.req.valid('json'); // name is typed as string
     const newUser = { id: '2', name };
-    return c.json(newUser, 201); // Return type is validated
+    return c.json(newUser, HTTP.ResultCodes.RS_2.Created); // Return type is validated
   }
 ```
 
@@ -171,17 +171,21 @@ export class HealthCheckController extends BaseController {
   @api({ configs: HEALTH_CHECK_ROUTES['/ping'] })
   ping(c: TRouteContext<typeof HEALTH_CHECK_ROUTES['/ping']>) { // Return type is automatically inferred
     const { message } = c.req.valid('json');
-    return c.json({ pong: message });
+    return c.json({ pong: message }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 ```
 
 ### Manual Route Definition Methods
 
-While decorator-based routing is available, the recommended way to define routes is by using the `defineRoute` and `bindRoute` methods inside the `binding()` method. This approach offers a clear and declarative syntax that keeps your route definitions organized and easy to manage.
+For advanced use cases or when you prefer a non-decorator approach, you can define routes manually using `defineRoute` and `bindRoute` methods inside the `binding()` method.
 
-:::tip Recommendation
-For better organization and a more declarative approach, we strongly recommend using `defineRoute` or `bindRoute` within the `binding()` method to define your controller's routes. This keeps all route definitions in one place, making your controller easier to read and maintain.
+:::tip When to Use Manual Definition
+Manual route definition is useful for:
+- Dynamically generating routes based on configuration
+- Conditional route registration (feature flags)
+- Developers who prefer non-decorator syntax (coming from Express/Fastify)
+- Complex routing logic that benefits from programmatic control
 :::
 
 #### `defineRoute`
@@ -287,19 +291,21 @@ The `ControllerFactory` provides a static method `defineCrudController` to quick
 
 ### `static defineCrudController<EntitySchema>(opts: ICrudControllerOptions<EntitySchema>)`
 
-This factory method returns a `BaseController` class that is already set up with the following standard CRUD endpoints:
+This factory method returns a `BaseController` class that is already set up with the following standard CRUD endpoints.
 
-| Name | Method | Path | Description |
+**Note:** The returned class is dynamically named using `controller.name` from the options. This ensures that when registered with `app.controller()`, the class has a proper name for binding keys and debugging (e.g., `ConfigurationController` instead of an anonymous class).
+
+| Route Name | Method | Path | Description |
 | :--- | :--- | :--- | :--- |
 | `count` | `GET` | `/count` | Get the number of records matching a filter. |
 | `find` | `GET` | `/` | Retrieve all records matching a filter. |
 | `findById` | `GET` | `/:id` | Retrieve a single record by its ID. |
 | `findOne` | `GET` | `/find-one` | Retrieve a single record matching a filter. |
 | `create` | `POST` | `/` | Create a new record. |
-| `updateById` | `PATCH` | `/:id` | Update a record by its ID. |
-| `updateAll` | `PATCH` | `/` | Update multiple records matching a filter. |
-| `deleteById` | `DELETE` | `/:id` | Delete a record by its ID. |
-| `deleteAll` | `DELETE` | `/` | Delete multiple records matching a filter. |
+| `updateById` | `PATCH` | `/:id` | Update a single record by its ID. |
+| `updateBy` | `PATCH` | `/` | Update multiple records matching a `where` filter. |
+| `deleteById` | `DELETE` | `/:id` | Delete a single record by its ID. |
+| `deleteBy` | `DELETE` | `/` | Delete multiple records matching a `where` filter. |
 
 ### `ICrudControllerOptions<EntitySchema>`
 
@@ -309,10 +315,30 @@ This factory method returns a `BaseController` class that is already set up with
 | `repository.name` | `string` | The binding key name of the repository associated with this entity (e.g., `'ConfigurationRepository'`). |
 | `controller.name` | `string` | A unique name for the generated controller (e.g., `'ConfigurationController'`). |
 | `controller.basePath`| `string` | The base path for all routes in this CRUD controller (e.g., `'/configurations'`). |
+| `controller.readonly` | `boolean` | If `true`, only read operations (find, findOne, findById, count) are generated. Write operations are excluded. Defaults to `false`. |
 | `controller.isStrict` | `boolean` | If `true`, query parameters like `where` will be strictly validated. Defaults to `true`. |
 | `controller.defaultLimit`| `number` | The default limit for `find` operations. Defaults to `10`. |
-| `schema` | `object` | An optional object to override the default Zod schemas for specific CRUD endpoints (e.g., `find`, `create`, `updateByIdRequestBody`). This allows for fine-grained control over the request and response validation and OpenAPI documentation. |
-| `doDeleteWithReturn` | `boolean` | If `true`, the `deleteById` and `deleteAll` endpoints will return the deleted record(s) in the response body. Defaults to `false`. |
+| `schema` | `object` | An optional object to override the default Zod schemas for specific CRUD endpoints. See schema options below. |
+| `doDeleteWithReturn` | `boolean` | If `true`, the `deleteById` and `deleteBy` endpoints will return the deleted record(s) in the response body. Defaults to `false`. |
+
+### Schema Override Options
+
+The `schema` option allows fine-grained control over request/response validation and OpenAPI documentation:
+
+| Schema Option | Description |
+| :--- | :--- |
+| `count` | Override response schema for count endpoint |
+| `find` | Override response schema for find endpoint |
+| `findOne` | Override response schema for findOne endpoint |
+| `findById` | Override response schema for findById endpoint |
+| `create` | Override response schema for create endpoint |
+| `createRequestBody` | Override request body schema for create endpoint |
+| `updateById` | Override response schema for updateById endpoint |
+| `updateByIdRequestBody` | Override request body schema for updateById endpoint |
+| `updateBy` | Override response schema for updateBy (bulk update) endpoint |
+| `updateByRequestBody` | Override request body schema for updateBy endpoint |
+| `deleteById` | Override response schema for deleteById endpoint |
+| `deleteBy` | Override response schema for deleteBy (bulk delete) endpoint |
 
 ### Example