create-fullstack-scaffold 0.1.0

package/template/src/shared/core/__tests__/ws-client.test.ts

@@ -0,0 +1,468 @@
+/**
+ * @framework-baseline dac723f73f2c7757
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+type TestProtocol = {
+  rpc: {
+    echo: { in: { message: string }; out: { message: string; timestamp: number } }
+    ping: { in: Record<string, never>; out: { pong: boolean } }
+  }
+  events: {
+    broadcast: { text: string }
+    notification: { title: string }
+  }
+}
+
+let savedWebSocket: typeof globalThis.WebSocket | undefined
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  savedWebSocket = globalThis.WebSocket
+  delete (globalThis as Record<string, unknown>).WebSocket
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  if (savedWebSocket !== undefined) {
+    globalThis.WebSocket = savedWebSocket
+  } else {
+    delete (globalThis as Record<string, unknown>).WebSocket
+  }
+})
+
+async function getModule() {
+  vi.resetModules()
+  const mod = await import('../ws-client')
+  return mod
+}
+
+describe('WSClientImpl', () => {
+  describe('constructor and status', () => {
+    it('should start in connecting state with StubWebSocket', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      expect(client.status).toBe('connecting')
+    })
+
+    it('should transition to open on ws.onopen', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as { ws: { onopen: ((e: Event) => void) | null; readyState: number } }
+      ).ws
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      expect(client.status).toBe('open')
+    })
+
+    it('should transition to closed on ws.onclose', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: {
+            onopen: ((e: Event) => void) | null
+            onclose: ((e: CloseEvent) => void) | null
+            readyState: number
+          }
+        }
+      ).ws
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      ws.readyState = 3
+      ws.onclose?.(new Event('close') as CloseEvent)
+      expect(client.status).toBe('closed')
+    })
+
+    it('should transition to closed on ws.onerror', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onerror: ((e: Event) => void) | null } }).ws
+
+      ws.onerror?.(new Event('error'))
+      expect(client.status).toBe('closed')
+    })
+
+    it('should not double-transition if already closed on onclose', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: { onclose: ((e: CloseEvent) => void) | null; readyState: number }
+        }
+      ).ws
+
+      ws.readyState = 3
+      ws.onclose?.(new Event('close') as CloseEvent)
+      expect(client.status).toBe('closed')
+    })
+
+    it('should not double-transition if already open on onopen', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as { ws: { onopen: ((e: Event) => void) | null; readyState: number } }
+      ).ws
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      const handler = vi.fn()
+      client.onStatusChange(handler)
+      handler.mockClear()
+      ws.onopen?.(new Event('open'))
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('should not transition on onerror if already closed', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onerror: ((e: Event) => void) | null } }).ws
+
+      ws.onerror?.(new Event('error'))
+      const handler = vi.fn()
+      client.onStatusChange(handler)
+      handler.mockClear()
+      ws.onerror?.(new Event('error'))
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('should return null for getSocket with StubWebSocket', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      expect(client.getSocket()).toBeNull()
+    })
+  })
+
+  describe('call()', () => {
+    it('should send RPC request and resolve with result', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: {
+            send: (d: string) => void
+            onopen: ((e: Event) => void) | null
+            onmessage: ((e: MessageEvent) => void) | null
+            readyState: number
+          }
+        }
+      ).ws
+      const sendSpy = vi.spyOn(ws, 'send')
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+
+      const callPromise = client.call('echo', { message: 'hello' })
+      expect(sendSpy).toHaveBeenCalledTimes(1)
+      const sent = JSON.parse(sendSpy.mock.calls[0][0] as string)
+      expect(sent.method).toBe('echo')
+
+      ws.onmessage?.({
+        data: JSON.stringify({ id: sent.id, result: { message: 'hello', timestamp: 123 } }),
+      } as MessageEvent)
+      const result = await callPromise
+      expect(result).toEqual({ message: 'hello', timestamp: 123 })
+    })
+
+    it('should reject on RPC error response', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: {
+            send: (d: string) => void
+            onopen: ((e: Event) => void) | null
+            onmessage: ((e: MessageEvent) => void) | null
+            readyState: number
+          }
+        }
+      ).ws
+      const sendSpy = vi.spyOn(ws, 'send')
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+
+      const callPromise = client.call('echo', { message: 'fail' })
+      const sent = JSON.parse(sendSpy.mock.calls[0][0] as string)
+      ws.onmessage?.({
+        data: JSON.stringify({ id: sent.id, error: 'Something went wrong' }),
+      } as MessageEvent)
+      await expect(callPromise).rejects.toThrow('Something went wrong')
+    })
+
+    it('should reject on timeout', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: { send: (d: string) => void; onopen: ((e: Event) => void) | null; readyState: number }
+        }
+      ).ws
+      vi.spyOn(ws, 'send')
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+
+      const callPromise = client.call('echo', { message: 'timeout' }, 1000)
+      vi.advanceTimersByTime(1001)
+      await expect(callPromise).rejects.toThrow('RPC Timeout: echo')
+    })
+
+    it('should clear timeout timer on resolve', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: {
+            send: (d: string) => void
+            onopen: ((e: Event) => void) | null
+            onmessage: ((e: MessageEvent) => void) | null
+            readyState: number
+          }
+        }
+      ).ws
+      const sendSpy = vi.spyOn(ws, 'send')
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+
+      const callPromise = client.call('echo', { message: 'hello' }, 1000)
+      const sent = JSON.parse(sendSpy.mock.calls[0][0] as string)
+      ws.onmessage?.({
+        data: JSON.stringify({ id: sent.id, result: { message: 'hello', timestamp: 1 } }),
+      } as MessageEvent)
+      await callPromise
+      vi.advanceTimersByTime(2000)
+    })
+
+    it('should buffer messages when socket is not open', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: {
+            send: (d: string) => void
+            onopen: ((e: Event) => void) | null
+            onmessage: ((e: MessageEvent) => void) | null
+            readyState: number
+          }
+        }
+      ).ws
+      const sendSpy = vi.spyOn(ws, 'send')
+
+      const callPromise = client.call('echo', { message: 'buffered' }, 5000)
+      expect(sendSpy).not.toHaveBeenCalled()
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      expect(sendSpy).toHaveBeenCalledTimes(1)
+      const sent = JSON.parse(sendSpy.mock.calls[0][0] as string)
+      ws.onmessage?.({
+        data: JSON.stringify({ id: sent.id, result: { message: 'buffered', timestamp: 1 } }),
+      } as MessageEvent)
+      await callPromise
+    })
+  })
+
+  describe('on()', () => {
+    it('should register event handler and receive events', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      const handler = vi.fn()
+      client.on('broadcast', handler)
+
+      ws.onmessage?.({
+        data: JSON.stringify({ type: 'broadcast', payload: { text: 'hello' } }),
+      } as MessageEvent)
+      expect(handler).toHaveBeenCalledWith({ text: 'hello' })
+    })
+
+    it('should support multiple handlers for same event', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      const handler1 = vi.fn()
+      const handler2 = vi.fn()
+      client.on('broadcast', handler1)
+      client.on('broadcast', handler2)
+
+      ws.onmessage?.({
+        data: JSON.stringify({ type: 'broadcast', payload: { text: 'hi' } }),
+      } as MessageEvent)
+      expect(handler1).toHaveBeenCalledWith({ text: 'hi' })
+      expect(handler2).toHaveBeenCalledWith({ text: 'hi' })
+    })
+
+    it('should return unsubscribe function that removes handler', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      const handler = vi.fn()
+      const unsub = client.on('broadcast', handler)
+      unsub()
+
+      ws.onmessage?.({
+        data: JSON.stringify({ type: 'broadcast', payload: { text: 'hello' } }),
+      } as MessageEvent)
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('should not call handlers for different event types', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      const handler = vi.fn()
+      client.on('broadcast', handler)
+
+      ws.onmessage?.({
+        data: JSON.stringify({ type: 'notification', payload: { title: 'test' } }),
+      } as MessageEvent)
+      expect(handler).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('emit()', () => {
+    it('should send typed event when socket is open', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: { send: (d: string) => void; onopen: ((e: Event) => void) | null; readyState: number }
+        }
+      ).ws
+      const sendSpy = vi.spyOn(ws, 'send')
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+
+      client.emit('broadcast', { text: 'hello world' })
+      expect(sendSpy).toHaveBeenCalledTimes(1)
+      const sent = JSON.parse(sendSpy.mock.calls[0][0] as string)
+      expect(sent).toEqual({ type: 'broadcast', payload: { text: 'hello world' } })
+    })
+
+    it('should buffer event when socket is not open', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: { send: (d: string) => void; onopen: ((e: Event) => void) | null; readyState: number }
+        }
+      ).ws
+      const sendSpy = vi.spyOn(ws, 'send')
+
+      client.emit('broadcast', { text: 'buffered' })
+      expect(sendSpy).not.toHaveBeenCalled()
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      expect(sendSpy).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('onStatusChange()', () => {
+    it('should call handler on status transitions', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as {
+          ws: {
+            onopen: ((e: Event) => void) | null
+            onclose: ((e: CloseEvent) => void) | null
+            readyState: number
+          }
+        }
+      ).ws
+
+      const handler = vi.fn()
+      client.onStatusChange(handler)
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      expect(handler).toHaveBeenCalledWith('open')
+
+      ws.readyState = 3
+      ws.onclose?.(new Event('close') as CloseEvent)
+      expect(handler).toHaveBeenCalledWith('closed')
+    })
+
+    it('should return unsubscribe function', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (
+        client as unknown as { ws: { onopen: ((e: Event) => void) | null; readyState: number } }
+      ).ws
+
+      const handler = vi.fn()
+      const unsub = client.onStatusChange(handler)
+      unsub()
+
+      ws.readyState = 1
+      ws.onopen?.(new Event('open'))
+      expect(handler).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('close()', () => {
+    it('should close the underlying socket', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { close: () => void } }).ws
+      const closeSpy = vi.spyOn(ws, 'close')
+
+      client.close()
+      expect(closeSpy).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('handleMessage edge cases', () => {
+    it('should ignore messages without id or type', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      const handler = vi.fn()
+      client.on('broadcast', handler)
+
+      ws.onmessage?.({ data: JSON.stringify({ method: 'test', payload: 'data' }) } as MessageEvent)
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('should ignore unknown RPC response ids', async () => {
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      ws.onmessage?.({ data: JSON.stringify({ id: 'unknown-id', result: 'data' }) } as MessageEvent)
+    })
+
+    it('should handle invalid JSON gracefully', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      const { WSClientImpl } = await getModule()
+      const client = new WSClientImpl<TestProtocol>('ws://localhost')
+      const ws = (client as unknown as { ws: { onmessage: ((e: MessageEvent) => void) | null } }).ws
+
+      ws.onmessage?.({ data: 'not-json' } as MessageEvent)
+      expect(consoleSpy).toHaveBeenCalled()
+      consoleSpy.mockRestore()
+    })
+  })
+})
+
+describe('createWSClient', () => {
+  it('should create a WSClient instance', async () => {
+    const { createWSClient } = await getModule()
+    const client = createWSClient<TestProtocol>('ws://localhost')
+    expect(client).toBeDefined()
+    expect(client.status).toBe('connecting')
+  })
+})

package/template/src/shared/core/api-request.ts

@@ -0,0 +1,192 @@
+/**
+ * @framework-baseline a1b2c3d4e5f6g7h8
+ * @framework-modify
+ * @reason 新增 API 请求包装器，提供链式调用的增强功能（loading、重试、错误处理）
+ * @impact 所有使用 api() 函数的 API 调用都会受到影响，提供统一的请求处理能力
+ *
+ * API 请求包装器
+ *
+ * 提供链式调用的 API 请求增强功能：
+ * - withLoading(): 显示 loading 状态
+ * - withRetry(): 自动重试
+ * - silentError(): 静默错误
+ * - json(): 解析响应并自动处理错误
+ */
+
+import type { ApiSuccess, ApiError as ApiErrorType } from './api-schemas'
+
+export interface ApiRequestOptions {
+  loading?: boolean | string
+  retry?: number
+  retryDelay?: number
+  silentError?: boolean
+}
+
+export class ApiRequestError extends Error {
+  readonly code?: string
+  readonly status?: number
+  readonly details?: Array<{ field?: string; message: string; code?: string }>
+  readonly timestamp?: string
+
+  constructor(error: ApiErrorType) {
+    super(error.error)
+    this.name = 'ApiRequestError'
+    this.code = error.code
+    this.status = error.status
+    this.details = error.details
+    this.timestamp = error.timestamp
+  }
+}
+
+type LoadingStore = {
+  startLoading: (text?: string) => void
+  stopLoading: () => void
+}
+
+type MessageApi = {
+  error: (msg: string) => void
+}
+
+let loadingStore: LoadingStore | null = null
+let messageApi: MessageApi | null = null
+
+export function setupApiRequestDeps(deps: { loadingStore: LoadingStore; messageApi: MessageApi }) {
+  loadingStore = deps.loadingStore
+  messageApi = deps.messageApi
+}
+
+interface HonoClientResponse<T> {
+  ok: boolean
+  status: number
+  statusText: string
+  json(): Promise<T>
+}
+
+export class ApiRequest<T> {
+  private options: ApiRequestOptions = {}
+  private requestPromise: Promise<HonoClientResponse<ApiSuccess<T> | ApiErrorType>>
+
+  constructor(promise: Promise<HonoClientResponse<ApiSuccess<T> | ApiErrorType>>) {
+    this.requestPromise = promise
+  }
+
+  withLoading(text?: boolean | string): this {
+    this.options.loading = text === undefined ? true : text
+    return this
+  }
+
+  withRetry(count: number, delay = 1000): this {
+    this.options.retry = count
+    this.options.retryDelay = delay
+    return this
+  }
+
+  silentError(): this {
+    this.options.silentError = true
+    return this
+  }
+
+  async json(): Promise<T> {
+    const { loading, retry = 0, retryDelay = 1000, silentError } = this.options
+
+    if (loading !== undefined && loading !== false && loadingStore) {
+      const text = typeof loading === 'string' ? loading : undefined
+      loadingStore.startLoading(text)
+    }
+
+    let lastError: Error | null = null
+    let attempts = 0
+
+    while (attempts <= retry) {
+      try {
+        const response = await this.requestPromise
+
+        if (!response.ok) {
+          const errorData = await this.tryParseError(response)
+          throw new ApiRequestError(errorData)
+        }
+
+        const result = await response.json()
+
+        if (result.success) {
+          if (loading !== undefined && loading !== false && loadingStore) {
+            loadingStore.stopLoading()
+          }
+          return result.data
+        }
+
+        throw new ApiRequestError(result)
+      } catch (error) {
+        lastError = error as Error
+        attempts++
+
+        if (attempts <= retry && this.shouldRetry(error)) {
+          await this.delay(retryDelay)
+          continue
+        }
+
+        break
+      }
+    }
+
+    if (loading !== undefined && loading !== false && loadingStore) {
+      loadingStore.stopLoading()
+    }
+
+    const error = lastError!
+
+    if (!silentError) {
+      if (error instanceof ApiRequestError) {
+        messageApi?.error(error.message)
+      } else {
+        messageApi?.error('请求失败，请稍后重试')
+      }
+    }
+
+    throw error
+  }
+
+  private async tryParseError(response: HonoClientResponse<unknown>): Promise<ApiErrorType> {
+    try {
+      const data = (await response.json()) as unknown
+      if (data && typeof data === 'object' && 'error' in data) {
+        return data as ApiErrorType
+      }
+    } catch {
+      // ignore
+    }
+    return {
+      success: false,
+      error: `HTTP Error: ${response.status} ${response.statusText}`,
+      status: response.status,
+    }
+  }
+
+  private shouldRetry(error: unknown): boolean {
+    if (error instanceof ApiRequestError) {
+      const status = error.status
+      if (status === 401 || status === 403 || status === 404 || status === 422) {
+        return false
+      }
+      return true
+    }
+    return error instanceof TypeError
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}
+
+type ExtractJsonType<T> = T extends { json(): Promise<infer J> } ? J : never
+type ExtractData<T> = T extends ApiSuccess<infer D> ? D : never
+
+export function api<T extends { json(): Promise<unknown> }>(
+  promise: Promise<T>
+): ApiRequest<ExtractData<ExtractJsonType<T>>> {
+  return new ApiRequest<ExtractData<ExtractJsonType<T>>>(
+    promise as unknown as Promise<
+      HonoClientResponse<ApiSuccess<ExtractData<ExtractJsonType<T>>> | ApiErrorType>
+    >
+  )
+}

package/template/src/shared/core/api-schemas.ts

@@ -0,0 +1,41 @@
+/**
+ * @framework-baseline 295608e4d0c3a8de
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ *
+ * @framework-modify
+ * @reason [必填] 修改原因
+ * @impact [必填] 影响范围
+ */
+
+import { z } from '@hono/zod-openapi'
+
+export const ApiSuccessSchema = <T extends z.ZodTypeAny>(dataSchema: T) =>
+  z.object({
+    success: z.literal(true),
+    data: dataSchema,
+    timestamp: z.string(),
+  })
+
+export const ApiErrorDetailSchema = z.object({
+  field: z.string().optional(),
+  message: z.string(),
+  code: z.string().optional(),
+})
+
+export const ApiErrorSchema = z.object({
+  success: z.literal(false),
+  error: z.string(),
+  code: z.string().optional(),
+  status: z.number().optional(),
+  details: z.array(ApiErrorDetailSchema).optional(),
+  timestamp: z.string().optional(),
+})
+
+export const ApiResponseSchema = <T extends z.ZodTypeAny>(dataSchema: T) =>
+  z.union([ApiSuccessSchema(dataSchema), ApiErrorSchema])
+
+export type ApiSuccess<T> = { success: true; data: T; timestamp: string }
+export type ApiErrorDetail = z.infer<typeof ApiErrorDetailSchema>
+export type ApiError = z.infer<typeof ApiErrorSchema>
+export type ApiResponse<T> = ApiSuccess<T> | ApiError