@iskra-bun/web-kit 0.1.0

package/src/features/storage/base.ts

@@ -0,0 +1,112 @@
+import fs from "node:fs/promises";
+
+export interface StorageConfig {
+    adapter: "local" | "minio" | "s3";
+    basePath?: string; // For local storage
+    connection?: {
+        endpoint?: string;
+        accessKey?: string;
+        secretKey?: string;
+        bucket?: string;
+        region?: string;
+        useSSL?: boolean;
+    };
+}
+
+export interface StorageFile {
+    name: string;
+    path: string;
+    size: number;
+    mimeType?: string;
+    lastModified?: Date;
+    url?: string;
+}
+
+export interface PutOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    public?: boolean;
+}
+
+export interface StorageAdapter {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    put(path: string, data: Uint8Array | Buffer | ReadableStream, options?: PutOptions): Promise<StorageFile>;
+    get(path: string): Promise<Uint8Array | null>;
+    // getStream(path: string): Promise<ReadableStream | null>; 
+    // Node streams are different, sticking to Buffer/Uint8Array for simplicity or using generic Stream
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    list(prefix?: string): Promise<StorageFile[]>;
+    url(path: string, expiresIn?: number): Promise<string>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    isDirectory(path: string): Promise<boolean>;
+}
+
+export abstract class BaseStorageAdapter implements StorageAdapter {
+    protected connected = false;
+
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract put(path: string, data: Uint8Array | Buffer | ReadableStream, options?: PutOptions): Promise<StorageFile>;
+    abstract get(path: string): Promise<Uint8Array | null>;
+
+    abstract delete(path: string): Promise<void>;
+    abstract exists(path: string): Promise<boolean>;
+    abstract list(prefix?: string): Promise<StorageFile[]>;
+    abstract url(path: string, expiresIn?: number): Promise<string>;
+    abstract isDirectory(path: string): Promise<boolean>;
+
+    isConnected(): boolean {
+        return this.connected;
+    }
+
+    protected ensureConnected(): void {
+        if (!this.connected) {
+            throw new Error("Storage not connected. Call connect() first.");
+        }
+    }
+
+    async copy(from: string, to: string): Promise<void> {
+        const data = await this.get(from);
+        if (!data) {
+            throw new Error(`Source file not found: ${from}`);
+        }
+        await this.put(to, data);
+    }
+
+    async move(from: string, to: string): Promise<void> {
+        await this.copy(from, to);
+        await this.delete(from);
+    }
+
+    protected generateFileName(originalName: string): string {
+        const ext = originalName.split(".").pop();
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 15);
+        return `${timestamp}-${random}.${ext}`;
+    }
+
+    protected sanitizePath(path: string): string {
+        return path
+            .replace(/^\/+/, "")
+            .replace(/\/+/g, "/")
+            .replace(/\\/g, "/");
+    }
+
+    protected getMimeType(filename: string): string {
+        const ext = filename.split(".").pop()?.toLowerCase();
+        const mimeTypes: Record<string, string> = {
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            png: "image/png",
+            gif: "image/gif",
+            pdf: "application/pdf",
+            txt: "text/plain",
+            json: "application/json",
+            zip: "application/zip",
+        };
+        return mimeTypes[ext || ""] || "application/octet-stream";
+    }
+}

package/src/features/storage/index.ts

@@ -0,0 +1,53 @@
+import type { Feature } from "../../types";
+import type { Kernel } from "../../kernel";
+import type { StorageConfig } from "./base";
+import { BaseStorageAdapter } from "./base";
+import type { Context, Next } from "hono";
+import { LocalStorageAdapter } from "./adapters/local";
+
+export { BaseStorageAdapter, LocalStorageAdapter };
+export type { StorageConfig, StorageFile } from "./base";
+
+declare module "hono" {
+    interface ContextVariableMap {
+        storage: BaseStorageAdapter;
+    }
+}
+
+export class StorageFeature implements Feature {
+    name = "storage";
+    private adapter?: BaseStorageAdapter;
+
+    constructor(private config: StorageConfig) { }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        if (this.config.adapter === "local") {
+            this.adapter = new LocalStorageAdapter(this.config);
+        } else if (this.config.adapter === "s3" || this.config.adapter === "minio") {
+            const { S3StorageAdapter } = await import("./adapters/s3");
+            this.adapter = new S3StorageAdapter(this.config);
+        } else {
+            throw new Error(`Adapter ${this.config.adapter} not supported.`);
+        }
+
+        await this.adapter.connect();
+
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            c.set("storage", this.adapter!);
+            await next();
+        });
+
+        console.log(`✅ StorageFeature initialized - ${this.config.adapter}`);
+    }
+
+    async shutdown(): Promise<void> {
+        if (this.adapter) {
+            await this.adapter.disconnect();
+        }
+    }
+
+    getAdapter(): BaseStorageAdapter | undefined {
+        return this.adapter;
+    }
+}

package/src/features/tracing.ts

@@ -0,0 +1,49 @@
+import type { Feature } from "../types";
+import type { Kernel } from "../kernel";
+import { httpInstrumentationMiddleware } from "@hono/otel";
+
+export interface OtelTracingConfig {
+    serviceName: string;
+    serviceVersion?: string;
+    captureRequestHeaders?: string[];
+    captureResponseHeaders?: string[];
+    tracerProvider?: any;
+    meterProvider?: any;
+    tracer?: any;
+    spanNameFactory?: (c: any) => string;
+    getTime?: () => number;
+}
+
+export class OtelTracingFeature implements Feature {
+    name = "otel-tracing";
+    private config: OtelTracingConfig;
+
+    constructor(config: OtelTracingConfig) {
+        if (!config.serviceName) {
+            throw new Error("serviceName is required for OtelTracingFeature");
+        }
+        this.config = config;
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+
+        const instrumentationConfig: any = {
+            serviceName: this.config.serviceName,
+        };
+
+        if (this.config.serviceVersion) instrumentationConfig.serviceVersion = this.config.serviceVersion;
+        if (this.config.captureRequestHeaders) instrumentationConfig.captureRequestHeaders = this.config.captureRequestHeaders;
+        if (this.config.captureResponseHeaders) instrumentationConfig.captureResponseHeaders = this.config.captureResponseHeaders;
+        if (this.config.tracerProvider) instrumentationConfig.tracerProvider = this.config.tracerProvider;
+        if (this.config.meterProvider) instrumentationConfig.meterProvider = this.config.meterProvider;
+        if (this.config.tracer) instrumentationConfig.tracer = this.config.tracer;
+        if (this.config.spanNameFactory) instrumentationConfig.spanNameFactory = this.config.spanNameFactory;
+        if (this.config.getTime) instrumentationConfig.getTime = this.config.getTime;
+
+        // Register Otel middleware
+        app.use("*", httpInstrumentationMiddleware(instrumentationConfig));
+
+        console.log("✅ OpenTelemetry tracing feature initialized");
+    }
+}

package/src/features/upload/helper.ts

@@ -0,0 +1,85 @@
+import type { StorageFeature } from "../storage";
+import type { BaseStorageAdapter, PutOptions } from "../storage/base";
+
+export interface UploadOptions {
+    metadata?: Record<string, string>;
+    contentType?: string;
+}
+
+export interface UploadResult {
+    path: string;
+    filename: string;
+    size: number;
+    uploadedAt: Date;
+}
+
+export class UploadHelper {
+    private basePath: string;
+
+    constructor(private storage: BaseStorageAdapter, private projectName: string) {
+        this.basePath = `${projectName}/`;
+    }
+
+    getBasePath(): string {
+        return this.basePath;
+    }
+
+    private buildPath(filename: string, subfolder?: string): string {
+        if (subfolder) {
+            const normalized = subfolder.replace(/^\/+|\/+$/g, "");
+            return `${this.basePath}${normalized}/${filename}`;
+        }
+        return `${this.basePath}${filename}`;
+    }
+
+    async upload(filename: string, data: Uint8Array | string, subfolder?: string, options?: UploadOptions): Promise<UploadResult> {
+        const fullPath = this.buildPath(filename, subfolder);
+        const fileData = typeof data === "string" ? new TextEncoder().encode(data) : data;
+
+        const putOptions: PutOptions | undefined = options ? {
+            contentType: options.contentType,
+            metadata: options.metadata
+        } : undefined;
+
+        await this.storage.put(fullPath, fileData, putOptions);
+
+        return {
+            path: fullPath,
+            filename,
+            size: fileData.length,
+            uploadedAt: new Date()
+        };
+    }
+
+    // uploadFromRequest: Not implementing raw request reading here to avoid Node/Bun specific request stream issues unless necessary
+    // or implementing simplified Version
+    async uploadFromRequest(request: Request, fieldName: string, subfolder?: string, options?: UploadOptions): Promise<UploadResult> {
+        const formData = await request.formData();
+        const file = formData.get(fieldName);
+        if (!file || !(file instanceof File)) throw new Error(`No file found in field: ${fieldName}`);
+
+        const data = new Uint8Array(await file.arrayBuffer());
+        const opts = { ...options, contentType: options?.contentType || file.type };
+        return this.upload(file.name, data, subfolder, opts);
+    }
+
+    async list(subfolder?: string) {
+        const prefix = subfolder ? `${this.basePath}${subfolder.replace(/^\/+|\/+$/g, "")}/` : this.basePath;
+        return await this.storage.list(prefix);
+    }
+
+    async get(filename: string, subfolder?: string) {
+        const fullPath = this.buildPath(filename, subfolder);
+        return await this.storage.get(fullPath);
+    }
+
+    async delete(filename: string, subfolder?: string) {
+        const fullPath = this.buildPath(filename, subfolder);
+        await this.storage.delete(fullPath);
+    }
+
+    async getUrl(filename: string, subfolder?: string, expiresIn?: number) {
+        const fullPath = this.buildPath(filename, subfolder);
+        return await this.storage.url(fullPath, expiresIn);
+    }
+}

package/src/features/upload/index.ts

@@ -0,0 +1,140 @@
+import type { Feature, UploadConfig } from "../../types";
+import type { Kernel } from "../../kernel";
+import type { Hono, Context, Next } from "hono";
+import { UploadHelper } from "./helper";
+import type { StorageFeature } from "../storage";
+
+declare module "hono" {
+    interface ContextVariableMap {
+        upload: UploadHelper;
+    }
+}
+
+export class UploadFeature implements Feature {
+    name = "upload";
+    dependencies = ["storage"];
+    private helper?: UploadHelper;
+    private config: Required<UploadConfig>;
+
+    constructor(config: UploadConfig) {
+        this.config = {
+            projectName: config.projectName,
+            maxFileSize: config.maxFileSize || 10 * 1024 * 1024,
+            allowedExtensions: config.allowedExtensions || [],
+            exposeRoutes: config.exposeRoutes || false,
+            routePrefix: config.routePrefix || "/upload"
+        };
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const storageFeature = kernel.getFeature("storage") as unknown as StorageFeature;
+        if (!storageFeature) throw new Error("Upload feature requires storage feature");
+        const storage = storageFeature.getAdapter();
+        if (!storage) throw new Error("Storage adapter not ready");
+
+        this.helper = new UploadHelper(storage, this.config.projectName);
+
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            c.set("upload", this.helper!);
+            await next();
+        });
+
+        console.log(`✅ Upload feature initialized: ${this.config.projectName}`);
+    }
+
+    routes(app: Hono) {
+        if (!this.config.exposeRoutes) return;
+
+        const prefix = this.config.routePrefix;
+
+        // POST — upload a file
+        app.post(`${prefix}`, async (c) => {
+            const upload = c.get("upload");
+            try {
+                const subfolder = c.req.query("subfolder");
+                const formData = await c.req.formData();
+                const file = formData.get("file");
+                if (!file || !(file instanceof File)) return c.json({ error: "No file" }, 400);
+
+                if (file.size > this.config.maxFileSize) return c.json({ error: "File too large" }, 400);
+                if (this.config.allowedExtensions.length > 0) {
+                    if (!this.config.allowedExtensions.some(e => file.name.toLowerCase().endsWith(e))) {
+                        return c.json({ error: "Invalid extension" }, 400);
+                    }
+                }
+
+                const data = new Uint8Array(await file.arrayBuffer());
+                const result = await upload.upload(file.name, data, subfolder, { contentType: file.type });
+                return c.json({ success: true, ...result });
+
+            } catch (e: any) {
+                return c.json({ error: e.message }, 500);
+            }
+        });
+
+        // GET — list files
+        app.get(`${prefix}`, async (c) => {
+            const upload = c.get("upload");
+            try {
+                const subfolder = c.req.query("subfolder");
+                const files = await upload.list(subfolder);
+                return c.json({ success: true, files });
+            } catch (e: any) {
+                return c.json({ error: e.message }, 500);
+            }
+        });
+
+        // GET — download a file
+        app.get(`${prefix}/*`, async (c) => {
+            const upload = c.get("upload");
+            try {
+                const filePath = c.req.path.replace(`${prefix}/`, "");
+                const segments = filePath.split("/");
+                const filename = segments.pop() || "";
+                const subfolder = segments.length > 0 ? segments.join("/") : undefined;
+
+                const data = await upload.get(filename, subfolder);
+                if (!data) {
+                    return c.json({ error: "File not found" }, 404);
+                }
+
+                const ext = filename.split(".").pop()?.toLowerCase() || "";
+                const mimeTypes: Record<string, string> = {
+                    jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+                    pdf: "application/pdf", txt: "text/plain", json: "application/json", zip: "application/zip",
+                };
+                const contentType = mimeTypes[ext] || "application/octet-stream";
+
+                const body = new Uint8Array(data.length);
+                body.set(data);
+
+                return new Response(body, {
+                    headers: {
+                        "Content-Type": contentType,
+                        "Content-Disposition": `inline; filename="${filename}"`,
+                        "Content-Length": String(data.length),
+                    },
+                });
+            } catch (e: any) {
+                return c.json({ error: e.message }, 500);
+            }
+        });
+
+        // DELETE — delete a file
+        app.delete(`${prefix}/*`, async (c) => {
+            const upload = c.get("upload");
+            try {
+                const filePath = c.req.path.replace(`${prefix}/`, "");
+                const segments = filePath.split("/");
+                const filename = segments.pop() || "";
+                const subfolder = segments.length > 0 ? segments.join("/") : undefined;
+
+                await upload.delete(filename, subfolder);
+                return new Response(null, { status: 204 });
+            } catch (e: any) {
+                return c.json({ error: e.message }, 500);
+            }
+        });
+    }
+}

package/src/features/validation.ts

@@ -0,0 +1,105 @@
+import type { Feature } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next, Hono, Handler } from "hono";
+import { z } from "zod";
+import { ErrorCodes, errorResponse } from "../responses";
+
+// Extend Hono Context to include valid() method
+declare module "hono" {
+    interface Context {
+        valid<T = any>(): T;
+    }
+}
+
+// Extend Hono to include *Validated methods if possible, 
+// or simpler: just provide middleware factory.
+// Monkey patching Hono class is tricky in strict TS if types aren't augmented in global/module scope correctly.
+// But we can try to follow kollective's approach if we augment module "hono".
+
+export interface ValidationSchema {
+    params?: z.ZodSchema<any>;
+    query?: z.ZodSchema<any>;
+    body?: z.ZodSchema<any>;
+}
+
+export interface ValidationOptions {
+    logErrors?: boolean;
+    status?: number;
+}
+
+function createValidationMiddleware(schema: ValidationSchema, options: ValidationOptions = {}) {
+    const { logErrors = true, status = 400 } = options;
+
+    return async (c: Context, next: Next) => {
+        try {
+            const validated: Record<string, any> = {};
+
+            if (schema.params) {
+                const parsed = schema.params.safeParse(c.req.param());
+                if (!parsed.success) {
+                    return c.json(errorResponse("Invalid route params", ErrorCodes.VALIDATION_ERROR, parsed.error.flatten()), status as any);
+                }
+                validated.params = parsed.data;
+            }
+
+            if (schema.query) {
+                const parsed = schema.query.safeParse(c.req.query());
+                if (!parsed.success) {
+                    return c.json(errorResponse("Invalid query params", ErrorCodes.VALIDATION_ERROR, parsed.error.flatten()), status as any);
+                }
+                validated.query = parsed.data;
+            }
+
+            if (schema.body) {
+                let data: unknown = {};
+                const contentType = c.req.header("content-type") || "";
+                if (contentType.includes("application/json")) {
+                    data = await c.req.json().catch(() => ({}));
+                } else if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
+                    data = await c.req.parseBody();
+                }
+
+                const parsed = schema.body.safeParse(data);
+                if (!parsed.success) {
+                    return c.json(errorResponse("Invalid body", ErrorCodes.VALIDATION_ERROR, parsed.error.flatten()), status as any);
+                }
+                validated.body = parsed.data;
+            }
+
+            // Attach to context
+            (c as any).valid = () => validated;
+
+            await next();
+        } catch (err) {
+            if (logErrors) console.error("Validation error:", err);
+            return c.json(errorResponse("Validation middleware failed", ErrorCodes.INTERNAL_ERROR), 500);
+        }
+    };
+}
+
+// Helper to monkey patch Hono
+function extendHonoWithValidation(app: Hono) {
+    const methods = ["get", "post", "put", "delete"] as const;
+    for (const method of methods) {
+        (app as any)[`${method}Validated`] = function (path: string, schema: ValidationSchema, handler: Handler, options?: ValidationOptions) {
+            const middleware = createValidationMiddleware(schema, options);
+            (this as any)[method](path, middleware, handler);
+            return this;
+        };
+    }
+}
+
+export class ValidationFeature implements Feature {
+    name = "validation";
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+        extendHonoWithValidation(app);
+
+        // Add context helper if not already present via middleware factory logic
+        // The middleware factory adds .valid() to the SPECIFIC request context
+        console.log("✅ Validation feature initialized");
+    }
+}
+
+export { createValidationMiddleware };

package/src/index.ts

@@ -0,0 +1,29 @@
+export * from "./types";
+export * from "./kernel";
+export * from "./driver";
+export * from "./server";
+export * from "./router";
+
+// Features
+export * from "./features/cors";
+export * from "./features/error-handler";
+export * from "./features/health";
+export * from "./features/logger";
+export * from "./features/request-id";
+export * from "./features/storage";
+export * from "./features/db";
+export * from "./features/cache";
+export * from "./features/session";
+export * from "./features/auth";
+export * from "./features/rate-limit";
+export * from "./features/permissions";
+export * from "./features/api-key";
+export * from "./features/csrf";
+export * from "./features/validation";
+export * from "./features/json-schema-validation";
+export * from "./features/openapi";
+export * from "./features/upload";
+export * from "./features/tracing";
+export * from "./features/email";
+export * from "./responses";
+export * from "./errors";