@punks/cli 0.1.15 → 1.0.0

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

@@ -0,0 +1,198 @@
+# Lifecycle
+
+Instead of a sequential process, Elysia's request handling is divided into multiple stages called lifecycle events.
+
+It's designed to separate the process into distinct phases based on their responsibility without interfering with each others.
+
+### List of events in order
+
+1. **request** - early, global
+2. **parse** - body parsing
+3. **transform** / **derive** - mutate context pre validation
+4. **beforeHandle** / **resolve** - auth/guard logic
+5. **handler** - your business code
+6. **afterHandle** - tweak response, set headers
+7. **mapResponse** - turn anything into a proper `Response`
+8. **onError** - centralized error handling
+9. **onAfterResponse** - post response/cleanup tasks
+
+## Request (`onRequest`)
+
+Runs first for every incoming request.
+
+- Ideal for **caching, rate limiting, CORS, adding global headers**.
+- If the hook returns a value, the whole lifecycle stops and that value becomes the response.
+
+```ts
+new Elysia().onRequest(({ ip, set }) => {
+    if (blocked(ip)) return (set.status = 429)
+})
+```
+
+---
+
+## Parse (`onParse`)
+
+_Body parsing stage._
+
+- Handles `text/plain`, `application/json`, `multipart/form-data`, `application/x www-form-urlencoded` by default.
+- Use to add **custom parsers** or support extra `Content Type`s.
+
+```ts
+new Elysia().onParse(({ request, contentType }) => {
+    if (contentType === 'application/custom') return request.text()
+})
+```
+
+---
+
+## Transform (`onTransform`)
+
+_Runs **just before validation**; can mutate the request context._
+
+- Perfect for **type coercion**, trimming strings, or adding temporary fields that validation will use.
+
+```ts
+new Elysia().onTransform(({ params }) => {
+    params.id = Number(params.id)
+})
+```
+
+---
+
+## Derive
+
+_Runs along with `onTransform` **but before validation**; adds per request values to the context._
+
+- Useful for extracting info from headers, cookies, query, etc., that you want to reuse in handlers.
+
+```ts
+new Elysia().derive(({ headers }) => ({
+    bearer: headers.authorization?.replace(/^Bearer /, '')
+}))
+```
+
+---
+
+## Before Handle (`onBeforeHandle`)
+
+_Executed after validation, right before the route handler._
+
+- Great for **auth checks, permission gating, custom pre validation logic**.
+- Returning a value skips the handler.
+
+```ts
+new Elysia().get('/', () => 'hi', {
+    beforeHandle({ cookie, status }) {
+        if (!cookie.session) return status(401)
+    }
+})
+```
+
+---
+
+## Resolve
+
+_Like `derive` but runs **after validation** along "Before Handle" (so you can rely on validated data)._
+
+- Usually placed inside a `guard` because it isn't available as a local hook.
+
+```ts
+new Elysia().guard(
+    { headers: t.Object({ authorization: t.String() }) },
+    (app) =>
+        app
+            .resolve(({ headers }) => ({
+                bearer: headers.authorization.split(' ')[1]
+            }))
+            .get('/', ({ bearer }) => bearer)
+)
+```
+
+---
+
+## After Handle (`onAfterHandle`)
+
+_Runs after the handler finishes._
+
+- Can **modify response headers**, wrap the result in a `Response`, or transform the payload.
+- Returning a value **replaces** the handler’s result, but the next `afterHandle` hooks still run.
+
+```ts
+new Elysia().get('/', () => '<h1>Hello</h1>', {
+    afterHandle({ response, set }) {
+        if (isHtml(response)) {
+            set.headers['content-type'] = 'text/html; charset=utf-8'
+            return new Response(response)
+        }
+    }
+})
+```
+
+---
+
+## Map Response (`mapResponse`)
+
+_Runs right after all `afterHandle` hooks; maps **any** value to a Web standard `Response`._
+
+- Ideal for **compression, custom content type mapping, streaming**.
+
+```ts
+new Elysia().mapResponse(({ responseValue, set }) => {
+    const body =
+        typeof responseValue === 'object'
+            ? JSON.stringify(responseValue)
+            : String(responseValue ?? '')
+
+    set.headers['content-encoding'] = 'gzip'
+    return new Response(Bun.gzipSync(new TextEncoder().encode(body)), {
+        headers: {
+            'Content-Type':
+                typeof responseValue === 'object'
+                    ? 'application/json'
+                    : 'text/plain'
+        }
+    })
+})
+```
+
+---
+
+## On Error (`onError`)
+
+_Caught whenever an error bubbles up from any lifecycle stage._
+
+- Use to **customize error messages**, **handle 404**, **log**, or **retry**.
+- Must be registered **before** the routes it should protect.
+
+```ts
+new Elysia().onError(({ code, status }) => {
+    if (code === 'NOT_FOUND') return status(404, '❓ Not found')
+    return new Response('Oops', { status: 500 })
+})
+```
+
+---
+
+## After Response (`onAfterResponse`)
+
+_Runs **after** the response has been sent to the client._
+
+- Perfect for **logging, metrics, cleanup**.
+
+```ts
+new Elysia().onAfterResponse(() =>
+    console.log('✅ response sent at', Date.now())
+)
+```
+
+---
+
+## Hook Types
+
+| Type                 | Scope                             | How to add                                                |
+| -------------------- | --------------------------------- | --------------------------------------------------------- |
+| **Local Hook**       | Single route                      | Inside route options (`afterHandle`, `beforeHandle`, …) |
+| **Interceptor Hook** | Whole instance (and later routes) | `.onXxx(cb)` or `.use(plugin)`                            |
+
+> **Remember:** Hooks only affect routes **defined after** they are registered, except `onRequest` which is global because it runs before route matching.

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

@@ -0,0 +1,83 @@
+# Macro
+
+Composable Elysia function for controlling lifecycle/schema/context with full type safety. Available in hook after definition control by key-value label.
+
+## Basic Pattern
+```typescript
+.macro({
+  hi: (word: string) => ({
+    beforeHandle() { console.log(word) }
+  })
+})
+.get('/', () => 'hi', { hi: 'Elysia' })
+```
+
+## Property Shorthand
+Object → function accepting boolean:
+```typescript
+.macro({
+	// These equivalent:
+	isAuth: { resolve: () => ({ user: 'saltyaom' }) },
+	isAuth(enabled: boolean) { if(enabled) return { resolve() {...} } }
+})
+```
+
+## Error Handling
+Return `status`, don't throw:
+```typescript
+.macro({
+  auth: {
+    resolve({ headers }) {
+      if(!headers.authorization) return status(401, 'Unauthorized')
+      return { user: 'SaltyAom' }
+    }
+  }
+})
+```
+
+## Resolve - Add Context Props
+```typescript
+.macro({
+  user: (enabled: true) => ({
+    resolve: () => ({ user: 'Pardofelis' })
+  })
+})
+.get('/', ({ user }) => user, { user: true })
+```
+
+### Named Macro for Type Inference
+TypeScript limitation workaround:
+```typescript
+.macro('user', { resolve: () => ({ user: 'lilith' }) })
+.macro('user2', { user: true, resolve: ({ user }) => {} })
+```
+
+## Schema
+Auto-validates, infers types, stacks with other schemas:
+```typescript
+.macro({
+  withFriends: {
+    body: t.Object({ friends: t.Tuple([...]) })
+  }
+})
+```
+
+Use named single macro for lifecycle type inference within same macro.
+
+## Extension
+Stack macros:
+```typescript
+.macro({
+  sartre: { body: t.Object({...}) },
+  fouco: { body: t.Object({...}) },
+  lilith: { fouco: true, sartre: true, body: t.Object({...}) }
+})
+```
+
+## Deduplication
+Auto-dedupes by property value. Custom seed:
+```typescript
+.macro({ sartre: (role: string) => ({ seed: role, ... }) })
+```
+
+Max stack: 16 (prevents infinite loops)

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

@@ -0,0 +1,207 @@
+# Plugins
+
+## Plugin = Decoupled Elysia Instance
+
+```ts
+const plugin = new Elysia()
+  .decorate('plugin', 'hi')
+  .get('/plugin', ({ plugin }) => plugin)
+
+const app = new Elysia()
+  .use(plugin)  // inherit properties
+  .get('/', ({ plugin }) => plugin)
+```
+
+**Inherits**: state, decorate
+**Does NOT inherit**: lifecycle (isolated by default)
+
+## Dependency
+
+Each instance runs independently like microservice. **Must explicitly declare dependencies**.
+
+```ts
+const auth = new Elysia()
+  .decorate('Auth', Auth)
+
+// ❌ Missing dependency
+const main = new Elysia()
+  .get('/', ({ Auth }) => Auth.getProfile())
+
+// ✅ Declare dependency
+const main = new Elysia()
+  .use(auth)  // required for Auth
+  .get('/', ({ Auth }) => Auth.getProfile())
+```
+
+## Deduplication
+
+**Every plugin re-executes by default**. Use `name` + optional `seed` to deduplicate:
+
+```ts
+const ip = new Elysia({ name: 'ip' })  // unique identifier
+  .derive({ as: 'global' }, ({ server, request }) => ({
+    ip: server?.requestIP(request)
+  }))
+
+const router1 = new Elysia().use(ip)
+const router2 = new Elysia().use(ip)
+const server = new Elysia().use(router1).use(router2)
+// `ip` only executes once due to deduplication
+```
+
+## Global vs Explicit Dependency
+
+**Global plugin** (rare, apply everywhere):
+- Doesn't add types - cors, compress, helmet
+- Global lifecycle no instance controls - tracing, logging
+- Examples: OpenAPI docs, OpenTelemetry, logging
+
+**Explicit dependency** (default, recommended):
+- Adds types - macro, state, model
+- Business logic instances interact with - Auth, DB
+- Examples: state management, ORM, auth, features
+
+## Scope
+
+**Lifecycle isolated by default**. Must specify scope to export.
+
+```ts
+// ❌ NOT inherited by app
+const profile = new Elysia()
+  .onBeforeHandle(({ cookie }) => throwIfNotSignIn(cookie))
+  .get('/profile', () => 'Hi')
+
+const app = new Elysia()
+  .use(profile)
+  .patch('/rename', ({ body }) => updateProfile(body))  // No sign-in check
+
+// ✅ Exported to app
+const profile = new Elysia()
+  .onBeforeHandle({ as: 'global' }, ({ cookie }) => throwIfNotSignIn(cookie))
+  .get('/profile', () => 'Hi')
+```
+
+## Scope Levels
+
+1. **local** (default) - current + descendants only
+2. **scoped** - parent + current + descendants  
+3. **global** - all instances (all parents, current, descendants)
+
+Example with `.onBeforeHandle({ as: 'local' }, ...)`:
+
+| type | child | current | parent | main |
+|------|-------|---------|--------|------|
+| local | ✅ | ✅ | ❌ | ❌ |
+| scoped | ✅ | ✅ | ✅ | ❌ |
+| global | ✅ | ✅ | ✅ | ✅ |
+
+## Config
+
+```ts
+// Instance factory with config
+const version = (v = 1) => new Elysia()
+  .get('/version', v)
+
+const app = new Elysia()
+  .use(version(1))
+```
+
+## Functional Callback (not recommended)
+
+```ts
+// Harder to handle scope/encapsulation
+const plugin = (app: Elysia) => app
+  .state('counter', 0)
+  .get('/plugin', () => 'Hi')
+
+// Prefer new instance (better type inference, no perf diff)
+```
+
+## Guard (Apply to Multiple Routes)
+
+```ts
+.guard(
+  { body: t.Object({ username: t.String(), password: t.String() }) },
+  (app) =>
+    app.post('/sign-up', ({ body }) => signUp(body))
+       .post('/sign-in', ({ body }) => signIn(body))
+)
+```
+
+**Grouped guard** (merge group + guard):
+
+```ts
+.group(
+  '/v1',
+  { body: t.Literal('Rikuhachima Aru') },  // guard here
+  (app) => app.post('/student', ({ body }) => body)
+)
+```
+
+## Scope Casting
+
+**3 methods to apply hook to parent**:
+
+1. **Inline as** (single hook):
+```ts
+.derive({ as: 'scoped' }, () => ({ hi: 'ok' }))
+```
+
+2. **Guard as** (multiple hooks, no derive/resolve):
+```ts
+.guard({
+  as: 'scoped',
+  response: t.String(),
+  beforeHandle() { console.log('ok') }
+})
+```
+
+3. **Instance as** (all hooks + schema):
+```ts
+const plugin = new Elysia()
+  .derive(() => ({ hi: 'ok' }))
+  .get('/child', ({ hi }) => hi)
+  .as('scoped')  // lift scope up
+```
+
+`.as()` lifts scope: local → scoped → global
+
+## Lazy Load
+
+**Deferred module** (async plugin, non-blocking startup):
+
+```ts
+// plugin.ts
+export const loadStatic = async (app: Elysia) => {
+  const files = await loadAllFiles()
+  files.forEach((asset) => app.get(asset, file(asset)))
+  return app
+}
+
+// main.ts
+const app = new Elysia().use(loadStatic)
+```
+
+**Lazy-load module** (dynamic import):
+
+```ts
+const app = new Elysia()
+  .use(import('./plugin'))  // loaded after startup
+```
+
+**Testing** (wait for modules):
+
+```ts
+await app.modules  // ensure all deferred/lazy modules loaded
+```
+
+## 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
+- Plugins isolated by default (must declare scope explicitly)
+- Use `name` for deduplication when plugin used multiple times
+- Prefer explicit dependency over global (better modularity/tracking)