@effect-vfs/core 0.2.0 → 0.3.1

package/dist/SnapshotDelta.js

@@ -7,23 +7,34 @@ import * as ByteSize from "effect/ByteSize";
 import * as Data from "effect/Data";
 import * as Schema from "effect/Schema";
 import { BytePath } from "./BytePath.js";
-const Natural = Schema.Finite.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
-/** Type identifier for opaque snapshot deltas. */
-export const SnapshotDeltaTypeId = Symbol("@effect-vfs/core/SnapshotDelta");
-const snapshotDeltas = new WeakMap();
-/** @internal */
-export const makeSnapshotDelta = (value) => {
-    const delta = Object.freeze({ [SnapshotDeltaTypeId]: SnapshotDeltaTypeId });
-    snapshotDeltas.set(delta, value);
-    return delta;
-};
-/** @internal */
-export const snapshotDeltaValue = (delta) => snapshotDeltas.get(delta);
-/** Schema for an already validated opaque snapshot delta. */
-export const SnapshotDelta = Schema.declare((value) => typeof value === "object" && value !== null && snapshotDeltas.has(value));
-/** Schema for filesystem entry kinds reported by snapshot inspection. */
+import * as Internal from "./internal/snapshotDeltaModel.js";
+/**
+ * Type identifier for opaque snapshot deltas.
+ *
+ * @category type IDs
+ * @since 0.1.0
+ */
+export const SnapshotDeltaTypeId = Internal.SnapshotDeltaTypeId;
+/**
+ * Schema for an already validated opaque snapshot delta.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const SnapshotDelta = Schema.declare(Internal.isSnapshotDelta);
+/**
+ * Schema for filesystem entry kinds reported by snapshot inspection.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
 export const SnapshotNodeKind = Schema.Literals(["directory", "file", "symlink"]);
-/** 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 const SnapshotDifference = Schema.Literals([
     "kind",
     "content",
@@ -43,6 +54,42 @@ 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
  */
 export const SnapshotChange = Schema.Union([
     Schema.TaggedStruct("Added", { path: BytePath, kind: SnapshotNodeKind }),
@@ -54,27 +101,93 @@ export const SnapshotChange = Schema.Union([
         differences: SnapshotDifferences
     })
 ]);
-/** 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 const SnapshotChangesOptions = Schema.Struct({
     /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
     includeTimestamps: Schema.optionalKey(Schema.Boolean)
 });
-/** 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 class SnapshotDeltaError extends Data.TaggedError("SnapshotDeltaError") {
 }
 const SnapshotDeltaLimitsSchema = Schema.Struct({
     maxEncodedBytes: Schema.ByteSize,
     maxIdentityBytes: Schema.ByteSize,
-    maxDeltaRecords: Natural,
+    maxDeltaRecords: Schema.Natural,
     maxDecodedDeltaBytes: Schema.ByteSize,
-    maxBaseRecords: Natural,
-    maxTargetRecords: Natural,
-    maxEntries: Natural,
-    maxOutputRecords: Natural,
+    maxBaseRecords: Schema.Natural,
+    maxTargetRecords: Schema.Natural,
+    maxEntries: Schema.Natural,
+    maxOutputRecords: Schema.Natural,
     maxOutputBytes: Schema.ByteSize,
-    maxInheritedRecords: Natural
+    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),
@@ -105,6 +218,30 @@ 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
  */
 export const SnapshotDeltaLimits = Object.assign(SnapshotDeltaLimitsSchema, {
     constrained,