@produck/type-error 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,139 @@
+# @produck/type-error
+
+A utility library for generating and throwing TypeError messages following the
+Produck TypeError template format.
+
+## Installation
+
+```bash
+npm install @produck/type-error
+```
+
+## API
+
+### `ErrorMessage(role: string, expected: string): string`
+
+Generates a formatted error message for type validation failures.
+
+**Parameters:**
+- `role` - Description of the parameter role (e.g., `"args[0]"`, `"options.name"`)
+- `expected` - Expected type or value description (e.g., `"string"`, `"function"`)
+
+**Returns:** Formatted error message string
+
+**Throws:** `TypeError` if role or expected is not a string
+
+**Example:**
+```javascript
+import { ErrorMessage } from '@produck/type-error';
+
+const message = ErrorMessage('args[0]', 'string');
+// Returns: Invalid "args[0]", one "string" expected.
+```
+
+### `ThrowTypeError(role: string, expected: string): never`
+
+Throws a TypeError with a formatted message.
+
+**Parameters:**
+- `role` - Description of the parameter role
+- `expected` - Expected type or value description
+
+**Throws:** `TypeError` always with formatted message
+
+**Example:**
+```javascript
+import { ThrowTypeError } from '@produck/type-error';
+
+function myFunction(value) {
+  if (typeof value !== 'string') {
+    ThrowTypeError('args[0]', 'string');
+  }
+}
+```
+
+### `AssertionChecker(validate: Validate, defaultExpected: string): Assert`
+
+Creates a reusable assertion function with a custom validation function.
+
+**Parameters:**
+- `validate` - Function that returns `true` if value is valid, `false` otherwise
+- `defaultExpected` - Default "expected" message used in error messages
+
+**Returns:** An assertion function `(value: unknown, role: string, expected?: string) => undefined`
+
+**Throws:** `TypeError` if validate is not a function or defaultExpected is not
+a string
+
+**Example:**
+```javascript
+import { AssertionChecker } from '@produck/type-error';
+
+const assertString = AssertionChecker(
+  (value) => typeof value === 'string',
+  'string'
+);
+
+// Use the assertion
+try {
+  assertString(42, 'args[0]');
+} catch (error) {
+  console.error(error.message);
+  // TypeError: Invalid "args[0]", one "string" expected.
+}
+
+// With custom expected message
+try {
+  assertString(null, 'args[0]', 'non-null string');
+} catch (error) {
+  console.error(error.message);
+  // TypeError: Invalid "args[0]", one "non-null string" expected.
+}
+```
+
+## Usage Patterns
+
+### Basic Validation
+
+```javascript
+import { ThrowTypeError } from '@produck/type-error';
+
+function processData(data) {
+  if (typeof data !== 'object' || data === null) {
+    ThrowTypeError('args[0]', 'object');
+  }
+  // ...
+}
+```
+
+### Creating Custom Validators
+
+```javascript
+import { AssertionChecker } from '@produck/type-error';
+
+const assertNumber = AssertionChecker(
+  (v) => typeof v === 'number',
+  'number'
+);
+
+const assertArray = AssertionChecker(
+  (v) => Array.isArray(v),
+  'array'
+);
+
+function calculateSum(numbers) {
+  assertArray(numbers, 'args[0]');
+  return numbers.reduce((sum, n) => {
+    assertNumber(n, 'array element');
+    return sum + n;
+  });
+}
+```
+
+## License
+
+MIT
+
+## Author
+
+ChaosLee

package/index.d.ts

@@ -1,6 +1,54 @@
-export type Assert = (value: unknown, role: string, expected?: string) => undefined;
+/**
+ * Assertion function that validates a value and throws TypeError if invalid
+ * @param value - The value to validate
+ * @param role - Description of the parameter role (e.g., "args[0]")
+ * @param expected - Expected type/value description (optional, uses default)
+ */
+export type Assert = (
+  value: unknown,
+  role: string,
+  expected?: string
+) => undefined;
+
+/**
+ * Validation function that checks if a value meets criteria
+ * @param value - The value to validate
+ * @returns true if valid, false otherwise
+ */
 export type Validate = (value: unknown) => boolean;
 
-export function ErrorMessage(role: string, expected: string): string;
-export function ThrowTypeError(): never;
-export function AssertionChecker(validate: Validate, defaultExpected: string): Assert;
+/**
+ * Generates a formatted error message for type validation failures
+ * @param role - Description of the parameter role
+ * @param expected - Expected type/value description
+ * @returns Formatted error message string
+ * @throws TypeError when role or expected is not a string
+ */
+export function ErrorMessage(
+  role: string,
+  expected: string
+): string;
+
+/**
+ * Throws a TypeError with a formatted message for type validation failures
+ * @param role - Description of the parameter role
+ * @param expected - Expected type/value description
+ * @throws TypeError always throws with formatted message
+ */
+export function ThrowTypeError(
+  role: string,
+  expected: string
+): never;
+
+/**
+ * Creates an assertion checker function with a custom validation function
+ * @param validate - Function that returns true if value is valid
+ * @param defaultExpected - Default "expected" message for the assertion
+ * @returns Assertion function that validates values
+ * @throws TypeError when validate is not a function or
+ *                   defaultExpected is not a string
+ */
+export function AssertionChecker(
+  validate: Validate,
+  defaultExpected: string
+): Assert;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@produck/type-error",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "",
 	"license": "MIT",
 	"author": "ChaosLee",
@@ -24,5 +24,5 @@
 		"test": "node ./test/index.mjs",
 		"test:only": "node --test-only ./test/index.mjs"
 	},
-	"gitHead": "de2978224fdba772c16d283baf328d8624f8d10f"
+	"gitHead": "e643e102546b9afc6dc47e1dd38fbb9e8157b86e"
 }