LiveVolume.ts overview
Image boundary for a storage adapter that commits each live volume mutation.
An adapter must preserve the supplied bytes atomically and classify each
commit as confirmed, definitely rejected, or uncertain. The opened volume
stays at memory-only unless the adapter explicitly supplies a qualified
durability tier.
Since v0.4.0
constructors
makeRegistry
Lazily share one live volume and its store per key through RcMap. Concurrent
borrowers share acquisition. Reusing an idle entry avoids rebuilding its store
and decoding its image, while retaining its memory and storage locks.
The registry's owning scope must outlive all borrowers. Closing it shuts down
every volume, including borrowed ones, before releasing their store Layers.
Capacity exhaustion fails with Cause.ExceededCapacityError; it does not evict
idle entries. Acquisition failures remain shared until the entry is released.
Invalidation is intentionally unavailable: acquiring a replacement while an existing borrower remains would violate exclusive store ownership. Canonicalize keys before borrowing and use one registry for each set of backing stores.
Example
import { LiveVolume } from "@effect-vfs/core"
import { ByteSize, Effect, Layer } from "effect"
declare const storeFor: (key: string) => Layer.Layer<LiveVolume.LiveImageStore>
const program = Effect.gen(function* () {
const registry = yield* LiveVolume.makeRegistry({
store: storeFor,
volume: { maxImageBytes: ByteSize.megabytes(1), volume: {} },
capacity: 8,
idleTimeToLive: "5 seconds"
})
return yield* Effect.scoped(
Effect.gen(function* () {
const volume = yield* registry.get("workspace")
return yield* (yield* volume.caller()).readFile("/plan.md")
})
)
})Signature
declare const makeRegistry: <K, E, R>(
options: RegistryOptions<K, E, R>
) => Effect.Effect<Registry<K, E>, ArgumentFailure, R | Digest.Digest | SecureRandom.SecureRandom | Scope.Scope>Since v0.9.0
open
Open a live volume using the supplied store Layer. The caller owns a Scope;
the volume shuts down before that Layer releases its storage resource.
Requires the Digest and SecureRandom services to mint a new volume or incarnation.
Signature
declare const open: (
options: Options
) => Effect.Effect<Volume, VfsError, LiveImageStore | Scope.Scope | Digest.Digest | SecureRandom.SecureRandom>Since v0.4.0
openImage
Open a validated image and stage every mutation before calling commit.
The returned session contains the volume and a coordinated shutdown effect.
Run shutdown before releasing the storage connection. An uncertain commit
makes the volume unavailable until it is reopened.
Signature
declare const openImage: (
image: Uint8Array,
maxImageBytes: ByteSize.ByteSize,
commit: (image: Uint8Array) => Effect.Effect<CommitOutcome>,
durability?: VolumeDurability
) => Effect.Effect<ImageSession, VfsError, Digest.Digest | SecureRandom.SecureRandom>Since v0.4.0
prepareEmptyImage
Construct a versioned image for a new, empty volume.
Store this image before opening it for mutation.
Requires the Digest and SecureRandom services for secure volume identifiers and reference keys.
Signature
declare const prepareEmptyImage: (
options?: VolumeOptions
) => Effect.Effect<Uint8Array, VfsError, Digest.Digest | SecureRandom.SecureRandom>Since v0.4.0
models
CommitOutcome (type alias)
A storage commit's observed outcome.
A provider may return a rejected Cause only when no storage write was attempted.
Ordinary mutations preserve that cause and leave the volume available; uncertain writes use unknown.
Signature
type CommitOutcome =
| "committed"
| "rejected"
| "unknown"
| {
readonly _tag: "Rejected"
readonly cause: Cause.Cause<never>
}Since v0.4.0
ImageSession (interface)
A live volume and the shutdown action its storage adapter must run before closing the underlying store.
Example
import type { ImageSession } from "@effect-vfs/core/LiveVolume"
const shutdown = (session: ImageSession) => session.shutdownSignature
export interface ImageSession {
readonly volume: Volume
readonly shutdown: Effect.Effect<void>
}Since v0.4.0
Options (interface)
Configuration shared by every live-image provider.
Signature
export interface Options {
readonly maxImageBytes: ByteSize.ByteSize
readonly volume: VolumeOptions
}Since v0.4.0
Registry (interface)
Scoped access to live volumes shared by canonical storage identity.
Each get retains its volume until the borrowing scope closes. Keep that
scope open until its callers and handles finish using the volume.
Signature
export interface Registry<K, E = never> {
readonly get: (key: K) => Effect.Effect<Volume, E | VfsError | Cause.ExceededCapacityError, Scope.Scope>
}Since v0.9.0
RegistryOptions (interface)
Store Layers are built independently for each acquired entry. The same volume configuration applies to every key. Keys use Effect's equality rules and must identify canonical storage locations; different aliases can create competing owners. Coordinate ownership across processes outside this registry.
Signature
export interface RegistryOptions<K, E = never, R = never> {
readonly store: (key: K) => Layer.Layer<LiveImageStore, E, R>
readonly volume: Options
/** Positive integer entry limit. Omission means unlimited; idle entries count. */
readonly capacity?: number
/** Retain unused entries for this duration. Omission releases them immediately. */
readonly idleTimeToLive?: Duration.Input
}Since v0.9.0
services
LiveImageStore (class)
One exclusively owned store. Its Layer holds the storage resource until the
volume has shut down. Providers must atomically replace each image and
classify ambiguous commits as unknown.
Signature
declare class LiveImageStoreSince v0.4.0