riser-bob 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zen Allaham — RiserBob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+<h1>
+  <img src="https://res.cloudinary.com/dgagbheuj/image/upload/v1792601028/riserbob/covers/keps4sy2lumzdx0ho23i.png" alt="RiserBob Logo" width="48" height="48" align="absmiddle" />
+  RiserBob
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A fun and fast framework powered by Bun and TypeScript, bringing simplicity and a fresh perspective to backend development.
+Stay in the Sponge Zone!
+
+> RiserBob is distributed under the [MIT License](#license).
+
+![RiserBob](https://res.cloudinary.com/dgagbheuj/image/upload/v1792927501/qlflwqvq6xqgxnbn0puk.png)
+
+## Features
+
+- **Modular Structure** — Clean, reusable modules that keep your codebase easy to maintain.
+- **Ready-to-Use Middleware** — Protect routes and handle common request workflows out of the box.
+- **Blazing-Fast Performance** — Built for Bun and TypeScript, with a lightweight HTTP core.
+- **Built-in Validation** — Validate incoming data with a simple, developer-friendly API.
+- **Integrated CLI** — Generate whole modules in seconds.
+- **Fun Sponge Zone** — Playful, SpongeBob-inspired messages and errors that make debugging enjoyable.
+
+## Installation
+
+Requires [Bun](https://bun.sh) 1.3 or newer. There are two ways to start.
+
+### 1. Starter template (recommended)
+```bash
+bun create riser-bob my-app
+```
+
+The best choice if you want a ready-made, organized template to start your project with. It creates `src/index.ts`:
+
+```ts
+import { RiserBob } from "riser-bob";
+import { UsersModule } from "./modules/users/users.module";
+
+async function bootstrap() {
+  const bob = new RiserBob();
+  bob.spongGet("/", async (spongReq, spongRes) => {
+    return spongRes.json({
+      message: "Welcome to Bikini Bottom! 🍍",
+    });
+  });
+  new UsersModule().register(bob);
+  bob.spongListen(4000, () => {
+    console.log("🧽 RiserBob is running at http://localhost:4000 🍍");
+  });
+}
+
+bootstrap().catch((error: unknown) => {
+  console.error("[RiserBob] Failed to start application:", error);
+  process.exit(1);
+});
+```
+
+Then the terminal shows:
+
+```text
+  🧽 RiserBob — Project created successfully!
+  📁 Location: /path/to/my-app
+
+  Get started:
+    $ cd "my-app"
+    $ bun install
+    $ bun run dev
+  🍍 Happy coding in the Sponge Zone!
+```
+
+### 2. Start from scratch
+RiserBob doesn't force anything on you. Run `bun init`, then `bun add riser-bob`. Just remember that you'll need to build the server entry file yourself (like the one above).
+
+## Simple API, Powerful Structure
+
+Every feature is a module of three focused files: a **controller** (the logic), a **router** (paths mapped to handlers) and a **module** that wires them together, so one call registers the whole feature: `new UsersModule().register(bob)`.
+
+## CLI
+
+Generate a complete module (`users.controller.ts`, `users.route.ts`, `users.module.ts`) with one command:
+
+```bash
+bun run riser-bob g module users   # `generate` also works
+```
+## Learn more
+
+Docs and examples: **[riserbob.vercel.app](https://riserbob.vercel.app)**. Contributions are welcome ([CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)); report vulnerabilities privately ([SECURITY.md](SECURITY.md)).
+
+## License
+RiserBob is released under the **MIT License**. See [LICENSE](LICENSE). Copyright (c) 2026 Zen Allaham — RiserBob
+
+<p align="center">
+  <img
+    src="https://res.cloudinary.com/dgagbheuj/image/upload/v1792769341/ob3ejwt32h6dtfhxg1kh.png"
+    alt="RiserBob — Build APIs. Stay in the Sponge Zone."
+    width="100%"
+  />
+</p>

package/dist/application/riser-bob.d.ts

@@ -0,0 +1,24 @@
+import type { SpongHandler } from '../types/spong-handler';
+import type { SpongRequest } from '../types/spong-request';
+import type { SpongMiddleware } from '../types/spong-middleware';
+import type { RiserBobOptions } from '../types/riser-bob-options';
+import { Server as SocketIOServer } from 'socket.io';
+import type { ServerOptions } from 'socket.io';
+export declare class RiserBob {
+    private readonly router;
+    private readonly middlewares;
+    private readonly errorMessages;
+    private socketIO?;
+    constructor(options?: RiserBobOptions);
+    private register;
+    spongGet(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongPost(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongPut(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongPatch(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongDelete(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongHead(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongOptions(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
+    spongUse(middleware: SpongMiddleware<SpongRequest>): this;
+    spongSocketIO(options?: Partial<ServerOptions>): SocketIOServer;
+    spongListen(port?: number, callback?: () => void): Bun.Server<import("@socket.io/bun-engine").WebSocketData>;
+}

package/dist/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env bun
+// @bun
+import{mkdir as m,writeFile as y,unlink as R}from"fs/promises";import s from"path";function g(o){return o.split(/[-_\s]+/).filter(Boolean).map((e)=>e[0].toUpperCase()+e.slice(1).toLowerCase()).join("")}function C(o){return o.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase().replace(/[_\s]+/g,"-")}function x(o){if(o.endsWith("ies")&&o.length>3)return`${o.slice(0,-3)}y`;if(o.endsWith("s")&&!o.endsWith("ss"))return o.slice(0,-1);return o}function v(o){return/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(o)}async function f(o){if(!v(o))throw Error('Invalid module name. Use letters, numbers, "-" or "_", starting with a letter.');let e=C(o),r=g(e),p=x(e),i=g(p),a=s.resolve(process.cwd(),"src","modules",e),c={[`${e}.controller.ts`]:`import type { SpongHandler } from "riser-bob";
+
+export class ${r}Controller {
+  readonly create: SpongHandler = async (spongReq, spongRes) => {
+    // TODO: Implement creation logic.
+  };
+
+  readonly findAll: SpongHandler = async (spongReq, spongRes) => {
+    // TODO: Implement fetching all records.
+  };
+
+  readonly findOne: SpongHandler = async (spongReq, spongRes) => {
+    // TODO: Implement fetching a record by ID.
+  };
+
+  readonly update: SpongHandler = async (spongReq, spongRes) => {
+    // TODO: Implement updating a record.
+  };
+
+  readonly delete: SpongHandler = async (spongReq, spongRes) => {
+    // TODO: Implement deleting a record.
+  };
+
+  verifyToken(token: string) {
+    // TODO: Implement token verification.
+    return null;
+  }
+}
+`,[`${e}.route.ts`]:`import type { RiserBob } from "riser-bob";
+import { AuthMiddleware } from "riser-bob";
+import { ${r}Controller } from "./${e}.controller";
+
+export class ${r}Router {
+  constructor(
+    private readonly bob: RiserBob,
+    private readonly controller: ${r}Controller,
+    private readonly authMiddleware: AuthMiddleware,
+  ) {}
+
+  register(): void {
+    // Public routes
+    this.bob.spongGet("/api/${e}", this.controller.findAll);
+    this.bob.spongGet("/api/${e}/:id", this.controller.findOne);
+
+    // Protected routes
+	this.bob.spongPost("/api/${e}", 
+	this.controller.create, 
+	this.authMiddleware.middleware,
+	);
+
+    this.bob.spongPut(
+      "/api/${e}/:id",
+      this.controller.update,
+      this.authMiddleware.middleware,
+    );
+
+    this.bob.spongDelete(
+      "/api/${e}/:id",
+      this.controller.delete,
+      this.authMiddleware.middleware,
+    );
+  }
+}
+`,[`${e}.module.ts`]:`import type { RiserBob } from "riser-bob";
+import { AuthMiddleware } from "riser-bob";
+import { ${r}Controller } from "./${e}.controller";
+import { ${r}Router } from "./${e}.route";
+
+export class ${r}Module {
+  register(bob: RiserBob): void {
+    const controller = new ${r}Controller();
+
+    const authMiddleware = new AuthMiddleware((token) =>
+      controller.verifyToken(token),
+    );
+
+    const router = new ${r}Router(
+      bob,
+      controller,
+      authMiddleware,
+    );
+
+    router.register();
+  }
+}
+`,[`schemas/${p}.schema.ts`]:`export class ${i}Schema {}
+`,["rules/create.ts"]:`import type { ValidationSchema } from "riser-bob";
+
+export const Create${i}Rule = {} satisfies ValidationSchema;
+`,["rules/update.ts"]:`import { Create${i}Rule } from "./create";
+
+export const Update${i}Rule = Create${i}Rule;
+`,[`tests/${e}.controller.test.ts`]:`import { describe, expect, test } from "bun:test";
+import { ${r}Controller } from "../${e}.controller";
+
+describe("${r}Controller", () => {
+  const controller = new ${r}Controller();
+
+  test("should be defined", () => {
+    expect(controller).toBeDefined();
+  });
+
+  test("should expose all route handlers", () => {
+    expect(typeof controller.create).toBe("function");
+    expect(typeof controller.findAll).toBe("function");
+    expect(typeof controller.findOne).toBe("function");
+    expect(typeof controller.update).toBe("function");
+    expect(typeof controller.delete).toBe("function");
+  });
+});
+`};await m(a,{recursive:!0});for(let t of Object.keys(c)){let n=s.join(a,t);if(await Bun.file(n).exists())throw Error(`File "${s.relative(process.cwd(),n)}" already exists.`)}let u=[];try{for(let[t,n]of Object.entries(c)){let d=s.join(a,t);await m(s.dirname(d),{recursive:!0}),await y(d,n,{flag:"wx"}),u.push(d)}}catch(t){throw await Promise.all(u.map((n)=>R(n).catch(()=>{}))),t}console.log(""),console.log(`\uD83E\uDDFD Module "${e}" generated successfully!`),console.log(""),console.log(`\uD83D\uDCC1 ${s.relative(process.cwd(),a)}`),console.log("");for(let t of Object.keys(c))console.log(`   \u2514\u2500\u2500 ${t}`)}var l=process.argv.slice(2),[h,O,b]=l;function w(){console.log(`
+\uD83E\uDDFD RiserBob CLI
+
+Usage:
+  riserbob g module <name>
+  riserbob generate module <name>
+  riserbob --help
+
+Commands:
+  g, generate    Generate a component
+  --help         Show this help message
+`)}async function B(){if(l.length===0||l.includes("--help")||l.includes("-h")){w();return}if(l.includes("--version")||l.includes("-v")){console.log("RiserBob CLI"),console.log("Version is provided by the installed package.");return}if((h==="g"||h==="generate")&&O==="module"&&b){await f(b);return}console.error("\uD83E\uDDFD Oh, barnacles! Unknown command."),w(),process.exitCode=1}B().catch((o)=>{let e=o instanceof Error?o.message:"Something went wrong.";console.error(`\uD83C\uDF4D RiserBob CLI: ${e}`),process.exitCode=1});

package/dist/errors/error-handler.d.ts

@@ -0,0 +1,3 @@
+export declare class ErrorHandler {
+    static handle(error: unknown): Response;
+}

package/dist/errors/errors-messages.d.ts

@@ -0,0 +1,14 @@
+export declare class ErrorMessages {
+    private readonly funnyMode;
+    constructor(funnyMode?: boolean);
+    invalidPath(path: string): string;
+    handlerDidNotReturnResponse(): string;
+    requestFailed(): string;
+    nextCalledMultipleTimes(): string;
+    duplicateRoute(key: string): string;
+    methodNotAllowed(method: string, path: string, allowed: string[]): string;
+    routeNotFound(method: string, path: string): string;
+    handlerResponseMissing(method: string, path: string, received: string): string;
+    requestHandlingFailed(): string;
+    invalidValidationSchema(field: string): string;
+}

package/dist/errors/http-error.d.ts

@@ -0,0 +1,4 @@
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/dist/http/content-negotiation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Checks whether a request uses JSON as its body format.
+ */
+export declare const isJsonContentType: (contentType: string | null) => boolean;
+/**
+ * Throws 415 when the request body is not declared as JSON.
+ */
+export declare const requireJsonContentType: (contentType: string | null) => void;
+/**
+ * Checks whether an Accept header permits a given response media type.
+ *
+ * Supports exact types, type wildcards,  and q= quality values.
+ * A missing Accept header means any response type is acceptable.
+ */
+export declare const acceptsMediaType: (acceptHeader: string | null, responseType: string) => boolean;
+/**
+ * Throws 406 when the client does not accept the response media type.
+ */
+export declare const requireAccepts: (acceptHeader: string | null, responseType: string) => void;

package/dist/http/read-request-body.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+export declare const readRequestBody: (request: Request, maxBodySize?: number) => Promise<Uint8Array>;

package/dist/http/response/riser-bob-response.d.ts

@@ -0,0 +1,2 @@
+import type { SpongResponse } from '../../types/spong-response';
+export declare function RiserBobResponse(): SpongResponse;

package/dist/http/response/status-code.d.ts

@@ -0,0 +1,65 @@
+export declare const StatusCode: {
+    readonly Continue: 100;
+    readonly SwitchingProtocols: 101;
+    readonly Processing: 102;
+    readonly EarlyHints: 103;
+    readonly OK: 200;
+    readonly Created: 201;
+    readonly Accepted: 202;
+    readonly NonAuthoritativeInfo: 203;
+    readonly NoContent: 204;
+    readonly ResetContent: 205;
+    readonly PartialContent: 206;
+    readonly MultiStatus: 207;
+    readonly AlreadyReported: 208;
+    readonly IMUsed: 226;
+    readonly MultipleChoices: 300;
+    readonly MovedPermanently: 301;
+    readonly Found: 302;
+    readonly SeeOther: 303;
+    readonly NotModified: 304;
+    readonly UseProxy: 305;
+    readonly TemporaryRedirect: 307;
+    readonly PermanentRedirect: 308;
+    readonly BadRequest: 400;
+    readonly Unauthorized: 401;
+    readonly PaymentRequired: 402;
+    readonly Forbidden: 403;
+    readonly NotFound: 404;
+    readonly MethodNotAllowed: 405;
+    readonly NotAcceptable: 406;
+    readonly ProxyAuthenticationRequired: 407;
+    readonly RequestTimeout: 408;
+    readonly Conflict: 409;
+    readonly Gone: 410;
+    readonly LengthRequired: 411;
+    readonly PreconditionFailed: 412;
+    readonly ContentTooLarge: 413;
+    readonly URITooLong: 414;
+    readonly UnsupportedMediaType: 415;
+    readonly RangeNotSatisfiable: 416;
+    readonly ExpectationFailed: 417;
+    readonly ImATeapot: 418;
+    readonly MisdirectedRequest: 421;
+    readonly UnprocessableContent: 422;
+    readonly Locked: 423;
+    readonly FailedDependency: 424;
+    readonly TooEarly: 425;
+    readonly UpgradeRequired: 426;
+    readonly PreconditionRequired: 428;
+    readonly TooManyRequests: 429;
+    readonly RequestHeaderFieldsTooLarge: 431;
+    readonly UnavailableForLegalReasons: 451;
+    readonly InternalServerError: 500;
+    readonly NotImplemented: 501;
+    readonly BadGateway: 502;
+    readonly ServiceUnavailable: 503;
+    readonly GatewayTimeout: 504;
+    readonly HTTPVersionNotSupported: 505;
+    readonly VariantAlsoNegotiates: 506;
+    readonly InsufficientStorage: 507;
+    readonly LoopDetected: 508;
+    readonly NotExtended: 510;
+    readonly NetworkAuthenticationRequired: 511;
+};
+export type StatusCode = (typeof StatusCode)[keyof typeof StatusCode];

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { RiserBob } from './application/riser-bob';
+export { HttpError } from './errors/http-error';
+export { AuthMiddleware } from './middleware/auth-middleware';
+export { corsMiddleware } from './middleware/cors-middleware';
+export { loggerMiddleware } from './middleware/logger-middleware';
+export { MiddlewarePipeline } from './middleware/middleware-pipeline';
+export type { SpongAuth } from './types/spong-auth';
+export type { SpongHandler } from './types/spong-handler';
+export type { SpongMethod } from './types/spong-method';
+export type { SpongMiddleware } from './types/spong-middleware';
+export type { SpongRequest } from './types/spong-request';
+export type { SpongResponse } from './types/spong-response';
+export type { SpongNext } from './types/spong-middleware';
+export type { ValidationSchema } from './validation/validator';
+export { Validator } from './validation/validator';