@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/elysia/elysiajs/references/route.md

@@ -0,0 +1,331 @@
+# ElysiaJS: Routing, Handlers & Context
+
+## Routing
+
+### Path Types
+
+```ts
+new Elysia()
+	.get('/static', 'static path')           // exact match
+	.get('/id/:id', 'dynamic path')          // captures segment
+	.get('/id/*', 'wildcard path')           // captures rest
+```
+
+**Path Priority**: static > dynamic > wildcard
+
+### Dynamic Paths
+
+```ts
+new Elysia()
+	.get('/id/:id', ({ params: { id } }) => id)
+	.get('/id/:id/:name', ({ params: { id, name } }) => id + ' ' + name)
+```
+
+**Optional params**: `.get('/id/:id?', ...)`
+
+### HTTP Verbs
+
+- `.get()` - retrieve data
+- `.post()` - submit/create
+- `.put()` - replace
+- `.patch()` - partial update
+- `.delete()` - remove
+- `.all()` - any method
+- `.route(method, path, handler)` - custom verb
+
+### Grouping Routes
+
+```ts
+new Elysia()
+	.group('/user', { body: t.Literal('auth') }, (app) =>
+		app.post('/sign-in', ...)
+			.post('/sign-up', ...)
+)
+
+// Or use prefix in constructor
+new Elysia({ prefix: '/user' })
+  .post('/sign-in', ...)
+```
+
+## Handlers
+
+### Handler = function accepting HTTP request, returning response
+
+```ts
+// Inline value (compiled ahead, optimized)
+.get('/', 'Hello Elysia')
+.get('/video', file('video.mp4'))
+
+// Function handler
+.get('/', () => 'hello')
+.get('/', ({ params, query, body }) => {...})
+```
+
+### Context Properties
+
+- `body` - HTTP message/form/file
+- `query` - query string as object
+- `params` - path parameters
+- `headers` - HTTP headers
+- `cookie` - mutable signal for cookies
+- `store` - global mutable state
+- `request` - Web Standard Request
+- `server` - Bun server instance
+- `path` - request pathname
+
+### Context Utilities
+
+```ts
+import { redirect, form } from 'elysia'
+
+new Elysia().get('/', ({ status, set, form }) => {
+    // Status code (type-safe)
+    status(418, "I'm a teapot")
+
+    // Set response props
+    set.headers['x-custom'] = 'value'
+    set.status = 418 // legacy, no type inference
+
+    // Redirect
+    return redirect('https://...', 302)
+
+    // Cookies (mutable signal, no get/set)
+    cookie.name.value // get
+    cookie.name.value = 'new' // set
+
+    // FormData response
+    return form({ name: 'Party', images: [file('a.jpg')] })
+
+    // Single file
+    return file('document.pdf')
+})
+```
+
+### Streaming
+
+```ts
+new Elysia()
+	.get('/stream', function* () {
+	  	yield 1
+	  	yield 2
+	  	yield 3
+	})
+	// Server-Sent Events
+	.get('/sse', function* () {
+	  	yield sse('hello')
+	  	yield sse({ event: 'msg', data: {...} })
+	})
+```
+
+**Note**: Headers only settable before first yield
+
+**Conditional stream**: returning without yield converts to normal response
+
+## Context Extension
+
+[Inference] Extend when property is:
+
+- Global mutable (use `state`)
+- Request/response related (use `decorate`)
+- Derived from existing props (use `derive`/`resolve`)
+
+### state() - Global Mutable
+
+```ts
+new Elysia()
+	`.state('version', 1)
+	.get('/', ({ store: { version } }) => version)
+	// Multiple
+	.state({ counter: 0, visits: 0 })
+	
+	// Remap (create new from existing)
+	.state(({ version, ...store }) => ({
+	  	...store,
+	  	apiVersion: version
+	}))
+````
+
+**Gotcha**: Use reference not value
+
+```ts
+new Elysia()
+	// ✅ Correct
+	.get('/', ({ store }) => store.counter++)
+	
+	// ❌ Wrong - loses reference
+	.get('/', ({ store: { counter } }) => counter++)
+```
+
+### decorate() - Additional Context Props
+
+```ts
+new Elysia()
+	.decorate('logger', new Logger())
+	.get('/', ({ logger }) => logger.log('hi'))
+	
+	// Multiple
+	.decorate({ logger: new Logger(), db: connection })
+```
+
+**When**: constant/readonly values, classes with internal state, singletons
+
+### derive() - Create from Existing (Transform Lifecycle)
+
+```ts
+new Elysia()
+	.derive(({ headers }) => ({
+	  	bearer: headers.authorization?.startsWith('Bearer ')
+	    	? headers.authorization.slice(7)
+		    : null
+	}))
+	.get('/', ({ bearer }) => bearer)
+```
+
+**Timing**: runs at transform (before validation)
+**Type safety**: request props typed as `unknown`
+
+### resolve() - Type-Safe Derive (beforeHandle Lifecycle)
+
+```ts
+new Elysia()
+	.guard({
+	  	headers: t.Object({
+	    	bearer: t.String({ pattern: '^Bearer .+$' })
+		})
+	})
+	.resolve(({ headers }) => ({
+	  	bearer: headers.bearer.slice(7)  // typed correctly
+	}))
+```
+
+**Timing**: runs at beforeHandle (after validation)
+**Type safety**: request props fully typed
+
+### Error from derive/resolve
+
+```ts
+new Elysia()
+	.derive(({ headers, status }) => {
+	  	if (!headers.authorization) return status(400)
+	  	return { bearer: ... }
+	})
+```
+
+Returns early if error returned
+
+## Patterns
+
+### Affix (Bulk Remap)
+
+```ts
+const plugin = new Elysia({ name: 'setup' }).decorate({
+    argon: 'a',
+    boron: 'b'
+})
+
+new Elysia()
+    .use(plugin)
+    .prefix('decorator', 'setup') // setupArgon, setupBoron
+    .prefix('all', 'setup') // remap everything
+```
+
+### Assignment Patterns
+
+1. **key-value**: `.state('key', value)`
+2. **object**: `.state({ k1: v1, k2: v2 })`
+3. **remap**: `.state(({old}) => ({new}))`
+
+## Testing
+
+```ts
+const app = new Elysia().get('/', 'hi')
+
+// Programmatic test
+app.handle(new Request('http://localhost/'))
+```
+
+## To Throw or Return
+
+Most of an error handling in Elysia can be done by throwing an error and will be handle in `onError`.
+
+But for `status` it can be a little bit confusing, since it can be used both as a return value or throw an error.
+
+It could either be **return** or **throw** based on your specific needs.
+
+- If an `status` is **throw**, it will be caught by `onError` middleware.
+- If an `status` is **return**, it will be **NOT** caught by `onError` middleware.
+
+See the following code:
+
+```typescript
+import { Elysia, file } from 'elysia'
+
+new Elysia()
+    .onError(({ code, error, path }) => {
+        if (code === 418) return 'caught'
+    })
+    .get('/throw', ({ status }) => {
+        // This will be caught by onError
+        throw status(418)
+    })
+    .get('/return', ({ status }) => {
+        // This will NOT be caught by onError
+        return status(418)
+    })
+```
+
+## To Throw or Return
+
+Elysia provide a `status` function for returning HTTP status code, prefers over `set.status`.
+
+`status` can be import from Elysia but preferably extract from route handler Context for type safety.
+
+```ts
+import { Elysia, status } from 'elysia'
+
+function doThing() {
+    if (Math.random() > 0.33) return status(418, "I'm a teapot")
+}
+
+new Elysia().get('/', ({ status }) => {
+    if (Math.random() > 0.33) return status(418)
+
+    return 'ok'
+})
+```
+
+Error Handling in Elysia can be done by throwing an error and will be handle in `onError`.
+
+Status could either be **return** or **throw** based on your specific needs.
+
+- If an `status` is **throw**, it will be caught by `onError` middleware.
+- If an `status` is **return**, it will be **NOT** caught by `onError` middleware.
+
+See the following code:
+
+```typescript
+import { Elysia, file } from 'elysia'
+
+new Elysia()
+    .onError(({ code, error, path }) => {
+        if (code === 418) return 'caught'
+    })
+    .get('/throw', ({ status }) => {
+        // This will be caught by onError
+        throw status(418)
+    })
+    .get('/return', ({ status }) => {
+        // This will NOT be caught by onError
+        return status(418)
+    })
+```
+
+## Notes
+
+[Inference] Based on docs patterns:
+
+- Use inline values for static resources (performance optimization)
+- Group routes by prefix for organization
+- Extend context minimally (separation of concerns)
+- Use `status()` over `set.status` for type safety
+- Prefer `resolve()` over `derive()` when type integrity matters

package/dist/skills/frameworks/elysia/elysiajs/references/testing.md

@@ -0,0 +1,385 @@
+# Unit Testing
+
+## Basic Test Setup
+
+### Installation
+```bash
+bun add -d @elysiajs/eden
+```
+
+### Basic Test
+```typescript
+// test/app.test.ts
+import { describe, expect, it } from 'bun:test'
+import { Elysia } from 'elysia'
+
+describe('Elysia App', () => {
+  it('should return hello world', async () => {
+    const app = new Elysia()
+      .get('/', () => 'Hello World')
+    
+    const res = await app.handle(
+      new Request('http://localhost/')
+    )
+    
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('Hello World')
+  })
+})
+```
+
+## Testing Routes
+
+### GET Request
+```typescript
+it('should get user by id', async () => {
+  const app = new Elysia()
+    .get('/user/:id', ({ params: { id } }) => ({
+      id,
+      name: 'John Doe'
+    }))
+  
+  const res = await app.handle(
+    new Request('http://localhost/user/123')
+  )
+  
+  const data = await res.json()
+  
+  expect(res.status).toBe(200)
+  expect(data).toEqual({
+    id: '123',
+    name: 'John Doe'
+  })
+})
+```
+
+### POST Request
+```typescript
+it('should create user', async () => {
+  const app = new Elysia()
+    .post('/user', ({ body }) => body)
+  
+  const res = await app.handle(
+    new Request('http://localhost/user', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        name: 'Jane Doe',
+        email: 'jane@example.com'
+      })
+    })
+  )
+  
+  const data = await res.json()
+  
+  expect(res.status).toBe(200)
+  expect(data.name).toBe('Jane Doe')
+})
+```
+
+## Testing Module/Plugin
+
+### Module Structure
+```
+src/
+├── modules/
+│   └── auth/
+│       ├── index.ts     # Elysia instance
+│       ├── service.ts
+│       └── model.ts
+└── index.ts
+```
+
+### Auth Module
+```typescript
+// src/modules/auth/index.ts
+import { Elysia, t } from 'elysia'
+
+export const authModule = new Elysia({ prefix: '/auth' })
+  .post('/login', ({ body, cookie: { session } }) => {
+    if (body.username === 'admin' && body.password === 'password') {
+      session.value = 'valid-session'
+      return { success: true }
+    }
+    return { success: false }
+  }, {
+    body: t.Object({
+      username: t.String(),
+      password: t.String()
+    })
+  })
+  .get('/profile', ({ cookie: { session }, status }) => {
+    if (!session.value) {
+      return status(401, { error: 'Unauthorized' })
+    }
+    return { username: 'admin' }
+  })
+```
+
+### Auth Module Test
+```typescript
+// test/auth.test.ts
+import { describe, expect, it } from 'bun:test'
+import { authModule } from '../src/modules/auth'
+
+describe('Auth Module', () => {
+  it('should login successfully', async () => {
+    const res = await authModule.handle(
+      new Request('http://localhost/auth/login', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          username: 'admin',
+          password: 'password'
+        })
+      })
+    )
+    
+    const data = await res.json()
+    expect(res.status).toBe(200)
+    expect(data.success).toBe(true)
+  })
+  
+  it('should reject invalid credentials', async () => {
+    const res = await authModule.handle(
+      new Request('http://localhost/auth/login', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          username: 'wrong',
+          password: 'wrong'
+        })
+      })
+    )
+    
+    const data = await res.json()
+    expect(data.success).toBe(false)
+  })
+  
+  it('should return 401 for unauthenticated profile request', async () => {
+    const res = await authModule.handle(
+      new Request('http://localhost/auth/profile')
+    )
+    
+    expect(res.status).toBe(401)
+  })
+})
+```
+
+## Eden Treaty Testing
+
+### Setup
+```typescript
+import { treaty } from '@elysiajs/eden'
+import { app } from '../src/modules/auth'
+
+const api = treaty(app)
+```
+
+### Eden Tests
+```typescript
+describe('Auth Module with Eden', () => {
+  it('should login with Eden', async () => {
+    const { data, error } = await api.auth.login.post({
+      username: 'admin',
+      password: 'password'
+    })
+    
+    expect(error).toBeNull()
+    expect(data?.success).toBe(true)
+  })
+  
+  it('should get profile with Eden', async () => {
+    // First login
+    await api.auth.login.post({
+      username: 'admin',
+      password: 'password'
+    })
+    
+    // Then get profile
+    const { data, error } = await api.auth.profile.get()
+    
+    expect(error).toBeNull()
+    expect(data?.username).toBe('admin')
+  })
+})
+```
+
+## Mocking Dependencies
+
+### With Decorators
+```typescript
+// app.ts
+export const app = new Elysia()
+  .decorate('db', realDatabase)
+  .get('/users', ({ db }) => db.getUsers())
+
+// test
+import { app } from '../src/app'
+
+describe('App with mocked DB', () => {
+  it('should use mock database', async () => {
+    const mockDb = {
+      getUsers: () => [{ id: 1, name: 'Test User' }]
+    }
+    
+    const testApp = app.decorate('db', mockDb)
+    
+    const res = await testApp.handle(
+      new Request('http://localhost/users')
+    )
+    
+    const data = await res.json()
+    expect(data).toEqual([{ id: 1, name: 'Test User' }])
+  })
+})
+```
+
+## Testing with Headers
+
+```typescript
+it('should require authorization', async () => {
+  const app = new Elysia()
+    .get('/protected', ({ headers, status }) => {
+      if (!headers.authorization) {
+        return status(401)
+      }
+      return { data: 'secret' }
+    })
+  
+  const res = await app.handle(
+    new Request('http://localhost/protected', {
+      headers: {
+        'Authorization': 'Bearer token123'
+      }
+    })
+  )
+  
+  expect(res.status).toBe(200)
+})
+```
+
+## Testing Validation
+
+```typescript
+import { Elysia, t } from 'elysia'
+
+it('should validate request body', async () => {
+  const app = new Elysia()
+    .post('/user', ({ body }) => body, {
+      body: t.Object({
+        name: t.String(),
+        age: t.Number({ minimum: 0 })
+      })
+    })
+  
+  // Valid request
+  const validRes = await app.handle(
+    new Request('http://localhost/user', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        name: 'John',
+        age: 25
+      })
+    })
+  )
+  expect(validRes.status).toBe(200)
+  
+  // Invalid request (negative age)
+  const invalidRes = await app.handle(
+    new Request('http://localhost/user', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        name: 'John',
+        age: -5
+      })
+    })
+  )
+  expect(invalidRes.status).toBe(400)
+})
+```
+
+## Testing WebSocket
+
+```typescript
+it('should handle websocket connection', (done) => {
+  const app = new Elysia()
+    .ws('/chat', {
+      message(ws, message) {
+        ws.send('Echo: ' + message)
+      }
+    })
+  
+  const ws = new WebSocket('ws://localhost:3000/chat')
+  
+  ws.onopen = () => {
+    ws.send('Hello')
+  }
+  
+  ws.onmessage = (event) => {
+    expect(event.data).toBe('Echo: Hello')
+    ws.close()
+    done()
+  }
+})
+```
+
+## Complete Example
+
+```typescript
+// src/modules/auth/index.ts
+import { Elysia, t } from 'elysia'
+
+export const authModule = new Elysia({ prefix: '/auth' })
+  .post('/login', ({ body, cookie: { session } }) => {
+    if (body.username === 'admin' && body.password === 'password') {
+      session.value = 'valid-session'
+      return { success: true }
+    }
+    return { success: false }
+  }, {
+    body: t.Object({
+      username: t.String(),
+      password: t.String()
+    })
+  })
+  .get('/profile', ({ cookie: { session }, status }) => {
+    if (!session.value) {
+      return status(401)
+    }
+    return { username: 'admin' }
+  })
+
+// test/auth.test.ts
+import { describe, expect, it } from 'bun:test'
+import { treaty } from '@elysiajs/eden'
+import { authModule } from '../src/modules/auth'
+
+const api = treaty(authModule)
+
+describe('Auth Module', () => {
+  it('should login successfully', async () => {
+    const { data, error } = await api.auth.login.post({
+      username: 'admin',
+      password: 'password'
+    })
+    
+    expect(error).toBeNull()
+    expect(data?.success).toBe(true)
+  })
+  
+  it('should return 401 for unauthorized access', async () => {
+    const { error } = await api.auth.profile.get()
+    
+    expect(error?.status).toBe(401)
+  })
+})
+```