@effect-vfs/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lloyd Richards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# @effect-vfs/core
+
+`@effect-vfs/core` is a runtime-neutral virtual filesystem engine for Effect. It gives you isolated in-memory volumes,
+byte-preserving paths, POSIX-inspired permissions, logical quotas, change streams, deterministic fixtures, and portable
+encoded snapshots without reading from or writing to the host filesystem.
+
+Use it when filesystem state is part of your domain: sandboxing a tool, modeling several users against one namespace,
+testing permission behavior, building repeatable fixtures, or saving and restoring an in-memory workspace. If you need
+Effect's standard `FileSystem` service, use [`@effect-vfs/memory`](https://www.npmjs.com/package/@effect-vfs/memory),
+which adapts this package to that interface.
+
+The package implements a documented subset of POSIX behavior. It does not claim full POSIX conformance. See the
+[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.docs/context/implemented-profile.md)
+for the exact permission, path, timestamp, quota, and atomicity rules.
+
+## Install
+
+```sh
+npm install @effect-vfs/core effect@4.0.0-rc.112
+```
+
+Version `0.1.0` targets the exact peer version `effect@4.0.0-rc.112`.
+
+## The mental model
+
+The API has three levels:
+
+- A `Volume` owns one isolated namespace and its file contents.
+- A `Caller` accesses that volume with its own identity, umask, and current directory.
+- File and directory handles are scoped capabilities. Effect closes them when their scope ends.
+
+Callers created from the same volume see the same files. A new volume starts with independent state. This separation
+lets you model access by several users without reaching for process globals or the host filesystem.
+
+## Create an isolated workspace
+
+This example creates a bounded workspace, gives an unprivileged caller access to one directory, and uses a scoped file
+handle to read the result. It demonstrates the main benefit of the core API: storage, credentials, limits, and resource
+lifetime are explicit values that can be composed in one Effect program.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import { Effect } from "effect"
+
+const utf8 = new TextEncoder()
+
+const program = Effect.scoped(Effect.gen(function*() {
+  const volume = yield* Vfs.make({
+    maxEntries: 100,
+    maxBytes: 1_000_000,
+    maxFileBytes: 100_000
+  })
+
+  const admin = yield* volume.caller()
+  yield* admin.mkdir("/workspace", { mode: 0o770 })
+  yield* admin.chown("/workspace", { uid: 1000, gid: 1000 })
+
+  const developer = yield* volume.caller({
+    identity: { uid: 1000, gid: 1000, groups: [], privileged: false },
+    umask: 0o027
+  })
+
+  yield* developer.writeFile(
+    "/workspace/config.json",
+    utf8.encode(JSON.stringify({ feature: "preview" })),
+    { access: "write", create: "exclusive", mode: 0o666 }
+  )
+
+  const file = yield* developer.open("/workspace/config.json", { access: "read" })
+  const contents = yield* file.read(100_000)
+  const metadata = yield* file.stat
+
+  return {
+    config: JSON.parse(new TextDecoder().decode(contents)),
+    mode: metadata.mode.toString(8)
+  }
+}))
+
+const result = await Effect.runPromise(program)
+console.log(result) // { config: { feature: "preview" }, mode: "640" }
+```
+
+The root caller is privileged by default. Privilege is explicit: setting `uid` to `0` does not grant it. New root
+callers default to umask `0o022`; the developer's `0o027` mask turns the requested file mode `0o666` into `0o640`.
+
+The root package exports `VirtualFileSystem` as a namespace. The equivalent direct module import is
+`import * as Vfs from "@effect-vfs/core/VirtualFileSystem"`.
+
+## Preserve path bytes exactly
+
+JavaScript strings cannot represent every filename allowed by a byte-oriented filesystem. `BytePath` keeps arbitrary
+non-NUL path bytes intact. This matters when reproducing archives, protocol fixtures, or Unix directory trees that
+contain names which are not valid UTF-8.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import { Effect } from "effect"
+
+const program = Effect.gen(function*() {
+  const volume = yield* Vfs.make()
+  const fs = yield* volume.caller()
+
+  // Absolute path whose final component is the single byte 0xff.
+  const opaquePath = yield* Vfs.pathFromBytes(new Uint8Array([0x2f, 0xff]))
+  yield* fs.writeFile(opaquePath, new Uint8Array([1, 2, 3]), {
+    access: "write",
+    create: "exclusive"
+  })
+
+  const names = yield* fs.readDirectoryBytes("/")
+  const roundTrip = yield* Vfs.pathToBytes(opaquePath)
+  return { names: names.map((name) => Array.from(name)), roundTrip: Array.from(roundTrip) }
+})
+
+console.log(await Effect.runPromise(program))
+// { names: [[255]], roundTrip: [47, 255] }
+```
+
+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.
+
+## Build fixtures and restore snapshots
+
+Fixtures make tests deterministic without a setup sequence. Snapshots let you capture that prepared state, serialize
+it, and create independent workspaces from the same image. This is useful for test isolation, preview environments, and
+resettable sandboxes.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import { Effect } from "effect"
+
+const decodeLimits = {
+  maxEncodedBytes: 1_000_000,
+  maxRecords: 1_000,
+  maxEntries: 1_000,
+  maxDecodedBytes: 1_000_000
+}
+
+const program = Effect.gen(function*() {
+  const template = yield* Vfs.fromFixture({
+    entries: [
+      { kind: "directory", path: "/project" },
+      {
+        kind: "file",
+        path: "/project/settings.json",
+        bytes: new TextEncoder().encode("{\"theme\":\"dark\"}")
+      }
+    ]
+  })
+
+  const encoded = yield* Vfs.encodeSnapshot(yield* template.snapshot)
+  const snapshot = yield* Vfs.decodeSnapshot(encoded, decodeLimits)
+  const workspaceA = yield* Vfs.fromSnapshot(snapshot)
+  const workspaceB = yield* Vfs.fromSnapshot(snapshot)
+  const a = yield* workspaceA.caller()
+  const b = yield* workspaceB.caller()
+
+  yield* a.writeFile("/project/settings.json", new TextEncoder().encode("{\"theme\":\"light\"}"), {
+    access: "write",
+    truncate: true
+  })
+
+  return new TextDecoder().decode(yield* b.readFile("/project/settings.json"))
+})
+
+console.log(await Effect.runPromise(program)) // {"theme":"dark"}
+```
+
+Fixture paths must be absolute and unique, and parent directories must be listed explicitly. Fixtures can also contain
+symbolic links, metadata, and forward hard links.
+
+Snapshot decoding requires explicit work limits because encoded bytes may come from an untrusted source. A snapshot
+contains the reachable namespace and metadata. It excludes callers, open handles, cursor positions, watch
+subscriptions, and unlinked content. Each restored volume is independent.
+
+## Use scoped handles for incremental I/O
+
+Whole-file operations are convenient, but handles give each open file an independent `bigint` cursor and support
+incremental reads, positional I/O, seeking, and truncation. `Effect.scoped` guarantees cleanup on success, failure, or
+interruption.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import { Effect } from "effect"
+
+const program = Effect.scoped(Effect.gen(function*() {
+  const fs = yield* (yield* Vfs.make()).caller()
+  yield* fs.writeFile("/events.log", new TextEncoder().encode("one\ntwo\n"), {
+    access: "write",
+    create: "exclusive"
+  })
+
+  const file = yield* fs.open("/events.log", { access: "read" })
+  const first = yield* file.read(4) // Advances this handle's cursor.
+  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))
+}))
+
+console.log(await Effect.runPromise(program)) // ["one\n", "two\n", "one"]
+```
+
+Handles also expose an explicit `close` effect when early release matters. Calling explicit close twice fails, while
+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.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import { Effect } from "effect"
+
+const program = Effect.gen(function*() {
+  const fs = yield* (yield* Vfs.make()).caller()
+
+  return yield* fs.readFile("/optional.json").pipe(
+    Effect.catchTag("FsError", (error) =>
+      error.code === "NotFound"
+        ? Effect.succeed(new TextEncoder().encode("{}"))
+        : Effect.fail(error))
+  )
+})
+
+const bytes = await Effect.runPromise(program)
+console.log(new TextDecoder().decode(bytes)) // {}
+```
+
+## Provide a caller as an Effect service
+
+`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.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import { Effect } from "effect"
+
+const loadConfig = Effect.gen(function*() {
+  const fs = yield* Vfs.CurrentFileSystem
+  return yield* fs.readFile("/app/config.json")
+})
+
+const program = Effect.gen(function*() {
+  const fs = yield* (yield* Vfs.make()).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))
+})
+
+const bytes = await Effect.runPromise(program)
+console.log(new TextDecoder().decode(bytes)) // {}
+```
+
+## When to use core or memory
+
+Choose `@effect-vfs/core` when you need direct access to volumes, callers, credentials, byte paths, quotas, watches,
+fixtures, or snapshots. Choose `@effect-vfs/memory` when existing code expects Effect's `FileSystem` service and you
+want an in-memory implementation. The memory adapter is built on this core, so you can create a core volume and bind
+the adapter to it when you need both interfaces.
+
+## Compatibility and behavioral limits
+
+This package is experimental. Its public API may change between minor releases while Effect v4 remains a release
+candidate.
+
+- Components are limited to 255 bytes. Symbolic-link traversal is limited to 40 links.
+- Omitted logical quotas are unbounded by configuration, apart from fixed file and component bounds.
+- Absolute paths ignore a supplied directory base. Relative paths can use a live, same-volume directory handle.
+- Operations coordinate through one permit per volume. Interruption while waiting makes no change; interruption after
+  a commit does not roll it back.
+- Watch streams contain byte paths and report future committed creates, updates, and removals without replay.
+- `sync` checks handle liveness. An in-memory volume provides no host or crash durability.
+
+For the complete contract, read the
+[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.docs/context/implemented-profile.md).

package/dist/Snapshot.d.ts

@@ -0,0 +1,65 @@
+import * as Schema from "effect/Schema";
+/**
+ * Type identifier for opaque filesystem snapshots.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export declare const SnapshotTypeId: unique symbol;
+/**
+ * Type identifier for opaque filesystem snapshots.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export type SnapshotTypeId = typeof SnapshotTypeId;
+/**
+ * An immutable, opaque capture of a virtual filesystem volume.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Snapshot {
+    readonly [SnapshotTypeId]: SnapshotTypeId;
+}
+declare const ImageError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ImageError";
+} & Readonly<A>;
+/**
+ * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class ImageError extends ImageError_base<{
+    /** Machine-readable encoding, version, structure, or limit failure. */
+    readonly code: "InvalidEncoding" | "UnsupportedVersion" | "InvalidStructure" | "LimitExceeded";
+    /** Input area or configured limit associated with the failure, when available. */
+    readonly field?: string;
+}> {
+}
+/**
+ * Schema for the mandatory resource limits applied while decoding a snapshot.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const DecodeLimits: Schema.Struct<{
+    /** Maximum accepted encoded input length in bytes. */
+    readonly maxEncodedBytes: Schema.Finite;
+    /** Maximum number of stored metadata and content records. */
+    readonly maxRecords: Schema.Finite;
+    /** Maximum number of namespace entries. */
+    readonly maxEntries: Schema.Finite;
+    /** Maximum combined decoded byte content. */
+    readonly maxDecodedBytes: Schema.Finite;
+}>;
+/**
+ * Resource limits applied while decoding a snapshot.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type DecodeLimits = typeof DecodeLimits.Type;
+export {};
+//# sourceMappingURL=Snapshot.d.ts.map

package/dist/Snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAQvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,eAAsC,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;;;;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAA;IAC9F,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,2CAA2C;;IAE3C,6CAA6C;;EAE7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}

package/dist/Snapshot.js

@@ -0,0 +1,43 @@
+/**
+ * Opaque virtual filesystem snapshots and their decoding limits.
+ *
+ * Snapshots contain a volume's reachable namespace and metadata, but exclude
+ * callers, open handles, watch subscriptions, and unlinked content. Use the
+ * encoding, decoding, and restoration functions in `VirtualFileSystem`.
+ *
+ * @since 0.1.0
+ */
+import * as Data from "effect/Data";
+import * as Schema from "effect/Schema";
+const Natural = Schema.Finite.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+/**
+ * Type identifier for opaque filesystem snapshots.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export const SnapshotTypeId = Symbol("@effect-vfs/core/Snapshot");
+/**
+ * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class ImageError extends Data.TaggedError("ImageError") {
+}
+/**
+ * Schema for the mandatory resource limits applied while decoding a snapshot.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const DecodeLimits = Schema.Struct({
+    /** Maximum accepted encoded input length in bytes. */
+    maxEncodedBytes: Natural,
+    /** Maximum number of stored metadata and content records. */
+    maxRecords: Natural,
+    /** Maximum number of namespace entries. */
+    maxEntries: Natural,
+    /** Maximum combined decoded byte content. */
+    maxDecodedBytes: Natural
+});