pocketbase-tools

PocketBase Tools

一个用于 PocketBase 的 TypeScript 工具库，提供完整的客户端管理、服务操作和类型定义。

🚀 特性

• ✅ 完整的导出管理 - 所有模块都已正确导出
• ✅ TypeScript 支持 - 完整的类型定义
• ✅ 代码格式化 - 自动格式化和代码质量检查
• ✅ 生产环境优化 - 代码混淆和压缩
• ✅ 多格式支持 - ESM 和 CommonJS 双格式输出

📦 安装

npm install pocketbase-tools
# 或
yarn add pocketbase-tools
# 或
bun add pocketbase-tools

🛠️ 开发脚本

构建相关

# 开发环境构建（未压缩，包含 source map）
bun run build:dev

# 生产环境构建（压缩混淆，移除 console）
bun run build:prod

# 默认构建（等同于 build:prod）
bun run build

代码质量

# 格式化所有代码
bun run format

# 检查代码格式
bun run format:check

其他

# 生成文档
bun run docs

# 运行测试
bun run test

# 监听测试
bun run test:watch

# 安装依赖
bun run setup

📁 项目结构

src/
├── base/           # 基础客户端和设置
│   ├── client.ts   # PocketBase 客户端管理
│   └── setup.ts    # 集合预设置
├── services/       # 业务服务
│   ├── auth.action.ts     # 认证服务
│   ├── product.action.ts  # 产品服务
│   ├── profile.action.ts  # 配置文件服务
│   └── user.action.ts     # 用户服务
├── types/          # 类型定义
│   ├── index.ts           # 类型导出
│   ├── product.types.ts   # 产品类型
│   ├── profile.types.ts   # 配置文件类型
│   └── user.types.ts      # 用户类型
├── utils/          # 工具函数
│   ├── index.ts           # 工具导出
│   ├── env.ts             # 环境变量处理
│   ├── errorHandler.ts    # 错误处理
│   ├── logger.ts          # 日志工具
│   └── useFiles.ts        # 文件处理
└── index.ts        # 主入口文件

🔧 配置文件

Prettier 配置 (.prettierrc)

• 使用双引号
• 2 空格缩进
• 行宽 80 字符
• 尾随逗号

ESLint 配置 (.eslintrc.js)

• TypeScript 支持
• 推荐规则集
• 自定义代码风格规则

Vite 配置 (vite.config.ts)

• 开发/生产环境区分
• 生产环境代码混淆和压缩
• 自动生成类型声明文件
• Source map 支持

📤 导出内容

基础模块

import { usePBClient, resetPBInstances } from "pocketbase-tools";
import {
  getCollect,
  userCollect,
  productCollect,
  profileCollect,
} from "pocketbase-tools";
import pb from "pocketbase-tools";

服务模块

import {
  // 认证服务
  useAuth,

  // 产品服务
  addProduct,
  updateProduct,
  deleteProduct,
  getAllProducts,
  getProductById,

  // 用户服务
  getAllUsers,
  addUser,
  updateUser,
  deleteUser,

  // 配置文件服务
  listAllCompanyProfiles,
  addCompanyProfile,
  updateCompanyProfile,
  deleteCompanyProfile,
} from "pocketbase-tools";

类型定义

import {
  User,
  UserCreate,
  UserUpdate,
  Product,
  ProfileCollection,
} from "pocketbase-tools";

工具函数

import {
  getEnvVar,
  validateEnvVars,
  withErrorHandling,
  logger,
} from "pocketbase-tools";

🎯 使用示例

import { usePBClient, getAllUsers, logger } from "pocketbase-tools";

// 初始化客户端
const pb = usePBClient({
  url: "http://localhost:8090",
});

// 或者使用默认的
import pb from "pocketbase-tools";

// 使用服务
const users = await getAllUsers();
logger.success("获取用户列表成功", users);

认证服务 (useAuth)

useAuth 提供了灵活的认证方法，支持在登录和刷新时指定 PocketBase 客户端的 URL 或实例。

import { useAuth } from "pocketbase-tools";
import PocketBase from "pocketbase"; // 如果需要直接传入实例

// 示例 1: 登录时指定自定义 URL
const adminLoginWithUrl = await useAuth.login('admin', {
    email: '[e-mail]',
    password: 'admin123456',
}, {
    url: 'http://127.0.0.1:8090', // 指定 PocketBase 服务地址
});
logger.success('管理员通过自定义 URL 登录成功', adminLoginWithUrl.record);

// 示例 2: 登录时指定自定义 PocketBase 实例
const customPbInstance = new PocketBase('http://127.0.0.1:8090');
const adminLoginWithInstance = await useAuth.login('admin', {
    email: '[e-mail]',
    password: 'admin123456',
}, {
    instance: customPbInstance, // 传入自定义 PocketBase 实例
});
logger.success('管理员通过自定义实例登录成功', adminLoginWithInstance.record);

// 示例 3: 使用默认配置的客户端 (例如，通过环境变量 VITE_POCKETBASE_URL 配置)
const adminLoginDefault = await useAuth.login('admin', {
    email: '[e-mail]',
    password: 'admin123456',
});
logger.success('管理员通过默认客户端登录成功', adminLoginDefault.record);

// 刷新认证信息时也可以使用 clientOptions
const refreshedAuth = await useAuth.refresh('admin', { url: 'http://127.0.0.1:8090' });
logger.success('刷新认证信息成功', refreshedAuth.record);

• 文件获取

import { filesCollect } from "pocketbase-tools";

// 获取最新的文件记录
const [record] = await filesCollect.getFullList({
    sort: '-created',
    limit: 1,
});
// 获取文件信息
console.log(useFiles.getAbsoluteURL(record, record?.file))

🔄 发布流程

项目配置了 prepack 钩子，在发布前会自动执行生产环境构建：

npm publish
# 会自动执行: bun run build:prod

📝 开发注意事项

• 代码提交前：运行 bun run format 确保代码格式正确
• 构建测试：使用 bun run build:prod 测试生产环境构建
• 类型检查：确保所有导出都有正确的类型定义
• 文档更新：新增功能时更新 README 和类型注释

📄 许可证

MIT License