imean-cassandra-orm 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# Cassandra ORM
+
+一个简单易用的 Cassandra ORM 库，提供类型安全的 API。
+
+## 安装
+
+```bash
+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"),
+});
+
+// 创建我们的客户端
+const client = new Client(cassandraClient);
+
+// 设置 keyspace
+await client.useKeyspace("my_keyspace", {
+  class: "SimpleStrategy",
+  replication_factor: 1,
+});
+
+// 创建用户模型
+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>;
+
+// 创建文章模型
+const postModel = client.createModel(
+  {
+    id: Field.uuid().partitionKey(),      // 分区键，必填
+    title: Field.text(),                  // 普通字段，必填
+    content: Field.text(),                // 普通字段，必填
+    created_at: Field.timestamp(),        // 普通字段，必填
+  },
+  "posts"
+);
+
+// 同步所有表结构
+await client.syncAllSchemas();
+
+// 创建用户
+const user = await userModel.create({
+  id: uuid(),           // 必须提供分区键
+  name: "张三",         // 必须提供聚类键
+  age: 25,             // 可选
+  email: "zhangsan@example.com"  // 必填
+});
+
+// 创建文章
+await postModel.create({
+  id: uuid(),
+  title: "测试文章",
+  content: "内容",
+  created_at: new Date(),
+});
+
+// 查询用户
+const foundUser = await userModel.findOne({ id: user.id });
+console.log(foundUser);
+
+// 关闭连接
+await client.close();
+```
+
+## API 参考
+
+### 类型推导工具
+
+ORM 库提供了一系列类型推导工具，可以帮助开发者在上层 API 中实现类型安全。
+
+#### Infer<M>
+
+从 Model 实例中推断出原始字段类型。
+
+```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 }
+```
+
+#### InferPartitionKey<M>
+
+推导分区键字段类型。
+
+```typescript
+type UserPartitionKey = InferPartitionKey<typeof userModel>;
+// 推导结果: { id: string }
+```
+
+#### InferClusteringKey<M>
+
+推导聚类键字段类型。
+
+```typescript
+type UserClusteringKey = InferClusteringKey<typeof userModel>;
+// 推导结果: { name: string }
+```
+
+#### InferNonPartitionFields<S>
+
+推导非分区键字段类型。
+
+```typescript
+type UserFields = {
+  id: { type: "uuid"; flags: { partitionKey: true } };
+  name: { type: "text" };
+  age: { type: "int" };
+};
+
+type NonPartitionFields = InferNonPartitionFields<UserFields>;
+// 推导结果: { name: string; age: number }
+```
+
+这些类型工具可以用于：
+
+1. 在 API 层定义类型安全的接口
+2. 在服务层进行类型检查
+3. 在数据访问层确保数据一致性
+4. 在业务逻辑层进行类型推导
+
+### Client
+
+`Client` 类是对原始 Cassandra 客户端的封装，提供了更高级的 API。
+
+#### 构造函数
+
+```typescript
+constructor(cassandraClient: CassandraClient)
+```
+
+#### 方法
+
+- `useKeyspace(keyspace: string, options: KeyspaceOptions): Promise<void>`
+  - 设置当前使用的 keyspace，如果不存在则创建
+  - `options`:
+    - `class`: 复制策略，可以是 `"SimpleStrategy"` 或 `"NetworkTopologyStrategy"`
+    - `replication_factor`: 复制因子（仅用于 `SimpleStrategy`）
+    - `datacenters`: 数据中心配置（仅用于 `NetworkTopologyStrategy`）
+
+- `createModel<S extends Record<string, FieldConfig<keyof TypeMap>>>(schema: S, tableName: string): Model<S>`
+  - 创建并注册一个新的模型
+  - 返回的模型实例可以直接使用，不需要额外获取
+
+- `syncAllSchemas(): Promise<void>`
+  - 同步所有已注册模型的结构到数据库
+
+- `close(): Promise<void>`
+  - 关闭数据库连接
+
+### Model
+
+`Model` 类提供了对数据库表的操作接口。
+
+#### 类型推导示例
+
+```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;
+};
+
+// 聚类键类型（用于查询和删除）
+type ClusteringKey = {
+  name: string;
+};
+
+// 可更新字段类型（用于更新操作）
+type UpdatableFields = {
+  age?: number;         // 可选字段
+  email: string;        // 普通字段
+};
+```
+
+#### 方法
+
+- `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()  // 将整数字段设置为可选
+    ```
+
+## 注意事项
+
+1. 所有模型必须在调用 `syncAllSchemas` 之前创建
+2. 创建记录时必须提供所有分区键字段
+3. 聚类键字段是否必填取决于是否设置了 `optional()`
+4. 更新记录时可以更新非分区键字段（包括聚类键和普通字段）
+5. 删除记录时必须提供所有分区键字段
+
+## 许可证
+
+MIT 

package/dist/mod.cjs

@@ -0,0 +1,308 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cassandraDriver = require('cassandra-driver');
+
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Client: () => Client2,
+  Field: () => Field,
+  FieldBuilder: () => FieldBuilder,
+  Model: () => Model,
+  uuid: () => uuid
+});
+var Model = class {
+  constructor(client, schema, tableName) {
+    this.client = client;
+    this.schema = schema;
+    this.tableName = tableName;
+    this.partitionKeys = Object.entries(schema).filter(([_, config]) => config.flags.partitionKey).map(([key]) => key);
+    this.clusteringKeys = Object.entries(schema).filter(([_, config]) => config.flags.clusteringKey).map(([key]) => key);
+  }
+  tableName;
+  partitionKeys;
+  clusteringKeys;
+  // 获取表结构 CQL
+  getTableSchema() {
+    const columns = Object.entries(this.schema).map(([name, config]) => {
+      const type = config.type;
+      return `${name} ${type}`;
+    }).join(",\n  ");
+    const primaryKey = this.clusteringKeys.length > 0 ? `((${this.partitionKeys.join(", ")}), ${this.clusteringKeys.join(
+      ", "
+    )})` : `((${this.partitionKeys.join(", ")}))`;
+    const clusteringOrder = this.clusteringKeys.map((key) => {
+      const config = this.schema[key];
+      if (typeof config.flags.clusteringKey === "object") {
+        return `${key} ${config.flags.clusteringKey.order}`;
+      }
+      return `${key} ASC`;
+    }).join(", ");
+    return `CREATE TABLE IF NOT EXISTS ${this.tableName} (
+  ${columns},
+  PRIMARY KEY ${primaryKey}
+)${clusteringOrder ? ` WITH CLUSTERING ORDER BY (${clusteringOrder})` : ""};`;
+  }
+  // 同步表结构
+  async syncSchema() {
+    const checkTableQuery = `
+      SELECT table_name 
+      FROM system_schema.tables 
+      WHERE keyspace_name = ? AND table_name = ?`;
+    const result = await this.client.execute(
+      checkTableQuery,
+      [this.client.keyspace, this.tableName],
+      { prepare: true }
+    );
+    if (result.rows.length === 0) {
+      await this.client.execute(this.getTableSchema(), [], { prepare: true });
+    } else {
+      const getColumnsQuery = `
+        SELECT column_name, type 
+        FROM system_schema.columns 
+        WHERE keyspace_name = ? AND table_name = ?`;
+      const columnsResult = await this.client.execute(
+        getColumnsQuery,
+        [this.client.keyspace, this.tableName],
+        { prepare: true }
+      );
+      const existingColumns = new Map(
+        columnsResult.rows.map((row) => [row.column_name, row.type])
+      );
+      const newColumns = Object.entries(this.schema).filter(([name]) => !existingColumns.has(name)).map(([name, config]) => {
+        const type = config.type;
+        return `ALTER TABLE ${this.tableName} ADD ${name} ${type}`;
+      });
+      for (const query of newColumns) {
+        await this.client.execute(query, [], { prepare: true });
+      }
+    }
+  }
+  // 构建查询条件
+  buildWhereClause(partitionFields, clusteringFields) {
+    const conditions = [];
+    this.partitionKeys.forEach((key) => {
+      const value = partitionFields[key];
+      if (value !== void 0) {
+        conditions.push(`${key} = ?`);
+      }
+    });
+    if (clusteringFields) {
+      this.clusteringKeys.forEach((key) => {
+        const value = clusteringFields[key];
+        if (value !== void 0) {
+          conditions.push(`${key} = ?`);
+        }
+      });
+    }
+    return conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  }
+  // 构建查询参数
+  buildQueryParams(partitionFields, clusteringFields) {
+    const params = [];
+    this.partitionKeys.forEach((key) => {
+      const value = partitionFields[key];
+      if (value !== void 0) {
+        params.push(value);
+      }
+    });
+    if (clusteringFields) {
+      this.clusteringKeys.forEach((key) => {
+        const value = clusteringFields[key];
+        if (value !== void 0) {
+          params.push(value);
+        }
+      });
+    }
+    return params;
+  }
+  // 将查询结果转换为我们的类型
+  convertResultToType(result) {
+    const converted = {};
+    Object.keys(this.schema).forEach((key) => {
+      converted[key] = result[key];
+    });
+    return converted;
+  }
+  // 查询方法
+  async findAll(partitionFields, clusteringFields) {
+    const whereClause = this.buildWhereClause(
+      partitionFields,
+      clusteringFields
+    );
+    const params = this.buildQueryParams(partitionFields, clusteringFields);
+    const query = `SELECT * FROM ${this.tableName} ${whereClause}`;
+    const result = await this.client.execute(query, params, { prepare: true });
+    return result.rows.map((row) => this.convertResultToType(row));
+  }
+  async findOne(partitionFields, clusteringFields) {
+    const whereClause = this.buildWhereClause(
+      partitionFields,
+      clusteringFields
+    );
+    const params = this.buildQueryParams(partitionFields, clusteringFields);
+    const query = `SELECT * FROM ${this.tableName} ${whereClause} LIMIT 1`;
+    const result = await this.client.execute(query, params, { prepare: true });
+    return result.rows[0] ? this.convertResultToType(result.rows[0]) : null;
+  }
+  // 添加记录方法
+  async create(data) {
+    const columns = Object.keys(data).join(", ");
+    const placeholders = Object.keys(data).map(() => "?").join(", ");
+    const params = Object.values(data);
+    const query = `INSERT INTO ${this.tableName} (${columns}) VALUES (${placeholders})`;
+    await this.client.execute(query, params, { prepare: true });
+  }
+  // 更新记录方法
+  async update(partitionFields, data) {
+    const setClause = Object.keys(data).map((key) => `${key} = ?`).join(", ");
+    const whereClause = this.buildWhereClause(partitionFields);
+    const params = [
+      ...Object.values(data),
+      ...this.buildQueryParams(partitionFields)
+    ];
+    const query = `UPDATE ${this.tableName} SET ${setClause} ${whereClause}`;
+    await this.client.execute(query, params, { prepare: true });
+  }
+  // 删除记录方法
+  async delete(partitionFields, clusteringFields) {
+    const whereClause = this.buildWhereClause(
+      partitionFields,
+      clusteringFields
+    );
+    const params = this.buildQueryParams(partitionFields, clusteringFields);
+    const query = `DELETE FROM ${this.tableName} ${whereClause}`;
+    await this.client.execute(query, params, { prepare: true });
+  }
+};
+var uuid = () => cassandraDriver.types.Uuid.random().toString();
+
+// src/client.ts
+var Client2 = class {
+  constructor(cassandraClient) {
+    this.cassandraClient = cassandraClient;
+  }
+  models = /* @__PURE__ */ new Map();
+  // 使用 keyspace
+  async useKeyspace(keyspace, options) {
+    const checkKeyspaceQuery = `
+      SELECT keyspace_name 
+      FROM system_schema.keyspaces 
+      WHERE keyspace_name = ?`;
+    const result = await this.cassandraClient.execute(
+      checkKeyspaceQuery,
+      [keyspace],
+      { prepare: true }
+    );
+    if (result.rows.length === 0) {
+      let createKeyspaceQuery = `CREATE KEYSPACE IF NOT EXISTS ${keyspace} WITH REPLICATION = { 'class' : '${options.class}'`;
+      if (options.class === "SimpleStrategy") {
+        createKeyspaceQuery += `, 'replication_factor' : ${options.replication_factor || 1}`;
+      } else if (options.class === "NetworkTopologyStrategy" && options.datacenters) {
+        const datacenterConfigs = Object.entries(options.datacenters).map(([dc, rf]) => `'${dc}' : ${rf}`).join(", ");
+        createKeyspaceQuery += `, ${datacenterConfigs}`;
+      }
+      createKeyspaceQuery += " }";
+      await this.cassandraClient.execute(createKeyspaceQuery, [], {
+        prepare: true
+      });
+    }
+    await this.cassandraClient.execute(`USE ${keyspace}`, [], { prepare: true });
+  }
+  // 创建模型
+  createModel(schema, tableName) {
+    const model = new Model(this.cassandraClient, schema, tableName);
+    this.models.set(tableName, model);
+    return model;
+  }
+  // 同步所有表结构
+  async syncAllSchemas() {
+    for (const model of this.models.values()) {
+      await model.syncSchema();
+    }
+  }
+  // 获取原始 Cassandra 客户端
+  getRawClient() {
+    return this.cassandraClient;
+  }
+  // 关闭连接
+  async close() {
+    await this.cassandraClient.shutdown();
+  }
+};
+
+// src/field.ts
+var FieldBuilder = class _FieldBuilder {
+  constructor(type, flags = {
+    partitionKey: false,
+    clusteringKey: false,
+    optional: false
+  }) {
+    this.type = type;
+    this.flags = flags;
+  }
+  partitionKey() {
+    const newFlags = {
+      ...this.flags,
+      partitionKey: true
+    };
+    return new _FieldBuilder(this.type, newFlags);
+  }
+  clusteringKey(order) {
+    const newFlags = {
+      ...this.flags,
+      clusteringKey: order ? { order } : true
+    };
+    return new _FieldBuilder(this.type, newFlags);
+  }
+  optional() {
+    const newFlags = {
+      ...this.flags,
+      optional: true
+    };
+    return new _FieldBuilder(this.type, newFlags);
+  }
+};
+var createField = (type) => {
+  return new FieldBuilder(type);
+};
+var Field = {
+  // 文本类型
+  text: () => createField("text"),
+  uuid: () => createField("uuid"),
+  // 数值类型
+  int: () => createField("int"),
+  bigint: () => createField("bigint"),
+  varint: () => createField("varint"),
+  decimal: () => createField("decimal"),
+  float: () => createField("float"),
+  double: () => createField("double"),
+  // 布尔类型
+  boolean: () => createField("boolean"),
+  // 时间类型
+  timestamp: () => createField("timestamp"),
+  // 二进制类型
+  blob: () => createField("blob"),
+  // 集合类型
+  list: () => createField("list"),
+  set: () => createField("set"),
+  map: () => createField("map")
+};
+
+// mod.ts
+var mod_default = src_exports;
+
+exports.Client = Client2;
+exports.Field = Field;
+exports.FieldBuilder = FieldBuilder;
+exports.Model = Model;
+exports.default = mod_default;
+exports.uuid = uuid;