R2Store.ts overview
Transport-independent image storage for one externally owned R2 object.
Since v0.12.0
layers
layer
A single-key experimental store. It passes the image limit to the transport's
readBounded operation when one is supplied. With a legacy client, the
store checks the limit after read returns.
The application must ensure one live owner; ETag conditions detect stale writes but cannot prevent stale reads.
A store scope waits for pending transport operations to settle before releasing ownership. A caller can stop waiting without aborting a transport request. If a write fails with an uncertain remote outcome, keep the key offline until reconciliation establishes that the request cannot still change the object and confirms the stored image.
Example
import { Client, layer, type R2Client } from "@effect-vfs/persistence/R2Store"
import { ByteSize, Layer } from "effect"
const makeStore = (client: R2Client) =>
layer({
key: "workspace-123",
maxImageBytes: ByteSize.mebibytes(4)
}).pipe(Layer.provide(Layer.succeed(Client, client)))Signature
declare const layer: (
options: Options
) => Layer.Layer<LiveVolume.LiveImageStore, VfsError.ArgumentFailure, Client | Digest.Digest>Since v0.5.0
models
ObjectRecord (interface)
A complete R2 image plus the metadata needed to validate and fence it.
Example
import type { ObjectRecord } from "@effect-vfs/persistence/R2Store"
const record: ObjectRecord = {
bytes: new Uint8Array(),
etag: '"version-1"',
generation: "0",
digest: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}Signature
export interface ObjectRecord {
readonly bytes: Uint8Array
readonly etag: string
readonly generation: string | undefined
readonly digest: string | undefined
}Since v0.5.0
Options (interface)
Configuration for one experimental R2-backed image.
Example
import type { Options } from "@effect-vfs/persistence/R2Store"
import { ByteSize } from "effect"
const options: Options = {
key: "effect-vfs-nfs-test/live-image",
maxImageBytes: ByteSize.mebibytes(16)
}Signature
export interface Options {
readonly key: string
readonly maxImageBytes: ByteSize.ByteSize
/** Assert R2's documented synchronous durable-write contract for a verified R2 endpoint and single owner. */
readonly durability?: "survives-power-loss"
}Since v0.5.0
R2Client (interface)
Transport operations required by the live-image adapter.
Example
import type { R2Client } from "@effect-vfs/persistence/R2Store"
type ReadObject = R2Client["read"]Signature
export interface R2Client {
/** Materializes an object without a transport limit. Prefer readBounded when available. */
readonly read: (key: string) => Effect.Effect<ObjectRecord | null, Vfs.VfsError>
/**
* Optional transport limit. Count bytes as they arrive and fail with
* `CorruptStore` after releasing an oversized body.
*/
readonly readBounded?: (
key: string,
maxImageBytes: ByteSize.ByteSize
) => Effect.Effect<ObjectRecord | null, Vfs.VfsError>
readonly write: (
key: string,
bytes: Uint8Array,
generation: string,
digest: string,
condition: { readonly ifMatch: string } | { readonly ifNoneMatch: "*" }
) => Effect.Effect<{ readonly etag: string } | null, Vfs.VfsError>
}Since v0.5.0
services
Client (class)
Supplies the borrowed R2 transport used by live-image stores. Share a client across distinct object keys while keeping each store owner separately scoped. The store does not close the supplied transport.
Example
import { Client, type R2Client } from "@effect-vfs/persistence/R2Store"
import { Layer } from "effect"
const provideClient = (client: R2Client) => Layer.succeed(Client, client)Signature
declare class ClientSince v0.12.0