@rightcapital/assert 3.0.1-renovate-auto-merge-dev-dependencies-updates.2473.1.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +15 -1
  2. package/lib/index.d.ts +15 -0
  3. package/lib/index.d.ts.map +1 -1
  4. package/lib/index.js +38 -25
  5. package/lib/index.js.map +1 -1
  6. package/package.json +11 -3
  7. package/skills/assert/SKILL.md +4 -2
  8. package/src/index.ts +35 -10
package/README.md CHANGED
@@ -8,6 +8,7 @@ Type-safe assertion utilities for defensive programming in TypeScript applicatio
8
8
  - **Control-Flow Guard (`assertUnreachable`)**: Mark unreachable branches for control-flow analysis and runtime safety.
9
9
  - **Expression-Level Assertions (`ensure` / `ensureNonNullable`)**: Assert and return narrowed values in single-line expressions.
10
10
  - **Type Narrowing (`assert` / `assertNonNullable`)**: Narrow types with standard TypeScript assertion signatures.
11
+ - **Unimplemented Stubs (`unimplemented`)**: Mark methods that should throw when called.
11
12
 
12
13
  ## Installation
13
14
 
@@ -111,6 +112,18 @@ try {
111
112
  }
112
113
  ```
113
114
 
115
+ ### Unimplemented Stubs (`unimplemented`)
116
+
117
+ Use `unimplemented` to mark a method that is intentionally not implemented yet. Calling it always throws an `AssertionError`.
118
+
119
+ ```typescript
120
+ import { unimplemented } from '@rightcapital/assert';
121
+
122
+ function saveDraft(): never {
123
+ return unimplemented('Draft saving is not available yet');
124
+ }
125
+ ```
126
+
114
127
  ## API Summary
115
128
 
116
129
  | API / Signature | Description / Typical Use Case |
@@ -118,6 +131,7 @@ try {
118
131
  | `AssertionError extends Error` | Error thrown on assertion failure |
119
132
  | `assertExhaustive(value: never, message?: string): never` | Enforce exhaustiveness check in `switch` or `if-else` |
120
133
  | `assertUnreachable(message?: string): never` | Mark logically unreachable code branches |
134
+ | `unimplemented(message?: string): never` | Mark a method stub that always throws |
121
135
  | `ensure<T, S extends T>(value: T, predicate: (value: T) => value is S, message?: string): S` | Validate and return value with narrowed type |
122
136
  | `ensureNonNullable<T>(value: T, message?: string): NonNullable<T>` | Validate non-null/undefined and return value |
123
137
  | `assert(value: boolean, message?: string): asserts value` | Standard boolean condition assertion |
@@ -145,4 +159,4 @@ npx skills add https://github.com/RightCapitalHQ/frontend-libraries/tree/main/pa
145
159
 
146
160
  ## API Reference
147
161
 
148
- See the [generated documentation](./docs/README.md) for detailed API reference.
162
+ See the [generated documentation](/packages/assert/docs/modules.md) for detailed API reference.
package/lib/index.d.ts CHANGED
@@ -163,4 +163,19 @@ export declare function assertUnreachable(message?: string): never;
163
163
  * ```
164
164
  */
165
165
  export declare function assertExhaustive(value: never, message?: string): never;
166
+ /**
167
+ * Marks methods or code paths that are intentionally not implemented yet.
168
+ *
169
+ * @param message - Optional custom error message
170
+ * @returns Never returns (always throws)
171
+ * @throws {AssertionError} Always thrown.
172
+ *
173
+ * @example
174
+ * ```typescript
175
+ * function saveDraft(): never {
176
+ * return unimplemented('Draft saving is not available yet');
177
+ * }
178
+ * ```
179
+ */
180
+ export declare function unimplemented(message?: string): never;
166
181
  //# sourceMappingURL=index.d.ts.map
package/lib/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAyB,IAAI,oBAAoB;CAClD;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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAyB,IAAI,oBAAoB;CAClD;AAoBD;;;;;;;;;;;;;;;;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,SAA6B,GAAG,KAAK,CAE7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,SAAoB,GAAG,KAAK,CAEhE"}
package/lib/index.js CHANGED
@@ -1,4 +1,3 @@
1
- "use strict";
2
1
  /**
3
2
  * Assertion functions provide type-safe assertions and validation.
4
3
  * When assertions fail, they throw `AssertionError`.
@@ -18,29 +17,26 @@
18
17
  * // admin is now typed as AdminUser
19
18
  * ```
20
19
  */
21
- Object.defineProperty(exports, "__esModule", { value: true });
22
- exports.AssertionError = void 0;
23
- exports.assert = assert;
24
- exports.assertNonNullable = assertNonNullable;
25
- exports.ensure = ensure;
26
- exports.ensureNonNullable = ensureNonNullable;
27
- exports.assertUnreachable = assertUnreachable;
28
- exports.assertExhaustive = assertExhaustive;
29
20
  /**
30
21
  * Error thrown when an assertion fails.
31
22
  */
32
- class AssertionError extends Error {
23
+ export class AssertionError extends Error {
33
24
  constructor() {
34
25
  super(...arguments);
35
26
  this.name = 'AssertionError';
36
27
  }
37
28
  }
38
- exports.AssertionError = AssertionError;
39
29
  /**
40
- * Throws an AssertionError for failed assertions.
30
+ * Throws an AssertionError with a message prefixed by the assertion name.
41
31
  */
42
- function throwError(name, value, message) {
43
- throw new AssertionError(message !== null && message !== void 0 ? message : `${name}: Unexpected ${String(value)}`);
32
+ function throwError(name, message) {
33
+ throw new AssertionError(`${name}: ${message}`);
34
+ }
35
+ /**
36
+ * Throws an AssertionError for an unexpected value.
37
+ */
38
+ function throwUnexpectedValueError(name, value, message = `Unexpected ${String(value)}`) {
39
+ throwError(name, message);
44
40
  }
45
41
  /**
46
42
  * Basic assertion: verifies that a value or expression is `true`, otherwise throws an exception.
@@ -59,9 +55,9 @@ function throwError(name, value, message) {
59
55
  * assert(isValid, 'Data validation failed');
60
56
  * ```
61
57
  */
62
- function assert(value, message) {
58
+ export function assert(value, message) {
63
59
  if (value !== true) {
64
- throwError('assert', value, message);
60
+ throwUnexpectedValueError('assert', value, message);
65
61
  }
66
62
  }
67
63
  /**
@@ -81,9 +77,9 @@ function assert(value, message) {
81
77
  * }
82
78
  * ```
83
79
  */
84
- function assertNonNullable(value, message) {
80
+ export function assertNonNullable(value, message) {
85
81
  if (value === null || value === undefined) {
86
- throwError('assertNonNullable', value, message);
82
+ throwUnexpectedValueError('assertNonNullable', value, message);
87
83
  }
88
84
  }
89
85
  /**
@@ -111,7 +107,7 @@ function assertNonNullable(value, message) {
111
107
  * // admin is typed as AdminUser
112
108
  * ```
113
109
  */
114
- function ensure(value, predicate, message) {
110
+ export function ensure(value, predicate, message) {
115
111
  assert(predicate(value), message);
116
112
  return value;
117
113
  }
@@ -135,9 +131,9 @@ function ensure(value, predicate, message) {
135
131
  * const userName = ensureNonNullable(user, 'User not found').name;
136
132
  * ```
137
133
  */
138
- function ensureNonNullable(value, message) {
134
+ export function ensureNonNullable(value, message) {
139
135
  if (value === null || value === undefined) {
140
- throwError('ensureNonNullable', value, message);
136
+ throwUnexpectedValueError('ensureNonNullable', value, message);
141
137
  }
142
138
  return value;
143
139
  }
@@ -163,8 +159,8 @@ function ensureNonNullable(value, message) {
163
159
  * }
164
160
  * ```
165
161
  */
166
- function assertUnreachable(message) {
167
- throwError('assertUnreachable', null, message);
162
+ export function assertUnreachable(message = 'Reached unreachable code') {
163
+ throwError('assertUnreachable', message);
168
164
  }
169
165
  /**
170
166
  * Used for exhaustiveness checking of union types. Ensures switch or if-else statements cover all possible types.
@@ -199,7 +195,24 @@ function assertUnreachable(message) {
199
195
  * }
200
196
  * ```
201
197
  */
202
- function assertExhaustive(value, message) {
203
- throwError('assertExhaustive', value, message);
198
+ export function assertExhaustive(value, message) {
199
+ throwUnexpectedValueError('assertExhaustive', value, message);
200
+ }
201
+ /**
202
+ * Marks methods or code paths that are intentionally not implemented yet.
203
+ *
204
+ * @param message - Optional custom error message
205
+ * @returns Never returns (always throws)
206
+ * @throws {AssertionError} Always thrown.
207
+ *
208
+ * @example
209
+ * ```typescript
210
+ * function saveDraft(): never {
211
+ * return unimplemented('Draft saving is not available yet');
212
+ * }
213
+ * ```
214
+ */
215
+ export function unimplemented(message = 'Not implemented') {
216
+ throwError('unimplemented', message);
204
217
  }
205
218
  //# sourceMappingURL=index.js.map
package/lib/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAqCH,wBAIC;AAmBD,8CAOC;AA2BD,wBAOC;AAsBD,8CAQC;AAwBD,8CAEC;AAmCD,4CAEC;AAhMD;;GAEG;AACH,MAAa,cAAe,SAAQ,KAAK;IAAzC;;QAC2B,SAAI,GAAG,gBAAgB,CAAC;IACnD,CAAC;CAAA;AAFD,wCAEC;AAED;;GAEG;AACH,SAAS,UAAU,CACjB,IAAY,EACZ,KAAc,EACd,OAA2B;IAE3B,MAAM,IAAI,cAAc,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,GAAG,IAAI,gBAAgB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC9E,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;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;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;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;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,iBAAiB,CAAC,OAAgB;IAChD,UAAU,CAAC,mBAAmB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAgB,gBAAgB,CAAC,KAAY,EAAE,OAAgB;IAC7D,UAAU,CAAC,kBAAkB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAAzC;;QAC2B,SAAI,GAAG,gBAAgB,CAAC;IACnD,CAAC;CAAA;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,IAAY,EAAE,OAAe;IAC/C,MAAM,IAAI,cAAc,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB,CAChC,IAAY,EACZ,KAAc,EACd,OAAO,GAAG,cAAc,MAAM,CAAC,KAAK,CAAC,EAAE;IAEvC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,OAAgB;IACrD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,yBAAyB,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAQ,EACR,OAAgB;IAEhB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,yBAAyB,CAAC,mBAAmB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,MAAM,CACpB,KAAQ,EACR,SAAmC,EACnC,OAAgB;IAEhB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAQ,EACR,OAAgB;IAEhB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,yBAAyB,CAAC,mBAAmB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAG,0BAA0B;IACpE,UAAU,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAY,EAAE,OAAgB;IAC7D,yBAAyB,CAAC,kBAAkB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,OAAO,GAAG,iBAAiB;IACvD,UAAU,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rightcapital/assert",
3
- "version": "3.0.1-renovate-auto-merge-dev-dependencies-updates.2473.1.0",
3
+ "version": "4.0.0",
4
4
  "description": "Type-safe assertion utilities for defensive programming.",
5
5
  "keywords": [
6
6
  "assertion",
@@ -19,6 +19,14 @@
19
19
  "license": "MIT",
20
20
  "author": "RightCapital Ecosystem team <npm-publisher@rightcapital.com>",
21
21
  "sideEffects": false,
22
+ "type": "module",
23
+ "exports": {
24
+ ".": {
25
+ "types": "./lib/index.d.ts",
26
+ "default": "./lib/index.js"
27
+ },
28
+ "./package.json": "./package.json"
29
+ },
22
30
  "main": "lib/index.js",
23
31
  "typings": "lib/index.d.ts",
24
32
  "directories": {
@@ -31,12 +39,12 @@
31
39
  ],
32
40
  "devDependencies": {
33
41
  "typedoc": "0.28.20",
34
- "typedoc-plugin-markdown": "4.13.1"
42
+ "typedoc-plugin-markdown": "4.12.0"
35
43
  },
36
44
  "publishConfig": {
37
45
  "registry": "https://registry.npmjs.org"
38
46
  },
39
47
  "scripts": {
40
- "docs": "pnpm exec typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts"
48
+ "docs": "pnpm exec typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.src.json --modulesFileName modules --out docs src/index.ts"
41
49
  }
42
50
  }
package/skills/assert/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: assert
3
3
  description: >-
4
4
  Type-safe assertion and validation utilities for defensive TypeScript programming.
5
- Use when writing runtime assertions, null checks, type guard validations, unreachable code markers, or exhaustive switch/if-else checking.
5
+ Use when writing runtime assertions, null checks, type guard validations, unreachable code markers, exhaustive switch/if-else checking, or unimplemented stubs.
6
6
  Import named functions from @rightcapital/assert.
7
7
  license: MIT
8
8
  metadata:
@@ -12,7 +12,7 @@ metadata:
12
12
 
13
13
  # assert
14
14
 
15
- Type-safe assertion utilities for defensive TypeScript programming. All functions throw `AssertionError` (which extends `Error`) on failure. Default error message format is `${functionName}: Unexpected ${String(value)}`.
15
+ Type-safe assertion utilities for defensive TypeScript programming. All functions throw `AssertionError` (which extends `Error`) on failure. Error messages are formatted as `${functionName}: ${message}`. When no message is provided, value assertions default to `Unexpected ${String(value)}`.
16
16
 
17
17
  ## Import
18
18
 
@@ -25,6 +25,7 @@ import {
25
25
  assertUnreachable,
26
26
  ensure,
27
27
  ensureNonNullable,
28
+ unimplemented,
28
29
  } from '@rightcapital/assert';
29
30
  ```
30
31
 
@@ -39,6 +40,7 @@ import {
39
40
  | `ensureNonNullable<T>(value: T, message?: string): NonNullable<T>` | Inline assignment or method chain for non-null value. |
40
41
  | `assertExhaustive(value: never, message?: string): never` | Exhaustiveness check in `switch` `default` case or `if-else` chain. |
41
42
  | `assertUnreachable(message?: string): never` | Mark logically impossible code paths. |
43
+ | `unimplemented(message?: string): never` | Mark a stub that always throws `AssertionError`. |
42
44
 
43
45
  ## Error Handling with `AssertionError`
44
46
 
package/src/index.ts CHANGED
@@ -26,14 +26,21 @@ export class AssertionError extends Error {
26
26
  }
27
27
 
28
28
  /**
29
- * Throws an AssertionError for failed assertions.
29
+ * Throws an AssertionError with a message prefixed by the assertion name.
30
30
  */
31
- function throwError(
31
+ function throwError(name: string, message: string): never {
32
+ throw new AssertionError(`${name}: ${message}`);
33
+ }
34
+
35
+ /**
36
+ * Throws an AssertionError for an unexpected value.
37
+ */
38
+ function throwUnexpectedValueError(
32
39
  name: string,
33
40
  value: unknown,
34
- message: string | undefined,
41
+ message = `Unexpected ${String(value)}`,
35
42
  ): never {
36
- throw new AssertionError(message ?? `${name}: Unexpected ${String(value)}`);
43
+ throwError(name, message);
37
44
  }
38
45
 
39
46
  /**
@@ -55,7 +62,7 @@ function throwError(
55
62
  */
56
63
  export function assert(value: boolean, message?: string): asserts value {
57
64
  if (value !== true) {
58
- throwError('assert', value, message);
65
+ throwUnexpectedValueError('assert', value, message);
59
66
  }
60
67
  }
61
68
 
@@ -81,7 +88,7 @@ export function assertNonNullable<T>(
81
88
  message?: string,
82
89
  ): asserts value is NonNullable<T> {
83
90
  if (value === null || value === undefined) {
84
- throwError('assertNonNullable', value, message);
91
+ throwUnexpectedValueError('assertNonNullable', value, message);
85
92
  }
86
93
  }
87
94
 
@@ -144,7 +151,7 @@ export function ensureNonNullable<T>(
144
151
  message?: string,
145
152
  ): NonNullable<T> {
146
153
  if (value === null || value === undefined) {
147
- throwError('ensureNonNullable', value, message);
154
+ throwUnexpectedValueError('ensureNonNullable', value, message);
148
155
  }
149
156
  return value;
150
157
  }
@@ -171,8 +178,8 @@ export function ensureNonNullable<T>(
171
178
  * }
172
179
  * ```
173
180
  */
174
- export function assertUnreachable(message?: string): never {
175
- throwError('assertUnreachable', null, message);
181
+ export function assertUnreachable(message = 'Reached unreachable code'): never {
182
+ throwError('assertUnreachable', message);
176
183
  }
177
184
 
178
185
  /**
@@ -209,5 +216,23 @@ export function assertUnreachable(message?: string): never {
209
216
  * ```
210
217
  */
211
218
  export function assertExhaustive(value: never, message?: string): never {
212
- throwError('assertExhaustive', value, message);
219
+ throwUnexpectedValueError('assertExhaustive', value, message);
220
+ }
221
+
222
+ /**
223
+ * Marks methods or code paths that are intentionally not implemented yet.
224
+ *
225
+ * @param message - Optional custom error message
226
+ * @returns Never returns (always throws)
227
+ * @throws {AssertionError} Always thrown.
228
+ *
229
+ * @example
230
+ * ```typescript
231
+ * function saveDraft(): never {
232
+ * return unimplemented('Draft saving is not available yet');
233
+ * }
234
+ * ```
235
+ */
236
+ export function unimplemented(message = 'Not implemented'): never {
237
+ throwError('unimplemented', message);
213
238
  }