@livestore/utils 0.4.0 → 0.5.0-dev.0

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

@@ -8,7 +8,7 @@ import { Effect, Stream } from 'effect'
 import prettyBytes from 'pretty-bytes'
 
 import type * as WebError from '../WebError.ts'
-import { Opfs } from './Opfs.ts'
+import * as Opfs from './Opfs.ts'
 import { getDirectoryHandleByPath, getMetadata, remove } from './utils.ts'
 
 /**
@@ -33,14 +33,15 @@ const ROOT_NAME = '/'
  * Materialize the entire OPFS tree starting from the origin root.
  */
 const buildTree = Effect.fn('@livestore/utils:Opfs.buildTree')(function* () {
-  const rootHandle = yield* Opfs.getRootDirectoryHandle
+  const opfs = yield* Opfs.Opfs
+  const rootHandle = yield* opfs.getRootDirectoryHandle
 
   const collectDirectory = (
     handle: FileSystemDirectoryHandle,
     pathSegments: ReadonlyArray<string>,
-  ): Effect.Effect<OpfsTreeNode, WebError.WebError, Opfs> =>
+  ): Effect.Effect<OpfsTreeNode, WebError.WebError, Opfs.Opfs> =>
     Effect.gen(function* () {
-      const handlesStream = yield* Opfs.values(handle)
+      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))),
@@ -134,8 +135,8 @@ const resetTree = remove('/')
 
 const getDirHandle = (path: string, options?: FileSystemGetDirectoryOptions) => getDirectoryHandleByPath(path, options)
 
-const runOpfsEffect = <A, E>(effect: Effect.Effect<A, E, Opfs>) =>
-  effect.pipe(Effect.provide(Opfs.Default), Effect.runPromise)
+const runOpfsEffect = <A, E>(effect: Effect.Effect<A, E, Opfs.Opfs>) =>
+  effect.pipe(Effect.provide(Opfs.layer), Effect.runPromise)
 
 export const debugUtils = {
   /**

package/src/browser/Opfs/utils.ts

@@ -1,6 +1,6 @@
 import { Effect, Stream } from 'effect'
 
-import { Opfs, OpfsError } from './Opfs.ts'
+import * as Opfs from './Opfs.ts'
 
 /**
  * Set of path segments that are forbidden by the File System specification.
@@ -25,14 +25,14 @@ const parsePathSegments = (path: string) =>
     const segments = path.split('/').filter((segment) => segment.length > 0)
 
     if (segments.length === 0) {
-      return yield* new OpfsError({
+      return yield* new Opfs.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) === true) {
-        return yield* new OpfsError({
+        return yield* new Opfs.OpfsError({
           message: `Invalid OPFS path '${path}': segment '${segment}' is not supported`,
         })
       }
@@ -65,11 +65,12 @@ const splitPathSegments = (segments: ReadonlyArray<string>) => ({
  */
 const traverseDirectoryPath = (segments: ReadonlyArray<string>, options?: FileSystemGetDirectoryOptions) =>
   Effect.gen(function* () {
-    let currentDirHandle = yield* Opfs.getRootDirectoryHandle
+    const opfs = yield* Opfs.Opfs
+    let currentDirHandle = yield* opfs.getRootDirectoryHandle
 
     for (let index = 0; index < segments.length; index++) {
       const segment = segments[index]!
-      currentDirHandle = yield* Opfs.getDirectoryHandle(currentDirHandle, segment, options)
+      currentDirHandle = yield* opfs.getDirectoryHandle(currentDirHandle, segment, options)
     }
 
     return currentDirHandle
@@ -83,14 +84,15 @@ const traverseDirectoryPath = (segments: ReadonlyArray<string>, options?: FileSy
  */
 const ensureDirectoryPath = (segments: ReadonlyArray<string>, options: { readonly recursive: boolean }) =>
   Effect.gen(function* () {
-    let currentDirHandle = yield* Opfs.getRootDirectoryHandle
+    const opfs = yield* Opfs.Opfs
+    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 = yield* opfs.getDirectoryHandle(
         currentDirHandle,
         segment,
         shouldCreate === true ? { create: true } : undefined,
@@ -111,7 +113,10 @@ export const getDirectoryHandleByPath = Effect.fn('@livestore/utils:Opfs.getDire
   path: string,
   options?: FileSystemGetDirectoryOptions,
 ) {
-  if (isRootPath(path) === true) return yield* Opfs.getRootDirectoryHandle
+  if (isRootPath(path) === true) {
+    const opfs = yield* Opfs.Opfs
+    return yield* opfs.getRootDirectoryHandle
+  }
 
   const pathSegments = yield* parsePathSegments(path)
   return yield* traverseDirectoryPath(pathSegments, options)
@@ -128,12 +133,13 @@ export const remove = Effect.fn('@livestore/utils:Opfs.remove')(function* (
   options?: { readonly recursive?: boolean },
 ) {
   const recursive = options?.recursive ?? false
+  const opfs = yield* Opfs.Opfs
 
   if (isRootPath(path) === true) {
-    const rootHandle = yield* Opfs.getRootDirectoryHandle
-    const handlesStream = yield* Opfs.values(rootHandle)
+    const rootHandle = yield* opfs.getRootDirectoryHandle
+    const handlesStream = opfs.values(rootHandle)
     yield* handlesStream.pipe(
-      Stream.runForEach((handle) => Opfs.removeEntry(rootHandle, handle.name, { recursive: true })),
+      Stream.runForEach((handle) => opfs.removeEntry(rootHandle, handle.name, { recursive: true })),
     )
     return
   }
@@ -142,7 +148,7 @@ export const remove = Effect.fn('@livestore/utils:Opfs.remove')(function* (
   const { parentSegments, leafSegment: targetName } = splitPathSegments(pathSegments)
   const parentDirHandle = yield* traverseDirectoryPath(parentSegments)
 
-  yield* Opfs.removeEntry(parentDirHandle, targetName, { recursive })
+  yield* opfs.removeEntry(parentDirHandle, targetName, { recursive })
 })
 
 /**
@@ -158,13 +164,14 @@ export const exists = Effect.fn('@livestore/utils:Opfs.exists')(function* (path:
   const { parentSegments, leafSegment: targetName } = splitPathSegments(pathSegments)
 
   const parentDirHandle = yield* traverseDirectoryPath(parentSegments, { create: false }).pipe(
-    Effect.catchTag('NotFoundError', () => Effect.succeed(undefined)),
+    Effect.catchTag('NotFoundError', () => Effect.void),
   )
 
   if (parentDirHandle === undefined) return false
 
-  return yield* Opfs.getFileHandle(parentDirHandle, targetName).pipe(
-    Effect.orElse(() => Opfs.getDirectoryHandle(parentDirHandle, targetName, { create: false })),
+  const opfs = yield* Opfs.Opfs
+  return yield* opfs.getFileHandle(parentDirHandle, targetName).pipe(
+    Effect.catch(() => opfs.getDirectoryHandle(parentDirHandle, targetName, { create: false })),
     Effect.as(true),
     Effect.catchTag('NotFoundError', () => Effect.succeed(false)),
   )
@@ -196,7 +203,8 @@ export const makeDirectory = Effect.fn('@livestore/utils:Opfs.makeDirectory')(fu
  * @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(
+  const opfs = yield* Opfs.Opfs
+  return yield* opfs.getFile(handle).pipe(
     Effect.map((file) => ({
       name: file.name,
       size: file.size,
@@ -217,7 +225,7 @@ export const getMetadata = Effect.fn('@livestore/utils:Opfs.getMetadata')(functi
  */
 export const writeFile = Effect.fn('@livestore/utils:Opfs.writeFile')(function* (path: string, data: Uint8Array) {
   if (isRootPath(path) === true) {
-    return yield* new OpfsError({
+    return yield* new Opfs.OpfsError({
       message: `Invalid OPFS path '${path}': cannot write file directly to the OPFS root`,
     })
   }
@@ -228,9 +236,10 @@ export const writeFile = Effect.fn('@livestore/utils:Opfs.writeFile')(function*
   return yield* Effect.scoped(
     Effect.gen(function* () {
       const parentDirHandle = yield* traverseDirectoryPath(parentSegments)
-      const fileHandle = yield* Opfs.getFileHandle(parentDirHandle, fileName, { create: true })
+      const opfs = yield* Opfs.Opfs
+      const fileHandle = yield* opfs.getFileHandle(parentDirHandle, fileName, { create: true })
 
-      yield* Opfs.writeFile(fileHandle, new Uint8Array(data), {
+      yield* opfs.writeFile(fileHandle, new Uint8Array(data), {
         keepExistingData: false,
       })
     }),
@@ -254,7 +263,7 @@ export const syncWriteFile = Effect.fn('@livestore/utils:Opfs.syncWriteFile')(fu
   data: Uint8Array,
 ) {
   if (isRootPath(path) === true) {
-    return yield* new OpfsError({
+    return yield* new Opfs.OpfsError({
       message: `Invalid OPFS path '${path}': cannot write file directly to the OPFS root`,
     })
   }
@@ -265,23 +274,24 @@ export const syncWriteFile = Effect.fn('@livestore/utils:Opfs.syncWriteFile')(fu
   return yield* Effect.scoped(
     Effect.gen(function* () {
       const parentDirHandle = yield* traverseDirectoryPath(parentSegments)
-      const fileHandle = yield* Opfs.getFileHandle(parentDirHandle, fileName, { create: true })
-      const syncHandle = yield* Opfs.createSyncAccessHandle(fileHandle)
+      const opfs = yield* Opfs.Opfs
+      const fileHandle = yield* opfs.getFileHandle(parentDirHandle, fileName, { create: true })
+      const syncHandle = yield* opfs.createSyncAccessHandle(fileHandle)
 
-      yield* Opfs.syncTruncate(syncHandle, 0)
+      yield* opfs.syncTruncate(syncHandle, 0)
 
       let offset = 0
       while (offset < data.byteLength) {
-        const wrote = yield* Opfs.syncWrite(syncHandle, data.subarray(offset), { at: offset })
+        const wrote = yield* opfs.syncWrite(syncHandle, data.subarray(offset), { at: offset })
         if (wrote === 0) {
-          return yield* new OpfsError({
+          return yield* new Opfs.OpfsError({
             message: `Short write: wrote ${offset} of ${data.byteLength} bytes.`,
           })
         }
         offset += Number(wrote)
       }
 
-      yield* Opfs.syncFlush(syncHandle)
+      yield* opfs.syncFlush(syncHandle)
     }),
   )
 })

package/src/browser/QuotaExceededError.ts

@@ -26,17 +26,22 @@ declare global {
      */
     readonly message: string
     /**
-     * A number representing the quota limit in bytes, or undefined.
+     * A number representing the quota limit in bytes, or null.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError/quota)
      */
-    readonly quota?: number
+    readonly quota: number | null
     /**
-     * A number representing the requested amount of storage in bytes, or undefined.
+     * A number representing the requested amount of storage in bytes, or null.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/QuotaExceededError/requested)
      */
-    readonly requested?: number
+    readonly requested: number | null
+  }
+
+  interface QuotaExceededErrorOptions {
+    quota?: number
+    requested?: number
   }
 
   /**
@@ -48,10 +53,8 @@ declare global {
    *
    * [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
+  var QuotaExceededError: {
+    prototype: QuotaExceededError
+    new (message?: string, options?: QuotaExceededErrorOptions): QuotaExceededError
+  }
 }

package/src/browser/WebChannelBrowser.ts

@@ -1,4 +1,4 @@
-import { Deferred, Exit, Scope } from 'effect'
+import { Cause, Deferred, Exit, Queue, Scope } from 'effect'
 
 import * as Effect from '../effect/Effect.ts'
 import * as Schema from '../effect/Schema/index.ts'
@@ -25,21 +25,26 @@ export const broadcastChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEn
 
       const channel = new BroadcastChannel(channelName)
 
-      yield* Effect.addFinalizer(() => Effect.try(() => channel.close()).pipe(Effect.ignoreLogged))
+      yield* Effect.addFinalizer(() =>
+        Effect.try({
+          try: () => channel.close(),
+          catch: (cause) => new Cause.UnknownError(cause),
+        }).pipe(Effect.ignore),
+      )
 
       const send = (message: MsgSend) =>
         Effect.gen(function* () {
-          const messageEncoded = yield* Schema.encode(schema.send)(message)
+          const messageEncoded = yield* Schema.encodeEffect(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)),
+        Stream.map((_) => Schema.decodeResult(schema.listen)(_.data)),
         listenToDebugPing(channelName),
       )
 
-      const closedDeferred = yield* Deferred.make<void>().pipe(Effect.acquireRelease(Deferred.done(Exit.void)))
+      const closedDeferred = yield* Effect.acquireRelease(Deferred.make<void>(), Deferred.done(Exit.void))
       const supportsTransferables = false
 
       return {
@@ -85,13 +90,22 @@ export const windowChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncod
         message: schema.listen,
         from: Schema.Literal(ids.other),
         to: Schema.Literal(ids.own),
-      }).annotations({ title: 'webmesh.WindowMessageListen' })
+      }).annotate({ title: 'webmesh.WindowMessageListen' })
 
       const WindowMessageSend = Schema.Struct({
         message: schema.send,
         from: Schema.Literal(ids.own),
         to: Schema.Literal(ids.other),
-      }).annotations({ title: 'webmesh.WindowMessageSend' })
+      }).annotate({ title: 'webmesh.WindowMessageSend' })
+
+      // `window.postMessage` can fire before a lazily-started stream has installed its listener.
+      // Buffer events from channel construction time so Effect v4 scheduling cannot drop them.
+      const messageQueue = yield* Effect.acquireRelease(Queue.unbounded<MessageEvent>(), Queue.shutdown)
+      const handler = (event: MessageEvent) => {
+        Queue.offerUnsafe(messageQueue, event)
+      }
+      listenWindow.addEventListener('message', handler)
+      yield* Effect.addFinalizer(() => Effect.sync(() => listenWindow.removeEventListener('message', handler)))
 
       const send = (message: MsgSend) =>
         Effect.gen(function* () {
@@ -105,16 +119,16 @@ export const windowChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncod
           sendWindow.postMessage(messageEncoded, targetOrigin, transferables)
         })
 
-      const listen = Stream.fromEventListener<MessageEvent>(listenWindow, 'message').pipe(
-        Stream.filter((_) => Schema.is(Schema.encodedSchema(WindowMessageListen))(_.data)),
+      const listen = Stream.fromQueue(messageQueue).pipe(
+        Stream.filter((_) => Schema.is(Schema.toEncoded(WindowMessageListen))(_.data)),
         Stream.map((_) => {
           debugInfo.listenTotal++
-          return Schema.decodeEither(schema.listen)(_.data.message)
+          return Schema.decodeResult(schema.listen)(_.data.message)
         }),
         listenToDebugPing('window'),
       )
 
-      const closedDeferred = yield* Deferred.make<void>().pipe(Effect.acquireRelease(Deferred.done(Exit.void)))
+      const closedDeferred = yield* Effect.acquireRelease(Deferred.make<void>(), Deferred.done(Exit.void))
       const supportsTransferables = true
 
       return {

package/src/browser/WebError.test.ts

@@ -7,7 +7,7 @@ Vitest.describe('parseWebError', () => {
     const domException = new DOMException('missing node', 'NotFoundError')
     const webError = new WebError.NotFoundError({ cause: domException })
 
-    const result = WebError.parseWebError(webError)
+    const result = WebError.classifyWebError(webError)
 
     Vitest.expect(result).toBeInstanceOf(WebError.NotFoundError)
     Vitest.expect(result.cause).toBe(domException)
@@ -16,7 +16,7 @@ Vitest.describe('parseWebError', () => {
   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])
+    const result = WebError.classifyWebError(nativeError, [WebError.TypeError])
 
     Vitest.expect(result).toBeInstanceOf(WebError.TypeError)
     Vitest.expect(result.cause).toBe(nativeError)
@@ -25,7 +25,7 @@ Vitest.describe('parseWebError', () => {
   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])
+    const result = WebError.classifyWebError(nativeError, [WebError.TypeError])
 
     Vitest.expect(result).toBeInstanceOf(WebError.UnknownError)
     Vitest.expect(result.cause).toBeInstanceOf(WebError.RangeError)
@@ -34,7 +34,7 @@ Vitest.describe('parseWebError', () => {
   Vitest.it('translates DOMException names into the matching WebError variant', () => {
     const domException = new DOMException('permission denied', 'NotAllowedError')
 
-    const result = WebError.parseWebError(domException, [WebError.NotAllowedError])
+    const result = WebError.classifyWebError(domException, [WebError.NotAllowedError])
 
     Vitest.expect(result).toBeInstanceOf(WebError.NotAllowedError)
     Vitest.expect(result.cause).toBe(domException)
@@ -43,7 +43,7 @@ Vitest.describe('parseWebError', () => {
   Vitest.it('produces UnknownError for non-error values with the default message', () => {
     const value = { reason: 'unexpected' }
 
-    const result = WebError.parseWebError(value)
+    const result = WebError.classifyWebError(value)
 
     Vitest.expect(result).toBeInstanceOf(WebError.UnknownError)
     Vitest.expect(result.cause).toBeDefined()
@@ -53,7 +53,7 @@ Vitest.describe('parseWebError', () => {
   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])
+    const result = WebError.classifyWebError(existing, [WebError.TypeError])
 
     Vitest.expect(result).toBeInstanceOf(WebError.UnknownError)