Trusted

Make localStorage trusted by solving three problems:

• Validate localStorage values against a schema, or using a custom validation function.
• Set default values to prevent receiving null.
• Prevent designating the same key multiple times.

Install

Install using npm or yarn.

npm install --save trusted

or

yarn add trusted

Basic Usage

// Create a new trusted storage.
const trusted = new Trusted();

// Create an accessor.
const greeting = trusted.string({ key: 'greeting' });

// Use the accessor to get and set the associated value
greeting.set('hello');
greeting.get(); // 'hello'

Adding Validations

Validations are configured when creating the accessor.

Validations can be done using a Yup schema.

const greeting = trusted.string({
  key: 'greeting',
  yupSchema: Yup.string().min(3),
});

greeting.set('hi'); // console.error
greeting.get(); // undefined

greeting.set('hello');
greeting.get(); // 'hello'

Or validations can be done manually using a validate function, which returns true for valid values.

const greeting = trusted.string({
  key: 'greeting',
  validation: value => value.length > 3,
});

greeting.set('hi'); // console.error
greeting.get(); // undefined

greeting.set('hello');
greeting.get(); // 'hello'

Adding Default Values

Default values are returned when the value being retrieved is null or fails validation. Default values must pass validation.

const greeting = trusted.string({
  key: 'greeting',
  yupSchema: Yup.string().oneOf(['hello', 'hola']),
  defaultValue: 'hello',
});

greeting.get(); // 'hello'
localStorage.setItem('greeting', 'sup'); // Manually set invalid value
greeting.get(); // 'hello'

Schema Accessor Types

The schema supports several built-in accessor types.

trusted.string({ key: 'greeting', defaultValue: 'hello' });

trusted.boolean({ key: 'isGreeting', default: true });

trusted.number({ key: 'timesGreeted', default: 5 });

trusted.object({ key: 'greeter', default: { id: '1', name: 'John Doe' } });

trusted.array({ key: 'availableGreetings', defaultValue: ['hello', 'hola'] });

trusted.date({ key: 'greetedAt', defaultValue: new Date() });

trusted.map({
  key: 'greetingByLanguage',
  defaultValue: new Map([
    ['en', 'hello'],
    ['es', 'hola'],
  ]),
});

trusted.set({
  key: 'availableGreetings',
  defaultValue: new Set(['hello', 'hola']),
});

Custom accessors can be created, allowing for user-defined marshaling.

trusted.accessor({
  key: 'greeting',
  marshal: item => item.toString(), // item will be marshaled into string form for localStorage
  unmarshal: string => new Item(string), // string will be unmarshaled back into an Item
});

API Reference

Trusted

Trusted is the provisioner of new accessors. It maintains global configuration and ensures key uniqueness.

Example

const trusted = new Trusted(options);

Options

namespace?: string

String to be used as a prefix for all entries in localStorage.

Methods

registerKey: (key: string) => void

Register a new key. Keys are automatically registered when a new accessor is provisioned, unless otherwise specified. If the provided key is already registered, and exception is thrown.

unregisterKey: (key: string) => void

Unregister a key. Keys are never unregistered automatically.

accessor<T>: (options: TrustedAccessorOptions<T>) => TrustedAccessor<T>

Provision a new accessor. Accessors can be provided with custom marshaling for localStorage compatibility. Provisioning a new accessor will automatically register the provided key. Generally, the type of the accessor can be inferred from the schema or default value, but if no applicable options exist, the type will be unknown until manually specified.

string<T>: (options: TrustedTypeAccessorOptions<T>) => TrustedAccessor<T>

Provision a string accessor. Providing a type enables using the string accessor for unions or enums.

boolean<T>: (options: TrustedTypeAccessorOptions<T>) => TrustedAccessor<T>

Provision a boolean accessor.

number<T>: (options: TrustedTypeAccessorOptions<T>) => TrustedAccessor<T>

Provision a number accessor.

object<T>: (options: TrustedTypeAccessorOptions<T>) => TrustedAccessor<T>

Provision an object accessor.

array<T>: (options: TrustedTypeAccessorOptions<T[]>) => TrustedAccessor<T[]>

Provision an array accessor. Note that T is a singular type.

date<T>: (options: TrustedTypeAccessorOptions<T>) => TrustedTypeAccessor<T>

Provision a date accessor.

map<K, T>: (accessorOptions: TrustedTypeAccessorOptions<Map<K, T>>) => TrustedAccessor<Map<K, T>>

Provision a Map accessor. Note that the Map type is constructed from K and T. K should be a valid key for a Map.

set<T>: (options: TrustedTypeAccessorOptions<Set<T>>) => TrustedAccessor<Set<T>>

Provision a Set accessor. Note that the Set type is constructed from T.

TrustedAccessor

Accessors are used to safely get and set values in localStorage. Accessors pertain to a specific key and hold configuration for validation, default values, and marshaling.

Example

interface Greeter {
  id: string;
  name: string;
}

const greeter = trusted.object<Greeter>({
  key: 'greeter',
  defaultValue: {
    id: '1',
    name: 'Luke',
  },
  yupSchema: Yup.object().shape({
    id: Yup.string().required(),
    name: Yup.string().required(),
  }),
});

TrustedAccessorOptions

key: string

Key to be used for storing value in localStorage. Key will be prefixed with the provided namespace. Keys are automatically registered when the accessor is provisioned, meaning they can't be used more than once, unless otherwise specified.

defaultValue?: T

Default value to be return from get() when the localStorage value is null or fails validation. If the default value fails validation, an exception is thrown.

yupSchema?: Schema<T>

Yup schema to be used for validation. Validation runs on get() and set().

validate?: (value: T) => boolean

Function that returns true for valid options, and false otherwise. Validation runs on get() and set().

skipRegistration?: boolean

When an accessor needs to be provisioned more than once for the same key, registration must be skipped, otherwise the duplicate key will be cause an exception. When true, skipRegistration will ignore the key registry.

marshal?: (value: T) => string

Only available for Trusted.accessor. Marshaling is used to "stringify" values for storage in localStorage (which only allows strings). Many types can be marshaled using JSON.stringify, but some require more complex logic, like Maps and Sets. The marshal function should accept a value and return its string representation.

unmarshal?: (localString: string) => value

Only available for Trusted.accessor. Unmarshaling is used to reverse the marshaling provided above. The unmarshal function should take a string representation and return the hydrated item.

Methods

get: () => T | undefined

Gets the unmarshaled value from localStorage. If the item is not found in localStorage, the default value will be returned. If the default value is returned, the localStorage value will be set to the marshaled default value. Note that the return type will be T if there is a default value specified, otherwise T | undefined.

set: (value: T) => void

Sets a marshaled value in localStorage. If the item fails validation, an error is logged and set results in a no-op.

remove: () => void

Remove the value from localStorage.

unregister: () => void

Unregister the accessor's key from the Trusted key registry.

getKey: () => string

Return the accessor's key.

getDefaultValue: () => T | undefined

Return the accessor's default value, if one was provided.