@xylabs/assert 4.13.20 → 4.13.22

package/README.md

@@ -12,13 +12,420 @@
 [![snyk-badge][]][snyk-link]
 [![socket-badge][]][socket-link]
 
-Version: 4.13.19
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
-## Documentation
+## Reference
+
+**@xylabs/assert**
+
+***
+
+## Functions
+
+- [assertDefinedEx](#functions/assertDefinedEx)
+- [assertEx](#functions/assertEx)
+
+### functions
+
+  ### <a id="assertDefinedEx"></a>assertDefinedEx
+
+[**@xylabs/assert**](#../README)
+
+***
+
+Implementation of assertDefinedEx that handles all overloads.
+
+## Call Signature
+
+```ts
+function assertDefinedEx<T>(expr, messageFunc?): 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`
+
+### messageFunc?
+
+`AssertExMessageFunc`\<`T`\>
+
+Function that returns a message for the error if expression is undefined
+
+### Returns
+
+`T`
+
+The value of the expression (guaranteed to be defined)
+
+### Throws
+
+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
+
+```ts
+function assertDefinedEx<T, R>(expr, errorFunc?): T;
+```
+
+Asserts that a value is defined (not undefined) and returns the value.
+Throws a custom error if the value is undefined.
+
+### Type Parameters
+
+### T
+
+`T`
+
+The type of value to check
+
+### R
+
+`R` *extends* `Error`
+
+The type of error to throw
+
+### Parameters
+
+### expr
+
+Expression to be evaluated for being defined
+
+`undefined` | `T`
+
+### errorFunc?
+
+`AssertExErrorFunc`\<`T`, `R`\>
+
+Function that returns a custom error instance if expression is undefined
+
+### Returns
+
+`T`
+
+The value of the expression (guaranteed to be defined)
+
+### Throws
+
+Custom error returned by errorFunc
+
+### Example
+
+```typescript
+// Using with a custom error
+const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))
+```
+
+## Call Signature
+
+```ts
+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
+
+Use overload with message function instead - passing a message will soon be required
+
+### Throws
+
+Error with a generic message
+
+## Call Signature
+
+```ts
+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 for consistency
+
+### Throws
+
+Error with the provided message
+
+  ### <a id="assertEx"></a>assertEx
+
+[**@xylabs/assert**](#../README)
+
+***
+
+Implementation of assertEx that handles all overloads.
+
+## Call Signature
+
+```ts
+function assertEx<T>(expr, messageFunc?): 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`
+
+### messageFunc?
+
+`AssertExMessageFunc`\<`T`\>
+
+Function that returns a message for the error if expression is falsy
+
+### Returns
+
+`T`
+
+The value of the expression (guaranteed to be truthy)
+
+### Throws
+
+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
+
+```ts
+function assertEx<T, R>(expr, errorFunc?): T;
+```
+
+Asserts that an expression is truthy and returns the value.
+Throws a custom error if the expression is falsy.
+
+### Type Parameters
+
+### T
+
+`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
+
+`undefined` | `null` | `T`
+
+### errorFunc?
+
+`AssertExErrorFunc`\<`T`, `R`\>
+
+Function that returns a custom error instance if expression is falsy
+
+### Returns
+
+`T`
+
+The value of the expression (guaranteed to be truthy)
+
+### Throws
+
+Custom error returned by errorFunc
+
+### Example
+
+```typescript
+// Using with a custom error
+const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))
+```
+
+## Call Signature
+
+```ts
+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
+
+Use overload with message function instead - passing a message will soon be required
+
+### Throws
+
+Error with a generic message
+
+## Call Signature
+
+```ts
+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`
+
+Error message if expression is falsy
+
+### Returns
+
+`T`
+
+The value of the expression (guaranteed to be truthy)
+
+### Deprecated
+
+Replace string with () => string for consistency
+
+### Throws
+
+Error with the provided message
 
-Coming Soon!
 
 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.20",
+  "version": "4.13.22",
   "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