weifuwu 0.27.2 → 0.27.3

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+import type postgres from 'postgres';
+/** Untyped postgres.js SQL client. Use typed `Sql<{ table: { col: type } }>` for schemas. */
+export type SqlClient = postgres.Sql<Record<string, unknown>>;
+/** Re-export for downstream usage. */
+export type { Sql } from 'postgres';
+export type { WebSocket } from 'ws';
+export type { Redis, RedisOptions } from 'ioredis';
+export interface Context {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    mountPath?: string;
+    [key: string]: unknown;
+}
+export type Handler<T extends Context = Context> = (req: Request, ctx: T) => Response | Promise<Response>;
+/**
+ * Metadata for middleware dependency checking.
+ * Middleware factories attach this for runtime validation.
+ */
+export interface MiddlewareMeta {
+    /** Fields this middleware injects into ctx. */
+    injects: string[];
+    /** Fields this middleware depends on (must be injected earlier). */
+    depends: string[];
+}
+export type Middleware<In extends Context = Context, Out extends In = In> = {
+    (req: Request, ctx: In, next: Handler<Out>): Response | Promise<Response>;
+    __meta?: MiddlewareMeta;
+};
+export type ErrorHandler<T extends Context = Context> = (error: Error, req: Request, ctx: T) => Response | Promise<Response>;
+/**
+ * Interface for resources that require explicit cleanup (connections, pools, timers).
+ * All stateful modules implement this.
+ */
+export interface Closeable {
+    /** Release all resources. Call once when shutting down. */
+    close(): Promise<void>;
+}
+/**
+ * HTTP error with an explicit status code.
+ * Throw from a handler or middleware to return a non-200 response.
+ *
+ * ```ts
+ * if (!resource) throw new HttpError('Not found', 404)
+ * serve() catches it and returns the status code.
+ * ```
+ */
+export declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.27.2",
+  "version": "0.27.3",
   "description": "Web-standard HTTP microframework for Node.js — (req, ctx) => Response",
   "exports": {
-    ".": "./index.ts"
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "weifuwu": "./dist/cli.js"
   },
   "files": [
-    "*.ts",
-    "core/*.ts",
-    "middleware/*.ts",
-    "ai/*.ts",
-    "postgres/*.ts",
-    "postgres/**/*.ts",
-    "queue/*.ts",
-    "redis/*.ts"
+    "dist/",
+    "README.md"
   ],
   "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepublishOnly": "npm run build && tsc --emitDeclarationOnly --outdir dist",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -51,6 +50,7 @@
     "@types/node": "^25.9.3",
     "@types/nodemailer": "^6.4.17",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.0",
     "eslint": "^10.5.0",
     "globals": "^17.6.0",
     "husky": "^9.1.7",

package/ai/provider.ts

@@ -1,129 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { Context, Middleware } from '../types.ts'
-import { createOpenAI } from '@ai-sdk/openai'
-import {
-  embed as aiEmbed,
-  embedMany as aiEmbedMany,
-  generateText as aiGenerateText,
-  streamText as aiStreamText,
-  type LanguageModel,
-  type EmbeddingModel,
-} from 'ai'
-
-// Augment Context with ai property
-declare module '../types.ts' {
-  interface Context {
-    ai: AIProvider
-  }
-}
-
-// ── Types ───────────────────────────────────────────────────────────────────
-
-export interface AIProviderInjected {
-  ai: AIProvider
-}
-
-export interface AIProviderOptions {
-  /** API base URL (default: OPENAI_BASE_URL env or http://localhost:11434/v1). */
-  baseURL?: string
-  /** API key (default: OPENAI_API_KEY env or 'ollama'). */
-  apiKey?: string
-  /** Chat model name (default: OPENAI_MODEL env or 'qwen3:0.6b'). */
-  model?: string
-  /** Embedding model name (default: OPENAI_EMBEDDING_MODEL env or 'qwen3-embedding:0.6b'). */
-  embeddingModel?: string
-  /** Vector dimension (default: EMBEDDING_DIMENSION env or 1024). */
-  embeddingDimension?: number
-}
-
-export interface AIProvider {
-  /** Get the language model. Caches by default; pass a name to override. */
-  model(name?: string): LanguageModel
-  /** Get the embedding model. Caches by default; pass a name to override. */
-  embeddingModel(name?: string): EmbeddingModel
-  /** Embed a single text string into a vector. */
-  embed(text: string): Promise<number[]>
-  /** Embed multiple text strings in batch. */
-  embedMany(texts: string[]): Promise<number[][]>
-  /** The configured vector dimension. */
-  readonly dimension: number
-
-  /**
-   * Generate text using the configured model.
-   * All options are passed through to the AI SDK's `generateText`, with `model` auto-injected.
-   */
-  generateText(
-    params: Omit<Parameters<typeof aiGenerateText>[0], 'model'>,
-  ): ReturnType<typeof aiGenerateText>
-  /**
-   * Stream text using the configured model.
-   * All options are passed through to the AI SDK's `streamText`, with `model` auto-injected.
-   */
-  streamText(
-    params: Omit<Parameters<typeof aiStreamText>[0], 'model'>,
-  ): ReturnType<typeof aiStreamText>
-}
-
-// ── Factory ─────────────────────────────────────────────────────────────────
-
-export function aiProvider(
-  options?: AIProviderOptions,
-): Middleware<Context, Context & AIProviderInjected> & AIProvider {
-  const baseURL = options?.baseURL ?? process.env.OPENAI_BASE_URL ?? 'http://localhost:11434/v1'
-  const apiKey = options?.apiKey ?? process.env.OPENAI_API_KEY ?? 'ollama'
-  const modelName = options?.model ?? process.env.OPENAI_MODEL ?? 'qwen3:0.6b'
-  const embedModelName =
-    options?.embeddingModel ?? process.env.OPENAI_EMBEDDING_MODEL ?? 'qwen3-embedding:0.6b'
-  const dimension =
-    options?.embeddingDimension ?? parseInt(process.env.EMBEDDING_DIMENSION || '1024', 10)
-
-  const client = createOpenAI({ baseURL, apiKey })
-
-  let _model: LanguageModel | undefined
-  let _embedModel: EmbeddingModel | undefined
-
-  const provider: AIProvider = {
-    get dimension() {
-      return dimension
-    },
-
-    model(name?: string): LanguageModel {
-      const m = name ?? modelName
-      if (!_model) _model = client(m)
-      return _model
-    },
-
-    embeddingModel(name?: string): EmbeddingModel {
-      const m = name ?? embedModelName
-      if (!_embedModel) _embedModel = client.embedding(m)
-      return _embedModel
-    },
-
-    async embed(text: string): Promise<number[]> {
-      const result = await aiEmbed({ model: this.embeddingModel(), value: text })
-      return result.embedding
-    },
-
-    async embedMany(texts: string[]): Promise<number[][]> {
-      const result = await aiEmbedMany({ model: this.embeddingModel(), values: texts })
-      return result.embeddings
-    },
-
-    generateText(params: Omit<Parameters<typeof aiGenerateText>[0], 'model'>) {
-      return aiGenerateText({ ...params, model: this.model() } as any)
-    },
-
-    streamText(params: Omit<Parameters<typeof aiStreamText>[0], 'model'>) {
-      return aiStreamText({ ...params, model: this.model() } as any)
-    },
-  }
-
-  const mw: Middleware<Context, Context & AIProviderInjected> = async (req, ctx, next) => {
-    ;(ctx as Context & AIProviderInjected).ai = provider
-    return next(req, ctx as Context & AIProviderInjected)
-  }
-  mw.__meta = { injects: ['ai'], depends: [] }
-
-  return Object.assign(mw, provider) as Middleware<Context, Context & AIProviderInjected> &
-    AIProvider
-}

package/ai/stream.ts

@@ -1,63 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { Context } from '../types.ts'
-import { Router } from '../core/router.ts'
-import type { AIProvider } from './provider.ts'
-
-export type AIHandler = (
-  req: Request,
-  ctx: Context,
-) => Record<string, unknown> | Promise<Record<string, unknown>>
-
-export const _ai: Record<string, any> = {}
-
-async function getStreamText() {
-  if (!_ai.streamText) _ai.streamText = (await import('ai')).streamText
-  return _ai.streamText
-}
-
-async function getStreamObject() {
-  if (!_ai.streamObject) _ai.streamObject = (await import('ai')).streamObject
-  return _ai.streamObject
-}
-
-/**
- * Create a streaming AI endpoint.
- *
- * @param handler - Returns options for `streamText` or `streamObject` (if `schema` is present).
- * @param provider - Optional AI provider. If provided and the handler does not return a `model`,
- *                   `provider.model()` is used as the default.
- */
-export async function aiStream(handler: AIHandler, provider?: AIProvider): Promise<Router> {
-  const r = new Router()
-
-  r.post('/', async (req, ctx) => {
-    let options
-    try {
-      options = await handler(req, ctx)
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err)
-      return new Response(JSON.stringify({ error: message }), {
-        status: 500,
-        headers: { 'Content-Type': 'application/json' },
-      })
-    }
-
-    // Inject default model from provider if handler didn't specify one
-    if (provider && !options.model) {
-      options.model = provider.model()
-    }
-
-    if (options.schema) {
-      const streamObject = await getStreamObject()
-      const { schema, ...params } = options
-      const result = streamObject({ ...params, schema: schema as any, output: 'object' as const })
-      return result.toTextStreamResponse()
-    }
-
-    const streamText = await getStreamText()
-    const result = streamText(options)
-    return result.toTextStreamResponse()
-  })
-
-  return r
-}

package/cli.ts

@@ -1,147 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable no-console */
-import { mkdir, writeFile } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { join, dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-const pkgRoot = existsSync(join(__dirname, 'package.json')) ? __dirname : resolve(__dirname, '..')
-
-async function readPkg() {
-  return JSON.parse(
-    await import('node:fs/promises').then((fs) =>
-      fs.readFile(join(pkgRoot, 'package.json'), 'utf-8'),
-    ),
-  )
-}
-
-async function cmdVersion() {
-  const pkg = await readPkg()
-  console.log(pkg.version)
-}
-
-async function cmdInit(name: string, opts: { skipInstall?: boolean }) {
-  const targetDir = resolve(process.cwd(), name)
-
-  if (existsSync(targetDir)) {
-    console.error(`Directory ${name} already exists.`)
-    process.exit(1)
-  }
-
-  const pkg = await readPkg()
-
-  await mkdir(targetDir, { recursive: true })
-
-  await writeFile(
-    join(targetDir, 'app.ts'),
-    [
-      `import { Router } from 'weifuwu'`,
-      ``,
-      `export const app = new Router()`,
-      ``,
-      `app.get('/', () => new Response('Hello from ${name}!'))`,
-      `app.get('/api/ping', () => Response.json({ pong: true, time: new Date().toISOString() }))`,
-      ``,
-    ].join('\n'),
-  )
-
-  await writeFile(
-    join(targetDir, 'index.ts'),
-    [
-      `import { loadEnv, serve } from 'weifuwu'`,
-      `import { app } from './app.ts'`,
-      ``,
-      `loadEnv()`,
-      `const port = Number(process.env.PORT) || 3000`,
-      `serve(app.handler(), { port })`,
-      ``,
-    ].join('\n'),
-  )
-
-  await writeFile(
-    join(targetDir, 'package.json'),
-    JSON.stringify(
-      {
-        name,
-        type: 'module',
-        scripts: {
-          dev: 'node --watch index.ts',
-          start: 'node index.ts',
-        },
-        dependencies: {
-          weifuwu: `^${pkg.version}`,
-        },
-      },
-      null,
-      2,
-    ) + '\n',
-  )
-
-  await writeFile(
-    join(targetDir, 'tsconfig.json'),
-    JSON.stringify(
-      {
-        compilerOptions: {
-          target: 'ESNext',
-          module: 'NodeNext',
-          moduleResolution: 'NodeNext',
-          strict: true,
-          skipLibCheck: true,
-          noEmit: true,
-          allowImportingTsExtensions: true,
-        },
-        include: ['*.ts'],
-      },
-      null,
-      2,
-    ) + '\n',
-  )
-
-  await writeFile(join(targetDir, '.gitignore'), 'node_modules\n.env\n')
-  await writeFile(join(targetDir, '.env'), 'PORT=3000\n')
-
-  if (!opts.skipInstall) {
-    console.log('\nInstalling dependencies...')
-    execSync('npm install', { cwd: targetDir, stdio: 'inherit' })
-  }
-
-  console.log(`\n✅ Created ${name}/`)
-  console.log(`   cd ${name}`)
-  if (opts.skipInstall) console.log(`   npm install`)
-  console.log(`   npm run dev`)
-}
-
-const cmd = process.argv[2]
-
-const HELP = `
-weifuwu — Web-standard HTTP microframework for Node.js
-
-Usage:
-  npx weifuwu init <name>              Create a new project
-  npx weifuwu init <name> --skip-install  Create project, skip npm install
-  npx weifuwu version                  Print version
-`
-
-if (cmd === 'version' || cmd === '-v' || cmd === '--version') {
-  cmdVersion().catch(console.error)
-} else if (cmd === 'init') {
-  const { values, positionals } = parseArgs({
-    args: process.argv.slice(3),
-    options: { 'skip-install': { type: 'boolean' } },
-    strict: false,
-    allowPositionals: true,
-  })
-  const name = positionals[0]
-  if (!name) {
-    console.error('Usage: npx weifuwu init <name> [--skip-install]')
-    process.exit(1)
-  }
-  cmdInit(name, { skipInstall: !!values['skip-install'] }).catch(console.error)
-} else {
-  console.log(HELP)
-}

package/core/cookie.ts

@@ -1,114 +0,0 @@
-/** Options for setting a cookie. All fields map to standard Set-Cookie attributes. */
-export interface CookieOptions {
-  domain?: string
-  path?: string
-  maxAge?: number
-  expires?: Date
-  httpOnly?: boolean
-  secure?: boolean
-  sameSite?: 'strict' | 'lax' | 'none'
-}
-
-/** Parse cookies from a Request's `Cookie` header.
- *
- * @example
- * ```ts
- * const cookies = getCookies(req)
- * console.log(cookies.session_id) // value or undefined
- * ``` */
-export function getCookies(req: Request): Record<string, string> {
-  const header = req.headers.get('cookie')
-  if (!header) return {}
-
-  const cookies: Record<string, string> = {}
-  for (const pair of header.split(';')) {
-    const idx = pair.indexOf('=')
-    if (idx === -1) continue
-    let name = pair.slice(0, idx).trim()
-    let value = pair.slice(idx + 1).trim()
-    if (!name) continue
-    // Decode cookie name (consistent with value)
-    try {
-      name = decodeURIComponent(name)
-    } catch {}
-    // Strip surrounding quotes from value (RFC 6265)
-    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
-      value = value.slice(1, -1)
-    }
-    try {
-      cookies[name] = decodeURIComponent(value)
-    } catch {
-      cookies[name] = value
-    }
-  }
-  return cookies
-}
-
-function serializeCookie(name: string, value: string, options?: CookieOptions): string {
-  // Reject control characters and special chars per RFC 6265
-  // eslint-disable-next-line no-control-regex
-  if (/[\x00-\x1F\x7F-\x9F;,]/.test(name) || /[\x00-\x1F\x7F-\x9F;,]/.test(value)) {
-    throw new Error(`Invalid cookie name or value: contains control characters or special chars`)
-  }
-  const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`]
-  if (options?.maxAge != null) parts.push(`Max-Age=${options.maxAge}`)
-  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`)
-  if (options?.domain) parts.push(`Domain=${options.domain}`)
-  if (options?.path) parts.push(`Path=${options.path}`)
-  if (options?.httpOnly) parts.push('HttpOnly')
-  if (options?.secure) parts.push('Secure')
-  if (options?.sameSite) parts.push(`SameSite=${options.sameSite}`)
-  return parts.join('; ')
-}
-
-/** Set a cookie on a Response.
- *
- * Appends a `Set-Cookie` header to the existing response headers.
- * Returns a new Response with the added header.
- *
- * @example
- * ```ts
- * const res = new Response('ok')
- * return setCookie(res, 'session', token, { httpOnly: true, path: '/' })
- * ``` */
-export function setCookie(
-  res: Response,
-  name: string,
-  value: string,
-  options?: CookieOptions,
-): Response {
-  const headers = new Headers(res.headers)
-  headers.append('Set-Cookie', serializeCookie(name, value, options))
-  return new Response(res.body, {
-    status: res.status,
-    statusText: res.statusText,
-    headers,
-  })
-}
-
-/** Delete a cookie by setting `Max-Age=0`.
- *
- * @example
- * ```ts
- * return deleteCookie(res, 'session')
- * ``` */
-export function deleteCookie(
-  res: Response,
-  name: string,
-  options?: Omit<CookieOptions, 'maxAge'>,
-): Response {
-  const headers = new Headers(res.headers)
-  headers.append(
-    'Set-Cookie',
-    serializeCookie(name, '', {
-      ...options,
-      maxAge: 0,
-      expires: new Date(0),
-    }),
-  )
-  return new Response(res.body, {
-    status: res.status,
-    statusText: res.statusText,
-    headers,
-  })
-}

package/core/env.ts

@@ -1,142 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import type { Context, Middleware } from '../types.ts'
-
-/** Build-time injection from esbuild --define. `true` in dist/index.js, undefined in TS source. */
-declare let __WFW_BUNDLED__: boolean | undefined
-
-const PUBLIC_PREFIX = 'WEIFUWU_PUBLIC_'
-
-/**
- * Get all public environment variables (those prefixed with `WEIFUWU_PUBLIC_`),
- * with the prefix stripped.
- *
- * ```ts
- * const pub = getPublicEnv()
- * // WEIFUWU_PUBLIC_API_URL=http://api.example.com → { API_URL: 'http://api.example.com' }
- * ```
- */
-export function getPublicEnv(): Record<string, string> {
-  const result: Record<string, string> = {}
-  for (const [key, value] of Object.entries(process.env)) {
-    if (key.startsWith(PUBLIC_PREFIX) && value !== undefined) {
-      result[key.slice(PUBLIC_PREFIX.length)] = value
-    }
-  }
-  return result
-}
-
-// Augment Context with env property
-declare module '../types.ts' {
-  interface Context {
-    env?: Record<string, string>
-  }
-}
-
-/**
- * Whether this code is running from the compiled `dist/index.js` bundle.
- * `false` when running TypeScript source directly (dev workflow in weifuwu repo).
- *
- * Used by modules that need to resolve package-internal files differently
- * depending on whether they are compiled (published npm package) or raw TS.
- */
-export function isBundled(): boolean {
-  return typeof __WFW_BUNDLED__ !== 'undefined' ? __WFW_BUNDLED__ : false
-}
-
-/**
- * Whether `NODE_ENV` is explicitly set to `'development'`.
- *
- * Used for dev-only features: HMR, livereload, React `createRoot` (not hydrate).
- * **Not** the opposite of {@link isProd} — when `NODE_ENV` is unset, both return `false`.
- */
-export function isDev(): boolean {
-  const env = process.env.NODE_ENV
-  return env !== 'production' && env !== 'test'
-}
-
-/**
- * Whether `NODE_ENV` is explicitly set to `'production'`.
- *
- * Used for production-only behavior: plain-text 404, suppressed warnings, minified output.
- */
-export function isProd(): boolean {
-  return process.env.NODE_ENV === 'production'
-}
-
-/**
- * Load environment variables from a `.env` file into `process.env`.
- *
- * Does **not** override existing `process.env` values.
- * Supports quoted values and inline comments.
- *
- * @param path - Path to `.env` file (default: `'.env'` relative to cwd).
- *
- * ```ts
- * import { loadEnv } from 'weifuwu'
- * loadEnv()
- * console.log(process.env.PORT)
- * ```
- */
-export function loadEnv(path?: string): void {
-  const filePath = resolve(process.cwd(), path ?? '.env')
-
-  let content: string
-  try {
-    content = readFileSync(filePath, 'utf-8')
-  } catch {
-    return
-  }
-
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim()
-    if (!trimmed || trimmed.startsWith('#')) continue
-
-    const eqIdx = trimmed.indexOf('=')
-    if (eqIdx === -1) continue
-
-    const key = trimmed.slice(0, eqIdx).trim()
-    if (!key) continue
-
-    if (process.env[key] !== undefined) continue
-
-    let value = trimmed.slice(eqIdx + 1).trim()
-
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1)
-    } else {
-      // Strip inline comments: space before #, or # at start of value
-      const commentIdx = value.search(/\s#/)
-      if (commentIdx !== -1) {
-        value = value.slice(0, commentIdx).trimEnd()
-      }
-    }
-
-    process.env[key] = value
-  }
-}
-
-/**
- * Public env middleware.
- *
- * Injects `ctx.env` with all environment variables prefixed with `WEIFUWU_PUBLIC_`,
- * with the prefix stripped. Safe to expose to the client.
- *
- * ```ts
- * import { env } from 'weifuwu'
- * app.use(env())
- *
- * // .env:  WEIFUWU_PUBLIC_API_URL=https://api.example.com
- * // ctx:   ctx.env.API_URL === 'https://api.example.com'
- * ```
- */
-export function env(): Middleware<Context, Context & { env: Record<string, string> }> {
-  const entries = getPublicEnv()
-  return async (req, ctx, next) => {
-    ;(ctx as Context & { env: Record<string, string> }).env = entries
-    return next(req, ctx as Context & { env: Record<string, string> })
-  }
-}