@xylabs/assert 4.13.21 → 4.13.23

package/README.md

@@ -15,17 +15,12 @@
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
-## API Documentation
+## Reference
 
 **@xylabs/assert**
 
 ***
 
-## Type Aliases
-
-- [AssertExMessageFunc](#type-aliases/AssertExMessageFunc)
-- [AssertExErrorFunc](#type-aliases/AssertExErrorFunc)
-
 ## Functions
 
 - [assertDefinedEx](#functions/assertDefinedEx)
@@ -39,13 +34,16 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+Implementation of assertDefinedEx that handles all overloads.
+
 ## Call Signature
 
 ```ts
 function assertDefinedEx<T>(expr, messageFunc?): T;
 ```
 
-Intended for defined checks for variables
+Asserts that a value is defined (not undefined) and returns the value.
+Throws an error if the value is undefined.
 
 ### Type Parameters
 
@@ -53,27 +51,43 @@ Intended for defined checks for variables
 
 `T`
 
+The type of value to check
+
 ### Parameters
 
 ### expr
 
-Expression to be evaluated for truthiness
+Expression to be evaluated for being defined
 
 `undefined` | `T`
 
 ### messageFunc?
 
-[`AssertExMessageFunc`](#../type-aliases/AssertExMessageFunc)\<`T`\>
+`AssertExMessageFunc`\<`T`\>
+
+Function that returns a message for the error if expression is undefined
 
 ### Returns
 
 `T`
 
-Value of expression
+The value of the expression (guaranteed to be defined)
 
 ### Throws
 
-AssertExError
+Error with the message returned by messageFunc
+
+### Example
+
+```typescript
+// Simple usage with a message function
+const value = assertDefinedEx(possiblyUndefined, () => 'Value must be defined')
+
+// Using with type narrowing
+const config: Config | undefined = loadConfig()
+const safeConfig = assertDefinedEx(config, () => 'Config failed to load')
+// safeConfig is now type Config (not Config | undefined)
+```
 
 ## Call Signature
 
@@ -81,7 +95,8 @@ AssertExError
 function assertDefinedEx<T, R>(expr, errorFunc?): T;
 ```
 
-Intended for defined checks for variables
+Asserts that a value is defined (not undefined) and returns the value.
+Throws a custom error if the value is undefined.
 
 ### Type Parameters
 
@@ -89,31 +104,44 @@ Intended for defined checks for variables
 
 `T`
 
+The type of value to check
+
 ### R
 
 `R` *extends* `Error`
 
+The type of error to throw
+
 ### Parameters
 
 ### expr
 
-Expression to be evaluated for truthiness
+Expression to be evaluated for being defined
 
 `undefined` | `T`
 
 ### errorFunc?
 
-[`AssertExErrorFunc`](#../type-aliases/AssertExErrorFunc)\<`T`, `R`\>
+`AssertExErrorFunc`\<`T`, `R`\>
+
+Function that returns a custom error instance if expression is undefined
 
 ### Returns
 
 `T`
 
-Value of expression
+The value of the expression (guaranteed to be defined)
 
 ### Throws
 
-AssertExError
+Custom error returned by errorFunc
+
+### Example
+
+```typescript
+// Using with a custom error
+const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))
+```
 
 ## Call Signature
 
@@ -121,25 +149,38 @@ AssertExError
 function assertDefinedEx<T>(expr): T;
 ```
 
+Asserts that a value is defined (not undefined) and returns the value.
+Throws an error if the value is undefined.
+
 ### Type Parameters
 
 ### T
 
 `T`
 
+The type of value to check
+
 ### Parameters
 
 ### expr
 
+Expression to be evaluated for being defined
+
 `undefined` | `T`
 
 ### Returns
 
 `T`
 
+The value of the expression (guaranteed to be defined)
+
 ### Deprecated
 
-- passing a message will soon be required
+Use overload with message function instead - passing a message will soon be required
+
+### Throws
+
+Error with a generic message
 
 ## Call Signature
 
@@ -147,29 +188,44 @@ function assertDefinedEx<T>(expr): T;
 function assertDefinedEx<T>(expr, message?): T;
 ```
 
+Asserts that a value is defined (not undefined) and returns the value.
+Throws an error with the provided message if the value is undefined.
+
 ### Type Parameters
 
 ### T
 
 `T`
 
+The type of value to check
+
 ### Parameters
 
 ### expr
 
+Expression to be evaluated for being defined
+
 `undefined` | `T`
 
 ### message?
 
 `string`
 
+Error message if expression is undefined
+
 ### Returns
 
 `T`
 
+The value of the expression (guaranteed to be defined)
+
 ### Deprecated
 
-- replace string with () => string
+Replace string with () => string for consistency
+
+### Throws
+
+Error with the provided message
 
   ### <a id="assertEx"></a>assertEx
 
@@ -177,13 +233,16 @@ function assertDefinedEx<T>(expr, message?): T;
 
 ***
 
+Implementation of assertEx that handles all overloads.
+
 ## Call Signature
 
 ```ts
 function assertEx<T>(expr, messageFunc?): T;
 ```
 
-Intended for simple truthiness checks for variables
+Asserts that an expression is truthy and returns the value.
+Throws an error if the expression is falsy.
 
 ### Type Parameters
 
@@ -191,6 +250,8 @@ Intended for simple truthiness checks for variables
 
 `T`
 
+The type of value to check
+
 ### Parameters
 
 ### expr
@@ -201,17 +262,31 @@ Expression to be evaluated for truthiness
 
 ### messageFunc?
 
-[`AssertExMessageFunc`](#../type-aliases/AssertExMessageFunc)\<`T`\>
+`AssertExMessageFunc`\<`T`\>
+
+Function that returns a message for the error if expression is falsy
 
 ### Returns
 
 `T`
 
-Value of expression
+The value of the expression (guaranteed to be truthy)
 
 ### Throws
 
-AssertExError
+Error with the message returned by messageFunc
+
+### Example
+
+```typescript
+// Simple usage with a message function
+const value = assertEx(possiblyFalsy, () => 'Value must be truthy')
+
+// Using with type narrowing
+const config: Config | null = loadConfig()
+const safeConfig = assertEx(config, () => 'Config failed to load')
+// safeConfig is now type Config (not Config | null)
+```
 
 ## Call Signature
 
@@ -219,7 +294,8 @@ AssertExError
 function assertEx<T, R>(expr, errorFunc?): T;
 ```
 
-Intended for simple truthiness checks for variables
+Asserts that an expression is truthy and returns the value.
+Throws a custom error if the expression is falsy.
 
 ### Type Parameters
 
@@ -227,10 +303,14 @@ Intended for simple truthiness checks for variables
 
 `T`
 
+The type of value to check
+
 ### R
 
 `R` *extends* `Error`
 
+The type of error to throw
+
 ### Parameters
 
 ### expr
@@ -241,17 +321,26 @@ Expression to be evaluated for truthiness
 
 ### errorFunc?
 
-[`AssertExErrorFunc`](#../type-aliases/AssertExErrorFunc)\<`T`, `R`\>
+`AssertExErrorFunc`\<`T`, `R`\>
+
+Function that returns a custom error instance if expression is falsy
 
 ### Returns
 
 `T`
 
-Value of expression
+The value of the expression (guaranteed to be truthy)
 
 ### Throws
 
-AssertExError
+Custom error returned by errorFunc
+
+### Example
+
+```typescript
+// Using with a custom error
+const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))
+```
 
 ## Call Signature
 
@@ -259,25 +348,38 @@ AssertExError
 function assertEx<T>(expr): T;
 ```
 
+Asserts that an expression is truthy and returns the value.
+Throws an error if the expression is falsy.
+
 ### Type Parameters
 
 ### T
 
 `T`
 
+The type of value to check
+
 ### Parameters
 
 ### expr
 
+Expression to be evaluated for truthiness
+
 `undefined` | `null` | `T`
 
 ### Returns
 
 `T`
 
+The value of the expression (guaranteed to be truthy)
+
 ### Deprecated
 
-- passing a message will soon be required
+Use overload with message function instead - passing a message will soon be required
+
+### Throws
+
+Error with a generic message
 
 ## Call Signature
 
@@ -285,87 +387,44 @@ function assertEx<T>(expr): T;
 function assertEx<T>(expr, message?): T;
 ```
 
+Asserts that an expression is truthy and returns the value.
+Throws an error with the provided message if the expression is falsy.
+
 ### Type Parameters
 
 ### T
 
 `T`
 
+The type of value to check
+
 ### Parameters
 
 ### expr
 
+Expression to be evaluated for truthiness
+
 `undefined` | `null` | `T`
 
 ### message?
 
 `string`
 
-### Returns
-
-`T`
-
-### Deprecated
-
-- replace string with () => string
-
-### type-aliases
-
-  ### <a id="AssertExErrorFunc"></a>AssertExErrorFunc
-
-[**@xylabs/assert**](#../README)
-
-***
-
-```ts
-type AssertExErrorFunc<T, R> = (value?) => R;
-```
-
-## Type Parameters
-
-### T
-
-`T`
-
-### R
-
-`R` *extends* `Error`
-
-## Parameters
+Error message if expression is falsy
 
-### value?
-
-`T` | `null`
-
-## Returns
-
-`R`
-
-  ### <a id="AssertExMessageFunc"></a>AssertExMessageFunc
-
-[**@xylabs/assert**](#../README)
-
-***
-
-```ts
-type AssertExMessageFunc<T> = (value?) => string;
-```
-
-## Type Parameters
-
-### T
+### Returns
 
 `T`
 
-## Parameters
+The value of the expression (guaranteed to be truthy)
 
-### value?
+### Deprecated
 
-`T` | `null`
+Replace string with () => string for consistency
 
-## Returns
+### Throws
 
-`string`
+Error with the provided message
 
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)

package/dist/neutral/assertDefinedEx.d.ts

@@ -1,21 +1,63 @@
 import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts';
 /**
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error if the value is undefined.
  *
- * Intended for defined checks for variables
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @param messageFunc - Function that returns a message for the error if expression is undefined
+ * @throws Error with the message returned by messageFunc
+ * @returns The value of the expression (guaranteed to be defined)
+ * @example
+ * ```typescript
+ * // Simple usage with a message function
+ * const value = assertDefinedEx(possiblyUndefined, () => 'Value must be defined')
  *
- * @param expr - Expression to be evaluated for truthiness
- * @param message - Message in Error if expression is false, may be a function that returns a string
- * @throws AssertExError
- * @returns Value of expression
+ * // Using with type narrowing
+ * const config: Config | undefined = loadConfig()
+ * const safeConfig = assertDefinedEx(config, () => 'Config failed to load')
+ * // safeConfig is now type Config (not Config | undefined)
+ * ```
  */
 declare function assertDefinedEx<T>(expr: T | undefined, messageFunc?: AssertExMessageFunc<T>): T;
+/**
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws a custom error if the value is undefined.
+ *
+ * @template T - The type of value to check
+ * @template R - The type of error to throw
+ * @param expr - Expression to be evaluated for being defined
+ * @param errorFunc - Function that returns a custom error instance if expression is undefined
+ * @throws Custom error returned by errorFunc
+ * @returns The value of the expression (guaranteed to be defined)
+ * @example
+ * ```typescript
+ * // Using with a custom error
+ * const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))
+ * ```
+ */
 declare function assertDefinedEx<T, R extends Error>(expr: T | undefined, errorFunc?: AssertExErrorFunc<T, R>): T;
 /**
- * @deprecated - passing a message will soon be required
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error if the value is undefined.
+ *
+ * @deprecated Use overload with message function instead - passing a message will soon be required
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @throws Error with a generic message
+ * @returns The value of the expression (guaranteed to be defined)
  */
 declare function assertDefinedEx<T>(expr: T | undefined): T;
 /**
- * @deprecated - replace string with () => string
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error with the provided message if the value is undefined.
+ *
+ * @deprecated Replace string with () => string for consistency
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @param message - Error message if expression is undefined
+ * @throws Error with the provided message
+ * @returns The value of the expression (guaranteed to be defined)
  */
 declare function assertDefinedEx<T>(expr: T | undefined, message?: string): T;
 export { assertDefinedEx };

package/dist/neutral/assertDefinedEx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertDefinedEx.d.ts","sourceRoot":"","sources":["../../src/assertDefinedEx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAExE;;;;;;;;GAQG;AAEH,iBAAS,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AACzF,iBAAS,eAAe,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,SAAS,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;AACzG;;GAEG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,GAAG,CAAC,CAAA;AACnD;;GAEG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;AAcrE,OAAO,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"assertDefinedEx.d.ts","sourceRoot":"","sources":["../../src/assertDefinedEx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAEzF;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,SAAS,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;AAEzG;;;;;;;;;GASG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,GAAG,CAAC,CAAA;AAEnD;;;;;;;;;;GAUG;AACH,iBAAS,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;AAmBrE,OAAO,EAAE,eAAe,EAAE,CAAA"}

package/dist/neutral/assertEx.d.ts

@@ -1,21 +1,63 @@
 import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts';
 /**
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error if the expression is falsy.
  *
- * Intended for simple truthiness checks for variables
- *
+ * @template T - The type of value to check
  * @param expr - Expression to be evaluated for truthiness
- * @param message - Message in Error if expression is false, may be a function that returns a string
- * @throws AssertExError
- * @returns Value of expression
+ * @param messageFunc - Function that returns a message for the error if expression is falsy
+ * @throws Error with the message returned by messageFunc
+ * @returns The value of the expression (guaranteed to be truthy)
+ * @example
+ * ```typescript
+ * // Simple usage with a message function
+ * const value = assertEx(possiblyFalsy, () => 'Value must be truthy')
+ *
+ * // Using with type narrowing
+ * const config: Config | null = loadConfig()
+ * const safeConfig = assertEx(config, () => 'Config failed to load')
+ * // safeConfig is now type Config (not Config | null)
+ * ```
  */
 declare function assertEx<T>(expr: T | null | undefined, messageFunc?: AssertExMessageFunc<T>): T;
+/**
+ * Asserts that an expression is truthy and returns the value.
+ * Throws a custom error if the expression is falsy.
+ *
+ * @template T - The type of value to check
+ * @template R - The type of error to throw
+ * @param expr - Expression to be evaluated for truthiness
+ * @param errorFunc - Function that returns a custom error instance if expression is falsy
+ * @throws Custom error returned by errorFunc
+ * @returns The value of the expression (guaranteed to be truthy)
+ * @example
+ * ```typescript
+ * // Using with a custom error
+ * const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))
+ * ```
+ */
 declare function assertEx<T, R extends Error>(expr: T | null | undefined, errorFunc?: AssertExErrorFunc<T, R>): T;
 /**
- * @deprecated - passing a message will soon be required
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error if the expression is falsy.
+ *
+ * @deprecated Use overload with message function instead - passing a message will soon be required
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for truthiness
+ * @throws Error with a generic message
+ * @returns The value of the expression (guaranteed to be truthy)
  */
 declare function assertEx<T>(expr: T | null | undefined): T;
 /**
- * @deprecated - replace string with () => string
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error with the provided message if the expression is falsy.
+ *
+ * @deprecated Replace string with () => string for consistency
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for truthiness
+ * @param message - Error message if expression is falsy
+ * @throws Error with the provided message
+ * @returns The value of the expression (guaranteed to be truthy)
  */
 declare function assertEx<T>(expr: T | null | undefined, message?: string): T;
 export { assertEx };

package/dist/neutral/assertEx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertEx.d.ts","sourceRoot":"","sources":["../../src/assertEx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAExE;;;;;;;;GAQG;AAEH,iBAAS,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AACzF,iBAAS,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;AACzG;;GAEG;AACH,iBAAS,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,CAAA;AACnD;;GAEG;AACH,iBAAS,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;AAerE,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"assertEx.d.ts","sourceRoot":"","sources":["../../src/assertEx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAEzF;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAA;AAEzG;;;;;;;;;GASG;AACH,iBAAS,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,CAAA;AAEnD;;;;;;;;;;GAUG;AACH,iBAAS,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAA;AAmBrE,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/neutral/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/assertDefinedEx.ts","../../src/assertEx.ts"],"sourcesContent":["import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts'\n\n/**\n *\n * Intended for defined checks for variables\n *\n * @param expr - Expression to be evaluated for truthiness\n * @param message - Message in Error if expression is false, may be a function that returns a string\n * @throws AssertExError\n * @returns Value of expression\n */\n\nfunction assertDefinedEx<T>(expr: T | undefined, messageFunc?: AssertExMessageFunc<T>): T\nfunction assertDefinedEx<T, R extends Error>(expr: T | undefined, errorFunc?: AssertExErrorFunc<T, R>): T\n/**\n * @deprecated - passing a message will soon be required\n */\nfunction assertDefinedEx<T>(expr: T | undefined): T\n/**\n * @deprecated - replace string with () => string\n */\nfunction assertDefinedEx<T>(expr: T | undefined, message?: string): T\nfunction assertDefinedEx<T, R extends Error, P extends string | AssertExMessageFunc<T> | AssertExErrorFunc<T, R>>(\n  expr: T | undefined,\n  messageOrFunc?: P,\n): T {\n  if (expr !== undefined) return expr\n  if (typeof messageOrFunc === 'function') {\n    const errorOrMessage = messageOrFunc(expr)\n    throw typeof errorOrMessage === 'string' ? new Error(errorOrMessage) : errorOrMessage\n  }\n  // a string was sent\n  throw new Error(messageOrFunc)\n}\n\nexport { assertDefinedEx }\n","import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts'\n\n/**\n *\n * Intended for simple truthiness checks for variables\n *\n * @param expr - Expression to be evaluated for truthiness\n * @param message - Message in Error if expression is false, may be a function that returns a string\n * @throws AssertExError\n * @returns Value of expression\n */\n\nfunction assertEx<T>(expr: T | null | undefined, messageFunc?: AssertExMessageFunc<T>): T\nfunction assertEx<T, R extends Error>(expr: T | null | undefined, errorFunc?: AssertExErrorFunc<T, R>): T\n/**\n * @deprecated - passing a message will soon be required\n */\nfunction assertEx<T>(expr: T | null | undefined): T\n/**\n * @deprecated - replace string with () => string\n */\nfunction assertEx<T>(expr: T | null | undefined, message?: string): T\nfunction assertEx<T, R extends Error, P extends string | AssertExMessageFunc<T> | AssertExErrorFunc<T, R>>(\n  expr: T | null | undefined,\n  messageOrFunc?: P,\n): T {\n  // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions\n  if (expr) return expr\n  if (typeof messageOrFunc === 'function') {\n    const errorOrMessage = messageOrFunc(expr)\n    throw typeof errorOrMessage === 'string' ? new Error(errorOrMessage) : errorOrMessage\n  }\n  // a string was sent\n  throw new Error(messageOrFunc)\n}\n\nexport { assertEx }\n"],"mappings":";AAsBA,SAAS,gBACP,MACA,eACG;AACH,MAAI,SAAS,OAAW,QAAO;AAC/B,MAAI,OAAO,kBAAkB,YAAY;AACvC,UAAM,iBAAiB,cAAc,IAAI;AACzC,UAAM,OAAO,mBAAmB,WAAW,IAAI,MAAM,cAAc,IAAI;AAAA,EACzE;AAEA,QAAM,IAAI,MAAM,aAAa;AAC/B;;;ACXA,SAAS,SACP,MACA,eACG;AAEH,MAAI,KAAM,QAAO;AACjB,MAAI,OAAO,kBAAkB,YAAY;AACvC,UAAM,iBAAiB,cAAc,IAAI;AACzC,UAAM,OAAO,mBAAmB,WAAW,IAAI,MAAM,cAAc,IAAI;AAAA,EACzE;AAEA,QAAM,IAAI,MAAM,aAAa;AAC/B;","names":[]}
+{"version":3,"sources":["../../src/assertDefinedEx.ts","../../src/assertEx.ts"],"sourcesContent":["import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts'\n\n/**\n * Asserts that a value is defined (not undefined) and returns the value.\n * Throws an error if the value is undefined.\n *\n * @template T - The type of value to check\n * @param expr - Expression to be evaluated for being defined\n * @param messageFunc - Function that returns a message for the error if expression is undefined\n * @throws Error with the message returned by messageFunc\n * @returns The value of the expression (guaranteed to be defined)\n * @example\n * ```typescript\n * // Simple usage with a message function\n * const value = assertDefinedEx(possiblyUndefined, () => 'Value must be defined')\n *\n * // Using with type narrowing\n * const config: Config | undefined = loadConfig()\n * const safeConfig = assertDefinedEx(config, () => 'Config failed to load')\n * // safeConfig is now type Config (not Config | undefined)\n * ```\n */\nfunction assertDefinedEx<T>(expr: T | undefined, messageFunc?: AssertExMessageFunc<T>): T\n\n/**\n * Asserts that a value is defined (not undefined) and returns the value.\n * Throws a custom error if the value is undefined.\n *\n * @template T - The type of value to check\n * @template R - The type of error to throw\n * @param expr - Expression to be evaluated for being defined\n * @param errorFunc - Function that returns a custom error instance if expression is undefined\n * @throws Custom error returned by errorFunc\n * @returns The value of the expression (guaranteed to be defined)\n * @example\n * ```typescript\n * // Using with a custom error\n * const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))\n * ```\n */\nfunction assertDefinedEx<T, R extends Error>(expr: T | undefined, errorFunc?: AssertExErrorFunc<T, R>): T\n\n/**\n * Asserts that a value is defined (not undefined) and returns the value.\n * Throws an error if the value is undefined.\n *\n * @deprecated Use overload with message function instead - passing a message will soon be required\n * @template T - The type of value to check\n * @param expr - Expression to be evaluated for being defined\n * @throws Error with a generic message\n * @returns The value of the expression (guaranteed to be defined)\n */\nfunction assertDefinedEx<T>(expr: T | undefined): T\n\n/**\n * Asserts that a value is defined (not undefined) and returns the value.\n * Throws an error with the provided message if the value is undefined.\n *\n * @deprecated Replace string with () => string for consistency\n * @template T - The type of value to check\n * @param expr - Expression to be evaluated for being defined\n * @param message - Error message if expression is undefined\n * @throws Error with the provided message\n * @returns The value of the expression (guaranteed to be defined)\n */\nfunction assertDefinedEx<T>(expr: T | undefined, message?: string): T\n\n/**\n * Implementation of assertDefinedEx that handles all overloads.\n *\n */\nfunction assertDefinedEx<T, R extends Error, P extends string | AssertExMessageFunc<T> | AssertExErrorFunc<T, R>>(\n  expr: T | undefined,\n  messageOrFunc?: P,\n): T {\n  if (expr !== undefined) return expr\n  if (typeof messageOrFunc === 'function') {\n    const errorOrMessage = messageOrFunc(expr)\n    throw typeof errorOrMessage === 'string' ? new Error(errorOrMessage) : errorOrMessage\n  }\n  // a string was sent\n  throw new Error(messageOrFunc)\n}\n\nexport { assertDefinedEx }\n","import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts'\n\n/**\n * Asserts that an expression is truthy and returns the value.\n * Throws an error if the expression is falsy.\n *\n * @template T - The type of value to check\n * @param expr - Expression to be evaluated for truthiness\n * @param messageFunc - Function that returns a message for the error if expression is falsy\n * @throws Error with the message returned by messageFunc\n * @returns The value of the expression (guaranteed to be truthy)\n * @example\n * ```typescript\n * // Simple usage with a message function\n * const value = assertEx(possiblyFalsy, () => 'Value must be truthy')\n *\n * // Using with type narrowing\n * const config: Config | null = loadConfig()\n * const safeConfig = assertEx(config, () => 'Config failed to load')\n * // safeConfig is now type Config (not Config | null)\n * ```\n */\nfunction assertEx<T>(expr: T | null | undefined, messageFunc?: AssertExMessageFunc<T>): T\n\n/**\n * Asserts that an expression is truthy and returns the value.\n * Throws a custom error if the expression is falsy.\n *\n * @template T - The type of value to check\n * @template R - The type of error to throw\n * @param expr - Expression to be evaluated for truthiness\n * @param errorFunc - Function that returns a custom error instance if expression is falsy\n * @throws Custom error returned by errorFunc\n * @returns The value of the expression (guaranteed to be truthy)\n * @example\n * ```typescript\n * // Using with a custom error\n * const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))\n * ```\n */\nfunction assertEx<T, R extends Error>(expr: T | null | undefined, errorFunc?: AssertExErrorFunc<T, R>): T\n\n/**\n * Asserts that an expression is truthy and returns the value.\n * Throws an error if the expression is falsy.\n *\n * @deprecated Use overload with message function instead - passing a message will soon be required\n * @template T - The type of value to check\n * @param expr - Expression to be evaluated for truthiness\n * @throws Error with a generic message\n * @returns The value of the expression (guaranteed to be truthy)\n */\nfunction assertEx<T>(expr: T | null | undefined): T\n\n/**\n * Asserts that an expression is truthy and returns the value.\n * Throws an error with the provided message if the expression is falsy.\n *\n * @deprecated Replace string with () => string for consistency\n * @template T - The type of value to check\n * @param expr - Expression to be evaluated for truthiness\n * @param message - Error message if expression is falsy\n * @throws Error with the provided message\n * @returns The value of the expression (guaranteed to be truthy)\n */\nfunction assertEx<T>(expr: T | null | undefined, message?: string): T\n\n/**\n * Implementation of assertEx that handles all overloads.\n */\nfunction assertEx<T, R extends Error, P extends string | AssertExMessageFunc<T> | AssertExErrorFunc<T, R>>(\n  expr: T | null | undefined,\n  messageOrFunc?: P,\n): T {\n  // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions\n  if (expr) return expr\n  if (typeof messageOrFunc === 'function') {\n    const errorOrMessage = messageOrFunc(expr)\n    throw typeof errorOrMessage === 'string' ? new Error(errorOrMessage) : errorOrMessage\n  }\n  // a string was sent\n  throw new Error(messageOrFunc)\n}\n\nexport { assertEx }\n"],"mappings":";AAuEA,SAAS,gBACP,MACA,eACG;AACH,MAAI,SAAS,OAAW,QAAO;AAC/B,MAAI,OAAO,kBAAkB,YAAY;AACvC,UAAM,iBAAiB,cAAc,IAAI;AACzC,UAAM,OAAO,mBAAmB,WAAW,IAAI,MAAM,cAAc,IAAI;AAAA,EACzE;AAEA,QAAM,IAAI,MAAM,aAAa;AAC/B;;;ACZA,SAAS,SACP,MACA,eACG;AAEH,MAAI,KAAM,QAAO;AACjB,MAAI,OAAO,kBAAkB,YAAY;AACvC,UAAM,iBAAiB,cAAc,IAAI;AACzC,UAAM,OAAO,mBAAmB,WAAW,IAAI,MAAM,cAAc,IAAI;AAAA,EACzE;AAEA,QAAM,IAAI,MAAM,aAAa;AAC/B;","names":[]}

package/dist/neutral/types.d.ts

@@ -1,3 +1,36 @@
+/**
+ * @internal
+ * A function that takes a possibly null or undefined value and returns an error message string.
+ * Used in assertion functions to provide custom error messages.
+ *
+ * @internal
+ * @template T - The type of value being asserted
+ * @param value - The value being asserted (may be null or undefined)
+ * @returns A string message to be used in the error thrown by the assertion
+ * @example
+ * ```typescript
+ * const messageFunc: AssertExMessageFunc<User> = (user) =>
+ *   `User ${user ? user.id : 'unknown'} is not valid or accessible`
+ * ```
+ */
 export type AssertExMessageFunc<T> = (value?: T | null) => string;
+/**
+ * A function that takes a possibly null or undefined value and returns a custom error instance.
+ * Used in assertion functions to provide specific error types with custom properties.
+ *
+ * @internal
+ * @template T - The type of value being asserted
+ * @template R - The specific error type to be returned, must extend Error
+ * @param value - The value being asserted (may be null or undefined)
+ * @returns An instance of the custom error type
+ * @example
+ * ```typescript
+ * const errorFunc: AssertExErrorFunc<User, UserNotFoundError> = (user) =>
+ *   new UserNotFoundError(`User ${user?.id || 'unknown'} not found`, {
+ *     userId: user?.id,
+ *     timestamp: new Date()
+ *   })
+ * ```
+ */
 export type AssertExErrorFunc<T, R extends Error> = (value?: T | null) => R;
 //# sourceMappingURL=types.d.ts.map

package/dist/neutral/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,KAAK,MAAM,CAAA;AACjE,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,KAAK,MAAM,CAAA;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/assert",
-  "version": "4.13.21",
+  "version": "4.13.23",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "xylabs",

package/src/assertDefinedEx.ts

@@ -1,25 +1,74 @@
 import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts'
 
 /**
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error if the value is undefined.
  *
- * Intended for defined checks for variables
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @param messageFunc - Function that returns a message for the error if expression is undefined
+ * @throws Error with the message returned by messageFunc
+ * @returns The value of the expression (guaranteed to be defined)
+ * @example
+ * ```typescript
+ * // Simple usage with a message function
+ * const value = assertDefinedEx(possiblyUndefined, () => 'Value must be defined')
  *
- * @param expr - Expression to be evaluated for truthiness
- * @param message - Message in Error if expression is false, may be a function that returns a string
- * @throws AssertExError
- * @returns Value of expression
+ * // Using with type narrowing
+ * const config: Config | undefined = loadConfig()
+ * const safeConfig = assertDefinedEx(config, () => 'Config failed to load')
+ * // safeConfig is now type Config (not Config | undefined)
+ * ```
  */
-
 function assertDefinedEx<T>(expr: T | undefined, messageFunc?: AssertExMessageFunc<T>): T
+
+/**
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws a custom error if the value is undefined.
+ *
+ * @template T - The type of value to check
+ * @template R - The type of error to throw
+ * @param expr - Expression to be evaluated for being defined
+ * @param errorFunc - Function that returns a custom error instance if expression is undefined
+ * @throws Custom error returned by errorFunc
+ * @returns The value of the expression (guaranteed to be defined)
+ * @example
+ * ```typescript
+ * // Using with a custom error
+ * const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))
+ * ```
+ */
 function assertDefinedEx<T, R extends Error>(expr: T | undefined, errorFunc?: AssertExErrorFunc<T, R>): T
+
 /**
- * @deprecated - passing a message will soon be required
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error if the value is undefined.
+ *
+ * @deprecated Use overload with message function instead - passing a message will soon be required
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @throws Error with a generic message
+ * @returns The value of the expression (guaranteed to be defined)
  */
 function assertDefinedEx<T>(expr: T | undefined): T
+
 /**
- * @deprecated - replace string with () => string
+ * Asserts that a value is defined (not undefined) and returns the value.
+ * Throws an error with the provided message if the value is undefined.
+ *
+ * @deprecated Replace string with () => string for consistency
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for being defined
+ * @param message - Error message if expression is undefined
+ * @throws Error with the provided message
+ * @returns The value of the expression (guaranteed to be defined)
  */
 function assertDefinedEx<T>(expr: T | undefined, message?: string): T
+
+/**
+ * Implementation of assertDefinedEx that handles all overloads.
+ *
+ */
 function assertDefinedEx<T, R extends Error, P extends string | AssertExMessageFunc<T> | AssertExErrorFunc<T, R>>(
   expr: T | undefined,
   messageOrFunc?: P,

package/src/assertEx.ts

@@ -1,25 +1,73 @@
 import type { AssertExErrorFunc, AssertExMessageFunc } from './types.ts'
 
 /**
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error if the expression is falsy.
  *
- * Intended for simple truthiness checks for variables
- *
+ * @template T - The type of value to check
  * @param expr - Expression to be evaluated for truthiness
- * @param message - Message in Error if expression is false, may be a function that returns a string
- * @throws AssertExError
- * @returns Value of expression
+ * @param messageFunc - Function that returns a message for the error if expression is falsy
+ * @throws Error with the message returned by messageFunc
+ * @returns The value of the expression (guaranteed to be truthy)
+ * @example
+ * ```typescript
+ * // Simple usage with a message function
+ * const value = assertEx(possiblyFalsy, () => 'Value must be truthy')
+ *
+ * // Using with type narrowing
+ * const config: Config | null = loadConfig()
+ * const safeConfig = assertEx(config, () => 'Config failed to load')
+ * // safeConfig is now type Config (not Config | null)
+ * ```
  */
-
 function assertEx<T>(expr: T | null | undefined, messageFunc?: AssertExMessageFunc<T>): T
+
+/**
+ * Asserts that an expression is truthy and returns the value.
+ * Throws a custom error if the expression is falsy.
+ *
+ * @template T - The type of value to check
+ * @template R - The type of error to throw
+ * @param expr - Expression to be evaluated for truthiness
+ * @param errorFunc - Function that returns a custom error instance if expression is falsy
+ * @throws Custom error returned by errorFunc
+ * @returns The value of the expression (guaranteed to be truthy)
+ * @example
+ * ```typescript
+ * // Using with a custom error
+ * const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))
+ * ```
+ */
 function assertEx<T, R extends Error>(expr: T | null | undefined, errorFunc?: AssertExErrorFunc<T, R>): T
+
 /**
- * @deprecated - passing a message will soon be required
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error if the expression is falsy.
+ *
+ * @deprecated Use overload with message function instead - passing a message will soon be required
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for truthiness
+ * @throws Error with a generic message
+ * @returns The value of the expression (guaranteed to be truthy)
  */
 function assertEx<T>(expr: T | null | undefined): T
+
 /**
- * @deprecated - replace string with () => string
+ * Asserts that an expression is truthy and returns the value.
+ * Throws an error with the provided message if the expression is falsy.
+ *
+ * @deprecated Replace string with () => string for consistency
+ * @template T - The type of value to check
+ * @param expr - Expression to be evaluated for truthiness
+ * @param message - Error message if expression is falsy
+ * @throws Error with the provided message
+ * @returns The value of the expression (guaranteed to be truthy)
  */
 function assertEx<T>(expr: T | null | undefined, message?: string): T
+
+/**
+ * Implementation of assertEx that handles all overloads.
+ */
 function assertEx<T, R extends Error, P extends string | AssertExMessageFunc<T> | AssertExErrorFunc<T, R>>(
   expr: T | null | undefined,
   messageOrFunc?: P,

package/src/types.ts

@@ -1,2 +1,36 @@
+/**
+ * @internal
+ * A function that takes a possibly null or undefined value and returns an error message string.
+ * Used in assertion functions to provide custom error messages.
+ *
+ * @internal
+ * @template T - The type of value being asserted
+ * @param value - The value being asserted (may be null or undefined)
+ * @returns A string message to be used in the error thrown by the assertion
+ * @example
+ * ```typescript
+ * const messageFunc: AssertExMessageFunc<User> = (user) =>
+ *   `User ${user ? user.id : 'unknown'} is not valid or accessible`
+ * ```
+ */
 export type AssertExMessageFunc<T> = (value?: T | null) => string
+
+/**
+ * A function that takes a possibly null or undefined value and returns a custom error instance.
+ * Used in assertion functions to provide specific error types with custom properties.
+ *
+ * @internal
+ * @template T - The type of value being asserted
+ * @template R - The specific error type to be returned, must extend Error
+ * @param value - The value being asserted (may be null or undefined)
+ * @returns An instance of the custom error type
+ * @example
+ * ```typescript
+ * const errorFunc: AssertExErrorFunc<User, UserNotFoundError> = (user) =>
+ *   new UserNotFoundError(`User ${user?.id || 'unknown'} not found`, {
+ *     userId: user?.id,
+ *     timestamp: new Date()
+ *   })
+ * ```
+ */
 export type AssertExErrorFunc<T, R extends Error> = (value?: T | null) => R