Snapshot.ts overview

Opaque virtual filesystem snapshots and their decoding limits.

A snapshot is the immutable value of a volume at one committed state, so capturing one copies nothing. It holds the reachable namespace and metadata, but excludes callers, open handles, watch subscriptions, and unlinked content. Use the encoding, decoding, and restoration functions in VirtualFileSystem.

Since v0.1.0

models

DecodeLimits (type alias)

Resource limits applied while decoding a snapshot.

Signature

export type DecodeLimits = {
  readonly maxEntries: number
  readonly maxEncodedBytes: ByteSize.ByteSize
  readonly maxRecords: number
  readonly maxDecodedBytes: ByteSize.ByteSize
  readonly maxLineBytes?: ByteSize.ByteSize
}

Source

Since v0.1.0

Snapshot (interface)

An immutable, opaque capture of a virtual filesystem volume.

Signature

export interface Snapshot {
  readonly [SnapshotTypeId]: SnapshotTypeId
}

Source

Since v0.1.0

schemas

DecodeLimits

Schema for the mandatory resource limits applied while decoding a snapshot.

Details

A snapshot is encoded one line per node, and a decoder checks each line as it ends, so input that breaks a limit is refused before the decoder holds more than one line of it. maxLineBytes bounds that line; the other limits bound what the accepted lines add up to.

Example

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { ByteSize, Effect } from "effect"
 
// The four counts are required: each bounds a different resource. `maxEncodedBytes`
// caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
// `maxLineBytes` is optional and caps one line, which holds at most one file.
const limits: Vfs.DecodeLimits = {
  maxEncodedBytes: ByteSize.megabytes(4),
  maxRecords: 10_000,
  maxEntries: 10_000,
  maxDecodedBytes: ByteSize.megabytes(16),
  maxLineBytes: ByteSize.megabytes(4)
}
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.make()
  const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
 
  yield* Vfs.decodeSnapshot(bytes, limits)
 
  return "accepted"
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// accepted

Signature

declare const DecodeLimits: Schema.Struct<{
  readonly maxEncodedBytes: Schema.ByteSize
  readonly maxRecords: Schema.Natural
  readonly maxEntries: Schema.Natural
  readonly maxDecodedBytes: Schema.ByteSize
  readonly maxLineBytes: Schema.optionalKey<Schema.ByteSize>
}>

Source

Since v0.1.0

type IDs

SnapshotTypeId

Type identifier for opaque filesystem snapshots.

Signature

declare const SnapshotTypeId: "@effect-vfs/core/Snapshot"

Source

Since v0.1.0

SnapshotTypeId (type alias)

Type identifier for opaque filesystem snapshots.

Signature

export type SnapshotTypeId = "@effect-vfs/core/Snapshot"

Source

Since v0.1.0