Validation guide

Why validation?

Any client-side storage (cookies, localStorage, indexedDb...) is not secure by nature, as the client can forge the value (intentionally to attack your app, or unintentionally because it is affected by a virus or a XSS attack).

It can cause obvious security issues, but also errors and thus crashes (as the received data type may not be what you expected).

Then, any data coming from client-side storage should be checked before used.

Why JSON schemas?

JSON Schema is a standard to describe the structure of a JSON data. You can see this as an equivalent to the DTD in XML, the Doctype in HTML or interfaces in TypeScript.

It can have many uses (it is why you have autocompletion in some JSON files in Visual Studio Code). In this lib, JSON schemas are used to validate the data retrieved from client-side storage.

How to validate simple data

Boolean

this.storage.get('test', { type: 'boolean' })

Integer

this.storage.get('test', { type: 'integer' })

Number

this.storage.get('test', { type: 'number' })

String

this.storage.get('test', { type: 'string' })

Arrays of primitives

this.storage.get('test', {
  type: 'array',
  items: { type: 'integer' },
})

this.storage.get('test', {
  type: 'array',
  items: { type: 'number' },
})

this.storage.get('test', {
  type: 'array',
  items: { type: 'string' },
})

How to validate advanced data

typebox

There is 2 ways to define the JSON schemas:

• directly as in the previous examples
• with the @sinclair/typebox library

npm install @sinclair/typebox

Tuple

In most cases, an array is for a list with values of the same type. In special cases, it can be useful to use arrays with values of different types. It is called tuples in TypeScript. For example: ['test', 1]

// JSON schema
this.storage.get<[string, number]>('test', {
  type: 'array',
  items: [
    { type: 'string' },
    { type: 'number' },
  ],
})

// typebox
import { Type, type Static } from '@sinclair/typebox';

const schema = Type.Tuple([
  Type.String(),
  Type.Number(),
]);

this.storage.get<Static<typeof schema>>('test', schema)

Object

For example:

// JSON schema
import type { JSONSchema } from '@ngx-pwa/local-storage';

interface User {
  name: string;
  isAuthenticated: boolean;
  age?: number;
  favoriteColors: string[];
}

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    isAuthenticated: { type: 'boolean' },
    age: { type: 'number' },
    favoriteColors: {
      type: 'array',
      items: {
        type: 'string',
      },
    },
  },
  required: ['name', 'isAuthenticated', 'favoriteColors']
} satisfies JSONSchema;

this.storage.get<User>('test', schema)

// With typebox library
import { Type, type Static } from '@sinclair/typebox';

const schema = Type.Object({
  name: Type.String(),
  isAuthenticated: Type.Boolean(),
  age: Type.Optional(Type.Number()),
  favoriteColors: Type.Array(Type.String()),
});

this.storage.get<Static<typeof schema>>('test', schema)

Why a schema and a cast?

You may ask why we have to define a TypeScript cast with get<User>() and a JSON schema with schema.

It is because they happen at different steps:

• a cast (get<User>()) just says "TypeScript, trust me, I am telling you it will be a User", but it only happens at compilation time, and given it is client-side storage (reminder: it can be forged), it is not true you known it will be a User.
• the JSON schema (schema) will be used at runtime when getting data in client-side storage for real.

So they each serve a different purpose:

• casting allows you to retrieve the data with the good type instead of any
• the schema allows the library to validate the data at runtime

For now, the library is able to infer the return type based on the JSON schema for primitives (string, number, integer, boolean and array of these), but not for more complex structures like objects.

Validation when writing

While validation is only required when reading storage, when the data is complex, you could store a wrongly structured object by error without noticing, and then get() will fail.

So when storing complex objects, it is better to check the structure when writing too:

this.storage.set('test', user, schema)

import { isDevMode } from '@angular/core';

this.storage.set('test', user, isDevMode() ? schema : undefined)

Additional validation

Options for booleans

• const (not available with typebox)

Options for integers and numbers

• const (not available with typebox)
• enum (not available with typebox)
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum

For example:

this.storage.get('test', {
  type: 'number',
  maximum: 5
})

Options for strings

• const (not available with typebox)
• enum (not available with typebox)
• maxLength
• minLength
• pattern

For example:

this.storage.get('test', {
  type: 'string',
  maxLength: 10
})

Options for arrays

• maxItems
• minItems
• uniqueItems

For example:

this.storage.get('test', {
  type: 'array',
  items: { type: 'string' },
  maxItems: 5
})

Errors vs. undefined / null

If validation fails, it will go in the error callback:

this.storage.get('existing', { type: 'string' })
.subscribe({
  next: (result) => { /* Called if data is valid or null or undefined */ },
  error: (error) => { /* Called if data is invalid */ },
});

But as usual (like when you do a database request), not finding an item is not an error. It succeeds but returns undefined:

this.storage.get('notExisting', { type: 'string' })
.subscribe({
  next: (result) => { result; /* undefined */ },
  error: (error) => { /* Not called */ },
});

Differences from the standard

The role of the validation feature in this library is to check the data against corruption, so it needs to be a strict checking. Then there are important differences with the JSON schema standards.

Restrictions

Types are enforced: each value MUST have a type.

Unsupported features

The following features available in the JSON schema standard are not available in this lib:

• additionalItems
• additionalProperties
• propertyNames
• maxProperties
• minProperties
• patternProperties
• not
• contains
• allOf
• anyOf
• oneOf
• array for type

Custom validation

Validating via this library is recommended but not required. You can use all the native JavaScript operators and functions to validate by yourself. For example:

this.storage.get('test').subscribe((result) => {

  result; // type: unknown

  if (typeof result === 'string') {
    result; // type: string
    result.substr(0, 2); // OK
  }

});

TypeScript will narrow the data type as you validate.

Back to general documentation