BytePath.ts overview

Opaque, byte-preserving filesystem paths.

A BytePath stores the exact bytes of a path component so that names which are not valid UTF-8 survive a round trip through the virtual filesystem.

Since v0.1.0

combinators

join

A byte path naming name under path. A string name is encoded as UTF-8 and not checked: a slash in it adds further components, and a NUL makes a path that fails where it is used.

Signature

declare const join: {
  (name: string | Uint8Array): (path: BytePath) => BytePath
  (path: BytePath, name: string | Uint8Array): BytePath
}

Source

Since v0.6.0

constructors

fromBytes

A byte path holding a copy of bytes, which must be non-empty and hold no NUL.

Signature

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

Source

Since v0.6.0

fromInput

A byte path for any path input: a byte path is returned as is, a string is encoded.

Signature

declare const fromInput: (input: PathInput) => Effect.Effect<BytePath, FsFailure>

Source

Since v0.6.0

fromString

A byte path holding the UTF-8 encoding of text.

Signature

declare const fromString: (text: string) => Effect.Effect<BytePath, FsFailure>

Source

Since v0.6.0

getters

basename

The final component of a byte path as bytes; empty for the root and for a path that ends in a slash.

Signature

declare const basename: (path: BytePath) => Uint8Array

Source

Since v0.6.0

decodeOption

The text of raw bytes such as an entry name, or none when they are not valid UTF-8.

Signature

declare const decodeOption: (bytes: Uint8Array) => Option.Option<string>

Source

Since v0.6.0

parent

The byte path holding everything before the final component, or the path itself when it has no parent.

Signature

declare const parent: (path: BytePath) => BytePath

Source

Since v0.6.0

toBytes

A copy of the bytes a byte path holds.

Signature

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

Source

Since v0.6.0

toString

The text of a byte path, failing as UnrepresentableName when its bytes are not valid UTF-8.

Signature

declare const toString: (path: BytePath) => Effect.Effect<string, FsFailure>

Source

Since v0.6.0

toStringOption

The text of a byte path, or none when its bytes are not valid UTF-8.

Signature

declare const toStringOption: (path: BytePath) => Option.Option<string>

Source

Since v0.6.0

models

BytePath (interface)

An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.

Example

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
// A name that is not valid UTF-8 still round-trips exactly.
const program = Effect.gen(function* () {
  const caller = yield* (yield* Vfs.make()).caller()
  const path = yield* Vfs.pathFromBytes(new Uint8Array([47, 0xff, 0xfe]))
 
  yield* caller.writeFile(path, new Uint8Array([1]), {
    access: "write",
    create: "exclusive"
  })
 
  // A listing carries names as bytes, so nothing is lost to text decoding.
  return (yield* caller.readDirectory("/")).value.map((entry) => entry.name)
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// [ Uint8Array(2) [ 255, 254 ] ]

Signature

export interface BytePath extends Equal.Equal, Pipeable {
  readonly [BytePathId]: BytePathId
}

Source

Since v0.1.0

ordering

Order

Orders byte paths by their bytes.

Signature

declare const Order: OrderModule.Order<BytePath>

Source

Since v0.6.0

byteOrder

Orders raw byte strings, such as entry names, byte by byte and then by length.

Signature

declare const byteOrder: OrderModule.Order<Uint8Array<ArrayBufferLike>>

Source

Since v0.6.0

predicates

isAbsolute

Whether a byte path starts with a slash.

Signature

declare const isAbsolute: (path: BytePath) => boolean

Source

Since v0.6.0

isBytePath

Whether a value is a byte path.

Signature

declare const isBytePath: (value: unknown) => value is BytePath

Source

Since v0.6.0

isRoot

Whether a byte path is exactly /.

Signature

declare const isRoot: (path: BytePath) => boolean

Source

Since v0.6.0

schemas

BytePath

Schema for an opaque byte-preserving filesystem path.

Signature

declare const BytePath: Schema.declare<BytePath, BytePath>

Source

Since v0.1.0

type IDs

BytePathId

Type identifier for opaque byte-preserving filesystem paths.

Signature

declare const BytePathId: "@effect-vfs/core/BytePath"

Source

Since v0.1.0

BytePathId (type alias)

Type identifier for opaque byte-preserving filesystem paths.

Signature

export type BytePathId = "@effect-vfs/core/BytePath"

Source

Since v0.1.0