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>

Source

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>

Source

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>

Source

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>

Source

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>
    }

Source

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.shutdown

Signature

export interface ImageSession {
  readonly volume: Volume
  readonly shutdown: Effect.Effect<void>
}

Source

Since v0.4.0

Options (interface)

Configuration shared by every live-image provider.

Signature

export interface Options {
  readonly maxImageBytes: ByteSize.ByteSize
  readonly volume: VolumeOptions
}

Source

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>
}

Source

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
}

Source

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 LiveImageStore

Source

Since v0.4.0