@riligar/agents-kit 1.11.0 → 1.13.0

package/.agent/skills/riligar-dev-backend/references/elysia-plugins.md

@@ -0,0 +1,202 @@
+# Elysia Plugins
+
+Plugins are the core pattern for organizing Elysia applications. Each plugin is a self-contained Elysia instance that can be composed into larger applications.
+
+## Creating a Plugin
+
+```javascript
+// routes/users.js
+import { Elysia } from 'elysia'
+
+export const userRoutes = new Elysia({ prefix: '/users' })
+    .get('/', () => getAllUsers())
+    .get('/:id', ({ params }) => getUserById(params.id))
+    .post('/', ({ body }) => createUser(body))
+    .delete('/:id', ({ params }) => deleteUser(params.id))
+```
+
+## Using Plugins
+
+```javascript
+// index.js
+import { Elysia } from 'elysia'
+import { userRoutes } from './routes/users'
+import { postRoutes } from './routes/posts'
+
+const app = new Elysia()
+    .use(userRoutes)
+    .use(postRoutes)
+    .listen(3000)
+```
+
+## Plugin with Configuration
+
+```javascript
+// plugins/logger.js
+export const loggerPlugin = (options = {}) => {
+    const { prefix = '[LOG]' } = options
+
+    return new Elysia({ name: 'logger' })
+        .onRequest(({ request }) => {
+            console.log(`${prefix} ${request.method} ${request.url}`)
+        })
+}
+
+// Usage
+app.use(loggerPlugin({ prefix: '[API]' }))
+```
+
+## Named Plugins (Deduplication)
+
+Use `name` to prevent duplicate plugin registration:
+
+```javascript
+const dbPlugin = new Elysia({ name: 'database' })
+    .decorate('db', database)
+
+// Even if used multiple times, only registers once
+app.use(dbPlugin).use(dbPlugin)
+```
+
+## Decorators (Dependency Injection)
+
+Add custom properties to the context:
+
+```javascript
+const app = new Elysia()
+    .decorate('db', database)
+    .decorate('config', { apiKey: process.env.API_KEY })
+    .get('/users', ({ db }) => db.query.users.findMany())
+```
+
+## State (Global Mutable State)
+
+```javascript
+const app = new Elysia()
+    .state('counter', 0)
+    .get('/count', ({ store }) => {
+        store.counter++
+        return { count: store.counter }
+    })
+```
+
+## Guard Pattern
+
+Apply validation/hooks to multiple routes:
+
+```javascript
+const app = new Elysia()
+    .guard({
+        beforeHandle: ({ headers, set }) => {
+            if (!headers.authorization) {
+                set.status = 401
+                return { error: 'Unauthorized' }
+            }
+        }
+    }, app => app
+        .get('/profile', () => getProfile())
+        .get('/settings', () => getSettings())
+        .put('/settings', ({ body }) => updateSettings(body))
+    )
+```
+
+## Group with Prefix
+
+```javascript
+const app = new Elysia()
+    .group('/api/v1', app => app
+        .get('/users', () => getUsers())
+        .get('/posts', () => getPosts())
+    )
+
+// Routes: /api/v1/users, /api/v1/posts
+```
+
+## Combining Guard + Group
+
+```javascript
+const app = new Elysia()
+    .group('/api/v1', app => app
+        // Public routes
+        .get('/health', () => ({ status: 'ok' }))
+
+        // Protected routes
+        .guard({
+            beforeHandle: requireAuth
+        }, app => app
+            .get('/profile', () => getProfile())
+            .put('/profile', ({ body }) => updateProfile(body))
+        )
+    )
+```
+
+## Plugin Scope
+
+### Local Scope (Default)
+
+Hooks only apply to the plugin and its children:
+
+```javascript
+const plugin = new Elysia()
+    .onBeforeHandle(() => console.log('Only in this plugin'))
+    .get('/local', () => 'Hello')
+
+app.use(plugin)
+app.get('/other', () => 'No hook here')
+```
+
+### Global Scope
+
+Hooks apply to all routes:
+
+```javascript
+const globalLogger = new Elysia()
+    .onBeforeHandle({ as: 'global' }, () => {
+        console.log('Runs on ALL routes')
+    })
+
+app.use(globalLogger)
+```
+
+## Recommended Structure
+
+```
+src/
+├── index.js              # Main app
+├── routes/
+│   ├── index.js          # Route aggregator
+│   ├── users.js          # User routes plugin
+│   ├── posts.js          # Post routes plugin
+│   └── auth.js           # Auth routes plugin
+├── plugins/
+│   ├── database.js       # DB connection plugin
+│   ├── logger.js         # Logging plugin
+│   └── cors.js           # CORS plugin
+├── services/
+│   ├── user.js           # User business logic
+│   └── post.js           # Post business logic
+└── middleware/
+    └── auth.js           # Auth middleware
+```
+
+## Route Aggregator Example
+
+```javascript
+// routes/index.js
+import { Elysia } from 'elysia'
+import { userRoutes } from './users'
+import { postRoutes } from './posts'
+import { authRoutes } from './auth'
+
+export const routes = new Elysia()
+    .use(authRoutes)
+    .use(userRoutes)
+    .use(postRoutes)
+
+// index.js
+import { routes } from './routes'
+
+const app = new Elysia()
+    .use(routes)
+    .listen(3000)
+```

package/.agent/skills/riligar-dev-backend/references/elysia-validation.md

@@ -0,0 +1,247 @@
+# Elysia Validation
+
+Elysia uses TypeBox for runtime validation. Import `t` from Elysia to define schemas.
+
+## Basic Validation
+
+```javascript
+import { Elysia, t } from 'elysia'
+
+const app = new Elysia()
+    .post('/users', ({ body }) => createUser(body), {
+        body: t.Object({
+            name: t.String(),
+            email: t.String()
+        })
+    })
+```
+
+## Validation Targets
+
+### Body Validation
+
+```javascript
+app.post('/users', ({ body }) => body, {
+    body: t.Object({
+        name: t.String(),
+        email: t.String({ format: 'email' }),
+        age: t.Number({ minimum: 0 })
+    })
+})
+```
+
+### Query Validation
+
+```javascript
+// GET /search?q=hello&limit=10
+app.get('/search', ({ query }) => search(query), {
+    query: t.Object({
+        q: t.String(),
+        limit: t.Optional(t.Numeric({ default: 10 }))
+    })
+})
+```
+
+### Params Validation
+
+```javascript
+app.get('/users/:id', ({ params }) => getUser(params.id), {
+    params: t.Object({
+        id: t.Numeric()
+    })
+})
+```
+
+### Headers Validation
+
+```javascript
+app.get('/protected', ({ headers }) => getData(), {
+    headers: t.Object({
+        authorization: t.String()
+    })
+})
+```
+
+## TypeBox Types
+
+### Primitives
+
+```javascript
+t.String()              // string
+t.Number()              // number
+t.Boolean()             // boolean
+t.Null()                // null
+t.Literal('active')     // exact value
+```
+
+### String Constraints
+
+```javascript
+t.String({ minLength: 1 })
+t.String({ maxLength: 100 })
+t.String({ format: 'email' })
+t.String({ format: 'uuid' })
+t.String({ pattern: '^[a-z]+$' })  // regex
+```
+
+### Number Constraints
+
+```javascript
+t.Number({ minimum: 0 })
+t.Number({ maximum: 100 })
+t.Number({ exclusiveMinimum: 0 })
+t.Integer()  // whole numbers only
+```
+
+### Numeric (String to Number)
+
+For query params that come as strings:
+
+```javascript
+t.Numeric()  // Converts "10" to 10
+t.Numeric({ minimum: 1, maximum: 100 })
+```
+
+### Optional & Nullable
+
+```javascript
+t.Optional(t.String())        // string | undefined
+t.Nullable(t.String())        // string | null
+t.Optional(t.Nullable(t.String()))  // string | null | undefined
+```
+
+### Default Values
+
+```javascript
+t.String({ default: 'guest' })
+t.Number({ default: 10 })
+t.Boolean({ default: false })
+```
+
+### Objects
+
+```javascript
+t.Object({
+    name: t.String(),
+    email: t.String(),
+    profile: t.Optional(t.Object({
+        bio: t.String(),
+        avatar: t.String()
+    }))
+})
+```
+
+### Arrays
+
+```javascript
+t.Array(t.String())                    // string[]
+t.Array(t.Number(), { minItems: 1 })   // at least 1 item
+t.Array(t.Object({ id: t.Number() }))  // object array
+```
+
+### Union (One of)
+
+```javascript
+t.Union([
+    t.Literal('active'),
+    t.Literal('inactive'),
+    t.Literal('pending')
+])
+
+// Or with different types
+t.Union([t.String(), t.Number()])
+```
+
+### Enum Pattern
+
+```javascript
+const Status = t.Union([
+    t.Literal('draft'),
+    t.Literal('published'),
+    t.Literal('archived')
+])
+
+app.post('/posts', ({ body }) => body, {
+    body: t.Object({
+        title: t.String(),
+        status: Status
+    })
+})
+```
+
+## Complete Example
+
+```javascript
+import { Elysia, t } from 'elysia'
+
+const CreateUserSchema = t.Object({
+    name: t.String({ minLength: 1, maxLength: 100 }),
+    email: t.String({ format: 'email' }),
+    age: t.Optional(t.Number({ minimum: 0 })),
+    role: t.Union([
+        t.Literal('user'),
+        t.Literal('admin')
+    ]),
+    tags: t.Optional(t.Array(t.String()))
+})
+
+const app = new Elysia()
+    .post('/users', ({ body }) => {
+        return createUser(body)
+    }, {
+        body: CreateUserSchema
+    })
+```
+
+## Custom Error Messages
+
+```javascript
+t.String({
+    minLength: 1,
+    error: 'Name is required'
+})
+
+t.Number({
+    minimum: 0,
+    error: 'Age must be positive'
+})
+```
+
+## Reusable Models
+
+Register schemas for reuse:
+
+```javascript
+const app = new Elysia()
+    .model({
+        user: t.Object({
+            name: t.String(),
+            email: t.String({ format: 'email' })
+        }),
+        pagination: t.Object({
+            page: t.Numeric({ default: 1 }),
+            limit: t.Numeric({ default: 10 })
+        })
+    })
+    .post('/users', ({ body }) => body, {
+        body: 'user'  // Reference by name
+    })
+    .get('/users', ({ query }) => query, {
+        query: 'pagination'
+    })
+```
+
+## Validation Error Handling
+
+```javascript
+const app = new Elysia()
+    .onError(({ code, error, set }) => {
+        if (code === 'VALIDATION') {
+            set.status = 422
+            return {
+                error: 'Validation failed',
+                details: error.all  // Array of all errors
+            }
+        }
+    })
+```