@livestore/utils 0.4.0-dev.9 → 0.5.0-dev.0

package/src/browser/Opfs/Opfs.ts

@@ -0,0 +1,463 @@
+/// <reference lib="webworker" />
+
+import { Context, Effect, Layer, Option, Schema, type Scope, Stream } from 'effect'
+
+import * as WebError from '../WebError.ts'
+
+/**
+ * Effect service that exposes ergonomic wrappers around Origin Private File System (OPFS) operations.
+ *
+ * @remarks
+ * - Helpers mirror the File System Access API where possible and parse web exceptions into Effect errors.
+ * - Sync access handle helpers can only be used in dedicated workers; invoking them in other contexts fails at runtime.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Origin_private_file_system | MDN Reference}
+ */
+export interface Service {
+  /**
+   * Acquire the OPFS root directory handle.
+   *
+   * @returns Root directory handle for the current origin.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/getDirectory | MDN Reference}
+   */
+  readonly getRootDirectoryHandle: Effect.Effect<FileSystemDirectoryHandle, WebError.WebError>
+  /**
+   * Resolve (and optionally create) a file handle relative to a directory.
+   *
+   * @param parent - Directory to search.
+   * @param name - Target file name.
+   * @param options - Forwarded `getFileHandle` options such as `{ create: true }`.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/getFileHandle | MDN Reference}
+   */
+  readonly getFileHandle: (
+    parent: FileSystemDirectoryHandle,
+    name: string,
+    options?: FileSystemGetFileOptions,
+  ) => Effect.Effect<FileSystemFileHandle, WebError.WebError>
+  /**
+   * Resolve (and optionally create) a directory handle relative to another directory.
+   *
+   * @param parent - Directory to search.
+   * @param name - Target directory name.
+   * @param options - Forwarded `getDirectoryHandle` options such as `{ create: true }`.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/getDirectoryHandle | MDN Reference}
+   */
+  readonly getDirectoryHandle: (
+    parent: FileSystemDirectoryHandle,
+    name: string,
+    options?: FileSystemGetDirectoryOptions,
+  ) => Effect.Effect<FileSystemDirectoryHandle, WebError.WebError>
+  /**
+   * Remove a file-system entry (file or directory) from its parent directory.
+   *
+   * @param parent - Directory containing the entry.
+   * @param name - Entry name.
+   * @param options - Removal behavior (for example `{ recursive: true }`).
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/removeEntry | MDN Reference}
+   */
+  readonly removeEntry: (
+    parent: FileSystemDirectoryHandle,
+    name: string,
+    options?: FileSystemRemoveOptions,
+  ) => Effect.Effect<void, WebError.WebError>
+  /**
+   * Return a stream of child file-system handles for a directory.
+   *
+   * @param directory - Directory whose children are to be streamed
+   * @returns `Stream` of `FileSystemHandle`
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/values | MDN Reference}
+   */
+  readonly values: (
+    directory: FileSystemDirectoryHandle,
+  ) => Stream.Stream<FileSystemHandle, WebError.NotAllowedError | WebError.NotFoundError | WebError.UnknownError>
+  /**
+   * Resolve the relative path from a parent directory to a descendant handle.
+   *
+   * @param parent - Reference directory.
+   * @param child - File or directory handle within the parent hierarchy.
+   * @returns `Option.some(pathSegments)` when reachable, otherwise `Option.none()`.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/resolve | MDN Reference}
+   */
+  readonly resolve: (
+    parent: FileSystemDirectoryHandle,
+    child: FileSystemHandle,
+  ) => Effect.Effect<Option.Option<ReadonlyArray<string>>, WebError.WebError>
+  /**
+   * Read the underlying `File` for a file handle.
+   *
+   * @param handle - Handle referencing the target file.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle/getFile | MDN Reference}
+   */
+  readonly getFile: (handle: FileSystemFileHandle) => Effect.Effect<File, WebError.WebError>
+  /**
+   * Overwrite the contents of a file with the provided data.
+   *
+   * @param handle - File to write to.
+   * @param data - Chunk(s) accepted by `FileSystemWritableFileStream.write`.
+   * @param options - Stream creation options (for example, `{ keepExistingData: false }`).
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle/createWritable | MDN Reference}
+   */
+  readonly writeFile: (
+    handle: FileSystemFileHandle,
+    data: FileSystemWriteChunkType,
+    options?: FileSystemCreateWritableOptions,
+  ) => Effect.Effect<void, WebError.WebError>
+  /**
+   * Append data to the end of an existing file.
+   *
+   * @param handle - File to extend.
+   * @param data - Data to append.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemWritableFileStream/write | MDN Reference}
+   */
+  readonly appendToFile: (
+    handle: FileSystemFileHandle,
+    data: FileSystemWriteChunkType,
+  ) => Effect.Effect<void, WebError.WebError>
+  /**
+   * Truncate a file to the specified size in bytes.
+   *
+   * @param handle - File to shrink or pad.
+   * @param size - Target byte length.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemWritableFileStream/truncate | MDN Reference}
+   */
+  readonly truncateFile: (handle: FileSystemFileHandle, size: number) => Effect.Effect<void, WebError.WebError>
+  /**
+   * Create a synchronous access handle for a file.
+   *
+   * @param handle - File handle to open.
+   * @returns A managed handle that is automatically closed when released.
+   *
+   * @remarks
+   * - Only available in Dedicated Web Workers.
+   * - This method is asynchronous even though the `FileSystemSyncAccessHandle` APIs are synchronous.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle/createSyncAccessHandle | MDN Reference}
+   */
+  readonly createSyncAccessHandle: (
+    handle: FileSystemFileHandle,
+  ) => Effect.Effect<FileSystemSyncAccessHandle, WebError.WebError, Scope.Scope>
+  /**
+   * Perform a synchronous read into the provided buffer from a sync access handle.
+   *
+   * @param handle - Sync access handle to read from.
+   * @param buffer - Destination buffer (can be a specific view like Uint8Array).
+   * @param options - Read position options.
+   * @returns Number of bytes read.
+   *
+   * @remarks
+   * Only available in Dedicated Web Workers.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle/read | MDN Reference}
+   */
+  readonly syncRead: (
+    handle: FileSystemSyncAccessHandle,
+    buffer: ArrayBuffer | ArrayBufferView,
+    options?: FileSystemReadWriteOptions,
+  ) => Effect.Effect<number, WebError.WebError>
+  /**
+   * Perform a synchronous write from the provided buffer into the file.
+   *
+   * @param handle - Sync access handle to write to.
+   * @param buffer - Source data.
+   * @param options - Write position options.
+   * @returns Number of bytes written.
+   *
+   * @remarks
+   * Only available in Dedicated Web Workers.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle/write | MDN Reference}
+   */
+  readonly syncWrite: (
+    handle: FileSystemSyncAccessHandle,
+    buffer: AllowSharedBufferSource,
+    options?: FileSystemReadWriteOptions,
+  ) => Effect.Effect<number, WebError.WebError>
+  /**
+   * Truncate the file associated with a sync access handle to the specified size.
+   *
+   * @param handle - Sync access handle to mutate.
+   * @param size - Desired byte length.
+   *
+   * @remarks
+   * Only available in Dedicated Web Workers.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle/truncate | MDN Reference}
+   */
+  readonly syncTruncate: (handle: FileSystemSyncAccessHandle, size: number) => Effect.Effect<void, WebError.WebError>
+  /**
+   * Retrieve the current size of a file via its sync access handle.
+   *
+   * @param handle - Sync access handle.
+   * @returns File size in bytes.
+   *
+   * @remarks
+   * Only available in Dedicated Web Workers.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle/getSize | MDN Reference}
+   */
+  readonly syncGetSize: (handle: FileSystemSyncAccessHandle) => Effect.Effect<number, WebError.WebError>
+  /**
+   * Flush pending synchronous writes to durable storage.
+   *
+   * @param handle - Sync access handle to flush.
+   *
+   * @remarks
+   * Only available in Dedicated Web Workers.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle/flush | MDN Reference}
+   */
+  readonly syncFlush: (handle: FileSystemSyncAccessHandle) => Effect.Effect<void, WebError.WebError>
+}
+
+export class Opfs extends Context.Service<Opfs, Service>()('@livestore/utils/Opfs') {}
+
+export const layer = Layer.succeed(
+  Opfs,
+  Opfs.of({
+    getRootDirectoryHandle: Effect.tryPromise({
+      try: () => navigator.storage.getDirectory(),
+      catch: (u) => WebError.classifyWebError(u, [WebError.SecurityError]),
+    }),
+    getFileHandle: (parent: FileSystemDirectoryHandle, name: string, options?: FileSystemGetFileOptions) =>
+      Effect.tryPromise({
+        try: () => parent.getFileHandle(name, options),
+        catch: (u) =>
+          WebError.classifyWebError(u, [
+            WebError.NotAllowedError,
+            WebError.TypeError,
+            WebError.TypeMismatchError,
+            WebError.NotFoundError,
+          ]),
+      }),
+    getDirectoryHandle: (parent: FileSystemDirectoryHandle, name: string, options?: FileSystemGetDirectoryOptions) =>
+      Effect.tryPromise({
+        try: () => parent.getDirectoryHandle(name, options),
+        catch: (u) =>
+          WebError.classifyWebError(u, [
+            WebError.NotAllowedError,
+            WebError.TypeError,
+            WebError.TypeMismatchError,
+            WebError.NotFoundError,
+          ]),
+      }),
+    removeEntry: (parent: FileSystemDirectoryHandle, name: string, options?: FileSystemRemoveOptions) =>
+      Effect.tryPromise({
+        try: () => parent.removeEntry(name, options),
+        catch: (u) =>
+          WebError.classifyWebError(u, [
+            WebError.TypeError,
+            WebError.NotAllowedError,
+            WebError.InvalidModificationError,
+            WebError.NotFoundError,
+            WebError.NoModificationAllowedError,
+          ]),
+      }),
+    values: (
+      directory: FileSystemDirectoryHandle,
+    ): Stream.Stream<
+      FileSystemHandle,
+      WebError.NotAllowedError | WebError.NotFoundError | WebError.UnknownError,
+      never
+    > =>
+      Stream.fromAsyncIterable(directory.values(), (u) =>
+        WebError.classifyWebError(u, [WebError.NotAllowedError, WebError.NotFoundError]),
+      ),
+    resolve: (parent: FileSystemDirectoryHandle, child: FileSystemHandle) =>
+      Effect.tryPromise({
+        try: () => parent.resolve(child),
+        catch: (u) => WebError.classifyWebError(u),
+      }).pipe(Effect.map((path) => (path === null ? Option.none() : Option.some(path)))),
+    getFile: (handle: FileSystemFileHandle) =>
+      Effect.tryPromise({
+        try: () => handle.getFile(),
+        catch: (u) => WebError.classifyWebError(u, [WebError.NotAllowedError, WebError.NotFoundError]),
+      }),
+    writeFile: (
+      handle: FileSystemFileHandle,
+      data: FileSystemWriteChunkType,
+      options?: FileSystemCreateWritableOptions,
+    ) =>
+      Effect.acquireUseRelease(
+        Effect.tryPromise({
+          try: () => handle.createWritable(options),
+          catch: (u) =>
+            WebError.classifyWebError(u, [
+              WebError.NotAllowedError,
+              WebError.NotFoundError,
+              WebError.NoModificationAllowedError,
+              WebError.AbortError,
+            ]),
+        }),
+        (stream) =>
+          Effect.tryPromise({
+            try: () => stream.write(data),
+            catch: (u) =>
+              WebError.classifyWebError(u, [WebError.NotAllowedError, WebError.QuotaExceededError, WebError.TypeError]),
+          }),
+        (stream) =>
+          Effect.tryPromise({
+            try: () => stream.close(),
+            catch: (u) => WebError.classifyWebError(u, [WebError.TypeError]),
+          }).pipe(Effect.catchCause(() => Effect.void)),
+      ),
+    appendToFile: (handle: FileSystemFileHandle, data: FileSystemWriteChunkType) =>
+      Effect.acquireUseRelease(
+        Effect.tryPromise({
+          try: () => handle.createWritable({ keepExistingData: true }),
+          catch: (u) =>
+            WebError.classifyWebError(u, [
+              WebError.NotAllowedError,
+              WebError.NotFoundError,
+              WebError.NoModificationAllowedError,
+              WebError.AbortError,
+            ]),
+        }),
+        (stream) =>
+          Effect.gen(function* () {
+            const file = yield* Effect.tryPromise({
+              try: () => handle.getFile(),
+              catch: (u) => WebError.classifyWebError(u, [WebError.NotAllowedError, WebError.NotFoundError]),
+            })
+            yield* Effect.tryPromise({
+              try: () => stream.seek(file.size),
+              catch: (u) => WebError.classifyWebError(u, [WebError.NotAllowedError, WebError.TypeError]),
+            })
+            yield* Effect.tryPromise({
+              try: () => stream.write(data),
+              catch: (u) =>
+                WebError.classifyWebError(u, [
+                  WebError.NotAllowedError,
+                  WebError.QuotaExceededError,
+                  WebError.TypeError,
+                ]),
+            })
+          }),
+        (stream) =>
+          Effect.tryPromise({
+            try: () => stream.close(),
+            catch: (u) => WebError.classifyWebError(u, [WebError.TypeError]),
+          }).pipe(Effect.catchCause(() => Effect.void)),
+      ),
+    truncateFile: (handle: FileSystemFileHandle, size: number) =>
+      Effect.acquireUseRelease(
+        Effect.tryPromise({
+          try: () => handle.createWritable({ keepExistingData: true }),
+          catch: (u) =>
+            WebError.classifyWebError(u, [
+              WebError.NotAllowedError,
+              WebError.NotFoundError,
+              WebError.NoModificationAllowedError,
+              WebError.AbortError,
+            ]),
+        }),
+        (stream) =>
+          Effect.tryPromise({
+            try: () => stream.truncate(size),
+            catch: (u) =>
+              WebError.classifyWebError(u, [WebError.NotAllowedError, WebError.TypeError, WebError.QuotaExceededError]),
+          }),
+        (stream) =>
+          Effect.tryPromise({
+            try: () => stream.close(),
+            catch: (u) => WebError.classifyWebError(u, [WebError.TypeError]),
+          }).pipe(Effect.catchCause(() => Effect.void)),
+      ),
+    createSyncAccessHandle: (handle: FileSystemFileHandle) =>
+      Effect.acquireRelease(
+        Effect.tryPromise({
+          try: () => handle.createSyncAccessHandle(),
+          catch: (u) =>
+            WebError.classifyWebError(u, [
+              WebError.NotAllowedError,
+              WebError.InvalidStateError,
+              WebError.NotFoundError,
+              WebError.NoModificationAllowedError,
+            ]),
+        }),
+        (syncHandle) => Effect.sync(() => syncHandle.close()),
+      ),
+    syncRead: (
+      handle: FileSystemSyncAccessHandle,
+      buffer: ArrayBuffer | ArrayBufferView,
+      options?: FileSystemReadWriteOptions,
+    ) =>
+      Effect.try({
+        try: () => handle.read(buffer, options),
+        catch: (u) =>
+          WebError.classifyWebError(u, [WebError.RangeError, WebError.InvalidStateError, WebError.TypeError]),
+      }),
+    syncWrite: (
+      handle: FileSystemSyncAccessHandle,
+      buffer: AllowSharedBufferSource,
+      options?: FileSystemReadWriteOptions,
+    ) =>
+      Effect.try({
+        try: () => handle.write(buffer, options),
+        catch: (u) => WebError.classifyWebError(u),
+      }),
+    syncTruncate: (handle: FileSystemSyncAccessHandle, size: number) =>
+      Effect.try({
+        try: () => handle.truncate(size),
+        catch: (u) => WebError.classifyWebError(u),
+      }),
+    syncGetSize: (handle: FileSystemSyncAccessHandle) =>
+      Effect.try({
+        try: () => handle.getSize(),
+        catch: (u) => WebError.classifyWebError(u),
+      }),
+    syncFlush: (handle: FileSystemSyncAccessHandle) =>
+      Effect.try({
+        try: () => handle.flush(),
+        catch: (u) => WebError.classifyWebError(u),
+      }),
+  }),
+)
+
+const notFoundError = new WebError.NotFoundError({
+  cause: new DOMException('The object can not be found here.', 'NotFoundError'),
+})
+
+const unknownError = (message: string) => new WebError.UnknownError({ description: message })
+
+/**
+ * A no-op Opfs service that can be used for testing.
+ */
+export const layerNoop = Layer.succeed(
+  Opfs,
+  Opfs.of({
+    getRootDirectoryHandle: Effect.fail(unknownError('OPFS is not supported in this environment')),
+    getFileHandle: () => Effect.fail(notFoundError),
+    getDirectoryHandle: () => Effect.fail(notFoundError),
+    removeEntry: () => Effect.fail(notFoundError),
+    values: () => Stream.fail(notFoundError),
+    resolve: () => Effect.succeed(Option.none()),
+    getFile: () => Effect.fail(notFoundError),
+    writeFile: () => Effect.fail(notFoundError),
+    appendToFile: () => Effect.fail(notFoundError),
+    truncateFile: () => Effect.fail(notFoundError),
+    createSyncAccessHandle: () => Effect.fail(unknownError('OPFS is not supported in this environment')),
+    syncRead: () => Effect.fail(unknownError('OPFS is not supported in this environment')),
+    syncWrite: () => Effect.fail(unknownError('OPFS is not supported in this environment')),
+    syncTruncate: () => Effect.fail(unknownError('OPFS is not supported in this environment')),
+    syncGetSize: () => Effect.fail(unknownError('OPFS is not supported in this environment')),
+    syncFlush: () => Effect.fail(unknownError('OPFS is not supported in this environment')),
+  }),
+)
+
+/**
+ * Error raised when OPFS operations fail.
+ */
+export class OpfsError extends Schema.TaggedError<OpfsError>('~@livestore/utils/OpfsError')('OpfsError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}

package/src/browser/Opfs/debug-utils.ts

@@ -0,0 +1,154 @@
+/**
+ * Debug utilities for OPFS (Origin Private File System) inspection and manipulation.
+ * These functions are designed for use in browser devtools console to help debug
+ * and inspect the OPFS structure during development.
+ */
+
+import { Effect, Stream } from 'effect'
+import prettyBytes from 'pretty-bytes'
+
+import type * as WebError from '../WebError.ts'
+import * as Opfs from './Opfs.ts'
+import { getDirectoryHandleByPath, getMetadata, remove } from './utils.ts'
+
+/**
+ * Metadata exposed directly on OPFS handles so we avoid `getFile()` reads.
+ */
+interface OpfsEntryMetadata {
+  readonly name: string
+  readonly path: string
+  readonly kind: FileSystemHandleKind
+  readonly size?: number
+  readonly lastModified?: number
+}
+
+interface OpfsTreeNode {
+  readonly metadata: OpfsEntryMetadata
+  readonly children?: ReadonlyArray<OpfsTreeNode>
+}
+
+const ROOT_NAME = '/'
+
+/**
+ * Materialize the entire OPFS tree starting from the origin root.
+ */
+const buildTree = Effect.fn('@livestore/utils:Opfs.buildTree')(function* () {
+  const opfs = yield* Opfs.Opfs
+  const rootHandle = yield* opfs.getRootDirectoryHandle
+
+  const collectDirectory = (
+    handle: FileSystemDirectoryHandle,
+    pathSegments: ReadonlyArray<string>,
+  ): Effect.Effect<OpfsTreeNode, WebError.WebError, Opfs.Opfs> =>
+    Effect.gen(function* () {
+      const handlesStream = opfs.values(handle)
+      const handles = yield* handlesStream.pipe(
+        Stream.runCollect,
+        Effect.map((chunk) => Array.from(chunk).sort((a, b) => a.name.localeCompare(b.name))),
+      )
+
+      const children = yield* Effect.forEach(
+        handles,
+        (childHandle) =>
+          Effect.gen(function* () {
+            const nextSegments = [...pathSegments, childHandle.name]
+            const path = formatPath(nextSegments)
+
+            if (childHandle.kind === 'directory') {
+              return yield* collectDirectory(childHandle as FileSystemDirectoryHandle, nextSegments)
+            }
+
+            const metadata = yield* getMetadata(childHandle as FileSystemFileHandle)
+
+            return {
+              metadata: {
+                name: childHandle.name,
+                path,
+                kind: 'file',
+                size: metadata.size,
+                lastModified: metadata.lastModified,
+              },
+            } satisfies OpfsTreeNode
+          }),
+        { concurrency: 'unbounded' },
+      )
+
+      return {
+        metadata: {
+          name: pathSegments.length === 0 ? ROOT_NAME : pathSegments[pathSegments.length - 1]!,
+          path: formatPath(pathSegments),
+          kind: 'directory',
+        },
+        children,
+      }
+    })
+
+  return yield* collectDirectory(rootHandle, [])
+})
+
+const formatPath = (segments: ReadonlyArray<string>) => (segments.length === 0 ? ROOT_NAME : `/${segments.join('/')}`)
+
+const formatLabel = ({ name, kind, size, lastModified }: OpfsEntryMetadata) => {
+  let label = name
+
+  if (kind === 'file' && lastModified !== undefined) {
+    const date = new Date(lastModified)
+    label += ` │ ${date.toISOString().split('T')[0]} ${date.toTimeString().split(' ')[0]}`
+
+    if (size !== undefined) {
+      label += ` │ ${prettyBytes(size)}`
+    }
+  }
+
+  return label
+}
+
+const logAsciiTree = (node: OpfsTreeNode): Effect.Effect<void> =>
+  logAsciiNode(node, { prefix: '', isLast: true, isRoot: true })
+
+const logAsciiNode: (
+  node: OpfsTreeNode,
+  options: { readonly prefix: string; readonly isLast: boolean; readonly isRoot?: boolean },
+) => Effect.Effect<void> = (node, options) =>
+  Effect.gen(function* () {
+    const label = formatLabel(node.metadata)
+    const branch = options.isRoot === true ? '' : `${options.prefix}${options.isLast === true ? '└── ' : '├── '}`
+    const nextPrefix = options.isRoot === true ? '' : `${options.prefix}${options.isLast === true ? '    ' : '│   '}`
+
+    console.log(`${branch}${label}`)
+
+    if (node.children === undefined || node.children.length === 0) return
+
+    for (let index = 0; index < node.children.length; index++) {
+      const child = node.children[index]!
+      const isLastChild = index === node.children.length - 1
+      yield* logAsciiNode(child, { prefix: nextPrefix, isLast: isLastChild })
+    }
+  })
+
+const printTree = Effect.gen(function* () {
+  const tree = yield* buildTree()
+  yield* logAsciiTree(tree)
+})
+
+const resetTree = remove('/')
+
+const getDirHandle = (path: string, options?: FileSystemGetDirectoryOptions) => getDirectoryHandleByPath(path, options)
+
+const runOpfsEffect = <A, E>(effect: Effect.Effect<A, E, Opfs.Opfs>) =>
+  effect.pipe(Effect.provide(Opfs.layer), Effect.runPromise)
+
+export const debugUtils = {
+  /**
+   * Print the entire OPFS tree structure to the console in an ASCII format.
+   */
+  printTree: (): Promise<void> => runOpfsEffect(printTree),
+  /**
+   * Reset the entire OPFS tree by removing all files and directories.
+   */
+  resetTree: (): Promise<void> => runOpfsEffect(resetTree),
+  /**
+   * Get a directory handle for a given path, useful for inspecting or manipulating specific directories.
+   */
+  getDirHandle: (path: string, options?: FileSystemGetDirectoryOptions) => runOpfsEffect(getDirHandle(path, options)),
+} as const

package/src/browser/Opfs/mod.ts

@@ -0,0 +1,3 @@
+export * from './debug-utils.ts'
+export * from './Opfs.ts'
+export * from './utils.ts'