VFS.Stat (VFS v0.1.0)

Copy Markdown View Source

Metadata for a path in a virtual filesystem.

Deliberately not File.Stat: that struct is shaped around POSIX stat(2) for real OS files (inode, uid, gid, links, major_device, minor_device). For virtual backends — git blobs, S3 objects, in-memory maps — those fields are meaningless and would be nil constantly. Better to have a struct shaped to the abstraction.

Fields follow File.Stat conventions where they exist (type :: atom(), not is_file :: boolean()).

Fields

  • :type — one of :regular, :directory, :symlink, :other.
  • :size — bytes for files; backends typically return 0 for directories.
  • :mtime — DateTime.t(). Backends without real mtimes (e.g. content-addressed git blobs) use a deterministic value such as the containing tree's commit time or epoch.
  • :mode — POSIX permission bits when meaningful, nil when not (e.g. S3).

Summary

Types

t()
type()

The kind of filesystem entry.

Functions

directory(mtime, mode \\ nil)

Build a directory stat.

regular(size, mtime, mode \\ nil)

Build a regular-file stat. Convenience constructor for backends that always set type: :regular and don't track mode.

Types

t()

@type t() :: %VFS.Stat{
  mode: non_neg_integer() | nil,
  mtime: DateTime.t(),
  size: non_neg_integer(),
  type: type()
}

type()

@type type() :: :regular | :directory | :symlink | :other

The kind of filesystem entry.

Functions

directory(mtime, mode \\ nil)

@spec directory(DateTime.t(), non_neg_integer() | nil) :: t()

Build a directory stat.

Examples

iex> VFS.Stat.directory(~U[2026-05-01 12:00:00Z])
%VFS.Stat{type: :directory, size: 0, mtime: ~U[2026-05-01 12:00:00Z], mode: nil}

regular(size, mtime, mode \\ nil)

@spec regular(non_neg_integer(), DateTime.t(), non_neg_integer() | nil) :: t()

Build a regular-file stat. Convenience constructor for backends that always set type: :regular and don't track mode.

Examples

iex> VFS.Stat.regular(42, ~U[2026-05-01 12:00:00Z])
%VFS.Stat{type: :regular, size: 42, mtime: ~U[2026-05-01 12:00:00Z], mode: nil}