FCF 2.0 development in progress...
JS
C++
>
Packages
>
fcf-framework-core
>
Functions
>
fcf.build()
[News] [JS Packages API] [JS Downloads] [Donate to the project] [Contacts]
Packages

fcf.build() function

mixed fcf.build(int|string|object|array a_type, mixed a_value)

Package: fcf-framework-core

File: fcf.js

Available from version: 1.0.16

fcf.build() is a data validation and assembly function. It verifies that the input a_value complies with the rules defined in the a_type object, performs type conversion (if enabled), and returns a cleaned copy object or value.

The fcf.build function ensures strict data typing within the application. It transforms raw input data into structured objects that conform to specified schemas, performing deep validation of nested structures.

Arguments

int|string|object|array a_type
- A type object created via fcf.type(). It can be defined in the following formats:
  • string: The type name (e.g., "string", "number", "array", "object", "enum", "set").
  • number: A type constant (e.g., fcf.STRING, fcf.NUMBER).
  • array - Array of Types: Implements "one of many" logic (e.g., `["number", fcf.NUMBER, {type: fcf.UNDEFINED}]`).
  • object- Configuration Object: An object containing the type (type field) and extended validation rules.

Depending on the type, the a_type object may contain the following properties:

Parameter Type Applicable Types Description
type string|int All Mandatory definition of the base type
require boolean

All

Used for arbitrary properties nested within an object (fcf.OBJECT) 		If true, the absence of a value will trigger an error
convert boolean All If true, the function attempts to cast a_value to the target type (e.g., string "10" to number 10).
default mixed All The value returned if a_value is missing or does not match the type.
min number fcf.NUMBER Sets the minimum acceptable value.
max number fcf.NUMBER Sets the maximum acceptable value.
length number fcf.STRING Strict match for the string length.
minLength number fcf.STRING Strict the minimum length.
maxLength number fcf.STRING Strict the maximum length.
item number|string|object|array fcf.ARRAY|fcf.ITERABLE|fcf.NUMBERED Description of the type for elements within a collection
fields object { FIELD_NAME: number|string|object|array } fcf.OBJECT Description of the type for elements within a collection
undeclared undefined|true|false|number|string|object|array fcf.OBJECT Rules for fields not defined in fields.

Can be undefined. Ignore - All undeclared fields are simply ignored, that is, they do not end up in the resulting object.

Can be false. Disallow - If an undeclared field is encountered, an error is raised;

Can be true. Any type - All undeclared fields are included in the resulting object in their original form;

Can be number|string|object|array - Specific type object;

items array fcf.ENUM|fcf.SET A list of allowed values

mixed a_value
- he source value to be processed
Result
mixed
- The validated value. If `convert: true` is enabled, the converted value is returned.
Detailed description

Exceptions:
The function throws `fcf.Exception` in the following cases:
  • NOT_MATCH_TYPE: The value does not match the type or fails nested element validation.
  • FIELD_NOT_SET: A required field (`require: true`) is missing.
  • NUMBER_MIN / NUMBER_MAX: The numeric value is outside the allowed range.
  • STRING_LENGTH / STRING_MIN_LENGTH / STRING_MAX_LENGTH: The string length does not meet the specified constraints.
  • UNDECLARED_FIELD: An undeclared field was found in the object (when `undeclared: false`).

Example: Assembling values of type number

let fcf = require("fcf-framework-core"); let description = { type: fcf.NUMBER, }; let type = fcf.type(description); let value = fcf.build(type, 1); fcf.log.log("APP", value);

Output:

2026-05-22 21:20:41.824 [PID:6551] [LOG] [MOD:APP]: 1

Example: Assembly of an invalid value for the number type

let fcf = require("fcf-framework-core"); let description = { type: fcf.NUMBER, }; let type = fcf.type(description); try { let value = fcf.build(type, "1"); } catch (e){ fcf.log.err("APP", e.message); }

Output:

2026-05-22 21:20:41.838 [PID:6551] [ERR] [MOD:APP]: The value passed does not match the specified types (number)

Example: An invalid value for the number type with conversion support

let fcf = require("fcf-framework-core"); let description = { type: fcf.NUMBER, convert: true, }; let type = fcf.type(description); let value = fcf.build(type, "1"); fcf.log.log("APP", value);

Output:

2026-05-22 21:20:41.838 [PID:6551] [LOG] [MOD:APP]: 1

Example: Constructing an enum value

let fcf = require("fcf-framework-core"); let description = { type: fcf.ENUM, items: ["none", "first", "second"], }; let type = fcf.type(description); let value = fcf.build(type, "none"); fcf.log.log("APP", value);

Output:

2026-05-22 21:20:41.839 [PID:6551] [LOG] [MOD:APP]: none

Example: Enum with default option

Example of constructing an enum value with substitution in case of a type mismatch.

let fcf = require("fcf-framework-core"); let description = { type: fcf.ENUM, items: ["none", "first", "second"], default: "none" // We specify a default value. // This value will be substituted in the // event of a mismatch in the input data. // In the event of an error, an exception is not thrown in the `build` method; // instead, the value from the `default` property is substituted. }; let type = fcf.type(description); let value = fcf.build(type, "error_value"); fcf.log.log("APP", value);

Output:

2026-05-22 22:07:50.147 [PID:9977] [LOG] [MOD:APP]: none

Example: An enum value construction with exception handling

let fcf = require("fcf-framework-core"); let description = { type: fcf.ENUM, items: ["none", "first", "second"], }; let type = fcf.type(description); try { let value = fcf.build(type, "error_value"); } catch (e){ fcf.log.err("APP", e.message); }

Output:

2026-05-22 22:07:50.148 [PID:9977] [ERR] [MOD:APP]: The value passed does not match the specified types (enum["none";"first";"second"])

Example: Assembling a complex object with nested fields.

let fcf = require("fcf-framework-core"); let type = fcf.type("object", { fields: { id: { type: "number", require: true }, // Mark these fields as required, indicating flag require = true. tags: { type: "array", item: "string" }, settings: { type: "object", fields: { active: { type: "boolean", default: true } }, default: { active: true } // If this property was a mistake or it was absent, the default value is set. } }, undeclared: false // We prohibit the presence of unannounced fields in this structure. } ); let input = { id: 1, tags: ["admin", "user"] }; let result = fcf.build(type, input); fcf.log.log("APP", "These settings fields are not passed:"); fcf.log.log("APP", result); input = { id: 1, settings: { active: "error_value"} }; result = fcf.build(type, input); fcf.log.log("APP", "Transmission of invalid data:"); fcf.log.log("APP", result); input = { id: 1, tags: ["admin", "user"], settings: {active: false} }; result = fcf.build(type, input); fcf.log.log("APP", "Transmission of valid data:"); fcf.log.log("APP", result);

Output:

2026-05-22 22:07:50.149 [PID:9977] [LOG] [MOD:APP]: These settings fields are not passed: 2026-05-22 22:07:50.149 [PID:9977] [LOG] [MOD:APP]: { "id" : 1, "tags" : [ "admin", "user" ], "settings" : { "active" : true } } 2026-05-22 22:07:50.150 [PID:9977] [LOG] [MOD:APP]: Transmission of invalid data: 2026-05-22 22:07:50.150 [PID:9977] [LOG] [MOD:APP]: { "id" : 1, "settings" : { "active" : true } } 2026-05-22 22:07:50.152 [PID:9977] [LOG] [MOD:APP]: Transmission of valid data: 2026-05-22 22:07:50.152 [PID:9977] [LOG] [MOD:APP]: { "id" : 1, "tags" : [ "admin", "user" ], "settings" : { "active" : false } }

Special thanks to the companies thanks to which the project is available
VPSDime is an industry leading VPS hosting company that provides virtualized server services with high performance, availability and friendly support.