assert

103 bytes

since v12.6.0

用法

Radashi 中的 assert 函数用于断言给定的 condition 为真。如果 condition 评估为 false，该函数将抛出一个错误。这是确保在运行时满足特定条件的基础构建块。

该工具在 TypeScript 中特别有用，因为它能够执行类型收窄。它在签名中使用了 asserts 关键字。当调用 assert(condition) 且条件为真时，TypeScript 会理解条件中涉及的任何变量的类型可以根据该真值性进行收窄。

import * as _ from 'radashi'

function processValue(value: string | null | undefined) {
  _.assert(value, '值不能为 null、undefined 或空')

  // 断言之后，'value' 的类型被收窄为 'string'
  console.log(value.toUpperCase())
}

processValue('hello') // 输出 "HELLO"
// _.assert 会对以下假值抛出错误：
// - null
// - undefined
// - '' (空字符串)
// - 0
// - false
// processValue(null) // 抛出 Error: 值不能为 null、undefined 或空
// processValue(undefined) // 抛出 Error: 值不能为 null、undefined 或空
// processValue('') // 抛出 Error: 值不能为 null、undefined 或空

您可以为 assert 提供一个可选的 message 作为第二个参数。如果断言失败，此消息将用作错误消息。

message 可以是一个字符串或 Error 类的实例。

• 如果提供了字符串，则会创建一个新的 Error 对象，并将该字符串作为消息。
• 如果提供了 Error 实例，则会直接抛出该特定的错误对象。
• 如果对于失败的断言没有提供消息，则使用默认消息 "Assertion failed"。

import * as _ from 'radashi'

// 使用自定义字符串消息
try {
  _.assert(false, '此条件失败！')
} catch (error: any) {
  console.error(error.message) // 输出 "此条件失败！"
}

// 使用自定义 Error 对象
const customError = new Error('发生了特定错误。')
try {
  _.assert(false, customError)
} catch (error) {
  console.error(error === customError) // 输出 "true"
}

当 condition 参数是字面量 false 时，存在一种特殊情况。在此场景下，assert(false, ...) 的 TypeScript 签名具有返回类型 never。

这个 never 返回类型向 TypeScript 编译器发出信号，表明此断言之后的代码路径是不可达的。这在诸如 switch 语句中的穷尽性检查或指示类型逻辑中的不可能状态等场景中特别有用。

import * as _ from 'radashi'

type Status = 'success' | 'pending' | 'failed'

function handleStatus(status: Status): number {
  return status === 'success'
    ? 1
    : status === 'pending'
      ? 2
      : status === 'failed'
        ? 3
        : _.assert(false, `未知状态: ${status}`)
}

// handleStatus 的返回类型是 number，但 _.assert(false)
// 分支的返回类型是 never，这是兼容的。
// 这演示了在像三元表达式这样不允许使用 throw 关键字的上下文中，
// 使用 assert(false) 作为“抛出表达式”。