@xylabs/object-model 5.0.83 → 5.0.86

package/README.md

@@ -15,6 +15,8 @@
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
+
+
 ## Reference
 
 **@xylabs/object-model**
@@ -23,19 +25,23 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ## Interfaces
 
-- [TypeCheckConfig](#interfaces/TypeCheckConfig)
-- [TypeCheckRequiredConfig](#interfaces/TypeCheckRequiredConfig)
-- [TypeCheckOptionalConfig](#interfaces/TypeCheckOptionalConfig)
+| Interface | Description |
+| ------ | ------ |
+| [TypeCheckConfig](#interfaces/TypeCheckConfig) | Configuration options for type check functions, with optional logging. |
+| [TypeCheckRequiredConfig](#interfaces/TypeCheckRequiredConfig) | Type check configuration that marks the value as required, causing assertions on failure. |
+| [TypeCheckOptionalConfig](#interfaces/TypeCheckOptionalConfig) | Type check configuration that marks the value as optional, returning undefined on failure. |
 
 ## Type Aliases
 
-- [AnyObject](#type-aliases/AnyObject)
-- [AsTypeFunction](#type-aliases/AsTypeFunction)
-- [AsOptionalTypeFunction](#type-aliases/AsOptionalTypeFunction)
-- [Compare](#type-aliases/Compare)
-- [EmptyObject](#type-aliases/EmptyObject)
-- [StringOrAlertFunction](#type-aliases/StringOrAlertFunction)
-- [TypeCheck](#type-aliases/TypeCheck)
+| Type Alias | Description |
+| ------ | ------ |
+| [AnyObject](#type-aliases/AnyObject) | Any object, which means that it does not enforce the set of fields that it has. Extending from AnyObject will result in a type that includes the universal set of field names |
+| [AsTypeFunction](#type-aliases/AsTypeFunction) | A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads. |
+| [AsOptionalTypeFunction](#type-aliases/AsOptionalTypeFunction) | A simplified type-narrowing function that returns T or undefined, without assertion support. |
+| [Compare](#type-aliases/Compare) | A comparator function that returns a negative number if a < b, zero if a == b, and a positive number if a > b. |
+| [EmptyObject](#type-aliases/EmptyObject) | An empty object, which means that it does enforce the set of field names, defaulting to an empty set until extended from, which then adds only those additional fields |
+| [StringOrAlertFunction](#type-aliases/StringOrAlertFunction) | A string message or function that produces an assertion error message for a failed type check. |
+| [TypeCheck](#type-aliases/TypeCheck) | A type guard function that checks whether a value conforms to type T, with optional configuration. |
 
 ### interfaces
 
@@ -45,6 +51,8 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+Configuration options for type check functions, with optional logging.
+
 ## Extended by
 
 - [`TypeCheckRequiredConfig`](#TypeCheckRequiredConfig)
@@ -52,11 +60,9 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ## Properties
 
-### log?
-
-```ts
-optional log: boolean | Logger;
-```
+| Property | Type |
+| ------ | ------ |
+| <a id="log"></a> `log?` | `boolean` \| `Logger` |
 
   ### <a id="TypeCheckOptionalConfig"></a>TypeCheckOptionalConfig
 
@@ -64,29 +70,18 @@ optional log: boolean | Logger;
 
 ***
 
+Type check configuration that marks the value as optional, returning undefined on failure.
+
 ## Extends
 
 - [`TypeCheckConfig`](#TypeCheckConfig)
 
 ## Properties
 
-### log?
-
-```ts
-optional log: boolean | Logger;
-```
-
-### Inherited from
-
-[`TypeCheckConfig`](#TypeCheckConfig).[`log`](TypeCheckConfig.md#log)
-
-***
-
-### required
-
-```ts
-required: false;
-```
+| Property | Type | Inherited from |
+| ------ | ------ | ------ |
+| <a id="log"></a> `log?` | `boolean` \| `Logger` | [`TypeCheckConfig`](#TypeCheckConfig).[`log`](TypeCheckConfig.md#log) |
+| <a id="required"></a> `required` | `false` | - |
 
   ### <a id="TypeCheckRequiredConfig"></a>TypeCheckRequiredConfig
 
@@ -94,29 +89,18 @@ required: false;
 
 ***
 
+Type check configuration that marks the value as required, causing assertions on failure.
+
 ## Extends
 
 - [`TypeCheckConfig`](#TypeCheckConfig)
 
 ## Properties
 
-### log?
-
-```ts
-optional log: boolean | Logger;
-```
-
-### Inherited from
-
-[`TypeCheckConfig`](#TypeCheckConfig).[`log`](TypeCheckConfig.md#log)
-
-***
-
-### required
-
-```ts
-required: true;
-```
+| Property | Type | Inherited from |
+| ------ | ------ | ------ |
+| <a id="log"></a> `log?` | `boolean` \| `Logger` | [`TypeCheckConfig`](#TypeCheckConfig).[`log`](TypeCheckConfig.md#log) |
+| <a id="required"></a> `required` | `true` | - |
 
 ### type-aliases
 
@@ -140,26 +124,28 @@ will result in a type that includes the universal set of field names
 ***
 
 ```ts
-type AsOptionalTypeFunction<T> = <TType>(value) => TType | undefined;
+type AsOptionalTypeFunction<T> = <TType>(value: AnyNonPromise) => TType | undefined;
 ```
 
-## Type Parameters
+A simplified type-narrowing function that returns T or undefined, without assertion support.
 
-### T
+## Type Parameters
 
-`T` *extends* `AnyNonPromise` = `AnyNonPromise`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` *extends* `AnyNonPromise` | `AnyNonPromise` |
 
 ## Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ## Parameters
 
-### value
-
-`AnyNonPromise`
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
 
 ## Returns
 
@@ -173,38 +159,44 @@ type AsOptionalTypeFunction<T> = <TType>(value) => TType | undefined;
 
 ```ts
 type AsTypeFunction<T> = {
-<TType>  (value): TType | undefined;
-<TType>  (value, config): TType;
-<TType>  (value, config): TType | undefined;
-<TType>  (value, assert): TType | undefined;
-<TType>  (value, assert, config): TType;
-<TType>  (value, assert, config): TType | undefined;
+<TType>  (value: AnyNonPromise): TType | undefined;
+<TType>  (value: AnyNonPromise, config: TypeCheckRequiredConfig): TType;
+<TType>  (value: AnyNonPromise, config: 
+  | TypeCheckConfig
+  | TypeCheckOptionalConfig): TType | undefined;
+<TType>  (value: AnyNonPromise, assert: StringOrAlertFunction<TType>): TType | undefined;
+<TType>  (value: AnyNonPromise, assert: StringOrAlertFunction<TType>, config: TypeCheckRequiredConfig): TType;
+<TType>  (value: AnyNonPromise, assert: StringOrAlertFunction<TType>, config: 
+  | TypeCheckConfig
+  | TypeCheckOptionalConfig): TType | undefined;
 };
 ```
 
-## Type Parameters
+A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
 
-### T
+## Type Parameters
 
-`T` *extends* `AnyNonPromise` = `AnyNonPromise`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` *extends* `AnyNonPromise` | `AnyNonPromise` |
 
 ## Call Signature
 
 ```ts
-<TType>(value): TType | undefined;
+<TType>(value: AnyNonPromise): TType | undefined;
 ```
 
 ### Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ### Parameters
 
-### value
-
-`AnyNonPromise`
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
 
 ### Returns
 
@@ -213,24 +205,21 @@ type AsTypeFunction<T> = {
 ## Call Signature
 
 ```ts
-<TType>(value, config): TType;
+<TType>(value: AnyNonPromise, config: TypeCheckRequiredConfig): TType;
 ```
 
 ### Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ### Parameters
 
-### value
-
-`AnyNonPromise`
-
-### config
-
-[`TypeCheckRequiredConfig`](#../interfaces/TypeCheckRequiredConfig)
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
+| `config` | [`TypeCheckRequiredConfig`](#../interfaces/TypeCheckRequiredConfig) |
 
 ### Returns
 
@@ -239,24 +228,23 @@ type AsTypeFunction<T> = {
 ## Call Signature
 
 ```ts
-<TType>(value, config): TType | undefined;
+<TType>(value: AnyNonPromise, config: 
+  | TypeCheckConfig
+  | TypeCheckOptionalConfig): TType | undefined;
 ```
 
 ### Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ### Parameters
 
-### value
-
-`AnyNonPromise`
-
-### config
-
-[`TypeCheckConfig`](#../interfaces/TypeCheckConfig) | [`TypeCheckOptionalConfig`](#../interfaces/TypeCheckOptionalConfig)
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
+| `config` | \| [`TypeCheckConfig`](#../interfaces/TypeCheckConfig) \| [`TypeCheckOptionalConfig`](#../interfaces/TypeCheckOptionalConfig) |
 
 ### Returns
 
@@ -265,24 +253,21 @@ type AsTypeFunction<T> = {
 ## Call Signature
 
 ```ts
-<TType>(value, assert): TType | undefined;
+<TType>(value: AnyNonPromise, assert: StringOrAlertFunction<TType>): TType | undefined;
 ```
 
 ### Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ### Parameters
 
-### value
-
-`AnyNonPromise`
-
-### assert
-
-[`StringOrAlertFunction`](#StringOrAlertFunction)\<`TType`\>
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
+| `assert` | [`StringOrAlertFunction`](#StringOrAlertFunction)\<`TType`\> |
 
 ### Returns
 
@@ -292,30 +277,24 @@ type AsTypeFunction<T> = {
 
 ```ts
 <TType>(
-   value, 
-   assert, 
-   config): TType;
+   value: AnyNonPromise, 
+   assert: StringOrAlertFunction<TType>, 
+   config: TypeCheckRequiredConfig): TType;
 ```
 
 ### Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ### Parameters
 
-### value
-
-`AnyNonPromise`
-
-### assert
-
-[`StringOrAlertFunction`](#StringOrAlertFunction)\<`TType`\>
-
-### config
-
-[`TypeCheckRequiredConfig`](#../interfaces/TypeCheckRequiredConfig)
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
+| `assert` | [`StringOrAlertFunction`](#StringOrAlertFunction)\<`TType`\> |
+| `config` | [`TypeCheckRequiredConfig`](#../interfaces/TypeCheckRequiredConfig) |
 
 ### Returns
 
@@ -325,30 +304,26 @@ type AsTypeFunction<T> = {
 
 ```ts
 <TType>(
-   value, 
-   assert, 
-   config): TType | undefined;
+   value: AnyNonPromise, 
+   assert: StringOrAlertFunction<TType>, 
+   config: 
+  | TypeCheckConfig
+  | TypeCheckOptionalConfig): TType | undefined;
 ```
 
 ### Type Parameters
 
-### TType
-
-`TType` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `TType` *extends* `AnyNonPromise` |
 
 ### Parameters
 
-### value
-
-`AnyNonPromise`
-
-### assert
-
-[`StringOrAlertFunction`](#StringOrAlertFunction)\<`TType`\>
-
-### config
-
-[`TypeCheckConfig`](#../interfaces/TypeCheckConfig) | [`TypeCheckOptionalConfig`](#../interfaces/TypeCheckOptionalConfig)
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `AnyNonPromise` |
+| `assert` | [`StringOrAlertFunction`](#StringOrAlertFunction)\<`TType`\> |
+| `config` | \| [`TypeCheckConfig`](#../interfaces/TypeCheckConfig) \| [`TypeCheckOptionalConfig`](#../interfaces/TypeCheckOptionalConfig) |
 
 ### Returns
 
@@ -361,24 +336,23 @@ type AsTypeFunction<T> = {
 ***
 
 ```ts
-type Compare<T> = (a, b) => number;
+type Compare<T> = (a: T, b: T) => number;
 ```
 
-## Type Parameters
+A comparator function that returns a negative number if a < b, zero if a == b, and a positive number if a > b.
 
-### T
+## Type Parameters
 
-`T`
+| Type Parameter |
+| ------ |
+| `T` |
 
 ## Parameters
 
-### a
-
-`T`
-
-### b
-
-`T`
+| Parameter | Type |
+| ------ | ------ |
+| `a` | `T` |
+| `b` | `T` |
 
 ## Returns
 
@@ -391,7 +365,7 @@ type Compare<T> = (a, b) => number;
 ***
 
 ```ts
-type EmptyObject<T> = Exclude<{ [K in keyof T]?: never }, unknown[] | (...args) => unknown | null>;
+type EmptyObject<T> = Exclude<{ [K in keyof T]?: never }, unknown[] | (...args: unknown[]) => unknown | null>;
 ```
 
 An empty object, which means that it does enforce the set of field names, defaulting to an empty set until
@@ -399,9 +373,9 @@ extended from, which then adds only those additional fields
 
 ## Type Parameters
 
-### T
-
-`T` *extends* `object` = `object`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` *extends* `object` | `object` |
 
   ### <a id="StringOrAlertFunction"></a>StringOrAlertFunction
 
@@ -413,11 +387,13 @@ extended from, which then adds only those additional fields
 type StringOrAlertFunction<T> = string | AssertExMessageFunc<T>;
 ```
 
-## Type Parameters
+A string message or function that produces an assertion error message for a failed type check.
 
-### T
+## Type Parameters
 
-`T` *extends* `AnyNonPromise`
+| Type Parameter |
+| ------ |
+| `T` *extends* `AnyNonPromise` |
 
   ### <a id="TypeCheck"></a>TypeCheck
 
@@ -427,29 +403,34 @@ type StringOrAlertFunction<T> = string | AssertExMessageFunc<T>;
 
 ```ts
 type TypeCheck<T> = {
-  (obj): obj is T;
-  (obj, config): obj is T;
-  (obj, config): obj is T;
+  (obj: AnyNonPromise): obj is T;
+  (obj: AnyNonPromise, config: TypeCheckConfig): obj is T;
+  (obj: AnyNonPromise, config: 
+  | number
+  | TypeCheckConfig
+  | undefined): obj is T;
 };
 ```
 
-## Type Parameters
+A type guard function that checks whether a value conforms to type T, with optional configuration.
 
-### T
+## Type Parameters
 
-`T` *extends* `TypedValue`
+| Type Parameter |
+| ------ |
+| `T` *extends* `TypedValue` |
 
 ## Call Signature
 
 ```ts
-(obj): obj is T;
+(obj: AnyNonPromise): obj is T;
 ```
 
 ### Parameters
 
-### obj
-
-`AnyNonPromise`
+| Parameter | Type |
+| ------ | ------ |
+| `obj` | `AnyNonPromise` |
 
 ### Returns
 
@@ -458,18 +439,15 @@ type TypeCheck<T> = {
 ## Call Signature
 
 ```ts
-(obj, config): obj is T;
+(obj: AnyNonPromise, config: TypeCheckConfig): obj is T;
 ```
 
 ### Parameters
 
-### obj
-
-`AnyNonPromise`
-
-### config
-
-[`TypeCheckConfig`](#../interfaces/TypeCheckConfig)
+| Parameter | Type |
+| ------ | ------ |
+| `obj` | `AnyNonPromise` |
+| `config` | [`TypeCheckConfig`](#../interfaces/TypeCheckConfig) |
 
 ### Returns
 
@@ -478,18 +456,18 @@ type TypeCheck<T> = {
 ## Call Signature
 
 ```ts
-(obj, config): obj is T;
+(obj: AnyNonPromise, config: 
+  | number
+  | TypeCheckConfig
+  | undefined): obj is T;
 ```
 
 ### Parameters
 
-### obj
-
-`AnyNonPromise`
-
-### config
-
-`number` | [`TypeCheckConfig`](#../interfaces/TypeCheckConfig) | `undefined`
+| Parameter | Type |
+| ------ | ------ |
+| `obj` | `AnyNonPromise` |
+| `config` | \| `number` \| [`TypeCheckConfig`](#../interfaces/TypeCheckConfig) \| `undefined` |
 
 ### Returns
 

package/dist/neutral/AsTypeFactory.d.ts

@@ -1,6 +1,10 @@
 import type { AnyNonPromise } from '@xylabs/promise';
 import type { AsTypeFunction } from './AsTypeFunction.ts';
 import type { TypeCheck } from './types.ts';
+/**
+ * Factory for creating type-narrowing 'as' functions that cast a value to T or return undefined.
+ * Supports optional assertion messages and configuration for required/optional behavior.
+ */
 export declare const AsTypeFactory: {
     create: <T extends AnyNonPromise>(typeCheck: TypeCheck<T>) => AsTypeFunction<T>;
     createOptional: <T extends AnyNonPromise>(typeCheck: TypeCheck<T>) => (value: AnyNonPromise) => T | undefined;

package/dist/neutral/AsTypeFunction.d.ts

@@ -1,5 +1,6 @@
 import type { AnyNonPromise } from '@xylabs/promise';
 import type { StringOrAlertFunction, TypeCheckConfig, TypeCheckOptionalConfig, TypeCheckRequiredConfig } from './types.ts';
+/** A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads. */
 export type AsTypeFunction<T extends AnyNonPromise = AnyNonPromise> = {
     <TType extends T>(value: AnyNonPromise): TType | undefined;
     <TType extends T>(value: AnyNonPromise, config: TypeCheckRequiredConfig): TType;
@@ -8,6 +9,7 @@ export type AsTypeFunction<T extends AnyNonPromise = AnyNonPromise> = {
     <TType extends T>(value: AnyNonPromise, assert: StringOrAlertFunction<TType>, config: TypeCheckRequiredConfig): TType;
     <TType extends T>(value: AnyNonPromise, assert: StringOrAlertFunction<TType>, config: TypeCheckConfig | TypeCheckOptionalConfig): TType | undefined;
 };
+/** A simplified type-narrowing function that returns T or undefined, without assertion support. */
 export type AsOptionalTypeFunction<T extends AnyNonPromise = AnyNonPromise> = {
     <TType extends T>(value: AnyNonPromise): TType | undefined;
 };

package/dist/neutral/Compare.d.ts

@@ -1 +1,2 @@
+/** A comparator function that returns a negative number if a < b, zero if a == b, and a positive number if a > b. */
 export type Compare<T> = (a: T, b: T) => number;

package/dist/neutral/types.d.ts

@@ -2,16 +2,21 @@ import type { AssertExMessageFunc } from '@xylabs/assert';
 import type { Logger } from '@xylabs/logger';
 import type { AnyNonPromise } from '@xylabs/promise';
 import type { TypedValue } from '@xylabs/typeof';
+/** Configuration options for type check functions, with optional logging. */
 export interface TypeCheckConfig {
     log?: boolean | Logger;
 }
+/** Type check configuration that marks the value as required, causing assertions on failure. */
 export interface TypeCheckRequiredConfig extends TypeCheckConfig {
     required: true;
 }
+/** Type check configuration that marks the value as optional, returning undefined on failure. */
 export interface TypeCheckOptionalConfig extends TypeCheckConfig {
     required: false;
 }
+/** A string message or function that produces an assertion error message for a failed type check. */
 export type StringOrAlertFunction<T extends AnyNonPromise> = string | AssertExMessageFunc<T>;
+/** A type guard function that checks whether a value conforms to type T, with optional configuration. */
 export type TypeCheck<T extends TypedValue> = {
     (obj: AnyNonPromise): obj is T;
     (obj: AnyNonPromise, config: TypeCheckConfig): obj is T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/object-model",
-  "version": "5.0.83",
+  "version": "5.0.86",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "homepage": "https://xyo.network",
   "bugs": {
@@ -35,14 +35,14 @@
     "!**/*.test.*"
   ],
   "dependencies": {
-    "@xylabs/assert": "~5.0.83",
-    "@xylabs/logger": "~5.0.83",
-    "@xylabs/promise": "~5.0.83",
-    "@xylabs/typeof": "~5.0.83"
+    "@xylabs/assert": "~5.0.86",
+    "@xylabs/logger": "~5.0.86",
+    "@xylabs/promise": "~5.0.86",
+    "@xylabs/typeof": "~5.0.86"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "~7.4.11",
-    "@xylabs/tsconfig": "~7.4.11",
+    "@xylabs/ts-scripts-yarn3": "~7.4.16",
+    "@xylabs/tsconfig": "~7.4.16",
     "typescript": "~5.9.3",
     "vitest": "~4.0.18"
   },