# 标准库常用签名

参数按位置传入，输出名属于合同。以下签名与随包 lib/ 的公开声明由 test/skill_examples.py 核对。

## 文本与数字

```signatures
text.trim(value: Text) (result: Text)
text.lower(value: Text) (result: Text)
text.upper(value: Text) (result: Text)
text.at(value: Text, index: Int) (result: Text?)
text.slice(value: Text, start: Int, end: Int) (result: Text?)
text.contains(value: Text, pattern: Text) (result: Bool)
text.startsWith(value: Text, prefix: Text) (result: Bool)
text.endsWith(value: Text, suffix: Text) (result: Bool)
text.split(value: Text, separator: Text) (result: List<Text>)
text.replace(value: Text, pattern: Text, replacement: Text) (result: Text)
text.join(values: List<Text>, separator: Text) (result: Text)
int.parse(value: Text) (result: Int?)
int.toText(value: Int) (result: Text)
decimal.parse(value: Text) (result: Decimal?)
decimal.round(value: Decimal, places: Int) (result: Decimal)
decimal.fromInt(value: Int) (result: Decimal)
decimal.toText(value: Decimal) (result: Text)
float.parse(value: Text) (result: Float?)
float.fromInt(value: Int) (result: Float)
uuid.parse(value: Text) (result: Uuid?)
uuid.toText(value: Uuid) (result: Text)
dever.id.fromText(text: Text) (id: Id)
dever.id.toText(id: Id) (text: Text)
```

数值和 Uuid 的 parse 失败返回 null。Id、Uuid、Model ID 是不同类型。Text 索引按 Unicode 码点，slice 含起点、不含终点。

## Bytes、时间与密码

```signatures
dever.bytes.fromText(text: Text) (bytes: Bytes)
dever.bytes.toText(bytes: Bytes) (text: Text)
dever.bytes.fromInts(values: List<Int>) (bytes: Bytes)
dever.bytes.length(bytes: Bytes) (length: Int)
dever.bytes.at(bytes: Bytes, index: Int) (value: Int?)
dever.bytes.slice(bytes: Bytes, start: Int, end: Int) (result: Bytes)
dever.bytes.concat(left: Bytes, right: Bytes) (bytes: Bytes)
dever.time.now() (output: DateTime)
dever.time.parseDatetime(text: Text) (output: DateTime) pure
dever.time.formatDatetime(value: DateTime) (output: Text) pure
dever.time.parseDate(text: Text) (output: Date) pure
dever.time.formatDate(value: Date) (output: Text) pure
dever.time.duration(millis: Int) (output: Duration) pure
dever.time.add(value: DateTime, duration: Duration) (output: DateTime) pure
dever.time.subtract(value: DateTime, duration: Duration) (output: DateTime) pure
dever.time.difference(later: DateTime, earlier: DateTime) (output: Duration) pure
dever.crypto.passwordHash(password: Secret) (value: Text)
dever.crypto.passwordVerify(password: Secret, hash: Text) (value: Bool)
dever.crypto.token(bytes: Int) (value: Secret)
dever.crypto.sha256(bytes: Bytes) (value: Bytes) pure
dever.crypto.hmacSha256(key: Secret, bytes: Bytes) (value: Bytes) pure
dever.crypto.constantTimeEq(left: Bytes, right: Bytes) (equal: Bool) pure
```

时间解析失败传播 DateTimeResult/DateResult，格式化失败传播 TextResult。非法 UTF-8 为 DecodeResult，字节范围错误为 BufferResult。密码与 token 分别传播 HashResult/VerifyResult/TokenResult；用 result 捕获。密码计算放事务外，在挂起调用链中使用 blocking。

## JSON 与 HTTP

```signatures
dever.json.fromText(source: Text) (value: Json)
dever.json.toText(value: Json) (source: Text)
dever.json.setProperty(value: Json, name: Text, child: Json) (result: Json)
dever.json.propertyValue(value: Json, name: Text) (result: Json?)
dever.json.asText(value: Json) (source: Text)
dever.json.asInteger(value: Json) (number: Int)
dever.json.parse(source: Text) (document: dever.json.value.Document)
dever.json.stringify(document: dever.json.value.Document) (text: Text)
dever.json.node(document: dever.json.value.Document, id: Int) (value: dever.json.value.Value?)
dever.json.property(document: dever.json.value.Document, id: Int, name: Text) (value: Int?)
dever.http.defaultLimits() (result: Limits)
dever.http.send(address: Text, port: Int, request: Request, limits: Limits) (response: Response)
```

Json 是不透明值，fromText/toText 保留原始 JSON；propertyValue 返回子 Json。普通 API/CMD 自动编解码。已有 Json 转具体类型用 `dever.json.decode(value)`，由局部类型声明、命名输出、字段或参数确定类型；直接复用 Serde 解码，失败传播 JsonResult.Failed。需要捕获时直接使用 `result(dever.json.decode(value))`，结果 Choice 的成功字段提供目标类型，error 分支包装 JsonResult。不要先转 Text、Document 再手工组装已知类型。未知结构才使用 Document 的 root/nodes 节点树。

HTTP 的 Limits/Request/Response 属于 dever.http。Request 有 method/target: Text、headers: List<Header>、body: Bytes；Header 有 name: Text、value: Bytes，Response 有 status: Int、headers、body。send 在 Adapter 使用，失败传播 ResponseResult.Failed。

日志由运行时和部署配置管理，当前标准库没有 dever.log 源码接口。

## 请求与权限

```signatures
dever.api.requestId() (value: Text)
dever.api.header(name: Text) (value: Text?)
dever.api.setHeader(name: Text, value: Text) ()
dever.auth.id() (value: Text)
dever.auth.session() (value: Text)
dever.auth.permissions() (values: List<Permission>)
dever.auth.currentPermissions() (values: List<Permission>)
dever.auth.roles() (values: List<Role>)
dever.auth.role(id: Text) (value: Role?)
dever.auth.userRoles(user_id: Int) (values: List<Role>)
dever.auth.isOwner(user_id: Int) (value: Bool)
dever.auth.hasProtectedRoles(user_id: Int) (value: Bool)
dever.auth.registerCapability(id: Uuid) (key: Text)
dever.auth.removeCapability(id: Uuid) ()
dever.auth.saveRole(id: Text, name: Text, all_permissions: Bool, permission_keys: List<Text>) ()
dever.auth.grantRole(user_id: Int, role_id: Text) ()
dever.auth.revokeRole(user_id: Int, role_id: Text) ()
dever.auth.disableRole(role_id: Text) ()
dever.auth.deleteRole(role_id: Text) ()
dever.auth.issueCookie(subject: Text, session: Text, tenant: Text?) ()
dever.auth.clearCookie() ()
dever.site.key() (value: Text)
```

`dever.api.require(condition, error)` 接受 Bool 条件和 dever.api.Error；false 时失败，true 时继续。

Permission 的 key/component/domain/site/action/method/kind 均为 Text；kind 为 http 或 capability，后者 method 为空、action 为 UUID。Role 有 id/site/name: Text、all_permissions/enabled/protected: Bool、permission_keys: List<Text>。

授权读取允许受保护或 authenticated 入口，修改仅允许普通受保护写入口。capability 还要求可信租户，返回 capability:<component>.<domain>.<site>.<uuid>。isOwner 查询当前站点，hasProtectedRoles 查询当前租户全部站点。访问边界见 [应用](application.md)。

dever.auth.userId()/tenantId() 可按上下文产生 verify 对应的可空名义 ID。角色操作的目标 user_id 为 Int，只标识当前租户内的对象，不替代操作者身份。

dever.job.enqueue(job.name[, payload], key) 返回 Id；enqueueAt 末尾加 DateTime。测试的 drainJobs(limit) 返回 Int，advanceClock(ms) 无输出。见 [Job 示例](examples.md#持久-job)。