@opfs-vfs/effect 0.2.0

package/dist/volume.d.ts

@@ -0,0 +1,52 @@
+import { Context, Effect, Layer, Scope } from 'effect';
+import { OpfsVfs, type LocalPersistenceState, type OpfsVfsOptions, type VolumePeek } from '@opfs-vfs/opfs-vfs';
+import type { OpenOpfsVfsWorkerOptions } from '@opfs-vfs/opfs-vfs/worker';
+import type { OpfsVfsWorkerClient } from '@opfs-vfs/opfs-vfs/worker-client';
+import type { ConfiguredVfsPlugin, VfsPluginRequest } from '@opfs-vfs/opfs-vfs/plugins';
+import { EncryptionError, SubscriptionError, VolumeError, type MountError, type RemoteErrorDetails } from './errors.js';
+export interface DirectMountOptions extends Omit<OpfsVfsOptions, 'plugins'> {
+    readonly fileName: string;
+    readonly plugins?: () => readonly ConfiguredVfsPlugin[];
+}
+export interface WorkerMountOptions extends Omit<OpenOpfsVfsWorkerOptions, 'signal' | 'plugins'> {
+    readonly fileName: string;
+    readonly plugins?: readonly VfsPluginRequest[] | (() => readonly VfsPluginRequest[]);
+}
+export interface PersistenceSnapshot {
+    /** Current backend telemetry; `clean` does not prove an earlier logical save survived, so await `sync`. */
+    readonly state: LocalPersistenceState | 'unknown';
+    readonly error: RemoteErrorDetails | null;
+}
+export interface VolumeService {
+    readonly fileName: string;
+    readonly sync: Effect.Effect<void, MountError>;
+    readonly persistence: Effect.Effect<PersistenceSnapshot, VolumeError>;
+    readonly acknowledgeOwnerChange: Effect.Effect<void, VolumeError>;
+}
+type Input<E, R> = DirectMountOptions | Effect.Effect<DirectMountOptions, E, R>;
+declare const Volume_base: Context.ServiceClass<Volume, "@opfs-vfs/effect/Volume", VolumeService>;
+export declare class Volume extends Volume_base {
+}
+/**
+ * Runs an effect, then syncs the current volume on success, preserving its result.
+ * The effect's filesystem must use this same volume. Failure or interruption can
+ * leave writes applied without this sync completing. This provides no rollback
+ * or isolation; nested wrappers each sync, and concurrent writes may also flush.
+ */
+export declare const withSync: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | MountError, R | Volume>;
+export declare const inspect: (fileName: string) => Effect.Effect<VolumePeek, VolumeError>;
+export declare function makeDirect(input: DirectMountOptions): Effect.Effect<VolumeService, MountError, Scope.Scope>;
+export declare function makeDirect<E, R>(input: Effect.Effect<DirectMountOptions, E, R>): Effect.Effect<VolumeService, MountError | E, Scope.Scope | R>;
+export declare function makeDirect<E = never, R = never>(input: Input<E, R>): Effect.Effect<VolumeService, MountError | E, Scope.Scope | R>;
+export declare function layerDirect(input: DirectMountOptions): Layer.Layer<Volume, MountError>;
+export declare function layerDirect<E, R>(input: Effect.Effect<DirectMountOptions, E, R>): Layer.Layer<Volume, MountError | E, R>;
+export declare function layerDirect<E = never, R = never>(input: Input<E, R>): Layer.Layer<Volume, MountError | E, R>;
+export declare function make<E = never, R = never>(input: WorkerMountOptions | Effect.Effect<WorkerMountOptions, E, R>): Effect.Effect<VolumeService, MountError | E, Scope.Scope | R>;
+export declare function layer<E = never, R = never>(input: WorkerMountOptions | Effect.Effect<WorkerMountOptions, E, R>): Layer.Layer<Volume, MountError | E, R>;
+export declare const unsafeBackend: (volume: VolumeService) => OpfsVfs | OpfsVfsWorkerClient;
+export declare const errorOf: (error: {
+    readonly reason?: {
+        readonly cause?: unknown;
+    };
+}) => VolumeError | EncryptionError | SubscriptionError | undefined;
+export {};

package/dist/volume.js

@@ -0,0 +1,3 @@
+import { a as e, c as t, i as n, n as r, o as i, r as a, s as o, t as s, u as c } from "./volume-BIqpe5Vt.js";
+import "./errors.js";
+export { s as Volume, r as errorOf, a as inspect, n as layer, e as layerDirect, i as make, o as makeDirect, t as unsafeBackend, c as withSync };

package/examples/direct.ts

@@ -0,0 +1,8 @@
+import { Effect } from 'effect';
+import { Volume } from '@opfs-vfs/effect';
+
+export const save = Effect.gen(function* () {
+  const volume = yield* Volume.makeDirect({ fileName: 'app.bin' });
+  yield* volume.sync;
+  return yield* volume.persistence;
+}).pipe(Effect.scoped);

package/examples/encrypted-session.ts

@@ -0,0 +1,347 @@
+import {
+  Context,
+  Effect,
+  Exit,
+  FileSystem,
+  Layer,
+  ManagedRuntime,
+  PlatformError,
+  Redacted,
+  Schema,
+  Stream,
+} from 'effect';
+import { OpfsFileSystem, Subscriptions, Volume, VolumeError, EncryptionError } from '@opfs-vfs/effect';
+import { encryptionRequest } from '@opfs-vfs/plugin-encryption/config';
+import { subscriptionsRequest } from '@opfs-vfs/plugin-subscriptions/config';
+
+export { Context, Effect, Exit, FileSystem, Layer, ManagedRuntime, PlatformError, Redacted, Schema, Stream };
+export { EncryptionError, OpfsFileSystem, Subscriptions, Volume, VolumeError };
+
+export type PluginProfile = 'plain' | 'subscriptions' | 'encrypted' | 'combined';
+export type CombinedRequestOrder = 'encryption-first' | 'subscriptions-first';
+export type Secret = Redacted.Redacted<string | Uint8Array>;
+
+const worker = () => new Worker(new URL('./encrypted-session.worker.ts', import.meta.url), { type: 'module' });
+
+const requests = (config: SessionConfig) => {
+  const encryption =
+    config.profile === 'encrypted' || config.profile === 'combined'
+      ? encryptionRequest({
+          secret: Redacted.value(config.secret),
+          ...(config.openMode === 'create-new' && config.initialPasskey
+            ? { initialPasskey: { secret: config.initialPasskey } }
+            : {}),
+        })
+      : undefined;
+  const subscriptions =
+    config.profile === 'subscriptions' || config.profile === 'combined' ? subscriptionsRequest() : undefined;
+  const order = config.order ?? 'encryption-first';
+  if (order === 'subscriptions-first') return [subscriptions, encryption].filter((item) => item !== undefined);
+  return [encryption, subscriptions].filter((item) => item !== undefined);
+};
+
+interface SessionConfigBase {
+  readonly fileName: string;
+  readonly order?: CombinedRequestOrder;
+}
+
+export type SessionConfig = SessionConfigBase &
+  (
+    | { readonly profile: 'plain' | 'subscriptions'; readonly openMode: 'create-new' | 'open-existing' }
+    | {
+        readonly profile: 'encrypted' | 'combined';
+        readonly openMode: 'create-new';
+        readonly secret: Secret;
+        readonly initialPasskey?: Uint8Array;
+      }
+    | {
+        readonly profile: 'encrypted' | 'combined';
+        readonly openMode: 'open-existing';
+        readonly secret: Secret;
+        readonly initialPasskey?: never;
+      }
+  );
+
+const encrypted = (profile: PluginProfile) => profile === 'encrypted' || profile === 'combined';
+const observed = (profile: PluginProfile) => profile === 'subscriptions' || profile === 'combined';
+
+const missingVolume = (fileName: string) =>
+  new VolumeError({
+    kind: 'filesystem',
+    fileName,
+    operation: 'open-existing',
+    code: 'ENOENT',
+    outcome: 'not-applied',
+    details: { message: 'The requested existing volume does not exist', code: 'ENOENT' },
+  });
+
+const inspectionPolicyFailure = (fileName: string, code: string, message: string, kind: VolumeError['kind']) =>
+  new VolumeError({
+    kind,
+    fileName,
+    operation: 'inspect',
+    code,
+    outcome: 'not-applied',
+    details: { message, code },
+  });
+
+const volumeLayer = (config: SessionConfig) => {
+  const options = {
+    fileName: config.fileName,
+    openMode: config.openMode,
+    transport: 'dedicated' as const,
+    ...(encrypted(config.profile) ? { worker } : {}),
+    plugins: () => requests(config),
+  };
+  if (config.openMode === 'create-new') return Volume.layer(options);
+  return Layer.effect(
+    Volume.Volume,
+    Effect.gen(function* () {
+      const info = yield* Volume.inspect(config.fileName);
+      if (!info.exists) return yield* Effect.fail(missingVolume(config.fileName));
+      if (info.importing)
+        return yield* Effect.fail(
+          inspectionPolicyFailure(config.fileName, 'VOLUME_IMPORTING', 'Volume import is incomplete', 'lifecycle'),
+        );
+      if (info.compatible === false)
+        return yield* Effect.fail(
+          inspectionPolicyFailure(
+            config.fileName,
+            'VFS_INCOMPATIBLE_VOLUME',
+            'Volume metadata is incompatible with this build',
+            'unsupported',
+          ),
+        );
+      return yield* Volume.make(options);
+    }),
+  );
+};
+
+export const makeSessionLayer = (config: SessionConfig) => {
+  const volume = volumeLayer(config);
+  return observed(config.profile)
+    ? Layer.merge(OpfsFileSystem.layer, Subscriptions.layer).pipe(Layer.provideMerge(volume))
+    : OpfsFileSystem.layer.pipe(Layer.provideMerge(volume));
+};
+
+export const createEncryptedLayer = (
+  fileName: string,
+  secret: Secret,
+  initialPasskey?: Uint8Array,
+  order: CombinedRequestOrder = 'encryption-first',
+) =>
+  makeSessionLayer({
+    fileName,
+    profile: 'encrypted',
+    openMode: 'create-new',
+    secret,
+    order,
+    initialPasskey,
+  });
+
+export const makeSessionRuntime = (config: SessionConfig) => ManagedRuntime.make(makeSessionLayer(config));
+
+export type SessionRuntime = ReturnType<typeof makeSessionRuntime>;
+export type SessionExit<A = unknown> = Exit.Exit<A, unknown>;
+
+export const startSessionRuntime = async (runtime: SessionRuntime) => {
+  const startExit: SessionExit<void> = await runtime.runPromiseExit(Effect.void);
+  if (Exit.isSuccess(startExit)) return { _tag: 'Started' as const, runtime, startExit };
+  const disposeExit = await Effect.runPromiseExit(runtime.disposeEffect);
+  return { _tag: 'StartFailed' as const, runtime, startExit, disposeExit };
+};
+
+const credentialsFailure = (exit: SessionExit): EncryptionError | undefined => {
+  if (Exit.isSuccess(exit) || exit.cause.reasons.length !== 1) return undefined;
+  const [reason] = exit.cause.reasons;
+  if (reason?._tag !== 'Fail') return undefined;
+  const error = reason.error;
+  if (Schema.is(EncryptionError)(error) && error.reason === 'CredentialsRejected') return error;
+  if (!PlatformError.isPlatformError(error)) return undefined;
+  const wrapper = error.reason.cause;
+  if (
+    Schema.is(VolumeError)(wrapper) &&
+    wrapper.kind === 'lifecycle' &&
+    Schema.is(EncryptionError)(wrapper.cause) &&
+    wrapper.cause.reason === 'CredentialsRejected'
+  )
+    return wrapper.cause;
+  return undefined;
+};
+
+const saveOnce = (contents: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const volume = yield* Volume.Volume;
+    yield* fs.writeFileString('/session-save.txt', contents);
+    yield* volume.sync;
+    return 'saved' as const;
+  });
+
+export type SessionSaveResult =
+  | { readonly _tag: 'Saved'; readonly useExit: SessionExit<'saved'> }
+  | {
+      readonly _tag: 'Replaced';
+      readonly useExit: SessionExit<'saved'>;
+      readonly disposeExit: Exit.Exit<void, never>;
+      readonly startExit: SessionExit<void>;
+    }
+  | {
+      readonly _tag: 'ReplacementBlocked';
+      readonly useExit: SessionExit<'saved'>;
+      readonly disposeExit: Exit.Exit<void, never>;
+    }
+  | {
+      readonly _tag: 'ReplacementCancelled';
+      readonly useExit: SessionExit<'saved'>;
+      readonly disposeExit: Exit.Exit<void, never>;
+    }
+  | {
+      readonly _tag: 'ReplacementFailed';
+      readonly useExit: SessionExit<'saved'>;
+      readonly disposeExit: Exit.Exit<void, never>;
+      readonly startExit: SessionExit<void>;
+      readonly replacementDisposeExit: Exit.Exit<void, never>;
+    }
+  | { readonly _tag: 'Failed'; readonly useExit: SessionExit<'saved'> }
+  | { readonly _tag: 'Unavailable' };
+
+/**
+ * `config` must match `initial`'s fileName, profile, and plugin request order. A replacement supplies a new secret only.
+ */
+export const makeSessionController = (
+  initial: SessionRuntime,
+  config: SessionConfigBase & { readonly profile: 'encrypted' | 'combined' },
+  requestCredentials: (error: EncryptionError) => Promise<Secret | undefined>,
+) => {
+  let current: SessionRuntime | undefined = initial;
+  let accepting = true;
+  let closed = false;
+  const closeRequested = Promise.withResolvers<undefined>();
+  let serial = Promise.resolve();
+  const ordered = <A>(work: () => Promise<A>): Promise<A> => {
+    const result = serial.then(work, work);
+    serial = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  };
+
+  const save = (contents: string): Promise<SessionSaveResult> => {
+    const admitted = accepting ? current : undefined;
+    return ordered(async () => {
+      if (!admitted || !accepting || current !== admitted) return { _tag: 'Unavailable' };
+      const previous = current;
+      if (!previous) return { _tag: 'Unavailable' };
+      const useExit: SessionExit<'saved'> = await previous.runPromiseExit(saveOnce(contents));
+      if (Exit.isSuccess(useExit)) return { _tag: 'Saved', useExit };
+      const credentials = credentialsFailure(useExit);
+      if (!credentials) return { _tag: 'Failed', useExit };
+
+      accepting = false;
+      current = undefined;
+      // The use fiber has exited. Disposal runs outside that runtime and its full Exit is retained.
+      const disposeExit = await Effect.runPromiseExit(previous.disposeEffect);
+      if (Exit.isFailure(disposeExit)) return { _tag: 'ReplacementBlocked', useExit, disposeExit };
+
+      if (closed) return { _tag: 'ReplacementCancelled', useExit, disposeExit };
+
+      let secret: Secret | undefined;
+      try {
+        secret = await Promise.race([requestCredentials(credentials), closeRequested.promise]);
+      } catch {
+        return { _tag: 'ReplacementCancelled', useExit, disposeExit };
+      }
+      if (closed || !secret) return { _tag: 'ReplacementCancelled', useExit, disposeExit };
+
+      const replacement = makeSessionRuntime({ ...config, openMode: 'open-existing', secret });
+      const startExit: SessionExit<void> = await replacement.runPromiseExit(Effect.void);
+      if (Exit.isFailure(startExit)) {
+        const replacementDisposeExit = await Effect.runPromiseExit(replacement.disposeEffect);
+        return { _tag: 'ReplacementFailed', useExit, disposeExit, startExit, replacementDisposeExit };
+      }
+      current = replacement;
+      accepting = !closed;
+      return { _tag: 'Replaced', useExit, disposeExit, startExit };
+    });
+  };
+
+  const runtime = () => current;
+  const close = () => {
+    closed = true;
+    accepting = false;
+    closeRequested.resolve(undefined);
+    return ordered(async () => {
+      if (!current) return Exit.succeed(undefined);
+      const closing = current;
+      current = undefined;
+      return Effect.runPromiseExit(closing.disposeEffect);
+    });
+  };
+
+  return { save, runtime, close };
+};
+
+export const acceptReconciledSave = Effect.gen(function* () {
+  const volume = yield* Volume.Volume;
+  yield* volume.acknowledgeOwnerChange;
+  yield* volume.sync;
+});
+
+export class DocumentsFs extends Context.Service<
+  DocumentsFs,
+  { readonly fs: FileSystem.FileSystem; readonly volume: Volume.VolumeService }
+>()('app/DocumentsFs') {}
+export class CacheFs extends Context.Service<
+  CacheFs,
+  { readonly fs: FileSystem.FileSystem; readonly volume: Volume.VolumeService }
+>()('app/CacheFs') {}
+
+export const makeSharedNamedFileSystems = (fileName: string) => {
+  const volume = Volume.layer({ fileName, plugins: [subscriptionsRequest()] });
+  const services = Layer.merge(OpfsFileSystem.layer, Subscriptions.layer).pipe(Layer.provideMerge(volume));
+  const consumers = Layer.mergeAll(
+    Layer.effect(
+      DocumentsFs,
+      Effect.gen(function* () {
+        return { fs: yield* FileSystem.FileSystem, volume: yield* Volume.Volume };
+      }),
+    ),
+    Layer.effect(
+      CacheFs,
+      Effect.gen(function* () {
+        return { fs: yield* FileSystem.FileSystem, volume: yield* Volume.Volume };
+      }),
+    ),
+  );
+  return consumers.pipe(Layer.provideMerge(services));
+};
+
+export const makeDocumentsFileSystem = (fileName: string) =>
+  Layer.effect(
+    DocumentsFs,
+    Effect.gen(function* () {
+      return { fs: yield* FileSystem.FileSystem, volume: yield* Volume.Volume };
+    }),
+  ).pipe(
+    Layer.provideMerge(
+      Layer.merge(OpfsFileSystem.layer, Subscriptions.layer).pipe(
+        Layer.provideMerge(Volume.layer({ fileName, plugins: [subscriptionsRequest()] })),
+      ),
+    ),
+  );
+
+export const makeCacheFileSystem = (fileName: string) =>
+  Layer.effect(
+    CacheFs,
+    Effect.gen(function* () {
+      return { fs: yield* FileSystem.FileSystem, volume: yield* Volume.Volume };
+    }),
+  ).pipe(
+    Layer.provideMerge(
+      Layer.merge(OpfsFileSystem.layer, Subscriptions.layer).pipe(
+        Layer.provideMerge(Volume.layer({ fileName, plugins: [subscriptionsRequest()] })),
+      ),
+    ),
+  );

package/examples/encrypted-session.worker.ts

@@ -0,0 +1,5 @@
+import { encryption } from '@opfs-vfs/plugin-encryption';
+import { subscriptions } from '@opfs-vfs/plugin-subscriptions';
+import { startVfsWorker } from '@opfs-vfs/opfs-vfs/worker-runtime';
+
+startVfsWorker({ plugins: [encryption, subscriptions] });

package/examples/filesystem-save.ts

@@ -0,0 +1,30 @@
+import { Effect } from 'effect';
+import { OpfsFileSystem, Volume } from '@opfs-vfs/effect';
+import { subscriptionsRequest } from '@opfs-vfs/plugin-subscriptions/config';
+
+// fallow-ignore-next-line unused-export
+export const saveNote = (fileName = `effect-save-${crypto.randomUUID()}.bin`) =>
+  Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const volume = yield* Volume.make({
+          fileName,
+          transport: 'dedicated',
+          plugins: () => [subscriptionsRequest()],
+        });
+        const fs = OpfsFileSystem.make(volume);
+        yield* fs.writeFileString('/note.txt', 'saved through FileSystem');
+        yield* volume.sync.pipe(
+          Effect.catchTag('VolumeError', (error) => {
+            if (error.code === 'VFS_SYNC_OWNER_CHANGED') {
+              return Effect.logWarning(
+                'Save status is uncertain; reconcile the current volume before acknowledging it.',
+              ).pipe(Effect.andThen(Effect.fail(error)));
+            }
+            return Effect.fail(error);
+          }),
+        );
+        return yield* fs.readFileString('/note.txt');
+      }),
+    ),
+  );

package/examples/filesystem-stream.ts

@@ -0,0 +1,20 @@
+import { ByteSize, Effect, Stream } from 'effect';
+import { OpfsFileSystem, Volume } from '@opfs-vfs/effect';
+
+export const streamFile = (fileName = `effect-stream-${crypto.randomUUID()}.bin`) =>
+  Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const volume = yield* Volume.make({ fileName, transport: 'dedicated' });
+        const fs = OpfsFileSystem.make(volume);
+        const source = new Uint8Array(16 * 1024 * 1024 + 1);
+        source.fill(7);
+        yield* fs.writeFile('/source.bin', source);
+        const sink = fs.sink('/copy.bin', { flag: 'w' });
+        yield* Stream.run(fs.stream('/source.bin', { chunkSize: 64 * 1024 }), sink);
+        yield* volume.sync;
+        const copy = yield* fs.open('/copy.bin', { flag: 'r' });
+        return ByteSize.toBigInt((yield* copy.stat).size);
+      }),
+    ),
+  );

package/examples/reconciled-view.ts

@@ -0,0 +1,74 @@
+import { Cause, Effect, Fiber, FileSystem, Layer, Queue, Schedule, Schema, Stream } from 'effect';
+import { OpfsFileSystem, Subscriptions, SubscriptionError, Volume } from '@opfs-vfs/effect';
+import { subscriptionsRequest } from '@opfs-vfs/plugin-subscriptions/config';
+
+export { Effect, Fiber, FileSystem, Queue, Volume };
+
+export const makeLayer = (fileName: string) => {
+  const volume = Volume.layer({ fileName, plugins: [subscriptionsRequest()] });
+  return Layer.merge(
+    volume,
+    Layer.merge(Layer.provide(Subscriptions.layer, volume), Layer.provide(OpfsFileSystem.layer, volume)),
+  );
+};
+
+export interface ReconciledViewOptions {
+  readonly path: string;
+  readonly publish: (paths: ReadonlyArray<string>) => Effect.Effect<void>;
+  readonly markStale: () => Effect.Effect<void>;
+}
+
+const recoverable = new Set(['SUBSCRIPTION_INTERRUPTED', 'SUBSCRIPTION_OVERFLOW', 'SUBSCRIPTION_RESYNC_REQUIRED']);
+
+const isRecoverableCause = (cause: Cause.Cause<unknown>): boolean => {
+  const [reason] = cause.reasons;
+  return (
+    cause.reasons.length === 1 &&
+    reason?._tag === 'Fail' &&
+    Schema.is(SubscriptionError)(reason.error) &&
+    recoverable.has(reason.error.code)
+  );
+};
+
+export const keepViewCurrent = (options: ReconciledViewOptions) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const subscriptions = yield* Subscriptions.Subscriptions;
+
+    let retries = 0;
+    const attempt = Effect.gen(function* () {
+      let retired: Effect.Effect<Subscriptions.SubscriptionRetirement> | undefined;
+      const exit = yield* Effect.exit(
+        Effect.scoped(
+          Effect.gen(function* () {
+            const sub = yield* subscriptions.subscribe({
+              path: options.path,
+              scope: 'directory',
+              recursive: true,
+              content: false,
+            });
+            retired = sub.retired;
+            yield* options.publish(yield* fs.readDirectory(options.path, { recursive: true }));
+            retries = 0;
+            yield* sub.changes.pipe(
+              Stream.runForEach(() =>
+                fs.readDirectory(options.path, { recursive: true }).pipe(Effect.flatMap(options.publish)),
+              ),
+            );
+          }),
+        ).pipe(Effect.onExit((result) => (result._tag === 'Failure' ? options.markStale() : Effect.void))),
+      );
+      if (retired) yield* retired;
+      return yield* exit;
+    });
+
+    return yield* attempt.pipe(
+      Effect.catchCause((cause) => Effect.fail(cause)),
+      Effect.retry(($) =>
+        $(Schedule.spaced('250 millis')).pipe(
+          Schedule.while(({ input }) => isRecoverableCause(input) && ++retries <= 3),
+        ),
+      ),
+      Effect.catch((cause) => Effect.failCause(cause)),
+    );
+  });

package/examples/subscriptions.ts

@@ -0,0 +1,20 @@
+import { Effect, FileSystem, Layer, Stream } from 'effect';
+import { OpfsFileSystem, Subscriptions, Volume } from '@opfs-vfs/effect';
+import { subscriptionsRequest } from '@opfs-vfs/plugin-subscriptions/config';
+
+export const observeOneChange = (fileName = `effect-subscriptions-${crypto.randomUUID()}.bin`) => {
+  const volume = Volume.layer({ fileName, plugins: () => [subscriptionsRequest()] });
+  const live = Layer.merge(Layer.provide(Subscriptions.layer, volume), Layer.provide(OpfsFileSystem.layer, volume));
+  return Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const subscriptions = yield* Subscriptions.Subscriptions;
+        const fs = yield* FileSystem.FileSystem;
+        const subscription = yield* subscriptions.subscribe({ path: '/', scope: 'directory', recursive: true });
+        yield* fs.writeFileString('/observed.txt', 'subscription example');
+        const change = yield* Stream.runHead(subscription.changes);
+        return { change, retired: yield* subscription.retired };
+      }),
+    ).pipe(Effect.provide(live)),
+  );
+};

package/examples/worker-session.ts

@@ -0,0 +1,32 @@
+import { Effect } from 'effect';
+import { Volume } from '@opfs-vfs/effect';
+import type { OpfsVfsWorkerClient } from '@opfs-vfs/opfs-vfs/worker-client';
+import { subscriptionsRequest } from '@opfs-vfs/plugin-subscriptions/config';
+
+export const runWorkerSession = (fileName = `effect-worker-${crypto.randomUUID()}.bin`) =>
+  Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const volume = yield* Volume.make({
+          fileName,
+          transport: 'dedicated',
+          plugins: () => [subscriptionsRequest()],
+        });
+        const backend = Volume.unsafeBackend(volume) as OpfsVfsWorkerClient;
+        yield* Effect.tryPromise({
+          try: () => backend.writeFileBuffer('/session.txt', new TextEncoder().encode('saved by a worker')),
+          catch: (error) => error,
+        });
+        yield* volume.sync;
+        return {
+          content: new TextDecoder().decode(
+            yield* Effect.tryPromise({
+              try: () => backend.readFileBuffer('/session.txt'),
+              catch: (error) => error,
+            }),
+          ),
+          persistence: yield* volume.persistence,
+        };
+      }),
+    ),
+  );

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@opfs-vfs/effect",
+  "version": "0.2.0",
+  "description": "Effect v4 adapter for OPFS VFS.",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opfs-vfs/opfs-vfs.git",
+    "directory": "packages/effect"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./volume": {
+      "types": "./dist/volume.d.ts",
+      "import": "./dist/volume.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.118",
+    "@opfs-vfs/opfs-vfs": "2.1.0",
+    "@opfs-vfs/plugin-subscriptions": "1.2.0",
+    "@types/node": "22.20.3",
+    "@vitest/browser": "4.1.11",
+    "@vitest/browser-playwright": "4.1.11",
+    "effect": "4.0.0-rc.118",
+    "playwright": "1.59.1",
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@opfs-vfs/opfs-vfs": "^2.1.0",
+    "@opfs-vfs/plugin-subscriptions": "^1.2.0",
+    "effect": "4.0.0-rc.118"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:conformance": "vitest run --config vitest.config.ts src/filesystem-contract.test.ts && vitest run --config vitest.node.config.ts",
+    "test:packed": "node scripts/test-packed.mjs",
+    "test:encrypted-packed": "node scripts/test-packed.mjs --encrypted",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}