Migration.getOriginStorage

기능 설명

이전 web.tossmini.com Origin과 현재 apps.tossmini.com Origin의 localStorage, IndexedDB, OPFS 데이터를 함께 가져와요. 가져온 데이터는 앱의 규칙에 맞게 직접 옮기거나 병합하세요.

타입

파라미터는 없어요.

Migration.getOriginStorage(): Promise<{
  previous: OriginStorageDump;
  current: OriginStorageDump;
}>;

previous와 current는 같은 구조예요. previous에는 이전 web.tossmini.com Origin의 값이, current에는 현재 apps.tossmini.com Origin의 값이 들어가요.

interface OriginStorageDump {
  /** 이 스냅샷을 읽은 Origin이에요. */
  origin: string;

  /** localStorage의 모든 키와 원본 문자열 값이에요. */
  localStorage: Record<string, string | null>;

  /** Origin에 있는 IndexedDB 데이터베이스 목록이에요. */
  indexedDB: Array<{
    /** 데이터베이스 이름이에요. */
    name: string;
    /** 데이터베이스 버전이에요. */
    version: number;
    /** 데이터베이스에 있는 object store 목록이에요. */
    objectStores: Array<{
      /** object store 이름이에요. */
      name: string;
      /** object store의 keyPath예요. out-of-line key면 null이에요. */
      keyPath: string | string[] | null;
      /** 키를 자동으로 생성하는 object store인지 나타내요. */
      autoIncrement: boolean;
      /** object store에 정의된 인덱스 목록이에요. */
      indexes: Array<{
        name: string;
        keyPath: string | string[];
        multiEntry: boolean;
        unique: boolean;
      }>;
      /** object store에 저장된 모든 레코드예요. */
      records: Array<{
        /** 커서에서 읽은 레코드 키예요. */
        key: IDBValidKey;
        /** 레코드가 가리키는 object store의 기본 키예요. */
        primaryKey: IDBValidKey;
        /** 저장된 값이에요. 사용 전에 앱의 타입으로 검증해야 해요. */
        value: unknown;
      }>;
    }>;
  }>;

  /** OPFS 루트를 기준으로 한 디렉터리와 파일 목록이에요. */
  opfs: {
    /** 루트부터의 상대 경로예요. 경로 앞에 슬래시가 붙지 않아요. */
    directories: string[];
    files: Array<{
      /** 루트부터의 파일 상대 경로예요. */
      path: string;
      /** 파일의 MIME 타입이에요. 알 수 없으면 빈 문자열일 수 있어요. */
      type: string;
      /** 마지막 수정 시각이에요. Unix epoch 기준 밀리초 값이에요. */
      lastModified: number;
      /** 파일의 원본 바이트예요. 문자열 파일은 TextDecoder로 읽을 수 있어요. */
      data: ArrayBuffer;
    }>;
  };

  /** 저장소별 조회 실패 정보예요. 빈 배열이면 세 저장소를 모두 읽었어요. */
  errors: Array<{
    storage: "localStorage" | "indexedDB" | "opfs";
    message: string;
  }>;
}

OriginStorageDump는 패키지에서 직접 가져올 수 있어요.

import type { OriginStorageDump } from "@apps-in-toss/web-framework";

호출 자체가 실패하면 Promise가 reject돼요. 일부 저장소만 읽지 못했다면 Promise는 resolve되고 원인은 previous.errors 또는 current.errors에 들어가요.

예시 코드

다음 예시는 조회 오류가 없고 현재 Origin에 값이 없을 때만 이전 localStorage 값을 옮겨요. 양쪽에 값이 있으면 현재 값을 유지해요.

import { Migration } from "@apps-in-toss/web-framework";

const SETTINGS_KEY = "my-app:settings";

async function migrateSettings() {
  const { previous, current } = await Migration.getOriginStorage();

  if (previous.errors.length > 0 || current.errors.length > 0) {
    console.error("저장소를 모두 읽지 못했어요.", {
      previous: previous.errors,
      current: current.errors,
    });
    return;
  }

  const previousValue = previous.localStorage[SETTINGS_KEY];
  const currentValue = current.localStorage[SETTINGS_KEY];

  if (currentValue == null && previousValue != null) {
    localStorage.setItem(SETTINGS_KEY, previousValue);
  }
}