榫ORM

一个PostgreSQL ORM设计的编码代理。为Node.js和TypeScript构建。

Tenon以编码代理可以读、写和检查的形式保持数据库工作：显式SQL，普通 TypeScript函数和SQL迁移。查询带有它们的结果类型和执行选项 这样，代理和审查其工作的人就可以在一个地方看到操作的效果。

npm install @kequtech/tenon-orm

要求Node.js 24+, PostgreSQL 16+， ESM。TypeScript应用需要TypeScript 6+和Node.js 打字。PostgreSQL驱动程序， pgclear，包括在内。

SQL查询

这个例子假设 public.users 带整数的表 id 和文本 email 列和a main 导出到 共享配置：

import { createTenon, sql } from '@kequtech/tenon-orm';
import { main } from './tenon.config.ts';

const db = createTenon(main);

try {
  const email = '[email protected]';
  const user = await db.query(
    sql<{ id: number; email: string }>`
      SELECT id, email FROM public.users WHERE email = ${email}
    `,
    { returns: 'oneOrNone' },
  );
  // user: { id: number; email: string } | undefined
} finally {
  await db.close();
}

${email} 变成了 $1 在SQL中，分别传递值。 sql<Row> 描述了一个 返回的行。 returns 选择Tenon如何归还这些排；

行数不匹配会引发。模式没有添加 LIMIT 或者更改SQL。在服务器中，重用一个 数据库实例，并在关机期间关闭它。通过应用程序提供环境变量； 榫不加载 .env 文件。

为编码代理设计

Tenon的API为编码代理提供了具体的代码和明确的契约：

• 可读的SQL。 所选列、连接、筛选器和冲突处理在查询中可见。 代理可以直接检查操作并使用PostgreSQL现有的词汇表。
• 普通的打印稿。 可重用查询是函数。代理可以跟随导入，更改a 函数，并将相同的查询代码传递给数据库或事务客户端。
• 显式写入限制。 查询可以只需要一个受影响的行，也可以设置一个最大值。榫 如果违反了该界限，则回滚操作。
• 可操作的检查。 生成的表类型描述存储契约； tenon check 报告 可恢复的SQL和声明的类型之间的矛盾。新鲜度检查捕获不新鲜的生成 声明和数据库测试验证结果和效果。

指南和变更日志随包一起发布，为已安装的程序提供代理文档 的版本。对于现有项目中的工作，从 代理指南.

Tenon是如何组合在一起的

• SQL定义操作。 直接使用PostgreSQL的join， aggregate， constraints和upserts。 对普通函数重用查询；当SQL的某些部分需要变化时，使用片段。
• TypeScript描述这些值。 声明查询投影。 sql<Row>． 选择生成 表的读/插入/更新类型 tenon generate． 捕获一个版本控制 模式指纹 与 tenon schema 对于应用程序拥有的守卫。
• 事务定义一起提交的内容。 使用 db.transaction(async (tx) => { ... }) 和运行 每个参与查询 tx.
• 写保护检查受影响的行。 { affectedRows: { exact: 1 } } 回滚写操作，除非 只有一行受到了影响。 { max: 1 } 允许0或1。
• 迁移会改变模式。 Tenon的可选运行程序应用编号的SQL文件。你可以继续 现有的模式和迁移运行程序。

对于对象输入， sql.insertValues(input) 和 sql.assignments(patch) 构建列/值 声明的部分内容。表、条件、表达式和冲突行为保留在SQL中。 没有模型实例或隐式关系加载。

查询类型是声明。Tenon不验证返回的数据 Row 在执行期间。 可选 tenon check 命令将可恢复的源查询与TypeScript类型和 PostgreSQL的元数据。保持数据库测试的实际结果和写入效果。

一些PostgreSQL值需要注意：bigint列和 count(*) 读取精确字符串，数字和 时间值也默认为字符串，JSON/数组输入使用显式编码助手。命令 rowCount 是一个数字或null。看到 值的映射 之前 选择应用程序类型。

与CLI共享配置

运行 tenon init 创建 tenon.config.ts． 将连接设置和编解码器放在其 main 出口, 然后重用该对象 createTenon(main)． 初始化保持惰性，因此构建只导入 数据库实例不需要凭据。

CLI对迁移使用相同的配置， tenon generate、新鲜度检查； tenon check, tenon describe query.sql． 对于多个数据库，添加命名导出并选择一个带有 --database. 看到 共享配置 以获得完整的设置。

文档

从……开始 开始 获取完整的表到查询示例。然后选择 任务指南：

README、指南和 更新日志 随NPM包一起发布。阅读文档 用于升级时安装的版本。图书馆维护费用包括在 CONTRIBUTING.md.

ISC许可． 维护的 Kequtech.