@rightcapital/assert 3.0.0 → 3.0.1-feature-assert-unimplemented.2490.1.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 +40 -16
  5. package/lib/index.js.map +1 -1
  6. package/package.json +11 -11
  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
@@ -19,7 +19,14 @@
19
19
  * ```
20
20
  */
21
21
  Object.defineProperty(exports, "__esModule", { value: true });
22
- exports.assertExhaustive = exports.assertUnreachable = exports.ensureNonNullable = exports.ensure = exports.assertNonNullable = exports.assert = exports.AssertionError = void 0;
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
+ exports.unimplemented = unimplemented;
23
30
  /**
24
31
  * Error thrown when an assertion fails.
25
32
  */
@@ -31,10 +38,16 @@ class AssertionError extends Error {
31
38
  }
32
39
  exports.AssertionError = AssertionError;
33
40
  /**
34
- * Throws an AssertionError for failed assertions.
41
+ * Throws an AssertionError with a message prefixed by the assertion name.
42
+ */
43
+ function throwError(name, message) {
44
+ throw new AssertionError(`${name}: ${message}`);
45
+ }
46
+ /**
47
+ * Throws an AssertionError for an unexpected value.
35
48
  */
36
- function throwError(name, value, message) {
37
- throw new AssertionError(message !== null && message !== void 0 ? message : `${name}: Unexpected ${String(value)}`);
49
+ function throwUnexpectedValueError(name, value, message = `Unexpected ${String(value)}`) {
50
+ throwError(name, message);
38
51
  }
39
52
  /**
40
53
  * Basic assertion: verifies that a value or expression is `true`, otherwise throws an exception.
@@ -55,10 +68,9 @@ function throwError(name, value, message) {
55
68
  */
56
69
  function assert(value, message) {
57
70
  if (value !== true) {
58
- throwError('assert', value, message);
71
+ throwUnexpectedValueError('assert', value, message);
59
72
  }
60
73
  }
61
- exports.assert = assert;
62
74
  /**
63
75
  * Asserts that a value is not `null` or `undefined`, providing TypeScript type narrowing to `NonNullable<T>`.
64
76
  * Ensures subsequent code can safely access the value.
@@ -78,10 +90,9 @@ exports.assert = assert;
78
90
  */
79
91
  function assertNonNullable(value, message) {
80
92
  if (value === null || value === undefined) {
81
- throwError('assertNonNullable', value, message);
93
+ throwUnexpectedValueError('assertNonNullable', value, message);
82
94
  }
83
95
  }
84
- exports.assertNonNullable = assertNonNullable;
85
96
  /**
86
97
  * Similar to `assert`, but returns the value. Ensures a value matches a type predicate and returns it with narrowed type.
87
98
  *
@@ -111,7 +122,6 @@ function ensure(value, predicate, message) {
111
122
  assert(predicate(value), message);
112
123
  return value;
113
124
  }
114
- exports.ensure = ensure;
115
125
  /**
116
126
  * Similar to `assertNonNullable`, but returns the value. Ensures a value is not null/undefined and returns it.
117
127
  *
@@ -134,11 +144,10 @@ exports.ensure = ensure;
134
144
  */
135
145
  function ensureNonNullable(value, message) {
136
146
  if (value === null || value === undefined) {
137
- throwError('ensureNonNullable', value, message);
147
+ throwUnexpectedValueError('ensureNonNullable', value, message);
138
148
  }
139
149
  return value;
140
150
  }
141
- exports.ensureNonNullable = ensureNonNullable;
142
151
  /**
143
152
  * Marks code branches that should theoretically never be reached.
144
153
  * Used for defensive programming to prevent unexpected code execution when data or logic doesn't match expectations.
@@ -161,10 +170,9 @@ exports.ensureNonNullable = ensureNonNullable;
161
170
  * }
162
171
  * ```
163
172
  */
164
- function assertUnreachable(message) {
165
- throwError('assertUnreachable', null, message);
173
+ function assertUnreachable(message = 'Reached unreachable code') {
174
+ throwError('assertUnreachable', message);
166
175
  }
167
- exports.assertUnreachable = assertUnreachable;
168
176
  /**
169
177
  * Used for exhaustiveness checking of union types. Ensures switch or if-else statements cover all possible types.
170
178
  * Leverages TypeScript's `never` type to catch missing branches at compile time.
@@ -199,7 +207,23 @@ exports.assertUnreachable = assertUnreachable;
199
207
  * ```
200
208
  */
201
209
  function assertExhaustive(value, message) {
202
- throwError('assertExhaustive', value, message);
210
+ throwUnexpectedValueError('assertExhaustive', value, message);
211
+ }
212
+ /**
213
+ * Marks methods or code paths that are intentionally not implemented yet.
214
+ *
215
+ * @param message - Optional custom error message
216
+ * @returns Never returns (always throws)
217
+ * @throws {AssertionError} Always thrown.
218
+ *
219
+ * @example
220
+ * ```typescript
221
+ * function saveDraft(): never {
222
+ * return unimplemented('Draft saving is not available yet');
223
+ * }
224
+ * ```
225
+ */
226
+ function unimplemented(message = 'Not implemented') {
227
+ throwError('unimplemented', message);
203
228
  }
204
- exports.assertExhaustive = assertExhaustive;
205
229
  //# 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;;;AAEH;;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;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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AA4CH,wBAIC;AAmBD,8CAOC;AA2BD,wBAOC;AAsBD,8CAQC;AAwBD,8CAEC;AAmCD,4CAEC;AAgBD,sCAEC;AAzND;;GAEG;AACH,MAAa,cAAe,SAAQ,KAAK;IAAzC;;QAC2B,SAAI,GAAG,gBAAgB,CAAC;IACnD,CAAC;CAAA;AAFD,wCAEC;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,SAAgB,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,SAAgB,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,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,yBAAyB,CAAC,mBAAmB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,iBAAiB,CAAC,OAAO,GAAG,0BAA0B;IACpE,UAAU,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAgB,gBAAgB,CAAC,KAAY,EAAE,OAAgB;IAC7D,yBAAyB,CAAC,kBAAkB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,aAAa,CAAC,OAAO,GAAG,iBAAiB;IACvD,UAAU,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC"}
package/package.json CHANGED
@@ -1,8 +1,7 @@
1
1
  {
2
2
  "name": "@rightcapital/assert",
3
- "version": "3.0.0",
3
+ "version": "3.0.1-feature-assert-unimplemented.2490.1.0",
4
4
  "description": "Type-safe assertion utilities for defensive programming.",
5
- "author": "RightCapital Ecosystem team <npm-publisher@rightcapital.com>",
6
5
  "keywords": [
7
6
  "assertion",
8
7
  "type-safe",
@@ -12,15 +11,16 @@
12
11
  "tanstack-intent",
13
12
  "utilities"
14
13
  ],
15
- "sideEffects": false,
16
- "license": "MIT",
17
- "main": "lib/index.js",
18
- "typings": "lib/index.d.ts",
19
14
  "repository": {
20
15
  "type": "git",
21
16
  "url": "git+https://github.com/RightCapitalHQ/frontend-libraries.git",
22
17
  "directory": "packages/assert"
23
18
  },
19
+ "license": "MIT",
20
+ "author": "RightCapital Ecosystem team <npm-publisher@rightcapital.com>",
21
+ "sideEffects": false,
22
+ "main": "lib/index.js",
23
+ "typings": "lib/index.d.ts",
24
24
  "directories": {
25
25
  "lib": "lib"
26
26
  },
@@ -29,14 +29,14 @@
29
29
  "skills",
30
30
  "src"
31
31
  ],
32
+ "devDependencies": {
33
+ "typedoc": "0.28.20",
34
+ "typedoc-plugin-markdown": "4.12.0"
35
+ },
32
36
  "publishConfig": {
33
37
  "registry": "https://registry.npmjs.org"
34
38
  },
35
- "devDependencies": {
36
- "typedoc": "0.25.7",
37
- "typedoc-plugin-markdown": "3.17.1"
38
- },
39
39
  "scripts": {
40
- "docs": "pnpm exec typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts"
40
+ "docs": "pnpm exec typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.lib.json --modulesFileName modules --out docs src/index.ts"
41
41
  }
42
42
  }
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
  }