use-storage-estimate

Track the origin's storage usage and quota with navigator.storage.estimate().


Package	`@vizejs/composable/use-storage-estimate`
Own the source	`vize lib pull composable:use-storage-estimate`
Runtime exports	`usePersistentStorage`, `useStorageEstimate`
Gzip budget	2560 B

Usage

import { usePersistentStorage, useStorageEstimate } from "@vizejs/composable/use-storage-estimate";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useStorageEstimate`	storage	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`
`usePersistentStorage`	storage	experimental	deterministic-fallback	caller-managed	none	web, desktop	`window`	`tryOnScopeDispose`

API

`useStorageEstimate`

Track the origin's storage usage and quota with navigator.storage.estimate(). The estimate is read on creation (unless immediate is false), whenever a reactive storage host changes, on refresh(), and every interval milliseconds through the injectable scheduler. The polling timer stops with the owning reactive scope; outside a scope, polling runs until the page unloads, so leave interval at 0 there. Server rendering: nothing is read, no timer starts, supported is false and every value is null.

function useStorageEstimate( options: UseStorageEstimateOptions = {}, ): StorageEstimateControls

const { usage, quota, percentUsed } = useStorageEstimate({ interval: 60_000 });

`usePersistentStorage`

Read and request persistent storage with navigator.storage.persist(). Persistent storage is not evicted under storage pressure. persist() may show a prompt or be decided silently by the browser; the result is stored in persisted. Nothing needs cleanup; a pending read is ignored after the owning reactive scope stops. Server rendering: nothing is read, supported and persisted are false.

function usePersistentStorage( options: UsePersistentStorageOptions = {}, ): PersistentStorageControls

const storage = usePersistentStorage();
const keepOfflineData = () => storage.persist();

Types

`StorageEstimateLike`

Result of navigator.storage.estimate().

Member	Type	Description
`usage`?	`number \| undefined`	Bytes used by the origin.
`quota`?	`number \| undefined`	Bytes available to the origin.
`usageDetails`?	`Readonly<Record<string, number>> \| undefined`	Per-storage-system usage in bytes (Chromium only).

`StorageManagerLike`

Minimal StorageManager (navigator.storage) used by this module.

Member	Type	Description
`estimate`?	`() => Promise<StorageEstimateLike>`	Estimate usage and quota.
`persisted`?	`() => Promise<boolean>`	Whether storage is already persistent.
`persist`?	`() => Promise<boolean>`	Request persistent storage.

`UseStorageEstimateOptions`

Options for useStorageEstimate.

Member	Type	Description
`storage`?	`MaybeRefOrGetter<StorageManagerLike \| null \| undefined>`	Storage manager for alternate runtimes and tests.
`immediate`?	`boolean`	Estimate as soon as the composable is created (browser only).
`interval`?	`number`	Re-estimate every `interval` milliseconds; `0` disables polling.
`scheduler`?	`IntervalScheduler`	Owns the polling timer.

`StorageEstimateControls`

Reactive state and actions returned by useStorageEstimate.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether `navigator.storage.estimate` is available.
`usage`	`Readonly<Ref<number \| null>>`	Bytes used, or `null` before the first estimate.
`quota`	`Readonly<Ref<number \| null>>`	Bytes available, or `null` before the first estimate.
`usageDetails`	`Readonly<ShallowRef<Readonly<Record<string, number>> \| null>>`	Per-storage-system usage, or `null` when the browser does not report it.
`percentUsed`	`ComputedRef<number \| null>`	Usage as a percentage (0..100) of quota, or `null` when unknown.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent estimate failure, cleared on success.
`refresh`	`() => Promise<boolean>`	Re-read the estimate.

`UsePersistentStorageOptions`

Options for usePersistentStorage.

Member	Type	Description
`storage`?	`MaybeRefOrGetter<StorageManagerLike \| null \| undefined>`	Storage manager for alternate runtimes and tests.
`immediate`?	`boolean`	Read `persisted()` as soon as the composable is created (browser only).

`PersistentStorageControls`

Reactive state and actions returned by usePersistentStorage.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether `navigator.storage.persist` is available.
`persisted`	`Readonly<Ref<boolean>>`	Whether the origin's storage is persistent (`false` until known).
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared on success.
`persist`	`() => Promise<boolean>`	Request persistent storage.
`check`	`() => Promise<boolean>`	Re-read `persisted()`.