balda-js 0.0.1 → 0.0.3

package/docs/docs/cron/overview.md

@@ -1,70 +0,0 @@
----
-sidebar_position: 6
----
-
-# Overview
-
-Balda.js includes a **cron job decorator** that lets you schedule background tasks directly from your controllers or services.
-
-> **Peer dependency** — Balda.js intentionally leaves the scheduling engine to the community-standard [`node-cron`](https://www.npmjs.com/package/node-cron). To enable cron support you must install it yourself:
->
-> ```bash
-> # with npm
-> npm install node-cron
->
-> # or with yarn / pnpm / bun
-> yarn add node-cron
-> pnpm add node-cron
-> bun add node-cron
-> ```
-
-## Basic Usage
-
-```typescript
-import { cron } from 'balda-js';
-
-class TickCron {
-// Run every minute
-@cron('* * * * *')
-async handle() {
-    console.log('Cron executed!');
-  }
-}
-```
-
-The decorator accepts any valid [cron expression](https://crontab.guru/) supported by `node-cron`.
-
-## Advanced Options
-
-You can pass an **options object** as the second argument to control timezone, concurrency, etc.
-
-```typescript
-@cron('0 0 * * *', { timezone: 'UTC' })
-async handle() {
-  await this.cleanupService.run();
-}
-```
-
-## Error Handling
-
-By default, if the decorated method throws, Balda.js will log the error (using the configured logger) but will **not** crash your server.
-
-You can set a global cron error handler to handle the errors:
-
-```typescript
-server.setGlobalCronErrorHandler((error) => {
-  console.error(error);
-});
-```
-
-## Starting Cron Jobs
-
-You can import registered cron jobs classes that have one or more `@cron` decorated methods or directly import the `@cron` decorator and use it to decorate your own methods.
-
-```typescript
-import './cron/specific_cron_job';
-
-server.startRegisteredCrons(['./cron/cron_jobs.{ts,js}'], () => {
-  console.log('Cron jobs started');
-});
-```

package/docs/docs/examples/rest-api.md

@@ -1,595 +0,0 @@
----
-sidebar_position: 1
----
-
-# REST API Example
-
-A complete REST API example using Balda.js with validation, serialization, and error handling.
-
-## Project Structure
-
-```
-src/
-├── controllers/
-│   ├── users.controller.ts
-│   ├── posts.controller.ts
-│   └── auth.controller.ts
-├── middleware/
-│   ├── auth.middleware.ts
-│   └── validation.middleware.ts
-├── schemas/
-│   ├── user.schema.ts
-│   └── post.schema.ts
-├── services/
-│   ├── user.service.ts
-│   └── post.service.ts
-└── server.ts
-```
-
-## Server Setup
-
-```typescript
-// src/server.ts
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  host: 'localhost',
-  controllerPatterns: ['./src/controllers/**/*.ts'],
-  plugins: {
-    cors: {
-      origin: ['http://localhost:3000', 'http://localhost:3001'],
-      credentials: true
-    },
-    json: {
-      sizeLimit: '10mb',
-      strict: true
-    },
-    cookie: {
-      secret: process.env.COOKIE_SECRET || 'dev-secret',
-      secure: false,
-      httpOnly: true
-    },
-    helmet: {
-      contentSecurityPolicy: false
-    },
-    log: {
-      logRequest: true,
-      logResponse: true
-    }
-  },
-  swagger: {
-    type: 'standard',
-    models: {
-      User: {
-        type: 'object',
-        properties: {
-          id: { type: 'number' },
-          email: { type: 'string' },
-          name: { type: 'string' },
-          createdAt: { type: 'string', format: 'date-time' }
-        }
-      },
-      Post: {
-        type: 'object',
-        properties: {
-          id: { type: 'number' },
-          title: { type: 'string' },
-          content: { type: 'string' },
-          authorId: { type: 'number' },
-          createdAt: { type: 'string', format: 'date-time' }
-        }
-      }
-    }
-  }
-});
-
-// Global error handler
-server.setErrorHandler((req, res, next, error) => {
-  console.error('Error:', error);
-
-  if (error.name === 'ValidationError') {
-    return res.badRequest({
-      error: 'Validation failed',
-      details: error.message
-    });
-  }
-
-  if (error.name === 'UnauthorizedError') {
-    return res.unauthorized({ error: 'Authentication required' });
-  }
-
-  res.internalServerError({ error: 'Internal server error' });
-});
-
-server.listen(({ port, host }) => {
-  console.log(`🚀 Server running on http://${host}:${port}`);
-  console.log(`📚 API Documentation: http://${host}:${port}/docs`);
-});
-```
-
-## Data Schemas
-
-```typescript
-// src/schemas/user.schema.ts
-import { Type } from '@sinclair/typebox';
-
-export const CreateUserSchema = Type.Object({
-  email: Type.String({ format: 'email' }),
-  password: Type.String({ minLength: 8 }),
-  name: Type.String({ minLength: 1, maxLength: 100 })
-});
-
-export const UpdateUserSchema = Type.Partial(CreateUserSchema);
-
-export const UserSchema = Type.Object({
-  id: Type.Number(),
-  email: Type.String({ format: 'email' }),
-  name: Type.String(),
-  createdAt: Type.String({ format: 'date-time' }),
-  updatedAt: Type.String({ format: 'date-time' })
-});
-
-export const LoginSchema = Type.Object({
-  email: Type.String({ format: 'email' }),
-  password: Type.String()
-});
-
-export type CreateUser = Static<typeof CreateUserSchema>;
-export type UpdateUser = Static<typeof UpdateUserSchema>;
-export type User = Static<typeof UserSchema>;
-export type Login = Static<typeof LoginSchema>;
-```
-
-```typescript
-// src/schemas/post.schema.ts
-import { Type } from '@sinclair/typebox';
-
-export const CreatePostSchema = Type.Object({
-  title: Type.String({ minLength: 1, maxLength: 200 }),
-  content: Type.String({ minLength: 1 }),
-  published: Type.Optional(Type.Boolean())
-});
-
-export const UpdatePostSchema = Type.Partial(CreatePostSchema);
-
-export const PostSchema = Type.Object({
-  id: Type.Number(),
-  title: Type.String(),
-  content: Type.String(),
-  published: Type.Boolean(),
-  authorId: Type.Number(),
-  createdAt: Type.String({ format: 'date-time' }),
-  updatedAt: Type.String({ format: 'date-time' })
-});
-
-export type CreatePost = Static<typeof CreatePostSchema>;
-export type UpdatePost = Static<typeof UpdatePostSchema>;
-export type Post = Static<typeof PostSchema>;
-```
-
-## Services
-
-```typescript
-// src/services/user.service.ts
-import { User, CreateUser, UpdateUser } from '../schemas/user.schema';
-
-export class UserService {
-  private users: User[] = [];
-  private nextId = 1;
-
-  async findAll(): Promise<User[]> {
-    return this.users;
-  }
-
-  async findById(id: number): Promise<User | null> {
-    return this.users.find(user => user.id === id) || null;
-  }
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.users.find(user => user.email === email) || null;
-  }
-
-  async create(data: CreateUser): Promise<User> {
-    const existingUser = await this.findByEmail(data.email);
-    if (existingUser) {
-      throw new Error('User with this email already exists');
-    }
-
-    const user: User = {
-      id: this.nextId++,
-      email: data.email,
-      name: data.name,
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString()
-    };
-
-    this.users.push(user);
-    return user;
-  }
-
-  async update(id: number, data: UpdateUser): Promise<User | null> {
-    const userIndex = this.users.findIndex(user => user.id === id);
-    if (userIndex === -1) {
-      return null;
-    }
-
-    const updatedUser = {
-      ...this.users[userIndex],
-      ...data,
-      updatedAt: new Date().toISOString()
-    };
-
-    this.users[userIndex] = updatedUser;
-    return updatedUser;
-  }
-
-  async delete(id: number): Promise<boolean> {
-    const userIndex = this.users.findIndex(user => user.id === id);
-    if (userIndex === -1) {
-      return false;
-    }
-
-    this.users.splice(userIndex, 1);
-    return true;
-  }
-}
-
-export const userService = new UserService();
-```
-
-```typescript
-// src/services/post.service.ts
-import { Post, CreatePost, UpdatePost } from '../schemas/post.schema';
-
-export class PostService {
-  private posts: Post[] = [];
-  private nextId = 1;
-
-  async findAll(published?: boolean): Promise<Post[]> {
-    if (published !== undefined) {
-      return this.posts.filter(post => post.published === published);
-    }
-    return this.posts;
-  }
-
-  async findById(id: number): Promise<Post | null> {
-    return this.posts.find(post => post.id === id) || null;
-  }
-
-  async findByAuthor(authorId: number): Promise<Post[]> {
-    return this.posts.filter(post => post.authorId === authorId);
-  }
-
-  async create(data: CreatePost, authorId: number): Promise<Post> {
-    const post: Post = {
-      id: this.nextId++,
-      title: data.title,
-      content: data.content,
-      published: data.published || false,
-      authorId,
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString()
-    };
-
-    this.posts.push(post);
-    return post;
-  }
-
-  async update(id: number, data: UpdatePost): Promise<Post | null> {
-    const postIndex = this.posts.findIndex(post => post.id === id);
-    if (postIndex === -1) {
-      return null;
-    }
-
-    const updatedPost = {
-      ...this.posts[postIndex],
-      ...data,
-      updatedAt: new Date().toISOString()
-    };
-
-    this.posts[postIndex] = updatedPost;
-    return updatedPost;
-  }
-
-  async delete(id: number): Promise<boolean> {
-    const postIndex = this.posts.findIndex(post => post.id === id);
-    if (postIndex === -1) {
-      return false;
-    }
-
-    this.posts.splice(postIndex, 1);
-    return true;
-  }
-}
-
-export const postService = new PostService();
-```
-
-## Middleware
-
-```typescript
-// src/middleware/auth.middleware.ts
-import { Request, Response, NextFunction } from 'balda-js';
-import { userService } from '../services/user.service';
-
-export const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
-  const token = req.headers.authorization?.replace('Bearer ', '');
-
-  if (!token) {
-    return res.unauthorized({ error: 'Authentication token required' });
-  }
-
-  try {
-    // In a real app, you'd verify the JWT token here
-    // For this example, we'll use a simple user ID lookup
-    const userId = parseInt(token);
-    const user = await userService.findById(userId);
-
-    if (!user) {
-      return res.unauthorized({ error: 'Invalid authentication token' });
-    }
-
-    req.user = user;
-    next();
-  } catch (error) {
-    return res.unauthorized({ error: 'Invalid authentication token' });
-  }
-};
-
-export const optionalAuthMiddleware = async (req: Request, res: Response, next: NextFunction) => {
-  const token = req.headers.authorization?.replace('Bearer ', '');
-
-  if (token) {
-    try {
-      const userId = parseInt(token);
-      const user = await userService.findById(userId);
-      if (user) {
-        req.user = user;
-      }
-    } catch (error) {
-      // Ignore auth errors for optional auth
-    }
-  }
-
-  next();
-};
-```
-
-## Controllers
-
-```typescript
-// src/controllers/users.controller.ts
-import {
-  controller,
-  get,
-  post,
-  put,
-  del,
-  validate,
-  serialize,
-  middleware
-} from 'balda-js';
-import { Request, Response } from 'balda-js';
-import {
-  CreateUserSchema,
-  UpdateUserSchema,
-  UserSchema,
-  LoginSchema
-} from '../schemas/user.schema';
-import { userService } from '../services/user.service';
-import { authMiddleware } from '../middleware/auth.middleware';
-
-@controller('/users')
-export class UsersController {
-  @get('/')
-  @serialize(Type.Array(UserSchema))
-  async getAllUsers(req: Request, res: Response) {
-    const users = await userService.findAll();
-    res.json(users);
-  }
-
-  @get('/:id')
-  @serialize(UserSchema)
-  async getUserById(req: Request, res: Response) {
-    const id = parseInt(req.params.id);
-    const user = await userService.findById(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: CreateUser) {
-    try {
-      const user = await userService.create(body);
-      res.created(user);
-    } catch (error) {
-      return res.conflict({ error: error.message });
-    }
-  }
-
-  @put('/:id')
-  @middleware(authMiddleware)
-  @validate.body(UpdateUserSchema)
-  @serialize(UserSchema)
-  async updateUser(req: Request, res: Response, body: UpdateUser) {
-    const id = parseInt(req.params.id);
-
-    // Ensure users can only update their own profile
-    if (req.user.id !== id) {
-      return res.forbidden({ error: 'Cannot update other users' });
-    }
-
-    const user = await userService.update(id, body);
-
-    if (!user) {
-      return res.notFound({ error: 'User not found' });
-    }
-
-    res.json(user);
-  }
-
-  @del('/:id')
-  @middleware(authMiddleware)
-  async deleteUser(req: Request, res: Response) {
-    const id = parseInt(req.params.id);
-
-    // Ensure users can only delete their own account
-    if (req.user.id !== id) {
-      return res.forbidden({ error: 'Cannot delete other users' });
-    }
-
-    const deleted = await userService.delete(id);
-
-    if (!deleted) {
-      return res.notFound({ error: 'User not found' });
-    }
-
-    res.noContent();
-  }
-
-  @post('/login')
-  @validate.body(LoginSchema)
-  async login(req: Request, res: Response, body: Login) {
-    const user = await userService.findByEmail(body.email);
-
-    if (!user) {
-      return res.unauthorized({ error: 'Invalid credentials' });
-    }
-
-    // In a real app, you'd verify the password hash here
-    // For this example, we'll just return the user ID as a token
-    res.json({
-      token: user.id.toString(),
-      user: {
-        id: user.id,
-        email: user.email,
-        name: user.name
-      }
-    });
-  }
-}
-```
-
-```typescript
-// src/controllers/posts.controller.ts
-import {
-  controller,
-  get,
-  post,
-  put,
-  del,
-  validate,
-  serialize,
-  middleware,
-  Request,
-  Response
-} from 'balda-js';
-import { Type, Static } from '@sinclair/typebox';
-import {
-  CreatePostSchema,
-  UpdatePostSchema,
-  PostSchema
-} from '../schemas/post.schema';
-import { postService } from '../services/post.service';
-import { authMiddleware, optionalAuthMiddleware } from '../middleware/auth.middleware';
-
-@controller('/posts')
-export class PostsController {
-  @get('/')
-  @middleware(optionalAuthMiddleware)
-  @serialize(Type.Array(PostSchema))
-  async getAllPosts(req: Request, res: Response) {
-    const published = req.query.published === 'true';
-    const posts = await postService.findAll(published);
-    res.json(posts);
-  }
-
-  @get('/:id')
-  @serialize(PostSchema)
-  async getPostById(req: Request, res: Response) {
-    const id = parseInt(req.params.id);
-    const post = await postService.findById(id);
-
-    if (!post) {
-      return res.notFound({ error: 'Post not found' });
-    }
-
-    // Only show unpublished posts to their authors
-    if (!post.published && (!req.user || req.user.id !== post.authorId)) {
-      return res.notFound({ error: 'Post not found' });
-    }
-
-    res.json(post);
-  }
-
-  @post('/')
-  @middleware(authMiddleware)
-  @validate.body(CreatePostSchema)
-  @serialize(PostSchema)
-  async createPost(req: Request, res: Response, body: Static<CreatePostSchema>) {
-    const post = await postService.create(body, req.user.id);
-    res.created(post);
-  }
-
-  @put('/:id')
-  @middleware(authMiddleware)
-  @validate.body(UpdatePostSchema)
-  @serialize(PostSchema)
-  async updatePost(req: Request, res: Response, body: UpdatePost) {
-    const id = parseInt(req.params.id);
-    const existingPost = await postService.findById(id);
-
-    if (!existingPost) {
-      return res.notFound({ error: 'Post not found' });
-    }
-
-    // Ensure users can only update their own posts
-    if (req.user.id !== existingPost.authorId) {
-      return res.forbidden({ error: 'Cannot update other users\' posts' });
-    }
-
-    const post = await postService.update(id, body);
-    res.json(post);
-  }
-
-  @del('/:id')
-  @middleware(authMiddleware)
-  async deletePost(req: Request, res: Response) {
-    const id = parseInt(req.params.id);
-    const existingPost = await postService.findById(id);
-
-    if (!existingPost) {
-      return res.notFound({ error: 'Post not found' });
-    }
-
-    // Ensure users can only delete their own posts
-    if (req.user.id !== existingPost.authorId) {
-      return res.forbidden({ error: 'Cannot delete other users\' posts' });
-    }
-
-    const deleted = await postService.delete(id);
-    res.noContent();
-  }
-
-  @get('/author/:authorId')
-  @serialize(Type.Array(PostSchema))
-  async getPostsByAuthor(req: Request, res: Response) {
-    const authorId = parseInt(req.params.authorId);
-    const posts = await postService.findByAuthor(authorId);
-
-    // Filter out unpublished posts unless the user is the author
-    const filteredPosts = posts.filter(post =>
-      post.published || (req.user && req.user.id === authorId)
-    );
-
-    res.json(filteredPosts);
-  }
-}
-```