create-fullstack-scaffold 0.1.0

package/template/src/server/module-notifications/__tests__/sse-rpc.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest'
+import { createApp } from '@server/app'
+import { createTestServer } from '@server/test-utils/test-server'
+import { createTestClient } from '@server/test-utils/test-client'
+import { setRuntimeAdapter } from '@server/core/runtime'
+import { getNodeRuntimeAdapter } from '@server/core/runtime-node'
+import { SSEClientImpl } from '@shared/core/sse-client'
+import * as notificationService from '../services/notification-service'
+import type { AppSSEProtocol } from '@shared/schemas'
+
+setRuntimeAdapter(getNodeRuntimeAdapter())
+
+let sseTestContext: { port: number; close: () => Promise<void> }
+let client: ReturnType<typeof createTestClient>
+
+function connectSSE() {
+  const conn = client.api.notifications.stream.$sse()
+  return conn as unknown as SSEClientImpl<AppSSEProtocol>
+}
+
+describe('SSE Routes with Patched $sse() RPC Method', () => {
+  beforeAll(async () => {
+    const app = createApp()
+    const server = await createTestServer(app, ['/api/notifications/stream'])
+    sseTestContext = { port: server.port, close: server.close }
+
+    client = createTestClient(`http://localhost:${server.port}`, {
+      sse: url => new SSEClientImpl(url, { Authorization: 'Bearer admin-token' }),
+      headers: { Authorization: 'Bearer admin-token' },
+    })
+  }, 15000)
+
+  afterAll(async () => {
+    await sseTestContext.close()
+  }, 15000)
+
+  beforeEach(() => {
+    notificationService.clearAllNotifications()
+  })
+
+  afterEach(() => {
+    notificationService.clearAllNotifications()
+  })
+
+  describe('GET /api/notifications/stream via $sse()', () => {
+    it('should use patched $sse() method for type-safe SSE connection', async () => {
+      const conn = connectSSE()
+
+      expect(['connecting', 'open', 'closed']).toContain(conn.status)
+
+      const receivedNotifications: AppSSEProtocol['events']['notification'][] = []
+      const receivedPings: AppSSEProtocol['events']['ping'][] = []
+      const receivedConnected: AppSSEProtocol['events']['connected'][] = []
+
+      const unsubscribeNotification = conn.on(
+        'notification',
+        (notification: (typeof receivedNotifications)[0]) => {
+          receivedNotifications.push(notification)
+        }
+      )
+
+      const unsubscribePing = conn.on('ping', (ping: (typeof receivedPings)[0]) => {
+        receivedPings.push(ping)
+      })
+
+      const unsubscribeConnected = conn.on(
+        'connected',
+        (connected: (typeof receivedConnected)[0]) => {
+          receivedConnected.push(connected)
+        }
+      )
+
+      await new Promise(resolve => setTimeout(resolve, 2000))
+
+      unsubscribeNotification()
+      unsubscribePing()
+      unsubscribeConnected()
+      conn.abort()
+
+      const totalEvents =
+        receivedNotifications.length + receivedPings.length + receivedConnected.length
+      expect(totalEvents).toBeGreaterThanOrEqual(0)
+    })
+
+    it('should receive typed notification events', async () => {
+      const conn = connectSSE()
+
+      const receivedNotifications: AppSSEProtocol['events']['notification'][] = []
+
+      const unsubscribe = conn.on(
+        'notification',
+        (notification: (typeof receivedNotifications)[0]) => {
+          receivedNotifications.push(notification)
+        }
+      )
+
+      await new Promise(resolve => setTimeout(resolve, 2000))
+
+      unsubscribe()
+      conn.abort()
+
+      receivedNotifications.forEach(notification => {
+        expect(notification.id).toBeDefined()
+        expect(notification.type).toBeDefined()
+        expect(notification.title).toBeDefined()
+        expect(notification.message).toBeDefined()
+        expect(notification.read).toBeDefined()
+        expect(notification.createdAt).toBeDefined()
+      })
+    })
+
+    it('should receive typed ping events', async () => {
+      const conn = connectSSE()
+
+      const receivedPings: AppSSEProtocol['events']['ping'][] = []
+
+      const unsubscribe = conn.on('ping', (ping: (typeof receivedPings)[0]) => {
+        receivedPings.push(ping)
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 2000))
+
+      unsubscribe()
+      conn.abort()
+
+      receivedPings.forEach(ping => {
+        expect(ping.timestamp).toBeDefined()
+        expect(typeof ping.timestamp).toBe('number')
+      })
+    })
+
+    it('should receive typed connected events', async () => {
+      const conn = connectSSE()
+
+      const receivedConnected: AppSSEProtocol['events']['connected'][] = []
+
+      const unsubscribe = conn.on('connected', (connected: (typeof receivedConnected)[0]) => {
+        receivedConnected.push(connected)
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 2000))
+
+      unsubscribe()
+      conn.abort()
+
+      receivedConnected.forEach(connected => {
+        expect(connected.timestamp).toBeDefined()
+        expect(typeof connected.timestamp).toBe('number')
+      })
+    })
+
+    it('should handle connection status changes', async () => {
+      const conn = connectSSE()
+
+      const statusHistory: ('connecting' | 'open' | 'closed')[] = []
+
+      const unsubscribe = conn.onStatusChange((status: (typeof statusHistory)[0]) => {
+        statusHistory.push(status)
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 1000))
+
+      conn.abort()
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      unsubscribe()
+
+      expect(statusHistory.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it('should handle errors gracefully', async () => {
+      const conn = connectSSE()
+
+      const unsubscribe = conn.onError((error: Error) => {
+        console.error('SSE error:', error)
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 1000))
+
+      unsubscribe()
+      conn.abort()
+
+      expect(conn.status).toBe('closed')
+    })
+  })
+
+  describe('Error Scenarios', () => {
+    it('should handle connection abort during event reception', async () => {
+      const conn = connectSSE()
+
+      const receivedEvents: unknown[] = []
+      const unsubscribe = conn.on('notification', (event: unknown) => {
+        receivedEvents.push(event)
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 500))
+
+      conn.abort()
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      unsubscribe()
+
+      expect(conn.status).toBe('closed')
+    })
+
+    it('should handle multiple abort calls gracefully', async () => {
+      const conn = connectSSE()
+
+      await new Promise(resolve => setTimeout(resolve, 500))
+
+      conn.abort()
+      conn.abort()
+      conn.abort()
+
+      expect(conn.status).toBe('closed')
+    })
+
+    it('should handle unsubscribe before connection close', async () => {
+      const conn = connectSSE()
+
+      const unsubscribe = conn.on('notification', () => {})
+
+      await new Promise(resolve => setTimeout(resolve, 500))
+
+      unsubscribe()
+
+      conn.abort()
+
+      expect(conn.status).toBe('closed')
+    })
+
+    it('should handle error events', async () => {
+      const conn = connectSSE()
+
+      let errorReceived = false
+      const unsubscribe = conn.onError((error: Error) => {
+        console.error('SSE error:', error)
+        errorReceived = true
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 1000))
+
+      conn.abort()
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      unsubscribe()
+
+      expect(['closed', 'connecting', 'open']).toContain(conn.status)
+      expect(typeof errorReceived).toBe('boolean')
+    })
+
+    it('should handle non-existent event type gracefully', async () => {
+      const conn = connectSSE()
+
+      let received = false
+      const unsubscribe = conn.on('nonExistentEvent' as 'notification', () => {
+        received = true
+      })
+
+      await new Promise(resolve => setTimeout(resolve, 500))
+
+      conn.abort()
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      unsubscribe()
+
+      expect(conn.status).toBe('closed')
+      expect(received).toBe(false)
+    })
+
+    it('should test error assertion pattern', async () => {
+      const conn = connectSSE()
+
+      await new Promise(resolve => setTimeout(resolve, 500))
+
+      conn.abort()
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      expect(conn.status).toBe('closed')
+      const nullValue = null
+      expect(nullValue).toBeNull()
+    })
+  })
+})

package/template/src/server/module-notifications/module.ts

@@ -0,0 +1,32 @@
+import type { ModuleManifest } from '@shared/core/module-manifest'
+
+const notificationManifest: ModuleManifest = {
+  name: 'notifications',
+  description: 'Notification management with SSE real-time streaming',
+  category: 'communication',
+  dependsOn: [],
+
+  routes: {
+    client: {
+      importPath: './routes/notification-routes',
+      exportName: 'notificationRoutes',
+    },
+  },
+
+  sharedSchemas: {
+    path: 'notifications',
+  },
+
+  clientPages: [{ name: 'NotificationPage', route: '/notifications' }],
+
+  clientStores: ['notificationStore'],
+
+  dbSchemas: {
+    files: ['notifications'],
+    hasSeed: false,
+  },
+
+  hasSSE: true,
+}
+
+export default notificationManifest

package/template/src/server/module-notifications/routes/notification-routes.ts

@@ -0,0 +1,190 @@
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import * as notificationService from '../services/notification-service'
+import {
+  NotificationSchema,
+  CreateNotificationSchema,
+  AppSSEProtocolSchema,
+  UnreadCountSchema,
+  NotificationIdSchema,
+} from '@shared/schemas'
+import {
+  successResponse,
+  errorResponse,
+  listResponse,
+  success,
+  created,
+} from '@server/utils/route-helpers'
+import { NotFoundError } from '@server/utils/app-error'
+import { getRuntimeAdapter } from '@server/core/runtime'
+
+const streamRoute = createRoute({
+  method: 'get',
+  path: '/notifications/stream',
+  tags: ['notifications'],
+  responses: {
+    200: {
+      content: {
+        'text/event-stream': { schema: AppSSEProtocolSchema },
+      },
+      description: 'SSE stream for notifications',
+    },
+    500: errorResponse('Internal server error'),
+  },
+})
+
+const listRoute = createRoute({
+  method: 'get',
+  path: '/notifications',
+  tags: ['notifications'],
+  request: {
+    query: z.object({
+      unreadOnly: z.string().optional(),
+      limit: z.string().optional(),
+      cursor: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: listResponse(NotificationSchema, 'List notifications'),
+    500: errorResponse('Internal server error'),
+  },
+})
+
+const unreadCountRoute = createRoute({
+  method: 'get',
+  path: '/notifications/unread-count',
+  tags: ['notifications'],
+  responses: {
+    200: successResponse(UnreadCountSchema, 'Get unread count'),
+    500: errorResponse('Internal server error'),
+  },
+})
+
+const getRoute = createRoute({
+  method: 'get',
+  path: '/notifications/{id}',
+  tags: ['notifications'],
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: successResponse(NotificationSchema, 'Get notification by ID'),
+    404: errorResponse('Notification not found'),
+  },
+})
+
+const createRouteDef = createRoute({
+  method: 'post',
+  path: '/notifications',
+  tags: ['notifications'],
+  request: {
+    body: {
+      content: { 'application/json': { schema: CreateNotificationSchema } },
+    },
+  },
+  responses: {
+    201: successResponse(NotificationSchema, 'Create notification'),
+    400: errorResponse('Invalid input'),
+  },
+})
+
+const markAllReadRoute = createRoute({
+  method: 'patch',
+  path: '/notifications/read-all',
+  tags: ['notifications'],
+  responses: {
+    200: successResponse(UnreadCountSchema, 'Mark all as read'),
+    500: errorResponse('Internal server error'),
+  },
+})
+
+const markReadRoute = createRoute({
+  method: 'patch',
+  path: '/notifications/{id}/read',
+  tags: ['notifications'],
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: successResponse(NotificationSchema, 'Mark as read'),
+    404: errorResponse('Notification not found'),
+  },
+})
+
+const deleteRoute = createRoute({
+  method: 'delete',
+  path: '/notifications/{id}',
+  tags: ['notifications'],
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: successResponse(NotificationIdSchema, 'Delete notification'),
+    404: errorResponse('Notification not found'),
+  },
+})
+
+export const notificationRoutes = new OpenAPIHono()
+  .openapi(streamRoute, async c => {
+    // In Cloudflare environment, route SSE to Durable Object for proper broadcast support
+    const env = c.env as { REALTIME_DO?: DurableObjectNamespace } | undefined
+    if (env?.REALTIME_DO) {
+      const id = env.REALTIME_DO.idFromName('global')
+      const stub = env.REALTIME_DO.get(id)
+      // Forward the SSE request to the Durable Object
+      const doRequest = new Request(c.req.url, {
+        method: c.req.method,
+        headers: c.req.raw.headers,
+      })
+      return stub.fetch(doRequest)
+    }
+
+    // Fallback for Node environment
+    const adapter = getRuntimeAdapter()
+    if (adapter.handleSSERequest) {
+      const response = await adapter.handleSSERequest()
+      return response
+    }
+    return c.json({ success: false as const, error: 'SSE not supported' }, 500)
+  })
+  .openapi(listRoute, async c => {
+    const query = c.req.valid('query')
+    const result = notificationService.listNotifications({
+      unreadOnly: query.unreadOnly === 'true',
+      limit: query.limit ? parseInt(query.limit) : 20,
+      cursor: query.cursor,
+    })
+    return c.json(success({ items: result.data, nextCursor: result.nextCursor }), 200)
+  })
+  .openapi(unreadCountRoute, async c => {
+    const count = notificationService.getUnreadCount()
+    return c.json(success({ count }), 200)
+  })
+  .openapi(getRoute, async c => {
+    const { id } = c.req.valid('param')
+    const notification = notificationService.getNotification(id)
+    if (!notification) throw new NotFoundError('Notification', id)
+    return c.json(success(notification), 200)
+  })
+  .openapi(createRouteDef, async c => {
+    const data = c.req.valid('json')
+    const notification = await notificationService.createNotificationAndBroadcast(data)
+
+    return c.json(created(notification), 201)
+  })
+  .openapi(markAllReadRoute, async c => {
+    const count = notificationService.markAllAsRead()
+    return c.json(success({ count }), 200)
+  })
+  .openapi(markReadRoute, async c => {
+    const { id } = c.req.valid('param')
+    const notification = notificationService.markAsRead(id)
+    if (!notification) throw new NotFoundError('Notification', id)
+    return c.json(success(notification), 200)
+  })
+  .openapi(deleteRoute, async c => {
+    const { id } = c.req.valid('param')
+    const deleted = notificationService.deleteNotification(id)
+    if (!deleted) throw new NotFoundError('Notification', id)
+    return c.json(success({ id }), 200)
+  })

package/template/src/server/module-notifications/services/notification-service.ts

@@ -0,0 +1,104 @@
+import type { AppNotification, CreateNotificationInput } from '@shared/schemas'
+import { generateUUID } from '@server/utils/uuid'
+import { realtime } from '@server/core'
+import { logger } from '@server/utils/logger'
+
+const notifications: AppNotification[] = []
+
+export function listNotifications(options: {
+  unreadOnly?: boolean
+  limit?: number
+  cursor?: string
+}): { data: AppNotification[]; nextCursor?: string } {
+  let filtered = [...notifications]
+
+  if (options.unreadOnly) {
+    filtered = filtered.filter(n => !n.read)
+  }
+
+  filtered.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())
+
+  const limit = options.limit ?? 20
+  let startIndex = 0
+
+  if (options.cursor) {
+    const cursorIndex = filtered.findIndex(n => n.id === options.cursor)
+    if (cursorIndex !== -1) {
+      startIndex = cursorIndex + 1
+    }
+  }
+
+  const data = filtered.slice(startIndex, startIndex + limit)
+  const nextCursor = data.length === limit ? data[data.length - 1]?.id : undefined
+
+  return { data, nextCursor }
+}
+
+export function getNotification(id: string): AppNotification | undefined {
+  return notifications.find(n => n.id === id)
+}
+
+export function createNotification(input: CreateNotificationInput): AppNotification {
+  const notification: AppNotification = {
+    id: generateUUID(),
+    type: input.type,
+    title: input.title,
+    message: input.message,
+    read: false,
+    createdAt: new Date().toISOString(),
+  }
+
+  notifications.unshift(notification)
+
+  return notification
+}
+
+export async function createNotificationAndBroadcast(
+  input: CreateNotificationInput
+): Promise<AppNotification> {
+  const notification = createNotification(input)
+
+  try {
+    await realtime.broadcast('notification', notification)
+  } catch (err) {
+    logger.module('notification').debug({ error: String(err) }, 'Broadcast failed')
+  }
+
+  return notification
+}
+
+export function markAsRead(id: string): AppNotification | undefined {
+  const notification = notifications.find(n => n.id === id)
+  if (notification) {
+    notification.read = true
+  }
+  return notification
+}
+
+export function markAllAsRead(): number {
+  let count = 0
+  notifications.forEach(n => {
+    if (!n.read) {
+      n.read = true
+      count++
+    }
+  })
+  return count
+}
+
+export function deleteNotification(id: string): boolean {
+  const index = notifications.findIndex(n => n.id === id)
+  if (index !== -1) {
+    notifications.splice(index, 1)
+    return true
+  }
+  return false
+}
+
+export function getUnreadCount(): number {
+  return notifications.filter(n => !n.read).length
+}
+
+export function clearAllNotifications(): void {
+  notifications.length = 0
+}