Field

A field is the most basic building block of fielded. It's where data is usually input by the user, and ultimately, where it's stored.

Instantiating a Field

There are some ways of creating a field. Each of the following methods creates an instance of Field that is bound to a specific type.

Field.text(initialValue)

Creates a text field, optionally taking an initial value. Returns a Field<string | undefined>.

Field.number(initialValue)

Creates a number field, optionally taking an initial value. Returns a Field<number | undefined>.

Field.fromValidator(validator, initialValue)

Creates a field whose type is inferred from a validator, optionally taking an initial value.

const field: Field<string> = Field.fromValidator((value: unknown): asserts value is string => {
  if (typeof value !== "string") {
    throw new Error("Not a string");
  }
});

See .addValidators() for more on the validators usage.

Properties

.type

What the underlying type of the field is. Either text or number.

.rawValue

Observable current value of the field (if any).

const nameField = Field.text("John Doe");

console.log(nameField.rawValue); // prints "John Doe"

.value

Observable value of the field if valid. If invalid, it's undefined.

const username = Field.text();
username.addValidators((value) => {
  if (value === "john") {
    throw new Error("taken");
  }
});

username.set("john");
console.log(username.value); // prints undefined

username.set("johnny");
console.log(username.value); // prints "johnny"

.validation

A Validation object representing the field's state of validation. Undefined unless the field value has been set before.

.errors

Observable list of validation errors of the field. Shorthand for field.validation.errors.

.error

Observable validation error of the field, if any. Shorthand for field.validation.errors[0].

Methods

.set(value)

Updates the value of the field to be value, and validates it. Returns the field itself, useful for chaining.

const value = Field.number().set(42).value;
console.log(value); // prints 42

.reset()

Resets the field to its initial value, and removes validation state.

const field = Field.number(42);
field.set(15).reset();
console.log(field.value); // prints 42

.validate()

Triggers validation using the field's current value. Returns a promise for the finished validation state.

const field = Field.number(42);
const validation = await field.validate();
if (validation.state === "valid") {
  console.log(`The field's value ${validation.value} is valid`);
}

.addValidators(...validators)

Adds one or more validators.
A validator is either a function, or an object with a validate function. It takes the current field value and throws an error, or returns a promise that rejects, if the value is invalid.

const required = {
  validate(value: string | undefined) {
    if (!value) {
      throw new Error("Please type a value.");
    }
  },
};

function validateWeekDay(value: string | undefined) {
  if (value === "saturday" || value === "sunday") {
    throw new Error("Please choose a week day.");
  }
}

const day = Field.text().addValidators(required, validateWeekDay);
day.set("sunday");
console.log(day.error); // "Please choose a week day."

.setError(error)

Sets the field to an invalid state with the specified error. Returns the field itself, useful for chaining.

const name = Field.text();
name.setError("Please type a name.");
console.log(name.error); // "Please type a name."