@effect-vfs/core 0.5.0 → 0.7.0

package/README.md

@@ -16,8 +16,8 @@ for the exact permission, path, timestamp, quota, and atomicity rules.
 npm install @effect-vfs/core@latest
 ```
 
-The package declares its exact Effect version as a peer dependency. The examples also need a `Crypto` service. On Node
-or Bun, install the matching provider and supply `NodeCrypto.layer`:
+The package declares its exact Effect version as a peer dependency. Volume constructors and snapshot delta functions require Effect’s `Crypto` service. On Node, install the matching
+provider and supply `NodeCrypto.layer` when running these effects:
 
 ```sh
 npm install "@effect/platform-node-shared@$(npm view @effect-vfs/core peerDependencies.effect)"
@@ -111,9 +111,9 @@ const program = Effect.gen(function*() {
     create: "exclusive"
   })
 
-  const names = yield* fs.readDirectoryBytes("/")
+  const listing = yield* fs.readDirectory("/")
   const roundTrip = yield* Vfs.pathToBytes(opaquePath)
-  return { names: names.map((name) => Array.from(name)), roundTrip: Array.from(roundTrip) }
+  return { names: listing.value.map((entry) => Array.from(entry.name)), roundTrip: Array.from(roundTrip) }
 })
 
 console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))))
@@ -121,8 +121,8 @@ console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer
 ```
 
 The constructors and byte-returning operations copy their buffers, so later mutation cannot change stored paths.
-String-returning operations fail with `FsError` code `UnrepresentableName` when a name is not valid UTF-8. Use the byte
-variants of directory enumeration, symbolic-link targets, and resolved paths when exact bytes matter.
+Directory listings, symbolic-link targets, and resolved paths come back as bytes; decoding them to text is the caller's
+choice, and a strict decoder reports a name that is not valid UTF-8.
 
 ## Build fixtures and restore snapshots
 
@@ -213,10 +213,13 @@ const program = Effect.scoped(Effect.gen(function*() {
   const second = yield* file.read(4)
   const preview = yield* file.pread(3, 0n) // Does not move the cursor.
 
-  return [first, second, preview].map((bytes) => new TextDecoder().decode(bytes))
+  const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes)
+
+  // A positioned read also says whether it reached the end of the file.
+  return [decode(first), decode(second), decode(preview.bytes), preview.eof]
 }))
 
-console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))) // ["one\n", "two\n", "one"]
+console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))) // ["one\n", "two\n", "one", false]
 ```
 
 Handles also expose an explicit `close` effect when early release matters. Calling explicit close twice fails, while
@@ -224,9 +227,10 @@ scope cleanup remains safe after an explicit close.
 
 ## Handle expected failures as data
 
-Filesystem failures are typed `FsError` values with a stable `code`, `operation`, and optional `path`. Configuration
-and snapshot failures use `ConfigurationError` and `ImageError`. Interruption and defects remain separate from these
-expected failures.
+Every failure is a `VfsError` with a stable `code` and the `operation` that failed. A rejected option names its
+`field`, a path-addressed failure names its `path` as bytes, and a classified failure keeps its `cause`. Codec and
+store failures share the class with their own codes. Interruption and defects remain separate from these expected
+failures.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
@@ -237,7 +241,7 @@ const program = Effect.gen(function*() {
   const fs = yield* (yield* Vfs.make()).caller()
 
   return yield* fs.readFile("/optional.json").pipe(
-    Effect.catchTag("FsError", (error) =>
+    Effect.catchTag("VfsError", (error) =>
       error.code === "NotFound"
         ? Effect.succeed(new TextEncoder().encode("{}"))
         : Effect.fail(error))
@@ -248,11 +252,13 @@ const bytes = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.lay
 console.log(new TextDecoder().decode(bytes)) // {}
 ```
 
-## Provide a caller as an Effect service
+## Provide a volume and a caller as Effect services
 
-`CurrentFileSystem` is an optional service for application code that should receive an existing caller through its
-Effect environment. The service owns no storage; the provided caller keeps its original volume, identity, umask, and
-current directory.
+`Volume` and `Caller` are services with static layers. `Volume.layer()` builds a fresh empty volume,
+`Volume.layerFromSnapshot`, `Volume.layerFromFixture` and `Volume.layerOverlay` build one from existing state, and
+`Volume.layerLive` opens a durable one through the `LiveImageStore` in context. `Caller.layer(options)` makes a root
+caller on the volume in context. A caller supplied through the service keeps its original volume, identity, umask and
+working directory.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
@@ -260,21 +266,23 @@ import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { Effect } from "effect"
 
 const loadConfig = Effect.gen(function*() {
-  const fs = yield* Vfs.CurrentFileSystem
+  const fs = yield* Vfs.Caller
   return yield* fs.readFile("/app/config.json")
 })
 
 const program = Effect.gen(function*() {
-  const fs = yield* (yield* Vfs.make()).caller()
+  const fs = yield* Vfs.Caller
   yield* fs.mkdir("/app")
   yield* fs.writeFile("/app/config.json", new TextEncoder().encode("{}"), {
     access: "write",
     create: "exclusive"
   })
-  return yield* loadConfig.pipe(Effect.provideService(Vfs.CurrentFileSystem, fs))
+  return yield* loadConfig
 })
 
-const bytes = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
+const bytes = await Effect.runPromise(
+  program.pipe(Effect.provide(Vfs.Caller.layer()), Effect.provide(Vfs.Volume.layer()), Effect.provide(NodeCrypto.layer))
+)
 console.log(new TextDecoder().decode(bytes)) // {}
 ```
 
@@ -295,7 +303,7 @@ candidate.
 - Absolute paths ignore a supplied directory base. Relative paths can use a live, same-volume directory handle.
 - Operations coordinate through one permit per volume. At most 65 operations are admitted at once by
   default, including the active operation; set `maxPendingOperations` to change the waiting budget.
-  Excess work fails with retryable `FsError` code `VolumeBusy`
+  Excess work fails with retryable `VfsError` code `VolumeBusy`
   before mutation or storage commit. Interruption while waiting makes no change; interruption after a commit
   does not roll it back.
 - Each watch subscriber retains at most 256 events by default; set `maxWatchEvents` to change this bound

package/dist/BytePath.d.ts

@@ -6,9 +6,14 @@
  *
  * @since 0.1.0
  */
+import * as Effect from "effect/Effect";
 import type * as Equal from "effect/Equal";
+import * as Option from "effect/Option";
+import * as OrderModule from "effect/Order";
 import type { Pipeable } from "effect/Pipeable";
 import * as Schema from "effect/Schema";
+import type { FsFailure } from "./VfsError.js";
+import type { PathInput } from "./VirtualFileSystem.js";
 /**
  * Type identifier for opaque byte-preserving filesystem paths.
  *
@@ -28,8 +33,8 @@ export type BytePathId = typeof BytePathId;
  *
  * @example
  * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // A name that is not valid UTF-8 still round-trips exactly.
@@ -42,11 +47,11 @@ export type BytePathId = typeof BytePathId;
  *     create: "exclusive"
  *   })
  *
- *   // `readDirectory` fails `UnrepresentableName` here; the byte variant keeps it.
- *   return yield* caller.readDirectoryBytes("/")
+ *   // 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(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
  * // [ Uint8Array(2) [ 255, 254 ] ]
  * ```
  *
@@ -63,4 +68,110 @@ export interface BytePath extends Equal.Equal, Pipeable {
  * @since 0.1.0
  */
 export declare const BytePath: Schema.declare<BytePath, BytePath>;
+/**
+ * Whether a value is a byte path.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export declare const isBytePath: (value: unknown) => value is BytePath;
+/**
+ * Orders raw byte strings, such as entry names, byte by byte and then by length.
+ *
+ * @category ordering
+ * @since 0.6.0
+ */
+export declare const byteOrder: OrderModule.Order<Uint8Array>;
+/**
+ * Orders byte paths by their bytes.
+ *
+ * @category ordering
+ * @since 0.6.0
+ */
+export declare const Order: OrderModule.Order<BytePath>;
+/**
+ * A byte path holding a copy of `bytes`, which must be non-empty and hold no NUL.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export declare const fromBytes: (bytes: Uint8Array) => Effect.Effect<BytePath, FsFailure>;
+/**
+ * A byte path holding the UTF-8 encoding of `text`.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export declare const fromString: (text: string) => Effect.Effect<BytePath, FsFailure>;
+/**
+ * A byte path for any path input: a byte path is returned as is, a string is encoded.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export declare const fromInput: (input: PathInput) => Effect.Effect<BytePath, FsFailure>;
+/**
+ * A copy of the bytes a byte path holds.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const toBytes: (path: BytePath) => Effect.Effect<Uint8Array, FsFailure>;
+/**
+ * The text of a byte path, failing as `UnrepresentableName` when its bytes are not valid UTF-8.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const toString: (path: BytePath) => Effect.Effect<string, FsFailure>;
+/**
+ * The text of a byte path, or none when its bytes are not valid UTF-8.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const toStringOption: (path: BytePath) => Option.Option<string>;
+/**
+ * The text of raw bytes such as an entry name, or none when they are not valid UTF-8.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const decodeOption: (bytes: Uint8Array) => Option.Option<string>;
+/**
+ * Whether a byte path is exactly `/`.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export declare const isRoot: (path: BytePath) => boolean;
+/**
+ * Whether a byte path starts with a slash.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export declare const isAbsolute: (path: BytePath) => boolean;
+/**
+ * The final component of a byte path as bytes; empty for the root and for a path that ends in a slash.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const basename: (path: BytePath) => Uint8Array;
+/**
+ * The byte path holding everything before the final component, or the path itself when it has no parent.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const parent: (path: BytePath) => BytePath;
+/**
+ * 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.
+ *
+ * @category combinators
+ * @since 0.6.0
+ */
+export declare const join: (path: BytePath, name: string | Uint8Array) => BytePath;
 //# sourceMappingURL=BytePath.d.ts.map

package/dist/BytePath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BytePath.d.ts","sourceRoot":"","sources":["../src/BytePath.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,2BAAiD,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK,CAAC,KAAK,EAAE,QAAQ;IACrD,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAAgD,CAAA"}
+{"version":3,"file":"BytePath.d.ts","sourceRoot":"","sources":["../src/BytePath.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,WAAW,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAG/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAKvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,2BAAiD,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK,CAAC,KAAK,EAAE,QAAQ;IACrD,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAAgD,CAAA;AAUrE;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,QAA8B,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC,UAAU,CAAoB,CAAA;AAExE;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAmD,CAAA;AAMjG;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAW,UAAU,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CACvB,CAAA;AAExD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAM1E,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAW,SAAS,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CACN,CAAA;AAExE;;;;;GAKG;AACH,eAAO,MAAM,OAAO,SAAU,QAAQ,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CACzB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,SAAU,QAAQ,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAItE,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,SAAU,QAAQ,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAgC,CAAA;AAEpG;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAErE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,SAAU,QAAQ,KAAG,OAIvC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,SAAU,QAAQ,KAAG,OAAqC,CAAA;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,SAAU,QAAQ,KAAG,UAIzC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,SAAU,QAAQ,KAAG,QAOvC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,SAAU,QAAQ,QAAQ,MAAM,GAAG,UAAU,KAAG,QAWhE,CAAA"}

package/dist/BytePath.js

@@ -1,5 +1,21 @@
+/**
+ * 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 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as OrderModule from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as Internal from "./internal/bytePath.js";
+import * as Bytes from "./internal/bytes.js";
+import { fsFailure, retargetFailure } from "./internal/errors.js";
+import * as Path from "./internal/path.js";
 /**
  * Type identifier for opaque byte-preserving filesystem paths.
  *
@@ -14,3 +30,142 @@ export const BytePathId = Internal.BytePathId;
  * @since 0.1.0
  */
 export const BytePath = Schema.declare(Internal.isBytePath);
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const SLASH = 0x2f;
+const bytesOf = (path) => Internal.getBytes(path) ?? new Uint8Array();
+/**
+ * Whether a value is a byte path.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export const isBytePath = Internal.isBytePath;
+/**
+ * Orders raw byte strings, such as entry names, byte by byte and then by length.
+ *
+ * @category ordering
+ * @since 0.6.0
+ */
+export const byteOrder = Bytes.bytesOrder;
+/**
+ * Orders byte paths by their bytes.
+ *
+ * @category ordering
+ * @since 0.6.0
+ */
+export const Order = OrderModule.mapInput(Bytes.bytesOrder, bytesOf);
+// The shared conversions fail under their own names; each toolkit function names itself instead.
+const named = (operation, effect) => Effect.mapError(effect, (error) => retargetFailure(operation, error));
+/**
+ * A byte path holding a copy of `bytes`, which must be non-empty and hold no NUL.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export const fromBytes = (bytes) => named("BytePath.fromBytes", Path.pathFromBytes(bytes));
+/**
+ * A byte path holding the UTF-8 encoding of `text`.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export const fromString = (text) => {
+    const bytes = Path.inputBytes(text);
+    return Result.isFailure(bytes)
+        ? Effect.fail(fsFailure(bytes.failure, "BytePath.fromString"))
+        : named("BytePath.fromString", Path.pathFromBytes(new Uint8Array(bytes.success)));
+};
+/**
+ * A byte path for any path input: a byte path is returned as is, a string is encoded.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export const fromInput = (input) => Internal.isBytePath(input) ? Effect.succeed(input) : fromString(input);
+/**
+ * A copy of the bytes a byte path holds.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const toBytes = (path) => named("BytePath.toBytes", Path.pathToBytes(path));
+/**
+ * The text of a byte path, failing as `UnrepresentableName` when its bytes are not valid UTF-8.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const toString = (path) => Effect.flatMap(named("BytePath.toString", Path.pathToBytes(path)), (bytes) => Path.strictString(bytes, "BytePath.toString"));
+/**
+ * The text of a byte path, or none when its bytes are not valid UTF-8.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const toStringOption = (path) => decodeOption(bytesOf(path));
+/**
+ * The text of raw bytes such as an entry name, or none when they are not valid UTF-8.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const decodeOption = Option.liftThrowable((bytes) => decoder.decode(bytes));
+/**
+ * Whether a byte path is exactly `/`.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export const isRoot = (path) => {
+    const bytes = bytesOf(path);
+    return bytes.length === 1 && bytes[0] === SLASH;
+};
+/**
+ * Whether a byte path starts with a slash.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export const isAbsolute = (path) => bytesOf(path)[0] === SLASH;
+/**
+ * The final component of a byte path as bytes; empty for the root and for a path that ends in a slash.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const basename = (path) => {
+    const bytes = bytesOf(path);
+    return bytes.slice(bytes.lastIndexOf(SLASH) + 1);
+};
+/**
+ * The byte path holding everything before the final component, or the path itself when it has no parent.
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export const parent = (path) => {
+    const bytes = bytesOf(path);
+    const slash = bytes.lastIndexOf(SLASH);
+    if (slash < 0)
+        return path;
+    return Internal.make(slash === 0 ? bytes.slice(0, 1) : bytes.slice(0, slash));
+};
+/**
+ * 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.
+ *
+ * @category combinators
+ * @since 0.6.0
+ */
+export const join = (path, name) => {
+    const prefix = bytesOf(path);
+    const suffix = Predicate.isString(name) ? encoder.encode(name) : name;
+    const separator = prefix.length > 0 && prefix[prefix.length - 1] === SLASH ? 0 : 1;
+    const output = new Uint8Array(prefix.length + separator + suffix.length);
+    output.set(prefix);
+    if (separator === 1)
+        output[prefix.length] = SLASH;
+    output.set(suffix, prefix.length + separator);
+    return Internal.make(output);
+};