bun-platform-kit 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# Bun Platform Kit
+
+A TypeScript framework for Bun, dev-friendly and enterprise-ready. Organize APIs with modules, services, and decorated controllers, ship essential middleware out of the box, and keep end-to-end typing without friction.
+
+## Features
+
+- 🧩 **Modular architecture**: add, replace, or disable modules without coupling to the core
+- 🚀 **Background services**: start processes and workers with `BaseServerService`
+- 🧰 **Standard preset**: CORS, security headers, in-memory rate limit, uploads, and request context
+- 🧭 **Clear priorities**: deterministic module initialization order
+- 🔒 **Safe defaults**: reasonable headers and limits out of the box
+- 🧪 **Simple testing**: helper for decorated apps without repeated bootstrap
+- 🛡️ **Real type safety**: strong typing on request, response, and decorators
+- 🎯 **Clean decorators**: declarative, easy-to-maintain routes
+
+## Benefits
+
+- ⚡ **Fast time-to-first-endpoint** with the standard preset
+- 🤝 **Team consistency** with clear module/service patterns
+- 🧱 **Scalable**: add pieces without rewriting the server
+- 🔍 **Basic observability** with requestId and per-request context
+- ✅ **Reliable testing** with bootstrap helpers for tests
+
+## Installation
+
+```bash
+bun add bun-platform-kit
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Core Concepts](docs/core-concepts.md)
+- [Modules](docs/modules.md)
+- [Using Decorators](docs/decorators.md)
+- [Services](docs/services.md)
+- [Testing Helpers](docs/testing.md)
+- [API Reference](docs/api-reference.md)
+- [Examples](docs/examples.md)
+
+## File uploads
+
+With `BunKitStandardServer`, uploads are enabled by default. If you use `BunKitServer` directly or disable the module, you need to register `FileUploadModule`. Configure limits and allowlists through the module:
+
+```typescript
+import { FileUploadModule } from "bun-platform-kit";
+
+const fileUpload = new FileUploadModule({
+  maxBodyBytes: 10 * 1024 * 1024,
+  maxFileBytes: 10 * 1024 * 1024,
+  maxFiles: 10,
+  allowedMimeTypes: ["image/*", "application/pdf"],
+});
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Conventional Commits
+
+We use Conventional Commits to automatically generate releases:
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation
+- `style:` - Format, spaces, etc.
+- `refactor:` - Code refactoring
+- `test:` - Add tests
+- `chore:` - Maintenance tasks
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Author
+
+Angel Bejarano - angel.bejarano@jaspesoft.com

package/dist/BunKitServer.d.ts

@@ -0,0 +1,31 @@
+import { BaseServerModule, BaseServerService } from "./abstract";
+import { ServerAdapter, ServerApp, ServerInstance } from "./abstract";
+export interface BunKitServerOptions {
+    adapter?: ServerAdapter;
+}
+export declare class BunKitServer {
+    private readonly app;
+    private readonly port;
+    private server?;
+    private modules;
+    private services;
+    private readonly adapter;
+    private readonly runtime;
+    constructor(port: number, options?: BunKitServerOptions);
+    removeModule(moduleName: string): BunKitServer;
+    addModule(module: BaseServerModule): BunKitServer;
+    addModules(modules: BaseServerModule[]): BunKitServer;
+    addService(service: BaseServerService): BunKitServer;
+    addServices(services: BaseServerService[]): BunKitServer;
+    getApp(): ServerApp;
+    getServer(): ServerInstance | undefined;
+    getHttpServer(): ServerInstance | undefined;
+    initialize(): Promise<void>;
+    start(): Promise<void>;
+    gracefulShutdown(): Promise<void>;
+    getModule<T extends BaseServerModule>(moduleClass: new (...args: any[]) => T): T | undefined;
+    hasModule(moduleClass: new (...args: any[]) => any): boolean;
+    private initializeServices;
+    private initializeServerModules;
+    private setupGracefulShutdown;
+}

package/dist/BunKitServer.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BunKitServer = void 0;
+const adapters_1 = require("./adapters");
+class BunKitServer {
+    constructor(port, options) {
+        this.modules = [];
+        this.services = [];
+        this.port = port;
+        this.adapter = options?.adapter ?? new adapters_1.BunAdapter();
+        this.runtime = this.adapter.runtime;
+        this.app = this.adapter.createApp();
+        this.adapter.configure(this.app, port);
+    }
+    removeModule(moduleName) {
+        this.modules = this.modules.filter((m) => m.getModuleName() !== moduleName);
+        return this;
+    }
+    addModule(module) {
+        const existingModuleIndex = this.modules.findIndex((m) => m.getModuleName() === module.getModuleName());
+        if (existingModuleIndex !== -1) {
+            // Replace existing module
+            this.modules[existingModuleIndex] = module;
+        }
+        else {
+            // Add new module
+            this.modules.push(module);
+        }
+        return this;
+    }
+    addModules(modules) {
+        for (const module of modules) {
+            const existingModuleIndex = this.modules.findIndex((m) => m.getModuleName() === module.getModuleName());
+            if (existingModuleIndex !== -1) {
+                // Replace existing module
+                this.modules[existingModuleIndex] = module;
+            }
+            else {
+                // Add new module
+                this.modules.push(module);
+            }
+        }
+        return this;
+    }
+    addService(service) {
+        this.services.push(service);
+        return this;
+    }
+    addServices(services) {
+        this.services.push(...services);
+        return this;
+    }
+    getApp() {
+        return this.app;
+    }
+    getServer() {
+        return this.server;
+    }
+    getHttpServer() {
+        return this.server;
+    }
+    async initialize() {
+        await this.initializeServerModules();
+    }
+    async start() {
+        await this.initializeServerModules();
+        return new Promise((resolve) => {
+            this.server = this.adapter.listen(this.app, this.port, () => {
+                console.log(`Server running on port ${this.port}`);
+                this.setupGracefulShutdown();
+                resolve();
+            });
+            this.initializeServices(this.server);
+        });
+    }
+    async gracefulShutdown() {
+        try {
+            console.log("Starting graceful shutdown...");
+            // Execute module shutdown in reverse order
+            const reversedModules = [...this.modules].reverse();
+            for (const module of reversedModules) {
+                if (module.shutdown) {
+                    try {
+                        console.log(`Shutting down module: ${module.getModuleName()}`);
+                        await module.shutdown();
+                        console.log(`Module shutdown completed: ${module.getModuleName()}`);
+                    }
+                    catch (error) {
+                        console.error(`Error shutting down module ${module.getModuleName()}:`, error);
+                    }
+                }
+            }
+            // Stop services in reverse order
+            const reversedServices = [...this.services].reverse();
+            for (const service of reversedServices) {
+                if (service.stop) {
+                    try {
+                        console.log(`Stopping service: ${service.name}`);
+                        await service.stop();
+                        console.log(`Service stopped: ${service.name}`);
+                    }
+                    catch (error) {
+                        console.error(`Error stopping service ${service.name}:`, error);
+                    }
+                }
+            }
+            // Close HTTP server
+            if (this.server) {
+                console.log("Closing server...");
+                await new Promise((resolve) => {
+                    this.server.close(() => resolve());
+                });
+                console.log("Server closed");
+            }
+            console.log("Graceful shutdown completed. Exiting...");
+            process.exit(0);
+        }
+        catch (error) {
+            console.error("Error during graceful shutdown:", error);
+            process.exit(1);
+        }
+    }
+    // Convenience methods to access specific modules
+    getModule(moduleClass) {
+        return this.modules.find((m) => m instanceof moduleClass);
+    }
+    hasModule(moduleClass) {
+        return this.modules.some((m) => m instanceof moduleClass);
+    }
+    async initializeServices(server) {
+        console.log("Starting services...");
+        for (const service of this.services) {
+            try {
+                await service.start(server);
+                console.log(`Service started: ${service.name}`);
+            }
+            catch (error) {
+                console.error(`Failed to start service ${service.name}:`, error);
+                throw error;
+            }
+        }
+        console.log("All services started successfully");
+    }
+    async initializeServerModules() {
+        // Sort modules by priority (lower number = higher priority)
+        this.modules.sort((a, b) => (a.priority || 0) - (b.priority || 0));
+        console.log("Initializing server modules in priority order:");
+        const context = {
+            runtime: this.runtime,
+            adapter: this.adapter,
+        };
+        for (const module of this.modules) {
+            try {
+                await module.init(this.app, context);
+                console.log(`Module initialized: ${module.getModuleName()}`);
+            }
+            catch (error) {
+                console.error(`Failed to initialize module ${module.getModuleName()}:`, error);
+                throw error;
+            }
+        }
+        console.log("All modules initialized successfully");
+    }
+    setupGracefulShutdown() {
+        const shutdown = async (signal) => {
+            console.log(`${signal} signal received. Shutting down application...`);
+            await this.gracefulShutdown();
+        };
+        process.on("SIGINT", () => shutdown("SIGINT"));
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+    }
+}
+exports.BunKitServer = BunKitServer;

package/dist/BunKitStandardServer.d.ts

@@ -0,0 +1,18 @@
+import { BunKitServer } from "./BunKitServer";
+import { ControllersModule } from "./modules";
+import { BaseServerModule, BaseServerService, ServerAdapter } from "./abstract";
+export interface BunKitStandardServerOptions {
+    adapter?: ServerAdapter;
+    modules?: {
+        cors?: BaseServerModule | false;
+        security?: BaseServerModule | false;
+        rateLimit?: BaseServerModule | false;
+        fileUpload?: BaseServerModule | false;
+        requestContext?: BaseServerModule | false;
+        extra?: BaseServerModule[];
+    };
+    services?: BaseServerService[];
+}
+export declare function BunKitStandardServer(port: number, module: ControllersModule, services?: BaseServerService[]): BunKitServer;
+export declare function BunKitStandardServer(port: number, module: ControllersModule, services: BaseServerService[], options: BunKitStandardServerOptions): BunKitServer;
+export declare function BunKitStandardServer(port: number, module: ControllersModule, options: BunKitStandardServerOptions): BunKitServer;

package/dist/BunKitStandardServer.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BunKitStandardServer = BunKitStandardServer;
+const BunKitServer_1 = require("./BunKitServer");
+const modules_1 = require("./modules");
+function BunKitStandardServer(port, arg2, arg3, arg4) {
+    let controllersModule;
+    let services;
+    let options;
+    controllersModule = arg2;
+    const addServices = (value) => {
+        if (!value?.length) {
+            return;
+        }
+        services = [...(services ?? []), ...value];
+    };
+    const processOptionalArg = (value) => {
+        if (!value) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            addServices(value);
+            return;
+        }
+        options = value;
+    };
+    processOptionalArg(arg3);
+    processOptionalArg(arg4);
+    addServices(options?.services);
+    const modulesToRegister = [controllersModule];
+    const preset = options?.modules;
+    const registerModule = (factory, override) => {
+        if (override === false) {
+            return;
+        }
+        modulesToRegister.push(override ?? factory());
+    };
+    registerModule(() => new modules_1.CorsModule(), preset?.cors);
+    registerModule(() => new modules_1.SecurityModule(), preset?.security);
+    registerModule(() => new modules_1.RateLimitModule(), preset?.rateLimit);
+    registerModule(() => new modules_1.FileUploadModule(), preset?.fileUpload);
+    registerModule(() => new modules_1.RequestContextModule(), preset?.requestContext);
+    if (preset?.extra?.length) {
+        modulesToRegister.push(...preset.extra);
+    }
+    const server = new BunKitServer_1.BunKitServer(port, {
+        adapter: options?.adapter,
+    }).addModules(modulesToRegister);
+    if (services) {
+        server.addServices(services);
+    }
+    return server;
+}

package/dist/abstract/ServerModule.d.ts

@@ -0,0 +1,7 @@
+import { ServerApp, ServerContext } from "./ServerTypes";
+export declare abstract class BaseServerModule {
+    priority: number;
+    abstract getModuleName(): string;
+    abstract init(app: ServerApp, context?: ServerContext): Promise<void> | void;
+    shutdown(): Promise<void>;
+}

package/dist/abstract/ServerModule.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseServerModule = void 0;
+class BaseServerModule {
+    constructor() {
+        this.priority = 0;
+    }
+    async shutdown() {
+        // Default empty shutdown
+    }
+}
+exports.BaseServerModule = BaseServerModule;

package/dist/abstract/ServerService.d.ts

@@ -0,0 +1,6 @@
+import { ServerInstance } from "./ServerTypes";
+export declare abstract class BaseServerService {
+    abstract name: string;
+    abstract start(server: ServerInstance): Promise<void> | void;
+    stop(): Promise<void>;
+}

package/dist/abstract/ServerService.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseServerService = void 0;
+class BaseServerService {
+    async stop() {
+        // Default empty stop
+    }
+}
+exports.BaseServerService = BaseServerService;

package/dist/abstract/ServerTypes.d.ts

@@ -0,0 +1,78 @@
+export declare enum ServerRuntime {
+    Bun = "bun"
+}
+export type NextFunction = (err?: unknown) => void;
+export type ServerHandler = (req: any, res: any, next: NextFunction) => any;
+export interface ServerRequest {
+    method: string;
+    path: string;
+    originalUrl?: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    files?: ServerFiles;
+    cookies?: Record<string, string>;
+    ip?: string;
+    requestId?: string;
+    raw?: unknown;
+}
+export interface ServerResponse {
+    status(code: number): this;
+    json(body: unknown): void | Promise<void>;
+    send(body: unknown): void | Promise<void>;
+    set(name: string, value: string): this;
+    header(name: string, value: string): this;
+    setHeader?(name: string, value: string): this;
+    cookie?(name: string, value: string, options?: {
+        maxAge?: number;
+        domain?: string;
+        path?: string;
+        expires?: Date;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: "lax" | "strict" | "none";
+    }): this;
+    download?(path: string, filename?: string, callback?: (err?: unknown) => void): this;
+    end(body?: unknown): void | Promise<void>;
+}
+export type BunMultipartFile = {
+    name: string;
+    size: number;
+    type: string;
+    slice?: (start?: number, end?: number) => {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text?: () => Promise<string>;
+    lastModified?: number;
+};
+export type ServerFile = BunMultipartFile;
+export type ServerFiles = Record<string, ServerFile | ServerFile[]>;
+export type ServerHandlerInput = ServerHandler | ServerHandler[] | ServerRouter;
+export interface ServerRouter {
+    use(pathOrHandler: string | ServerHandlerInput, ...handlers: ServerHandlerInput[]): void;
+    get(path: string, ...handlers: ServerHandler[]): void;
+    post(path: string, ...handlers: ServerHandler[]): void;
+    put(path: string, ...handlers: ServerHandler[]): void;
+    delete(path: string, ...handlers: ServerHandler[]): void;
+    patch(path: string, ...handlers: ServerHandler[]): void;
+}
+export interface ServerApp extends ServerRouter {
+    set?(key: string, value: unknown): void;
+    listen?(port: number, callback?: () => void): unknown;
+}
+export type ServerInstance = {
+    close(callback?: () => void): void;
+};
+export interface ServerAdapter {
+    runtime: ServerRuntime;
+    createApp(): ServerApp;
+    createRouter(): ServerRouter;
+    configure(app: ServerApp, port: number): void;
+    listen(app: ServerApp, port: number, onListen: () => void): ServerInstance;
+}
+export interface ServerContext {
+    runtime: ServerRuntime;
+    adapter: ServerAdapter;
+}

package/dist/abstract/ServerTypes.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerRuntime = void 0;
+var ServerRuntime;
+(function (ServerRuntime) {
+    ServerRuntime["Bun"] = "bun";
+})(ServerRuntime || (exports.ServerRuntime = ServerRuntime = {}));

package/dist/abstract/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./ServerService";
+export * from "./ServerModule";
+export * from "./ServerTypes";

package/dist/abstract/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ServerService"), exports);
+__exportStar(require("./ServerModule"), exports);
+__exportStar(require("./ServerTypes"), exports);

package/dist/adapters/BunAdapter.d.ts

@@ -0,0 +1,12 @@
+import { ServerAdapter, ServerApp, ServerInstance, ServerRequest, ServerRouter, ServerRuntime, BunMultipartFile } from "../abstract/ServerTypes";
+export declare class BunAdapter implements ServerAdapter {
+    runtime: ServerRuntime;
+    createApp(): ServerApp;
+    createRouter(): ServerRouter;
+    configure(app: ServerApp, _port: number): void;
+    listen(app: ServerApp, port: number, onListen: () => void): ServerInstance;
+}
+type MultipartFile = BunMultipartFile;
+export declare function getFiles(req: ServerRequest, field: string): MultipartFile[];
+export declare function getFile(req: ServerRequest, field: string): MultipartFile | undefined;
+export {};