@livestore/utils 0.4.0-dev.18 → 0.4.0-dev.19

package/src/browser/Opfs/utils.ts

@@ -0,0 +1,270 @@
+import { Effect, Stream } from 'effect'
+import { Opfs, OpfsError } from './Opfs.ts'
+
+/**
+ * Set of path segments that are forbidden by the File System specification.
+ *
+ * A valid segment is non-empty, not equal to `.` or `..`, and must not have path separator characters.
+ *
+ * @see {@link https://fs.spec.whatwg.org/#valid-file-name | File System Spec}
+ */
+const DISALLOWED_SEGMENTS = new Set(['.', '..'])
+
+/**
+ * Parse a slash-separated OPFS path into validated segments.
+ *
+ * Rejects empty paths and disallows `.` / `..` so callers cannot rely on implicit current/parent
+ * directory semantics that the File System Access API does not support.
+ *
+ * @param path - Slash-delimited path relative to the OPFS root.
+ * @returns Effect that yields the sanitized path segments.
+ */
+const parsePathSegments = (path: string) =>
+  Effect.gen(function* () {
+    const segments = path.split('/').filter((segment) => segment.length > 0)
+
+    if (segments.length === 0) {
+      return yield* new OpfsError({
+        message: `Invalid OPFS path '${path}': path must contain at least one non-empty segment`,
+      })
+    }
+
+    for (const segment of segments) {
+      if (DISALLOWED_SEGMENTS.has(segment)) {
+        return yield* new OpfsError({
+          message: `Invalid OPFS path '${path}': segment '${segment}' is not supported`,
+        })
+      }
+    }
+
+    return segments
+  })
+
+/**
+ * Determine whether the provided OPFS path refers to the origin root.
+ */
+const isRootPath = (path: string) => path === '' || path === '/'
+
+/**
+ * Split a set of path segments into parent and leaf portions.
+ *
+ * @param segments - Non-empty sequence of path segments pointing to a concrete entry.
+ * @returns Parent directory segments and the final segment representing the target entry.
+ */
+const splitPathSegments = (segments: ReadonlyArray<string>) => ({
+  parentSegments: segments.slice(0, -1),
+  leafSegment: segments[segments.length - 1]!,
+})
+
+/**
+ * Resolve a directory path from the OPFS root and return the final directory handle.
+ *
+ * @param segments - Ordered list of directory names to follow.
+ * @param options - Options forwarded to each `getDirectoryHandle` call.
+ */
+const traverseDirectoryPath = (segments: ReadonlyArray<string>, options?: FileSystemGetDirectoryOptions) =>
+  Effect.gen(function* () {
+    let currentDirHandle = yield* Opfs.getRootDirectoryHandle
+
+    for (let index = 0; index < segments.length; index++) {
+      const segment = segments[index]!
+      currentDirHandle = yield* Opfs.getDirectoryHandle(currentDirHandle, segment, options)
+    }
+
+    return currentDirHandle
+  })
+
+/**
+ * Ensure that a directory path exists, creating intermediate segments when permitted.
+ *
+ * @param segments - Ordered list of directory names to ensure.
+ * @param options.recursive - When `true`, create every missing segment. Otherwise only the leaf is created.
+ */
+const ensureDirectoryPath = (segments: ReadonlyArray<string>, options: { readonly recursive: boolean }) =>
+  Effect.gen(function* () {
+    let currentDirHandle = yield* Opfs.getRootDirectoryHandle
+
+    for (let index = 0; index < segments.length; index++) {
+      const segment = segments[index]!
+      const isLast = index === segments.length - 1
+      const shouldCreate = options.recursive || isLast
+
+      currentDirHandle = yield* Opfs.getDirectoryHandle(
+        currentDirHandle,
+        segment,
+        shouldCreate ? { create: true } : undefined,
+      )
+    }
+
+    return currentDirHandle
+  })
+
+/**
+ * Resolve a directory handle using a slash-delimited OPFS path.
+ *
+ * @param path - Directory path relative to the OPFS root.
+ * @param options - Options forwarded to `getDirectoryHandle` when traversing segments.
+ * @returns Directory handle for the final segment.
+ */
+export const getDirectoryHandleByPath = Effect.fn('@livestore/utils:Opfs.getDirectoryHandleByPath')(function* (
+  path: string,
+  options?: FileSystemGetDirectoryOptions,
+) {
+  if (isRootPath(path)) return yield* Opfs.getRootDirectoryHandle
+
+  const pathSegments = yield* parsePathSegments(path)
+  return yield* traverseDirectoryPath(pathSegments, options)
+})
+
+/**
+ * Remove a file or directory identified by an OPFS path.
+ *
+ * @param path - Slash-delimited path to delete.
+ * @param options.recursive - When `true`, recursively delete directory contents; defaults to `false`.
+ */
+export const remove = Effect.fn('@livestore/utils:Opfs.remove')(function* (
+  path: string,
+  options?: { readonly recursive?: boolean },
+) {
+  const recursive = options?.recursive ?? false
+
+  if (isRootPath(path)) {
+    const rootHandle = yield* Opfs.getRootDirectoryHandle
+    const handlesStream = yield* Opfs.values(rootHandle)
+    yield* handlesStream.pipe(
+      Stream.runForEach((handle) => Opfs.removeEntry(rootHandle, handle.name, { recursive: true })),
+    )
+    return
+  }
+
+  const pathSegments = yield* parsePathSegments(path)
+  const { parentSegments, leafSegment: targetName } = splitPathSegments(pathSegments)
+  const parentDirHandle = yield* traverseDirectoryPath(parentSegments)
+
+  yield* Opfs.removeEntry(parentDirHandle, targetName, { recursive })
+})
+
+/**
+ * Determine whether a file or directory exists at the given OPFS path.
+ *
+ * @param path - Slash-delimited path to inspect.
+ * @returns `true` if the path resolves to a file or directory, otherwise `false`.
+ */
+export const exists = Effect.fn('@livestore/utils:Opfs.exists')(function* (path: string) {
+  if (isRootPath(path)) return true
+
+  const pathSegments = yield* parsePathSegments(path)
+  const { parentSegments, leafSegment: targetName } = splitPathSegments(pathSegments)
+
+  const parentDirHandle = yield* traverseDirectoryPath(parentSegments, { create: false }).pipe(
+    Effect.catchTag('@livestore/utils/Web/NotFoundError', () => Effect.succeed(undefined)),
+  )
+
+  if (parentDirHandle === undefined) return false
+
+  return yield* Opfs.getFileHandle(parentDirHandle, targetName).pipe(
+    Effect.orElse(() => Opfs.getDirectoryHandle(parentDirHandle, targetName, { create: false })),
+    Effect.as(true),
+    Effect.catchTag('@livestore/utils/Web/NotFoundError', () => Effect.succeed(false)),
+  )
+})
+
+/**
+ * Create a directory at the provided path, optionally creating parents recursively.
+ *
+ * @param path - Slash-delimited directory path.
+ * @param options.recursive - When `true`, create all missing parent segments; defaults to `false`.
+ */
+export const makeDirectory = Effect.fn('@livestore/utils:Opfs.makeDirectory')(function* (
+  path: string,
+  options?: { readonly recursive?: boolean },
+) {
+  const recursive = options?.recursive ?? false
+
+  if (isRootPath(path)) return
+
+  const pathSegments = yield* parsePathSegments(path)
+
+  yield* ensureDirectoryPath(pathSegments, { recursive })
+})
+
+/**
+ * Extract basic metadata for a given file handle.
+ *
+ * @param handle - File handle whose metadata should be read.
+ * @returns Object containing name, size, MIME type, and last modification timestamp.
+ */
+export const getMetadata = Effect.fn('@livestore/utils:Opfs.getMetadata')(function* (handle: FileSystemFileHandle) {
+  return yield* Opfs.getFile(handle).pipe(
+    Effect.map((file) => ({
+      name: file.name,
+      size: file.size,
+      type: file.type,
+      lastModified: file.lastModified,
+    })),
+  )
+})
+
+/**
+ * Write bytes to an OPFS path, creating or replacing the target file.
+ *
+ * @param path - Slash-delimited file path.
+ * @param data - Bytes to persist.
+ */
+export const writeFile = Effect.fn('@livestore/utils:Opfs.writeFile')(function* (path: string, data: Uint8Array) {
+  if (isRootPath(path)) {
+    return yield* new OpfsError({
+      message: `Invalid OPFS path '${path}': cannot write file directly to the OPFS root`,
+    })
+  }
+
+  const pathSegments = yield* parsePathSegments(path)
+  const { parentSegments, leafSegment: fileName } = splitPathSegments(pathSegments)
+
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      const parentDirHandle = yield* traverseDirectoryPath(parentSegments)
+      const fileHandle = yield* Opfs.getFileHandle(parentDirHandle, fileName, { create: true })
+
+      yield* Opfs.writeFile(fileHandle, new Uint8Array(data), {
+        keepExistingData: false,
+      })
+    }),
+  )
+})
+
+/**
+ * Synchronously write bytes to the target file handle, truncating any existing content.
+ *
+ * @param handle - Sync access handle to overwrite.
+ * @param buffer - Raw data to persist.
+ * @returns Effect that resolves once every byte is flushed to durable storage.
+ *
+ * @remarks
+ * - Only available in Dedicated Web Workers.
+ * - Crash safety: not atomic. A crash mid-write can leave the file truncated or partially written.
+ *   For atomic replacement, prefer `writeFile` or a temp-file pattern with two prepared handles.
+ */
+export const syncWriteFile = Effect.fn('@livestore/utils:Opfs.syncWriteFile')(function* (
+  handle: FileSystemSyncAccessHandle,
+  buffer: AllowSharedBufferSource,
+) {
+  const bytes = ArrayBuffer.isView(buffer)
+    ? new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+    : new Uint8Array(buffer as ArrayBufferLike)
+
+  yield* Opfs.syncTruncate(handle, 0)
+
+  let offset = 0
+  while (offset < bytes.byteLength) {
+    const wrote = yield* Opfs.syncWrite(handle, bytes.subarray(offset), { at: offset })
+    if (wrote === 0) {
+      return yield* new OpfsError({
+        message: `Short write: wrote ${offset} of ${bytes.byteLength} bytes.`,
+      })
+    }
+    offset += Number(wrote)
+  }
+
+  yield* Opfs.syncFlush(handle)
+})

package/src/browser/QuotaExceededError.ts

@@ -0,0 +1,59 @@
+/**
+ * Type augmentation for the `QuotaExceededError` interface.
+ *
+ * In previous versions of the Web platform standard, quota exceeded errors were to be thrown
+ * as regular `DOMException` objects with `name: "QuotaExceededError"`. In the latest versions,
+ * the `QuotaExceededError` exists as a dedicated interface extending `DOMException`, providing
+ * additional properties like `quota` and `requested`.
+ *
+ * As of TypeScript 5.9, the standard DOM type definitions (`lib.dom.d.ts`) do **not** include
+ * the `QuotaExceededError` interface, even though it is already supported by a few browsers.
+ *
+ * This file provides the missing type definitions so that code can safely reference
+ * `globalThis.QuotaExceededError` with proper type checking, supporting both:
+ * - Browsers with the new dedicated interface
+ * - Browsers still using a regular `DOMException`
+ *
+ * @see {@link https://webidl.spec.whatwg.org/#quotaexceedederror | Web IDL Specification}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError | MDN Reference}
+ */
+declare global {
+  interface QuotaExceededError extends DOMException {
+    /**
+     * The **`message`** read-only property of a message or description associated with the given error name.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError/QuotaExceededError#message)
+     */
+    readonly message: string
+    /**
+     * A number representing the quota limit in bytes, or undefined.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError/quota)
+     */
+    readonly quota?: number
+    /**
+     * A number representing the requested amount of storage in bytes, or undefined.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError/requested)
+     */
+    readonly requested?: number
+  }
+
+  /**
+   * The **`QuotaExceededError`** represents an error when a requested operation would exceed a system-imposed storage quota.
+   *
+   * @remarks
+   *
+   * In browser versions before this interface was implemented, it was a regular DOMException. The subclassing allows for extra information like quota and requested to be included.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError)
+   */
+  var QuotaExceededError:
+    | {
+        prototype: QuotaExceededError
+        new (message?: string, options?: { quota: number; requested: number }): QuotaExceededError
+      }
+    | undefined
+}
+
+export {}

package/src/browser/WebChannelBrowser.ts

@@ -0,0 +1,131 @@
+import { Deferred, Exit, Scope } from 'effect'
+
+import * as Effect from '../effect/Effect.ts'
+import * as Schema from '../effect/Schema/index.ts'
+import * as Stream from '../effect/Stream.ts'
+import {
+  type InputSchema,
+  listenToDebugPing,
+  mapSchema,
+  type WebChannel,
+  WebChannelSymbol,
+} from '../effect/WebChannel/common.ts'
+
+/** Browser BroadcastChannel-backed WebChannel */
+export const broadcastChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
+  channelName,
+  schema: inputSchema,
+}: {
+  channelName: string
+  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
+}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
+  Effect.scopeWithCloseable((scope) =>
+    Effect.gen(function* () {
+      const schema = mapSchema(inputSchema)
+
+      const channel = new BroadcastChannel(channelName)
+
+      yield* Effect.addFinalizer(() => Effect.try(() => channel.close()).pipe(Effect.ignoreLogged))
+
+      const send = (message: MsgSend) =>
+        Effect.gen(function* () {
+          const messageEncoded = yield* Schema.encode(schema.send)(message)
+          channel.postMessage(messageEncoded)
+        })
+
+      // TODO also listen to `messageerror` in parallel
+      const listen = Stream.fromEventListener<MessageEvent>(channel, 'message').pipe(
+        Stream.map((_) => Schema.decodeEither(schema.listen)(_.data)),
+        listenToDebugPing(channelName),
+      )
+
+      const closedDeferred = yield* Deferred.make<void>().pipe(Effect.acquireRelease(Deferred.done(Exit.void)))
+      const supportsTransferables = false
+
+      return {
+        [WebChannelSymbol]: WebChannelSymbol,
+        send,
+        listen,
+        closedDeferred,
+        shutdown: Scope.close(scope, Exit.succeed('shutdown')),
+        schema,
+        supportsTransferables,
+      }
+    }).pipe(Effect.withSpan(`WebChannel:broadcastChannel(${channelName})`)),
+  )
+
+/**
+ * Window.postMessage-based WebChannel
+ */
+export const windowChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
+  listenWindow,
+  sendWindow,
+  targetOrigin = '*',
+  ids,
+  schema: inputSchema,
+}: {
+  listenWindow: Window
+  sendWindow: Window
+  targetOrigin?: string
+  ids: { own: string; other: string }
+  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
+}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
+  Effect.scopeWithCloseable((scope) =>
+    Effect.gen(function* () {
+      const schema = mapSchema(inputSchema)
+
+      const debugInfo = {
+        sendTotal: 0,
+        listenTotal: 0,
+        targetOrigin,
+        ids,
+      }
+
+      const WindowMessageListen = Schema.Struct({
+        message: schema.listen,
+        from: Schema.Literal(ids.other),
+        to: Schema.Literal(ids.own),
+      }).annotations({ title: 'webmesh.WindowMessageListen' })
+
+      const WindowMessageSend = Schema.Struct({
+        message: schema.send,
+        from: Schema.Literal(ids.own),
+        to: Schema.Literal(ids.other),
+      }).annotations({ title: 'webmesh.WindowMessageSend' })
+
+      const send = (message: MsgSend) =>
+        Effect.gen(function* () {
+          debugInfo.sendTotal++
+
+          const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(WindowMessageSend)({
+            message,
+            from: ids.own,
+            to: ids.other,
+          })
+          sendWindow.postMessage(messageEncoded, targetOrigin, transferables)
+        })
+
+      const listen = Stream.fromEventListener<MessageEvent>(listenWindow, 'message').pipe(
+        Stream.filter((_) => Schema.is(Schema.encodedSchema(WindowMessageListen))(_.data)),
+        Stream.map((_) => {
+          debugInfo.listenTotal++
+          return Schema.decodeEither(schema.listen)(_.data.message)
+        }),
+        listenToDebugPing('window'),
+      )
+
+      const closedDeferred = yield* Deferred.make<void>().pipe(Effect.acquireRelease(Deferred.done(Exit.void)))
+      const supportsTransferables = true
+
+      return {
+        [WebChannelSymbol]: WebChannelSymbol,
+        send,
+        listen,
+        closedDeferred,
+        shutdown: Scope.close(scope, Exit.succeed('shutdown')),
+        schema,
+        supportsTransferables,
+        debugInfo,
+      }
+    }).pipe(Effect.withSpan(`WebChannel:windowChannel`)),
+  )

package/src/browser/WebError.test.ts

@@ -0,0 +1,66 @@
+import * as Vitest from '@effect/vitest'
+
+import * as WebError from './WebError.ts'
+
+Vitest.describe('parseWebError', () => {
+  Vitest.it('returns a WebError instance unchanged when no expectations are provided', () => {
+    const domException = new DOMException('missing node', 'NotFoundError')
+    const webError = new WebError.NotFoundError({ cause: domException })
+
+    const result = WebError.parseWebError(webError)
+
+    Vitest.expect(result).toBeInstanceOf(WebError.NotFoundError)
+    Vitest.expect(result.cause).toBe(domException)
+  })
+
+  Vitest.it('maps native errors to the corresponding WebError when expected', () => {
+    const nativeError = new globalThis.TypeError('unsupported type')
+
+    const result = WebError.parseWebError(nativeError, [WebError.TypeError])
+
+    Vitest.expect(result).toBeInstanceOf(WebError.TypeError)
+    Vitest.expect(result.cause).toBe(nativeError)
+  })
+
+  Vitest.it('wraps parsed errors that are not in the expected list in UnknownError', () => {
+    const nativeError = new globalThis.RangeError('value out of range')
+
+    const result = WebError.parseWebError(nativeError, [WebError.TypeError])
+
+    Vitest.expect(result).toBeInstanceOf(WebError.UnknownError)
+    Vitest.expect(result.cause).toBeInstanceOf(WebError.RangeError)
+  })
+
+  Vitest.it('translates DOMException names into the matching WebError variant', () => {
+    const domException = new DOMException('permission denied', 'NotAllowedError')
+
+    const result = WebError.parseWebError(domException, [WebError.NotAllowedError])
+
+    Vitest.expect(result).toBeInstanceOf(WebError.NotAllowedError)
+    Vitest.expect(result.cause).toBe(domException)
+  })
+
+  Vitest.it('produces UnknownError for non-error values with the default message', () => {
+    const value = { reason: 'unexpected' }
+
+    const result = WebError.parseWebError(value)
+
+    Vitest.expect(result).toBeInstanceOf(WebError.UnknownError)
+    Vitest.expect(result.cause).toBeDefined()
+    Vitest.expect(result.message).toBe('A web error occurred')
+  })
+
+  Vitest.it('returns UnknownError instances without altering their payload when expectations are provided', () => {
+    const existing = new WebError.UnknownError({ description: 'pre-parsed' })
+
+    const result = WebError.parseWebError(existing, [WebError.TypeError])
+
+    Vitest.expect(result).toBeInstanceOf(WebError.UnknownError)
+
+    if (!(result instanceof WebError.UnknownError)) {
+      throw new Error('Expected an UnknownError instance')
+    }
+
+    Vitest.expect(result.description).toBe('pre-parsed')
+  })
+})