Volume.ts overview

Volume identity brands and schemas: durability, identity tokens, reference keys, construction options, and the change summaries an overlay volume reports.

Since v0.6.0

models

OverlayChange (type alias)

One summarised change between an overlay and its base.

Signature

export type OverlayChange =
  | {
      readonly _tag: "Added"
      readonly path: BytePath
      readonly kind: "file" | "directory" | "symlink"
    }
  | {
      readonly _tag: "Removed"
      readonly path: BytePath
      readonly kind: "file" | "directory" | "symlink"
    }
  | {
      readonly _tag: "Replaced"
      readonly path: BytePath
      readonly beforeKind: "file" | "directory" | "symlink"
      readonly afterKind: "file" | "directory" | "symlink"
      readonly differences: readonly (
        "uid" | "gid" | "mode" | "atimeNs" | "mtimeNs" | "ctimeNs" | "birthtimeNs" | "content"
      )[]
    }
  | {
      readonly _tag: "Renamed"
      readonly from: BytePath
      readonly to: BytePath
      readonly kind: "file" | "directory" | "symlink"
      readonly differences: readonly (
        "uid" | "gid" | "mode" | "atimeNs" | "mtimeNs" | "ctimeNs" | "birthtimeNs" | "content"
      )[]
    }
  | {
      readonly _tag: "Updated"
      readonly path: BytePath
      readonly kind: "file" | "directory" | "symlink"
      readonly differences: readonly (
        "uid" | "gid" | "mode" | "atimeNs" | "mtimeNs" | "ctimeNs" | "birthtimeNs" | "content"
      )[]
    }

Source

Since v0.6.0

OverlayChangesOptions (type alias)

Options of an overlay change summary.

Signature

export type OverlayChangesOptions = { readonly includeTimestamps?: boolean }

Source

Since v0.6.0

OverlayDifference (type alias)

One way an overlay entry differs from its base.

Signature

export type OverlayDifference =
  "uid" | "gid" | "mode" | "atimeNs" | "mtimeNs" | "ctimeNs" | "birthtimeNs" | "content"

Source

Since v0.6.0

OverlayNodeKind (type alias)

A kind of filesystem entry in an overlay summary.

Signature

export type OverlayNodeKind = "file" | "directory" | "symlink"

Source

Since v0.6.0

ReferenceKey (type alias)

The serialisable name of one object in one volume.

Signature

export type ReferenceKey = {
  readonly identity: Uint8Array<ArrayBufferLike>
  readonly epoch: Uint8Array<ArrayBufferLike>
  readonly ino: bigint
  readonly tag: Uint8Array<ArrayBufferLike>
}

Source

Since v0.6.0

VolumeDurability (type alias)

The failure boundary a volume's committed mutations survive.

Signature

export type VolumeDurability =
  | "memory-only"
  | "survives-process-crash"
  | "survives-operating-system-crash"
  | "survives-power-loss"

Source

Since v0.6.0

VolumeIdentity (type alias)

A volume identity.

Signature

export type VolumeIdentity = string & Brand.Brand<"@effect-vfs/core/VolumeIdentity">

Source

Since v0.6.0

VolumeIncarnation (type alias)

A volume incarnation.

Signature

export type VolumeIncarnation = string & Brand.Brand<"@effect-vfs/core/VolumeIncarnation">

Source

Since v0.6.0

VolumeOptions (type alias)

Volume construction options.

Signature

export type VolumeOptions = {
  readonly maxEntries?: number
  readonly maxPathBytes?: ByteSize.ByteSize
  readonly maxFileBytes?: ByteSize.ByteSize
  readonly identity?: string & Brand.Brand<"@effect-vfs/core/VolumeIdentity">
  readonly execution?: "cooperative" | "sync"
  readonly maxPendingOperations?: number
  readonly maxWatchEvents?: number
  readonly maxBytes?: ByteSize.ByteSize
}

Source

Since v0.6.0

ordering

VolumeDurabilityOrder

Weakest-to-strongest ordering for volume durability guarantees.

Signature

declare const VolumeDurabilityOrder: Order.Order<
  "memory-only" | "survives-process-crash" | "survives-operating-system-crash" | "survives-power-loss"
>

Source

Since v0.6.0

predicates

isVolumeDurabilityAtLeast

Returns whether actual survives at least the failure boundary required by required.

Signature

declare const isVolumeDurabilityAtLeast: {
  (required: VolumeDurability): (actual: VolumeDurability) => boolean
  (actual: VolumeDurability, required: VolumeDurability): boolean
}

Source

Since v0.6.0

schemas

OverlayChange

Schema for one summarised change between an overlay and its base.

Signature

declare const OverlayChange: Schema.Union<
  readonly [
    Schema.TaggedStruct<
      "Added",
      {
        readonly path: Schema.declare<BytePath, BytePath>
        readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>
      }
    >,
    Schema.TaggedStruct<
      "Removed",
      {
        readonly path: Schema.declare<BytePath, BytePath>
        readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>
      }
    >,
    Schema.TaggedStruct<
      "Replaced",
      {
        readonly path: Schema.declare<BytePath, BytePath>
        readonly beforeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>
        readonly afterKind: Schema.Literals<readonly ["directory", "file", "symlink"]>
        readonly differences: Schema.$Array<
          Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>
        >
      }
    >,
    Schema.TaggedStruct<
      "Renamed",
      {
        readonly from: Schema.declare<BytePath, BytePath>
        readonly to: Schema.declare<BytePath, BytePath>
        readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>
        readonly differences: Schema.$Array<
          Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>
        >
      }
    >,
    Schema.TaggedStruct<
      "Updated",
      {
        readonly path: Schema.declare<BytePath, BytePath>
        readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>
        readonly differences: Schema.$Array<
          Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>
        >
      }
    >
  ]
>

Source

Since v0.6.0

OverlayChangesOptions

Schema for the options of an overlay change summary.

Signature

declare const OverlayChangesOptions: Schema.Struct<{ readonly includeTimestamps: Schema.optionalKey<Schema.Boolean> }>

Source

Since v0.6.0

OverlayDifference

Schema for one way an overlay entry differs from its base.

Signature

declare const OverlayDifference: Schema.Literals<
  readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]
>

Source

Since v0.6.0

OverlayNodeKind

Schema for the kinds of filesystem entry an overlay summary reports.

Signature

declare const OverlayNodeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>

Source

Since v0.6.0

ReferenceKey

Schema for a reference key: the serialisable name of one object in one volume, for adapters that must name an object outside the process, such as an NFS filehandle.

Details

identity is the volume's identity and epoch the inode-number namespace the object was numbered in, both as 16 bytes encoded as base64; ino is the object's inode number, encoded as a decimal string; tag is 16 bytes of HMAC-SHA-256 over the identity, epoch and inode number under a secret only the volume holds, encoded as base64. Inode numbers are small and sequential, so the tag is what keeps a holder of one key from naming a neighbouring object: a key with another inode number or an altered tag fails InvalidReference. A volume mints a new epoch and secret whenever its inode numbers start over: a new volume, a snapshot or fixture restore, and an overlay. A live volume keeps both across a reopen, so its keys outlive the process. Turning a key into bytes of a fixed layout stays the adapter's job.

Signature

declare const ReferenceKey: Schema.Struct<{
  readonly identity: Schema.Uint8ArrayFromBase64
  readonly epoch: Schema.Uint8ArrayFromBase64
  readonly ino: Schema.BigIntFromString
  readonly tag: Schema.Uint8ArrayFromBase64
}>

Source

Since v0.6.0

VolumeDurability

Schema for the failure boundary a volume's committed mutations survive.

Signature

declare const VolumeDurability: Schema.Literals<
  readonly ["memory-only", "survives-process-crash", "survives-operating-system-crash", "survives-power-loss"]
>

Source

Since v0.6.0

VolumeIdentity

Schema for a volume identity: 128 bits as lowercase hexadecimal, stable across restarts of a durable volume.

Signature

declare const VolumeIdentity: Schema.brand<Schema.String, "@effect-vfs/core/VolumeIdentity">

Source

Since v0.6.0

VolumeIncarnation

Schema for a volume incarnation: 128 bits as lowercase hexadecimal, minted on every construction.

Signature

declare const VolumeIncarnation: Schema.brand<Schema.String, "@effect-vfs/core/VolumeIncarnation">

Source

Since v0.6.0

VolumeOptions

Schema for volume construction options.

Signature

declare const VolumeOptions: Schema.Struct<{
  readonly execution: Schema.optionalKey<Schema.Literals<readonly ["cooperative", "sync"]>>
  readonly identity: Schema.optionalKey<Schema.brand<Schema.String, "@effect-vfs/core/VolumeIdentity">>
  readonly maxEntries: Schema.optionalKey<Schema.Natural>
  readonly maxPendingOperations: Schema.optionalKey<Schema.Int>
  readonly maxWatchEvents: Schema.optionalKey<Schema.Int>
  readonly maxBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxFileBytes: Schema.optionalKey<Schema.ByteSize>
  readonly maxPathBytes: Schema.optionalKey<Schema.ByteSize>
}>

Source

Since v0.6.0

type IDs

VolumeId

Brand key that marks a volume.

Signature

declare const VolumeId: unique symbol

Source

Since v0.6.0

VolumeId (type alias)

Brand key that marks a volume.

Signature

export type VolumeId = typeof VolumeId

Source

Since v0.6.0