balda-js 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balda-js",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "main": "./lib/index.cjs",
   "module": "./lib/index.js",
@@ -74,11 +74,6 @@
   "peerDependencies": {
     "node-cron": "^4.1.0"
   },
-  "peerDependenciesMeta": {
-    "ioredis": {
-      "node-cron": true
-    }
-  },
   "tags": [
     "framework",
     "http",

package/.husky/pre-commit

@@ -1,19 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-yarn format
-yarn build:test
-
-echo "Running tests..."
-
-echo "Running tests for Node..."
-yarn test
-
-echo "Running tests for Bun..."
-yarn test:bun
-
-echo "Running tests for Deno..."
-yarn test:deno
-
-echo "Adding changes..."
-git add .

package/.nvmrc

@@ -1 +0,0 @@
-v22.14.0

package/docs/README.md

@@ -1,135 +0,0 @@
-# Balda.js Documentation
-
-This directory contains the documentation for Balda.js, built with Docusaurus.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 18+ or Bun
-- Yarn (recommended) or npm
-
-### Installation
-
-```bash
-# Install dependencies
-yarn install
-
-# Start development server
-yarn start
-```
-
-### Available Scripts
-
-- `yarn start` - Start the development server
-- `yarn build` - Build the documentation for production
-- `yarn serve` - Serve the built documentation locally
-
-## Documentation Structure
-
-```
-docs/
-├── intro.md                    # Main introduction page
-├── getting-started/            # Getting started guides
-│   ├── installation.md
-│   ├── quick-start.md
-│   └── configuration.md
-├── core-concepts/              # Core framework concepts
-│   ├── server.md
-│   ├── controllers.md
-│   ├── routing.md
-│   ├── middleware.md
-│   └── request-response.md
-├── api/                        # API reference
-│   ├── server.md
-│   ├── controllers.md
-│   ├── decorators.md
-│   ├── plugins.md
-│   ├── cli.md
-│   └── cron.md
-├── plugins/                    # Plugin documentation
-│   ├── overview.md
-│   ├── cors.md
-│   ├── json.md
-│   ├── static.md
-│   ├── cookie.md
-│   ├── helmet.md
-│   ├── rate-limiter.md
-│   ├── log.md
-│   ├── file.md
-│   ├── urlencoded.md
-│   └── swagger.md
-├── advanced/                   # Advanced topics
-│   ├── validation.md
-│   ├── serialization.md
-│   ├── error-handling.md
-│   ├── testing.md
-│   └── deployment.md
-├── examples/                   # Example applications
-│   ├── rest-api.md
-│   ├── file-upload.md
-│   ├── authentication.md
-│   ├── cron-jobs.md
-│   └── cli-commands.md
-└── runtime/                    # Runtime-specific guides
-    ├── node.md
-    ├── bun.md
-    └── deno.md
-```
-
-## Contributing
-
-When adding or updating documentation:
-
-1. Follow the existing structure and naming conventions
-2. Use TypeScript code examples
-3. Include practical examples and use cases
-4. Keep content clear and concise
-5. Test all code examples
-
-## Building for Production
-
-```bash
-# Build the documentation
-yarn build
-
-# The built files will be in the `build` directory
-```
-
-## Deployment
-
-The documentation can be deployed to various platforms:
-
-- **GitHub Pages**: Use the `yarn deploy` command
-- **Netlify**: Connect your repository and set build command to `yarn build`
-- **Vercel**: Connect your repository and set build command to `yarn build`
-
-## Configuration
-
-The documentation is configured in `docusaurus.config.ts`. Key settings:
-
-- Site title and description
-- Navigation and sidebar structure
-- Theme customization
-- Plugin configuration
-
-## Customization
-
-### Styling
-
-Custom CSS can be added to `src/css/custom.css`.
-
-### Components
-
-Custom React components can be added to `src/components/`.
-
-### Pages
-
-Custom pages can be added to `src/pages/`.
-
-## Support
-
-For questions about the documentation or Balda.js:
-
-- [GitHub Issues](https://github.com/Frasan00/balda-js/issues)
-- [GitHub Discussions](https://github.com/Frasan00/balda-js/discussions)

package/docs/blog/authors.yml

@@ -1,6 +0,0 @@
-# Authors configuration for Balda.js blog
-francesco:
-  name: Francesco Sangiovanni
-  title: Framework Creator
-  url: https://github.com/Frasan00
-  image_url: https://github.com/Frasan00.png

package/docs/blog/tags.yml

@@ -1,4 +0,0 @@
-# Tags configuration for Balda.js blog
-balda-js:
-  description: Balda.js framework related posts
-  permalink: /blog/tags/balda-js

package/docs/cli.md

@@ -1,109 +0,0 @@
----
-id: cli
-title: Command-Line Interface
-sidebar_position: 1
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-# `@cli/` overview
-
-Balda ships with an opinionated, TypeScript-first CLI—think of it as a meta-toolbox. It scaffolds new commands, plugins, and cron jobs so you can stay focused on application logic.
-
-```bash title="General syntax"
-npx balda <command> [options] [arguments]
-```
-
-Need help?
-
-```bash title="Global & command help"
-npx balda # access the cli
-npx balda <command> -h  # command-specific help
-```
-
----
-
-## Built-in generators
-
-### 1. `generate-command`
-
-Scaffolds a new CLI command file.
-
-| Argument / Flag | Type   | Default          | Description                              |
-| --------------- | ------ | ---------------- | ---------------------------------------- |
-| `<name>`        | string | — (required)     | File (and class) name of the new command |
-| `-p`, `--path`  | string | `src/commands`   | Target directory                         |
-
-```bash title="Example"
-npx balda generate-command hello-world -p tools/cli
-```
-
----
-
-### 2. `generate-plugin`
-
-Creates a plugin skeleton.
-
-| Argument / Flag | Type   | Default       | Description                          |
-| --------------- | ------ | ------------- | ------------------------------------ |
-| `<pluginName>`  | string | — (required)  | Plugin filename & class name         |
-| `-p`, `--path`  | string | `src/plugins` | Directory where the file is written |
-
-```bash title="Example"
-npx balda generate-plugin auth -p src/plugins/security
-```
-
----
-
-### 3. `generate-cron`
-
-Bootstraps a cron-job class adorned with the `@cron()` decorator.
-
-| Argument / Flag | Type   | Default   | Description               |
-| --------------- | ------ | --------- | ------------------------- |
-| `<fileName>`    | string | —         | Cron job filename         |
-| `-p`, `--path`  | string | `src/cron`| Where to create the file  |
-
-```bash title="Example"
-npx balda generate-cron clean-sessions -p src/maintenance/cron
-```
-
----
-
-## Extending the CLI
-
-Declare your own commands and tell Balda where to find them:
-
-```ts title="Custom command discovery"
-import { CommandRegistry } from '@cli/';
-
-CommandRegistry.setCommandsPattern('./my/commands/**/*.ts');
-```
-
-At startup the CLI loads:
-
-1. Anything matching the pattern above.
-2. The built-in generators described earlier.
-
-> **Tip:** Use decorators (`@arg`, `@flag`) in your command classes for self-documenting, runtime-validated definitions.
-
----
-
-## Help & validation
-
-Each command inherits colourised `--help` output **and** validation for missing/invalid flags. Introduce an error:
-
-```bash
-npx balda generate-plugin
-```
-
-You’ll get a detailed, friendly validation report and a non-zero exit code.
-
----
-
-## Next steps
-
-• Install globally with `npm i -g balda` if you prefer the shorter `balda` binary.
-• Peek at `src/commands/base_command.ts` for advanced goodies like `keepAlive`.
-• Curious about decorators? Check **Docs → Decorators** (coming soon).

package/docs/docs/core-concepts/controllers.md

@@ -1,393 +0,0 @@
----
-sidebar_position: 2
----
-
-# Controllers
-
-Controllers are the heart of your Balda.js application. They organize your route handlers into logical groups and provide a clean, decorator-based API for defining HTTP endpoints.
-
-## Basic Controller
-
-```typescript
-import { controller, get, post } from 'balda-js';
-import { Request, Response } from 'balda-js';
-
-@controller('/users')
-export class UsersController {
-  @get('/')
-  async getAllUsers(req: Request, res: Response) {
-    res.json({ users: [] });
-  }
-
-  @post('/')
-  async createUser(req: Request, res: Response) {
-    res.created(req.body);
-  }
-}
-```
-
-## Controller Decorator
-
-The `@controller()` decorator marks a class as a controller and defines the base path for all routes within that controller.
-
-```typescript
-@controller(path?: string, swaggerOptions?: SwaggerRouteOptions)
-```
-
-### Parameters
-
-- `path` (optional): Base path for all routes in the controller
-- `swaggerOptions` (optional): Swagger documentation options for the controller
-
-### Examples
-
-```typescript
-// Simple controller
-@controller('/users')
-export class UsersController {}
-
-// Controller with Swagger options
-@controller('/users', {
-  tags: ['Users'],
-  summary: 'User management endpoints'
-})
-export class UsersController {}
-```
-
-## HTTP Method Decorators
-
-Balda.js provides decorators for all HTTP methods:
-
-### GET Requests
-
-```typescript
-@get('/')
-async getAllUsers(req: Request, res: Response) {
-  res.json({ users: [] });
-}
-
-@get('/:id')
-async getUserById(req: Request, res: Response) {
-  const id = req.params.id;
-  res.json({ user: { id } });
-}
-```
-
-### POST Requests
-
-```typescript
-@post('/')
-async createUser(req: Request, res: Response) {
-  const user = req.body;
-  res.created(user);
-}
-```
-
-### PUT Requests
-
-```typescript
-@put('/:id')
-async updateUser(req: Request, res: Response) {
-  const id = req.params.id;
-  const updates = req.body;
-  res.json({ id, ...updates });
-}
-```
-
-### PATCH Requests
-
-```typescript
-@patch('/:id')
-async partialUpdateUser(req: Request, res: Response) {
-  const id = req.params.id;
-  const updates = req.body;
-  res.json({ id, ...updates });
-}
-```
-
-### DELETE Requests
-
-```typescript
-@del('/:id')
-async deleteUser(req: Request, res: Response) {
-  const id = req.params.id;
-  res.noContent();
-}
-```
-
-## Route Options
-
-Each HTTP method decorator can accept route options:
-
-```typescript
-@get('/', {
-  middleware: [authMiddleware],
-  swagger: {
-    summary: 'Get all users',
-    description: 'Retrieve a list of all users'
-  }
-})
-async getAllUsers(req: Request, res: Response) {
-  res.json({ users: [] });
-}
-```
-
-## Controller-Level Middleware
-
-You can apply middleware to all routes in a controller:
-
-```typescript
-@controller('/users')
-@middleware(authMiddleware)
-export class UsersController {
-  @get('/')
-  async getAllUsers(req: Request, res: Response) {
-    // This route will use authMiddleware
-    res.json({ users: [] });
-  }
-
-  @get('/public')
-  @middleware(publicMiddleware) // Override controller middleware
-  async getPublicUsers(req: Request, res: Response) {
-    // This route will use publicMiddleware instead
-    res.json({ users: [] });
-  }
-}
-```
-
-## Complete Controller Example
-
-```typescript
-import {
-  controller,
-  get,
-  post,
-  put,
-  del,
-  middleware,
-  validate,
-  serialize
-} from 'balda-js';
-import { Request, Response } from 'balda-js';
-import { Type, Static } from '@sinclair/typebox';
-
-const UserSchema = Type.Object({
-  id: Type.Number(),
-  name: Type.String(),
-  email: Type.String()
-});
-
-const CreateUserSchema = Type.Object({
-  name: Type.String(),
-  email: Type.String({ format: 'email' })
-});
-
-@controller('/users', {
-  tags: ['Users'],
-  summary: 'User management endpoints'
-})
-@middleware(loggerMiddleware)
-export class UsersController {
-  private users = [
-    { id: 1, name: 'John Doe', email: 'john@example.com' },
-    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
-  ];
-
-  @get('/')
-  @serialize(Type.Array(UserSchema))
-  async getAllUsers(req: Request, res: Response) {
-    res.json(this.users);
-  }
-
-  @get('/:id')
-  @serialize(UserSchema)
-  async getUserById(req: Request, res: Response) {
-    const id = parseInt(req.params.id);
-    const user = this.users.find(u => u.id === id);
-
-    if (!user) {
-      return res.notFound({ error: 'User not found' });
-    }
-
-    res.json(user);
-  }
-
-  @post('/')
-  @validate.body(CreateUserSchema)
-  @serialize(UserSchema)
-    async createUser(req: Request, res: Response, body: Static<typeof CreateUserSchema>) {
-    const newUser = {
-      id: this.users.length + 1,
-      ...body
-    };
-
-    this.users.push(newUser);
-    res.created(newUser);
-  }
-
-  @put('/:id')
-  @middleware(authMiddleware)
-  @validate.body(CreateUserSchema)
-  @serialize(UserSchema)
-  async updateUser(req: Request, res: Response, body: Static<typeof CreateUserSchema>) {
-    const id = parseInt(req.params.id);
-    const userIndex = this.users.findIndex(u => u.id === id);
-
-    if (userIndex === -1) {
-      return res.notFound({ error: 'User not found' });
-    }
-
-    this.users[userIndex] = { ...this.users[userIndex], ...body };
-    res.json(this.users[userIndex]);
-  }
-
-  @del('/:id')
-  @middleware(authMiddleware)
-  async deleteUser(req: Request, res: Response) {
-    const id = parseInt(req.params.id);
-    const userIndex = this.users.findIndex(u => u.id === id);
-
-    if (userIndex === -1) {
-      return res.notFound({ error: 'User not found' });
-    }
-
-    this.users.splice(userIndex, 1);
-    res.noContent();
-  }
-}
-```
-
-## Controller Organization
-
-### File Structure
-
-```
-src/
-├── controllers/
-│   ├── users.controller.ts
-│   ├── posts.controller.ts
-│   ├── auth.controller.ts
-│   └── index.ts
-```
-
-### Controller Registration
-
-Controllers are automatically registered when the server starts. Make sure your controller files match the patterns specified in your server configuration:
-
-```typescript
-const server = new Server({
-  controllerPatterns: ['./src/controllers/**/*.ts']
-});
-```
-
-### Controller Index
-
-You can create an index file to export all controllers:
-
-```typescript
-// src/controllers/index.ts
-export * from './users.controller';
-export * from './posts.controller';
-export * from './auth.controller';
-```
-
-## Best Practices
-
-### 1. Single Responsibility
-
-Each controller should handle a single resource or feature:
-
-```typescript
-// Good: Focused on users
-@controller('/users')
-export class UsersController {}
-
-// Good: Focused on authentication
-@controller('/auth')
-export class AuthController {}
-
-// Avoid: Mixed responsibilities
-@controller('/api')
-export class ApiController {} // Too broad
-```
-
-### 2. Consistent Naming
-
-Use consistent naming conventions:
-
-```typescript
-// Good: Clear and descriptive
-@controller('/users')
-export class UsersController {}
-
-@controller('/blog-posts')
-export class BlogPostsController {}
-
-// Avoid: Unclear names
-@controller('/u')
-export class UController {}
-```
-
-### 3. Error Handling
-
-Handle errors consistently within controllers:
-
-```typescript
-@controller('/users')
-export class UsersController {
-  @get('/:id')
-  async getUserById(req: Request, res: Response) {
-    try {
-      const id = parseInt(req.params.id);
-      const user = await userService.findById(id);
-
-      if (!user) {
-        return res.notFound({ error: 'User not found' });
-      }
-
-      res.json(user);
-    } catch (error) {
-      console.error('Error fetching user:', error);
-      res.internalServerError({ error: 'Failed to fetch user' });
-    }
-  }
-}
-```
-
-### 4. Validation and Serialization
-
-Use validation and serialization decorators for type safety:
-
-```typescript
-@controller('/users')
-export class UsersController {
-  @post('/')
-  @validate.body(CreateUserSchema)
-  @serialize(UserSchema)
-  async createUser(req: Request, res: Response, body: Static<typeof CreateUserSchema>) {
-    // body is now typed as CreateUser
-    const user = await userService.create(body);
-    res.created(user);
-  }
-}
-```
-
-### 5. Middleware Organization
-
-Group related middleware and apply them at the appropriate level:
-
-```typescript
-// Apply to all routes in controller
-@controller('/users')
-@middleware(authMiddleware)
-export class UsersController {
-  // Apply to specific routes
-  @get('/admin')
-  @middleware(adminMiddleware)
-  async getAdminUsers(req: Request, res: Response) {
-    // Uses both authMiddleware and adminMiddleware
-  }
-}
-```
-
-Controllers provide a clean, organized way to structure your Balda.js application's route handlers.