@dangao/bun-server 0.4.0 → 1.0.1

package/dist/session/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Session 数据
+ */
+export interface SessionData {
+    [key: string]: unknown;
+}
+/**
+ * Session 信息
+ */
+export interface Session {
+    /**
+     * Session ID
+     */
+    id: string;
+    /**
+     * Session 数据
+     */
+    data: SessionData;
+    /**
+     * 创建时间
+     */
+    createdAt: number;
+    /**
+     * 最后访问时间
+     */
+    lastAccessedAt: number;
+    /**
+     * 过期时间（毫秒时间戳）
+     */
+    expiresAt: number;
+}
+/**
+ * Session 存储接口
+ */
+export interface SessionStore {
+    /**
+     * 获取 Session
+     * @param sessionId - Session ID
+     * @returns Session，如果不存在或已过期则返回 undefined
+     */
+    get(sessionId: string): Promise<Session | undefined>;
+    /**
+     * 设置 Session
+     * @param session - Session 信息
+     * @param maxAge - 最大存活时间（毫秒）
+     * @returns 是否设置成功
+     */
+    set(session: Session, maxAge: number): Promise<boolean>;
+    /**
+     * 删除 Session
+     * @param sessionId - Session ID
+     * @returns 是否删除成功
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * 检查 Session 是否存在
+     * @param sessionId - Session ID
+     * @returns 是否存在
+     */
+    has(sessionId: string): Promise<boolean>;
+    /**
+     * 更新 Session 的最后访问时间
+     * @param sessionId - Session ID
+     * @returns 是否更新成功
+     */
+    touch(sessionId: string): Promise<boolean>;
+    /**
+     * 清空所有 Session
+     * @returns 是否清空成功
+     */
+    clear(): Promise<boolean>;
+}
+/**
+ * 内存 Session 存储实现
+ */
+export declare class MemorySessionStore implements SessionStore {
+    private store;
+    private cleanupInterval?;
+    constructor(options?: {
+        cleanupInterval?: number;
+    });
+    get(sessionId: string): Promise<Session | undefined>;
+    set(session: Session, maxAge: number): Promise<boolean>;
+    delete(sessionId: string): Promise<boolean>;
+    has(sessionId: string): Promise<boolean>;
+    touch(sessionId: string): Promise<boolean>;
+    clear(): Promise<boolean>;
+    /**
+     * 清理过期 Session
+     */
+    private cleanup;
+    /**
+     * 销毁存储，清理定时器
+     */
+    destroy(): void;
+}
+/**
+ * Redis Session 存储实现（需要 redis 包）
+ */
+export interface RedisSessionStoreOptions {
+    /**
+     * Redis 客户端（需要用户提供）
+     */
+    client: {
+        get(key: string): Promise<string | null>;
+        set(key: string, value: string, options?: {
+            PX?: number;
+        }): Promise<void>;
+        del(key: string): Promise<void>;
+        exists(key: string): Promise<number>;
+        expire(key: string, seconds: number): Promise<void>;
+    };
+    /**
+     * 键前缀
+     * @default 'session:'
+     */
+    keyPrefix?: string;
+}
+export declare class RedisSessionStore implements SessionStore {
+    private client;
+    private keyPrefix;
+    constructor(options: RedisSessionStoreOptions);
+    private getKey;
+    get(sessionId: string): Promise<Session | undefined>;
+    set(session: Session, maxAge: number): Promise<boolean>;
+    delete(sessionId: string): Promise<boolean>;
+    has(sessionId: string): Promise<boolean>;
+    touch(sessionId: string): Promise<boolean>;
+    clear(): Promise<boolean>;
+}
+/**
+ * SessionModule 配置选项
+ */
+export interface SessionModuleOptions {
+    /**
+     * Session 存储实现
+     * @default MemorySessionStore
+     */
+    store?: SessionStore;
+    /**
+     * Session 名称（Cookie 名称）
+     * @default 'sessionId'
+     */
+    name?: string;
+    /**
+     * Session 最大存活时间（毫秒）
+     * @default 86400000 (24 小时)
+     */
+    maxAge?: number;
+    /**
+     * 是否在每次访问时更新过期时间
+     * @default true
+     */
+    rolling?: boolean;
+    /**
+     * Cookie 选项
+     */
+    cookie?: {
+        /**
+         * 是否只在 HTTPS 下发送
+         * @default false
+         */
+        secure?: boolean;
+        /**
+         * 是否只能通过 HTTP 访问（不能通过 JavaScript）
+         * @default true
+         */
+        httpOnly?: boolean;
+        /**
+         * Cookie 路径
+         * @default '/'
+         */
+        path?: string;
+        /**
+         * Cookie 域名
+         */
+        domain?: string;
+        /**
+         * SameSite 属性
+         * @default 'lax'
+         */
+        sameSite?: 'strict' | 'lax' | 'none';
+    };
+}
+/**
+ * SessionService Token
+ */
+export declare const SESSION_SERVICE_TOKEN: unique symbol;
+/**
+ * SessionModule Options Token
+ */
+export declare const SESSION_OPTIONS_TOKEN: unique symbol;
+//# sourceMappingURL=types.d.ts.map

package/dist/session/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/readme.md

@@ -2,87 +2,72 @@
 
 [![bun](https://img.shields.io/badge/Bun-1.3%2B-000?logo=bun&logoColor=fff)](https://bun.sh/)
 [![typescript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
-[![license](https://img.shields.io/badge/license-MIT-blue)](#许可证)
-
-> Bun Server 是一个运行在 Bun Runtime 上的高性能、装饰器驱动的 DI Web
-> 框架，目标是为企业级应用提供即开即用的现代体验。
-
-- [Bun Server](#@dangao/bun-server)
-  - [为什么选择 Bun Server](#为什么选择-@dangao/bun-server)
-  - [核心特性](#核心特性)
-  - [架构总览](#架构总览)
-  - [快速上手](#快速上手)
-  - [示例与扩展](#示例与扩展)
-  - [性能与 Benchmark](#性能与-benchmark)
-  - [文档与多语言支持](#文档与多语言支持)
-  - [路线图](#路线图)
-  - [工程规范](#工程规范)
-  - [贡献指南](#贡献指南)
-  - [许可证](#许可证)
-  - [其他语言](#其他语言)
-
-## 为什么选择 Bun Server
-
-- **原生 Bun**：充分利用 Bun Runtime 的高性能 I/O、原生 TypeScript
-  与极速包管理器。
-- **现代 DX**：大量使用装饰器、元数据与
-  DI，让控制器、服务、路由、验证与中间件的编写极其顺滑。
-- **轻量 +
-  可扩展**：松耦合的模块系统、扩展系统与日志框架，既可以快速起步，也能按需裁剪。
-- **Monorepo 友好**：原生支持 Bun workspaces，使用 `workspace:*`
-  协议管理内部依赖，配合 catalog 统一版本，完美适配多包协作场景。
-- **完整测试矩阵**：内置单元/集成测试、压力与基准测试用例，Security 和 Swagger 模块测试覆盖完整，便于持续优化。
-
-## 核心特性
-
-- 🚀 **高性能 HTTP 栈**：基于 `Bun.serve`，提供轻量
-  `Application`、`Router`、`Context` 封装。
-- 🧩
-  **依赖注入容器**：`Container`、`@Injectable()`、`@Inject()`、模块系统、生命周期管理与自动依赖计划缓存。
-- 🧵
-  **中间件管道**：支持全局/控制器/方法级中间件，内置日志、错误处理、CORS、文件上传、静态资源等。
-- ✅ **输入校验**：声明式验证装饰器，直连 `ValidationError` 与异常过滤器。
-- 📡 **WebSocket**：`@WebSocketGateway`、`@OnMessage` 等装饰器级开发体验。
-- 📖 **Swagger/OpenAPI**：内置 Swagger 插件，支持 `@ApiTags`、`@ApiOperation`、`@ApiParam`、`@ApiBody`、`@ApiResponse` 等装饰器，自动生成 API 文档和 Swagger UI。
-- 🔐 **安全认证**：内置 SecurityModule，支持 JWT 和 OAuth2 认证，提供 `@Auth()` 装饰器进行角色权限控制。
-- 📚 **示例与文档**：多语言文档、基础/完整示例、基准脚本与最佳实践。
-
-## 架构总览
+[![license](https://img.shields.io/badge/license-MIT-blue)](#license)
+
+> A high-performance, decorator-driven DI web framework running on Bun Runtime.
+
+- [Why Bun Server](#why-@dangao/bun-server)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Getting Started](#getting-started)
+- [Examples & Extensions](#examples--extensions)
+- [Benchmark Suite](#benchmark-suite)
+- [Docs & Localization](#docs--localization)
+- [Roadmap](#roadmap)
+- [Engineering Guidelines](#engineering-guidelines)
+- [Contributing](#contributing)
+- [License](#license)
+- [Other Languages](#other-languages)
+
+## Why Bun Server
+
+- **Native Bun**: built on top of `Bun.serve`, embracing native TS, fast I/O and
+  the Bun package manager.
+- **Modern DX**: decorators, metadata and DI everywhere — controllers, services,
+  middleware, validation.
+- **Lightweight yet extensible**: modular DI + extension layer + logging
+  provider that scales from MVP to enterprise.
+- **Well-tested**: unit, integration, stress and benchmark suites ship with the
+  repo.
+
+## Features
+
+- 🚀 **Fast HTTP stack** powered by Bun with `Application`, `Router`, `Context`
+  and `ResponseBuilder` helpers.
+- 🧩 **Dependency injection container** with `@Injectable`, `@Inject`, module
+  metadata, lifecycle management and cached dependency plans.
+- 🧵 **Middleware pipeline** with global/class/method scopes plus built-ins
+  (logging, error, CORS, upload, static, ...).
+- ✅ **Input validation** via decorators and `ValidationError` integration.
+- 📡 **WebSocket gateways** with `@WebSocketGateway`, `@OnMessage`, etc.
+- 📚 **Docs & samples** including multi-language docs, benchmark scripts and
+  best practices.
+
+## Architecture
 
 ```
-┌───────────────────────────────┐
-│           Application         │
-│  (Controllers / Modules / DI) │
-└───────────────────────────────┘
-                ↓
-┌───────────────────────────────┐
-│        Middleware Pipeline    │
-│  Logging / Error / Custom ... │
-└───────────────────────────────┘
-                ↓
-┌───────────────────────────────┐
-│   Router + Context + Response │
-└───────────────────────────────┘
-                ↓
-┌───────────────────────────────┐
-│          Bun Runtime          │
-└───────────────────────────────┘
+Application (Controllers / Modules / DI)
+          ↓
+    Middleware Pipeline
+          ↓
+ Router + Context + Response
+          ↓
+        Bun Runtime
 ```
 
-## 快速上手
+## Getting Started
 
-### 环境要求
+### Requirements
 
 - Bun ≥ `1.3.3`
-- Node.js / npm 只在极少数脚手架场景使用
 
-### 安装依赖
+### Install
 
 ```bash
 bun install
 ```
 
-### Hello World 控制器
+### Hello World
 
 ```ts
 import "reflect-metadata";
@@ -111,81 +96,77 @@ app.registerController(HealthController);
 app.listen();
 ```
 
-### 常用脚本
-
-> 代码位于 `packages/@dangao/bun-server/`，以下命令请在该目录执行。
+### Useful scripts
 
 ```bash
-bun --cwd=packages/@dangao/bun-server test             # 运行测试
-bun --cwd=benchmark run bench        # 执行所有基准测试
-bun --cwd=benchmark run bench:router # 仅运行路由基准
-bun --cwd=benchmark run bench:di     # 仅运行 DI 基准
+bun --cwd=packages/@dangao/bun-server test
+bun --cwd=packages/@dangao/bun-server run bench
+bun --cwd=packages/@dangao/bun-server run bench:router
+bun --cwd=packages/@dangao/bun-server run bench:di
 ```
 
-> 直接在仓库根目录运行 `bun test`
-> 会因为工作区结构导致无法找到源文件，请使用上面的命令或先进入
-> `packages/@dangao/bun-server/`。
+> Running `bun test` from the repo root fails because Bun only scans the current
+> workspace. Use the commands above or `cd packages/@dangao/bun-server` first.
 
-## 示例与扩展
+## Examples & Extensions
 
-- `examples/basic-app.ts`：最小可运行示例，覆盖 DI + Logger + Middleware + Swagger + ConfigModule。
-- `examples/full-app.ts`：包含验证、文件上传、WebSocket、复杂控制器，使用 ConfigModule 管理端口与中间件配置。
-- `examples/multi-module-app.ts`：多模块示例，展示模块间的依赖关系和服务共享，使用 ConfigModule 统一管理应用配置。
-- `examples/auth-app.ts`：完整的认证演示，包含 JWT + OAuth2 认证流程、前端演示页面，并通过 ConfigModule 管理应用标题和端口。
-- `packages/bun-server/src/extensions/`：官方扩展（如
-  LoggerExtension、SwaggerExtension），可用于注册第三方能力。
+- `examples/basic-app.ts`: minimal DI + Logger + Middleware showcase.
+- `examples/full-app.ts`: advanced controllers, validation, uploads, WebSocket.
+- `packages/@dangao/bun-server/src/extensions/`: official extensions (e.g.
+  `LoggerExtension`) for plugging in external capabilities.
 
-## 性能与 Benchmark
+## Benchmark Suite
 
-`benchmark/` 目录提供可复现脚本：
+Benchmarks live in `benchmark/` and rely on `PerformanceHarness` &
+`StressTester`.
 
-| Script            | 描述                                       |
-| ----------------- | ------------------------------------------ |
-| `router.bench.ts` | 静态/动态路由命中、handle 以及压力测试     |
-| `di.bench.ts`     | 单例解析、嵌套依赖解析、工厂解析与并发测试 |
+| Script            | Description                                                           |
+| ----------------- | --------------------------------------------------------------------- |
+| `router.bench.ts` | static/dynamic route hits, `router.handle` and stress runs            |
+| `di.bench.ts`     | singleton vs factory resolves, nested dependencies, concurrent stress |
 
-运行方式：
+Run directly:
 
 ```bash
 bun benchmark/router.bench.ts
 bun benchmark/di.bench.ts
 ```
 
-或使用 `bun run bench*` 脚本批量执行，结果会以表格形式打印。
+Or use `bun run bench*` scripts for convenience.
+
+## Docs & Localization
 
-## 文档与多语言支持
+- **English** (default): `docs/api.md`, `docs/guide.md`,
+  `docs/best-practices.md`, `docs/migration.md`, `docs/extensions.md`.
+- **Chinese**: mirrored under `docs/zh/`. If something is missing, please fall
+  back to the English source.
 
-- 中文默认文档位于 `docs/`
-  - `docs/api.md` - API 参考文档
-  - `docs/guide.md` - 使用指南
-  - `docs/extensions.md` - 扩展系统说明（中间件、扩展、模块等）
-  - `docs/best-practices.md` - 最佳实践
-  - `docs/migration.md` - 迁移指南
-- 英文草稿位于
-  `docs/en/`，与中文文件结构一致；如果缺失内容，请优先参考中文版本。
+## Roadmap
 
-## 路线图
+Detailed milestones and history are tracked in
+[`.roadmap/v0.3.0.md`](./.roadmap/v0.3.0.md).
 
-详细路线图、阶段目标与完成情况请查阅 [`.roadmap/v0.3.0.md`](./.roadmap/v0.3.0.md)。
+## Engineering Guidelines
 
-## 工程规范
+- Comments & log messages **must be in English** to keep the codebase
+  international-friendly.
+- Documentation defaults to English; Chinese copies live in `docs/zh/`.
+- Benchmarks belong to `benchmark/` and should run inside Bun environments.
 
-- **注释 & 日志**：统一使用英文，确保国际化友好。
-- **Docs**：默认中文，同时在 `docs/en/` 提供英文版本。
-- **基准脚本**：存放于 `benchmark/`，运行前请确保在 Bun 环境下执行。
+## Contributing
 
-## 贡献指南
+1. Fork & create a feature branch.
+2. Run `bun test` (and relevant benchmarks if the change affects performance).
+3. Submit a PR with a clear description and test evidence.
 
-1. Fork & 创建特性分支
-2. 提交前运行 `bun test` 和相关 benchmark
-3. 提交 PR 时请附带变更说明与必要的测试数据
+Issues and discussions are welcome for new ideas or perf bottlenecks.
 
-欢迎通过 Issue / Discussion 反馈需求或性能瓶颈。
+## License
 
-## 许可证
+Released under the [MIT License](./LICENSE).
 
-本项目基于 [MIT License](./LICENSE) 开源。
+## Other Languages
 
-## 其他语言
+- [中文 README](./readme_zh.md)
 
-- [English README](./readme_en.md)
+Enjoy building on Bun Server!