React Hooks API

createLocalStorage()

Create a storage module by localStorage.

Type

function createLocalStorage<T>(options: CreateStorageOptions<T>): SoftStorage<T>;

Parameters

• options: CreateStorageOptions<T>

  type CreateStorageOptions<T> = {
    /* Storage module key (must be unique) */
    storageModuleKey: string;
    /* Initial value (non-nullable properties must be initialized, 
      and optional properties cannot be initialized) */
    initial: PickNonNullable<T>;
    /* Whether to enable module protection */
    protect?: boolean;
    /* Version number of the storage module */
    version?: number;
    /* Previous version number of the storage module */
    preVersion?: number;
  };
  

Return Value

The function returns an object (SoftStorage) that includes some required variables for useStorage and useStorageHelper.

Example

type UserInfo = {
  token?: string;
  hasSigned: boolean;
};

export const storage = createLocalStorage<UserInfo>({
  storageModuleKey: 'user_info',
  initial: { hasSigned: false },
});

createSessionStorage()

Create a storage module by sessionStorage.

Type

function createSessionStorage<T>(options: CreateStorageOptions<T>): SoftStorage<T>;

Parameters

Same as createLocalStorage() > Parameters

Return Value

Same as createLocalStorage() > Return Value

Example

type UserInfo = {
  token?: string;
  hasSigned: boolean;
};

export const storage = createSessionStorage<UserInfo>({
  storageModuleKey: 'user_info',
  initial: { hasSigned: false },
});

useStorage()

Get states, setters, resetters and checkers from storage module.

Type

function useStorage<T>(storage: SoftStorage<T>): StorageStates<T>;

Parameters

• storage: SoftStorage<T>

  An object returned by createLocalStorage or createSessionStorage.

Return Value

The function returns a Record object, whose key type is StateKey<T>, value type is StorageState<T, K extends keyof T>:

type StorageStates<T> = {
  [SK in StateKey<T>]: RestoreSuffixedKey<SK, 'state'> extends keyof T
    ? StorageState<T, RestoreSuffixedKey<SK, 'state'>>
    : never;
};

TIP

RestoreSuffixedKey<SK, 'state'> here is used to restore the StateKey<T>, for example, the "tokenState" will be restored to "token".

---

StateKey<T> is a string (such as "tokenState"):

type StateKey<T> = SuffixedKeys<T, 'state'>;

TIP

SuffixedKeys<T, 'state'> here is used to add suffix, for example, the "token" will become to "tokenState".

---

And the StorageState<T, K extends keyof T> is an object containing:

• xxx: T[K]
• setXxx: Setter<T[K]>, type of setXxx is SetterKey<K>
• resetXxx: Resetter, type of resetXxx is ResetterKey<K>
• containsXxx: Checker, type of containsXxx is CheckerKey<K>

type StorageState<T, K extends keyof T> = {
  [Key in K]: T[K];
} & {
  [Key in SetterKey<K>]: Setter<T[K]>;
} & {
  [Key in ResetterKey<K>]: Resetter;
} & {
  [Key in CheckerKey<K>]: Checker;
};

Example

import { storage } from './storage';
const {
  tokenState: { token, setToken, resetToken, containsToken },
} = useStorage(storage);

useStorageHelper()

Get instance of storage module helper.

Type

function useStorageHelper<T>(storage: SoftStorage<T>): StorageHelper;

Return Value

type StorageHelper = {
  contains: (key: string) => boolean;
  size: () => number;
  initialize: () => void;
};

Example

import { storage } from './storage';
const storageHelper = useStorageHelper(storage);