feat(invariant): Implement invariant

.scripts/postbuild.sh

@@ -11,3 +11,4 @@ echo "export * from './dist/object';" > object.d.ts
 echo "export * from './dist/predicate';" > predicate.d.ts
 echo "export * from './dist/promise';" > promise.d.ts
 echo "export * from './dist/string';" > string.d.ts
+echo "export * from './dist/util';" > util.d.ts

docs/ja/reference/util/invariant.md

@@ -0,0 +1,41 @@
+# invariant
+
+与えられた条件が真であることを主張します。条件が偽の場合は、指定されたメッセージでエラーが投げられますます。
+
+## インターフェース
+
+```typescript
+function invariant(condition: unknown, message: string): asserts condition;
+```
+
+### パラメータ
+
+- `condition` (`unknown`): 評価する条件。
+- `message` (`string`): 条件が偽である場合に投げるエラーメッセージ。
+
+### 戻り値
+
+(`void`): 条件が真の場合、voidを返します。
+
+### エラー
+
+条件が偽の場合、指定されたメッセージでエラーが投げられます。
+
+## 例
+
+```typescript
+// This call will succeed without any errors
+invariant(true, 'This should not throw');
+
+// This call will fail and throw an error with the message 'This should throw'
+invariant(false, 'This should throw');
+
+// Example of using invariant with a condition
+invariant(condition, 'Expected condition is false');
+
+// Ensure that the value is neither null nor undefined
+invariant(value !== null && value !== undefined, 'Value should not be null or undefined');
+
+// Example of using invariant to check if a number is positive
+invariant(number > 0, 'Number must be positive');
+```

docs/ko/reference/util/invariant.md

@@ -0,0 +1,41 @@
+# invariant
+
+주어진 조건이 참임을 단언해요. 조건이 거짓이면 제공된 메시지와 함께 오류를 던져요.
+
+## 인터페이스
+
+```typescript
+function invariant(condition: unknown, message: string): asserts condition;
+```
+
+### 파라미터
+
+- `condition` (`unknown`): 평가할 조건.
+- `message` (`string`): 조건이 거짓일 때 발생할 오류 메시지.
+
+### 반환 값
+
+(`void`): 조건이 참이면 void를 반환해요.
+
+### 에러
+
+조건이 거짓이면 주어진 메시지와 함께 에러를 던져요.
+
+## 예시
+
+```typescript
+// This call will succeed without any errors
+invariant(true, 'This should not throw');
+
+// This call will fail and throw an error with the message 'This should throw'
+invariant(false, 'This should throw');
+
+// Example of using invariant with a condition
+invariant(condition, 'Expected condition is false');
+
+// Ensure that the value is neither null nor undefined
+invariant(value !== null && value !== undefined, 'Value should not be null or undefined');
+
+// Example of using invariant to check if a number is positive
+invariant(number > 0, 'Number must be positive');
+```

docs/reference/util/invariant.md

@@ -0,0 +1,41 @@
+# invariant
+
+Asserts that a given condition is true. If the condition is false, an error is thrown with the provided message.
+
+## Signature
+
+```typescript
+function invariant(condition: unknown, message: string): asserts condition;
+```
+
+### Parameters
+
+- `condition` (`unknown`): The condition to evaluate.
+- `message` (`string`): The error message to throw if the condition is false.
+
+### Returns
+
+(`void`): Returns void if the condition is true.
+
+### Throws
+
+Throws an error with the specified message if the condition evaluates to false.
+
+## Examples
+
+```typescript
+// This call will succeed without any errors
+invariant(true, 'This should not throw');
+
+// This call will fail and throw an error with the message 'This should throw'
+invariant(false, 'This should throw');
+
+// Example of using invariant with a condition
+invariant(condition, 'Expected condition is false');
+
+// Ensure that the value is neither null nor undefined
+invariant(value !== null && value !== undefined, 'Value should not be null or undefined');
+
+// Example of using invariant to check if a number is positive
+invariant(number > 0, 'Number must be positive');
+```

docs/zh_hans/reference/util/invariant.md

@@ -0,0 +1,41 @@
+# invariant
+
+断言给定条件为真。如果条件为假，则抛出提供的错误信息。
+
+## 签名
+
+```typescript
+function invariant(condition: unknown, message: string): asserts condition;
+```
+
+### 参数
+
+- `condition` (`unknown`): 要评估的条件。
+- `message` (`string`): 如果条件为假，则抛出的错误信息。
+
+### 返回值
+
+(`void`): 如果条件为真则返回void。
+
+### 抛出异常
+
+如果条件为假，则抛出带有指定消息的错误。
+
+## 示例
+
+```typescript
+// This call will succeed without any errors
+invariant(true, 'This should not throw');
+
+// This call will fail and throw an error with the message 'This should throw'
+invariant(false, 'This should throw');
+
+// Example of using invariant with a condition
+invariant(condition, 'Expected condition is false');
+
+// Ensure that the value is neither null nor undefined
+invariant(value !== null && value !== undefined, 'Value should not be null or undefined');
+
+// Example of using invariant to check if a number is positive
+invariant(number > 0, 'Number must be positive');
+```

package.json

@@ -24,6 +24,7 @@
     "./predicate": "./src/predicate/index.ts",
     "./promise": "./src/promise/index.ts",
     "./string": "./src/string/index.ts",
+    "./util": "./src/util/index.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -117,6 +118,16 @@
           "default": "./dist/string/index.js"
         }
       },
+      "./util": {
+        "import": {
+          "types": "./dist/util/index.d.mts",
+          "default": "./dist/util/index.mjs"
+        },
+        "require": {
+          "types": "./dist/util/index.d.ts",
+          "default": "./dist/util/index.js"
+        }
+      },
       "./compat": {
         "import": {
           "types": "./dist/compat/index.d.mts",

src/index.ts

@@ -62,3 +62,4 @@ export * from './object/index.ts';
 export * from './predicate/index.ts';
 export * from './promise/index.ts';
 export * from './string/index.ts';
+export * from './util/index.ts';

src/util/index.ts

@@ -0,0 +1 @@
+export { invariant } from './invariant.ts';

src/util/invariant.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { invariant } from './invariant';
+
+describe('invariant', () => {
+  it('should not throw an error when the condition is true', () => {
+    expect(() => invariant(true, 'This should not throw')).not.toThrow();
+
+    const value1 = 'some value';
+    expect(() =>
+      invariant(value1 !== null && value1 !== undefined, 'Value should not be null or undefined')
+    ).not.toThrow();
+
+    const value2 = null;
+    expect(() => invariant(value2 !== null && value2 !== undefined, 'Value should not be null or undefined')).toThrow(
+      'Value should not be null or undefined'
+    );
+
+    const number = 5;
+    expect(() => invariant(number > 0, 'Number must be positive')).not.toThrow();
+  });
+
+  it('should throw an error when the condition is false', () => {
+    expect(() => invariant(false, 'This should throw')).toThrow('This should throw');
+
+    const value1 = undefined;
+    expect(() => invariant(value1 !== null && value1 !== undefined, 'Value should not be null or undefined')).toThrow(
+      'Value should not be null or undefined'
+    );
+
+    const number = -1;
+    expect(() => invariant(number > 0, 'Number must be positive')).toThrow('Number must be positive');
+  });
+});

src/util/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Asserts that a given condition is true. If the condition is false, an error is thrown with the provided message.
+ *
+ * @param {unknown} condition - The condition to evaluate.
+ * @param {string} [message] - The error message to throw if the condition is false.
+ * @returns {void} Returns void if the condition is true.
+ * @throws {Error} Throws an error if the condition is false.
+ *
+ * @example
+ * // This call will succeed without any errors
+ * invariant(true, 'This should not throw');
+ *
+ * // This call will fail and throw an error with the message 'This should throw'
+ * invariant(false, 'This should throw');
+ *
+ * // Example of using invariant with a condition
+ * invariant(condition, 'Expected condition is false');
+ *
+ * // Ensure that the value is neither null nor undefined
+ * invariant(value !== null && value !== undefined, 'Value should not be null or undefined');
+ *
+ * // Example of using invariant to check if a number is positive
+ * invariant(number > 0, 'Number must be positive');
+ */
+export function invariant(condition: unknown, message: string): asserts condition {
+  if (condition) {
+    return;
+  }
+
+  throw new Error(message);
+}