riser-bob 1.0.0 → 1.1.0

package/LICENSE

@@ -1,27 +1,21 @@
-# RiserBob Proprietary License
-
-Copyright (c) 2026 RiserBob. All rights reserved.
-
-## 1. Ownership
-RiserBob and its original source code, documentation, and associated materials are protected by applicable intellectual property laws. All rights not expressly granted under this license are reserved by the copyright holder.
-
-## 2. Permission to Use
-Subject to the terms of this license, users are granted permission to use the official, unmodified version of RiserBob in their own applications and projects.
-
-## 3. Modification Restrictions
-No person or entity may modify, adapt, alter, or create derivative versions of the RiserBob framework without prior written permission from the copyright holder.
-
-## 4. Distribution Restrictions
-Redistribution, resale, sublicensing, or publication of RiserBob or any modified version of the framework is prohibited unless expressly authorized in writing by the copyright holder.
-
-## 5. Independent Applications
-Users retain ownership of their independently developed application code, subject to any third-party rights and applicable law. Using RiserBob does not, by itself, transfer ownership of an application's independent code to the copyright holder.
-
-## 6. No Implied Permission
-No permission is granted beyond the rights expressly stated in this license. Any exception must be approved in writing by the copyright holder.
-
-## 7. Disclaimer
-RiserBob is provided "AS IS", without warranties of any kind, to the maximum extent permitted by applicable law.
-
-## 8. Contact and Written Permission
-Requests for permission to modify or redistribute RiserBob must be submitted to the copyright holder and approved in writing before the relevant activity takes place.
+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,231 +1,96 @@
-# 🧽 RiserBob
+<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>
 
-A lightweight, fun, and fully tested HTTP framework for [Bun](https://bun.sh), with a built-in router, middleware pipeline, request validation, and consistent error handling.
+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 [RiserBob Proprietary License](#license). Please read it before using the framework.
+> RiserBob is distributed under the [MIT License](#license).
 
-## Features
-
-- **Fast routing** with static and dynamic (`/users/:id`) routes, where static routes win over dynamic ones.
-- **Middleware pipeline** with global and per-route middleware, executed in registration order.
-- **Built-in auth middleware** for Bearer-token authentication with your own token verifier.
-- **Validator** with a simple rule syntax (`required`, `string`, `email`, `min:18`, ...).
-- **Response helpers** for JSON, status codes, headers, and redirects.
-- **Consistent errors** through `HttpError` and a central error handler (`404`, `405` with the `Allow` header, `500`).
-- **Fully tested** with Bun's test runner (unit and end-to-end tests).
+![RiserBob](https://res.cloudinary.com/dgagbheuj/image/upload/v1792927501/qlflwqvq6xqgxnbn0puk.png)
 
-## Requirements
+## Features
 
-- [Bun](https://bun.sh) 1.3 or newer
+- **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
 
-```bash
-bun add riser-bob
-```
-
-> The examples below import from `riser-bob`. Adjust the import path if you install or reference the framework differently.
-
-## Quick Start
-
-```ts
-import { RiserBob } from 'riser-bob'
-
-const app = new RiserBob()
-
-app.spongGet('/', async (spongReq, spongRes) => {
-	return spongRes.json({ message: 'Welcome to Bikini Bottom! 🍍' })
-})
-
-app.spongListen(3000, () => {
-	console.log('RiserBob is running on http://localhost:3000')
-})
-```
-
-Run it:
+Requires [Bun](https://bun.sh) 1.3 or newer. There are two ways to start.
 
+### 1. Starter template (recommended)
 ```bash
-bun run index.ts
-```
-
-## Routing
-
-Register routes with the `Sponge` methods. Every method returns the app, so calls can be chained.
-
-```ts
-app.spongGet('/users', listUsers)
-	.spongPost('/users', createUser)
-	.spongPut('/users/:id', replaceUser)
-	.spongPatch('/users/:id', updateUser)
-	.spongDelete('/users/:id', deleteUser)
-```
-
-Paths must start with `/`, and registering the same method and path twice throws an error.
-
-### Route parameters and query strings
-
-```ts
-app.spongGet('/users/:id', async (spongReq, spongRes) => {
-	const { id } = spongReq.params // decoded automatically
-	const page = spongReq.query.get('page') // URLSearchParams
-
-	return spongRes.json({ id, page })
-})
-```
-
-### Reading the request body
-
-```ts
-app.spongPost('/users', async (spongReq, spongRes) => {
-	const body = await spongReq.json<{ name: string }>()
-
-	return spongRes.json({ created: body.name })
-})
+bun create riser-bob my-app
 ```
 
-`spongReq` also exposes `method`, `path`, `url`, `headers`, `text()`, and the original `request`.
-
-## Middleware
-
-A middleware receives the request and a `next` function. Return `next()` to continue, or return a `Response` to stop the chain.
+The best choice if you want a ready-made, organized template to start your project with. It creates `src/index.ts`:
 
 ```ts
-import type { SpongMiddleware, SpongRequest } from 'riser-bob'
-
-const logger: SpongMiddleware<SpongRequest> = async (spongReq, next) => {
-	console.log(`${spongReq.method} ${spongReq.path}`)
-	return next()
+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 🍍");
+  });
 }
 
-app.spongUse(logger) // global middleware
-
-app.spongGet('/admin', handler, adminOnly) // route-specific middleware
-```
-
-> Global middleware is attached when a route is registered, so call `spongUse` **before** registering the routes it should apply to.
-
-### Authentication
-
-```ts
-import { AuthMiddleware } from 'riser-bob'
-
-const auth = new AuthMiddleware(async (token) => {
-	// Return the user for a valid token, or null for an invalid one.
-	return verifyMyToken(token)
-})
-
-app.spongGet(
-	'/me',
-	async (spongReq, spongRes) => {
-		return spongRes.json({ user: spongReq.user })
-	},
-	auth.middleware
-)
-```
-
-The middleware reads the `Authorization: Bearer <token>` header. On success it sets `spongReq.user` and `spongReq.auth`. Otherwise it responds with `401` (`Unauthorized`, `Token is required`, or `Invalid or expired token`).
-
-## Validation
-
-```ts
-import { Validator } from 'riser-bob'
-
-const result = Validator.validate(
-	{ name: 'Zen', age: 17, email: 'zen@example.com' },
-	{
-		name: ['required', 'string'],
-		age: ['required', 'number', 'min:13'],
-		email: ['required', 'email']
-	}
-)
-
-if (!result.valid) {
-	console.log(result.errors) // { age: ['age must be at least 13'], ... }
-}
+bootstrap().catch((error: unknown) => {
+  console.error("[RiserBob] Failed to start application:", error);
+  process.exit(1);
+});
 ```
 
-| Rule                            | Description                                            |
-| ------------------------------- | ------------------------------------------------------ |
-| `required`                      | Value must be present and not empty.                   |
-| `nullable`                      | `null` is allowed. Cannot be combined with `required`. |
-| `string` / `number` / `boolean` | Type checks. Numbers must be finite.                   |
-| `email`                         | Must be a valid email address.                         |
-| `confirmed`                     | Must match the `<field>Confirmation` value.            |
-| `min:n` / `max:n`               | Numeric limit for numbers, length limit for strings.   |
-| `minLength:n` / `maxLength:n`   | String length limits (integers only).                  |
-
-Fields without `required` are optional: missing values and empty strings are skipped.
-
-## Responses and Errors
-
-Handlers must return a `Response`. The `spongRes` helper builds one for you, and you can always return a standard `Response` instead.
+Then the terminal shows:
 
-```ts
-app.spongGet('/ok', async (spongReq, spongRes) => spongRes.json({ ok: true }))
-app.spongGet('/raw', async () => new Response('plain text'))
+```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!
 ```
 
-To fail with a specific status, throw an `HttpError`:
-
-```ts
-import { HttpError } from 'riser-bob'
+### 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).
 
-app.spongGet('/secret', async () => {
-	throw new HttpError(403, 'Forbidden')
-})
-```
+## Simple API, Powerful Structure
 
-RiserBob handles the common cases for you:
+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)`.
 
-| Situation                      | Response                                                |
-| ------------------------------ | ------------------------------------------------------- |
-| No matching route              | `404 Not Found`                                         |
-| Path exists, method does not   | `405 Method Not Allowed` with an `Allow` header         |
-| Handler throws an `HttpError`  | The error's status and message                          |
-| Handler throws any other error | `500 Internal Server Error` (details are never exposed) |
-| Handler returns no `Response`  | `500`                                                   |
+## CLI
 
-## Development
+Generate a complete module (`users.controller.ts`, `users.route.ts`, `users.module.ts`) with one command:
 
 ```bash
-# Install dependencies
-bun install
-
-# Run all tests
-bun test
-```
-
-```text
-src/
-  application/   RiserBob application class
-  errors/        HttpError and ErrorHandler
-  http/          Response helpers
-  middleware/    Middleware pipeline and built-in middleware
-  routing/       Router
-  server/        HTTP server
-  types/         Shared types
-  validation/    Validator
-test/
-  unit/          Unit tests
-  e2e/           End-to-end tests
+bun run riser-bob g module users   # `generate` also works
 ```
+## Learn more
 
-## Contributing
-
-Contributions are welcome, but because RiserBob is proprietary, please read [CONTRIBUTING.md](CONTRIBUTING.md) first. It explains the contribution terms. Please also follow our [Code of Conduct](CODE_OF_CONDUCT.md).
-
-## Security
-
-Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md) for details.
+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 **RiserBob Proprietary License**. In short:
-
-- You may use the official, unmodified version of RiserBob in your own applications and projects.
-- You may **not** modify, redistribute, resell, or sublicense the framework without prior written permission.
-- You keep full ownership of the application code you write with RiserBob.
-
-See the [LICENSE](LICENSE) file for the full terms.
-
-Copyright (c) 2026 RiserBob. All rights reserved.
+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

@@ -1,9 +1,15 @@
 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;
@@ -13,5 +19,6 @@ export declare class RiserBob {
     spongHead(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
     spongOptions(path: string, handler: SpongHandler, ...middlewares: SpongMiddleware<SpongRequest>[]): this;
     spongUse(middleware: SpongMiddleware<SpongRequest>): this;
-    spongListen(port?: number, callback?: () => void): Bun.Server<undefined>;
+    spongSocketIO(options?: Partial<ServerOptions>): SocketIOServer;
+    spongListen(port?: number, callback?: () => void): Bun.Server<import("@socket.io/bun-engine").WebSocketData>;
 }

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 // @bun
-import{mkdir as b,writeFile as f}from"fs/promises";import i from"path";function h(o){return o.split(/[-_\s]+/).filter(Boolean).map((e)=>e[0].toUpperCase()+e.slice(1).toLowerCase()).join("")}function w(o){return o.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase().replace(/[_\s]+/g,"-")}function y(o){return/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(o)}async function p(o){if(!y(o))throw Error('Invalid module name. Use letters, numbers, "-" or "_", starting with a letter.');let e=w(o),r=h(e),l=i.resolve(process.cwd(),"src","modules",e),c={[`${e}.controller.ts`]:`import type { SpongHandler } from "riser-bob";
+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) => {
@@ -41,11 +41,15 @@ export class ${r}Router {
 
   register(): void {
     // Public routes
-    this.bob.spongPost("/api/${e}", this.controller.create);
     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,
@@ -81,7 +85,32 @@ export class ${r}Module {
     router.register();
   }
 }
-`};await b(l,{recursive:!0});for(let t of Object.keys(c)){let n=i.join(l,t);if(await Bun.file(n).exists())throw Error(`File "${i.relative(process.cwd(),n)}" already exists.`)}let d=[];try{for(let[t,n]of Object.entries(c)){let a=i.join(l,t);await f(a,n,{flag:"wx"}),d.push(a)}}catch(t){let{unlink:n}=await import("fs/promises");throw await Promise.all(d.map((a)=>n(a).catch(()=>{}))),t}console.log(`\uD83E\uDDFD Module "${e}" generated successfully!`),console.log(`\uD83D\uDCC1 ${i.relative(process.cwd(),l)}`);for(let t of Object.keys(c))console.log(`   \u2514\u2500\u2500 ${t}`)}var s=process.argv.slice(2),[m,v,g]=s;function u(){console.log(`
+`,[`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:
@@ -92,4 +121,4 @@ Usage:
 Commands:
   g, generate    Generate a component
   --help         Show this help message
-`)}async function R(){if(s.length===0||s.includes("--help")||s.includes("-h")){u();return}if(s.includes("--version")||s.includes("-v")){console.log("RiserBob CLI"),console.log("Version is provided by the installed package.");return}if((m==="g"||m==="generate")&&v==="module"&&g){await p(g);return}console.error("\uD83E\uDDFD Oh, barnacles! Unknown command."),u(),process.exitCode=1}R().catch((o)=>{let e=o instanceof Error?o.message:"Something went wrong.";console.error(`\uD83C\uDF4D RiserBob CLI: ${e}`),process.exitCode=1});
+`)}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/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/index.d.ts

@@ -10,5 +10,6 @@ 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';