ocache
npm version
npm downloads
Composable caching primitives with TTL(Time To Live), stale-while-revalidate, 그리고 HTTP 응답 캐싱을 지원합니다. 프레임워크 의존성이 전혀 없으며 표준 Request/Response를 가진 모든 런타임에서 작동합니다.
[!TIP]
📖 더 자세한 내용은 문서(documentation)를 참조하세요.
주요 기능 (Features)
사용법 (Usage)
함수 캐싱 (Caching Functions)
TTL, stale-while-revalidate, 요청 중복 제거를 추가하기 위해 모든 함수를 defineCachedFunction으로 래핑하세요:
import { defineCachedFunction } from "ocache";
const cachedFetch = defineCachedFunction(
...
[!NOTE]
더 자세한 내용은 함수 캐싱 (Caching Functions) 가이드를 참조하고, 무효화 및 만료 (Invalidation & Expiration)와 스토리지 (Storage)를 확인하세요.
HTTP 핸들러 캐싱 (Caching HTTP Handlers)
etag 및 304 Not Modified 지원을 통해 자동 응답 캐싱을 위해 HTTP 핸들러를 defineCachedHandler로 래핑하세요:
import { defineCachedHandler } from "ocache";
const handler = defineCachedHandler(
...
[!NOTE]
더 자세한 내용은 Caching HTTP Handlers 가이드에서 확인하고, Query Parameters, Cookies, Cache-Control & Eligibility, 그리고 Incremental Static Regeneration를 참고하세요.
API
<!-- automd:docs4ts -->
BlobValue
type BlobValue = ArrayBufferView | ArrayBufferLike;
바이트 백엔드가 반환할 수 있는 값: 뷰(view) 또는 그 뒤에 있는 버퍼(buffer).
CachedEventHandler
type CachedEventHandler<E extends HTTPEvent = HTTPEvent> = EventHandler<E> &
리소스 수준의 캐시 관리 메서드를 갖춘 캐시 핸들러입니다.
각 메서드는 모든 기본 접두사(base prefix)에서 GET 및 HEAD 변형을 다룹니다.
cachedFunction
const cachedFunction = defineCachedFunction;
defineCachedFunction의 별칭입니다.
CacheStatus
type CacheStatus = "hit" | "stale" | "revalidated" | "miss";
하나의 캐시 호출 결과입니다.
- "hit": 신선한(fresh) 저장된 값을 반환했습니다.
- "stale": 오래된(stale) 데이터를 반환하고 백그라운드 재검증을 시작했습니다.
- "revalidated": 이전 값을 교체한 후 반환했습니다.
- "miss": 값이 존재하지 않아 값을 해결(resolve)했습니다.
composeStorage
function composeStorage(
layers: ReadonlyArray<StorageInterface | StorageLayer>,
opts: ComposeStorageOptions =
여러 백엔드를 하나의 계층화된 StorageInterface로 결합합니다.
읽기(Reads)는 각 레이어를 순서대로 시도하며 첫 번째 히트에서 멈추고, 이를 이전 모든 레이어에 전파(promote)합니다. 쓰기(Writes)와 삭제(Deletes)는 모든 레이어에 도달합니다. 오류를 발생시키는 레이어가 있더라도 작동을 실패시키지 않고 건너뛰므로, 로컬 캐시가 여전히 서비스를 제공할 수 있는 동안 공유 원격 레이어가 다운될 수 있습니다.
이것은 백엔드이며 캐시 옵션이 아닙니다: 위의 캐시는 하나의 저장소와 하나의 선언을 가진 스토어를 보기 때문에, 키(key), 엔트리(entry), 또는 삭제 경로(purge path)에 아무것도 변경되지 않습니다.
예시:
const storage = composeStorage([
{ storage: createMemoryStorage({ maxBytes: 64 * 1024 * 1024 }), ttl: 60 },
createBlobStorage(redis),
...
createBlobStorage
function createBlobStorage(backend: BlobBackend): StorageInterface;
블롭 전용 백엔드(byte-only backend)를 StorageInterface로 어댑팅하여, 각 항목을 하나의 프레임으로 저장합니다.
항목의 메타데이터는 JSON 형태로 전달되고 페이로드(payload)는 그 자체로 전달되어 뒤에 추가됩니다. 이 방식은 응답 본문(텍스트 또는 바이너리)이 JSON 문서 밖에 있도록 유지합니다. 텍스트는 어느 방향에서도 이스케이프 처리가 필요 없으며, 바이트 값은 백엔드에서 base64 인코딩이나 4/3 확장이 필요 없습니다.
페이로드는 항목 생성자가 선언하는 {@link CacheEntry.payload}라는 이름의 데이터입니다. 이는 응답 본문인 경우 http/entry.ts를, 바이트 값인 경우 cache.ts를 사용합니다. 여기서는 값의 형태만으로 페이로드를 추론하지 않습니다.
이것은 'binary'를 선언하는데, 프레임이 선언된 페이로드 자체를 바이트 형태로 운반하기 때문입니다. 항목의 다른 모든 멤버는 JSON이며, 직렬화(serializing) 백엔드에서와 정확히 동일합니다. 어딘가에 숨겨진 바이트 뷰는 ocache가 넣지 않은 것이므로, 이 백엔드나 다른 어떤 JSON 형태의 백엔드에서도 살아남을 수 없습니다.
다른 버전에서 작성된 프레임은 누락(miss)으로 읽히기 때문에, 형식 변경이 발생해도 손상된 항목이 되는 대신 재검증(revalidation) 비용만 발생합니다.
예시:
const storage = createBlobStorage({
get: (key) => unstorage.getItemRaw(key),
set: (key, value, opts) =>
...
createMemoryStorage
function createMemoryStorage(opts: MemoryStorageOptions =
TTL을 초 단위로 설정하고 LRU 제거 정책(LRU eviction)이 적용된 Map 기반 메모리 스토리지를 생성합니다.
defineCachedFunction
function defineCachedFunction<T, ArgsT extends unknown[] = any[]>(
fn: (...args: ArgsT) => T | Promise<T>,
opts: CacheOptions<T, ArgsT> =
함수에 캐싱(caching), SWR (stale-while-revalidate), 무결성 검사(integrity checks), 요청 중복 제거(request deduplication) 기능을 래핑합니다.
매개변수:
fn: 캐싱할 함수입니다.opts: 캐시 옵션입니다.
캐시된 함수와 해당 캐시 관리 메서드.
defineCachedHandler
function defineCachedHandler<E extends HTTPEvent = HTTPEvent>(
handler: EventHandler<E>,
opts: CachedEventHandlerOptions<E> =
응답 캐싱 및 조건부 응답 지원 기능을 통해 HTTP 핸들러를 래핑합니다.
Range 헤더가 없는 GET 및 HEAD 요청만 캐시 가능합니다.- 200, 203, 301, 308 응답만 저장됩니다.
- 응답의
Cache-Control 및 Vary 헤더를 통해 저장이 방지될 수 있습니다.
매개변수:
handler — 캐시할 핸들러입니다.opts — 캐시 및 HTTP 옵션입니다.
반환값: — 리소스 수준의 캐시 관리 메서드를 갖춘 캐시된 핸들러입니다.
EventHandler
type EventHandler<E extends HTTPEvent = HTTPEvent> = (
HTTP 이벤트를 수신하는 핸들러입니다.
expireCache
async function expireCache<ArgsT extends unknown[] = any[]>(
input:
일치하는 항목을 제거하지 않고 만료(stale) 상태로 표시합니다.
- SWR은 원래의 만료 기간 내에서 오래된 값(stale value)을 제공할 수 있습니다.
- SWR이 없는 경우, 다음 호출은 반환하기 전에 재검증합니다.
- 남은 저장소 TTL(Time To Live)을 유지하려면 원래의 수명 주기 옵션을 전달하십시오.
- 이 함수는
options.storage가 설정되지 않았을 때 오류를 발생시킵니다.
매개변수:
input — 캐시 옵션 및 함수 인자입니다.
예제:
await expireCache({
options: { name: "fetchUser", getKey: (id: string) => id, maxAge: 60, swr: true, storage },
args: ["user-123"],
});
invalidateCache
async function invalidateCache<ArgsT extends unknown[] = any[]>(
input:
모든 기본 접두사에서 일치하는 항목을 제거합니다.
- 원래의 옵션 객체 또는 동일한 명시적 저장소 백엔드를 전달하십시오.
- 전역 스토어가 존재하지 않기 때문에
options.storage가 설정되지 않았을 때 이 함수는 오류를 발생시킵니다.
- 사용 가능한 경우 캐시된 함수의
.invalidate() 메서드를 사용하는 것이 좋습니다.
매개변수:
input — 캐시 옵션 및 함수 인자입니다.
예제:
await invalidateCache({
options: { name: "fetchUser", getKey: (id: string) => id, storage },
args: ["user-123"],
...
resolveCacheKeys
async function resolveCacheKeys<ArgsT extends unknown[] = any[]>(
input:
기본 접두사(base prefix)당 하나의 스토리지 키를 반환합니다.
캐시된 함수와 동일한 getKey, name, group, 및 base 옵션을 전달하세요. 이 헬퍼는 스토리지에 접근하지 않고 키를 계산합니다.
매개변수 (Parameters):
반환값 (Returns): — 기본 접두사 순서로 정렬된 스토리지 키들.
예시 (Example):
const keys = await resolveCacheKeys({
options: { name: "fetchUser", getKey: (id: string) => id },
args: ["user-123"],
...
resolveSignal
function resolveSignal(event: HTTPEvent): AbortSignal | undefined;
이 이벤트가 유발하는 해결 과정의 마감 기한 신호(deadline signal)입니다. 만약 이 이벤트가 해결 과정을 유발하지 않는다면 undefined를 반환합니다.
resolveStatus
function resolveStatus(event: HTTPEvent): CacheStatus | undefined;
이 이벤트가 유발하는 포그라운드 해결 과정의 상태입니다. 만약 이 이벤트가 해결 과정을 유발하지 않는다면 undefined를 반환합니다.
scheduleTimer
function scheduleTimer(fn: () => void, ms: number): () => void;
fn을 ms 시간 후에 예약하며, 프로세스를 활성 상태로 유지하지 않고도 작동합니다. (32비트 타이머 제한 초과 가능)
MAX_TIMER_MS보다 긴 지연 시간은 체인(chained) 방식으로 처리됩니다: 각 단계는 남은 시간을 위해 재설정되므로, 30일의 maxAge는 1ms가 아닌 실제로 30일 후에 작동합니다. 취소 함수를 반환합니다.
캐시 내 타이머가 오버플로우되는 것을 방지하기 위해 cache.ts의 withDeadline과 공유됩니다.
StorageOption
type StorageOption = StorageInterface | (() => StorageInterface);
스토리지 인스턴스 또는 지연 바인딩(late-bound) 스토리지 팩토리입니다.
캐시는 첫 번째 캐시 작업 시에만 이 팩토리를 호출합니다.
<!-- /automd-->
개발 (Development)
<details>
<summary>로컬 개발 (local development)</summary>
- 이 저장소를 복제합니다.
- 최신 LTS 버전의 [Node.js]를 설치합니다.
corepack enable을 사용하여 [Corepack]을 활성화합니다.pnpm install을 사용하여 의존성을 설치합니다.pnpm dev를 사용하여 인터랙티브 테스트를 실행합니다.
</details>
라이선스
[MIT] 라이선스 하에 게시되었습니다. 💛.
