weifuwu 0.28.2 → 0.30.0

package/README.md

@@ -0,0 +1,394 @@
+# weifuwu
+
+Web-standard HTTP microframework for Node.js — `(req, ctx) => Response`.
+
+## Usage
+
+```bash
+npm install weifuwu
+```
+
+```ts
+import { serve, Router } from 'weifuwu'
+
+const app = new Router()
+app.get('/', () => new Response('Hello'))
+serve(app, { port: 3000 })
+```
+
+## Exports
+
+Everything is exported from `'weifuwu'`:
+
+### Core
+
+| Export | Kind | Description |
+|---|---|---|
+| `serve(app, opts?)` | function | Start HTTP server. Takes a `Router`. Returns `Server`. |
+| `Router` | class | Trie-based HTTP router with WebSocket support. |
+| `loadEnv(path?)` | function | Load `.env` file into `process.env`. |
+| `isDev()` | function | `true` unless `NODE_ENV` is `production` or `test`. |
+| `isProd()` | function | `true` if `NODE_ENV` is `production`. |
+| `isBundled()` | function | `true` when running the esbuild bundle (checks `__WFW_BUNDLED__`). |
+| `getPublicEnv()` | function | Returns all `process.env` keys prefixed with `WEIFUWU_PUBLIC_`. |
+| `DEFAULT_MAX_BODY` | const | `10 * 1024 * 1024` (10MB). |
+
+### Router
+
+```ts
+const app = new Router()
+
+// HTTP methods
+app.get(path, ...handlers)
+app.post(path, ...handlers)
+app.put(path, ...handlers)
+app.delete(path, ...handlers)
+app.patch(path, ...handlers)
+app.head(path, ...handlers)
+app.options(path, ...handlers)
+app.all(path, ...handlers)    // match any method
+
+// WebSocket
+app.ws(path, ...middlewares, handler)
+// handler: { open?, message?, close?, error? }
+
+// Middleware & mounting
+app.use(middleware)           // global middleware
+app.mount(prefix, router)     // mount sub-router at prefix
+app.onError(handler)          // global error handler
+app.routes()                  // debug: string[] of all registered routes
+
+// Path params
+app.get('/users/:id', (req, ctx) => {
+  const id = ctx.params.id   // string
+  const q = ctx.query.search // from ?search=...
+})
+```
+
+### Middleware
+
+| Export | Kind | Description |
+|---|---|---|
+| `cors(opts?)` | middleware | CORS headers. `origin`, `methods`, `headers`, `credentials`, `maxAge`. |
+| `helmet(opts?)` | middleware | Security headers (CSP, HSTS, X-Frame-Options, etc). |
+| `compress(opts?)` | middleware | gzip / brotli / deflate response compression. |
+| `rateLimit(opts?)` | middleware | Sliding-window rate limiter. `windowMs`, `max`, `keyGenerator`. |
+| `requestId(opts?)` | middleware | Generates `X-Request-ID` header. `header`, `generator`. |
+| `logger(opts?)` | middleware | Structured request logging. `format`, `level`, `stream`. |
+| `validate(schemas?)` | middleware | Zod-based request validation. `{ body?, query?, params?, headers? }`. |
+| `upload(opts?)` | middleware | Multipart file upload. `maxSize`, `dest`, `preservePath`. |
+| `health(opts?)` | function→Router | Health check router. Mount at `/_health` or custom path. |
+| `env()` | middleware | Injects `WEIFUWU_PUBLIC_*` env vars into `ctx.env`. |
+| `trace(opts?)` | middleware | Injects trace context into `ctx.trace` (requestId, traceId, startTime, elapsed). |
+
+### Route-level tools
+
+| Export | Kind | Description |
+|---|---|---|
+| `serveStatic(root, opts?)` | handler | Serve static files. `cacheControl`, `index`, `dotfiles`. |
+| `graphql(options)` | function→Router | GraphQL endpoint. Pass a `GraphQLHandler` function `({ query, variables, ctx })`. |
+
+### HTML rendering
+
+| Export | Kind | Description |
+|---|---|---|
+| `html(template, ...values)` | tagged template | Auto-escaped HTML builder. Signal/Computed-aware. |
+| `raw(content)` | function | Raw unescaped HTML string (use with caution). |
+
+### SSE (Server-Sent Events)
+
+| Export | Kind | Description |
+|---|---|---|
+| `createSSEStream()` | function | Create an SSE stream controller for `text/event-stream` responses. |
+| `formatSSE(event, data)` | function | Format a single SSE event string. |
+| `formatSSEData(data)` | function | Format SSE data string. |
+
+### Cookies
+
+| Export | Kind | Description |
+|---|---|---|
+| `getCookies(req)` | function | Parse cookies from `Request`. Returns `Record<string, string>`. |
+| `setCookie(headers, name, value, opts?)` | function | Set `Set-Cookie` header. `path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`, `partitioned`. |
+| `deleteCookie(headers, name, opts?)` | function | Delete a cookie (Max-Age=0). |
+
+### Postgres
+
+| Export | Kind | Description |
+|---|---|---|
+| `postgres(opts?)` | middleware+client | Create a Postgres client. `url`, `host`, `port`, `database`, `user`, `password`, `max`. |
+| `MIGRATIONS_TABLE` | const | Migration table name: `_weifuwu_migrations`. |
+
+```ts
+const sql = postgres({ url: process.env.DATABASE_URL })
+
+// As middleware — injects ctx.sql
+app.use(sql)
+// As query client
+const rows = await sql.client`SELECT * FROM users WHERE id = ${id}`
+
+// Migrations
+await sql.migrate({
+  '001_init': async (s) => {
+    await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`
+  },
+})
+```
+
+### Redis
+
+| Export | Kind | Description |
+|---|---|---|
+| `redis(opts?)` | middleware+client | Create a Redis client (ioredis). `url`, `host`, `port`, `password`, `db`. |
+
+```ts
+const r = redis({ url: process.env.REDIS_URL })
+app.use(r)  // injects ctx.redis
+await r.client.set('key', 'value')
+```
+
+### Queue & Cron
+
+| Export | Kind | Description |
+|---|---|---|
+| `queue(opts?)` | middleware+instance | In-process job queue with cron support. `concurrency`. |
+
+```ts
+const q = queue({ concurrency: 3 })
+app.use(q)  // injects ctx.queue
+
+q.process('send-email', async (job) => {
+  await sendEmail(job.data.to)
+})
+
+q.cron('cleanup', '0 3 * * *', async () => {
+  await cleanupOldSessions()
+})
+
+await q.add('send-email', { to: 'user@example.com' })
+```
+
+### WebSocket Hub
+
+| Export | Kind | Description |
+|---|---|---|
+| `createHub(opts?)` | function | Pub/Sub hub for cross-connection broadcast. Supports Redis adapter for multi-process. |
+
+```ts
+const hub = createHub()
+app.ws('/chat', {
+  open(ws, ctx) {
+    ctx.ws.join('lobby')
+    ctx.ws.json({ type: 'join', room: 'lobby' })
+  },
+  message(ws, ctx, data) {
+    ctx.ws.sendRoom('lobby', { type: 'chat', text: data.toString() })
+  },
+})
+```
+
+### Theme & I18n
+
+| Export | Kind | Description |
+|---|---|---|
+| `theme(opts?)` | middleware+Router | Theme middleware. Injects `ctx.theme` with `get()`, `set(theme)`, `toggle()`. Routes: `/__theme/:theme`. |
+| `i18n(opts?)` | middleware+Router | I18n middleware. Injects `ctx.i18n` with `locale`, `t(key, params?)`, `set(locale)`. `dir` for locale JSON files. Routes: `/__lang/:locale`. |
+| `flash()` | middleware | Flash messages. Injects `ctx.flash` with `set(msg)`, `get()`. One-time messages across redirects. |
+| `csrf()` | middleware | CSRF protection. Injects `ctx.csrf` with `token`. Auto-validates on `POST`/`PUT`/`PATCH`/`DELETE`. |
+
+### Tracing
+
+| Export | Kind | Description |
+|---|---|---|
+| `currentTraceId()` | function | Get current request's trace ID (from AsyncLocalStorage). |
+| `currentTrace()` | function | Get current trace context `{ traceId, startTime }`. |
+| `runWithTrace(id, fn)` | function | Run `fn` with a trace context. Auto-generates ID if null. |
+| `traceElapsed()` | function | Milliseconds since trace start. |
+
+### Error handling
+
+| Export | Kind | Description |
+|---|---|---|
+| `HttpError` | class | `new HttpError(message, status)`. Throw to return that status. |
+| `app.onError(handler)` | Router method | Global error handler: `(error, req, ctx) => Response`. |
+
+### Testing
+
+| Export | Kind | Description |
+|---|---|---|
+| `testApp(app)` | function | Create a test client for a Router. Returns `{ get, post, put, delete, patch }` for `(path, opts?)`. |
+| `createTestServer(app, opts?)` | function | Start a test server on a random port. Returns `{ server, url }`. |
+| `createTestDb()` | function | Create an ephemeral Postgres test database. |
+| `withTestDb(fn)` | function | Run `fn(sql)` with a temp database, auto-cleanup. |
+
+### Types
+
+| Export | Description |
+|---|---|
+| `Context` | `{ params, query, mountPath?, user?, loaderData?, env?, [key: string] }` |
+| `Handler<T>` | `(req: Request, ctx: T) => Response \| Promise<Response>` |
+| `Middleware<In, Out>` | `(req, ctx, next) => Response \| Promise<Response>` |
+| `WebSocketHandler` | `{ open?, message?, close?, error? }` |
+| `HttpError` | `Error` subclass with `.status: number` |
+| `Closeable` | `{ close(): Promise<void> }` |
+| `Server` | `{ stop, close, port, hostname, ready }` |
+| `ServeOptions` | `{ port, hostname, signal, maxBodySize, timeout, keepAliveTimeout, headersTimeout, shutdown }` |
+
+## Handler / Middleware patterns
+
+```ts
+// Handler — standard Web API
+app.get('/api/data', (req, ctx) => {
+  const { q } = ctx.query
+  const id = ctx.params.id
+  return Response.json({ q, id })
+})
+
+// Async
+app.get('/db/users', async (req, ctx) => {
+  const rows = await sql`SELECT * FROM users`
+  return Response.json(rows)
+})
+
+// Throwing HttpError
+app.get('/item/:id', (req, ctx) => {
+  const item = db.get(ctx.params.id)
+  if (!item) throw new HttpError('Not found', 404)
+  return Response.json(item)
+})
+
+// Middleware
+app.use(async (req, ctx, next) => {
+  const start = Date.now()
+  const res = await next(req, ctx)
+  console.log(`${req.method} ${req.url} ${Date.now() - start}ms`)
+  return res
+})
+
+// Route-level middleware (before handler)
+app.get('/admin', validate(bodySchema), authCheck, adminHandler)
+
+// Error handler
+app.onError((err, req, ctx) => {
+  if (err instanceof HttpError) {
+    return Response.json({ error: err.message }, { status: err.status })
+  }
+  console.error(err)
+  return new Response('Internal error', { status: 500 })
+})
+```
+
+## Complete example
+
+```ts
+import { serve, Router, loadEnv, cors, helmet, compress, logger, requestId, rateLimit, postgres, redis, queue, HttpError, html } from 'weifuwu'
+
+loadEnv()
+
+const app = new Router()
+
+// Global middleware
+app.use(requestId())
+app.use(logger())
+app.use(cors())
+app.use(helmet())
+app.use(compress())
+app.use(rateLimit({ windowMs: 60_000, max: 100 }))
+
+// Database & services
+const sql = postgres({ url: process.env.DATABASE_URL })
+const cache = redis({ url: process.env.REDIS_URL })
+const jobs = queue()
+
+app.use(sql)
+app.use(cache)
+app.use(jobs)
+
+// Routes
+app.get('/', () => html`<h1>weifuwu</h1><p>Running on ${process.version}</p>`)
+
+app.get('/api/users', async (req, ctx) => {
+  const users = await ctx.sql`SELECT id, name, email FROM users ORDER BY id`
+  return Response.json(users)
+})
+
+app.get('/api/users/:id', async (req, ctx) => {
+  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
+  if (!user) throw new HttpError('User not found', 404)
+  return Response.json(user)
+})
+
+app.post('/api/users', async (req, ctx) => {
+  const { name, email } = await req.json()
+  const [user] = await ctx.sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`
+  return Response.json(user, { status: 201 })
+})
+
+// Background job
+jobs.process('welcome-email', async (job) => {
+  const { userId } = job.data
+  const [user] = await sql.client`SELECT * FROM users WHERE id = ${userId}`
+  await sendWelcomeEmail(user.email)
+})
+
+app.post('/api/register', async (req, ctx) => {
+  const { name, email } = await req.json()
+  const [user] = await ctx.sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`
+  await ctx.queue.add('welcome-email', { userId: user.id })
+  return Response.json(user, { status: 201 })
+})
+
+// WebSocket chat
+app.ws('/chat', {
+  open(ws, ctx) {
+    ctx.ws.join('lobby')
+  },
+  message(ws, ctx, data) {
+    ctx.ws.sendRoom('lobby', { text: data.toString() })
+  },
+})
+
+// Error handling
+app.onError((err, req, ctx) => {
+  if (err instanceof HttpError) {
+    return Response.json({ error: err.message }, { status: err.status })
+  }
+  return Response.json({ error: 'Internal error' }, { status: 500 })
+})
+
+// Health check
+import { health } from 'weifuwu'
+app.mount('/_health', health())
+
+serve(app, { port: 3000 })
+```
+
+## Project Structure
+
+```
+weifuwu/
+├── package.json
+├── tsconfig.json
+├── scripts/
+│   ├── build.mjs
+│   └── release.mjs
+├── src/
+│   ├── index.ts              ← all exports
+│   ├── types.ts              ← Context, Handler, Middleware, HttpError
+├── core/                 ← serve, router, trace, env, logger, cookie, sse, html
+│   ├── middleware/        ← cors, compress, helmet, rate-limit, static, validate, upload, health, theme, i18n, flash, csrf, request-id
+├── postgres/             ← postgres client, migrations, module injection
+│   ├── redis/                ← redis client
+│   ├── queue/                ← job queue, cron
+│   ├── graphql.ts            ← schema-first GraphQL handler
+│   ├── hub.ts                ← pub/sub hub (WebSocket rooms)
+│   └── test/                 ← 324 tests
+└── dist/
+```
+
+## Development
+
+```bash
+npm run build          # esbuild bundle → dist/index.js
+npm run typecheck      # tsc --noEmit
+npm test              # node --test (324 tests, 0 failures)
+```

package/dist/ai/provider.d.ts

@@ -0,0 +1,45 @@
+import type { Context, Middleware } from '../types.ts';
+import { generateText as aiGenerateText, streamText as aiStreamText, type LanguageModel, type EmbeddingModel } from 'ai';
+declare module '../types.ts' {
+    interface Context {
+        ai: AIProvider;
+    }
+}
+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>;
+}
+export declare function aiProvider(options?: AIProviderOptions): Middleware<Context, Context & AIProviderInjected> & AIProvider;

package/dist/ai/stream.d.ts

@@ -0,0 +1,13 @@
+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 declare const _ai: Record<string, any>;
+/**
+ * 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 declare function aiStream(handler: AIHandler, provider?: AIProvider): Promise<Router>;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+// cli.ts
+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";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var 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, opts) {
+  const targetDir = resolve(process.cwd(), name);
+  if (existsSync(targetDir)) {
+    console.error(`Directory ${name} already exists.`);
+    process.exit(1);
+  }
+  const pkg = await readPkg();
+  const typesNodeVersion = pkg.devDependencies?.["@types/node"] || "^22";
+  if (opts.ssr) {
+    await generateReactSsr(targetDir, name, pkg.version, typesNodeVersion, opts.skipInstall);
+  } else {
+    await generateMinimal(targetDir, name, pkg.version, typesNodeVersion, opts.skipInstall);
+  }
+}
+async function generateMinimal(targetDir, name, version, typesNodeVersion, skipInstall) {
+  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 writePackageJson(targetDir, name, version, typesNodeVersion, {});
+  await writeCommonFiles(targetDir);
+  await finishInit(targetDir, skipInstall);
+}
+async function generateReactSsr(targetDir, name, version, typesNodeVersion, skipInstall) {
+  const templateDir = join(pkgRoot, "cli", "template", "react");
+  await copyRecursive(templateDir, targetDir);
+  await writePackageJson(targetDir, name, version, typesNodeVersion, {
+    dependencies: {
+      react: "^19",
+      "react-dom": "^19",
+      "@tailwindcss/postcss": "^4",
+      tailwindcss: "^4",
+      postcss: "^8"
+    },
+    devDependencies: {
+      "@types/react": "^19",
+      "@types/react-dom": "^19",
+      esbuild: "^0.28"
+    }
+  });
+  await writeFile(join(targetDir, ".gitignore"), "node_modules\n.env\n.weifuwu\n");
+  await finishInit(targetDir, skipInstall);
+}
+async function copyRecursive(src, dest) {
+  const { readdir, stat, copyFile } = await import("node:fs/promises");
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await mkdir(destPath, { recursive: true });
+      await copyRecursive(srcPath, destPath);
+    } else if (entry.isFile()) {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+async function writePackageJson(targetDir, name, version, typesNodeVersion, extra) {
+  const pkg = {
+    name,
+    type: "module",
+    scripts: {
+      dev: "node --watch index.ts",
+      start: "node index.ts"
+    },
+    dependencies: {
+      weifuwu: "^" + version
+    },
+    devDependencies: {
+      "@types/node": typesNodeVersion
+    }
+  };
+  if (extra) {
+    if (extra.dependencies) {
+      Object.assign(pkg.dependencies, extra.dependencies);
+    }
+    if (extra.devDependencies) {
+      Object.assign(pkg.devDependencies, extra.devDependencies);
+    }
+  }
+  await writeFile(join(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+}
+async function writeCommonFiles(targetDir) {
+  await writeFile(join(targetDir, ".gitignore"), "node_modules\n.env\n.weifuwu\n");
+  await writeFile(join(targetDir, ".env"), "PORT=3000\n");
+}
+async function finishInit(targetDir, skipInstall) {
+  if (!skipInstall) {
+    console.log("\nInstalling dependencies...");
+    execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+  }
+  console.log(`
+\u2705 Created ${targetDir.split("/").pop()}/`);
+  console.log(`   cd ${targetDir.split("/").pop()}`);
+  if (skipInstall) console.log(`   npm install`);
+  console.log(`   npm run dev`);
+}
+var cmd = process.argv[2];
+var HELP = `
+weifuwu \u2014 Web-standard HTTP microframework for Node.js
+
+Usage:
+  npx weifuwu init <name>                Create a new API project
+  npx weifuwu init <name> --ssr          Create a React SSR project
+  npx weifuwu init <name> --skip-install  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" },
+      "ssr": { type: "boolean" },
+      "react": { type: "boolean" }
+    },
+    strict: false,
+    allowPositionals: true
+  });
+  const name = positionals[0];
+  if (!name) {
+    console.error("Usage: npx weifuwu init <name> [--ssr] [--skip-install]");
+    process.exit(1);
+  }
+  cmdInit(name, {
+    skipInstall: !!values["skip-install"],
+    ssr: !!(values["ssr"] || values["react"])
+  }).catch(
+    console.error
+  );
+} else {
+  console.log(HELP);
+}

package/dist/core/cookie.d.ts

@@ -0,0 +1,36 @@
+/** 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 declare function getCookies(req: Request): Record<string, string>;
+/** 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 declare function setCookie(res: Response, name: string, value: string, options?: CookieOptions): Response;
+/** Delete a cookie by setting `Max-Age=0`.
+ *
+ * @example
+ * ```ts
+ * return deleteCookie(res, 'session')
+ * ``` */
+export declare function deleteCookie(res: Response, name: string, options?: Omit<CookieOptions, 'maxAge'>): Response;