@cp949/browser-extra

@cp949/browser-extra

브라우저 친화적인 범용 자원 관리 유틸. DisposableScope는 여러 cleanup을 한 scope에 모아 한 번에 해제하고, URLCreateRegistry는 Blob 기반 Object URL의 수명을 참조 카운트로 관리한다.

설치

pnpm add @cp949/browser-extra

rxjs, eventemitter3에 의존하지 않는다.

최소 예제

import { DisposableScope } from "@cp949/browser-extra";

const scope = new DisposableScope();
scope.listen(window, "resize", () => {});
scope.setTimeout(() => {}, 1000);
scope.dispose(); // 한 번에 정리

DisposableScope 예제

일반 cleanup 함수 등록

import { DisposableScope } from "@cp949/browser-extra";

const scope = new DisposableScope();
const socket = new WebSocket("wss://example.com");

scope.use(() => socket.close());

// ... 사용

scope.dispose();

이미 dispose 메서드가 있는 객체 등록

import { DisposableScope } from "@cp949/browser-extra";

const scope = new DisposableScope();
const subscription = {
  dispose() {
    console.log("cleaned");
  },
};

scope.use(subscription);
scope.dispose();

이벤트 리스너를 등록하고 수동 cleanup 하기

import { DisposableScope } from "@cp949/browser-extra";

const scope = new DisposableScope();
const cleanupResize = scope.listen(window, "resize", () => {
  console.log("resized");
});

cleanupResize(); // 리스너 제거 + scope 등록 정보도 함께 정리

delay와 AbortSignal 함께 쓰기

import { delay } from "@cp949/browser-extra";

const controller = new AbortController();
setTimeout(() => controller.abort(), 100);

await delay(1000, controller.signal); // abort 시 조기 종료

DisposableScope 계약

• dispose()는 idempotent하며 등록된 cleanup을 역순(LIFO)으로 실행한다.
• 이미 dispose된 scope에 use()하면 리소스를 즉시 정리한 뒤 에러를 던진다.
• toCleanup() 정규화 순서는 dispose -> close -> unsubscribe -> abort -> terminate -> destroy -> shutdown 이다.
• adopt() 대상은 dispose()가 idempotent여야 하며 onDispose를 최대 한 번 호출해야 한다.

URLCreateRegistry 예제

import { URLCreateRegistry } from "@cp949/browser-extra";

const registry = new URLCreateRegistry();
const blob = new Blob(["hello"], { type: "text/plain" });

const url = registry.acquire(blob);

// 같은 Blob이면 같은 URL을 재사용하고 참조 수만 올린다.
registry.acquire(blob);

// 사용이 끝나면 release()로 참조를 내린다.
registry.release(blob);
registry.release(blob); // 마지막 참조에서 실제 revoke

URL을 즉시 폐기하기

import { URLCreateRegistry } from "@cp949/browser-extra";

const registry = new URLCreateRegistry();
const blob = new Blob(["hello"], { type: "text/plain" });
const url = registry.acquire(blob);

registry.revoke(url); // 참조 수와 무관하게 즉시 revoke

URLCreateRegistry는 FinalizationRegistry를 대체하지 않는다. 가비지 컬렉션 시점에 자동 정리를 기대하면 안 되며, release(), revoke(), revokeAll()로 직접 수명을 관리해야 한다.