DeviceLibraryAdapter — @gj-kit/expo-media

@gj-kit/expo-media/core에서 공개하는 interface입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

import { DeviceLibraryAdapter } from '@gj-kit/expo-media/core';

시그니처, 매개변수, 반환 타입

interface DeviceLibraryAdapter {
    /**
     * ⚠ Android 13+에서 granular 목록(`['photo','video']`)을 **반드시** 지정할 것. 생략하면
     * 매니페스트의 모든 권한이 대상이 되어, 거부된 `READ_MEDIA_AUDIO`가 유효한 사진·동영상 허용을
     * 거부처럼 보이게 만든다(Android의 "선택한 사진" 접근 모드 포함) — §7 하드닝 5.
     *
     * ⚠ **순수 위임이다.** "언제 요청할 것인가"(현재 권한 조회 → `!granted && canAskAgain`일 때만
     * 요청)는 어댑터가 아니라 core가 소유한다 — `DeviceLibrary.ensurePermission()`(§5.4-④(c), G17).
     * 어댑터에 두면 (i) 3자 어댑터마다 규칙이 갈리고, (ii) iOS에서 `canAskAgain=false`인데 재요청해
     * 아무 일도 일어나지 않는 **UI 데드록**이 재발한다.
     * 어댑터의 몫은 네이티브 응답을 `MediaPermission`으로 매핑하는 것까지다
     * (`accessPrivileges === 'limited'` → `limited: true` 포함).
     */
    requestPermission(): Promise<MediaPermission>;
    /** 순수 조회 — 요청하지 않는다. 합성 규칙은 core가 갖는다(위 참조). */
    getPermission(): Promise<MediaPermission>;
    /**
     * ⚠ **정렬 계약: creationTime 내림차순(최신 우선).** 전신 `devicePhotoLibrary.ts:220`
     *   `sortBy: [[SortBy.creationTime, false]]`.
     * core는 재정렬하지 않는다 — 페이지 단위 재정렬은 전역 순서를 보장하지 못하면서
     * (다음 페이지가 이전 페이지보다 최신일 수 있다) `endCursor`는 여전히 어댑터 순서를 따라가
     * **커서와 표시 순서가 어긋난다**(§5.4-④(d)). 이 계약을 어기면 그리드 순서와 무한스크롤
     * 커서가 함께 깨지며, **타입도 가드도 그것을 잡지 못한다**.
     *
     * ⚠ 자산별 `getAssetInfo` 호출 금지 — 60개 원본을 직렬 해석하면 페이지당 ~20초다.
     * 그리드는 raw uri(iOS `ph://`)를 그대로 그린다. 네이티브 이미지 로더가 PHImageManager에
     * 뷰 크기 썸네일을 요청하므로 시스템 사진 그리드와 같은 방식이 된다. 원본 바이트는
     * 업로드 시점의 resolve에서만 해석한다(§7.1).
     */
    listAssets(input: {
        readonly albumId?: string | null | undefined;
        readonly after?: string | undefined;
        readonly pageSize: number;
        readonly kinds: readonly MediaKind[];
    }): Promise<DeviceAssetPage>;
    /**
     * 원본 목록을 **그대로** 반환한다 — 필터·정렬 금지.
     * `count > 0` 필터와 count 내림차순 정렬은 core가 수행하므로
     * (전신 `devicePhotoLibrary.ts:243-250`의 정책을 core로 승격) 어댑터가 중복 수행할 이유가 없다.
     * 전량을 한 번에 반환하는 in-memory 목록이라 core가 전역 순서를 보장할 수 있다는 점이
     * `listAssets`와의 차이다(§5.4-④(d)).
     */
    listAlbums(): Promise<readonly DeviceAlbum[]>;
    /**
     * ⚠ `downloadFromNetwork`는 **필수 인자**다(§6.1-④). 옵셔널로 두면 어댑터 구현자가
     * 플랫폼 기본값(Expo legacy API는 `true`)을 흘려 iCloud 원본을 무단으로 셀룰러 다운로드한다 —
     * 전신이 실제로 겪은 사고다.
     * 타임아웃(15s / 60s)도 core가 건다 — 어댑터는 순수 위임(§7 하드닝 6).
     */
    getAssetInfo(assetId: string, input: {
        readonly downloadFromNetwork: boolean;
    }): Promise<DeviceAssetInfo>;
}

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

패키지: @gj-kit/expo-media
버전: 0.6.1
공개 entry: ./core
소스: GitHub