@mornya/eventable-storage-libs

Eventable Storage Libs

The project of Eventable & Expirable Storage library.

This project has been created by Vessel CLI. For a simple and quick reference about it, click here.

About

웹스토리지(window.Storage)의 Storage 인터페이스를 구현한 localStorage, sessionStorage 사용시 저장된 데이터 변경에 따른 이벤트를 발생시켜준다.

Installation

해당 라이브러리를 사용 할 프로젝트에서는 아래와 같이 의존성 모듈로 설치한다.

$ npm install --save @mornya/eventable-storage-libs
or
$ yarn add @mornya/eventable-storage-libs

Usage

기본적인 사용방법은 아래와 같다.
타입스크립트 사용시 window.Storage에 대한 글로벌 타입 재선언이 필요하므로 먼저 tsconfig.tson 파일에 타입이 참조되도록 추가한다.

{
  ...
  "typeRoots": [
    "./node_modules/@mornya/eventable-storage-libs/dist"
  ],
  ...
}

애플리케이션 구동 초기에 활성화를 위해 아래와 같이 코드를 추가한다.

import { EventableStorage } from '@mornya/eventable-storage-libs';

if (!EventableStorage.isAvailableStorage('localStorage')) {
  console.error('window.localStorage를 사용 할 수 없습니다!');
} else {
  ...
  EventableStorage.initialize(true);
  ...
}

EventableStorage에서 발생되는 이벤트를 활용하기 위해서는 아래와 같은 방법을 사용한다.

import { EventableStorage } from '@mornya/eventable-storage-libs';

const eventHandler = (event) => {
  console.log(event.detail); // { action: 'set', key: 'foo', value: 'bar' }
};

window.addEventListener('eventableStorage', handler, false);

window.localStorage.setItem('foo', 'bar');

window.removeEventListener('eventableStorage', handler, false);

혹은 제공되는 메소드를 사용한다 (위와 동일한 실행이지만 리스너 등록 허용 갯수 제한이 있다).

import { EventableStorage } from '@mornya/eventable-storage-libs';

const eventHandler: EventableStorage.Listener = (detail: Detail) => {
  console.log(detail); // { action: 'set', key: 'foo', value: 'bar' }
};

EventableStorage.addListener(eventHandler);

window.localStorage.setItem('foo', 'bar');

EventableStorage.removeListener(eventHandler);

Storage methods

Storage 객체 내 제공되는 메소드들은 아래와 같다.

getItem

스토리지에 저장된 값을 얻어온다.

window.localStorage.getItem(key);
window.sessionStorage.getItem(key);

setItem

스토리지에 값을 저장한다. 만료일시(Date타입)를 지정할 수 있다. getItem으로 스토리지에 저장된 값을 읽어올 때 만료일시가 지났다면 해당 키로 저장된 값이 스토리지에서 제거되며, null이 반환된다.

window.localStorage.setItem(key, value[, expireDate]);
window.sessionStorage.setItem(key, value[, expireDate]);

removeItem

스토리지에 저장된 값을 제거한다.

window.localStorage.removeItem(key);
window.sessionStorage.removeItem(key);

clear

스토리지에 저장된 값을 모두 제거한다.

window.localStorage.clear();
window.sessionStorage.clear();

setExpire

존재하는 스토리지 값을 만료 가능한 상태로 만든다. isEventable 값이 true로 설정되면 생성시 이벤트를 발생한다.

window.localStorage.setExpire(key, expireDate[, isEventable]);
window.sessionStorage.setExpire(key, expireDate[, isEventable]);

keys

존재하는 스토리지 키 목록을 리턴한다. 스토리지 값 만료를 위해 생성되는 *.exp 형태의 키는 제외된다.

window.localStorage.keys();
window.sessionStorage.keys();

Modules in the package

본 패키지에는 아래와 같은 모듈들을 포함한다.
제공되는 모듈과 메소드 사용법 등은 코드 스니핏을 참고한다.

isAvailableStorage

window.Storage 객체 존재 여부 확인.

import { isAvailableStorage } from '@mornya/eventable-storage-libs';

const result = isAvailableStorage('localStorage');

console.log(result); // true or false

EventableStorage module

EventableStorage 모듈은 다음과 같은 메소드들을 제공한다.

EventableStorage.initialize

초기화를 위해 앱 실행시점(최초)에 실행한다. 여러 번 호출해도 1회만 실행된다. isActive 파라미터 값은 기본적으로 false 이므로, 바로 활성화 필요시 파라미터를 true로 주거나, EventableStorage.setActive(true) 메소드를 실행해야 한다.

function initialize (isActive: boolean): boolean {}

EventableStorage.isActive

EventableStorage 활성화 혹은 비활성화 여부를 리턴한다.

function isActive (): boolean {}

EventableStorage.setActive

EventableStorage 활성화 혹은 비활성화 처리한다.

function setActive (flag: boolean): void {}

EventableStorage.getMaxListeners

허용 가능한 이벤트 리스너 등록 갯수를 리턴한다.

function getMaxListeners (): number {}

EventableStorage.setMaxListeners

허용 가능한 이벤트 리스너 등록 갯수를 설정한다.

function setMaxListsners (max: number): void {}

EventableStorage.addListener

eventableStorage 리스너를 등록한다. 등록된 리스너의 갯수를 리턴한다.

function addListener (listener: Listener): number {}

리스너 등록은 아래와 같이 두 가지 방법 중 하나로 한다.

// 핸들러 선언
function myEventHandler () { ... }

EventableStorage.addListener(myEventHandler);
/* 혹은 */
window.addEventListener('eventableStorage', myEventHandler, false);

EventableStorage.removeListener

eventableStorage 리스너를 해제한다. 등록된 리스너의 갯수를 리턴한다.

function removeListener (listener: Listener): number {}

리스너 해제는 아래와 같이 두 가지 방법 중 하나로 한다.

// 핸들러 선언
function myEventHandler () { ... }

EventableStorage.removeListener(myEventHandler);
/* 혹은 */
window.removeEventListener('eventableStorage', myEventHandler);

Change Log

프로젝트 변경사항은 CHANGELOG.md 파일 참조.

License

프로젝트 라이센스는 LICENSE 파일 참조.