js-lite-rest

v0.0.5

Published

3 months ago

纯前端 RESTful 风格增删改查。

0High
0Medium
0Low

wll8

json store localStorage nodejs browser restful database json-server lightweight client-side data-storage

js-lite-rest

纯前端 RESTful 风格增删改查库，适用于单机应用和原型开发。无需后端服务器，即可实现完整的数据 CRUD 操作。

📚 文档地址 | 🎮 在线示例

English Documentation

✨ 特性

🚀 轻量级：自包含设计，UMD 版本无需额外依赖
🌐 跨平台：同时支持 Node.js 和浏览器环境
📦 多种存储：支持内存、文件系统、localStorage 存储
🔄 RESTful API：提供标准的 HTTP 风格 CRUD 操作接口
🎯 TypeScript 支持：完整的类型定义，开发体验更佳
🔧 可扩展：支持中间件和自定义适配器
⚡ 异步操作：所有操作都是异步的，性能更好
🔗 关联查询：支持嵌套资源和关联数据查询
📝 批量操作：支持批量增删改查操作

📦 安装

npm install js-lite-rest

或者使用其他包管理器：

yarn add js-lite-rest
pnpm add js-lite-rest

CDN 引入

<!-- ES Module (浏览器专用版本，包含 localforage) -->
<script type="module">
  import JsLiteRest from 'https://unpkg.com/js-lite-rest/dist/js-lite-rest.browser.mjs';
  const store = await JsLiteRest.create();
</script>

<!-- UMD (全局变量，自包含，无需额外依赖) -->
<script src="https://unpkg.com/js-lite-rest/dist/js-lite-rest.umd.js"></script>
<script>
  // 使用全局变量 JsLiteRest
  const store = await JsLiteRest.create();
</script>

📚 多环境支持

js-lite-rest 提供了多种构建格式，可在不同环境中无缝使用：

| 环境 | 格式 | 文件 | 使用方式 | |------|------|------|----------| | Node.js | CommonJS | js-lite-rest.cjs | require('js-lite-rest') | | Node.js | ES Module | js-lite-rest.mjs | import JsLiteRest from 'js-lite-rest' | | 浏览器 | ES Module | js-lite-rest.browser.mjs | import JsLiteRest from '...' | | 浏览器 | UMD | js-lite-rest.umd.js | <script src="..."> |

自动环境检测：当使用 import 或 require 导入时，会自动根据环境选择合适的构建文件。

浏览器环境特性：

✅ 浏览器版本内置 localforage，支持 IndexedDB、WebSQL、localStorage
✅ 自动选择最佳存储方案，提供更大的存储空间
✅ 通过 JsLiteRest.lib.localforage 访问底层存储 API

🚀 快速开始

Node.js 环境

import JsLiteRest from 'js-lite-rest';

// 创建 store 实例，数据将保存到文件
const store = await JsLiteRest.create({
  books: [
    { id: 1, title: 'JavaScript 权威指南', author: 'David Flanagan' },
    { id: 2, title: 'Node.js 实战', author: 'Mike Cantelon' }
  ]
});

// 查询所有书籍
const books = await store.get('books');
console.log(books); // 返回所有书籍

// 获取特定书籍
const book = await store.get('books/1');
console.log(book); // { id: 1, title: 'JavaScript 权威指南', author: 'David Flanagan' }

// 添加新书籍（自动生成 ID）
const newBook = await store.post('books', { title: 'Vue.js 实战', author: 'John Doe' });
console.log(newBook); // { id: 3, title: 'Vue.js 实战', author: 'John Doe' }

// 更新书籍
await store.put('books/1', { title: 'JavaScript 高级程序设计', author: 'Nicholas C. Zakas' });

// 部分更新
await store.patch('books/1', { author: 'Nicholas Zakas' });

// 删除书籍
await store.delete('books/2');

浏览器环境

<!DOCTYPE html>
<html>
<head>
  <title>js-lite-rest 示例</title>
  <!-- 使用 UMD 版本，自包含无需额外依赖 -->
  <script src="https://unpkg.com/js-lite-rest/dist/js-lite-rest.umd.js"></script>
  <script>
    async function demo() {
      // 在浏览器中使用 localStorage 存储
      const store = await JsLiteRest.create();

      // 添加用户数据
      await store.post('users', { name: 'Alice', email: '[email protected]' });
      await store.post('users', { name: 'Bob', email: '[email protected]' });

      // 查询所有用户
      const users = await store.get('users');
      console.log('所有用户:', users);

      // 查询特定用户
      const user = await store.get('users/1');
      console.log('用户 1:', user);
    }
    
    // 等待页面加载后执行
    document.addEventListener('DOMContentLoaded', demo);
  </script>
</head>
<body>
  <h1>js-lite-rest 浏览器示例</h1>
  <p>打开控制台查看输出结果</p>
</body>
</html>

📖 API 文档

JsLiteRest.create(data?, options?)

创建一个新的 store 实例。

参数

data (可选)

类型: string | object | null
默认值: {}

数据源配置：

字符串:
- Node.js 环境：作为 JSON 文件路径
- 浏览器环境：作为 localStorage 的 key
对象: 直接使用该对象作为初始数据
null: 使用自定义适配器（需在 options 中配置）
未传入: 使用默认存储位置
- 浏览器：localStorage key 为 js-lite-rest
- Node.js：当前目录下的 js-lite-rest.json 文件

options (可选)

类型: StoreOptions

配置选项：

idKeySuffix: ID 键后缀，默认为 'Id'
savePath: 自定义保存路径
load: 自定义加载函数
save: 自定义保存函数
adapter: 自定义适配器

Store 实例方法

GET 操作

// 获取所有记录
await store.get('users');

// 获取特定记录
await store.get('users/1');

// 嵌套资源查询
await store.get('posts/1/comments');

POST 操作

// 添加单条记录
await store.post('users', { name: 'Alice', email: '[email protected]' });

// 批量添加
await store.post('users', [
  { name: 'Bob', email: '[email protected]' },
  { name: 'Charlie', email: '[email protected]' }
]);

// 嵌套资源添加
await store.post('posts/1/comments', { content: '很好的文章！' });

PUT 操作

// 完全替换记录
await store.put('users/1', { name: 'Alice Smith', email: '[email protected]' });

// 批量更新
await store.put('users', [
  { id: 1, name: 'Alice Updated' },
  { id: 2, name: 'Bob Updated' }
]);

PATCH 操作

// 部分更新记录
await store.patch('users/1', { name: 'Alice Johnson' });

DELETE 操作

// 删除单条记录
await store.delete('users/1');

// 批量删除  
await store.delete('users', ['user1', 'user2', 'user3']);

🔧 高级用法

中间件

使用中间件可以在请求前后执行自定义逻辑：

const store = await JsLiteRest.create();

// 添加日志中间件
store.use(async (args, next, opt) => {
  const [method, path] = args;
  console.log(`${method.toUpperCase()} ${path}`);

  const result = await next();
  console.log('结果:', result);

  return result;
});

// 添加验证中间件
store.use(async (args, next, opt) => {
  const [method, path, data] = args;

  if (method === 'post' && path === 'users') {
    if (!data.email) {
      throw new Error('邮箱是必填项');
    }
  }

  return next();
});

自定义适配器

// 创建自定义适配器
class CustomAdapter {
  constructor(config) {
    this.config = config;
  }

  async get(path) {
    // 自定义获取逻辑
  }

  async post(path, data) {
    // 自定义创建逻辑
  }

  // ... 其他方法
}

// 使用自定义适配器
const store = await JsLiteRest.create(null, {
  adapter: new CustomAdapter({ /* 配置 */ })
});

关联数据

支持嵌套资源和关联查询：

const store = await JsLiteRest.create({
  posts: [
    { id: 1, title: '第一篇文章', authorId: 1 },
    { id: 2, title: '第二篇文章', authorId: 2 }
  ],
  comments: [
    { id: 1, content: '很好的文章！', postId: 1 },
    { id: 2, content: '我也这么认为', postId: 1 }
  ]
});

// 获取文章的所有评论
const comments = await store.get('posts/1/comments');
console.log(comments); // 返回 postId 为 1 的所有评论

🛠️ 开发

环境要求

Node.js 20+
pnpm 10+

开发脚本

# 安装依赖
pnpm install

# 运行测试
pnpm test                    # Node.js 环境开发测试
pnpm test:dev:browser        # 浏览器环境开发测试
pnpm test:build              # Node.js 环境构建测试
pnpm test:build:browser      # 浏览器环境构建测试

# 构建项目
pnpm build

# 多环境导入测试
node test/import-tests/test-cjs.cjs        # CommonJS 测试
node test/import-tests/test-esm.mjs        # ES Module 测试
node test/import-tests/server.mjs          # 启动浏览器测试服务器

# 开发文档
pnpm docs:dev

# 构建文档
pnpm docs:build

测试覆盖

项目包含完整的测试套件，覆盖所有环境和格式：

✅ 121 个功能测试：涵盖所有 CRUD 操作、中间件、拦截器等
✅ 4 种环境测试：Node.js (CJS/ESM) + 浏览器 (ESM/UMD)
✅ 32 个导入测试：验证各种使用场景

详见 test/import-tests/README.md

技术栈

构建工具: Rollup
测试框架: Mocha + Chai
代码规范: @antfu/eslint-config
文档: VitePress
包管理: pnpm

📋 待办事项

[x] JSON 适配器
[x] 浏览器支持
[x] 中间件系统
[x] Node.js 支持
[x] TypeScript 类型定义
[x] 批量操作
[x] 嵌套资源
[ ] SQLite 适配器
[ ] 数据验证
[ ] 查询过滤器

🔗 相关项目

Dexie - 现代浏览器 IndexedDB 包装器
PouchDB - 浏览器和 Node.js 的数据库
JSStore - 类 SQL 的 IndexedDB 包装器
Lovefield - Google 的关系型数据库库

📄 许可证

MIT © xw

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

js-lite-rest

✨ 特性

📦 安装

CDN 引入

📚 多环境支持

🚀 快速开始

Node.js 环境

浏览器环境

📖 API 文档

JsLiteRest.create(data?, options?)

参数

Store 实例方法

GET 操作

POST 操作

PUT 操作

PATCH 操作

DELETE 操作

🔧 高级用法

中间件

自定义适配器

关联数据

🛠️ 开发

环境要求

开发脚本

测试覆盖

技术栈

📋 待办事项

🔗 相关项目

📄 许可证

🤝 贡献