#数据库 (MonSQLize)

// src/config/default.ts
import type { VextUserConfig } from "vextjs";

export default {
  host: "127.0.0.1",
  port: 3000,
  adapter: "native",
  frontend: { enabled: false },
  database: {
    databaseName: "vext_docs_database",
    config: { uri: "mongodb://127.0.0.1:27017/vext_docs_database" },
    // 启动插件显式等待索引完成，再对外接收请求。
    monsqlizeOptions: { autoIndex: false },
  },
} satisfies VextUserConfig;

// src/models/user.ts
import type { VextModelDefinition } from "vextjs";

export type UserRole = "admin" | "editor" | "viewer";

export interface UserDocument {
  _id: string;
  name: string;
  email: string;
  role: UserRole;
  createdAt: Date;
  updatedAt: Date;
}

export default {
  collection: "users",
  schema: {
    _id: "uuid!",
    name: "string:1-50!",
    email: "email!",
    role: "admin|editor|viewer",
  },
  indexes: [{ key: { email: 1 }, unique: true }],
  options: { timestamps: true },
} satisfies VextModelDefinition;

// src/plugins/database-indexes.ts
import { definePlugin, type VextDatabase } from "vextjs";

export default definePlugin({
  name: "database-indexes",
  async setup(app) {
    const db = app.db as VextDatabase | undefined;
    if (!db) throw new Error("Database is not configured");
    await db.model("users").ensureIndexes({ throwOnError: true });
  },
});

// src/services/user.ts
import { randomUUID } from "node:crypto";
import type { VextApp } from "vextjs";
import type { UserDocument, UserRole } from "../models/user.js";

type UserInput = { name: string; email: string; role?: UserRole };

export default class UserService {
  constructor(private app: VextApp) {}

  private get users() {
    if (!this.app.db) throw new Error("Database is not configured");
    return this.app.db.model<UserDocument>("users");
  }

  private rethrowWriteError(error: unknown): never {
    const code =
      typeof error === "object" && error !== null && "code" in error
        ? error.code
        : undefined;
    if (code === 11000 || code === "DUPLICATE_KEY") {
      this.app.throw(409, "用户 ID 或邮箱已存在");
    }
    throw error;
  }

  async findById(id: string) {
    const user = await this.users.findOne({ _id: id });
    if (!user) this.app.throw(404, "用户不存在");
    return user;
  }

  async findAll({
    page = 1,
    limit = 20,
    role,
  }: {
    page?: number;
    limit?: number;
    role?: UserRole;
  } = {}) {
    const filter = role ? { role } : {};
    const { data, total } = await this.users.findAndCount(filter, {
      skip: (page - 1) * limit,
      limit,
      sort: { _id: 1 },
    });
    return {
      items: data,
      total,
      page,
      limit,
      totalPages: Math.ceil(total / limit),
    };
  }

  async create(input: UserInput) {
    const doc = {
      _id: randomUUID(),
      name: input.name,
      email: input.email,
      role: input.role ?? "viewer",
    };
    try {
      await this.users.insertOne(doc);
    } catch (error) {
      this.rethrowWriteError(error);
    }
    return this.findById(doc._id);
  }

  async update(id: string, input: Partial<UserInput>) {
    const changes: Partial<UserInput> = {};
    if (input.name !== undefined) changes.name = input.name;
    if (input.email !== undefined) changes.email = input.email;
    if (input.role !== undefined) changes.role = input.role;
    if (Object.keys(changes).length === 0)
      this.app.throw(400, "没有可更新字段");
    try {
      const result = await this.users.updateOne({ _id: id }, { $set: changes });
      if (result.matchedCount === 0) this.app.throw(404, "用户不存在");
    } catch (error) {
      this.rethrowWriteError(error);
    }
    return this.findById(id);
  }

  async delete(id: string) {
    const result = await this.users.deleteOne({ _id: id });
    if (result.deletedCount === 0) this.app.throw(404, "用户不存在");
  }
}

// src/routes/users.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get(
    "/",
    {
      validate: {
        query: {
          page: "integer:1-1000",
          limit: "integer:1-100",
          role: "admin|editor|viewer",
        },
      },
    },
    async (req, res) => {
      res.json(await app.services.user.findAll(req.valid("query")));
    },
  );
  app.get(
    "/:id",
    { validate: { param: { id: "uuid!" } } },
    async (req, res) => {
      res.json(await app.services.user.findById(req.valid("param").id));
    },
  );
  app.post(
    "/",
    {
      validate: {
        body: {
          name: "string:1-50!",
          email: "email!",
          role: "admin|editor|viewer",
        },
      },
    },
    async (req, res) => {
      const user = await app.services.user.create(req.valid("body"));
      res.setHeader("Location", `/users/${user._id}`);
      res.json(user, 201);
    },
  );
  app.patch(
    "/:id",
    {
      validate: {
        param: { id: "uuid!" },
        body: {
          name: "string:1-50",
          email: "email",
          role: "admin|editor|viewer",
        },
      },
    },
    async (req, res) => {
      res.json(
        await app.services.user.update(
          req.valid("param").id,
          req.valid("body"),
        ),
      );
    },
  );
  app.delete(
    "/:id",
    { validate: { param: { id: "uuid!" } } },
    async (req, res) => {
      await app.services.user.delete(req.valid("param").id);
      res.json(null, 204);
    },
  );
});

// src/config/default.ts
export default {
  database: {
    // 连接配置
    config: {
      uri: "mongodb://localhost:27017/myapp",
    },
  },
};

export default {
  database: {
    databaseName: "myapp",
    config: {
      uri: "mongodb://admin:secret@mongo1:27017,mongo2:27017,mongo3:27017/myapp?replicaSet=rs0&authSource=admin",
    },
  },
};

export default {
  database: {
    databaseName: "myapp",
    config: {
      uri: "mongodb+srv://admin:secret@cluster0.abc123.mongodb.net/myapp",
    },
  },
};

import type { VextUserConfig } from "vextjs";

export default {
  database: {
    config: { uri: "mongodb://localhost:27017/myapp" },
    monsqlizeOptions: {
      findMaxLimit: 2_000,
      findMaxSkip: 20_000,
      transaction: { enableRetry: true, maxRetries: 2 },
      autoIndex: { enabled: true, emitEvents: true },
      cacheAutoInvalidate: true,
      writePathPolicy: { default: "model-only" },
    },
  },
} satisfies VextUserConfig;

export default {
  database: {
    config: { uri: "mongodb://localhost:27017/myapp" },

    cache: {
      // L1 内存缓存（默认开启）
      memory: {
        enabled: true,
        maxSize: 1000, // 最大缓存条数
        ttl: 300_000, // 默认 TTL（毫秒，5 分钟）
      },

      // L2 Redis 缓存（可选）
      redis: {
        enabled: true,
        uri: "redis://localhost:6379",
        prefix: "myapp:cache:",
        ttl: 600_000, // 毫秒，10 分钟
      },
    },
  },
};

// src/config/default.ts — 完整 base
import type { VextUserConfig } from "vextjs";

const config: VextUserConfig = {
  database: {
    config: { uri: "mongodb://localhost:27017/myapp" },
    findLimit: 10,
    models: { dir: "models" },
    slowQueryMs: 500,
  },
};

export default config;

// src/config/development.ts — 合法的局部 database patch
import type { VextConfigOverride } from "vextjs";

const config: VextConfigOverride = {
  database: {
    findLimit: 25,
    models: { validation: "strict" },
  },
};

export default config;

// src/config/production.ts — patch 环境专属的连接 URI
import type { VextConfigOverride } from "vextjs";

const config: VextConfigOverride = {
  database: {
    config: {
      uri: "mongodb://prod-db:27017/myapp",
    },
    slowQueryMs: 200, // 生产环境慢查询阈值更低
  },
};

export default config;

// src/config/database-check.ts — 验证环境使用临时数据库
import type { VextConfigOverride } from "vextjs";

const config: VextConfigOverride = {
  database: {
    databaseName: "vext_docs_database_test",
    useMemoryServer: true, // 使用 mongodb-memory-server-core
  },
};

export default config;

// src/config/development.ts — 前层不存在 database
import type { MonSQLizeDatabaseConfig, VextConfigOverride } from "vextjs";

const database = {
  config: { uri: "mongodb://localhost:27017/myapp" },
  findLimit: 25,
  models: { dir: "models", validation: "strict" },
} satisfies MonSQLizeDatabaseConfig;

const config = { database } satisfies VextConfigOverride;

export default config;

// 获取 users 集合
const usersCol = app.db.collection("users");

// 查询
const user = await usersCol.findOne({ email: "test@example.com" });
const users = await usersCol.find({ role: "admin" });

// 插入
const result = await usersCol.insertOne({
  name: "张三",
  email: "zhangsan@example.com",
});

// 更新
await usersCol.updateOne({ _id: userId }, { $set: { name: "李四" } });

// 删除
await usersCol.deleteOne({ _id: userId });

// 聚合
const stats = await usersCol.aggregate([
  { $group: { _id: "$role", count: { $sum: 1 } } },
]);

// 计数
const total = await usersCol.countDocuments({ role: "admin" });

// src/models/user.ts 导出 { collection: "users", ... } 时，根目录注册键
// 就是精确的 "users"，不会自动单数化或转为 PascalCase。
const User = app.db.model("users");

// Model 提供更高级的 API（分页、缓存、校验等）
const result = await User.findPage({
  query: { role: "admin" },
  page: 1,
  limit: 20,
  sort: { createdAt: -1, _id: -1 },
  totals: { mode: "sync" },
});
const { items, pageInfo, totals } = result;

// 访问 billing 数据库的 invoices 集合
const billing = app.db.use("billing");
const invoice = await billing.collection("invoices").findOne({ _id: id });

// 也可直接链式调用
const anotherInvoice = await app.db
  .use("billing")
  .collection("invoices")
  .findOne({ _id: id });

// use() 只切换数据库 scope，不会改写注册键。
// models/billing/invoice.ts 这类 depth-1 文件注册为 BillingInvoice。
const Invoice = app.db.use("billing").model("BillingInvoice");

// database 对象内的配置片段；先准备这两个 MongoDB 实例。
pools: [
  { name: "cn", config: { uri: "mongodb://127.0.0.1:27018/myapp" } },
  { name: "billing", config: { uri: "mongodb://127.0.0.1:27019/billing" } },
],
poolStrategy: "auto",

// 访问 cn 池的 orders 集合
const order = await app.db.pool("cn").collection("orders").findOne({ _id: id });

// 连接池中的 Model 查询仍使用精确注册键。
const Invoice = app.db.pool("billing").model("BillingInvoice");
// 只有 Model 显式声明 key: "Invoice" 时，短键才有效。
const InvoiceAlias = app.db.pool("billing").model("Invoice");

// cn 池 + billing 库（collection）
const invoice = await app.db
  .pool("cn")
  .use("billing")
  .collection("invoices")
  .findOne({});

// cn 池 + billing 库 + 精确的 Model 注册键
const InvoiceCn = app.db.pool("cn").use("billing").model("BillingInvoice");

// 深度-2 模型目录（models/cn/billing/order.ts）：注册键 = CnBillingOrder
// scope accessor 不会自动添加前缀，也不会回落到另一个键。
const Order1 = app.db.model("CnBillingOrder"); // 完整 key
const Order2 = app.db.pool("cn").use("billing").model("CnBillingOrder");
// 两者用不同的显式 scope 解析同一个已注册 Model。

const session = app.db.client.startSession();

try {
  await session.withTransaction(async () => {
    await app.db
      .collection("accounts")
      .updateOne({ _id: fromId }, { $inc: { balance: -amount } }, { session });
    await app.db
      .collection("accounts")
      .updateOne({ _id: toId }, { $inc: { balance: amount } }, { session });
  });
} finally {
  await session.endSession();
}

const monsqlize = app.db;
if (!monsqlize) throw new Error("Database is not configured");

// 实例级完整能力都保留在 app.db。
await monsqlize.withTransaction(async (transaction) => {
  // ...
});
monsqlize.on("slow-query", (info) => {
  app.logger.warn({ ...info }, "Slow query detected");
});

// app.db 返回上游 Collection / Model 实例。
const hits = await monsqlize.collection("products").vectorSearch({
  index: "product_embedding",
  path: "embedding",
  queryVector: embedding,
  numCandidates: 100,
  limit: 10,
});

const Product = monsqlize.model("Product");
const usage = await Product.checkRelationUsage({ _id: productId });
await Product.deleteOneWithRelations({ _id: productId });

import { defineModel, Model } from "monsqlize";
import type { VextApp } from "vextjs";

const UserDescriptor = defineModel("manual_users", {
  schema: {
    email: "email!",
    age: "number?",
  },
});

Model.define(UserDescriptor);

export async function findUser(app: VextApp, email: string) {
  const User = app.db?.model(UserDescriptor);
  return User?.findOne({ email }); // email: string；age?: number
}

// src/models/user.ts
export default {
  collection: "users",

  // schema-dsl 简洁语法
  schema: {
    name: "string:1-50!", // 必填字符串，1~50 字符
    email: "email!", // 必填，邮箱格式
    role: "admin|editor|viewer", // 枚举值
    avatar: "string", // 可选字符串
  },

  // 索引
  indexes: [
    { key: { email: 1 }, unique: true },
    { key: { role: 1, createdAt: -1 } },
  ],

  // 使用 options.timestamps 自动管理 createdAt/updatedAt
  options: {
    timestamps: true,
  },
};

// src/models/member.ts
import { randomUUID } from "node:crypto";
import type { VextModelDefinition } from "vextjs";

export default {
  collection: "members",
  schema: {
    "_id!": { type: "string", format: "uuid" },
    "name!": { type: "string", minLength: 1, maxLength: 50 },
    "email!": { type: "string", format: "email" },
    role: { type: "string", enum: ["admin", "editor", "viewer"] },
    tags: { type: "array", items: { type: "string" } },
    slug: { type: "string" },
  },
  defaults: { _id: () => randomUUID(), role: "viewer" },
  indexes: [{ key: { email: 1 }, unique: true }],
  hooks: {
    beforeInsert(context) {
      const doc = context.data;
      if (typeof doc !== "object" || doc === null || !("name" in doc)) return;
      if (typeof doc.name === "string") {
        Object.assign(doc, {
          slug: doc.name.toLowerCase().replace(/\s+/g, "-"),
        });
      }
    },
  },
  options: { timestamps: true },
} satisfies VextModelDefinition;

// 简单模式：自动添加 createdAt + updatedAt
options: { timestamps: true }

// 自定义字段名
options: { timestamps: { createdAt: 'created_time', updatedAt: 'updated_time' } }

// 只启用 createdAt（日志类集合）
options: { timestamps: { createdAt: true, updatedAt: false } }

// src/models/billing-invoice.ts
export default {
  collection: "BillingInvoice", // MongoDB 实际集合名
  key: "Invoice", // 短名别名（可选）

  schema: {
    amount: "number!",
    currency: "CNY|USD|EUR",
    status: "draft|pending|paid",
  },

  // 绑定到指定连接池 + 数据库（让 app.db.model() 路由正确）
  connection: {
    pool: "billing",
    database: "billing",
  },
};

app.db.model("BillingInvoice"); // 按集合名（全路径）
app.db.model("Invoice"); // 按别名（短名）

// scope 切换不会改写任一精确键
app.db.pool("billing").model("BillingInvoice");
app.db.pool("billing").model("Invoice");

// src/models/billing/invoice.ts
import type { VextModelDefinition } from "vextjs";

// 无需手动写 connection — 由目录路径自动推断
export default {
  schema: {
    amount: "number!",
    currency: "CNY|USD|EUR",
    status: "draft|pending|paid",
  },
} satisfies VextModelDefinition;

// 效果等同于显式配置：
// export default {
//   name: "invoice",
//   connection: { database: "billing" },
//   schema: { ... },
// };

export default {
  database: {
    config: { uri: "mongodb://localhost:27017/myapp" },

    models: {
      // Model 定义文件目录（相对于 src/，默认 'models'）
      dir: "models",

      // 是否自动注册（默认 true）
      autoRegister: true,

      // 发现策略：strict（默认）或 lenient
      validation: "strict",

      // 外部共享 Model 包（微服务场景）
      sharedPackage: "@myproject/shared-models",
    },
  },
};

// 加载顺序：先 shared 包 → 再本地 models/
// 本地 Model 可以覆盖 shared 包中同名的 Model
models: {
  sharedPackage: '@myproject/shared-models',
  dir: 'models',  // 本地 Model（可覆盖 shared）
}

// src/config/database-check.ts
import type { VextConfigOverride } from "vextjs";

const config: VextConfigOverride = {
  database: {
    databaseName: "vext_docs_database_test",
    useMemoryServer: true,
  },
};

export default config;

export default {
  database: {
    config: { uri: "mongodb://localhost:27017/myapp" },
    slowQueryMs: 200, // 超过 200ms 的查询会产生警告

    // 可选：持久化慢查询记录到专用集合
    slowQueryLog: {
      enabled: true,
      collection: "_slow_queries",
    },
  },
};

const logsDb = app.db.use("logs");
const logsCollection = app.db.db("logs").collection("events");
// 需要同时指定池和库时：
const regionalLogs = app.db.pool("cn").use("logs");