@tamayrp14/fire-api 0.0.0-stage → 1.0.0

package/test/openapi.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test';
+import { Router } from '../src/core/router';
+import { s } from '../src/schema/schema';
+import { generateOpenAPISpec } from '../src/schema/openapi';
+import { renderScalarDocsHTML } from '../src/docs/scalar-ui';
+
+describe('FireAPI OpenAPI 3.1 & Scalar Documentation Engine', () => {
+  it('generates compliant OpenAPI 3.1 specification from routes and schemas', () => {
+    const router = new Router();
+
+    router.post('/users', {
+      ai: { description: 'Create user' },
+      schema: {
+        body: s.object({
+          name: s.string().min(2),
+          email: s.string().email(),
+        }),
+      },
+      handler: (ctx) => ctx.created({}),
+    });
+
+    const spec = generateOpenAPISpec(router, {
+      title: 'Test FireAPI',
+      version: '1.0.0',
+    });
+
+    expect(spec.openapi).toBe('3.1.0');
+    expect(spec.info.title).toBe('Test FireAPI');
+    expect(spec.paths['/users']).toBeDefined();
+    expect(spec.paths['/users'].post).toBeDefined();
+    expect(spec.paths['/users'].post.requestBody.content['application/json'].schema.type).toBe('object');
+  });
+
+  it('renders modern Scalar interactive documentation HTML', () => {
+    const html = renderScalarDocsHTML('/openapi.json', 'My Fire API Docs');
+    expect(html).toContain('<!DOCTYPE html>');
+    expect(html).toContain('@scalar/api-reference');
+    expect(html).toContain('/openapi.json');
+    expect(html).toContain('My Fire API Docs');
+  });
+});

package/test/orm-relations.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter } from '../src/index';
+
+describe('FireAPI Ultra-Simple Relational Proxy ORM (.include())', () => {
+  it('eager-loads one-to-many relations using ctx.db.users.include("posts").findById(id)', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+    const router = createRouter();
+
+    // 1. Seed data
+    const user = await app.db.users.insert({ id: 'u100', name: 'Devin', role: 'admin' });
+    await app.db.posts.insert([
+      { id: 'p1', userId: 'u100', title: 'First Post', published: true },
+      { id: 'p2', userId: 'u100', title: 'Second Post', published: false },
+      { id: 'p3', userId: 'other_user', title: 'Unrelated Post', published: true },
+    ]);
+
+    router.get('/users/:id', async (ctx) => {
+      const result = await ctx.db.users.include('posts').findById(ctx.params.id);
+      if (!result) return ctx.notFound('User not found');
+      return ctx.ok(result);
+    });
+
+    app.use(router);
+
+    const res = await app.handle(
+      new Request('http://localhost:3000/users/u100', { method: 'GET' })
+    );
+
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.id).toBe('u100');
+    expect(data.name).toBe('Devin');
+    expect(Array.isArray(data.posts)).toBe(true);
+    expect(data.posts.length).toBe(2);
+    expect(data.posts[0].title).toBe('First Post');
+    expect(data.posts[1].title).toBe('Second Post');
+  });
+
+  it('eager-loads many-to-one parent relations using ctx.db.posts.include("user").findById(id)', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+
+    await app.db.users.insert({ id: 'u200', name: 'Grace Hopper' });
+    await app.db.posts.insert({ id: 'p50', userId: 'u200', title: 'Compilers in Practice' });
+
+    const post = await app.db.posts.include('user').findById('p50');
+
+    expect(post).not.toBeNull();
+    expect(post.title).toBe('Compilers in Practice');
+    expect(post.user).toBeDefined();
+    expect(post.user.name).toBe('Grace Hopper');
+    expect(post.user.id).toBe('u200');
+  });
+
+  it('eager-loads multiple relations across array results using .include(["posts", "profile"]).find()', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+
+    await app.db.users.insert([
+      { id: 'u1', name: 'User One' },
+      { id: 'u2', name: 'User Two' },
+    ]);
+
+    await app.db.posts.insert([
+      { id: 'p1', userId: 'u1', title: 'U1 Post' },
+      { id: 'p2', userId: 'u2', title: 'U2 Post' },
+    ]);
+
+    await app.db.profiles.insert([
+      { id: 'prof1', userId: 'u1', bio: 'Bio 1' },
+      { id: 'prof2', userId: 'u2', bio: 'Bio 2' },
+    ]);
+
+    const users = await app.db.users.include(['posts', 'profile']).find();
+
+    expect(users.length).toBe(2);
+    expect(users[0].posts.length).toBe(1);
+    expect(users[0].posts[0].title).toBe('U1 Post');
+    expect(users[0].profile).toBeDefined();
+    expect(users[0].profile.bio).toBe('Bio 1');
+
+    expect(users[1].posts.length).toBe(1);
+    expect(users[1].posts[0].title).toBe('U2 Post');
+    expect(users[1].profile).toBeDefined();
+    expect(users[1].profile.bio).toBe('Bio 2');
+  });
+});

package/test/orm-shortcuts.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp } from '../src/index';
+
+describe('FireAPI Ultra-Simple Proxy ORM Shortcuts', () => {
+  it('supports direct table property access: ctx.db.products.delete(id)', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+
+    // 1. Insert via shortcut: ctx.db.products.insert(...)
+    const product = await app.db.products.insert({
+      title: 'Gaming Mouse',
+      price: 50,
+      category: 'hardware',
+    });
+    expect(product.id).toBeDefined();
+    expect(product.title).toBe('Gaming Mouse');
+
+    // 2. Find by ID via shortcut: ctx.db.products.findById(id)
+    const found = await app.db.products.findById(product.id);
+    expect(found?.title).toBe('Gaming Mouse');
+
+    // 3. Find with object filter: ctx.db.products.find({ category: 'hardware' })
+    const hardwares = await app.db.products.find({ category: 'hardware' });
+    expect(hardwares.length).toBe(1);
+
+    // 4. Update by ID via shortcut: ctx.db.products.update(id, data)
+    const updated = await app.db.products.update(product.id, { price: 45 });
+    expect(updated.price).toBe(45);
+
+    // 5. Delete by ID via shortcut: ctx.db.products.delete(id)
+    const deleteResult = await app.db.products.delete(product.id);
+    expect(deleteResult.count).toBe(1);
+
+    // Verify deleted
+    const remaining = await app.db.products.findById(product.id);
+    expect(remaining).toBeNull();
+  });
+
+  it('supports delete by filter object: ctx.db.products.delete({ category: "old" })', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+
+    await app.db.items.insert({ title: 'Item 1', status: 'archived' });
+    await app.db.items.insert({ title: 'Item 2', status: 'archived' });
+    await app.db.items.insert({ title: 'Item 3', status: 'active' });
+
+    const del = await app.db.items.delete({ status: 'archived' });
+    expect(del.count).toBe(2);
+
+    const activeList = await app.db.items.find();
+    expect(activeList.length).toBe(1);
+    expect(activeList[0].status).toBe('active');
+  });
+});

package/test/rbac.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter } from '../src/index';
+
+describe('FireAPI Granular RBAC & Policy Gates', () => {
+  it('enforces role requirements (roles: ["admin"]) and blocks unauthorized roles with 403', async () => {
+    const app = createApp();
+    const router = createRouter('/admin');
+
+    // Attach user to context for simulation
+    const setRole = (role: string) => async (ctx: any, next: any) => {
+      ctx.user = { id: 'u1', role };
+      return next();
+    };
+
+    router.get('/dashboard', {
+      roles: ['admin', 'superadmin'],
+      handler: (ctx) => ctx.ok({ secret: 'admin-portal' }),
+    });
+
+    app.use(router);
+
+    // 1. User with 'member' role -> 403 Forbidden
+    const memberApp = createApp();
+    memberApp.use(setRole('member'));
+    memberApp.use(router);
+
+    const forbiddenRes = await memberApp.handle(new Request('http://localhost:3000/admin/dashboard'));
+    expect(forbiddenRes.status).toBe(403);
+    const errData = await forbiddenRes.json();
+    expect(errData.error).toBe('Forbidden');
+
+    // 2. User with 'admin' role -> 200 OK
+    const adminApp = createApp();
+    adminApp.use(setRole('admin'));
+    adminApp.use(router);
+
+    const okRes = await adminApp.handle(new Request('http://localhost:3000/admin/dashboard'));
+    expect(okRes.status).toBe(200);
+    expect((await okRes.json()).secret).toBe('admin-portal');
+  });
+
+  it('evaluates dynamic resource policy gates (can: async (user, ctx) => boolean)', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+    await app.db.table('articles').insert({ id: 'art_1', authorId: 'author_123', title: 'Post 1' });
+
+    const router = createRouter('/articles');
+
+    router.delete('/:id', {
+      can: async (user, ctx) => {
+        const article = await ctx.db.table('articles').findById(ctx.params.id);
+        return user?.id === article?.authorId || user?.role === 'admin';
+      },
+      handler: async (ctx) => {
+        await ctx.db.table('articles').where('id', ctx.params.id).delete();
+        return ctx.ok({ deleted: true });
+      },
+    });
+
+    app.use(router);
+
+    // 1. Other user trying to delete -> 403 Forbidden
+    const unauthApp = createApp();
+    unauthApp.db = app.db;
+    unauthApp.use(async (ctx, next) => {
+      ctx.user = { id: 'other_user', role: 'member' };
+      return next();
+    });
+    unauthApp.use(router);
+
+    const failRes = await unauthApp.handle(new Request('http://localhost:3000/articles/art_1', { method: 'DELETE' }));
+    expect(failRes.status).toBe(403);
+
+    // 2. Author user deleting own article -> 200 OK
+    const authorApp = createApp();
+    authorApp.db = app.db;
+    authorApp.use(async (ctx, next) => {
+      ctx.user = { id: 'author_123', role: 'member' };
+      return next();
+    });
+    authorApp.use(router);
+
+    const successRes = await authorApp.handle(new Request('http://localhost:3000/articles/art_1', { method: 'DELETE' }));
+    expect(successRes.status).toBe(200);
+  });
+});

package/test/router-fastpath.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'bun:test';
+import { Router } from '../src/core/router';
+
+describe('FireAPI JIT Route Fast-Path Cache', () => {
+  it('hits fast-path cache for identical and variable parameter lookups', () => {
+    const router = new Router();
+    router.get('/products/:id', {
+      handler: (ctx) => ctx.ok({ id: ctx.params.id }),
+    });
+
+    // 1st lookup - Misses cache, populates fast-path
+    const match1 = router.match('GET', '/products/100');
+    expect(match1).not.toBeNull();
+    expect(match1?.params.id).toBe('100');
+
+    // 2nd lookup on same URL - Hits fast-path cache
+    const match2 = router.match('GET', '/products/100');
+    expect(match2).not.toBeNull();
+    expect(match2?.params.id).toBe('100');
+
+    // 3rd lookup with different param - Correctly extracts new param
+    const match3 = router.match('GET', '/products/200');
+    expect(match3).not.toBeNull();
+    expect(match3?.params.id).toBe('200');
+  });
+
+  it('demonstrates extreme sub-microsecond lookup speed across 10,000 iterations', () => {
+    const router = new Router();
+    router.get('/api/v1/users/:userId/orders/:orderId', {
+      handler: () => 'ok',
+    });
+
+    const start = performance.now();
+    for (let i = 0; i < 10000; i++) {
+      router.match('GET', '/api/v1/users/42/orders/999');
+    }
+    const duration = performance.now() - start;
+
+    // 10,000 matches should complete in under 20ms (averaging < 0.002ms per match!)
+    expect(duration).toBeLessThan(20);
+  });
+});

package/test/router.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'bun:test';
+import { Router } from '../src/core/router';
+
+describe('FireAPI Core Router', () => {
+  it('registers and matches static routes', () => {
+    const router = new Router();
+    router.get('/health', {
+      handler: (ctx) => ctx.json({ status: 'ok' }),
+    });
+
+    const match = router.match('GET', '/health');
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({});
+  });
+
+  it('matches routes with dynamic path parameters', () => {
+    const router = new Router();
+    router.get('/users/:id', {
+      handler: (ctx) => ctx.json({ id: ctx.params.id }),
+    });
+
+    const match = router.match('GET', '/users/usr_123');
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({ id: 'usr_123' });
+  });
+
+  it('matches nested routes with multiple parameters', () => {
+    const router = new Router();
+    router.get('/orgs/:orgId/members/:memberId', {
+      handler: (ctx) => ctx.json({}),
+    });
+
+    const match = router.match('GET', '/orgs/google/members/42');
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({ orgId: 'google', memberId: '42' });
+  });
+
+  it('handles wildcards (*)', () => {
+    const router = new Router();
+    router.get('/assets/*', {
+      handler: (ctx) => ctx.text('asset'),
+    });
+
+    const match = router.match('GET', '/assets/css/style.css');
+    expect(match).not.toBeNull();
+    expect(match?.params['*']).toBe('css/style.css');
+  });
+
+  it('differentiates HTTP methods', () => {
+    const router = new Router();
+    router.get('/items', { handler: () => 'get' });
+    router.post('/items', { handler: () => 'post' });
+
+    const getMatch = router.match('GET', '/items');
+    const postMatch = router.match('POST', '/items');
+    const putMatch = router.match('PUT', '/items');
+
+    expect(getMatch).not.toBeNull();
+    expect(postMatch).not.toBeNull();
+    expect(putMatch).toBeNull();
+  });
+
+  it('supports prefix-based sub-router mounting', () => {
+    const rootRouter = new Router();
+    const apiRouter = new Router();
+    const userRouter = new Router();
+
+    userRouter.get('/:id', { handler: () => 'user' });
+    apiRouter.use('/users', userRouter);
+    rootRouter.use('/api/v1', apiRouter);
+
+    const match = rootRouter.match('GET', '/api/v1/users/777');
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({ id: '777' });
+  });
+
+  it('normalizes trailing slashes properly', () => {
+    const router = new Router();
+    router.get('/dashboard', { handler: () => 'dash' });
+
+    expect(router.match('GET', '/dashboard/')).not.toBeNull();
+    expect(router.match('GET', '/dashboard')).not.toBeNull();
+  });
+});

package/test/schema.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'bun:test';
+import { s, Infer } from '../src/schema/schema';
+import { validate } from '../src/schema/validator';
+
+describe('FireAPI FireSchema Validation Engine', () => {
+  it('validates string constraints (min, max, email)', () => {
+    const emailSchema = s.string().email();
+    expect(validate(emailSchema, 'user@example.com').success).toBe(true);
+    expect(validate(emailSchema, 'invalid-email').success).toBe(false);
+
+    const lengthSchema = s.string().min(3).max(10);
+    expect(validate(lengthSchema, 'ab').success).toBe(false);
+    expect(validate(lengthSchema, 'valid').success).toBe(true);
+    expect(validate(lengthSchema, 'too-long-string-here').success).toBe(false);
+  });
+
+  it('validates numbers with int and ranges', () => {
+    const ageSchema = s.number().int().min(18).max(120);
+    expect(validate(ageSchema, 25).success).toBe(true);
+    expect(validate(ageSchema, 17).success).toBe(false);
+    expect(validate(ageSchema, 25.5).success).toBe(false);
+    expect(validate(ageSchema, '25').success).toBe(false); // strict type
+  });
+
+  it('validates nested objects with required and optional fields', () => {
+    const userSchema = s.object({
+      name: s.string().min(2),
+      age: s.number().optional(),
+      role: s.enum(['admin', 'user']).default('user'),
+    });
+
+    type User = Infer<typeof userSchema>;
+
+    const validResult = validate(userSchema, { name: 'Alice' });
+    expect(validResult.success).toBe(true);
+    expect(validResult.data?.role).toBe('user'); // default value applied
+
+    const invalidResult = validate(userSchema, { name: 'A' });
+    expect(invalidResult.success).toBe(false);
+    expect(invalidResult.errors?.[0].field).toBe('name');
+  });
+
+  it('validates arrays of schemas', () => {
+    const tagsSchema = s.array(s.string().min(1)).min(1);
+    expect(validate(tagsSchema, ['tech', 'api']).success).toBe(true);
+    expect(validate(tagsSchema, []).success).toBe(false); // min 1
+    expect(validate(tagsSchema, ['tech', '']).success).toBe(false); // inner item invalid
+  });
+});

package/test/seeder-migrator.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, s, FireMigrator, Migration } from '../src/index';
+
+describe('FireAPI Schema Auto-Seeder & Migration Engine', () => {
+  it('seeds database with schema-compliant mock data via app.db.seed()', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+
+    const BookSchema = s.object({
+      title: s.string().min(5),
+      author: s.string().min(3),
+      price: s.number().min(10).max(500),
+      inStock: s.boolean(),
+    });
+
+    // Seed 10 books
+    const seeded = await app.db.seed('books', BookSchema, 10);
+    expect(seeded.length).toBe(10);
+
+    // Verify persisted rows in database
+    const booksInDb = await app.db.books.find();
+    expect(booksInDb.length).toBe(10);
+    expect(booksInDb[0].title.length).toBeGreaterThanOrEqual(5);
+    expect(typeof booksInDb[0].price).toBe('number');
+  });
+
+  it('runs migrations up and rolls back cleanly with FireMigrator', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+    const migrator = new FireMigrator(app.db);
+
+    const migrations: Migration[] = [
+      {
+        name: '001_create_customers',
+        up: async (db) => {
+          await db.customers.insert({ id: 'c1', name: 'Initial Customer' });
+        },
+        down: async (db) => {
+          await db.customers.delete('c1');
+        },
+      },
+      {
+        name: '002_create_orders',
+        up: async (db) => {
+          await db.orders.insert({ id: 'o1', customerId: 'c1', total: 100 });
+        },
+        down: async (db) => {
+          await db.orders.delete('o1');
+        },
+      },
+    ];
+
+    // 1. Check initial status -> both pending
+    const initialStatus = await migrator.status(migrations);
+    expect(initialStatus.every((m) => m.status === 'pending')).toBe(true);
+
+    // 2. Run migrations UP
+    const upResult = await migrator.up(migrations);
+    expect(upResult.applied.length).toBe(2);
+    expect(upResult.applied).toEqual(['001_create_customers', '002_create_orders']);
+
+    // Verify records created
+    const customer = await app.db.customers.findById('c1');
+    const order = await app.db.orders.findById('o1');
+    expect(customer).not.toBeNull();
+    expect(order).not.toBeNull();
+
+    // Verify status -> both applied
+    const appliedStatus = await migrator.status(migrations);
+    expect(appliedStatus.every((m) => m.status === 'applied')).toBe(true);
+
+    // 3. Rollback (DOWN)
+    const downResult = await migrator.down(migrations);
+    expect(downResult.rolledBack.length).toBe(2);
+
+    // Verify rolled back
+    const customerAfter = await app.db.customers.findById('c1');
+    expect(customerAfter).toBeNull();
+  });
+});

package/test/shield.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'bun:test';
+import { applySecurityHeaders } from '../src/shield/headers';
+import { handleCORS } from '../src/shield/cors';
+import { RateLimiter } from '../src/shield/rate-limiter';
+import { sanitizePayload } from '../src/shield/sanitizer';
+
+describe('FireAPI FireShield Security Engine', () => {
+  it('applies standard security headers to responses', () => {
+    const baseResponse = new Response(JSON.stringify({ ok: true }));
+    const securedResponse = applySecurityHeaders(baseResponse);
+
+    expect(securedResponse.headers.get('x-content-type-options')).toBe('nosniff');
+    expect(securedResponse.headers.get('x-frame-options')).toBe('SAMEORIGIN');
+    expect(securedResponse.headers.get('x-xss-protection')).toBe('0');
+    expect(securedResponse.headers.get('strict-transport-security')).toContain('max-age=');
+  });
+
+  it('handles CORS preflight and standard requests', () => {
+    const preflightReq = new Request('http://localhost:3000/api', {
+      method: 'OPTIONS',
+      headers: {
+        origin: 'https://app.client.com',
+        'access-control-request-method': 'POST',
+      },
+    });
+
+    const preflightRes = handleCORS(preflightReq, { origin: '*' });
+    expect(preflightRes).not.toBeNull();
+    expect(preflightRes?.status).toBe(204);
+    expect(preflightRes?.headers.get('access-control-allow-origin')).toBe('*');
+  });
+
+  it('enforces sliding-window rate limiting and rejects exceeding traffic', () => {
+    const limiter = new RateLimiter({ max: 3, windowMs: 1000 });
+    const ip = '192.168.1.100';
+
+    expect(limiter.check(ip).allowed).toBe(true);
+    expect(limiter.check(ip).allowed).toBe(true);
+    expect(limiter.check(ip).allowed).toBe(true);
+    
+    // 4th request exceeds max 3
+    const fourth = limiter.check(ip);
+    expect(fourth.allowed).toBe(false);
+    expect(fourth.retryAfter).toBeGreaterThan(0);
+  });
+
+  it('detects and strips/rejects prototype pollution attempts', () => {
+    const maliciousJson = JSON.parse('{"name":"admin","__proto__":{"isAdmin":true}}');
+    const sanitized = sanitizePayload(maliciousJson);
+
+    expect(sanitized.name).toBe('admin');
+    expect((Object.prototype as any).isAdmin).toBeUndefined();
+    expect((sanitized as any).__proto__.isAdmin).toBeUndefined();
+  });
+});

package/test/shorthand-dx.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp } from '../src/index';
+
+describe('FireAPI Ultra-Simple Shorthand DX', () => {
+  it('allows direct handler function without options wrapper', async () => {
+    const app = createApp();
+
+    // 1. Return raw string
+    app.get('/hello', () => 'Hello FireAPI!');
+
+    // 2. Return raw object (auto 200 JSON)
+    app.get('/data', () => ({ status: 'success', count: 42 }));
+
+    // 3. Return from ctx.db directly
+    app.get('/users', async (ctx) => {
+      return [{ id: '1', name: 'Yoga' }];
+    });
+
+    const res1 = await app.handle(new Request('http://localhost:3000/hello'));
+    expect(res1.status).toBe(200);
+    expect(await res1.text()).toBe('Hello FireAPI!');
+
+    const res2 = await app.handle(new Request('http://localhost:3000/data'));
+    expect(res2.status).toBe(200);
+    expect(await res2.json()).toEqual({ status: 'success', count: 42 });
+
+    const res3 = await app.handle(new Request('http://localhost:3000/users'));
+    expect(res3.status).toBe(200);
+    expect(await res3.json()).toEqual([{ id: '1', name: 'Yoga' }]);
+  });
+});

package/test/sse.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'bun:test';
+import { createSSEResponse } from '../src/stream/sse';
+import { createContext } from '../src/core/context';
+
+describe('FireAPI AI & Real-Time SSE Streaming Engine', () => {
+  it('formats SSE events and streams chunks via ReadableStream', async () => {
+    const sseResponse = createSSEResponse(async (stream) => {
+      await stream.send('Hello');
+      await stream.send({ token: 'world' }, { event: 'token', id: '1' });
+      stream.close();
+    });
+
+    expect(sseResponse.status).toBe(200);
+    expect(sseResponse.headers.get('Content-Type')).toBe('text/event-stream; charset=utf-8');
+    expect(sseResponse.headers.get('Cache-Control')).toContain('no-cache');
+
+    const reader = sseResponse.body!.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      text += decoder.decode(value);
+    }
+
+    expect(text).toContain('data: Hello\n\n');
+    expect(text).toContain('event: token\n');
+    expect(text).toContain('id: 1\n');
+    expect(text).toContain('data: {"token":"world"}\n\n');
+  });
+
+  it('is accessible via ctx.stream.sse() helper', async () => {
+    const ctx = createContext({ req: new Request('http://localhost:3000/stream') });
+    const sseRes = ctx.stream.sse(async (stream) => {
+      await stream.send('stream-ready');
+      stream.close();
+    });
+
+    expect(sseRes.status).toBe(200);
+    expect(sseRes.headers.get('Content-Type')).toBe('text/event-stream; charset=utf-8');
+  });
+});