VirtualFileSystem.ts overview

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const encoder = new TextEncoder()
 
const program = Effect.gen(function* () {
  // Parent directories must be listed explicitly, in any order.
  const volume = yield* Vfs.fromFixture({
    entries: [
      { kind: "directory", path: "/project" },
      {
        kind: "file",
        path: "/project/package.json",
        bytes: encoder.encode(`{"version":"1.2.3"}`)
      },
      { kind: "symlink", path: "/project/latest", target: "/project/package.json" }
    ]
  })
 
  // A fixture's directories list their entries in the byte order of their names.
  const listing = yield* (yield* volume.caller()).readDirectory("/project")
 
  return listing.value.map((entry) => new TextDecoder().decode(entry.name))
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'latest', 'package.json' ]

declare const fromFixture: {
  (options?: VolumeOptions): (fixture: Fixture) => Effect.Effect<Volume, VfsError, Crypto.Crypto>
  (fixture: Fixture, options?: VolumeOptions): Effect.Effect<Volume, VfsError, Crypto.Crypto>
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const original = yield* Vfs.make()
  const source = yield* original.caller()
 
  yield* source.writeFile("/seed.txt", new TextEncoder().encode("one"), {
    access: "write",
    create: "exclusive"
  })
 
  const restored = yield* Vfs.fromSnapshot(yield* original.snapshot)
  const copy = yield* restored.caller()
 
  // Writing to the restore leaves the original untouched: the two are independent.
  yield* copy.writeFile("/seed.txt", new TextEncoder().encode("two"), {
    access: "write",
    truncate: true
  })
 
  return [
    new TextDecoder().decode(yield* source.readFile("/seed.txt")),
    new TextDecoder().decode(yield* copy.readFile("/seed.txt"))
  ]
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'one', 'two' ]

declare const fromSnapshot: {
  (options?: VolumeOptions): (snapshot: Snapshot) => Effect.Effect<Volume, VfsError, Crypto.Crypto>
  (snapshot: Snapshot, options?: VolumeOptions): Effect.Effect<Volume, VfsError, Crypto.Crypto>
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.make()
  const caller = yield* volume.caller()
 
  yield* caller.mkdir("/work")
  yield* caller.writeFile("/work/notes.txt", new Uint8Array([104, 105]), { access: "write", create: "exclusive" })
 
  return yield* caller.readFile("/work/notes.txt")
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// Uint8Array(2) [ 104, 105 ]

declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, VfsError, Crypto.Crypto>

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const base = yield* Vfs.make()
  const origin = yield* base.caller()
 
  yield* origin.writeFile("/config.json", new TextEncoder().encode("{}"), {
    access: "write",
    create: "exclusive"
  })
 
  const workspace = yield* Vfs.makeOverlay(yield* base.snapshot)
 
  yield* (yield* workspace.caller()).writeFile("/config.json", new TextEncoder().encode("[]"), {
    access: "write",
    truncate: true
  })
 
  // The write landed in the workspace only; the base still reads its own value.
  return [
    new TextDecoder().decode(yield* origin.readFile("/config.json")),
    (yield* workspace.changes()).map((change) => change._tag)
  ]
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ '{}', [ 'Updated' ] ]

declare const makeOverlay: {
  (options?: VolumeOptions): (base: Snapshot) => Effect.Effect<OverlayVolume, VfsError, Crypto.Crypto>
  (base: Snapshot, options?: VolumeOptions): Effect.Effect<OverlayVolume, VfsError, Crypto.Crypto>
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// Any byte except NUL is accepted. Empty, NUL-bearing, detached, and shared-memory
// input all fail with `InvalidArgument`.
const program = Effect.gen(function* () {
  const path = yield* Vfs.pathFromBytes(new Uint8Array([47, 116, 109, 112]))
 
  const rejected = yield* Vfs.pathFromBytes(new Uint8Array([47, 0])).pipe(
    Effect.as("accepted"),
    Effect.catchTag("VfsError", (error) => Effect.succeed(error.code))
  )
 
  return [yield* Vfs.pathToBytes(path), rejected]
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ Uint8Array(4) [ 47, 116, 109, 112 ], 'InvalidArgument' ]

declare const pathFromBytes: (bytes: Uint8Array) => Effect.Effect<BytePath, FsFailure>

declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array, FsFailure>

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// Whole-file reads and writes need no scope. `writeFile` always takes an
// options bag; `access` is required and `create` decides what a missing file means.
const program = Effect.gen(function* () {
  const volume = yield* Vfs.make()
  const caller = yield* volume.caller()
 
  yield* caller.mkdir("/work")
  yield* caller.writeFile("/work/notes.txt", new TextEncoder().encode("hello"), {
    access: "write",
    create: "exclusive"
  })
 
  return (yield* caller.readDirectory("/work")).value.map((entry) => new TextDecoder().decode(entry.name))
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'notes.txt' ]

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// Reach for a handle when a whole-file write will not do. A handle carries a
// cursor and lives until its scope closes.
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
 
  const handle = yield* caller.open("/log.txt", {
    access: "readWrite",
    create: "exclusive"
  })
 
  yield* handle.write(new TextEncoder().encode("first "))
  yield* handle.write(new TextEncoder().encode("second"))
  yield* handle.seek(0n, "start")
 
  return new TextDecoder().decode(yield* handle.read(64))
}).pipe(Effect.scoped)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// first second

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// A derived caller holds the directory's identity, not its path, so renaming
// the directory does not redirect later relative writes.
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
 
  yield* caller.mkdir("/build")
 
  const work = yield* caller.withDirectory("/build")
 
  yield* caller.rename("/build", "/dist")
  yield* work.writeFile("out.txt", new TextEncoder().encode("done"), {
    access: "write",
    create: "exclusive"
  })
 
  return (yield* caller.readDirectory("/dist")).value.map((entry) => new TextDecoder().decode(entry.name))
}).pipe(Effect.scoped)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'out.txt' ]

export interface Caller {
  readonly [CallerId]: true
  /** Backing volume configuration; these are not subtree quotas. */
  readonly limits: VolumeLimits
  /** Watches current authorized names, rebasing events when each change commits. */
  readonly watch: (
    target: TargetInput,
    options?: WatchModule.CallerWatchOptions
  ) => Effect.Effect<Stream.Stream<Change, FsFailure>, FsFailure, Scope.Scope>
  /**
   * Narrows authority to a directory identity and resets the working directory. Absolute paths and symbolic
   * links start at this root; `..` stops here. Nested roots retain their ancestor boundaries. References and
   * direct handles check current membership on every use, including privileged callers. Root rename preserves
   * authority; deletion permanently invalidates it. Existing hard links can share contents across roots.
   * Independently scoped descendants and handles retain their own lifetime when their creator closes.
   */
  readonly withRoot: (directory: TargetInput) => Effect.Effect<Caller, FsFailure, Scope.Scope>
  /** The reference of the caller's visible root directory. */
  readonly root: Effect.Effect<ObjectReference, FsFailure>
  /** The reference of a child of a directory, without following it. */
  readonly lookup: (entry: EntryInput) => Effect.Effect<ObjectReference, FsFailure>
  /** The reference of a directory's parent; the root is its own parent. */
  readonly parent: (directory: TargetInput) => Effect.Effect<ObjectReference, FsFailure>
  /** Metadata and revision of a target. A path follows a final symbolic link unless its target says otherwise. */
  readonly stat: (target: TargetInput) => Effect.Effect<Metadata, FsFailure>
  /** The entries of a directory with their references, and the directory's revision. */
  readonly readDirectory: (
    directory: TargetInput
  ) => Effect.Effect<ObjectObservation<ReadonlyArray<DirectoryEntry>>, FsFailure>
  /**
   * Every entry below a directory, as a stream that reads one directory at a time and holds no handle. Entries
   * arrive depth first, each directory's entries in the byte order of their names; symbolic links are reported,
   * never followed. Each directory is read in one observation, so the walk sees each listing whole but no
   * snapshot of the tree, and it refreshes no access time. Each directory below the root is reached by name, as a
   * path lookup reaches it, so it needs search permission on every directory above it, and one that goes away or
   * is renamed out of the tree before the walk reads it is skipped. A failure below the root names the entry's
   * path under the path the root was given by, or under the root when it was given by reference or handle.
   */
  readonly walk: (directory: TargetInput, options?: WalkOptions) => Stream.Stream<WalkEntry, WalkFailure>
  /** The bytes a symbolic link points at. A path never follows the final link. */
  readonly readLink: (target: TargetInput) => Effect.Effect<Uint8Array, FsFailure>
  /** The canonical absolute path of a target. */
  readonly realPath: (target: TargetInput) => Effect.Effect<BytePath, FsFailure>
  /** The bits of `bits` the caller may exercise on the target: READ, WRITE, EXECUTE as 4, 2, 1. */
  readonly access: (target: TargetInput, bits?: number) => Effect.Effect<number, FsFailure>
  /** The whole content of a regular file. */
  readonly readFile: (target: TargetInput) => Effect.Effect<Uint8Array, FsFailure>
  /**
   * Writes a whole file in one operation and returns its object reference, creating or replacing it as the options say.
   * The curried form is `writeFile(bytes, options)(entry)`; the caller remains bound.
   */
  readonly writeFile: {
    (bytes: Uint8Array, options: WriteFileOptions): (entry: EntryInput) => Effect.Effect<ObjectReference, FsFailure>
    (entry: EntryInput, bytes: Uint8Array, options: WriteFileOptions): Effect.Effect<ObjectReference, FsFailure>
  }
  /**
   * Opens a file. On a target, the file must exist and `create` is rejected. On an entry, the name is looked up
   * and created in one gate hold, and the result reports whether it was created.
   */
  readonly open: {
    (
      target: Target | PathInput | ObjectReference | FileHandle,
      options: OpenOptions
    ): Effect.Effect<FileHandle, FsFailure, Scope.Scope>
    (entry: Entry, options: OpenEntryOptions): Effect.Effect<OpenEntryResult, FsFailure, Scope.Scope>
  }
  /**
   * Creates a directory. With `recursive`, every missing directory on a path is created in one change, so a
   * failure creates none and a watcher sees them all at once; symbolic links on the way are followed, dot names
   * are walked, and a final name that is already a directory (or a link to one) succeeds without a change. The
   * result names the directory the path ends on, with its parent's revision before and after the call, so a path
   * that leaves a directory it created, such as `new/..`, still reports the change. A name on the way that is not
   * a directory fails with `NotDirectory`, a final one with `AlreadyExists`, and only names the caller wrote are
   * created, so a dangling link fails with `NotFound`.
   */
  readonly mkdir: (entry: EntryInput, options?: MkdirOptions) => Effect.Effect<ReferenceEntryResult, FsFailure>
  /** Creates a symbolic link to `target`, stored as given. */
  readonly symlink: (
    target: PathInput,
    entry: EntryInput,
    options?: SymlinkOptions
  ) => Effect.Effect<ReferenceEntryResult, FsFailure>
  /** Adds a name for an existing file or symbolic link. A path source follows a final symbolic link only when its target says so. */
  readonly link: {
    (entry: EntryInput): (source: TargetInput) => Effect.Effect<ReferenceEntryResult, FsFailure>
    (source: TargetInput, entry: EntryInput): Effect.Effect<ReferenceEntryResult, FsFailure>
  }
  /** Removes a file or symbolic link. */
  readonly unlink: (entry: EntryInput) => Effect.Effect<DirectoryChange, FsFailure>
  /** Removes an empty directory. */
  readonly rmdir: (entry: EntryInput) => Effect.Effect<DirectoryChange, FsFailure>
  /**
   * Removes a file, a symbolic link, or an empty directory. With `recursive`, a directory that has entries is
   * emptied first, entries before their directories, each removal its own change; it stops at the first failure,
   * whose path names the entry it stopped at, and leaves what it has not reached. Each entry is removed by its name
   * in a directory reached by name, so a subtree renamed out of the target is left alone. A directory with entries
   * must be readable, and no permission is changed to make it so. With `force`, a missing target is success and the
   * result is `undefined`; a failure below the target is still a failure.
   */
  readonly remove: {
    (entry: EntryInput, options?: RemoveOptions & { readonly force?: false }): Effect.Effect<DirectoryChange, FsFailure>
    (entry: EntryInput, options: RemoveOptions): Effect.Effect<DirectoryChange | undefined, FsFailure>
  }
  /** Moves an entry, replacing a compatible destination. */
  readonly rename: {
    (to: EntryInput): (from: EntryInput) => Effect.Effect<RenameReferenceResult, FsFailure>
    (from: EntryInput, to: EntryInput): Effect.Effect<RenameReferenceResult, FsFailure>
  }
  /** Sets the permission bits of a target. */
  readonly chmod: {
    (mode: number): (target: TargetInput) => Effect.Effect<void, FsFailure>
    (target: TargetInput, mode: number): Effect.Effect<void, FsFailure>
  }
  /** Changes the owner or group of a target. */
  readonly chown: {
    (owner: OwnerUpdate): (target: TargetInput) => Effect.Effect<void, FsFailure>
    (target: TargetInput, owner: OwnerUpdate): Effect.Effect<void, FsFailure>
  }
  /** Sets the access and modification times of a target. */
  readonly utimes: {
    (times: Times): (target: TargetInput) => Effect.Effect<void, FsFailure>
    (target: TargetInput, times: Times): Effect.Effect<void, FsFailure>
  }
  /** Sets the size of a regular file. */
  readonly truncate: {
    (length: bigint): (target: TargetInput) => Effect.Effect<void, FsFailure>
    (target: TargetInput, length: bigint): Effect.Effect<void, FsFailure>
  }
  /**
   * Changes a target's size, owner, mode and times as one change. Every check passes before any attribute
   * applies, so a failure changes nothing. The attributes apply as size, owner, mode, then times, the POSIX
   * composition of chown then chmod, so a requested mode wins over the set-ID clearing an owner change or a
   * resize triggers. A protocol adapter that sanitises the requested mode, as NFS does after Linux knfsd,
   * does so before it calls setattr, and passes the revision it read as `expected` so the change refuses a
   * target another change has moved.
   */
  readonly setattr: {
    (attributes: SetattrOptions): (target: TargetInput) => Effect.Effect<void, FsFailure>
    (target: TargetInput, attributes: SetattrOptions): Effect.Effect<void, FsFailure>
  }
  /** A caller whose working directory is the target, released with the scope. */
  readonly withDirectory: (directory: TargetInput) => Effect.Effect<Caller, FsFailure, Scope.Scope>
  /** A handle on a directory, released with the scope. */
  readonly openDirectory: (directory: TargetInput) => Effect.Effect<DirectoryHandle, FsFailure, Scope.Scope>
}

export type CallerWatchOptions = {
  readonly recursive?: boolean
  readonly alias?: "all" | "resolved"
}

export type Change =
  | { readonly _tag: "Create"; readonly path: BytePath }
  | { readonly _tag: "Update"; readonly path: BytePath }
  | { readonly _tag: "Remove"; readonly path: BytePath }
  | { readonly _tag: "Rescan"; readonly path: BytePath }

export type DirectoryChange = { readonly before: bigint; readonly after: bigint }

export interface DirectoryEntry {
  readonly name: Uint8Array
  readonly reference: ObjectReference
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// The handle anchors relative paths to the directory itself, so a rename in
// between does not send the write somewhere else.
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
 
  yield* caller.mkdir("/project")
 
  const directory = yield* caller.openDirectory("/project")
 
  yield* caller.rename("/project", "/renamed")
  yield* caller.writeFile(
    Vfs.Target.Path({ path: "notes.txt", relativeTo: directory }),
    new TextEncoder().encode("kept"),
    {
      access: "write",
      create: "exclusive"
    }
  )
 
  return (yield* caller.readDirectory("/renamed")).value.map((entry) => new TextDecoder().decode(entry.name))
}).pipe(Effect.scoped)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'notes.txt' ]

export interface DirectoryHandle {
  readonly [DirectoryHandleId]: true
  readonly stat: Effect.Effect<Metadata, FsFailure>
  readonly close: Effect.Effect<void, FsFailure>
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
 
  const handle = yield* caller.open("/data.bin", {
    access: "readWrite",
    create: "exclusive"
  })
 
  yield* handle.write(new Uint8Array([1, 2, 3, 4]))
 
  // `pread` reads at an offset and leaves the cursor where writing left it.
  const slice = yield* handle.pread(2, 1n)
 
  return [slice.bytes, slice.eof, yield* handle.seek(0n, "current")]
}).pipe(Effect.scoped)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ Uint8Array(2) [ 2, 3 ], false, 4n ]

export interface FileHandle {
  readonly [FileHandleId]: true
  /** Reads up to `maximumBytes` from the cursor and advances it by the returned length. */
  readonly read: (maximumBytes: number) => Effect.Effect<Uint8Array, FsFailure>
  /** Reads at `offset` without changing the cursor. */
  readonly pread: (maximumBytes: number, offset: bigint) => Effect.Effect<ReadResult, FsFailure>
  /** Writes at the cursor and advances it, or writes at end of file when opened for append. */
  readonly write: (bytes: Uint8Array) => Effect.Effect<number, FsFailure>
  /**
   * Writes at `offset` without changing the cursor. Append mode does not affect positional writes.
   * The curried form is `pwrite(offset)(bytes)`.
   */
  readonly pwrite: {
    (offset: bigint): (bytes: Uint8Array) => Effect.Effect<number, FsFailure>
    (bytes: Uint8Array, offset: bigint): Effect.Effect<number, FsFailure>
  }
  /**
   * Moves the cursor and returns its new offset. `data` finds content and `hole` finds end of file.
   * The curried form is `seek(mode)(offset)`.
   */
  readonly seek: {
    (mode: SeekMode): (offset: bigint) => Effect.Effect<bigint, FsFailure>
    (offset: bigint, mode: SeekMode): Effect.Effect<bigint, FsFailure>
  }
  /** Sets the file length without changing the cursor. */
  readonly truncate: (length: bigint) => Effect.Effect<void, FsFailure>
  /** Reads metadata for the open file. */
  readonly stat: Effect.Effect<Metadata, FsFailure>
  /** Checks handle and provider health. Durable mutations have already committed; memory volumes have nothing to flush. */
  readonly sync: Effect.Effect<void, FsFailure>
  /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
  readonly close: Effect.Effect<void, FsFailure>
}

export type Fixture = {
  readonly entries: readonly (
    | {
        readonly path: string | BytePath
        readonly kind: "directory"
        readonly metadata?: {
          readonly uid?: number
          readonly gid?: number
          readonly mode?: number
          readonly atimeNs?: bigint
          readonly mtimeNs?: bigint
          readonly ctimeNs?: bigint
          readonly birthtimeNs?: bigint
        }
      }
    | {
        readonly path: string | BytePath
        readonly kind: "file"
        readonly bytes: Uint8Array<ArrayBufferLike>
        readonly metadata?: {
          readonly uid?: number
          readonly gid?: number
          readonly mode?: number
          readonly atimeNs?: bigint
          readonly mtimeNs?: bigint
          readonly ctimeNs?: bigint
          readonly birthtimeNs?: bigint
        }
      }
    | {
        readonly path: string | BytePath
        readonly kind: "symlink"
        readonly target: string | BytePath
        readonly metadata?: {
          readonly uid?: number
          readonly gid?: number
          readonly mode?: number
          readonly atimeNs?: bigint
          readonly mtimeNs?: bigint
          readonly ctimeNs?: bigint
          readonly birthtimeNs?: bigint
        }
      }
    | {
        readonly kind: "hardLink"
        readonly path: string | BytePath
        readonly target: string | BytePath
      }
  )[]
  readonly rootMetadata?: {
    readonly uid?: number
    readonly gid?: number
    readonly mode?: number
    readonly atimeNs?: bigint
    readonly mtimeNs?: bigint
    readonly ctimeNs?: bigint
    readonly birthtimeNs?: bigint
  }
}

export type FsCode =
  | "NotFound"
  | "AlreadyExists"
  | "NotEmpty"
  | "NotDirectory"
  | "AccessDenied"
  | "NotPermitted"
  | "InvalidHandle"
  | "ForeignHandle"
  | "InvalidReference"
  | "ForeignReference"
  | "StaleReference"
  | "ClosedCaller"
  | "InvalidArgument"
  | "InvalidPathEncoding"
  | "PathTooLong"
  | "NoSpace"
  | "IsDirectory"
  | "FileTooLarge"
  | "NoData"
  | "SymlinkLoop"
  | "UnrepresentableName"
  | "StorageRejected"
  | "OutcomeUnknown"
  | "VolumeUnavailable"
  | "VolumeBusy"

export type Identity = {
  readonly uid: number
  readonly gid: number
  readonly groups: readonly number[]
  readonly privileged: boolean
}

export type Metadata = {
  readonly kind: "file" | "directory" | "symlink"
  readonly ino: bigint
  readonly nlink: number
  readonly size: bigint
  readonly uid: number
  readonly gid: number
  readonly mode: number
  readonly atimeNs: bigint
  readonly mtimeNs: bigint
  readonly ctimeNs: bigint
  readonly birthtimeNs: bigint
  readonly revision: bigint
}

export type MkdirOptions = {
  readonly mode?: number
  readonly exactMode?: boolean
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
  readonly recursive?: boolean
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// References survive renames, and each observation carries the revision it
// matched, so a caller can tell whether what it read is still current.
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
 
  yield* caller.mkdir("/work")
 
  const root = yield* caller.root
  const work = yield* caller.lookup(Vfs.Entry(root, "work"))
 
  const before = yield* caller.stat(work)
 
  yield* caller.rename("/work", "/moved")
 
  const after = yield* caller.stat(work)
 
  return [before.kind, after.kind, after.revision > before.revision]
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'directory', 'directory', true ]

export interface ObjectObservation<A> {
  readonly value: A
  readonly revision: bigint
}

export interface ObjectReference {
  readonly [ObjectReferenceId]: true
}

export type OpenEntryOptions = {
  readonly access: "read" | "write" | "readWrite"
  readonly expected?: ObjectReference | null
  readonly mode?: number
  readonly create?: "never" | "ifMissing" | "exclusive"
  readonly append?: boolean
  readonly truncate?: boolean
  readonly exactMode?: boolean
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
  readonly owner?: { readonly uid?: number; readonly gid?: number }
  readonly followFinalSymlink?: boolean
  readonly initialSize?: bigint
  readonly expectedChild?: {
    readonly reference: ObjectReference
    readonly revision: bigint
    readonly atimeNs: bigint
    readonly mtimeNs: bigint
  } | null
}

export interface OpenEntryResult {
  readonly handle: FileHandle
  readonly reference: ObjectReference
  readonly created: boolean
  readonly directory: DirectoryChange
}

export type OpenOptions = {
  readonly access: "read" | "write" | "readWrite"
  readonly mode?: number
  readonly create?: "never" | "ifMissing" | "exclusive"
  readonly append?: boolean
  readonly truncate?: boolean
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const base = yield* Vfs.make()
  const workspace = yield* Vfs.makeOverlay(yield* base.snapshot)
 
  yield* (yield* workspace.caller()).writeFile("/out.txt", new TextEncoder().encode("built"), {
    access: "write",
    create: "exclusive"
  })
 
  // One committed state: the summary describes exactly the snapshot beside it,
  // so restoring from it cannot disagree with the change list.
  const captured = yield* workspace.capture()
  const restored = yield* Vfs.fromSnapshot(captured.snapshot)
  const reader = yield* restored.caller()
 
  return [captured.changes.map((change) => change._tag), new TextDecoder().decode(yield* reader.readFile("/out.txt"))]
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ [ 'Added' ], 'built' ]

export interface OverlayCapture {
  /** Complete version 1 snapshot owned by this capture. */
  readonly snapshot: Snapshot
  /** Owned summary that describes the same state as `snapshot`. */
  readonly changes: ReadonlyArray<OverlayChange>
}

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"
      )[]
    }

export type OverlayChangesOptions = { readonly includeTimestamps?: boolean }

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

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

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const base = yield* Vfs.make()
  const workspace = yield* Vfs.makeOverlay(yield* base.snapshot)
 
  yield* (yield* workspace.caller()).writeFile("/added.txt", new Uint8Array([1]), {
    access: "write",
    create: "exclusive"
  })
 
  // `capture` pairs one committed snapshot with the summary describing it.
  const captured = yield* workspace.capture()
 
  return captured.changes.map((change) => change._tag)
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'Added' ]

export interface OverlayVolume extends Volume {
  /** Computes final differences from the immutable base when this reusable effect executes. */
  readonly changes: (options?: OverlayChangesOptions) => Effect.Effect<ReadonlyArray<OverlayChange>, VfsError>
  /** Captures one committed state when this reusable effect executes. */
  readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, VfsError>
}

export type OwnerUpdate = { readonly uid?: number; readonly gid?: number }

type PathInput = string | BytePath

export interface ReadResult {
  readonly bytes: Uint8Array
  readonly eof: boolean
}

export interface ReferenceEntryResult {
  readonly reference: ObjectReference
  readonly directory: DirectoryChange
}

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

export type RemoveOptions = {
  readonly expected?: ObjectReference
  readonly recursive?: boolean
  readonly force?: boolean
}

export type RenameReferenceResult =
  | {
      readonly _tag: "DifferentDirectories"
      readonly sourceDirectory: { readonly before: bigint; readonly after: bigint }
      readonly destinationDirectory: { readonly before: bigint; readonly after: bigint }
    }
  | {
      readonly _tag: "SameDirectory"
      readonly directory: { readonly before: bigint; readonly after: bigint }
    }

export type RootCallerOptions = {
  readonly identity?: {
    readonly uid: number
    readonly gid: number
    readonly groups: readonly number[]
    readonly privileged: boolean
  }
  readonly umask?: number
}

export type SeekMode = "start" | "end" | "current" | "data" | "hole"

export type SetattrOptions = {
  readonly expected?: { readonly revision: bigint }
  readonly size?: bigint
  readonly mode?: number
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
  readonly owner?: { readonly uid?: number; readonly gid?: number }
}

export type SymlinkOptions = {
  readonly times?: {
    readonly access:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
    readonly modification:
      | { readonly kind: "now" }
      | { readonly kind: "omit" }
      | { readonly kind: "value"; readonly nanoseconds: bigint }
  }
}

export type Times = {
  readonly access:
    | { readonly kind: "now" }
    | { readonly kind: "omit" }
    | { readonly kind: "value"; readonly nanoseconds: bigint }
  readonly modification:
    | { readonly kind: "now" }
    | { readonly kind: "omit" }
    | { readonly kind: "value"; readonly nanoseconds: bigint }
}

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect, Fiber, Option, Stream } from "effect"
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.make()
  const caller = yield* volume.caller()
 
  // `watch` reports future changes only; nothing is replayed.
  const watcher = yield* volume
    .watch()
    .pipe(Effect.flatMap(Stream.runHead), Effect.forkChild({ startImmediately: true }))
 
  yield* caller.mkdir("/logs")
 
  const change = yield* Fiber.join(watcher)
 
  return Option.getOrElse(
    Option.map(change, (event) => event._tag),
    () => "none"
  )
}).pipe(Effect.scoped)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// Create

export interface Volume {
  /** The strongest failure boundary survived by acknowledged writes. */
  readonly durability: VolumeDurability
  /** Stable logical identity, preserved across reconstruction only when supplied explicitly. */
  readonly identity: VolumeIdentity
  /** Fresh identity for this uninterrupted storage lifetime. */
  readonly incarnation: VolumeIncarnation
  /** Effective static limits, where `undefined` means unlimited. */
  readonly limits: VolumeLimits
  /** Samples content bytes and directory entries together from the current committed state. */
  readonly usage: Effect.Effect<VolumeUsage, FsFailure>
  /**
   * Opens a scoped stream of future changes, registered before it returns; events are not replayed. Without a
   * scope it covers the volume and `Rescan` at `/` requires a full rescan; with one it covers that object (and its
   * subtree unless `recursive` is `false`), `Rescan` names the object's current path, and the stream ends after
   * `Remove` for the object once its last name is gone.
   */
  readonly watch: (options?: WatchOptions) => Effect.Effect<Stream.Stream<Change>, FsFailure, Scope.Scope>
  /** Captures an isolated snapshot of the reachable namespace and metadata. */
  readonly snapshot: Effect.Effect<Snapshot, VfsError>
  /**
   * The serialisable key of an object this volume issued. Fails with `InvalidReference` for a value that is not a
   * reference, `ForeignReference` for another volume's, and `StaleReference` once the object is gone.
   */
  readonly referenceKey: (reference: ObjectReference) => Effect.Effect<ReferenceKey, FsFailure>
  /**
   * The object a key names, as the same reference traversal returns. Fails with `InvalidReference` for a malformed
   * key or one whose tag this volume did not compute, `ForeignReference` for a key another volume or another epoch
   * of this one minted, and `StaleReference` once the object is gone. It checks no permission: holding the volume
   * already grants every caller, and the tag keeps a key holder from reaching an object no key was issued for.
   */
  readonly resolveReferenceKey: (key: ReferenceKey) => Effect.Effect<ObjectReference, FsFailure>
  readonly [VolumeId]: true
  /** Creates a caller rooted at `/` with independent credentials, umask, and current directory. */
  readonly caller: (options?: RootCallerOptions) => Effect.Effect<Caller, VfsError>
}

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

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

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

export interface VolumeLimits {
  readonly maxBytes: ByteSize.ByteSize | undefined
  readonly maxFileBytes: ByteSize.ByteSize
  readonly maxEntries: number | undefined
  readonly maxPathBytes: ByteSize.ByteSize | undefined
  /** Waiting budget; at most this many plus one callers are admitted at once. */
  readonly maxPendingOperations: number
  /** Maximum retained events per watch subscriber, including the rescan marker. */
  readonly maxWatchEvents: number
}

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
}

export interface VolumeUsage {
  readonly usedBytes: bigint
  readonly entries: number
}

export interface WalkEntry {
  readonly path: BytePath
  readonly name: Uint8Array
  readonly reference: ObjectReference
  readonly directory: ObjectReference
  readonly kind: Metadata["kind"]
  readonly depth: number
}

type WalkFailure = FsFailure | (VfsError & { readonly code: "LimitExceeded" })

export type WalkOptions = {
  readonly maxEntries?: number
  readonly maxDepth?: number
  readonly maxBytes?: ByteSize.ByteSize
  readonly order?: "pre" | "post"
}

export type WatchOptions = { readonly recursive?: boolean; readonly scope?: ObjectReference }

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
  const bytes = new TextEncoder().encode("v2")
 
  // `access` is required. `create: "exclusive"` refuses to replace an entry,
  // while `truncate` overwrites one that already exists.
  yield* caller.writeFile("/app.conf", new TextEncoder().encode("v1"), {
    access: "write",
    create: "exclusive",
    mode: 0o640
  })
 
  const refused = yield* caller
    .writeFile("/app.conf", bytes, {
      access: "write",
      create: "exclusive"
    })
    .pipe(
      Effect.as("replaced"),
      Effect.catchTag("VfsError", (error) => Effect.succeed(error.code))
    )
 
  yield* caller.writeFile("/app.conf", bytes, { access: "write", truncate: true })
 
  return [refused, new TextDecoder().decode(yield* caller.readFile("/app.conf"))]
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'AlreadyExists', 'v2' ]

declare const WriteFileOptions: Schema.Struct<{
  readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>
  readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>
  readonly mode: Schema.optionalKey<Schema.Natural>
  readonly append: Schema.optionalKey<Schema.Boolean>
  readonly truncate: Schema.optionalKey<Schema.Boolean>
  readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>
  readonly replaceFinalSymlink: Schema.optionalKey<Schema.Boolean>
  readonly finalMode: Schema.optionalKey<Schema.Natural>
}>

export type WriteFileOptions = {
  readonly access: "read" | "write" | "readWrite"
  readonly mode?: number
  readonly create?: "never" | "ifMissing" | "exclusive"
  readonly append?: boolean
  readonly truncate?: boolean
  readonly followFinalSymlink?: boolean
  readonly replaceFinalSymlink?: boolean
  readonly finalMode?: number
}

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

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

declare const CallerWatchOptions: Schema.Struct<{
  readonly recursive: Schema.optionalKey<Schema.Boolean>
  readonly alias: Schema.optionalKey<Schema.Literals<readonly ["all", "resolved"]>>
}>

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect, Fiber, Stream } from "effect"
 
const program = Effect.gen(function* () {
  const volume = yield* Vfs.make()
  const caller = yield* volume.caller()
 
  const watcher = yield* volume.watch().pipe(
    Effect.flatMap((stream) => Stream.runCollect(Stream.take(stream, 2))),
    Effect.forkChild({ startImmediately: true })
  )
 
  yield* caller.mkdir("/logs")
  yield* caller.rmdir("/logs")
 
  // Each event pairs the kind of change with the absolute path it happened to.
  const events = yield* Fiber.join(watcher)
 
  return yield* Effect.forEach(events, (change) =>
    Effect.map(Vfs.pathToBytes(change.path), (bytes) => `${change._tag} ${new TextDecoder().decode(bytes)}`)
  )
}).pipe(Effect.scoped)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ 'Create /logs', 'Remove /logs' ]

declare const Change: Schema.TaggedUnion<{
  readonly Create: Schema.TaggedStruct<"Create", { readonly path: Schema.declare<BytePath, BytePath> }>
  readonly Update: Schema.TaggedStruct<"Update", { readonly path: Schema.declare<BytePath, BytePath> }>
  readonly Remove: Schema.TaggedStruct<"Remove", { readonly path: Schema.declare<BytePath, BytePath> }>
  readonly Rescan: Schema.TaggedStruct<"Rescan", { readonly path: Schema.declare<BytePath, BytePath> }>
}>

declare const DirectoryChange: Schema.Struct<{ readonly before: Schema.BigInt; readonly after: Schema.BigInt }>

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect, Schema } from "effect"
 
// Fixtures must list every parent directory before its children.
const program = Schema.decodeUnknownEffect(Vfs.Fixture)({
  entries: [{ kind: "file", path: "/etc/hosts", bytes: new TextEncoder().encode("127.0.0.1") }]
}).pipe(
  Effect.flatMap(Vfs.fromFixture),
  Effect.as("built"),
  Effect.catchTag("VfsError", (error) => Effect.succeed(`rejected: ${error.code}`))
)
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// rejected: InvalidStructure

declare const Fixture: Schema.Struct<{
  readonly rootMetadata: Schema.optionalKey<
    Schema.Struct<{
      readonly uid: Schema.optionalKey<Schema.Natural>
      readonly gid: Schema.optionalKey<Schema.Natural>
      readonly mode: Schema.optionalKey<Schema.Natural>
      readonly atimeNs: Schema.optionalKey<Schema.BigInt>
      readonly mtimeNs: Schema.optionalKey<Schema.BigInt>
      readonly ctimeNs: Schema.optionalKey<Schema.BigInt>
      readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>
    }>
  >
  readonly entries: Schema.$Array<
    Schema.toTaggedUnion<
      "kind",
      readonly [
        Schema.Struct<{
          readonly kind: Schema.Literal<"directory">
          readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
          readonly metadata: Schema.optionalKey<
            Schema.Struct<{
              readonly uid: Schema.optionalKey<Schema.Natural>
              readonly gid: Schema.optionalKey<Schema.Natural>
              readonly mode: Schema.optionalKey<Schema.Natural>
              readonly atimeNs: Schema.optionalKey<Schema.BigInt>
              readonly mtimeNs: Schema.optionalKey<Schema.BigInt>
              readonly ctimeNs: Schema.optionalKey<Schema.BigInt>
              readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>
            }>
          >
        }>,
        Schema.Struct<{
          readonly kind: Schema.Literal<"file">
          readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
          readonly bytes: Schema.Uint8Array
          readonly metadata: Schema.optionalKey<
            Schema.Struct<{
              readonly uid: Schema.optionalKey<Schema.Natural>
              readonly gid: Schema.optionalKey<Schema.Natural>
              readonly mode: Schema.optionalKey<Schema.Natural>
              readonly atimeNs: Schema.optionalKey<Schema.BigInt>
              readonly mtimeNs: Schema.optionalKey<Schema.BigInt>
              readonly ctimeNs: Schema.optionalKey<Schema.BigInt>
              readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>
            }>
          >
        }>,
        Schema.Struct<{
          readonly kind: Schema.Literal<"symlink">
          readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
          readonly target: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
          readonly metadata: Schema.optionalKey<
            Schema.Struct<{
              readonly uid: Schema.optionalKey<Schema.Natural>
              readonly gid: Schema.optionalKey<Schema.Natural>
              readonly mode: Schema.optionalKey<Schema.Natural>
              readonly atimeNs: Schema.optionalKey<Schema.BigInt>
              readonly mtimeNs: Schema.optionalKey<Schema.BigInt>
              readonly ctimeNs: Schema.optionalKey<Schema.BigInt>
              readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>
            }>
          >
        }>,
        Schema.Struct<{
          readonly kind: Schema.Literal<"hardLink">
          readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
          readonly target: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>
        }>
      ]
    >
  >
}>