@effect-vfs/core 0.5.0 → 0.7.0

package/dist/Target.d.ts

@@ -0,0 +1,225 @@
+/**
+ * How a caller names what it operates on. A `Target` is a path, an object
+ * reference, or an open handle; an `Entry` is a child of a directory target
+ * called `name`. Every verb takes one or the other, so the three addressing
+ * modes share one body and one option vocabulary.
+ *
+ * @since 0.6.0
+ */
+import * as Data from "effect/Data";
+import * as Schema from "effect/Schema";
+import type { DirectoryHandle, FileHandle, ObjectReference, PathInput } from "./VirtualFileSystem.js";
+/**
+ * A target: a path resolved from the caller's working directory or a base
+ * handle, an object reference, or an open handle.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Target = Data.TaggedEnum<{
+    readonly Path: {
+        readonly path: PathInput;
+        /** A live directory handle from the same volume that a relative path starts from. */
+        readonly relativeTo?: DirectoryHandle;
+        /** Whether a final symbolic link is followed. Defaults to `true`. */
+        readonly followFinalSymlink?: boolean;
+    };
+    readonly Reference: {
+        readonly reference: ObjectReference;
+    };
+    readonly Handle: {
+        readonly handle: FileHandle | DirectoryHandle;
+    };
+}>;
+declare const enumeration: {
+    readonly $is: <Tag extends "Handle" | "Path" | "Reference">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Handle";
+        readonly handle: FileHandle | DirectoryHandle;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Path";
+        readonly path: PathInput;
+        readonly relativeTo?: DirectoryHandle;
+        readonly followFinalSymlink?: boolean;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Reference";
+        readonly reference: ObjectReference;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "Handle" | "Path" | "Reference"]: (args: Extract<{
+            readonly _tag: "Handle";
+            readonly handle: FileHandle | DirectoryHandle;
+        } | {
+            readonly _tag: "Path";
+            readonly path: PathInput;
+            readonly relativeTo?: DirectoryHandle;
+            readonly followFinalSymlink?: boolean;
+        } | {
+            readonly _tag: "Reference";
+            readonly reference: ObjectReference;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "Handle";
+            readonly handle: FileHandle | DirectoryHandle;
+        } | {
+            readonly _tag: "Path";
+            readonly path: PathInput;
+            readonly relativeTo?: DirectoryHandle;
+            readonly followFinalSymlink?: boolean;
+        } | {
+            readonly _tag: "Reference";
+            readonly reference: ObjectReference;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Handle" | "Path" | "Reference"]>>;
+        <Cases extends { readonly [Tag in "Handle" | "Path" | "Reference"]: (args: Extract<{
+            readonly _tag: "Handle";
+            readonly handle: FileHandle | DirectoryHandle;
+        } | {
+            readonly _tag: "Path";
+            readonly path: PathInput;
+            readonly relativeTo?: DirectoryHandle;
+            readonly followFinalSymlink?: boolean;
+        } | {
+            readonly _tag: "Reference";
+            readonly reference: ObjectReference;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Handle";
+            readonly handle: FileHandle | DirectoryHandle;
+        } | {
+            readonly _tag: "Path";
+            readonly path: PathInput;
+            readonly relativeTo?: DirectoryHandle;
+            readonly followFinalSymlink?: boolean;
+        } | {
+            readonly _tag: "Reference";
+            readonly reference: ObjectReference;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Handle" | "Path" | "Reference"]>>;
+    };
+    readonly Handle: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Handle";
+        readonly handle: FileHandle | DirectoryHandle;
+    }, "_tag">;
+    readonly Path: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Path";
+        readonly path: PathInput;
+        readonly relativeTo?: DirectoryHandle;
+        readonly followFinalSymlink?: boolean;
+    }, "_tag">;
+    readonly Reference: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Reference";
+        readonly reference: ObjectReference;
+    }, "_tag">;
+};
+/**
+ * Whether a value is a `Target`.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export declare const isTarget: (value: unknown) => value is Target;
+/**
+ * Anything a verb accepts where it takes a target: a `Target`, or the bare
+ * path, reference, or handle it would wrap.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type TargetInput = Target | PathInput | ObjectReference | FileHandle | DirectoryHandle;
+/**
+ * Constructors and matchers for `Target`, plus `of`, which wraps a bare path,
+ * reference, or handle.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export declare const Target: typeof enumeration & {
+    readonly of: (input: TargetInput) => Target;
+};
+/**
+ * A directory entry name as bytes or as a string encoded as UTF-8: one to 255
+ * bytes with no NUL and no slash. `.` and `..` are well formed but reserved.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type NameInput = string | Uint8Array;
+/**
+ * Schema for a well-formed entry name, as bytes.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const Name: Schema.Uint8Array;
+/**
+ * A well-formed entry name, as bytes.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Name = typeof Name.Type;
+/**
+ * A child of a directory target, called `name`.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export interface Entry {
+    readonly directory: Target;
+    readonly name: NameInput;
+}
+/**
+ * Anything a verb accepts where it takes an entry: an `Entry`, or a path (bare
+ * or as a path target with a base) whose final component is the name and
+ * whose prefix is the directory.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type EntryInput = Entry | PathInput | PathTarget;
+/**
+ * The path variant of `Target`.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type PathTarget = Extract<Target, {
+    readonly _tag: "Path";
+}>;
+/**
+ * Whether a value is an `Entry`.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export declare const isEntry: (value: unknown) => value is Entry;
+/**
+ * Names a child of a directory. The directory may be given bare.
+ *
+ * @example
+ * ```ts
+ * import { Entry, Target } from "@effect-vfs/core/Target"
+ *
+ * const explicit = Entry(Target.Path({ path: "/var" }), "log")
+ * const bare = Entry("/var", "log")
+ * ```
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export declare const Entry: (directory: TargetInput, name: NameInput) => Entry;
+/**
+ * Whether a path input is a byte path rather than a string.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export declare const isBytePathInput: (input: PathInput) => boolean;
+export {};
+//# sourceMappingURL=Target.d.ts.map

package/dist/Target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Target.d.ts","sourceRoot":"","sources":["../src/Target.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAErG;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;QACxB,qFAAqF;QACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAA;QACrC,qEAAqE;QACrE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KACtC,CAAA;IACD,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAA;KAAE,CAAA;IAC3D,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,eAAe,CAAA;KAAE,CAAA;CACnE,CAAC,CAAA;AAQF,QAAA,MAAM,WAAW;;;yBATqB,UAAU,GAAG,eAAe;;;;;uBAP/C,SAAS;8BAEF,eAAe;sCAEP,OAAO;;;;;4BAEG,eAAe;;;;;;;6BACrB,UAAU,GAAG,eAAe;;;2BAP/C,SAAS;kCAEF,eAAe;0CAEP,OAAO;;;gCAEG,eAAe;;;;;;;;;;;;;;;;;6BACrB,UAAU,GAAG,eAAe;;;2BAP/C,SAAS;kCAEF,eAAe;0CAEP,OAAO;;;gCAEG,eAAe;;;;;;;;;;;;;;;;;;yBACrB,UAAU,GAAG,eAAe;;;;uBAP/C,SAAS;8BAEF,eAAe;sCAEP,OAAO;;;;4BAEG,eAAe;;CAUd,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAW,OAAO,KAAG,KAAK,IAAI,MACiE,CAAA;AAEpH;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,UAAU,GAAG,eAAe,CAAA;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE,OAAO,WAAW,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAA;CAiBtF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,IAAI,mBAYhB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,UAAU,CAAA;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,OAAO,UAAW,OAAO,KAAG,KAAK,IAAI,KAC8D,CAAA;AAEhH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,cAAe,WAAW,QAAQ,SAAS,KAAG,KAAoD,CAAA;AAEpH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UAAW,SAAS,KAAG,OAAqC,CAAA"}

package/dist/Target.js

@@ -0,0 +1,92 @@
+/**
+ * How a caller names what it operates on. A `Target` is a path, an object
+ * reference, or an open handle; an `Entry` is a child of a directory target
+ * called `name`. Every verb takes one or the other, so the three addressing
+ * modes share one body and one option vocabulary.
+ *
+ * @since 0.6.0
+ */
+import * as Data from "effect/Data";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { DirectoryHandleId, FileHandleId } from "./FileHandle.js";
+import * as Internal from "./internal/bytePath.js";
+const isFileHandle = (value) => Predicate.hasProperty(FileHandleId)(value) && value[FileHandleId] === true;
+const isDirectoryHandle = (value) => Predicate.hasProperty(DirectoryHandleId)(value) && value[DirectoryHandleId] === true;
+const enumeration = Data.taggedEnum();
+/**
+ * Whether a value is a `Target`.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export const isTarget = (value) => Predicate.isTagged("Path")(value) || Predicate.isTagged("Reference")(value) || Predicate.isTagged("Handle")(value);
+/**
+ * Constructors and matchers for `Target`, plus `of`, which wraps a bare path,
+ * reference, or handle.
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export const Target = {
+    Path: enumeration.Path,
+    Reference: enumeration.Reference,
+    Handle: enumeration.Handle,
+    $is: enumeration.$is,
+    $match: enumeration.$match,
+    // A string or byte path is a path and a handle is a handle; anything else is taken for a reference, so a forged
+    // token reaches the registry and is reported as one.
+    of: (input) => {
+        if (isTarget(input))
+            return input;
+        if (isFileHandle(input) || isDirectoryHandle(input))
+            return enumeration.Handle({ handle: input });
+        if (Predicate.isString(input) || Internal.isBytePath(input))
+            return enumeration.Path({ path: input });
+        return enumeration.Reference({ reference: input });
+    }
+};
+/**
+ * Schema for a well-formed entry name, as bytes.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const Name = Schema.Uint8Array.check(Schema.makeFilter((bytes) => bytes.length === 0
+    ? "must not be empty"
+    : bytes.length > 255
+        ? "must be at most 255 bytes"
+        : bytes.includes(0)
+            ? "must not contain NUL"
+            : bytes.includes(0x2f)
+                ? "must not contain a slash"
+                : undefined));
+/**
+ * Whether a value is an `Entry`.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export const isEntry = (value) => Predicate.hasProperty(value, "directory") && Predicate.hasProperty(value, "name") && isTarget(value.directory);
+/**
+ * Names a child of a directory. The directory may be given bare.
+ *
+ * @example
+ * ```ts
+ * import { Entry, Target } from "@effect-vfs/core/Target"
+ *
+ * const explicit = Entry(Target.Path({ path: "/var" }), "log")
+ * const bare = Entry("/var", "log")
+ * ```
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export const Entry = (directory, name) => ({ directory: Target.of(directory), name });
+/**
+ * Whether a path input is a byte path rather than a string.
+ *
+ * @category predicates
+ * @since 0.6.0
+ */
+export const isBytePathInput = (input) => Internal.isBytePath(input);

package/dist/Testing.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Test helpers over the `Volume` and `Caller` services: a fresh volume with a
+ * root caller as one layer, callers with other credentials on the volume in
+ * context, and collecting a known number of watch changes.
+ *
+ * **Details**
+ *
+ * The helpers are plain Effect values with no test-runner dependency. Each
+ * build of `layer` is a fresh volume, so provide it to every test that needs
+ * its own state, and share one build only between tests that do not
+ * interfere.
+ *
+ * @since 0.6.0
+ */
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type { Identity, RootCallerOptions } from "./Caller.js";
+import type { Fixture } from "./Fixture.js";
+import type { VfsError } from "./VfsError.js";
+import { Caller, Volume } from "./VirtualFileSystem.js";
+import type { VolumeOptions } from "./Volume.js";
+/**
+ * Options of a test volume layer.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export interface LayerOptions {
+    /** Entries the volume starts with; without one the volume starts empty. */
+    readonly fixture?: Fixture;
+    /** Limits and identity of the volume. */
+    readonly volume?: VolumeOptions;
+    /** Credentials and umask of the root caller the layer provides. */
+    readonly caller?: RootCallerOptions;
+}
+/**
+ * A fresh volume and a root caller on it, as one layer.
+ *
+ * **Details**
+ *
+ * Every build constructs a new volume, from `fixture` when one is given. The
+ * layer fails with the `VfsError` the constructor or the caller reports for
+ * invalid options. Provide `Crypto.Crypto` to build the volume.
+ *
+ * @example
+ * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as Testing from "@effect-vfs/core/Testing"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const fs = yield* Vfs.Caller
+ *   yield* fs.mkdir("/work")
+ *
+ *   return (yield* fs.readDirectory("/")).value.map((entry) => new TextDecoder().decode(entry.name))
+ * })
+ *
+ * // Each provide builds its own volume, so neither run sees the other's writes.
+ * Effect.runPromise(program.pipe(Effect.provide(Testing.layer()), Effect.provide(BunCrypto.layer))).then(console.log)
+ * // [ 'work' ]
+ * ```
+ *
+ * @category layers
+ * @since 0.6.0
+ */
+export declare const layer: (options?: LayerOptions) => Layer.Layer<Volume | Caller, VfsError, Crypto.Crypto>;
+/**
+ * A root caller with `identity` on the volume in context.
+ *
+ * @example
+ * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as Testing from "@effect-vfs/core/Testing"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* (yield* Vfs.Caller).mkdir("/private", { mode: 0o700 })
+ *
+ *   const guest = yield* Testing.callerAs({ uid: 1000, gid: 1000, groups: [], privileged: false })
+ *
+ *   return (yield* Effect.flip(guest.readDirectory("/private"))).code
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(Testing.layer()), Effect.provide(BunCrypto.layer))).then(console.log)
+ * // AccessDenied
+ * ```
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export declare const callerAs: (identity: Identity, options?: Omit<RootCallerOptions, "identity">) => Effect.Effect<Caller, VfsError, Volume>;
+/**
+ * Starts collecting the first `n` elements of `stream` and returns an effect
+ * that waits for them.
+ *
+ * **Details**
+ *
+ * The collection runs in a fiber of the current scope, so the returned effect
+ * can be awaited after the writes that produce the changes. Open the watch
+ * stream before writing: a volume publishes only changes committed after the
+ * subscription.
+ *
+ * @example
+ * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as Testing from "@effect-vfs/core/Testing"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.Volume
+ *   const changes = yield* Testing.collectChanges(yield* volume.watch(), 1)
+ *
+ *   yield* (yield* Vfs.Caller).mkdir("/work")
+ *
+ *   return (yield* changes).map((change) => change._tag)
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.scoped, Effect.provide(Testing.layer()), Effect.provide(BunCrypto.layer))).then(console.log)
+ * // [ 'Create' ]
+ * ```
+ *
+ * @category combinators
+ * @since 0.6.0
+ */
+export declare const collectChanges: <A, E, R>(stream: Stream.Stream<A, E, R>, n: number) => Effect.Effect<Effect.Effect<Array<A>, E>, never, R | Scope.Scope>;
+//# sourceMappingURL=Testing.d.ts.map

package/dist/Testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Testing.d.ts","sourceRoot":"","sources":["../src/Testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,KAAK,aAAc,YAAY,KAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAOhG,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,aACT,QAAQ,YACR,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,KAC5C,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CACoC,CAAA;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,KACR,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAIhE,CAAA"}

package/dist/Testing.js

@@ -0,0 +1,100 @@
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { Caller, Volume } from "./VirtualFileSystem.js";
+/**
+ * A fresh volume and a root caller on it, as one layer.
+ *
+ * **Details**
+ *
+ * Every build constructs a new volume, from `fixture` when one is given. The
+ * layer fails with the `VfsError` the constructor or the caller reports for
+ * invalid options. Provide `Crypto.Crypto` to build the volume.
+ *
+ * @example
+ * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as Testing from "@effect-vfs/core/Testing"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const fs = yield* Vfs.Caller
+ *   yield* fs.mkdir("/work")
+ *
+ *   return (yield* fs.readDirectory("/")).value.map((entry) => new TextDecoder().decode(entry.name))
+ * })
+ *
+ * // Each provide builds its own volume, so neither run sees the other's writes.
+ * Effect.runPromise(program.pipe(Effect.provide(Testing.layer()), Effect.provide(BunCrypto.layer))).then(console.log)
+ * // [ 'work' ]
+ * ```
+ *
+ * @category layers
+ * @since 0.6.0
+ */
+export const layer = (options) => Caller.layer(options?.caller).pipe(Layer.provideMerge(options?.fixture === undefined
+    ? Volume.layer(options?.volume)
+    : Volume.layerFromFixture(options.fixture, options.volume)));
+/**
+ * A root caller with `identity` on the volume in context.
+ *
+ * @example
+ * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as Testing from "@effect-vfs/core/Testing"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* (yield* Vfs.Caller).mkdir("/private", { mode: 0o700 })
+ *
+ *   const guest = yield* Testing.callerAs({ uid: 1000, gid: 1000, groups: [], privileged: false })
+ *
+ *   return (yield* Effect.flip(guest.readDirectory("/private"))).code
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(Testing.layer()), Effect.provide(BunCrypto.layer))).then(console.log)
+ * // AccessDenied
+ * ```
+ *
+ * @category constructors
+ * @since 0.6.0
+ */
+export const callerAs = (identity, options) => Effect.flatMap(Volume, (volume) => volume.caller({ ...options, identity }));
+/**
+ * Starts collecting the first `n` elements of `stream` and returns an effect
+ * that waits for them.
+ *
+ * **Details**
+ *
+ * The collection runs in a fiber of the current scope, so the returned effect
+ * can be awaited after the writes that produce the changes. Open the watch
+ * stream before writing: a volume publishes only changes committed after the
+ * subscription.
+ *
+ * @example
+ * ```ts
+ * import * as BunCrypto from "@effect/platform-bun/BunCrypto"
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as Testing from "@effect-vfs/core/Testing"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.Volume
+ *   const changes = yield* Testing.collectChanges(yield* volume.watch(), 1)
+ *
+ *   yield* (yield* Vfs.Caller).mkdir("/work")
+ *
+ *   return (yield* changes).map((change) => change._tag)
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.scoped, Effect.provide(Testing.layer()), Effect.provide(BunCrypto.layer))).then(console.log)
+ * // [ 'Create' ]
+ * ```
+ *
+ * @category combinators
+ * @since 0.6.0
+ */
+export const collectChanges = (stream, n) => Stream.runCollect(Stream.take(stream, n)).pipe(Effect.forkScoped({ startImmediately: true }), Effect.map(Fiber.join));