@effect-vfs/core 0.3.0 → 0.4.0

package/dist/Snapshot.js

@@ -12,13 +12,43 @@ import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 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 * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * 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.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // declined at encodedBytes
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -27,6 +57,34 @@ 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 * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * 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.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // accepted
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */

package/dist/SnapshotDelta.d.ts

@@ -9,14 +9,14 @@ import { BytePath } from "./BytePath.js";
 /**
  * Type identifier for opaque snapshot deltas.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export declare const SnapshotDeltaTypeId: "@effect-vfs/core/SnapshotDelta";
 /**
  * Type identifier for opaque snapshot deltas.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export type SnapshotDeltaTypeId = typeof SnapshotDeltaTypeId;
@@ -70,6 +70,39 @@ export type SnapshotDifference = typeof SnapshotDifference.Type;
  * 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
  */
@@ -95,6 +128,32 @@ export type SnapshotChange = typeof SnapshotChange.Type;
 /**
  * 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
  */
@@ -115,6 +174,32 @@ declare const SnapshotDeltaError_base: new <A extends Record<string, any> = {}>(
 /**
  * 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
  */
@@ -141,7 +226,11 @@ declare const SnapshotDeltaLimitsSchema: Schema.Struct<{
  * @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.
@@ -149,6 +238,27 @@ export declare const makeSnapshotDeltaLimits: (limits: SnapshotDeltaLimits) => S
  * 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
  */

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;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;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE;;;;;GAKG;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,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA2B9B;;;;;;;;GAQG;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"}

package/dist/SnapshotDelta.js

@@ -11,7 +11,7 @@ import * as Internal from "./internal/snapshotDeltaModel.js";
 /**
  * Type identifier for opaque snapshot deltas.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export const SnapshotDeltaTypeId = Internal.SnapshotDeltaTypeId;
@@ -55,6 +55,39 @@ const SnapshotDifferences = Schema.Array(SnapshotDifference).check(Schema.isMinL
  * 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
  */
@@ -71,6 +104,32 @@ export const SnapshotChange = Schema.Union([
 /**
  * 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
  */
@@ -81,6 +140,32 @@ export const SnapshotChangesOptions = Schema.Struct({
 /**
  * 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
  */
@@ -98,7 +183,11 @@ const SnapshotDeltaLimitsSchema = Schema.Struct({
     maxOutputBytes: Schema.ByteSize,
     maxInheritedRecords: Schema.Natural
 });
-/** Constructs and freezes a complete snapshot-delta resource policy. @internal */
+/**
+ * Constructs and freezes a complete snapshot-delta resource policy.
+ *
+ * @internal
+ */
 export const makeSnapshotDeltaLimits = (limits) => Object.freeze({ ...limits });
 const constrained = makeSnapshotDeltaLimits({
     maxEncodedBytes: ByteSize.mebibytes(2),
@@ -130,6 +219,27 @@ const defaultLimits = makeSnapshotDeltaLimits({
  * 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
  */