String Length Constraints

The length of a string value for a property such as the title of a book may have to be constrained, typically rather by a maximum length, but possibly also by a minimum length. In an SQL table definition, a maximum string length can be specified in parenthesis appended to the SQL datatype CHAR or VARCHAR, as in VARCHAR(50).

UML does not define any special way of expressing string length constraints in class diagrams. Of course, we always have the option to use an invariant for expressing any kind of constraint, but it seems preferable to use a simpler form of expressing these property constraints. One option is to append a maximum length, or both a minimum and a maximum length, in parenthesis to the datatype name, like so

Another option is to use min/max constraint keywords in the property modifier list:

Mandatory Value Constraints

A mandatory value constraint requires that a property must have a value. This can be expressed in a UML class diagram with the help of a multiplicity constraint expression where the lower multiplicity is 1. For a single-valued property, this would result in the multiplicity expression 1..1, or the simplified expression 1, appended to the property name in brackets. For example, the following class diagram defines a mandatory value constraint for the property name:

Whenever a class rectangle does not show a multiplicity expression for a property, the property is mandatory (and single-valued), that is, the multiplicity expression 1 is the default for properties.

In an SQL table creation statement, a mandatory value constraint is expressed in a table column definition by appending the key phrase NOT NULL to the column definition as in the following example:

CREATE TABLE persons(
  name  VARCHAR(30) NOT NULL,
  age   INTEGER
)

According to this table definition, any row of the persons table must have a value in the column name, but not necessarily in the column age.

In JavaScript, we can code a mandatory value constraint by a class-level check function that tests if the provided argument evaluates to a value, as illustrated in the following example:

Person.checkName = function (n) {
  if (n === undefined) {
    return "A name must be provided!"; // constraint violation error message
  } else return "";  // no constraint violation
};

With Java Bean Validation, a mandatory property like name is annotated with NotNull in the following way:

@Entity
public class Person {
  @NotNull
  private String name;
  private int age;
}

The equivalent ASP.NET Data Annotation is Required as shown in

public class Person {
  [Required]
  public string name { get; set; }
  public int age { get; set; }
}

Range Constraints

A range constraint requires that a property must have a value from the value space of the type that has been defined as its range. This is implicitly expressed by defining a type for a property as its range. For instance, the attribute age defined for the object type Person in the class diagram above has the range Integer, so it must not have a value like "aaa", which does not denote an integer. However, it may have values like -13 or 321, which also do not make sense as the age of a person. In a similar way, since its range is String, the attribute name may have the value "" (the empty string), which is a valid string that does not make sense as a name.

We can avoid allowing negative integers like -13 as age values, and the empty string as a name, by assigning more specific datatypes as range to these attributes, such as NonNegativeInteger to age, and NonEmptyString to name. Notice that such more specific datatypes are neither predefined in SQL nor in common programming languages, so we have to implement them either in the form of user-defined types, as supported in SQL-99 database management systems such as PostgreSQL, or by using suitable additional constraints such as interval constraints, which are discussed in the next section. In a UML class diagram, we can simply define NonNegativeInteger and NonEmptyString as custom datatypes and then use them in the definition of a property, as illustrated in the following diagram:

In JavaScript, we can code a range constraint by a check function, as illustrated in the following example:

Person.checkName = function (n) {
  if (typeof(n) !== "string" || n.trim() === "") {
    return "Name must be a non-empty string!";
  } else return "";
};

This check function detects and reports a constraint violation if the given value for the name property is not of type "string" or is an empty string.

In a Java EE web app, for declaring empty strings as non-admissible user input we must set the context parameter javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL to true in the web deployment descriptor file web.xml.

In ASP.NET, empty strings are non-admissible by default.

Interval Constraints

An interval constraint requires that an attribute's value must be in a specific interval, which is specified by a minimum value or a maximum value, or both. Such a constraint can be defined for any attribute having an ordered type, but normally we define them only for numeric datatypes or calendar datatypes. For instance, we may want to define an interval constraint requiring that the age attribute value must be in the interval [25,70]. In a class diagram, we can define such a constraint by using the property modifiers min and max, as shown for the age attribute of the Driver class in the following diagram.

In an SQL table creation statement, an interval constraint is expressed in a table column definition by appending a suitable CHECK clause to the column definition as in the following example:

CREATE TABLE drivers(
  name  VARCHAR NOT NULL,
  age   INTEGER CHECK (age >= 25 AND age <= 70)
)

In JavaScript, we can code an interval constraint in the following way:

Driver.checkAge = function (a) {
  if (a < 25 || a > 70) {
    return "Age must be between 25 and 70!";
  } else return "";
};

In Java Bean Validation, we express this interval constraint by adding the annotations Min() and Max() to the property age in the following way:

@Entity
public class Driver {
  @NotNull
  private String name;
  @Min(25) @Max(70)
  private int age;
}

The equivalent ASP.NET Data Annotation is Range(25,70) as shown in

public class Driver{
  [Required]
  public string name { get; set; }
  [Range(25,70)]
  public int age { get; set; }
}

Pattern Constraints

A pattern constraint requires that a string attribute's value must match a certain pattern, typically defined by a regular expression. For instance, for the object type Book we define an isbn attribute with the datatype String as its range and add a pattern constraint requiring that the isbn attribute value must be a 10-digit string or a 9-digit string followed by "X" to the Book class rectangle shown in the following diagram.

In an SQL table creation statement, a pattern constraint is expressed in a table column definition by appending a suitable CHECK clause to the column definition as in the following example:

CREATE TABLE books(
  isbn   VARCHAR(10) NOT NULL CHECK (isbn ~ '^\d{9}(\d|X)$'),
  title  VARCHAR(50) NOT NULL
)

The ~ (tilde) symbol denotes the regular expression matching predicate and the regular expression ^\d{9}(\d|X)$ follows the syntax of the POSIX standard (see, e.g. the PostgreSQL documentation).

In JavaScript, we can code a pattern constraint by using the built-in regular expression function test, as illustrated in the following example:

Person.checkIsbn = function (id) {
  if (!/\b\d{9}(\d|X)\b/.test( id)) {
    return "The ISBN must be a 10-digit string or a 9-digit string followed by 'X'!";
  } else return "";
};

In Java EE Bean Validation, this pattern constraint for isbn is expressed with the annotation Pattern in the following way:

@Entity
public class Book {
@NotNull
  @Pattern(regexp="^\\(\d{9}(\d|X))$")
  private String isbn;
  @NotNull
  private String title;
}

The equivalent ASP.NET Data Annotation is RegularExpression as shown in

public class Book{
  [Required]
  [RegularExpression(@"^(\d{9}(\d|X))$")]
  public string isbn { get; set; }
  public string title { get; set; }
}

Cardinality Constraints

A cardinality constraint requires that the cardinality of a multi-valued property's value set is not less than a given minimum cardinality or not greater than a given maximum cardinality. In UML, cardinality constraints are called multiplicity constraints, and minimum and maximum cardinalities are expressed with the lower bound and the upper bound of the multiplicity expression, as shown in the following diagram, which contains two examples of properties with cardinality constraints.

The attribute definition nickNames[0..3] in the class Person specifies a minimum cardinality of 0 and a maximum cardinality of 3, with the meaning that a person may have no nickname or at most 3 nicknames. The reference property definition members[3..5] in the class Team specifies a minimum cardinality of 3 and a maximum cardinality of 5, with the meaning that a team must have at least 3 and at most 5 members.

It's not obvious how cardinality constraints could be checked in an SQL database, as there is no explicit concept of cardinality constraints in SQL, and the generic form of constraint expressions in SQL, assertions, are not supported by available DBMSs. However, it seems that the best way to implement a minimum (or maximum) cardinality constraint is an on-delete (or on-insert) trigger that tests the number of rows with the same reference as the deleted (or inserted) row.

In JavaScript, we can code a cardinality constraint validation for a multi-valued property by testing the size of the property's value set, as illustrated in the following example:

Person.checkNickNames = function (nickNames) {
  if (nickNames.length > 3) {
    return "There must be no more than 3 nicknames!";
  } else return "";
};

With Java Bean Validation annotations, we can specify

@Size( max=3)
List<String> nickNames
@Size( min=3, max=5)
List<Person> members

Uniqueness Constraints

A uniqueness constraint (or key constraint) requires that a property's value (or the value list of a list of properties in the case of a composite key constraint) is unique among all instances of the given object type. For instance, in a UML class diagram with the object type Book we can define the isbn attribute to be unique, or, in other words, a key, by appending the (user-defined) property modifier keyword key in curly braces to the attribute's definition in the Book class rectangle shown in the following diagram.

In an SQL table creation statement, a uniqueness constraint is expressed by appending the keyword UNIQUE to the column definition as in the following example:

CREATE TABLE books(
  isbn   VARCHAR(10) NOT NULL UNIQUE,
  title  VARCHAR(50) NOT NULL
)

In JavaScript, we can code this uniqueness constraint by a check function that tests if there is already a book with the given isbn value in the books table of the app's database.

Standard Identifiers (Primary Keys)

A unique attribute (or a composite key) can be declared to be the standard identifier for objects of a given type, if it is mandatory (or if all attributes of the composite key are mandatory). We can indicate this in a UML class diagram with the help of the property modifier id appended to the declaration of the attribute isbn as shown in the following diagram.

Notice that such a standard ID declaration implies both a mandatory value and a uniqueness constraint on the attribute concerned.

Often, practitioners do not recommended using a composite key as a standard ID, since composite identifiers are more difficult to handle and not always supported by tools. Whenever an object type does not have a key attribute, but only a composite key, it may therefore be preferable to add an artificial standard ID attribute (also called surrogate ID) to the object type. However, each additional surrogate ID has a price: it creates some cognitive and computational overhead. Consequently, in the case of a simple composite key, it may be preferable not to add a surrogate ID, but use the composite key as the standard ID.

There is also an argument against using any real attribute, such as the isbn attribute, for a standard ID. The argument points to the risk that the values even of natural ID attributes like isbn may have to be changed during the life time of a business object, and any such change would require an unmanageable effort to change also all corresponding ID references. However, the business semantics of natural ID attributes implies that they are frozen. Thus, the need of a value change can only occur in the case of a data input error. But such a case is normally detected early in the life time of the object concerned, and at this stage the change of all corresponding ID references is still manageable.

Standard IDs are called primary keys in relational databases. We can declare an attribute to be the primary key in an SQL table creation statement by appending the phrase PRIMARY KEY to the column definition as in the following example:

CREATE TABLE books(
  isbn   VARCHAR(10) PRIMARY KEY,
  title  VARCHAR(50) NOT NULL
)

In object-oriented programming languages, like JavaScript and Java, we cannot code a standard ID declaration, because this would have to be part of the metadata of a class definition, and there is no support for such metadata. However, we should still check the implied mandatory value and uniqueness constraints.

Referential Integrity Constraints

A referential integrity constraint requires that the values of a reference property refer to an object that exists in the population of the property's range class. Since we do not deal with reference properties in this chapter, we postpone the discussion of referential integrity constraints to Part 4 of our tutorial.

Frozen and Read-Only Value Constraints

A frozen value constraint defined for a property requires that the value of this property must not be changed after it has been assigned. This includes the special case of read-only value constraints on mandatory properties that are initialized at object creation time.

Typical examples of properties with a frozen value constraint are standard identifier attributes and event properties. In the case of events, the semantic principle that the past cannot be changed prohibits that the property values of events can be changed. In the case of a standard identifier attribute we may want to prevent users from changing the ID of an object since this requires that all references to this object using the old ID value are changed as well, which may be difficult to achieve (even though SQL provides special support for such ID changes by means of its ON UPDATE CASCADE clause for the change management of foreign keys).

The following diagram shows how to define a frozen value constraint for the isbn attribute:

In Java, a read-only value constraint can be enforced by declaring the property to be final. In JavaScript, a read-only property slot can be implemented as in the following example:

Object.defineProperty( obj, "teamSize", {value: 5, writable: false, enumerable: true})

where the property slot obj.teamSize is made unwritable. An entire object obj can be frozen with Object.freeze( obj).

We can implement a frozen value constraint for a property in the property's setter method like so:

Book.prototype.setIsbn = function (i) {
  if (this.isbn === undefined) this.isbn = i;
  else console.log("Attempt to re-assign a frozen property!");
}

Beyond property constraints

So far, we have only discussed how to define and check property constraints. However, in certain cases there may be also integrity constraints that do not just depend on the value of a particular property, but rather on

1. the values of several properties of a particular object (object-level constraints),

2. the value of a property before and its value after a change attempt (dynamic constraints),

3. the set of all instances of a particular object type (type-level constraints),

4. the set of all instances of several object types.

In a class model, property constraints can be expressed within the property declaration line in a class rectangle (typically with keywords, such as id, max, etc.). For expressing more complex constraints, such as object-level or type-level constraints, we can attach an invariant declaration box to the class rectangle(s) concerned and express the constraint either in (unambiguous) English or in the Object Constraint Language (OCL). A simple example of an object-level constraint expressed as an OCL invariant is shown in Figure 1-1. An example of an object-level constraint.

A general approach for implementing object-level constraint validation consists of taking the following steps:

1. Choose a fixed name for an object-level constraint validation function, such as validate.

2. For any class that needs object-level constraint validation, define a validate function returning either a ConstraintViolation or a NoConstraintViolation object.

3. Call this function, if it exists, for the given model class,

   1. in the UI/view, on form submission;

   2. in the model class, before save, both in the create and in the update method.

We again consider the book data management problem that was considered in Part 1 of this tutorial. But now we also consider the data integrity rules (or 'business rules') that govern the management of book data. These integrity rules, or constraints, can be expressed in a UML class diagram as shown in Figure 1-2. A design model defining the object type Book with two invariants below.

In this model, the following constraints have been expressed:

1. Due to the fact that the isbn attribute is declared to be the standard identifier of Book, it is mandatory and unique.

2. The isbn attribute has a pattern constraint requiring its values to match the ISBN-10 format that admits only 10-digit strings or 9-digit strings followed by "X".

3. The title attribute is mandatory, as indicated by its multiplicity expression [1], and has a string length constraint requiring its values to have at most 50 characters.

4. The year attribute is mandatory and has an interval constraint, however, of a special form since the maximum is not fixed, but provided by the calendar function nextYear(), which we implement as a utility function.

Notice that the edition attribute is not mandatory, but optional, as indicated by its multiplicity expression [0..1]. In addition to the constraints described in this list, there are the implicit range constraints defined by assigning the datatype NonEmptyString as range to isbn and title, Integer to year, and PositiveInteger to edition. In our plain JavaScript approach, all these property constraints are coded in the model class within property-specific check functions.

The meaning of the design model can be illustrated by a sample data population respecting all constraints:

Provide general utility functions and JavaScript fixes in library files

We add two module files to the lib folder:

1. util.mjs contains the definitions of a few utility functions such as isNonEmptyString(x) for testing if x is a non-empty string.

2. errorTypes.mjs defines classes for error (or exception) types corresponding to the basic types of property constraints discussed above: StringLengthConstraintViolation, MandatoryValueConstraintViolation, RangeConstraintViolation, IntervalConstraintViolation, PatternConstraintViolation, UniquenessConstraintViolation. In addition, a class NoConstraintViolation is defined for being able to return a validation result object in the case of no constraint violation.

Provide an external test data source

Unlike the minimal app which only generates a small data sample for data purposes, this app generates 50 book records, loaded from the JSON file books.json, located in the folder test-data.

Create a start page

The start page index.html takes care of loading CSS style files with the help of the following two link elements:

<link rel="stylesheet" href="css/normalize.min.css"/>
<link rel="stylesheet" href="css/main.css"/>

The first CSS file (normalize.css) is a widely used collection of style normalization rules making browsers render all HTML elements more consistently. The second file (main.css) contains the specific styles of the app's user interface (UI) pages.

Since the app's start page does not provide much UI functionality, but only a few navigation links and two buttons, only a few lines of code are needed for setting up the buttons' event listeners. This is taken care of in an embedded script element of type module:

<script type="module">
  import { handleAuthentication } from "./js/v/accessControl.mjs";
  import Book from "./js/m/Book.mjs";

  handleAuthentication();
  const clearButton = document.getElementById("clearData"),
    generateTestDataButtons = document.querySelectorAll("button.generateTestData");
  // set event handlers for the buttons "clearData" and "generateTestData"
  clearButton.addEventListener("click", Book.clearData);
  for (const btn of generateTestDataButtons) {
    btn.addEventListener("click", Book.generateTestData);
  }
</script>

Notice how the Book class is loaded by importing the module Book.mjs from the js/m folder, as well the handleAuthentication() procedure from the module handleAuthentication.mjs, later invoked to handle access control on the start page.

The JavaScript class model shown on the right hand side in Figure 2-1. From an information design model to a JS class model can be coded step by step to get the code of the model layer of our JavaScript and Firebase web app. These steps are summarized in the following section.

Summary

We want to check if a new property value satisfies all constraints of a property whenever the value of a property is set. A best practice for making sure that new values are validated before assigned is using a setter method for assigning a property, and invoking a check function in the setter. We use JavaScript's implicit getters and setters in combination with an internal property name (like _isbn).

Code the model class as a constructor function

The model class Book is coded as a JS class with a constructor function having a single constructor parameter in the form of a record using ES6 function parameter destructuring:

class Book {
  // using a single record parameter with ES6 function parameter destructuring
  constructor ({isbn, title, year, edition}) {
    // assign properties by invoking implicit setters
    this.isbn = isbn;  // string
    this.title = title;  // string
    this.year = year;  // number (int)
    // edition is an optional property
    if (edition) this.edition = edition;  // optional number (int)
  };
  ...
}

In the constructor body, we assign the values of the constructor parameters to the corresponding class properties. It is helpful to indicate the range of a property in a comment. This requires to map the platform-independent datatypes of the information design model to the corresponding implicit JavaScript datatypes according to the following table.

Since the setters may throw constraint violation errors, the model class Book constructor, and any setter, should be called in a try-catch block where the catch clause takes care of processing errors (at least logging suitable error messages).

Code the property checks

Code the property check functions in the form of class-level ('static') methods. In JavaScript, this means to define them as method slots of the constructor, as in checkIsbn (recall that a constructor is a JS object, since in JavaScript, functions are objects, and as an object, it can have slots).

Take care that all constraints of a property as specified in the class model are properly coded in its check function. This concerns, in particular, the mandatory value and uniqueness constraints implied by the standard identifier declaration (with {id}), and the mandatory value constraints for all properties with multiplicity 1, which is the default when no multiplicity is shown. If any constraint is violated, an error object instantiating one of the error classes listed above in and defined in the file errorTypes.mjs is returned.

For instance, for the checkIsbn operation we obtain the following code:

static checkIsbn( isbn) {
  if (!isbn) return new NoConstraintViolation();
  else if (typeof( isbn) !== "string" || isbn.trim() === "") {
    return new RangeConstraintViolation("The ISBN must be a non-empty string!");
  } else if (!(/\b\d{9}(\d|X)\b/.test( isbn))) {
    return new PatternConstraintViolation(
      'The ISBN must be a 10-digit string or a 9-digit string followed by "X"!');
  } else {
    return new NoConstraintViolation();
  }
}

Notice that, since isbn is the standard identifier attribute of Book, we only check the syntactic constraints in checkIsbn, but we check the mandatory value and uniqueness constraints in checkIsbnAsId, which itself first invokes checkIsbn and then queries the Firestore database to check if the ISBN already exists:

static async checkIsbnAsId( isbn) {
  let validationResult = Book.checkIsbn( isbn);
  if ((validationResult instanceof NoConstraintViolation)) {
    if (!isbn) {
      validationResult = new MandatoryValueConstraintViolation(
        "A value for the ISBN must be provided!");
    } else {
      const bookDocSn = await getDoc( fsDoc( fsDb, "books", isbn));
      if (bookDocSn.exists()) {
        validationResult = new UniquenessConstraintViolation(
           "There is already a book record with this ISBN!");
      } else {
        validationResult = new NoConstraintViolation();
      }
    }
  }
  return validationResult;
}

Notice that all check functions should be able to deal both with proper data values (that are from the attribute's range type) and also with string values that are supposed to represent proper data values, but have not yet been converted to the attribute's range type. We take this approach for avoiding datatype conversions in the user interface ("view") code. Notice that all data entered by a user in an HTML form field is of type String and must be converted before its validity can be checked and it can be assigned to the corresponding property. It is preferable to perform these type conversions in the model code, and not in the user interface code.

For instance, in our example app, we have the integer-valued attribute year. When the user has entered a value for this attribute in a corresponding form field, in the Create or Update user interface, the form field holds a string value. This value is first passed to checkYear method and then to the Book.add or Book.update methods, where this string value is converted to an integer and assigned to the year attribute.

Code the property getters and setters

For each property, we define implicit getters and setters using the predefined JS keywords get and set:

Code the setter operations as (instance-level) methods. In the setter, the corresponding check function is invoked and the property is only set, if the check does not detect any constraint violation. Otherwise, the constraint violation error object returned by the check function is thrown. For instance, the get isbn and set isbn operations are coded in the following way:

get isbn() {
  return this._isbn;
}
set isbn(n) {
  const validationResult = Book.checkIsbn(n);
  if (validationResult instanceof NoConstraintViolation) {
    this._isbn = n;
  } else {
    throw validationResult;
  }
}

There are similar getters and setters for the other properties (title, year and edition).

Object-to-Storage Mapping

Firestore supports an Object-to-Storage mapping from typed objects to JS/Firestore records and, vice versa, from JS/Firestore records to typed objects, by defining two conversion functions:

• toFirestore, used every time a write operation is invoked, converting a typed JS object (instantiating a model class) into a JS record.

• fromFirestore, used every time a read operation is invoked, converting a JS record into a typed JS object instantiating a specific model class.

Book.converter = {
  toFirestore: function (book) {
    const data = {
      isbn: book.isbn,
      title: book.title,
      year: parseInt( book.year)
    };
    if (book.edition) data.edition = parseInt( book.edition);
    return data;
  },
  fromFirestore: function (snapshot, options) {
    const data = snapshot.data( options);
    return new Book( data);
  }
};

Such a converter can be applied to a Firestore collection reference with the help of the built-in method withConverter:

const bookDocRef = fsDoc( fsDb, "books", book.isbn).withConverter( Book.converter);

Whenever a Firestore operation is performed, the data converter function will act accordingly, distinguishing between write operations (toFirestore) and read operations (fromFirestore).

Data Management Operations

In addition to defining the model class in the form of a constructor function with property definitions, checks, setters and getters, we also need to define the following data management operations as class-level methods of the model class:

• Book.add for creating a new Book instance and adding it to the collection of all Book instances.
• Book.update for updating an existing Book instance.
• Book.destroy for deleting a Book instance from Firestore.
• Book.retrieve for retrieving a Book instance.
• Book.retrieveAll for retrieving all Book instances from Firestore.
• Book.generateTestData for creating sample book records to be used as test data.
• Book.clearData for clearing the book data store.

Notice that for the change operations add (create), we need to implement an asynchronous invocation of checkIsbnAsId, working as an all-or-nothing policy, whenever there is a constraint violation for the isbn property. When a constraint violation is detected in this checker, the object creation attempt fails, and instead a constraint violation error message is created. Otherwise, the new book object is added to Firestore and a status message is created, as shown in the following program listing:

Book.add = async function (slots) {
  let book = null;
  try {
    // validate data by creating Book instance
    book = new Book( slots);
    // invoke asynchronous ID/uniqueness check
    let validationResult = await Book.checkIsbnAsId( book.isbn);
    if (!validationResult instanceof NoConstraintViolation) throw validationResult;
  } catch (e) {
    console.error(`${e.constructor.name}: ${e.message}`);
    book = null;
  }
  if (book) {
    try {
      const bookDocRef = fsDoc( fsDb, "books", book.isbn).withConverter( Book.converter);
      await setDoc( bookDocRef, book);
      console.log(`Book record "${book.isbn}" created!`);
    } catch (e) {
      console.error(`${e.constructor.name}: ${e.message} + ${e}`);
    }
  }
};

When an object of a model class is to be updated, we first retrieve a book record from Firestore to use it as a reference to check what properties has been updated, and only if a property has changed the update is performed on the database, and we report this in a status log.

Normally, all properties defined by a model class, except the standard identifier attribute, can be updated. It is, however, possible to also allow updating the standard identifier attribute. This requires special care for making sure that all references to the given object via its old standard identifier are updated as well.

When a constraint violation is detected in one of the checkers invoked in Book.update, the object update attempt fails, and instead the error message of the constraint violation object thrown by the checker and caught in the update method is shown, and the record is not updated. Otherwise, a status message is created, as shown in the following program listing:

Book.update = async function (slots) {
  let noConstraintViolated = true,
    validationResult = null,
    bookBeforeUpdate = null;
  const bookDocRef = fsDoc( fsDb, "books", slots.isbn).withConverter( Book.converter),
    updatedSlots = {};
  try {
    // retrieve up-to-date book record
    const bookDocSn = await getDoc( bookDocRef);
    bookBeforeUpdate = bookDocSn.data();
  } catch (e) {
    console.error(`${e.constructor.name}: ${e.message}`);
  }
  try {
    if (bookBeforeUpdate.title !== slots.title) {
      validationResult = Book.checkTitle( slots.title);
      if (validationResult instanceof NoConstraintViolation) updatedSlots.title = slots.title;
      else throw validationResult;
    }
    if (bookBeforeUpdate.year !== parseInt( slots.year)) {
      validationResult = Book.checkYear( slots.year);
      if (validationResult instanceof NoConstraintViolation) updatedSlots.year = parseInt( slots.year);
      else throw validationResult;
    }
    if (slots.edition && bookBeforeUpdate.edition !== parseInt( slots.edition)) {
      // slots.edition has a non-empty value that is different from the old value
      validationResult = Book.checkEdition( slots.edition);
      if (validationResult instanceof NoConstraintViolation) updatedSlots.edition = parseInt( slots.edition);
      else throw validationResult;
    } else if (!slots.edition && bookBeforeUpdate.edition) {
      // slots.edition has an empty value while the old value was not empty
      updatedSlots.edition = await updateDoc( bookDocRef, {edition: deleteField()});
    }
  } catch (e) {
    noConstraintViolated = false;
    console.error(`${e.constructor.name}: ${e.message}`);
  }
  if (noConstraintViolated) {
    const updatedProperties = Object.keys(updatedSlots);
    if (updatedProperties.length) {
      await updateDoc(bookDocRef, updatedSlots);
      console.log(`Property(ies) "${updatedProperties.toString()}" modified for book record "${slots.isbn}"`);
    } else {
      console.log(`No property value changed for book record "${slots.isbn}"!`);
    }
  }
};

Notice that optional properties, like edition, need to be treated in a special way. If the user doesn't enter any value for them in a Create or Update user interface, the form field's value is the empty string "". In the case of an optional property, this means that the property is not assigned a value in the add use case, or that it is unset if it has had a value in the update use case. This is different from the case of a mandatory property, where the empty string value obtained from an empty form field may or may not be an admissible value. Notice the use of the Firestore method deleteField() used in combination with updateDoc, for deleting an specific field during the Update operation.

When an object of a model class is to be deleted, the destroy procedure is invoked.

Book.destroy = async function (isbn) {
  try {
    await deleteDoc( fsDoc(fsDb, "books", isbn));
    console.log(`Book record "${isbn}" deleted!`);
  } catch (e) {
    console.error(`Error deleting book record: ${e}`);
  }
};

Whenever an individual object of a model class is to be retrieved, we can use this simplified version of the function Book.retrieve:

Book.retrieve = async function( isbn) {
  try {
    const bookRec = (await getDoc( fsDoc(fsDb, "books", isbn)
      .withConverter( Book.converter))).data();
    console.log(`Book record "${bookRec.isbn}" retrieved.`);
    return bookRec;
  } catch (e) {
    console.error(`Error retrieving book record: ${e}`);
  }
};

And when all records in a Firestore collection are to be retrieved, we can again use a simplified version of function Book.retrieveAll. However this time it is introduced the option to order the resulting records, using the orderBy() method. Later we will see on the view code the implementation of a HTML select element to trigger this function with the parameter order, being for instance isbn, title and year.

Book.retrieveAll = async function (order) {
  if (!order) order = "isbn";
  const booksCollRef = fsColl( fsDb, "books"),
    q = fsQuery( booksCollRef, orderBy( order));
  try {
    const bookRecs = (await getDocs( q.withConverter( Book.converter))).docs.map( d => d.data());
    console.log(`${bookRecs.length} book records retrieved ${order ? "ordered by " + order : ""}`);
    return bookRecs;
  } catch (e) {
    console.error(`Error retrieving book records: ${e}`);
  }
};

For testing the app, 50 book records can be generated by, first retrieving data stored in JSON format in an external file books.json, using the Fetch API. Then the retrieved data is parsed as JSON using the method json(). Finally, every record is stored to Firestore using JS promises in parallel, using the Promise.all method.

Book.generateTestData = async function() {
  try {
    console.log("Generating test data...");
    const response = await fetch( "../../test-data/books.json");
    const bookRecs = await response.json();
    await Promise.all( bookRecs.map( d => Book.add( d)));
    console.log(`${bookRecs.length} books saved.`);
  } catch (e) {
    console.error(`${e.constructor.name}: ${e.message}`);
  }
};

Inversely, whenever we need to empty the Book collection, we use function Book.clearData. First all the book records in the collection books are retrieved from Firestore, and then iteratively and asynchronously we use the Promise.all method to delete every record, this time reusing the Book.destroy() function.

Book.clearData = async function() {
  if (confirm("Do you really want to delete all book records?")) {
    try {
      console.log("Clearing test data...");
      const booksCollRef = fsColl( fsDb, "books");
      const booksQrySn = (await getDocs( booksCollRef));
      await Promise.all( booksQrySn.docs.map( d => Book.destroy( d.id)))
      console.log(`${booksQrySn.docs.length} books deleted.`);
    } catch (e) {
      console.error(`${e.constructor.name}: ${e.message}`);
    }
  }
};

By invoking checkValidity() on the form element, we make sure that the form data is only saved (by Book.add), if there is no constraint violation. After the property checks are executed on an invalid form, the browser takes control and tests if the predefined property validity has an error flag for any form field. In our approach, since we use setCustomValidity, the validity.customError would be true. If this is the case, the custom constraint violation message will be displayed (in a bubble) and the submit event will be suppressed.

The showProgressBar function is used to show or hide a HTML <progress> element while the invoked asynchronous function is happening. This visual cue is used to give feedback about the interaction on the submit event, communicating that our app is in control now processing the order. Its counterpart, hideProgressBar, hides the progress element after the operation finishes.

In the UI of the use case Update, which is handled in v/updateBook.mjs, we do not have an input, but rather an output field for the standard identifier attribute isbn, since it is not supposed to be modifiable. Consequently, we don't need to validate any user input for it.

The implementation on the view code start by retrieving all book records from the Firestore collection, and then initializing the form element with its values, the save button and the book selector, which is a select element inside the form.

const bookRecords = await Book.retrieveAll();
...
const formEl = document.forms["Book"],
  saveButton = formEl.commit,
  selectBookEl = formEl.selectBook;

Additionally, we need to set up a selection list (in the form of an HTML select element) with the retrieved book records, allowing the user to select a book record in the first step, before its data can be modified. This requires to add a change event listener on the select element such that the fields of the UI can be filled with the data of the selected object. Finally, all custom validation errors messages are deleted with setCustomValidity(""), in case they were set before.

fillSelectWithOptions(bookRecords, selectBookEl, "isbn", "title");
// when a book is selected, populate the form with its data
selectBookEl.addEventListener("change", async function () {
  const bookKey = selectBookEl.value;
  if (bookKey) {
    // retrieve up-to-date book record
    const bookRecord = await Book.retrieve( bookKey);
    for (const a of ["isbn", "title", "year", "edition"]) {
      formEl[a].value = bookRecord[a] !== undefined ? bookRecord[a] : "";
      // delete custom validation error message which may have been set before
      formEl[a].setCustomValidity("");
    }
  } else {
    formEl.reset();
  }
});

There is no need to set up responsive validation for the standard identifier attribute isbn, but for all other form fields, as shown above for the Create use case.

formEl["title"].addEventListener("input", function () {
  formEl["title"].setCustomValidity(
    Book.checkTitle( slots.title).message);
});
formEl["year"].addEventListener("input", function () {
  formEl["year"].setCustomValidity(
    Book.checkYear( slots.year).message);
});
if (formEl["edition"].value) {
  formEl["edition"].addEventListener("input", function () {
    formEl["edition"].setCustomValidity(
      Book.checkEdition(slots.edition).message);
  });
}

The last step in the UI is handling the submit event, when the user clicks on the "Update" button, which consists in five steps:

1. initialize UI elements and the book key value (bookIdRef),
2. prepare the slots object,
3. invoke the constraint violations checkers and set error messages on the UI, and
4. Invoke the update function with the slots object.
5. Neutralize the submit event.

updateButton.addEventListener("click", function () {
  const formEl = document.forms["Book"],
    selectBookEl = formEl["selectBook"],
    bookIdRef = selectBookEl.value;
  if (!bookIdRef) return;
  const slots = {
    isbn: formEl["isbn"].value,
    title: formEl["title"].value,
    year: formEl["year"].value
  };
  // set error messages in case of constraint violations
  formEl["title"].addEventListener("input", function () {
    formEl["title"].setCustomValidity(
      Book.checkTitle( slots.title).message);
  });
  formEl["year"].addEventListener("input", function () {
    formEl["year"].setCustomValidity(
      Book.checkYear( slots.year).message);
  });
  if (formEl["edition"].value) {
    formEl["edition"].addEventListener("input", function () {
      formEl["edition"].setCustomValidity(
        Book.checkEdition(slots.edition).message);
    });
  }
  if (formEl.checkValidity()) {
    Book.update( slots);
    // update the selection list option
    selectBookEl.options[selectBookEl.selectedIndex].text = slots.title;
    formEl.reset();
  }
});
// neutralize the submit event
formEl.addEventListener("submit", function (e) {
  e.preventDefault();
});

The logic for setting up the UI for the Delete use case is similar. We only need to take care that the object to be deleted can be selected by providing a selection list, like in the Update use case. No validation is needed for the Delete use case.

Basic match/allow pattern

For defining Security Rules we follow this simple pattern:

1. declare service (Firestore, in this case),
2. match a database path, and
3. apply conditions to allow access to data in that path, using specific methods.

rules_version = '2';
service cloud.firestore {
  match <path> {
    allow <methods>: <condition>;
  }
}

Methods in the allow clause

Each allow statement includes at least one method to give access for incoming requests, for reading or writing data, and a convenience method can be used to allow access to standard methods, as shown in the following table:

Being conditions optional, it is possible to write allow statements as simple as

allow read: false;
allow write: false;

or

allow read: true;
allow write: true;

Notice however that such simplicity may either compromise security or restrict undesirable access to our Firebase project, so for achieving granularity in our restrictions we can use conditions.

Conditions

Firebase Security Rules can be written with a syntax similar to JavaScript. For defining conditions web developers use

• wildcard variables, used to define specificity in a match path
  • for any book record/document in the books table/collection, or

    match /books/{book}/{document=**}

  • for any record in the books table/collection, and its subcollections

    match /{path=**}/songs/{song}

• request objects, represent the incoming request, with the following attributes: request.auth, request.path, request.query.resource, request.time, and request.writeFields.
• resource objects, represent an available recourse (collection or document).

Example 1: this condition allows to create a new document if the user is authenticated with verified email:

allow create: if request.auth.token.email_verified == true

Example 2: this condition allows to create a new document if its ISBN field is equal to "0279872631".

allow write: if request.resource.data.isbn == "0279872631"

Creating Security Rules step by step

Going through each line in the following Security Rules file, we found

• line 1: the latest version of the Firebase Security Rules language is v2, this statement goes always on the first line.
• line 2: defines the Firebase service Firestore.
• line 3: the {database} clause indicates that these rules apply to all databases in Firestore.
• line 4: defines a rule for every record/document within the "books" table/collection, even its subcollections.
• line 5: defines a rule that allows to create, update and delete records/documents if the user is registered with verified email.
• line 6: defines a rule that allows to get individual documents and queries or collections, even if the user is not authenticated (anonymous).

1
2
3
4
5
6
7
8
9

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /books/{document=**} {
      allow write: if request.auth.token.email_verified == true;
      allow read: if request.auth != null;
    }
  }
}

Functions

In the quest for a granular control to secure a web app, rules may become very complex, and functions are the way to reuse code in our Security Rules. Even though Security rules are written in a similar-to-JavaScript DSL (domain-specific language) we must know its limitations:

1. can contain a unique return statement.
2. can invoke other functions, but their recursive capacities are limited.
3. can use let to define variables, but must contain a return statement.

In this example Security Rules, the function checkIsbnAsId is invoked with the isbn value obtained from the request object:

service cloud.firestore {
  match /databases/{database}/documents {
    function checkIsbnAsId(isbn) {
      return !(exists(/databases/$(database)/documents/books/$(isbn)));
    }
    match /books/{document=**} {
      allow create: if request.auth.token.email_verified == true &&
        checkIsbnAsId(request.resource.data.isbn) == true;
    }
  }
}

Security Rules for the Validation App

For implementing backend data validation with Security Rules, we have to copy the check functions from the app's model classes and rewrite them using the Security Rules language, which has a syntax that is similar to the syntax of JS. The main components of Security Rules for the validation app are:

1. four functions to check ISBN, year and edition attributes: checkIsbn uses Firebase Security Rules regular expressions to check how ISBN is well formed, and checkIsbnAsId edition
   • checkIsbn uses Firebase Security Rules regular expressions to check if ISBN is well formed, and

     function checkIsbn( isbn) {
       return isbn.matches('^[0-9]+[0-9X]$') 
              && isbn != null;
     }

   • checkIsbnAsId checks if another document on the books collection exists with same ISBN,

     function checkIsbnAsId( isbn) {
       return !(exists(/databases/$(database)/documents/books/$(isbn)));
     }

   • checkYear checks all constraints for the attribute year: min, max and integer, and

     function checkYear( year) {
       return (timestamp.date( year,1,1).toMillis() < request.time.toMillis() 
               && year > 1459 
               && year is int 
               && year != null);
     }

   • checkEdition checks if the edition attribute is present, and if it is integer,

     function checkEdition( edition) {
       return (edition is int || !("edition" in request.resource.data));
     }

2. one allow statement with the convenience method read, for giving access to read to any anonymous user,

   allow read: if request.auth != null;

3. one allow statement with the standard method create, for giving access to write to registered users with verified email, in the process the ISBN, year and edition attributes are checked,

   allow create: if request.auth.token.email_verified == true
                 && checkIsbnAsId( request.resource.data.isbn) == true
                 && checkIsbn( request.resource.data.isbn) == true
                 && request.resource.data.title != null
                 && checkYear( request.resource.data.year) == true
                 && checkEdition( request.resource.data.edition);

4. one allow statement with the standard method update, for giving access to write to registered users with verified email, and since the incoming data is mean to update a document we use the clause diff to compare incoming data (request.resource.data) with stored data (resource.data); but the update may only happen on the attributes title, year and edition, and not on ISBN, which never should be updated

   allow update: if request.auth.token.email_verified == true
                    && (request.resource.data.diff( resource.data).affectedKeys()
                     .hasOnly(['title', 'year', 'edition']))
                    && request.resource.data.year != null ?
                      checkYear( request.resource.data.year) : true
                    && request.resource.data.edition != null ?
                      checkEdition( request.resource.data.edition) : true;

5. one allow statement with the standard method delete, for giving access to delete to authenticated users with verified email.

   allow delete: if request.auth.token.email_verified == true;

These Security Rules are located in the file 2-ValidatioApp/firestore.rules.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    /** VALIDATION FUNCTIONS **/
    // check how ISBN is formed: a 10-digit string or a 9-digit string followed by "X"
    function checkIsbn( isbn) {
      return isbn.matches('^[0-9]+[0-9X]$')
             && isbn != null;
    }
    // check if exist document with same ISBN
    function checkIsbnAsId( isbn) {
      return !(exists(/databases/$(database)/documents/books/$(isbn)));
    }
    // check all constraints for year: min, max and integer
    function checkYear( year) {
      return (timestamp.date( year,1,1).toMillis() < request.time.toMillis()
             && year > 1459
             && year is int
             && year != null);
    }
    // if present, check if it is integer
    function checkEdition( edition) {
      return (edition is int || !("edition" in request.resource.data));
    }
    /** VALIDATION RULES **/
    match /{books}/{document=**} {
      /** RULES FOR allow read WITH CONVENIENCE METHOD - LOW GRANULARITY **/
      /** NO authentication required **/
      allow read: if request.auth != null;

      /** RULES FOR allow write WITH STANDARD METHODS - HIGH GRANULARITY **/
      /** authentication required **/
      //validate when create new book record
      allow create: if request.auth.token.email_verified == true
                       && checkIsbnAsId( request.resource.data.isbn) == true
                       && checkIsbn( request.resource.data.isbn) == true
                       && request.resource.data.title != null
                       && checkYear( request.resource.data.year) == true
                       && checkEdition( request.resource.data.edition);

      // validate when update book record
      allow update: if request.auth.token.email_verified == true
                       && (request.resource.data.diff( resource.data).affectedKeys()
                        .hasOnly(['title', 'year', 'edition']))
                       && request.resource.data.year != null ?
                           checkYear( request.resource.data.year) : true
                       && request.resource.data.edition != null ?
                           checkEdition( request.resource.data.edition) : true;

      // validate when delete book record
      allow delete: if request.auth.token.email_verified == true;
    }
  }
}

You can run the validation app from our server or download the code as a ZIP archive file.

Attribute-level access control

More fine-grained access control can be achieved by specifying access control rules for specific fields.

Testing security rules in Firestore

While writing Security Rules we need to test our rules in real time, and deploying our rules to Firebase every time we change them is not an efficient approach. The advised tool is Firebase Emulator, which allows running a Firestore database locally.

Using regular expressions

Sometimes using a regular expression is the only way to define a validations constraint. Firebase uses RE2, a Regular Expression software created by Google.

Adding an object-level validation function

When object-level validation (across two or more properties) is required for a model class, we can add a custom validation function validate to it, such that object-level validation can be performed before save by invoking validate on the object concerned. For instance, for expressing the constraint defined in the class model shown in Figure 1-1. An example of an object-level constraint, we define the following validation function:

Author.prototype.validate = function () {
  if (this.dateOfDeath && this.dateOfDeath < this.dateOfBirth) {
    throw new ConstraintViolation("The dateOfDeath must be after the dateOfBirth!");
  }
};

When a validate function has been defined for a model class, it can be invoked in the create and update methods. For instance,

Author.add = function (slots) {
  var author = null;
  try {
    author = new Author( slots);
    author.validate();
  } catch (e) {
    console.log( e.constructor.name +": "+ e.message);
  }
};

Handling success and error messages

We have implemented a good solution for handling error messages throughout this tutorial, showing them contextually in each input field. However, we should consider extending this solution to show success messages on the user interface when the user completes an action successfully, for instance, for any CRUD use case or in the authentication workflow. Each app in this series of tutorials handles success messages, but only on the JavaScript console.

Boilerplate code

An issue with the do-it-yourself code of this example app is the boilerplate code needed

1. per model class for the storage management methods add, update, destroy, etc.;

2. per model class and property for getters, setters and validation checks.

While it is good to write this code a few times for learning app development, you don't want to write it again and again later when you work on real projects. In our mODELcLASSjs tutorial, we present an approach how to put these methods in a generic form in a meta-class, such that they can be reused in all model classes of an app.

Configuring the UI for preventing invalid user input

Many of the new HTML5 input field types (like number, tel, email, url, date (together with datetime-local, time and month) or color) are intended to allow web browsers rendering corresponding input elements in the form of UI widgets (like a date picker or a color picker) that limit the user's input options such that only valid input is possible. In terms of usability, it's preferable to prevent users from entering invalid data instead of allowing to enter it and only then checking its validity and reporting errors.

Input fields for decimal number input should not be defined like

<input type="number" name="..." />

but rather like

<input type="text" inputmode="decimal" name="..." />

because this provides for a better user experience on mobile phones.

Improving the user experience by showing helpful auto-complete suggestions

While browsers have heuristics for showing auto-complete suggestions, you cannot rely on them, and should better add the autocomplete attribute with a suitable value. For instance, in iOS Safari, setting the input type to "tel" does only show auto-complete suggestions if autocomplete="tel" is added.

HTML5 defines more than 50 possible values for the autocomplete attribute. So, you have to make an effort looking up the one that best suits your purposes.

You can also create your own custom auto-complete functionality with datalist.