@rightcapital/assert 0.0.0 → 2.1.3-feature-assertion-helpers-api-refinement.2357.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 RightCapital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
 # @rightcapital/assert
 
-Placeholder release — real implementation coming in a future version.
+Type-safe assertion utilities for defensive programming in TypeScript applications.
+
+## Key Features
+
+- **Compile-Time Exhaustiveness (`assertExhaustive`)**: Enforce full coverage of union types at compile time with TypeScript `never`.
+- **Control-Flow Guard (`assertUnreachable`)**: Mark unreachable branches for control-flow analysis and runtime safety.
+- **Expression-Level Assertions (`ensure` / `ensureNonNullable`)**: Assert and return narrowed values in single-line expressions.
+- **Type Narrowing (`assert` / `assertNonNullable`)**: Narrow types with standard TypeScript assertion signatures.
+
+## Installation
+
+```bash
+npm install @rightcapital/assert
+# or
+pnpm add @rightcapital/assert
+# or
+yarn add @rightcapital/assert
+```
+
+## Usage Examples
+
+### Compile-Time Exhaustiveness Checking (`assertExhaustive`)
+
+Use `assertExhaustive` in `switch` statements or `if-else` chains. It leverages TypeScript `never` to catch missing cases at compile time.
+
+```typescript
+import { assertExhaustive } from '@rightcapital/assert';
+
+type Action = { type: 'open' } | { type: 'close' };
+
+function handleAction(action: Action) {
+  switch (action.type) {
+    case 'open':
+      return 'Opening';
+    case 'close':
+      return 'Closing';
+    default:
+      // If a new Action type is added without a case,
+      // TypeScript reports a compile error here.
+      return assertExhaustive(action);
+  }
+}
+```
+
+### Control Flow & Unreachable Code Guard (`assertUnreachable`)
+
+Use `assertUnreachable` for code branches that should never execute. Because `assertUnreachable` returns `never`, TypeScript understands control flow stops at this point.
+
+```typescript
+import { assertUnreachable } from '@rightcapital/assert';
+
+function processStatus(status: 'active' | 'inactive') {
+  if (status === 'active') {
+    handleActive();
+  } else if (status === 'inactive') {
+    handleInactive();
+  } else {
+    // TypeScript knows execution stops here because `assertUnreachable` returns `never`.
+    assertUnreachable(`Unexpected status: ${status}`);
+  }
+}
+```
+
+> **Tip**: If your project enforces the ESLint `consistent-return` rule, add `return` before the function call (for example, `return assertUnreachable(...)`) to satisfy ESLint.
+
+### Expression-Level Type Narrowing (`ensure` & `ensureNonNullable`)
+
+Unlike `assert`, `ensure` and `ensureNonNullable` validate a value and return it with a narrowed type. This allows assertions inside single-line expressions or method chains.
+
+```typescript
+import { ensure, ensureNonNullable } from '@rightcapital/assert';
+
+// Assert and get a non-nullable value in one expression
+const userName = ensureNonNullable(getUser(), 'User must exist').name;
+
+// Assert with a custom type guard
+const admin = ensure(currentUser, isAdminUser, 'Admin privileges required');
+// `admin` is typed as AdminUser
+```
+
+### Basic Assertion & Type Narrowing (`assert` & `assertNonNullable`)
+
+Use `assert` and `assertNonNullable` for standalone statement assertions.
+
+```typescript
+import { assert, assertNonNullable } from '@rightcapital/assert';
+
+// Basic condition assertion
+assert(user.age >= 18, 'User must be at least 18 years old');
+
+// Non-nullable assertion with type narrowing
+assertNonNullable(user, 'User cannot be null');
+// `user` is narrowed to NonNullable<User>
+```
+
+### Error Handling (`AssertError`)
+
+All assertion functions throw `AssertError` (which extends `Error`) when an assertion fails.
+
+```typescript
+import { assert, AssertError } from '@rightcapital/assert';
+
+try {
+  assert(user.age >= 18, 'User must be at least 18 years old');
+} catch (error) {
+  if (error instanceof AssertError) {
+    console.error('Assertion failed:', error.message);
+  }
+}
+```
+
+## API Summary
+
+| API                              | Return / Type Behavior            | Typical Use Case                                      |
+| :------------------------------- | :-------------------------------- | :---------------------------------------------------- |
+| `AssertError`                    | `class extends Error`             | Error thrown on assertion failure                     |
+| `assertExhaustive(value, msg?)`  | `never`                           | Enforce exhaustiveness check in `switch` or `if-else` |
+| `assertUnreachable(msg?)`        | `never`                           | Mark logically unreachable code branches              |
+| `ensure(value, predicate, msg?)` | `S extends T`                     | Validate and return value with narrowed type          |
+| `ensureNonNullable(value, msg?)` | `NonNullable<T>`                  | Validate non-null/undefined and return value          |
+| `assert(value, msg?)`            | `asserts value`                   | Standard boolean condition assertion                  |
+| `assertNonNullable(value, msg?)` | `asserts value is NonNullable<T>` | Standard non-null/undefined assertion                 |
+
+## Agent Skills
+
+This package ships with an [Agent Skill](https://agentskills.io) that teaches AI coding agents (Claude Code, Cursor, etc.) how to use the assert API correctly, following the [npm-based Agent Skills Convention](https://github.com/antfu/skills-npm).
+
+### Automatic discovery (recommended)
+
+If your project uses [`skills-npm`](https://github.com/antfu/skills-npm), the skill is discovered automatically from `node_modules`:
+
+```bash
+npx skills-npm
+```
+
+### Manual installation
+
+You can also install the skill directly using the [`skills` CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add https://github.com/RightCapitalHQ/frontend-libraries/tree/main/packages/assert/skills
+```
+
+## API Reference
+
+See the [generated documentation](./docs/README.md) for detailed API reference.

package/lib/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Assertion functions provide type-safe assertions and validation.
+ * When assertions fail, they throw `AssertError`.
+ *
+ * @author lixiaoyan <lxy.lixiaoyan@gmail.com>
+ * @example
+ * ```typescript
+ * // Basic assertion
+ * assert(user.age >= 18, 'User must be at least 18 years old');
+ *
+ * // Non-nullable assertion with type narrowing
+ * assertNonNullable(user, 'User cannot be null');
+ * // user is now typed as NonNullable<T>
+ *
+ * // Ensure with type guard
+ * const admin = ensure(currentUser, isAdminUser, 'Admin required');
+ * // admin is now typed as AdminUser
+ * ```
+ */
+/**
+ * Error thrown when an assertion fails.
+ */
+export declare class AssertError extends Error {
+    readonly name = "AssertError";
+}
+/**
+ * Basic assertion: verifies that a value or expression is `true`, otherwise throws an exception.
+ *
+ * @param value - The value to assert as truthy
+ * @param message - Optional custom error message
+ * @throws {AssertError} Throws an error if `value` is not `true`.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * assert(user.age >= 18, 'User must be at least 18 years old');
+ *
+ * // Condition validation
+ * const isValid = validateData(data);
+ * assert(isValid, 'Data validation failed');
+ * ```
+ */
+export declare function assert(value: unknown, message?: string): asserts value;
+/**
+ * Asserts that a value is not `null` or `undefined`, providing TypeScript type narrowing to `NonNullable<T>`.
+ * Ensures subsequent code can safely access the value.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @throws {AssertError} Throws an error if `value` is `null` or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * function processUser(user: User | null | undefined) {
+ *   assertNonNullable(user, 'User cannot be null');
+ *   // user is now typed as User
+ *   console.log(user.name); // Safe to access
+ * }
+ * ```
+ */
+export declare function assertNonNullable<T>(value: T, message?: string): asserts value is NonNullable<T>;
+/**
+ * Similar to `assert`, but returns the value. Ensures a value matches a type predicate and returns it with narrowed type.
+ *
+ * @param value - The value to validate
+ * @param predicate - Type guard function that validates the value
+ * @param message - Optional custom error message
+ * @returns The value with narrowed type
+ * @throws {AssertError} Throws an error if `predicate` returns `false`.
+ *
+ * @example
+ * ```typescript
+ * // Define type guard
+ * function isAdminUser(user: User): user is AdminUser {
+ *   return user.role === 'admin';
+ * }
+ *
+ * // Use ensure to get type-safe value
+ * const admin = ensure(
+ *   currentUser,
+ *   isAdminUser,
+ *   'Admin privileges required'
+ * );
+ * // admin is typed as AdminUser
+ * ```
+ */
+export declare function ensure<T, S extends T>(value: T, predicate: (value: T) => value is S, message?: string): S;
+/**
+ * Similar to `assertNonNullable`, but returns the value. Ensures a value is not null/undefined and returns it.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @returns The non-nullable value
+ * @throws {AssertError} Throws an error if `value` is `null` or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * // Use in expressions
+ * const config = ensureNonNullable(
+ *   getConfig(),
+ *   'Configuration not found'
+ * );
+ *
+ * // Chain calls
+ * const userName = ensureNonNullable(user, 'User not found').name;
+ * ```
+ */
+export declare function ensureNonNullable<T>(value: T, message?: string): NonNullable<T>;
+/**
+ * Marks code branches that should theoretically never be reached.
+ * Used for defensive programming to prevent unexpected code execution when data or logic doesn't match expectations.
+ *
+ * @param message - Optional custom error message
+ * @returns Never returns (always throws)
+ * @throws {AssertError} Always thrown.
+ *
+ * @example
+ * ```typescript
+ * function processStatus(status: 'active' | 'inactive' | 'activating') {
+ *   if (status === 'active') {
+ *     // Handle active state
+ *   } else if (status === 'inactive') {
+ *     // Handle inactive state
+ *   } else {
+ *     // According to business logic, this should never be reached
+ *     assertUnreachable(`Unexpected status value: ${status}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function assertUnreachable(message?: string): never;
+/**
+ * Used for exhaustiveness checking of union types. Ensures switch or if-else statements cover all possible types.
+ * Leverages TypeScript's `never` type to catch missing branches at compile time.
+ *
+ * @param value - The value that should be `never` if all cases are handled
+ * @param message - Optional custom error message
+ * @returns Never returns (always throws)
+ * @throws {AssertError} Always thrown.
+ *
+ * @example
+ * ```typescript
+ * type Action =
+ *   | { type: 'ADD'; payload: number }
+ *   | { type: 'SUBTRACT'; payload: number }
+ *   | { type: 'MULTIPLY'; payload: number };
+ *
+ * function reducer(action: Action) {
+ *   switch (action.type) {
+ *     case 'ADD':
+ *       return state + action.payload;
+ *     case 'SUBTRACT':
+ *       return state - action.payload;
+ *     case 'MULTIPLY':
+ *       return state * action.payload;
+ *     default:
+ *       // If all types are exhausted, action is of type never
+ *       // If new Action types are added but not handled, TypeScript will report error
+ *       return assertExhaustive(action);
+ *                               // ^ never
+ *   }
+ * }
+ * ```
+ */
+export declare function assertExhaustive(value: never, message?: string): never;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAyB,IAAI,iBAAiB;CAC/C;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAItE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAIjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,EACnC,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,EACnC,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAGH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAAC,CAAC,CAAC,CAKhB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAEtE"}

package/lib/index.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Assertion functions provide type-safe assertions and validation.
+ * When assertions fail, they throw `AssertError`.
+ *
+ * @author lixiaoyan <lxy.lixiaoyan@gmail.com>
+ * @example
+ * ```typescript
+ * // Basic assertion
+ * assert(user.age >= 18, 'User must be at least 18 years old');
+ *
+ * // Non-nullable assertion with type narrowing
+ * assertNonNullable(user, 'User cannot be null');
+ * // user is now typed as NonNullable<T>
+ *
+ * // Ensure with type guard
+ * const admin = ensure(currentUser, isAdminUser, 'Admin required');
+ * // admin is now typed as AdminUser
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertExhaustive = exports.assertUnreachable = exports.ensureNonNullable = exports.ensure = exports.assertNonNullable = exports.assert = exports.AssertError = void 0;
+/**
+ * Error thrown when an assertion fails.
+ */
+class AssertError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'AssertError';
+    }
+}
+exports.AssertError = AssertError;
+/**
+ * Throws an AssertError for failed assertions.
+ */
+function throwError(name, value, message) {
+    throw new AssertError(message !== null && message !== void 0 ? message : `${name}: Unexpected ${String(value)}`);
+}
+/**
+ * Basic assertion: verifies that a value or expression is `true`, otherwise throws an exception.
+ *
+ * @param value - The value to assert as truthy
+ * @param message - Optional custom error message
+ * @throws {AssertError} Throws an error if `value` is not `true`.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * assert(user.age >= 18, 'User must be at least 18 years old');
+ *
+ * // Condition validation
+ * const isValid = validateData(data);
+ * assert(isValid, 'Data validation failed');
+ * ```
+ */
+function assert(value, message) {
+    if (value !== true) {
+        throwError('assert', value, message);
+    }
+}
+exports.assert = assert;
+/**
+ * Asserts that a value is not `null` or `undefined`, providing TypeScript type narrowing to `NonNullable<T>`.
+ * Ensures subsequent code can safely access the value.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @throws {AssertError} Throws an error if `value` is `null` or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * function processUser(user: User | null | undefined) {
+ *   assertNonNullable(user, 'User cannot be null');
+ *   // user is now typed as User
+ *   console.log(user.name); // Safe to access
+ * }
+ * ```
+ */
+function assertNonNullable(value, message) {
+    if (value === null || value === undefined) {
+        throwError('assertNonNullable', value, message);
+    }
+}
+exports.assertNonNullable = assertNonNullable;
+/**
+ * Similar to `assert`, but returns the value. Ensures a value matches a type predicate and returns it with narrowed type.
+ *
+ * @param value - The value to validate
+ * @param predicate - Type guard function that validates the value
+ * @param message - Optional custom error message
+ * @returns The value with narrowed type
+ * @throws {AssertError} Throws an error if `predicate` returns `false`.
+ *
+ * @example
+ * ```typescript
+ * // Define type guard
+ * function isAdminUser(user: User): user is AdminUser {
+ *   return user.role === 'admin';
+ * }
+ *
+ * // Use ensure to get type-safe value
+ * const admin = ensure(
+ *   currentUser,
+ *   isAdminUser,
+ *   'Admin privileges required'
+ * );
+ * // admin is typed as AdminUser
+ * ```
+ */
+function ensure(value, predicate, message) {
+    assert(predicate(value), message);
+    return value;
+}
+exports.ensure = ensure;
+/**
+ * Similar to `assertNonNullable`, but returns the value. Ensures a value is not null/undefined and returns it.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @returns The non-nullable value
+ * @throws {AssertError} Throws an error if `value` is `null` or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * // Use in expressions
+ * const config = ensureNonNullable(
+ *   getConfig(),
+ *   'Configuration not found'
+ * );
+ *
+ * // Chain calls
+ * const userName = ensureNonNullable(user, 'User not found').name;
+ * ```
+ */
+function ensureNonNullable(value, message) {
+    if (value === null || value === undefined) {
+        throwError('ensureNonNullable', value, message);
+    }
+    return value;
+}
+exports.ensureNonNullable = ensureNonNullable;
+/**
+ * Marks code branches that should theoretically never be reached.
+ * Used for defensive programming to prevent unexpected code execution when data or logic doesn't match expectations.
+ *
+ * @param message - Optional custom error message
+ * @returns Never returns (always throws)
+ * @throws {AssertError} Always thrown.
+ *
+ * @example
+ * ```typescript
+ * function processStatus(status: 'active' | 'inactive' | 'activating') {
+ *   if (status === 'active') {
+ *     // Handle active state
+ *   } else if (status === 'inactive') {
+ *     // Handle inactive state
+ *   } else {
+ *     // According to business logic, this should never be reached
+ *     assertUnreachable(`Unexpected status value: ${status}`);
+ *   }
+ * }
+ * ```
+ */
+function assertUnreachable(message) {
+    throwError('assertUnreachable', null, message);
+}
+exports.assertUnreachable = assertUnreachable;
+/**
+ * Used for exhaustiveness checking of union types. Ensures switch or if-else statements cover all possible types.
+ * Leverages TypeScript's `never` type to catch missing branches at compile time.
+ *
+ * @param value - The value that should be `never` if all cases are handled
+ * @param message - Optional custom error message
+ * @returns Never returns (always throws)
+ * @throws {AssertError} Always thrown.
+ *
+ * @example
+ * ```typescript
+ * type Action =
+ *   | { type: 'ADD'; payload: number }
+ *   | { type: 'SUBTRACT'; payload: number }
+ *   | { type: 'MULTIPLY'; payload: number };
+ *
+ * function reducer(action: Action) {
+ *   switch (action.type) {
+ *     case 'ADD':
+ *       return state + action.payload;
+ *     case 'SUBTRACT':
+ *       return state - action.payload;
+ *     case 'MULTIPLY':
+ *       return state * action.payload;
+ *     default:
+ *       // If all types are exhausted, action is of type never
+ *       // If new Action types are added but not handled, TypeScript will report error
+ *       return assertExhaustive(action);
+ *                               // ^ never
+ *   }
+ * }
+ * ```
+ */
+function assertExhaustive(value, message) {
+    throwError('assertExhaustive', value, message);
+}
+exports.assertExhaustive = assertExhaustive;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH;;GAEG;AACH,MAAa,WAAY,SAAQ,KAAK;IAAtC;;QAC2B,SAAI,GAAG,aAAa,CAAC;IAChD,CAAC;CAAA;AAFD,kCAEC;AAED;;GAEG;AACH,SAAS,UAAU,CACjB,IAAY,EACZ,KAAc,EACd,OAA2B;IAE3B,MAAM,IAAI,WAAW,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,GAAG,IAAI,gBAAgB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,MAAM,CAAC,KAAc,EAAE,OAAgB;IACrD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,UAAU,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAJD,wBAIC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,iBAAiB,CAC/B,KAAQ,EACR,OAAgB;IAEhB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,UAAU,CAAC,mBAAmB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAPD,8CAOC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,MAAM,CACpB,KAAQ,EACR,SAAmC,EACnC,OAAgB;IAEhB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC;AACf,CAAC;AAPD,wBAOC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,iBAAiB,CAC/B,KAAQ,EACR,OAAgB;IAEhB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,UAAU,CAAC,mBAAmB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AARD,8CAQC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,iBAAiB,CAAC,OAAgB;IAChD,UAAU,CAAC,mBAAmB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAFD,8CAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAgB,gBAAgB,CAAC,KAAY,EAAE,OAAgB;IAC7D,UAAU,CAAC,kBAAkB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAFD,4CAEC"}

package/package.json

@@ -1,14 +1,42 @@
 {
   "name": "@rightcapital/assert",
-  "version": "0.0.0",
+  "version": "2.1.3-feature-assertion-helpers-api-refinement.2357.1.0",
+  "description": "Type-safe assertion utilities for defensive programming.",
+  "author": "RightCapital Ecosystem team <npm-publisher@rightcapital.com>",
+  "keywords": [
+    "assertion",
+    "type-safe",
+    "validation",
+    "defensive",
+    "TypeScript",
+    "tanstack-intent",
+    "utilities"
+  ],
+  "sideEffects": false,
   "license": "MIT",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/RightCapitalHQ/frontend-libraries.git",
     "directory": "packages/assert"
   },
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "src"
+  ],
   "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "typedoc": "0.25.7",
+    "typedoc-plugin-markdown": "3.17.1"
+  },
+  "scripts": {
+    "docs": "pnpm exec typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts"
   }
-}
+}

package/skills/assert/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: assert
+description: >-
+  Type-safe assertion and validation utilities for defensive TypeScript programming.
+  Use when writing runtime assertions, null checks, type guard validations, unreachable code markers, or exhaustive switch/if-else checking.
+  Import named functions from @rightcapital/assert.
+license: MIT
+metadata:
+  author: RightCapital
+  package: '@rightcapital/assert'
+---
+
+# assert
+
+Type-safe assertion utilities for defensive TypeScript programming. All functions throw `AssertError` (which extends `Error`) on failure. Default error message format is `${functionName}: Unexpected ${String(value)}`.
+
+## Import
+
+```typescript
+import {
+  assert,
+  AssertError,
+  assertExhaustive,
+  assertNonNullable,
+  assertUnreachable,
+  ensure,
+  ensureNonNullable,
+} from '@rightcapital/assert';
+```
+
+## Quick Reference
+
+| Class / Function                 | Signature / Return                | Use Case                                                            |
+| -------------------------------- | --------------------------------- | ------------------------------------------------------------------- |
+| `AssertError`                    | `class extends Error`             | Error type thrown when any assertion in this package fails.         |
+| `assert(value, msg?)`            | `asserts value`                   | Precondition or boolean check (verifies `value === true`).          |
+| `assertNonNullable(value, msg?)` | `asserts value is NonNullable<T>` | Guard statement against `null` or `undefined`.                      |
+| `ensure(value, predicate, msg?)` | `S extends T`                     | Inline validation using type guard function `(val: T) => val is S`. |
+| `ensureNonNullable(value, msg?)` | `NonNullable<T>`                  | Inline assignment or method chain for non-null value.               |
+| `assertExhaustive(value, msg?)`  | `value: never` -> `never`         | Exhaustiveness check in `switch` `default` case or `if-else` chain. |
+| `assertUnreachable(msg?)`        | `never`                           | Mark logically impossible code paths.                               |
+
+## Error Handling with `AssertError`
+
+All assertion functions throw `AssertError` when a condition is not met. Use `instanceof AssertError` to catch assertion failures specifically:
+
+```typescript
+import { assert, AssertError } from '@rightcapital/assert';
+
+try {
+  assert(age >= 18, 'User must be an adult');
+} catch (error) {
+  if (error instanceof AssertError) {
+    console.error('Assertion failed:', error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Critical Rules for Code Generation
+
+### 1. `assert()` Checks Strict Boolean Equality (`value !== true`)
+
+`assert(value)` throws if `value !== true`. It throws for truthy non-boolean values like objects or strings.
+
+- **Incorrect**: `assert(user);` (throws even if `user` is an object)
+- **Correct**: `assertNonNullable(user);`
+- **Correct**: `assert(user.age >= 18, 'Must be 18+');`
+
+### 2. Choose `assert*` Statements vs `ensure*` Expressions
+
+- **`assert*` functions** are statements. They narrow the type of an existing variable for subsequent code.
+- **`ensure*` functions** are expressions. They return the validated value with a narrowed type for direct assignment or chaining.
+
+```typescript
+// Statement form
+assertNonNullable(user);
+console.log(user.name);
+
+// Expression form
+const userName = ensureNonNullable(getUser()).name;
+```
+
+### 3. `ensure()` Requires a Type Guard Predicate
+
+The `predicate` parameter in `ensure(val, predicate)` must be a TypeScript type guard (`(val: T) => val is S`). A standard boolean function without a type predicate will cause a compile error.
+
+```typescript
+function isAdminUser(user: User): user is AdminUser {
+  return user.role === 'admin';
+}
+
+const admin = ensure(currentUser, isAdminUser, 'Admin required');
+```
+
+### 4. `assertExhaustive` vs `assertUnreachable`
+
+- Use `assertExhaustive(value)` when TypeScript can prove all union cases are handled (e.g., `switch` default case). It catches missing union members at compile time because `value` must be typed as `never`.
+- Use `assertUnreachable(message)` for defensive checks in branches that TypeScript cannot prove unreachable.
+- Prefix with `return` in non-void functions (for example, `return assertExhaustive(val);` or `return assertUnreachable(msg);`) to satisfy ESLint `consistent-return`.
+
+```typescript
+// Exhaustive switch over union
+switch (shape.kind) {
+  case 'circle':
+    return Math.PI * shape.radius ** 2;
+  case 'square':
+    return shape.side ** 2;
+  default:
+    return assertExhaustive(shape);
+}
+
+// Unreachable defensive branch
+if (status === 'active') {
+  handleActive();
+} else if (status === 'inactive') {
+  handleInactive();
+} else {
+  return assertUnreachable(`Unexpected status: ${status}`);
+}
+```

package/src/index.ts

@@ -0,0 +1,213 @@
+/**
+ * Assertion functions provide type-safe assertions and validation.
+ * When assertions fail, they throw `AssertError`.
+ *
+ * @author lixiaoyan <lxy.lixiaoyan@gmail.com>
+ * @example
+ * ```typescript
+ * // Basic assertion
+ * assert(user.age >= 18, 'User must be at least 18 years old');
+ *
+ * // Non-nullable assertion with type narrowing
+ * assertNonNullable(user, 'User cannot be null');
+ * // user is now typed as NonNullable<T>
+ *
+ * // Ensure with type guard
+ * const admin = ensure(currentUser, isAdminUser, 'Admin required');
+ * // admin is now typed as AdminUser
+ * ```
+ */
+
+/**
+ * Error thrown when an assertion fails.
+ */
+export class AssertError extends Error {
+  public override readonly name = 'AssertError';
+}
+
+/**
+ * Throws an AssertError for failed assertions.
+ */
+function throwError(
+  name: string,
+  value: unknown,
+  message: string | undefined,
+): never {
+  throw new AssertError(message ?? `${name}: Unexpected ${String(value)}`);
+}
+
+/**
+ * Basic assertion: verifies that a value or expression is `true`, otherwise throws an exception.
+ *
+ * @param value - The value to assert as truthy
+ * @param message - Optional custom error message
+ * @throws {AssertError} Throws an error if `value` is not `true`.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * assert(user.age >= 18, 'User must be at least 18 years old');
+ *
+ * // Condition validation
+ * const isValid = validateData(data);
+ * assert(isValid, 'Data validation failed');
+ * ```
+ */
+export function assert(value: unknown, message?: string): asserts value {
+  if (value !== true) {
+    throwError('assert', value, message);
+  }
+}
+
+/**
+ * Asserts that a value is not `null` or `undefined`, providing TypeScript type narrowing to `NonNullable<T>`.
+ * Ensures subsequent code can safely access the value.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @throws {AssertError} Throws an error if `value` is `null` or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * function processUser(user: User | null | undefined) {
+ *   assertNonNullable(user, 'User cannot be null');
+ *   // user is now typed as User
+ *   console.log(user.name); // Safe to access
+ * }
+ * ```
+ */
+export function assertNonNullable<T>(
+  value: T,
+  message?: string,
+): asserts value is NonNullable<T> {
+  if (value === null || value === undefined) {
+    throwError('assertNonNullable', value, message);
+  }
+}
+
+/**
+ * Similar to `assert`, but returns the value. Ensures a value matches a type predicate and returns it with narrowed type.
+ *
+ * @param value - The value to validate
+ * @param predicate - Type guard function that validates the value
+ * @param message - Optional custom error message
+ * @returns The value with narrowed type
+ * @throws {AssertError} Throws an error if `predicate` returns `false`.
+ *
+ * @example
+ * ```typescript
+ * // Define type guard
+ * function isAdminUser(user: User): user is AdminUser {
+ *   return user.role === 'admin';
+ * }
+ *
+ * // Use ensure to get type-safe value
+ * const admin = ensure(
+ *   currentUser,
+ *   isAdminUser,
+ *   'Admin privileges required'
+ * );
+ * // admin is typed as AdminUser
+ * ```
+ */
+export function ensure<T, S extends T>(
+  value: T,
+  predicate: (value: T) => value is S,
+  message?: string,
+): S {
+  assert(predicate(value), message);
+  return value;
+}
+
+/**
+ * Similar to `assertNonNullable`, but returns the value. Ensures a value is not null/undefined and returns it.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @returns The non-nullable value
+ * @throws {AssertError} Throws an error if `value` is `null` or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * // Use in expressions
+ * const config = ensureNonNullable(
+ *   getConfig(),
+ *   'Configuration not found'
+ * );
+ *
+ * // Chain calls
+ * const userName = ensureNonNullable(user, 'User not found').name;
+ * ```
+ */
+export function ensureNonNullable<T>(
+  value: T,
+  message?: string,
+): NonNullable<T> {
+  if (value === null || value === undefined) {
+    throwError('ensureNonNullable', value, message);
+  }
+  return value;
+}
+
+/**
+ * Marks code branches that should theoretically never be reached.
+ * Used for defensive programming to prevent unexpected code execution when data or logic doesn't match expectations.
+ *
+ * @param message - Optional custom error message
+ * @returns Never returns (always throws)
+ * @throws {AssertError} Always thrown.
+ *
+ * @example
+ * ```typescript
+ * function processStatus(status: 'active' | 'inactive' | 'activating') {
+ *   if (status === 'active') {
+ *     // Handle active state
+ *   } else if (status === 'inactive') {
+ *     // Handle inactive state
+ *   } else {
+ *     // According to business logic, this should never be reached
+ *     assertUnreachable(`Unexpected status value: ${status}`);
+ *   }
+ * }
+ * ```
+ */
+export function assertUnreachable(message?: string): never {
+  throwError('assertUnreachable', null, message);
+}
+
+/**
+ * Used for exhaustiveness checking of union types. Ensures switch or if-else statements cover all possible types.
+ * Leverages TypeScript's `never` type to catch missing branches at compile time.
+ *
+ * @param value - The value that should be `never` if all cases are handled
+ * @param message - Optional custom error message
+ * @returns Never returns (always throws)
+ * @throws {AssertError} Always thrown.
+ *
+ * @example
+ * ```typescript
+ * type Action =
+ *   | { type: 'ADD'; payload: number }
+ *   | { type: 'SUBTRACT'; payload: number }
+ *   | { type: 'MULTIPLY'; payload: number };
+ *
+ * function reducer(action: Action) {
+ *   switch (action.type) {
+ *     case 'ADD':
+ *       return state + action.payload;
+ *     case 'SUBTRACT':
+ *       return state - action.payload;
+ *     case 'MULTIPLY':
+ *       return state * action.payload;
+ *     default:
+ *       // If all types are exhausted, action is of type never
+ *       // If new Action types are added but not handled, TypeScript will report error
+ *       return assertExhaustive(action);
+ *                               // ^ never
+ *   }
+ * }
+ * ```
+ */
+export function assertExhaustive(value: never, message?: string): never {
+  throwError('assertExhaustive', value, message);
+}