@effect-vfs/core 0.2.0 → 0.3.1

package/dist/BytePath.d.ts

@@ -1,13 +1,59 @@
+/**
+ * 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 type * as Equal from "effect/Equal";
+import type { Pipeable } from "effect/Pipeable";
 import * as Schema from "effect/Schema";
-export declare const BytePathId: unique symbol;
+/**
+ * Type identifier for opaque byte-preserving filesystem paths.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export declare const BytePathId: "@effect-vfs/core/BytePath";
+/**
+ * Type identifier for opaque byte-preserving filesystem paths.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export type BytePathId = typeof BytePathId;
 /**
  * An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.
  *
+ * @example
+ * ```ts
+ * 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"
+ *   })
+ *
+ *   // `readDirectory` fails `UnrepresentableName` here; the byte variant keeps it.
+ *   return yield* caller.readDirectoryBytes("/")
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ Uint8Array(2) [ 255, 254 ] ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
-export interface BytePath {
-    readonly [BytePathId]: true;
+export interface BytePath extends Equal.Equal, Pipeable {
+    readonly [BytePathId]: BytePathId;
 }
 /**
  * Schema for an opaque byte-preserving filesystem path.
@@ -16,6 +62,4 @@ export interface BytePath {
  * @since 0.1.0
  */
 export declare const BytePath: Schema.declare<BytePath, BytePath>;
-export declare const make: (bytes: Uint8Array) => BytePath;
-export declare const getBytes: (path: BytePath) => Uint8Array | undefined;
 //# 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,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,eAAO,MAAM,UAAU,eAAsC,CAAA;AAI7D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,IAAI,CAAA;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAEpB,CAAA;AAED,eAAO,MAAM,IAAI,UAAW,UAAU,KAAG,QAIxC,CAAA;AAED,eAAO,MAAM,QAAQ,SAAU,QAAQ,KAAG,UAAU,GAAG,SAAgC,CAAA"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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"}

package/dist/BytePath.js

@@ -1,16 +1,16 @@
 import * as Schema from "effect/Schema";
-export const BytePathId = Symbol("@effect-vfs/core/BytePath");
-const bytePaths = new WeakMap();
+import * as Internal from "./internal/bytePath.js";
+/**
+ * Type identifier for opaque byte-preserving filesystem paths.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export const BytePathId = Internal.BytePathId;
 /**
  * Schema for an opaque byte-preserving filesystem path.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const BytePath = Schema.declare((value) => typeof value === "object" && value !== null && bytePaths.has(value));
-export const make = (bytes) => {
-    const path = Object.freeze({ [BytePathId]: true });
-    bytePaths.set(path, bytes);
-    return path;
-};
-export const getBytes = (path) => bytePaths.get(path);
+export const BytePath = Schema.declare(Internal.isBytePath);

package/dist/Snapshot.d.ts

@@ -2,14 +2,14 @@ import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
-export declare const SnapshotTypeId: unique symbol;
+export declare const SnapshotTypeId: "@effect-vfs/core/Snapshot";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export type SnapshotTypeId = typeof SnapshotTypeId;
@@ -28,6 +28,35 @@ declare const ImageError_base: new <A extends Record<string, any> = {}>(args: im
 /**
  * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Decoding is a trust boundary. `code` says what went wrong and `field` says
+ * // which input or limit it was, so a caller can decline just the bad payload.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   return yield* Vfs.decodeSnapshot(bytes, {
+ *     maxEncodedBytes: ByteSize.bytes(16),
+ *     maxRecords: 10_000,
+ *     maxEntries: 10_000,
+ *     maxDecodedBytes: ByteSize.megabytes(16)
+ *   }).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("ImageError", (error) =>
+ *       error.code === "LimitExceeded"
+ *         ? Effect.succeed(`declined at ${error.field}`)
+ *         : Effect.fail(error))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // declined at encodedBytes
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -41,6 +70,33 @@ export declare class ImageError extends ImageError_base<{
 /**
  * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * const limits: Vfs.DecodeLimits = {
+ *   maxEncodedBytes: ByteSize.megabytes(4),
+ *   maxRecords: 10_000,
+ *   maxEntries: 10_000,
+ *   maxDecodedBytes: ByteSize.megabytes(16)
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   yield* Vfs.decodeSnapshot(bytes, limits)
+ *
+ *   return "accepted"
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // accepted
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -48,9 +104,9 @@ export declare const DecodeLimits: Schema.Struct<{
     /** Maximum accepted encoded input length in bytes. */
     readonly maxEncodedBytes: Schema.ByteSize;
     /** Maximum number of stored metadata and content records. */
-    readonly maxRecords: Schema.Finite;
+    readonly maxRecords: Schema.Natural;
     /** Maximum number of namespace entries. */
-    readonly maxEntries: Schema.Finite;
+    readonly maxEntries: Schema.Natural;
     /** Maximum combined decoded byte content. */
     readonly maxDecodedBytes: Schema.ByteSize;
 }>;

package/dist/Snapshot.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAG,2BAAoC,CAAA;AAElE;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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

@@ -9,17 +9,45 @@
  */
 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
+ * @category type IDs
  * @since 0.1.0
  */
-export const SnapshotTypeId = Symbol("@effect-vfs/core/Snapshot");
+export const SnapshotTypeId = "@effect-vfs/core/Snapshot";
 /**
  * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Decoding is a trust boundary. `code` says what went wrong and `field` says
+ * // which input or limit it was, so a caller can decline just the bad payload.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   return yield* Vfs.decodeSnapshot(bytes, {
+ *     maxEncodedBytes: ByteSize.bytes(16),
+ *     maxRecords: 10_000,
+ *     maxEntries: 10_000,
+ *     maxDecodedBytes: ByteSize.megabytes(16)
+ *   }).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("ImageError", (error) =>
+ *       error.code === "LimitExceeded"
+ *         ? Effect.succeed(`declined at ${error.field}`)
+ *         : Effect.fail(error))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // declined at encodedBytes
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -28,6 +56,33 @@ export class ImageError extends Data.TaggedError("ImageError") {
 /**
  * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * const limits: Vfs.DecodeLimits = {
+ *   maxEncodedBytes: ByteSize.megabytes(4),
+ *   maxRecords: 10_000,
+ *   maxEntries: 10_000,
+ *   maxDecodedBytes: ByteSize.megabytes(16)
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   yield* Vfs.decodeSnapshot(bytes, limits)
+ *
+ *   return "accepted"
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // accepted
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -35,9 +90,9 @@ export const DecodeLimits = Schema.Struct({
     /** Maximum accepted encoded input length in bytes. */
     maxEncodedBytes: Schema.ByteSize,
     /** Maximum number of stored metadata and content records. */
-    maxRecords: Natural,
+    maxRecords: Schema.Natural,
     /** Maximum number of namespace entries. */
-    maxEntries: Natural,
+    maxEntries: Schema.Natural,
     /** Maximum combined decoded byte content. */
     maxDecodedBytes: Schema.ByteSize
 });

package/dist/SnapshotDelta.d.ts

@@ -6,33 +6,105 @@
 import * as ByteSize from "effect/ByteSize";
 import * as Schema from "effect/Schema";
 import { BytePath } from "./BytePath.js";
-/** Type identifier for opaque snapshot deltas. */
-export declare const SnapshotDeltaTypeId: unique symbol;
-/** Type identifier for opaque snapshot deltas. */
+/**
+ * Type identifier for opaque snapshot deltas.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export declare const SnapshotDeltaTypeId: "@effect-vfs/core/SnapshotDelta";
+/**
+ * Type identifier for opaque snapshot deltas.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
 export type SnapshotDeltaTypeId = typeof SnapshotDeltaTypeId;
-/** An immutable, opaque description of the exact difference between two snapshots. */
+/**
+ * An immutable, opaque description of the exact difference between two snapshots.
+ *
+ * @category models
+ * @since 0.1.0
+ */
 export interface SnapshotDelta {
     readonly [SnapshotDeltaTypeId]: SnapshotDeltaTypeId;
 }
-/** @internal */
-export declare const makeSnapshotDelta: (value: object) => SnapshotDelta;
-/** @internal */
-export declare const snapshotDeltaValue: (delta: SnapshotDelta) => object | undefined;
-/** Schema for an already validated opaque snapshot delta. */
+/**
+ * Schema for an already validated opaque snapshot delta.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
 export declare const SnapshotDelta: Schema.declare<SnapshotDelta, SnapshotDelta>;
-/** Schema for filesystem entry kinds reported by snapshot inspection. */
+/**
+ * Schema for filesystem entry kinds reported by snapshot inspection.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
 export declare const SnapshotNodeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-/** A filesystem entry kind reported by snapshot inspection. */
+/**
+ * A filesystem entry kind reported by snapshot inspection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
 export type SnapshotNodeKind = typeof SnapshotNodeKind.Type;
-/** Schema for semantic fields that can differ between snapshots. */
+/**
+ * Schema for semantic fields that can differ between snapshots.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
 export declare const SnapshotDifference: Schema.Literals<readonly ["kind", "content", "target", "hardLinks", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>;
-/** A semantic field that differs between two snapshots. */
+/**
+ * A semantic field that differs between two snapshots.
+ *
+ * @category models
+ * @since 0.1.0
+ */
 export type SnapshotDifference = typeof SnapshotDifference.Type;
 /**
  * Schema for a path-oriented difference between two snapshots.
  *
  * Independent snapshots do not preserve shared lineage, so moves are reported
  * as a removal and an addition rather than an inferred rename.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([2, 3]), { access: "write", truncate: true })
+ *   yield* caller.chmod("/f", 0o600)
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *   const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *
+ *   // `Updated` carries which fields moved; `Added` and `Removed` carry a kind.
+ *   const change = changes[0]!
+ *
+ *   return change._tag === "Updated" ? change.differences : change.kind
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'content', 'mode' ]
+ * ```
+ *
+ * @category schemas
+ * @since 0.1.0
  */
 export declare const SnapshotChange: Schema.Union<readonly [Schema.TaggedStruct<"Added", {
     readonly path: Schema.declare<BytePath, BytePath>;
@@ -46,19 +118,91 @@ export declare const SnapshotChange: Schema.Union<readonly [Schema.TaggedStruct<
     readonly afterKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
     readonly differences: Schema.$Array<Schema.Literals<readonly ["kind", "content", "target", "hardLinks", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
 }>]>;
-/** A path-oriented semantic difference between two snapshots. */
+/**
+ * A path-oriented semantic difference between two snapshots.
+ *
+ * @category models
+ * @since 0.1.0
+ */
 export type SnapshotChange = typeof SnapshotChange.Type;
-/** Schema for snapshot-delta inspection options. */
+/**
+ * Schema for snapshot-delta inspection options.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *
+ *   // Timestamps are excluded by default, since they change on every write.
+ *   const plain = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *   const timed = yield* Vfs.inspectSnapshotDelta(base, delta, { includeTimestamps: true })
+ *
+ *   return [plain.length, timed.length]
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 1, 2 ]
+ * ```
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
 export declare const SnapshotChangesOptions: Schema.Struct<{
     /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
     readonly includeTimestamps: Schema.optionalKey<Schema.Boolean>;
 }>;
-/** Filtering options for snapshot-delta inspection. */
+/**
+ * Filtering options for snapshot-delta inspection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
 export type SnapshotChangesOptions = typeof SnapshotChangesOptions.Type;
 declare const SnapshotDeltaError_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: "SnapshotDeltaError";
 } & Readonly<A>;
-/** A valid snapshot delta was inspected or applied against a valid but semantically different base. */
+/**
+ * A valid snapshot delta was inspected or applied against a valid but semantically different base.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   // Omitting limits uses `default`; `constrained` suits memory-sensitive hosts.
+ *   const tight = { ...Vfs.SnapshotDeltaLimits.constrained, maxOutputRecords: 0 }
+ *
+ *   return yield* Vfs.diffSnapshots(base, yield* volume.snapshot, tight).pipe(
+ *     Effect.as("diffed"),
+ *     Effect.catchTag("ImageError", (error) => Effect.succeed(`${error.code} at ${error.field}`))
+ *   )
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // LimitExceeded at outputRecords
+ * ```
+ *
+ * @category errors
+ * @since 0.1.0
+ */
 export declare class SnapshotDeltaError extends SnapshotDeltaError_base<{
     readonly code: "BaseMismatch";
 }> {
@@ -66,36 +210,69 @@ export declare class SnapshotDeltaError extends SnapshotDeltaError_base<{
 declare const SnapshotDeltaLimitsSchema: Schema.Struct<{
     readonly maxEncodedBytes: Schema.ByteSize;
     readonly maxIdentityBytes: Schema.ByteSize;
-    readonly maxDeltaRecords: Schema.Finite;
+    readonly maxDeltaRecords: Schema.Natural;
     readonly maxDecodedDeltaBytes: Schema.ByteSize;
-    readonly maxBaseRecords: Schema.Finite;
-    readonly maxTargetRecords: Schema.Finite;
-    readonly maxEntries: Schema.Finite;
-    readonly maxOutputRecords: Schema.Finite;
+    readonly maxBaseRecords: Schema.Natural;
+    readonly maxTargetRecords: Schema.Natural;
+    readonly maxEntries: Schema.Natural;
+    readonly maxOutputRecords: Schema.Natural;
     readonly maxOutputBytes: Schema.ByteSize;
-    readonly maxInheritedRecords: Schema.Finite;
+    readonly maxInheritedRecords: Schema.Natural;
 }>;
-/** Resource limits shared by delta creation, inspection, encoding, decoding, and application. */
+/**
+ * Resource limits shared by delta creation, inspection, encoding, decoding, and application.
+ *
+ * @category models
+ * @since 0.1.0
+ */
 export type SnapshotDeltaLimits = typeof SnapshotDeltaLimitsSchema.Type;
-/** Constructs and freezes a complete snapshot-delta resource policy. @internal */
+/**
+ * Constructs and freezes a complete snapshot-delta resource policy.
+ *
+ * @internal
+ */
 export declare const makeSnapshotDeltaLimits: (limits: SnapshotDeltaLimits) => SnapshotDeltaLimits;
 /**
  * Schema for a complete snapshot-delta resource policy, with frozen presets.
  *
  * The constrained preset is intended for memory-sensitive environments. The
  * default preset permits larger snapshots and payloads while remaining finite.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* (yield* volume.caller()).mkdir("/work")
+ *
+ *   // Omitting limits uses `default`; pass `constrained` where memory is tight.
+ *   return yield* Vfs.diffSnapshots(
+ *     base,
+ *     yield* volume.snapshot,
+ *     Vfs.SnapshotDeltaLimits.constrained
+ *   )
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ * ```
+ *
+ * @category schemas
+ * @since 0.1.0
  */
 export declare const SnapshotDeltaLimits: Schema.Struct<{
     readonly maxEncodedBytes: Schema.ByteSize;
     readonly maxIdentityBytes: Schema.ByteSize;
-    readonly maxDeltaRecords: Schema.Finite;
+    readonly maxDeltaRecords: Schema.Natural;
     readonly maxDecodedDeltaBytes: Schema.ByteSize;
-    readonly maxBaseRecords: Schema.Finite;
-    readonly maxTargetRecords: Schema.Finite;
-    readonly maxEntries: Schema.Finite;
-    readonly maxOutputRecords: Schema.Finite;
+    readonly maxBaseRecords: Schema.Natural;
+    readonly maxTargetRecords: Schema.Natural;
+    readonly maxEntries: Schema.Natural;
+    readonly maxOutputRecords: Schema.Natural;
     readonly maxOutputBytes: Schema.ByteSize;
-    readonly maxInheritedRecords: Schema.Finite;
+    readonly maxInheritedRecords: Schema.Natural;
 }> & {
     constrained: {
         readonly maxEncodedBytes: ByteSize.ByteSize;

package/dist/SnapshotDelta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SnapshotDelta.d.ts","sourceRoot":"","sources":["../src/SnapshotDelta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAQxC,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,eAA2C,CAAA;AAC3E,kDAAkD;AAClD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA;AAE5D,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACpD;AAID,gBAAgB;AAChB,eAAO,MAAM,iBAAiB,UAAW,MAAM,KAAG,aAIjD,CAAA;AAED,gBAAgB;AAChB,eAAO,MAAM,kBAAkB,UAAW,aAAa,KAAG,MAAM,GAAG,SAAsC,CAAA;AAEzG,6DAA6D;AAC7D,eAAO,MAAM,aAAa,8CAEzB,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,4DAAoD,CAAA;AACjF,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,4IAY7B,CAAA;AACF,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AACF,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,oDAAoD;AACpD,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AACF,uDAAuD;AACvD,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE,uGAAuG;AACvG,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B,CAAC;CAAG;AAEL,QAAA,MAAM,yBAAyB;;;;;;;;;;;EAW7B,CAAA;AACF,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAEvE,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA2B9B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG9B,CAAA"}
+{"version":3,"file":"SnapshotDelta.d.ts","sourceRoot":"","sources":["../src/SnapshotDelta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,gCAA+D,CAAA;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACpD;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,8CAA0D,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,4DAAoD,CAAA;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,4IAY7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B,CAAC;CAAG;AAEL,QAAA,MAAM,yBAAyB;;;;;;;;;;;EAW7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAEvE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA4B9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG9B,CAAA"}