@kurdel/core 0.1.0-beta.1

package/lib/http/routing/route.js

@@ -0,0 +1,21 @@
+export const ROUTE_META = Symbol('@kurdel/core:route-meta');
+/* ──────────────────────────────────────────────────────────────────────────
+ * route(meta)(handler)
+ * Attaches metadata to a handler AND preserves the handler's identity.
+ *
+ * Important: handler is NOT wrapped.
+ * RuntimeControllerPipe calls handler.call(controller, ctx),
+ * so the function MUST be the original method reference.
+ * ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Decorates the given handler with metadata (method, path, schema).
+ *
+ * Typing also narrows ctx.params based on meta.path automatically.
+ */
+export function route(meta) {
+    return function (fn) {
+        fn[ROUTE_META] = meta;
+        return fn;
+    };
+}
+//# sourceMappingURL=route.js.map

package/lib/http/routing/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../src/http/routing/route.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAwI5D;;;;;;;gFAOgF;AAEhF;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAA4B,IAAO;IACtD,OAAO,UAGL,EAA0B;QACzB,EAAU,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QAC/B,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC"}

package/lib/http/routing/router.d.ts

@@ -0,0 +1,27 @@
+import type { Container } from '@kurdel/ioc';
+import type { Method, ControllerConfig, ControllerResolver, RouteMatch } from '../../http/index.js';
+/**
+ * A minimal HTTP router contract.
+ *
+ * Responsibilities:
+ * - Register routes at bootstrap (`init`)
+ * - Resolve a request (method + path) to an executable handler
+ * - Leave actual execution (middlewares, controller action, rendering)
+ *   to higher orchestration layers.
+ */
+export interface Router {
+    /**
+     * Initializes the routing table and prepares route lookup.
+     * Called exactly once during application bootstrap.
+     */
+    init(resolver: ControllerResolver, controllerConfigs: ControllerConfig[]): void;
+    /**
+     * Attempts to resolve a route for the given HTTP method and URL.
+     *
+     * Returns a {@link RouteMatch} describing which controller/action to execute,
+     * or `null` if no route matches.
+     *
+     * The returned object is later executed by RuntimeRequestOrchestrator.
+     */
+    resolve(method: Method, url: string, scope: Container): RouteMatch | null;
+}

package/lib/http/routing/router.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=router.js.map

package/lib/http/routing/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../../src/http/routing/router.ts"],"names":[],"mappings":""}

package/lib/http/server/index.d.ts

@@ -0,0 +1,2 @@
+export * from './running-server.js';
+export * from './server-adapter.js';

package/lib/http/server/index.js

@@ -0,0 +1,3 @@
+export * from './running-server.js';
+export * from './server-adapter.js';
+//# sourceMappingURL=index.js.map

package/lib/http/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/http/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/lib/http/server/running-server.d.ts

@@ -0,0 +1,8 @@
+export interface RunningServer {
+    /** e.g. http://127.0.0.1:3000 */
+    url?: string;
+    /** Graceful shutdown */
+    close(): Promise<void>;
+    /** Escape hatch for tests (e.g., Node http.Server) */
+    raw?<T = unknown>(): T | undefined;
+}

package/lib/http/server/running-server.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=running-server.js.map

package/lib/http/server/running-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"running-server.js","sourceRoot":"","sources":["../../../src/http/server/running-server.ts"],"names":[],"mappings":""}

package/lib/http/server/server-adapter.d.ts

@@ -0,0 +1,82 @@
+import type { HttpRequest, HttpResponse } from '@kurdel/common';
+/**
+ * A unified abstraction over different HTTP runtime environments.
+ *
+ * The `ServerAdapter` interface allows the Kurdel runtime to operate
+ * in both long-running (Node.js) and request-scoped (Web/Edge) contexts
+ * using a shared contract.
+ *
+ * Implementations may bridge native platform primitives
+ * (e.g. Node’s `IncomingMessage`, Fetch API `Request`, etc.)
+ * into the framework-agnostic `HttpRequest` / `HttpResponse` types.
+ *
+ * ---
+ * ### Adapter responsibilities:
+ * - Translate platform-specific request/response objects.
+ * - Delegate execution to the runtime pipeline (middlewares + controller).
+ * - Manage platform-specific server lifecycle (optional).
+ *
+ * ### Typical Implementations:
+ * - **Node.js** → `NativeHttpServerAdapter` (uses `listen` / `close`)
+ * - **Web / Edge** → `WebHttpServerAdapter` (uses `handle`)
+ *
+ * ---
+ */
+export interface ServerAdapter<R = HttpRequest, S = HttpResponse> {
+    /**
+     * Registers the platform-independent request handler.
+     *
+     * The runtime calls this once to connect the main execution pipeline.
+     *
+     * @example
+     * adapter.on(async (req, res) => {
+     *   await router.dispatch(req, res);
+     * });
+     */
+    on(handler: (req: R, res: S) => void | Promise<void>): void;
+    /**
+     * Handles a single incoming request.
+     *
+     * This method is primarily used by environments that expose a Fetch-like API
+     * (such as Cloudflare Workers, Deno Deploy, Bun, or Vercel Edge).
+     *
+     * Implementations should adapt the incoming request object and return
+     * a platform-compatible response.
+     *
+     * @example
+     * const response = await adapter.handle(request);
+     */
+    handle?(request: unknown, ...args: unknown[]): Promise<unknown> | unknown;
+    /**
+     * Starts listening for incoming connections.
+     *
+     * Used by long-running environments (e.g., Node.js, Bun’s TCP mode).
+     * May be a no-op in serverless / edge environments.
+     *
+     * @example
+     * adapter.listen(3000, () => console.log('Server started'));
+     */
+    listen?(port: number, hostOrCb?: string | (() => void), cb?: () => void): void | Promise<void>;
+    /**
+     * Gracefully closes the underlying server.
+     *
+     * Optional. Typically used in tests or controlled shutdowns.
+     */
+    close?(): Promise<void>;
+    /**
+     * Returns the underlying platform-native server instance.
+     *
+     * This is a low-level escape hatch for advanced integrations
+     * (e.g., attaching WebSocket handlers, inspecting connections).
+     *
+     * @example
+     * const nodeServer = adapter.raw<import('../../http').Server>();
+     */
+    raw?<T = unknown>(): T | undefined;
+    /**
+     * Returns the effective base URL of the server, if applicable.
+     *
+     * Useful for testing, introspection, or constructing self-referential links.
+     */
+    url?(): string;
+}

package/lib/http/server/server-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server-adapter.js.map

package/lib/http/server/server-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-adapter.js","sourceRoot":"","sources":["../../../src/http/server/server-adapter.ts"],"names":[],"mappings":""}

package/lib/http/types.d.ts

@@ -0,0 +1,10 @@
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type Route = {
+    method: Method;
+    path: string;
+    handler: Function;
+};
+export type Query = Readonly<Record<string, string | string[]>>;
+export type JsonValue = string | number | boolean | null | undefined | JsonValue[] | {
+    [k: string]: JsonValue;
+};

package/lib/http/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/http/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":""}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * as http from './http/index.js';
+export * as app from './app/index.js';
+export * as db from './db/index.js';
+export * as template from './template/index.js';
+export * as tokens from './tokens/index.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export * as http from './http/index.js';
+export * as app from './app/index.js';
+export * as db from './db/index.js';
+export * as template from './template/index.js';
+export * as tokens from './tokens/index.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAC;AACpC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC"}

package/lib/template/index.d.ts

@@ -0,0 +1,2 @@
+export * from './template-engine.js';
+export * from './template-tokens.js';

package/lib/template/index.js

@@ -0,0 +1,3 @@
+export * from './template-engine.js';
+export * from './template-tokens.js';
+//# sourceMappingURL=index.js.map

package/lib/template/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/template/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/lib/template/template-engine.d.ts

@@ -0,0 +1,3 @@
+export interface TemplateEngine {
+    render(templatePath: string, data: Record<string, unknown>): Promise<string>;
+}

package/lib/template/template-engine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=template-engine.js.map

package/lib/template/template-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-engine.js","sourceRoot":"","sources":["../../src/template/template-engine.ts"],"names":[],"mappings":""}

package/lib/template/template-tokens.d.ts

@@ -0,0 +1,2 @@
+import type { TemplateEngine } from '../template/index.js';
+export declare const TemplateEngineToken: import("@kurdel/ioc").InjectionToken<TemplateEngine>;

package/lib/template/template-tokens.js

@@ -0,0 +1,3 @@
+import { createToken } from '@kurdel/ioc';
+export const TemplateEngineToken = createToken('@kurdel/core/template/engine');
+//# sourceMappingURL=template-tokens.js.map

package/lib/template/template-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-tokens.js","sourceRoot":"","sources":["../../src/template/template-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAiB,8BAA8B,CAAC,CAAC"}

package/lib/tokens/index.d.ts

@@ -0,0 +1 @@
+export * from './tokens.js';

package/lib/tokens/index.js

@@ -0,0 +1,2 @@
+export * from './tokens.js';
+//# sourceMappingURL=index.js.map

package/lib/tokens/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/lib/tokens/tokens.d.ts

@@ -0,0 +1,12 @@
+export declare const TOKENS: {
+    TemplateEngineToken: import("@kurdel/ioc").InjectionToken<import("../template/index.js").TemplateEngine>;
+    OnStart: import("@kurdel/ioc").InjectionToken<import("../app/index.js").LifecycleHook[]>;
+    OnShutdown: import("@kurdel/ioc").InjectionToken<import("../app/index.js").LifecycleHook[]>;
+    ServerAdapter: import("@kurdel/ioc").InjectionToken<import("../http/index.js").ServerAdapter<import("@kurdel/common").HttpRequest, import("@kurdel/common").HttpResponse>>;
+    Router: import("@kurdel/ioc").InjectionToken<import("../http/index.js").Router>;
+    ControllerClasses: import("@kurdel/ioc").InjectionToken<import("../http/index.js").Controller<{}>[]>;
+    ControllerConfigs: import("@kurdel/ioc").InjectionToken<import("../http/index.js").ControllerConfig[]>;
+    MiddlewareRegistry: import("@kurdel/ioc").InjectionToken<import("../http/index.js").MiddlewareRegistry>;
+    ControllerResolver: import("@kurdel/ioc").InjectionToken<import("../http/index.js").ControllerResolver>;
+    ResponseRenderer: import("@kurdel/ioc").InjectionToken<import("../http/index.js").ResponseRenderer>;
+};

package/lib/tokens/tokens.js

@@ -0,0 +1,9 @@
+import { HTTP_TOKENS } from '../http/index.js';
+import { APP_TOKENS } from '../app/index.js';
+import { TemplateEngineToken } from '../template/index.js';
+export const TOKENS = {
+    ...HTTP_TOKENS,
+    ...APP_TOKENS,
+    TemplateEngineToken,
+};
+//# sourceMappingURL=tokens.js.map

package/lib/tokens/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/tokens/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,GAAG,WAAW;IACd,GAAG,UAAU;IACb,mBAAmB;CACpB,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@kurdel/core",
+  "version": "0.1.0-beta.1",
+  "description": "Core HTTP, routing, controller, and model abstractions for Kurdel",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js",
+    "./http": "./lib/http/index.js",
+    "./app": "./lib/app/index.js",
+    "./db": "./lib/db/index.js",
+    "./template": "./lib/template/index.js",
+    "./tokens": "./lib/tokens/index.js"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:ui": "vitest",
+    "test:watch": "vitest --watch",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf lib ../../.cache/tsconfig.core.build.tsbuildinfo",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:force": "npm run clean && tsc -p tsconfig.build.json --force && tsc-alias -p tsconfig.build.json"
+  },
+  "keywords": [
+    "kurdel",
+    "framework",
+    "http",
+    "routing",
+    "typescript"
+  ],
+  "author": "Andrii Sorokin",
+  "license": "MIT",
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ignorantic/kurdel.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/ignorantic/kurdel/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/ignorantic/kurdel/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "@types/supertest": "^6.0.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "rimraf": "^6.0.1",
+    "supertest": "^7.1.4",
+    "tsc-alias": "^1.8.16"
+  },
+  "dependencies": {
+    "@kurdel/common": "0.1.0-beta.1",
+    "@kurdel/db": "0.1.0-beta.1",
+    "@kurdel/ioc": "0.1.0-beta.1"
+  }
+}