@kanjijs/core 0.2.0-beta.1

package/README.md

@@ -0,0 +1,55 @@
+# @kanjijs/core
+
+The "Brain" of the framework. This package handles the **Declaration Phase**.
+It provides the decorators used to define APIs and the internal storage mechanism to save that metadata for later use by the Adapter.
+
+## 📦 Features
+
+### Decorators
+
+- **`@Controller(prefix: string)`**: Marks a class as a controller and sets the root path.
+- **`@Get(path: string)`**: Registers a GET route.
+- **`@Post(path: string)`**: Registers a POST route.
+- **`@Put`, `@Delete`, `@Patch`**: Support for standard HTTP verbs.
+- **`@Use(...middlewares)`**: Registers Hono-compatible middleware for a route or controller.
+- **`@Module({ ... })`**: Defines a module with `imports`, `controllers`, and `providers`.
+- **`@Inject(token)`**: Token-based dependency injection.
+
+### Request Context (AsyncLocalStorage)
+Kanjijs Core includes a built-in `kanjijsContext` (based on Node.js AsyncLocalStorage) to track request state globally without prop drilling. It enables access to `requestId` anywhere in the stack.
+
+```typescript
+import { getRequestId } from "@kanjijs/core";
+const reqId = getRequestId();
+```
+
+### Dependency Injection
+**KanjijsIoC**: A lightweight, platform-agnostic IoC container embedded in Core. It handles singleton resolution and dependency injection for your modules and controllers.
+
+### Metadata Storage
+
+We use a `WeakMap`-based `MetadataStorage` singleton to keep the memory footprint minimal and ensure metadata is garbage collected if the controller class is no longer referenced.
+
+```typescript
+// Internal usage
+const routes = MetadataStorage.getRoutes(ControllerClass.prototype);
+```
+
+## 🛡️ Exception Handling
+
+Kanjijs Core defines the standard exceptions used across the framework.
+
+-   **`HttpException`**: Base class for HTTP errors.
+-   **`ExceptionFilter`**: Interface for implementing custom exception filters.
+
+```typescript
+import { HttpException } from "@kanjijs/core";
+
+throw new HttpException("Custom Error", 400);
+// OR
+throw new HttpException({ message: "Validation Failed", errors: [] }, 422);
+```
+
+## 🚫 No Runtime Cost
+
+This package does **not** depend on Hono, Bun, or Express. It only uses `reflect-metadata` to store information. The actual execution logic is delegated to the Platform adapters.