# adam

Functions to create, process and test objects.

Source:
  - adam.js, line 10

### Methods

#### (static) change(obj, action, settingsopt) → {Object}

Source:
  - adam.js, line 1350
See:
  - checkField
  - copy

Change all or filtered fields of object/map/array, applying specified action/transformation.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object/map/array whose fields should be changed.
`action` | function | String |  | An action/operation that should be applied to get new field value. See description of `transform` setting of copy.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter that should be used to select fields for modification (see checkField); fields conforming to the filter will be changed
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

Modified object (value of `obj` parameter).

Type
  Object

#### (static) checkField(obj, field, filter, settingsopt) → {Boolean}

Source:
  - adam.js, line 347
See:
  - getClass
  - isKindOf

Check whether the field of given object/map/array/set corresponds to specified condition(s) or filter(s).

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object, map (including WeakMap), array or set (including WeakSet) to be processed.
`field` | String | Symbol |  | Field that should be checked.

`filter`

Any

A filter or array of filters specifying conditions that should be checked. A filter can be:

- a function; if the function returns a true value it means that the field corresponds to this filter; the following parameters will be passed into the function: field value, field name, reference to the object and operation settings
- a regular expression; if the field value (converted to string) matches the regular expression it means that the field corresponds to this filter
- a string; value can be one of the following:
  - `own` - if the field is own property of the object it means that the field corresponds to this filter
  - `!own` - if the field is not own property of the object it means that the field corresponds to this filter
  - any other value - is used as the check when calling isKindOf; if isKindOf returns `true` for the given field value and the filter it means that the field corresponds to this filter
- an object (referred below as condition);
  - if the object has `and` or `or` field, its value is used as subfilter and will be passed in recursive call of `checkField` as value of `filter` parameter; the field name (`and` or `or`) will be used as value of `filterConnect` setting (see below); if the result of the recursive call is `true` it means that the field corresponds to this filter
  - if the object has `field` field, its value is used as filter for the field name (property key) that is being checked; the filter is applied to the field name (property key) in recursive call of `checkField` as if the key is a tested field value of special object that is created for the check purposes (i.e. `checkField({field: field}, "field", filter.field, {filterConnect: settings.filterConnect})`)
  - if the object has `value` field, its value is used as filter; if the field value strictly equals to the filter value
  - if the object has `inside` field, its value is used as filter; if the filter value "contains" the field value it means that the field corresponds to this filter; the filter value can be:
    - an array or a string; in such case `indexOf` is used to check presence of the field value in the filter value;
    - a set; in such case `has` is used to check presence of the field value in the filter value;
    - a map or an object; when `key` field is specified in the condition, the filter value will be checked for presence of such key/value pair; if `true` is set as value for `key` field, value of `field` parameter will be used as the key; when `key` field is absent in the condition, the field value will be checked for presence in the list of values of the map/object;
    - any other value; in such case the field value is not inside the filter value;
  - in any other case if the field value strictly equals to the object it means that the field corresponds to this filter
- any other value; if the field value strictly equals to the filter value it means that the field corresponds to this filter

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported (setting's default value is specified in parentheses):

- `filterConnect`: `String` (`and`) - a boolean connector that should be used when array of filters is specified in `filter` parameter; valid values are the following: `and`, `or` (case-insensitive); any other value is treated as `and`
- `value`: `Any` - a value that should be used for check instead of field's value

##### Returns:

`true` if the field corresponds to specified filter(s), otherwise `false`.

Type
  Boolean

#### (static) checkValue(value, filter, settingsopt) → {Boolean}

Source:
  - adam.js, line 473
See:
  - checkField

Check whether the value corresponds to specified condition(s) or filter(s).

This function is a "wrap" for the following code:

    checkField({value: value}, "value", filter, settings);

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`value` | Any |  | Value that should be checked.
`filter` | Any |  | A filter or array of filters specifying conditions that should be checked. See checkField for details.
`settings` | Object | <optional> | Operation settings. See checkField for details.

##### Returns:

`true` if the value corresponds to specified filter(s), otherwise `false`.

Type
  Boolean

#### (static) copy(source, target, settingsopt) → {Object}

Source:
  - adam.js, line 1265
See:
  - checkField
  - transform

Copy all or filtered fields from source object/map/array/set into target object/map/array/set, applying specified transformation if necessary.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`source` | Object |  | Object/map/array/set whose fields will be copied.
`target` | Object |  | Object/map/array/set into which fields should be copied.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter that should be used to select fields for copying (see checkField); fields conforming to the filter will be copied
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)
- `transform` - an action/operation that should be applied to get field's value that will be copied instead of value from source object; can be a string specifying transformation (see transform) or a function whose result will be used as field's value; object with the following fields will be passed into the function:
  - `field` - field name
  - `value` field value from source object
  - `source` - reference to the source object
  - `target` - reference to the target object
  - `settings` - operation settings

##### Returns:

Reference to the target object (value of `target` parameter).

Type
  Object

#### (static) empty(value) → {Any}

Source:
  - adam.js, line 1063

Empty the given value according to the following rules:

- for array, `Map` or `Set`: removes all elements from the value
- for object: removes all own fields from the value
- for string: returns empty string
- for number: returns `0`
- otherwise: returns `undefined`

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value to be processed.

##### Returns:

Processed value (for array, object, `Map` or `Set`) or empty value corresponding to the given value.

Type
  Any

#### (static) fromArray(list, keyFieldopt, settingsopt) → {Object}

Source:
  - adam.js, line 799
See:
  - checkField

Create object (map) from list of objects/maps. Fields of the created object are values of specified field/key of objects/maps, values of the created object are corresponding items of the list.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`list` | Array |  | List of objects/values to be processed.

`keyField`

function | String

<optional>

Specifies names of fields of the created object. Can be name of field or method whose value is used as field name of the created object, or function that returns the field name. In the latter case the following parameters will be passed in the function: the source object (an item of the list), the created object, the index of the source object, operation settings. When the parameter is not set, items of the list are used as field names.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported (setting's default value is specified in parentheses):

- `deleteKeyField`: `Boolean` (`false`) - specifies whether key field (whose value is field name of the created object) should be deleted from the source object (an item of the list)
- `filter` - a filter specifying objects that should be included into result (see checkField); an item of the list will be used as value for check
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

Object created from the given list.

Type
  Object

#### (static) getClass(value) → {String}

Source:
  - adam.js, line 112

Return class of given value (namely value of internal property `[[Class]]`).

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value whose class should be determined.

##### Returns:

String indicating value class.

Type
  String

#### (static) getFields(obj, settingsopt) → {Array}

Source:
  - adam.js, line 533
See:
  - checkField
  - getKeys

Return list of all or filtered fields of specified object or map.

Fields are searched (checked) in the object itself and in its prototype chain.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map to be processed.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter specifying fields that should be selected (see checkField)
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)
- `limit` - a maximum number of fields that should be included into result; after the specified number of fields is attained, the search will be stopped
- `pairs`: `object | boolean | 'list' | 'obj'` - whether list of field-value pairs should be returned instead of list of fields; when `true` is set it is the same as `{form: 'obj'}`; when a string is set it is the same as `{form: <string>}`; an object value specifies a form of field-value pairs and can have the following fields:
  - `form`: `'list' | 'obj'` - whether an item of the result list should be `[field, value]` array or `{key: field, value: value}` object; default value is `'obj'`; any string that is different from `'list'` is treated as `'obj'`;
  - `type` - the same as `form`;
  - `key`: `string` - for object items of the result list specifies name of field that contains processed object's field; default value is `key`;
  - `value`: `string` - for object items of the result list specifies name of field that contains processed object's field value; default value is `value`;

##### Returns:

List of all or filtered fields of specified object.

Type
  Array

#### (static) getFreeField(obj, settingsopt) → {String}

Source:
  - adam.js, line 741

Return name of first free (absent) field/key of specified object/map, that conforms to the following pattern: <prefix><number>

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map in which a free field/key should be found. If `null` (or any false value) is set, the first value that conforms to the pattern will be returned.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported (setting's default value is specified in parentheses):

- `checkPrefix`: `Boolean` (`false`) - specifies whether pattern consisting only from prefix (without number) should be checked
- `prefix`: `String` (`f`) - prefix of sought field
- `startNum`: `Integer` (`0`) - starting number which is used as part of pattern by search/check

##### Returns:

Name of field which is absent in the specified object and conforms to the pattern.

Type
  String

#### (static) getKeys(value) → {Array|null}

Source:
  - adam.js, line 487
See:
  - getFields

Return list of all keys of specified object/map/array/set.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value that should be processed.

##### Returns:

List of all keys of specified object/map/array/set or `null` if another value is passed.

Type
  Array | null

#### (static) getPropertySymbols(obj) → {Array}

Source:
  - adam.js, line 79

Return list of all symbol property keys for given object including keys from prototype chain.

This function is defined only when `Object.getOwnPropertySymbols` is available.

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | Object to be processed.

##### Returns:

List of all found symbol property keys.

Type
  Array

#### (static) getSize(obj, settingsopt) → {Integer}

Source:
  - adam.js, line 169
See:
  - getFields

Return number of all or filtered fields of specified object or map.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map to be processed.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter specifying fields that should be counted (see checkField)
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

Number of all or filtered fields of specified object.

Type
  Integer

#### (static) getType(value) → {String}

Source:
  - adam.js, line 144

Return type of given value.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value whose type should be determined.

##### Returns:

For `NaN` - `'nan'`, for `null` - `'null'`, otherwise - result of `typeof` operator.

Type
  String

#### (static) getValueKey(obj, value, bAllopt) → {Array|String|null}

Source:
  - adam.js, line 640

Return the name of field (or list of names) having the specified value in the given object or map.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map to be checked.
`value` | Any |  | Value that should be searched for.
`bAll` | Boolean | <optional> | Whether names of all found fields having the specified value should be returned. Default value is `false`.

##### Returns:

Names of fields (when `bAll` is `true`) or a field name having the specified value, or `null` when the object do not contain the specified value.

Type
  Array | String | null

#### (static) getValues(obj, settingsopt) → {Array}

Source:
  - adam.js, line 692
See:
  - checkField

Return list of all or filtered field values of specified object or map.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map to be processed.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter specifying fields that should be selected (see checkField)
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

List of all or filtered field values of specified object.

Type
  Array

#### (static) isEmpty(value) → {Boolean}

Source:
  - adam.js, line 217
See:
  - getClass
  - isSizeMore

Check whether given value is an empty value i.e. `null`, `undefined`, `0`, empty object, empty array, empty map, empty set or empty string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value to be checked.

##### Returns:

`true` if the value is an empty value, otherwise `false`.

Type
  Boolean

#### (static) isKindOf(value, sKind) → {Boolean}

Source:
  - adam.js, line 260
See:
  - getClass
  - getType
  - isEmpty

Check whether given value has (or does not have) specified kind (type or class).

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value to be checked.

`sKind`

String

Type or class for check. Can be any value that is returned by getType and getClass, or one of the following:

- `empty` - check whether the value is empty (see isEmpty)

- `even` - check whether the value is an even integer

- `false` - check whether the value is a false value

- `infinity` - check whether the value is a number representing positive or negative infinity

- `integer` - check whether the value is an integer number

- `negative` - check whether the value is a negative number

- `numeric` - check whether the value is a number or a string that can be converted to number

- `odd` - check whether the value is an odd integer

- `positive` - check whether the value is a positive number

- `real` - check whether the value is a real number

- `true` - check whether the value is a true value

- `zero` - check whether the value is `0`

  If exclamation mark (`!`) is set before the kind, it means that the check should be negated i.e. check whether given value does not have the specified kind. For example, `!real` means: check whether the value is not a real number.

##### Returns:

`true` if value has the specified kind (or does not have when the check is negated), otherwise `false`.

Type
  Boolean

#### (static) isMap(value, bWeakopt) → {Boolean}

Source:
  - adam.js, line 130
See:
  - getClass

Check whether given value is a `Map` or a `WeakMap`.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`value` | Any |  |  | Value that should be checked.
`bWeak` | Boolean | <optional> | `false` | By default the passed value is only checked for `Map`. If you specify `true` for `bWeak`, the value will be also checked for `WeakMap`.

##### Returns:

`true` when the passed value is a `Map` or `WeakMap`, otherwise `false`.

Type
  Boolean

#### (static) isSizeMore(obj, nValue, settingsopt) → {Boolean}

Source:
  - adam.js, line 192
See:
  - getFields

Check whether number of all or filtered fields of specified object/map is more than the given value.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map to be checked.
`nValue` | Number |  | Value that should be used for comparison with number of fields.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter specifying fields that should be counted (see checkField)
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

`true`, when number of all or filtered fields is more than the given value, otherwise `false`.

Type
  Boolean

#### (static) map(obj, action, settingsopt) → {Object}

Source:
  - adam.js, line 1382
See:
  - checkField
  - copy

Create new object containing all or filtered fields of the source object/map/array/set, applying specified action/transformation for field values.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Array | Object |  | Object/map/array/set whose fields should be copied.
`action` | function | String |  | An action/operation that should be applied to get field value that will be saved in created object. See description of `transform` setting of copy.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter that should be used to select fields for copying (see checkField); fields conforming to the filter will be copied in created object
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

Created object containing processed fields.

Type
  Object

#### (static) remove(obj, filter, settingsopt) → {Array|Object}

Source:
  - adam.js, line 1015
See:
  - checkField

Remove filtered fields/elements from specified object/map/array/set.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Array | Object |  | Array, set, object or map to be processed.
`filter` | Any |  | A filter or array of filters specifying fields or elements that should be removed (see checkField).

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` parameter (see checkField)

##### Returns:

Processed array, set, object or map.

Type
  Array | Object

#### (static) reverse(value) → {Any}

Source:
  - adam.js, line 1108

Reverse or negate the given value according to the following rules:

- for array or set: creates a copy and reverses order of elements in it
- for object or map: creates a copy where fields are swapped with their values (i.e. for `{a: "b", c: "d"}` returns `{b: "a", d: "c"}`)
- for string: reverses order of its characters
- for number: returns negated value (i.e. `- value`)
- for boolean: returns negated value (i.e. `! value`)
- otherwise: returns source value without modification

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value to be processed.

##### Returns:

Processed value.

Type
  Any

#### (static) select(filter, from, settingsopt) → {Any}

Source:
  - adam.js, line 875
See:
  - checkField

Return the value of the first element/field in the passed array/object/map/set that satisfies the specified filter(s).

If value passed for selection is not an array/set nor an object/map and `settings.defaultValue` is not set, the value will be returned as is. If no element in the passed array/set satisfies the specified filter(s), `settings.defaultValue` or the last element of the array/set (or `undefined` when the array is empty) will be returned. If no field in the passed object/map satisfies the specified filter(s), `settings.defaultValue` or `undefined` will be returned.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`filter` | Any |  | Filter that should be used to select a value (see checkField for details).
`from` | Any |  | An array/object/map/set from which a value should be selected.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported (setting's default value is specified in parentheses):

- `defaultValue`: `Any` - default value that should be used when no element/field in the passed array/object/map/set satisfies the specified filter(s) or when value of `from` parameter is not an array/set nor an object/map
- `filterConnect`: `String` (`and`) - a boolean connector that should be used when array of filters is specified in `filter` parameter (see checkField for details)

##### Returns:

The value of first element/field in the passed array/object/map/set that satisfies the specified filter(s), or `settings.defaultValue`, or the value of `from` parameter or `undefined`.

Type
  Any

#### (static) split(obj, firstObjFields, settingsopt) → {Array}

Source:
  - adam.js, line 954
See:
  - checkField

Divide given object or map into 2 parts: the first part includes specified fields, the second part includes all other fields.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`obj` | Object |  | Object or map to be divided.
`firstObjFields` | Array | Object | null |  | List of names of fields that should be included in the first part, or an object defining those fields. If value is not specified (`null` or `undefined`), `filter` setting should be used to divide fields into parts.

`settings`

Object

<optional>

Operation settings. Keys are settings names, values are corresponding settings values. The following settings are supported:

- `filter` - a filter that should be used to divide fields into parts (see checkField); fields conforming to the filter will be included in the first part, fields that do not conform to the filter will be included in the second part
- `filterConnect`: `String` - a boolean connector that should be used when array of filters is specified in `filter` setting (see checkField)

##### Returns:

Created parts: item with index 0 is the first part, item with index 1 is the second part.

Type
  Array

#### (static) transform(value, sAction) → {Any}

Source:
  - adam.js, line 1176
See:
  - empty
  - reverse

Transform the given value applying the specified operation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Any | Value to be transformed.

`sAction`

String

Operation that should be applied to transform the value. Can be one of the following:

- `array` - convert the value to array (using `Array(value)`)
- `boolean` - convert the value to boolean value (using `Boolean(value)`)
- `empty` - empty the value (see empty)
- `function` - convert the value to function (using `Function(value)`)
- `integer` - try to convert the value to an integer number (using `Math.round(Number(value)`)
- `map` - try to convert the value to Map (using `new Map(value)` or `new Map([[value, value]])`)
- `number` - try to convert the value to number (using `Number(value)`)
- `object` - convert the value to object (using `Object(value)`)
- `promise` or `resolve` - convert the value to resolved promise (using `Promise.resolve(value)`)
- `reject` - convert the value to rejected promise (using `Promise.reject(value)`)
- `reverse` - reverse the value (see reverse)
- `set` - try to convert the value to Set (using `new Set(value)` or `new Set([value])`)
- `string` - convert the value to string (using `String(value)`)
- otherwise - source value

##### Returns:

Transformed value.

Type
  Any