# @xylabs/object-model

[![npm][npm-badge]][npm-link]
[![license][license-badge]][license-link]

> Base functionality used throughout XY Labs TypeScript/JavaScript libraries

## Install

Using npm:

```sh
npm install {{name}}
```

Using yarn:

```sh
yarn add {{name}}
```

Using pnpm:

```sh
pnpm add {{name}}
```

Using bun:

```sh
bun add {{name}}
```


## License

See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).

## Reference

### packages

  ### object-model

    ### .temp-typedoc

      ### interfaces

        ### <a id="AsTypeFunction"></a>AsTypeFunction

[**@xylabs/object-model**](#../README)

***

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

## Type Parameters

### T

`T` *extends* `AnyNonPromise` = `AnyNonPromise`

## Call Signature

```ts
AsTypeFunction<TType>(value): TType | undefined;
```

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

### Type Parameters

### TType

`TType` *extends* `AnyNonPromise`

### Parameters

### value

`AnyNonPromise`

### Returns

`TType` \| `undefined`

## Call Signature

```ts
AsTypeFunction<TType>(value, config): TType;
```

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

### Type Parameters

### TType

`TType` *extends* `AnyNonPromise`

### Parameters

### value

`AnyNonPromise`

### config

[`TypeCheckRequiredConfig`](#TypeCheckRequiredConfig)

### Returns

`TType`

## Call Signature

```ts
AsTypeFunction<TType>(value, config): TType | undefined;
```

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

### Type Parameters

### TType

`TType` *extends* `AnyNonPromise`

### Parameters

### value

`AnyNonPromise`

### config

  \| [`TypeCheckConfig`](#TypeCheckConfig)
  \| [`TypeCheckOptionalConfig`](#TypeCheckOptionalConfig)

### Returns

`TType` \| `undefined`

## Call Signature

```ts
AsTypeFunction<TType>(value, assert): TType | undefined;
```

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

### Type Parameters

### TType

`TType` *extends* `AnyNonPromise`

### Parameters

### value

`AnyNonPromise`

### assert

[`StringOrAlertFunction`](#../type-aliases/StringOrAlertFunction)\<`TType`\>

### Returns

`TType` \| `undefined`

## Call Signature

```ts
AsTypeFunction<TType>(
   value, 
   assert, 
   config): TType;
```

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

### Type Parameters

### TType

`TType` *extends* `AnyNonPromise`

### Parameters

### value

`AnyNonPromise`

### assert

[`StringOrAlertFunction`](#../type-aliases/StringOrAlertFunction)\<`TType`\>

### config

[`TypeCheckRequiredConfig`](#TypeCheckRequiredConfig)

### Returns

`TType`

## Call Signature

```ts
AsTypeFunction<TType>(
   value, 
   assert, 
   config): TType | undefined;
```

A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.

### Type Parameters

### TType

`TType` *extends* `AnyNonPromise`

### Parameters

### value

`AnyNonPromise`

### assert

[`StringOrAlertFunction`](#../type-aliases/StringOrAlertFunction)\<`TType`\>

### config

  \| [`TypeCheckConfig`](#TypeCheckConfig)
  \| [`TypeCheckOptionalConfig`](#TypeCheckOptionalConfig)

### Returns

`TType` \| `undefined`

        ### <a id="TypeCheck"></a>TypeCheck

[**@xylabs/object-model**](#../README)

***

A type guard function that checks whether a value conforms to type T, with optional configuration.

## Type Parameters

### T

`T` *extends* `TypedValue`

## Call Signature

```ts
TypeCheck(obj): obj is T;
```

A type guard function that checks whether a value conforms to type T, with optional configuration.

### Parameters

### obj

`AnyNonPromise`

### Returns

`obj is T`

## Call Signature

```ts
TypeCheck(obj, config): obj is T;
```

A type guard function that checks whether a value conforms to type T, with optional configuration.

### Parameters

### obj

`AnyNonPromise`

### config

[`TypeCheckConfig`](#TypeCheckConfig)

### Returns

`obj is T`

## Call Signature

```ts
TypeCheck(obj, config): obj is T;
```

A type guard function that checks whether a value conforms to type T, with optional configuration.

### Parameters

### obj

`AnyNonPromise`

### config

`number` \| [`TypeCheckConfig`](#TypeCheckConfig) \| `undefined`

### Returns

`obj is T`

        ### <a id="TypeCheckConfig"></a>TypeCheckConfig

[**@xylabs/object-model**](#../README)

***

Configuration options for type check functions, with optional logging.

## Extended by

- [`TypeCheckRequiredConfig`](#TypeCheckRequiredConfig)
- [`TypeCheckOptionalConfig`](#TypeCheckOptionalConfig)

## Properties

### log?

```ts
optional log?: boolean | Logger;
```

        ### <a id="TypeCheckOptionalConfig"></a>TypeCheckOptionalConfig

[**@xylabs/object-model**](#../README)

***

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;
```

        ### <a id="TypeCheckRequiredConfig"></a>TypeCheckRequiredConfig

[**@xylabs/object-model**](#../README)

***

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;
```

      ### type-aliases

        ### <a id="AnyObject"></a>AnyObject

[**@xylabs/object-model**](#../README)

***

```ts
type AnyObject = EmptyObject & Partial<Record<TypedKey, unknown>>;
```

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

        ### <a id="AsOptionalTypeFunction"></a>AsOptionalTypeFunction

[**@xylabs/object-model**](#../README)

***

```ts
type AsOptionalTypeFunction<T> = <TType>(value) => TType | undefined;
```

A simplified type-narrowing function that returns T or undefined, without assertion support.

## Type Parameters

### T

`T` *extends* `AnyNonPromise` = `AnyNonPromise`

## Type Parameters

### TType

`TType` *extends* `T`

## Parameters

### value

`AnyNonPromise`

## Returns

`TType` \| `undefined`

        ### <a id="Compare"></a>Compare

[**@xylabs/object-model**](#../README)

***

```ts
type Compare<T> = (a, b) => number;
```

A comparator function that returns a negative number if a < b, zero if a == b, and a positive number if a > b.

## Type Parameters

### T

`T`

## Parameters

### a

`T`

### b

`T`

## Returns

`number`

        ### <a id="EmptyObject"></a>EmptyObject

[**@xylabs/object-model**](#../README)

***

```ts
type EmptyObject<T> = Exclude<{ [K in keyof T]?: never }, unknown[] | ((...args) => unknown) | null>;
```

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

## Type Parameters

### T

`T` *extends* `object` = `object`

        ### <a id="StringOrAlertFunction"></a>StringOrAlertFunction

[**@xylabs/object-model**](#../README)

***

```ts
type StringOrAlertFunction<T> = string | AssertExMessageFunc<T>;
```

A string message or function that produces an assertion error message for a failed type check.

## Type Parameters

### T

`T` *extends* `AnyNonPromise`


[npm-badge]: https://img.shields.io/npm/v/@xylabs/object-model.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/object-model
[license-badge]: https://img.shields.io/npm/l/@xylabs/object-model.svg
[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE