imean-cassandra-orm 1.5.0 → 2.0.0

package/README.md

@@ -1,6 +1,17 @@
-# Cassandra ORM
+# IMean Cassandra ORM
 
-一个简单易用的 Cassandra ORM 库，提供类型安全的 API。
+一个基于 Zod 的 Cassandra ORM，提供类型安全的 schema 定义和数据库操作。
+
+## 特性
+
+- 🎯 **类型安全**: 基于 Zod 的 schema 验证和 TypeScript 类型推断，确保入库和出库的数据类型安全。
+- 🔧 **自动 CQL 生成**: 自动生成 Cassandra CQL 语句，无需手写。
+- 📊 **完整 CRUD**: 支持插入、查询、更新、删除操作。
+- 🚀 **批量操作**: 支持批量插入，提升性能。
+- 🎨 **简洁 API**: 简单易用的 API 设计，通过 Client 统一管理模型。
+- 🔄 **Schema 同步**: 自动创建和同步 keyspace 和表结构。
+- ⚙️ **Keyspace 配置**: 支持自定义复制策略和配置。
+- 🤖 **自动序列化**: 自动处理复杂类型（如 JSON 对象、数组）的序列化和反序列化。
 
 ## 安装
 
@@ -8,341 +19,240 @@
 npm install imean-cassandra-orm
 ```
 
-## 使用示例
-
-```typescript
-import { Client as CassandraClient, auth } from "cassandra-driver";
-import { Client, Field, uuid, type Infer } from "imean-cassandra-orm";
+## 快速开始
 
-// 创建原始 Cassandra 客户端
-const cassandraClient = new CassandraClient({
-  contactPoints: ["localhost"],
-  localDataCenter: "datacenter1",
-  authProvider: new auth.PlainTextAuthProvider("cassandra", "cassandra"),
-});
+### 1. 定义 Schema
 
-// 创建我们的客户端
-const client = new Client(cassandraClient);
+使用 `TableSchema` 和 `zod` 来定义你的表结构。ORM 会根据你的定义自动推断类型和生成数据库表。
 
-// 设置 keyspace
-await client.useKeyspace("my_keyspace", {
-  class: "SimpleStrategy",
-  replication_factor: 1,
+```typescript
+import { z } from "zod";
+import { TableSchema } from "imean-cassandra-orm";
+
+// 定义用户表 schema
+const userSchema = new TableSchema({
+  fields: {
+    user_id: z.string(),
+    email: z.string().email(),
+    name: z.string(),
+    age: z.number().int().positive(),
+    is_active: z.boolean(),
+    metadata: z.record(z.any()), // 可以是任意复杂的对象
+    created_at: z.date(),
+  },
+  partitionKey: ["user_id"],
+  tableName: "users",
+  keyspace: "my_app_keyspace",
 });
 
-// 创建用户模型
-const userModel = client.createModel(
-  {
-    id: Field.uuid().partitionKey(),      // 分区键，必填
-    name: Field.text().clusteringKey(),   // 聚类键，必填
-    age: Field.int().optional(),          // 可选字段
-    email: Field.text(),                  // 普通字段，必填
+// 定义帖子表 schema（带聚类键）
+const postSchema = new TableSchema({
+  fields: {
+    user_id: z.string(),
+    post_id: z.string(),
+    title: z.string(),
+    content: z.string(),
+    tags: z.array(z.string()), // 数组类型
+    published_at: z.date(),
   },
-  "users"
-);
-type User = Infer<typeof userModel>;
+  partitionKey: ["user_id"],
+  clusteringKey: { post_id: "desc" }, // 按 post_id 降序
+  tableName: "posts",
+  keyspace: "my_app_keyspace",
+});
+```
 
-// 创建文章模型
-const postModel = client.createModel(
-  {
-    id: Field.uuid().partitionKey(),      // 分区键，必填
-    title: Field.text(),                  // 普通字段，必填
-    content: Field.text(),                // 普通字段，必填
-    created_at: Field.timestamp(),        // 普通字段，必填
-  },
-  "posts"
-);
+### 2. 创建 Client 和模型
 
-// 同步所有表结构
-await client.syncAllSchemas();
+`Client` 是所有操作的入口。你需要先创建一个 `Client` 实例，然后用它来创建 `Model` 实例。
 
-// 创建用户
-const user = await userModel.create({
-  id: uuid(),           // 必须提供分区键
-  name: "张三",         // 必须提供聚类键
-  age: 25,             // 可选
-  email: "zhangsan@example.com"  // 必填
-});
+```typescript
+import { Client } from "imean-cassandra-orm";
 
-// 创建文章
-await postModel.create({
-  id: uuid(),
-  title: "测试文章",
-  content: "内容",
-  created_at: new Date(),
+// 1. 创建 Client 实例
+const client = new Client({
+  contactPoints: ["localhost"],
+  localDataCenter: "datacenter1",
 });
 
-// 查询用户
-const foundUser = await userModel.findOne({ id: user.id });
-console.log(foundUser);
+// 2. 连接到 Cassandra
+await client.connect();
 
-// 关闭连接
-await client.close();
-```
+// 3. (可选) 删除旧的 keyspace 以进行全新测试
+await client.dropKeyspace("my_app_keyspace");
 
-## API 参考
+// 4. 通过 Client 创建模型实例
+const userModel = client.createModel(userSchema);
+const postModel = client.createModel(postSchema);
 
-### 类型推导工具
+// 5. 同步所有模型的 Schema
+// 这会确保 keyspace 和所有相关的表都已创建
+await client.syncSchema();
+```
 
-ORM 库提供了一系列类型推导工具，可以帮助开发者在上层 API 中实现类型安全。
+`client.syncSchema()` 会自动处理所有已创建模型的 schema 同步，你不再需要为每个模型单独调用 `syncSchema()`。
 
-#### Infer<M>
+### 3. 基本操作
 
-从 Model 实例中推断出原始字段类型。
+模型实例提供了完整的 CRUD API。
 
 ```typescript
-const userModel = client.createModel({
-  id: Field.uuid().partitionKey(),
-  name: Field.text().clusteringKey(),
-  age: Field.int().optional(),
-  email: Field.text(),
-}, "users");
-
-type User = Infer<typeof userModel>;
-// 推导结果: { id: string; name: string; age?: number; email: string }
-```
+// 插入数据 (自动序列化 metadata 对象)
+const userData = {
+  user_id: "user1",
+  email: "user1@example.com",
+  name: "张三",
+  age: 25,
+  is_active: true,
+  metadata: { score: 95.5, level: 3, tags: ["vip"] },
+  created_at: new Date(),
+};
+await userModel.insert(userData);
 
-#### InferPartitionKey<M>
+// 查询数据 (自动反序列化 metadata)
+const foundUser = await userModel.findOne({ user_id: "user1" });
+console.log(foundUser?.metadata); // { score: 95.5, level: 3, tags: ["vip"] }
 
-推导分区键字段类型。
+// 更新数据
+await userModel.update(
+  { user_id: "user1" },
+  { name: "李四", age: 26 }
+);
 
-```typescript
-type UserPartitionKey = InferPartitionKey<typeof userModel>;
-// 推导结果: { id: string }
+// 删除数据
+await userModel.delete({ user_id: "user1" });
 ```
 
-#### InferClusteringKey<M>
-
-推导聚类键字段类型。
+### 4. 批量操作
 
 ```typescript
-type UserClusteringKey = InferClusteringKey<typeof userModel>;
-// 推导结果: { name: string }
+// 批量插入
+const usersData = [
+  {
+    user_id: "user2",
+    email: "user2@example.com",
+    name: "王五",
+    age: 30,
+    is_active: true,
+    metadata: { score: 88.0 },
+    created_at: new Date(),
+  },
+  {
+    user_id: "user3",
+    email: "user3@example.com",
+    name: "赵六",
+    age: 28,
+    is_active: false,
+    metadata: { score: 79.2 },
+    created_at: new Date(),
+  },
+];
+await userModel.batchInsert(usersData);
 ```
 
-#### InferNonPartitionFields<S>
+### 5. 使用聚类键
 
-推导非分区键字段类型。
+当你的 schema 定义了 `clusteringKey` 时，你可以在查询、更新和删除操作中指定它。
 
 ```typescript
-type UserFields = {
-  id: { type: "uuid"; flags: { partitionKey: true } };
-  name: { type: "text" };
-  age: { type: "int" };
+// 插入带聚类键的数据
+const postData = {
+  user_id: "user1",
+  post_id: "post1",
+  title: "我的第一篇帖子",
+  content: "这是内容...",
+  tags: ["技术", "编程"],
+  published_at: new Date(),
 };
+await postModel.insert(postData);
+
+// 查询特定帖子
+const post = await postModel.findOne(
+  { user_id: "user1" },
+  { post_id: "post1" } // 指定聚类键
+);
+
+// 更新特定帖子
+await postModel.update(
+  { user_id: "user1" },
+  { title: "更新后的标题" },
+  { post_id: "post1" } // 指定聚类键
+);
 
-type NonPartitionFields = InferNonPartitionFields<UserFields>;
-// 推导结果: { name: string; age: number }
+// 删除特定帖子
+await postModel.delete(
+  { user_id: "user1" }, 
+  { post_id: "post1" } // 指定聚类键
+);
 ```
 
-#### InferStaticFields<M>
+### 6. 类型安全与校验
 
-推导静态字段类型。
+ORM 会在数据返回时使用 Zod schema 进行校验，确保你得到的数据是类型安全的。
 
 ```typescript
-const userModel = client.createModel({
-  id: Field.uuid().partitionKey(),
-  name: Field.text().static(),    // 静态字段
-  age: Field.int().optional(),
-  email: Field.text(),
-}, "users");
-
-type UserStaticFields = InferStaticFields<typeof userModel>;
-// 推导结果: { name: string }
+// 从数据库返回的数据
+const userFromDb = await userModel.findOne({ user_id: "user1" });
+
+// userFromDb 的类型是根据 userSchema 推断出来的，具有完整的类型提示
+if (userFromDb) {
+  console.log(userFromDb.name.toUpperCase());
+}
+
+// 如果数据库中的数据不符合 schema（例如，手动修改了数据库），
+// 在查询时会抛出 ZodError，防止脏数据进入你的应用。
 ```
 
-静态列的特点：
-1. 在分区级别存储数据，而不是在每一行重复存储
-2. 适用于在分区内所有行共享相同值的字段
-3. 可以节省存储空间
-4. 提高查询效率
+## API 参考
+
+### `Client`
 
-这些类型工具可以用于：
+#### `new Client(options: cassandra.ClientOptions)`
 
-1. 在 API 层定义类型安全的接口
-2. 在服务层进行类型检查
-3. 在数据访问层确保数据一致性
-4. 在业务逻辑层进行类型推导
+创建一个新的 Client 实例。`options` 与 `cassandra-driver` 的 `ClientOptions` 相同。
 
-### Client
+#### `client.connect(): Promise<void>`
 
-`Client` 类是对原始 Cassandra 客户端的封装，提供了更高级的 API。
+连接到 Cassandra 集群。
 
-#### 构造函数
+#### `client.createModel(schema: TableSchema): Model`
 
-```typescript
-constructor(cassandraClient: CassandraClient)
-```
+根据 `TableSchema` 创建一个 `Model` 实例。
 
-#### 方法
+#### `client.syncSchema(): Promise<void>`
 
-- `useKeyspace(keyspace: string, options: KeyspaceOptions): Promise<void>`
-  - 设置当前使用的 keyspace，如果不存在则创建
-  - `options`:
-    - `class`: 复制策略，可以是 `"SimpleStrategy"` 或 `"NetworkTopologyStrategy"`
-    - `replication_factor`: 复制因子（仅用于 `SimpleStrategy`）
-    - `datacenters`: 数据中心配置（仅用于 `NetworkTopologyStrategy`）
+同步所有通过 `createModel` 创建的模型的 schema。
 
-- `createModel<S extends Record<string, FieldConfig<keyof TypeMap>>>(schema: S, tableName: string): Model<S>`
-  - 创建并注册一个新的模型
-  - 返回的模型实例可以直接使用，不需要额外获取
+#### `client.dropKeyspace(keyspace: string): Promise<void>`
 
-- `syncAllSchemas(): Promise<void>`
-  - 同步所有已注册模型的结构到数据库
+删除一个 keyspace。
 
-- `close(): Promise<void>`
-  - 关闭数据库连接
+### `Model`
 
-### Model
+#### `model.insert(data: T): Promise<void>`
 
-`Model` 类提供了对数据库表的操作接口。
+插入一条数据。
 
-#### 类型推导示例
+#### `model.batchInsert(data: T[]): Promise<void>`
 
-```typescript
-// 定义模型 schema
-const userModel = client.createModel({
-  id: Field.uuid().partitionKey(),      // 分区键，必填
-  name: Field.text().clusteringKey(),   // 聚类键，必填
-  age: Field.int().optional(),          // 可选字段
-  email: Field.text(),                  // 普通字段，必填
-}, "users");
-
-// 推导出的类型：
-type User = {
-  id: string;           // 分区键，必填
-  name: string;         // 聚类键，必填
-  age?: number;         // 可选字段
-  email: string;        // 普通字段，必填
-};
+批量插入多条数据。
 
-// 分区键类型（用于查询和删除）
-type PartitionKey = {
-  id: string;
-};
+#### `model.find(partitionKey: PK): Promise<T[]>`
 
-// 聚类键类型（用于查询和删除）
-type ClusteringKey = {
-  name: string;
-};
+根据分区键查询多条数据。
 
-// 可更新字段类型（用于更新操作）
-type UpdatableFields = {
-  age?: number;         // 可选字段
-  email: string;        // 普通字段
-};
-```
+#### `model.findOne(partitionKey: PK, clusteringKey?: CK): Promise<T | null>`
+
+根据分区键和（可选的）聚类键查询单条数据。
+
+#### `model.update(partitionKey: PK, data: Partial<T>, clusteringKey?: CK): Promise<void>`
+
+更新一条数据。
+
+#### `model.delete(partitionKey: PK, clusteringKey?: CK): Promise<void>`
+
+删除一条数据。
 
-#### 方法
-
-- `create(data: User): Promise<void>`
-  - 创建新记录
-  - 示例：
-    ```typescript
-    await userModel.create({
-      id: uuid(),           // 必须提供分区键
-      name: "张三",         // 必须提供聚类键
-      age: 25,             // 可选
-      email: "zhangsan@example.com"  // 必填
-    });
-    ```
-
-- `findOne(partitionKey: PartitionKey, clusteringKey?: Partial<ClusteringKey>): Promise<User | null>`
-  - 查询单条记录
-  - 示例：
-    ```typescript
-    // 只使用分区键查询
-    const user = await userModel.findOne({ id: "some-uuid" });
-    
-    // 使用分区键和聚类键查询
-    const user = await userModel.findOne(
-      { id: "some-uuid" },
-      { name: "张三" }
-    );
-    ```
-
-- `findAll(partitionKey: PartitionKey, clusteringKey?: Partial<ClusteringKey>): Promise<User[]>`
-  - 查询多条记录
-  - 参数同 `findOne`
-
-- `update(partitionKey: PartitionKey, data: Partial<UpdatableFields>): Promise<void>`
-  - 更新记录
-  - 示例：
-    ```typescript
-    await userModel.update(
-      { id: "some-uuid" },  // 必须提供分区键
-      { 
-        age: 26,            // 可以更新可选字段
-        email: "new@example.com"  // 可以更新普通字段
-      }
-    );
-    ```
-
-- `delete(partitionKey: PartitionKey, clusteringKey?: Partial<ClusteringKey>): Promise<void>`
-  - 删除记录
-  - 参数同 `findOne`
-
-### Field
-
-`Field` 类提供了创建字段配置的方法。
-
-#### 静态方法
-
-- `uuid(): FieldBuilder<"uuid">`
-- `text(): FieldBuilder<"text">`
-- `int(): FieldBuilder<"int">`
-- `bigint(): FieldBuilder<"bigint">`
-- `float(): FieldBuilder<"float">`
-- `double(): FieldBuilder<"double">`
-- `boolean(): FieldBuilder<"boolean">`
-- `timestamp(): FieldBuilder<"timestamp">`
-
-#### 实例方法
-
-- `partitionKey(): this`
-  - 将字段设置为分区键
-  - 分区键字段是必填的，不能为 null
-  - 示例：
-    ```typescript
-    Field.uuid().partitionKey()  // 将 UUID 字段设置为分区键
-    ```
-
-- `clusteringKey(order?: "ASC" | "DESC"): this`
-  - 将字段设置为聚类键
-  - 聚类键字段是否必填取决于是否设置了 `optional()`
-  - `order` 可选，指定排序方向
-  - 示例：
-    ```typescript
-    Field.text().clusteringKey()          // 默认升序，必填
-    Field.text().clusteringKey("DESC")    // 降序，必填
-    Field.text().clusteringKey().optional()  // 可选聚类键
-    ```
-
-- `optional(): this`
-  - 将字段设置为可选
-  - 可以用于任何类型的字段，包括聚类键
-  - 示例：
-    ```typescript
-    Field.int().optional()  // 将整数字段设置为可选
-    ```
-
-- `static(): this`
-  - 将字段设置为静态列
-  - 静态列在分区级别存储，而不是在每一行重复存储
-  - 适用于在分区内所有行共享相同值的字段
-  - 示例：
-    ```typescript
-    Field.text().static()  // 将文本字段设置为静态列
-    ```
-
-## 注意事项
-
-1. 所有模型必须在调用 `syncAllSchemas` 之前创建
-2. 创建记录时必须提供所有分区键字段
-3. 聚类键字段是否必填取决于是否设置了 `optional()`
-4. 更新记录时可以更新非分区键字段（包括聚类键和普通字段）
-5. 删除记录时必须提供所有分区键字段
-
-## 许可证
-
-MIT 
+---
+贡献者：imean
+License: MIT