@livestore/utils 0.4.0-dev.3 → 0.4.0-dev.6

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@livestore/utils",
-  "version": "0.4.0-dev.3",
+  "version": "0.4.0-dev.6",
   "type": "module",
   "sideEffects": [
-    "./src/global.ts"
+    "./src/global.ts",
+    "./dist/global.js"
   ],
   "exports": {
     ".": {
@@ -35,32 +36,32 @@
   },
   "dependencies": {
     "@standard-schema/spec": "1.0.0",
-    "msgpackr": "1.11.5",
     "nanoid": "5.1.5",
-    "pretty-bytes": "7.0.0"
+    "pretty-bytes": "7.0.1"
   },
   "devDependencies": {
-    "@effect/cli": "^0.69.0",
-    "@effect/cluster": "^0.46.2",
-    "@effect/experimental": "^0.54.3",
-    "@effect/opentelemetry": "^0.56.1",
-    "@effect/platform": "^0.90.0",
+    "@effect/ai": "^0.26.0",
+    "@effect/cli": "^0.69.2",
+    "@effect/cluster": "^0.48.2",
+    "@effect/experimental": "^0.54.6",
+    "@effect/opentelemetry": "0.56.4",
+    "@effect/platform": "^0.90.6",
     "@effect/platform-browser": "^0.70.0",
-    "@effect/platform-bun": "^0.77.0",
-    "@effect/platform-node": "^0.94.1",
+    "@effect/platform-bun": "^0.79.0",
+    "@effect/platform-node": "^0.96.0",
     "@effect/printer": "^0.45.0",
     "@effect/printer-ansi": "^0.45.0",
-    "@effect/rpc": "^0.68.3",
-    "@effect/sql": "^0.44.0",
+    "@effect/rpc": "^0.69.1",
+    "@effect/sql": "^0.44.2",
     "@effect/typeclass": "^0.36.0",
-    "@effect/vitest": "^0.25.0",
-    "@opentelemetry/api": "^1.9.0",
+    "@effect/vitest": "^0.25.1",
+    "@opentelemetry/api": "1.9.0",
     "@opentelemetry/resources": "^2.0.1",
-    "@types/bun": "^1.2.19",
+    "@types/bun": "^1.2.21",
     "@types/jsdom": "^21.1.7",
     "@types/node": "24.2.0",
-    "@types/web": "^0.0.260",
-    "effect": "^3.17.6",
+    "@types/web": "^0.0.264",
+    "effect": "3.17.9",
     "jsdom": "^26.1.0",
     "vitest": "3.2.4"
   },
@@ -71,28 +72,26 @@
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@effect/cli": "^0.69.0",
-    "@effect/cluster": "^0.46.2",
-    "@effect/experimental": "^0.54.3",
-    "@effect/opentelemetry": "^0.56.1",
-    "@effect/platform": "^0.90.0",
+    "@effect/ai": "^0.26.0",
+    "@effect/cli": "^0.69.2",
+    "@effect/cluster": "^0.48.2",
+    "@effect/experimental": "^0.54.6",
+    "@effect/opentelemetry": "^0.56.4",
+    "@effect/platform": "^0.90.6",
     "@effect/platform-browser": "^0.70.0",
-    "@effect/platform-bun": "^0.77.0",
-    "@effect/platform-node": "^0.94.1",
+    "@effect/platform-bun": "^0.79.0",
+    "@effect/platform-node": "^0.96.0",
     "@effect/printer": "^0.45.0",
     "@effect/printer-ansi": "^0.45.0",
-    "@effect/rpc": "^0.68.3",
-    "@effect/sql": "^0.44.0",
+    "@effect/rpc": "^0.69.1",
+    "@effect/sql": "^0.44.2",
     "@effect/typeclass": "^0.36.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/resources": "^2.0.1",
-    "effect": "^3.17.6"
+    "effect": "^3.17.9"
   },
   "publishConfig": {
-    "access": "public",
-    "sideEffects": [
-      "./dist/global.js"
-    ]
+    "access": "public"
   },
   "react-native": "./dist/index.js",
   "scripts": {

package/src/NoopTracer.ts

@@ -9,6 +9,7 @@ export const makeNoopSpan = () => {
     setAttribute: () => null,
     setAttributes: () => null,
     addEvent: () => null,
+    addLink: () => null,
     setStatus: () => null,
     updateName: () => null,
     recordException: () => null,

package/src/effect/Effect.ts

@@ -1,6 +1,18 @@
 import * as OtelTracer from '@effect/opentelemetry/Tracer'
-import type { Context, Duration, Stream } from 'effect'
-import { Cause, Deferred, Effect, Fiber, FiberRef, HashSet, Logger, pipe, Scope } from 'effect'
+import {
+  Cause,
+  type Context,
+  Deferred,
+  Duration,
+  Effect,
+  Fiber,
+  FiberRef,
+  HashSet,
+  Logger,
+  pipe,
+  Scope,
+  type Stream,
+} from 'effect'
 import type { UnknownException } from 'effect/Cause'
 import { log } from 'effect/Console'
 import type { LazyArg } from 'effect/Function'
@@ -166,7 +178,7 @@ export const logDuration =
       const start = Date.now()
       const res = yield* eff
       const end = Date.now()
-      yield* Effect.log(`${label}: ${end - start}ms`)
+      yield* Effect.log(`${label}: ${Duration.format(end - start)}`)
       return res
     })
 

package/src/effect/Error.ts

@@ -1,6 +1,6 @@
 import { Schema } from 'effect'
 
-export class UnknownError extends Schema.TaggedError<'UnknownError'>()('UnknownError', {
+export class UnknownError extends Schema.TaggedError<UnknownError>()('UnknownError', {
   cause: Schema.Any,
   payload: Schema.optional(Schema.Any),
 }) {}

package/src/effect/Logger.ts

@@ -8,20 +8,24 @@ const defaultDateFormat = (date: Date): string =>
     .toString()
     .padStart(2, '0')}.${date.getMilliseconds().toString().padStart(3, '0')}`
 
-export const prettyWithThread = (threadName: string) =>
+export const prettyWithThread = (threadName: string, options: { mode?: 'tty' | 'browser' } = {}) =>
   Logger.replace(
     Logger.defaultLogger,
     Logger.prettyLogger({
       formatDate: (date) => `${defaultDateFormat(date)} ${threadName}`,
+      mode: options.mode,
     }),
-    // consoleLogger(threadName),
   )
 
 export const consoleLogger = (threadName: string) =>
   Logger.make(({ message, annotations, date, logLevel, cause }) => {
+    const isCloudflareWorker = typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers'
     const consoleFn =
       logLevel === LogLevel.Debug
-        ? console.debug
+        ? // Cloudflare Workers doesn't support console.debug 🤷
+          isCloudflareWorker
+          ? console.log
+          : console.debug
         : logLevel === LogLevel.Info
           ? console.info
           : logLevel === LogLevel.Warning
@@ -35,5 +39,11 @@ export const consoleLogger = (threadName: string) =>
       messages.push(Cause.pretty(cause, { renderErrorCause: true }))
     }
 
-    consoleFn(`[${defaultDateFormat(date)} ${threadName}]`, ...messages, annotationsObj)
+    if (Object.keys(annotationsObj).length > 0) {
+      messages.push(annotationsObj)
+    }
+
+    consoleFn(`[${defaultDateFormat(date)} ${threadName}]`, ...messages)
   })
+
+export const consoleWithThread = (threadName: string) => Logger.replace(Logger.defaultLogger, consoleLogger(threadName))

package/src/effect/OtelTracer.ts

@@ -0,0 +1,11 @@
+import { makeExternalSpan } from '@effect/opentelemetry/Tracer'
+import type { Link as OtelSpanLink } from '@opentelemetry/api'
+import type { SpanLink as EffectSpanLink } from 'effect/Tracer'
+
+export * from '@effect/opentelemetry/Tracer'
+
+export const makeSpanLink = (otelSpanLink: OtelSpanLink): EffectSpanLink => ({
+  _tag: 'SpanLink',
+  span: makeExternalSpan(otelSpanLink.context),
+  attributes: otelSpanLink.attributes ?? {},
+})

package/src/effect/RpcClient.ts

@@ -0,0 +1,205 @@
+export * from '@effect/rpc/RpcClient'
+
+import { Socket } from '@effect/platform'
+import { RpcClient, RpcClientError, RpcSerialization } from '@effect/rpc'
+import { Protocol } from '@effect/rpc/RpcClient'
+import { constPing, type FromServerEncoded } from '@effect/rpc/RpcMessage'
+import { Cause, Deferred, Effect, Layer, Option, Schedule, type Scope } from 'effect'
+import { constVoid, identity } from 'effect/Function'
+import * as SubscriptionRef from './SubscriptionRef.ts'
+
+// This is based on `makeProtocolSocket` / `layerProtocolSocket` from `@effect/rpc` in order to:
+// - Add a `isConnected` subscription ref to track the connection state
+// - Add a ping schedule to the socket
+// - Add a retry schedule to the socket
+
+export const layerProtocolSocketWithIsConnected = (options: {
+  readonly url: string
+  readonly retryTransientErrors?: Schedule.Schedule<unknown> | undefined
+  readonly isConnected: SubscriptionRef.SubscriptionRef<boolean>
+  readonly pingSchedule?: Schedule.Schedule<unknown> | undefined
+}): Layer.Layer<Protocol, never, RpcSerialization.RpcSerialization | Socket.Socket> =>
+  Layer.scoped(Protocol, makeProtocolSocketWithIsConnected(options))
+
+export const makeProtocolSocketWithIsConnected = (options: {
+  readonly url: string
+  readonly retryTransientErrors?: Schedule.Schedule<unknown> | undefined
+  // CHANGED: add isConnected subscription ref
+  readonly isConnected: SubscriptionRef.SubscriptionRef<boolean>
+  // CHANGED: add ping schedule
+  readonly pingSchedule?: Schedule.Schedule<unknown> | undefined
+}): Effect.Effect<Protocol['Type'], never, Scope.Scope | RpcSerialization.RpcSerialization | Socket.Socket> =>
+  Protocol.make(
+    Effect.fnUntraced(function* (writeResponse) {
+      const socket = yield* Socket.Socket
+      const serialization = yield* RpcSerialization.RpcSerialization
+
+      const write = yield* socket.writer
+      const parser = serialization.unsafeMake()
+
+      const pinger = yield* makePinger(write(parser.encode(constPing)!), options?.pingSchedule)
+
+      yield* Effect.suspend(() => {
+        // CHANGED: don't reset parser on every message
+        // parser = serialization.unsafeMake()
+        pinger.reset()
+        return socket
+          .runRaw((message) => {
+            try {
+              const responses = parser.decode(message) as Array<FromServerEncoded>
+              if (responses.length === 0) return
+              let i = 0
+              return Effect.whileLoop({
+                while: () => i < responses.length,
+                body: () => {
+                  const response = responses[i++]!
+                  if (response._tag === 'Pong') {
+                    pinger.onPong()
+                  }
+                  return writeResponse(response).pipe(
+                    // CHANGED: set isConnected to true on pong
+                    Effect.tap(
+                      Effect.fn(function* () {
+                        if (options?.isConnected !== undefined) {
+                          yield* SubscriptionRef.set(options.isConnected, true)
+                        }
+                      }),
+                    ),
+                  )
+                },
+                step: constVoid,
+              })
+            } catch (defect) {
+              return writeResponse({
+                _tag: 'ClientProtocolError',
+                error: new RpcClientError.RpcClientError({
+                  reason: 'Protocol',
+                  message: 'Error decoding message',
+                  cause: Cause.fail(defect),
+                }),
+              })
+            }
+          })
+          .pipe(
+            Effect.raceFirst(
+              Effect.zipRight(
+                pinger.timeout,
+                Effect.fail(
+                  new Socket.SocketGenericError({
+                    reason: 'OpenTimeout',
+                    cause: new Error('ping timeout'),
+                  }),
+                ),
+              ),
+            ),
+          )
+      }).pipe(
+        Effect.zipRight(
+          Effect.fail(
+            new Socket.SocketCloseError({
+              reason: 'Close',
+              code: 1000,
+              closeReason: 'Closing connection',
+            }),
+          ),
+        ),
+        Effect.tapErrorCause(
+          Effect.fn(function* (cause) {
+            // CHANGED: set isConnected to false on error
+            if (options?.isConnected !== undefined) {
+              yield* SubscriptionRef.set(options.isConnected, false)
+            }
+
+            const error = Cause.failureOption(cause)
+            if (
+              options?.retryTransientErrors &&
+              Option.isSome(error) &&
+              (error.value.reason === 'Open' || error.value.reason === 'OpenTimeout')
+            ) {
+              return
+            }
+            // yield* Effect.logError('Error in socket', cause)
+            return yield* writeResponse({
+              _tag: 'ClientProtocolError',
+              error: new RpcClientError.RpcClientError({
+                reason: 'Protocol',
+                message: 'Error in socket',
+                cause: Cause.squash(cause),
+              }),
+            })
+          }),
+        ),
+        // CHANGED: make configurable via schedule
+        options?.retryTransientErrors ? Effect.retry(options.retryTransientErrors) : identity,
+        Effect.annotateLogs({
+          module: 'RpcClient',
+          method: 'makeProtocolSocket',
+        }),
+        Effect.interruptible,
+        Effect.ignore, // Errors are already handled
+        Effect.provide(Layer.setUnhandledErrorLogLevel(Option.none())),
+        Effect.forkScoped,
+      )
+
+      return {
+        send: (request) => {
+          const encoded = parser.encode(request)
+          if (encoded === undefined) return Effect.void
+
+          return Effect.orDie(write(encoded))
+        },
+        supportsAck: true,
+        supportsTransferables: false,
+        pinger,
+      }
+    }),
+  )
+
+export const SocketPinger = Effect.map(RpcClient.Protocol, (protocol) => (protocol as any).pinger as SocketPinger)
+
+export type SocketPinger = Effect.Effect.Success<ReturnType<typeof makePinger>>
+
+const makePinger = Effect.fnUntraced(function* <A, E, R>(
+  writePing: Effect.Effect<A, E, R>,
+  pingSchedule: Schedule.Schedule<unknown> = Schedule.spaced(10000).pipe(Schedule.addDelay(() => 5000)),
+) {
+  // CHANGED: add manual ping deferreds
+  const manualPingDeferreds = new Set<Deferred.Deferred<void, never>>()
+
+  let recievedPong = true
+  const latch = Effect.unsafeMakeLatch()
+  const reset = () => {
+    recievedPong = true
+    latch.unsafeClose()
+  }
+  const onPong = () => {
+    recievedPong = true
+    // CHANGED: mark all manual ping deferreds as done
+    for (const deferred of manualPingDeferreds) {
+      Deferred.unsafeDone(deferred, Effect.void)
+    }
+  }
+  yield* Effect.suspend(() => {
+    // Starting new ping
+    if (!recievedPong) return latch.open
+    recievedPong = false
+    return writePing
+  }).pipe(
+    // CHANGED: make configurable via schedule
+    Effect.schedule(pingSchedule),
+    Effect.ignore,
+    Effect.forever,
+    Effect.interruptible,
+    Effect.forkScoped,
+  )
+
+  // CHANGED: add manual ping
+  const ping = Effect.gen(function* () {
+    const deferred = yield* Deferred.make<void, never>()
+    manualPingDeferreds.add(deferred)
+    yield* deferred
+    manualPingDeferreds.delete(deferred)
+  })
+
+  return { timeout: latch.await, reset, onPong, ping } as const
+})

package/src/effect/Schema/index.ts

@@ -8,7 +8,6 @@ import { shouldNeverHappen } from '../../mod.ts'
 
 export * from 'effect/Schema'
 export * from './debug-diff.ts'
-export * from './msgpack.ts'
 
 // NOTE this is a temporary workaround until Effect schema has a better way to hash schemas
 // https://github.com/Effect-TS/effect/issues/2719

package/src/effect/Stream.test.ts

@@ -0,0 +1,127 @@
+import { Effect, Option, Stream } from 'effect'
+import { describe, expect, it } from 'vitest'
+import { concatWithLastElement, runCollectReadonlyArray } from './Stream.ts'
+
+describe('concatWithLastElement', () => {
+  it('should concatenate streams with access to last element of first stream', async () => {
+    const stream1 = Stream.make(1, 2, 3)
+    const result = concatWithLastElement(stream1, (lastElement) =>
+      lastElement.pipe(
+        Option.match({
+          onNone: () => Stream.make('no-previous'),
+          onSome: (last) => Stream.make(`last-was-${last}`, 'continuing'),
+        }),
+      ),
+    )
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual([1, 2, 3, 'last-was-3', 'continuing'])
+  })
+
+  it('should handle empty first stream', async () => {
+    const stream1 = Stream.empty
+    const result = concatWithLastElement(stream1, (lastElement) =>
+      lastElement.pipe(
+        Option.match({
+          onNone: () => Stream.make('no-previous-element'),
+          onSome: (last) => Stream.make(`last-was-${last}`),
+        }),
+      ),
+    )
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual(['no-previous-element'])
+  })
+
+  it('should handle single element first stream', async () => {
+    const stream1 = Stream.make('single')
+    const result = concatWithLastElement(stream1, (lastElement) =>
+      lastElement.pipe(
+        Option.match({
+          onNone: () => Stream.make('unexpected'),
+          onSome: (last) => Stream.make(`after-${last}`),
+        }),
+      ),
+    )
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual(['single', 'after-single'])
+  })
+
+  it('should handle empty second stream', async () => {
+    const stream1 = Stream.make(1, 2, 3)
+    const result = concatWithLastElement(stream1, () => Stream.empty)
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual([1, 2, 3])
+  })
+
+  it('should preserve error handling from first stream', async () => {
+    const stream1 = Stream.fail('first-error')
+    const result = concatWithLastElement(stream1, () => Stream.make('should-not-reach'))
+
+    const outcome = await Effect.runPromise(Effect.either(runCollectReadonlyArray(result)))
+    expect(outcome._tag).toBe('Left')
+    if (outcome._tag === 'Left') {
+      expect(outcome.left).toBe('first-error')
+    }
+  })
+
+  it('should preserve error handling from second stream', async () => {
+    const stream1 = Stream.make(1, 2)
+    const result = concatWithLastElement(stream1, () => Stream.fail('second-error'))
+
+    const outcome = await Effect.runPromise(Effect.either(runCollectReadonlyArray(result)))
+    expect(outcome._tag).toBe('Left')
+    if (outcome._tag === 'Left') {
+      expect(outcome.left).toBe('second-error')
+    }
+  })
+
+  it('should work with different types in streams', async () => {
+    const stream1 = Stream.make(1, 2, 3)
+    const result = concatWithLastElement(stream1, (lastElement) =>
+      lastElement.pipe(
+        Option.match({
+          onNone: () => Stream.make('no-number') as Stream.Stream<number | string, never, never>,
+          onSome: (last) => Stream.make(last * 10, last * 100),
+        }),
+      ),
+    )
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual([1, 2, 3, 30, 300])
+  })
+
+  it('should handle async effects in streams', async () => {
+    const stream1 = Stream.fromEffect(Effect.succeed('async-value'))
+    const result = concatWithLastElement(stream1, (lastElement) =>
+      lastElement.pipe(
+        Option.match({
+          onNone: () => Stream.fromEffect(Effect.succeed('no-async')),
+          onSome: (last) => Stream.fromEffect(Effect.succeed(`processed-${last}`)),
+        }),
+      ),
+    )
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual(['async-value', 'processed-async-value'])
+  })
+
+  it('should work with dual function - piped style', async () => {
+    const stream1 = Stream.make('a', 'b', 'c')
+    const result = stream1.pipe(
+      concatWithLastElement((lastElement) =>
+        lastElement.pipe(
+          Option.match({
+            onNone: () => Stream.make('no-last'),
+            onSome: (last) => Stream.make(`last-${last}`, 'done'),
+          }),
+        ),
+      ),
+    )
+
+    const collected = await Effect.runPromise(runCollectReadonlyArray(result))
+    expect(collected).toEqual(['a', 'b', 'c', 'last-c', 'done'])
+  })
+})

package/src/effect/Stream.ts

@@ -1,7 +1,8 @@
+/** biome-ignore-all lint/suspicious/useIterableCallbackReturn: Biome bug */
 export * from 'effect/Stream'
 
-import type { Chunk } from 'effect'
-import { Effect, Option, pipe, Ref, Stream } from 'effect'
+import { type Cause, Chunk, Effect, Option, pipe, Ref, Stream } from 'effect'
+import { dual } from 'effect/Function'
 
 export const tapLog = <R, E, A>(stream: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>
   tapChunk<never, never, A, void>(Effect.forEach((_) => Effect.succeed(console.log(_))))(stream)
@@ -61,3 +62,111 @@ export const skipRepeated_ = <R, E, A>(
       ),
     ),
   )
+
+/**
+ * Returns the first element of the stream or `None` if the stream is empty.
+ * It's different than `Stream.runHead` which runs the stream to completion.
+ * */
+export const runFirst = <A, E, R>(stream: Stream.Stream<A, E, R>): Effect.Effect<Option.Option<A>, E, R> =>
+  stream.pipe(Stream.take(1), Stream.runCollect, Effect.map(Chunk.head))
+
+/**
+ * Returns the first element of the stream or throws a `NoSuchElementException` if the stream is empty.
+ * It's different than `Stream.runHead` which runs the stream to completion.
+ * */
+export const runFirstUnsafe = <A, E, R>(
+  stream: Stream.Stream<A, E, R>,
+): Effect.Effect<A, Cause.NoSuchElementException | E, R> => runFirst(stream).pipe(Effect.flatten)
+
+export const runCollectReadonlyArray = <A, E, R>(stream: Stream.Stream<A, E, R>): Effect.Effect<readonly A[], E, R> =>
+  stream.pipe(Stream.runCollect, Effect.map(Chunk.toReadonlyArray))
+
+/**
+ * Concatenates two streams where the second stream has access to the last element
+ * of the first stream as an `Option`. If the first stream is empty, the callback
+ * receives `Option.none()`.
+ *
+ * @param stream - The first stream to consume
+ * @param getStream2 - Function that receives the last element from the first stream
+ *   and returns the second stream to concatenate
+ * @returns A new stream containing all elements from both streams
+ *
+ * @example
+ * ```ts
+ * // Direct usage
+ * const result = concatWithLastElement(
+ *   Stream.make(1, 2, 3),
+ *   lastElement => lastElement.pipe(
+ *     Option.match({
+ *       onNone: () => Stream.make('empty'),
+ *       onSome: last => Stream.make(`last-was-${last}`)
+ *     })
+ *   )
+ * )
+ *
+ * // Piped usage
+ * const result = Stream.make(1, 2, 3).pipe(
+ *   concatWithLastElement(lastElement =>
+ *     Stream.make(lastElement.pipe(Option.getOrElse(() => 0)) * 10)
+ *   )
+ * )
+ * ```
+ */
+export const concatWithLastElement: {
+  <A1, A2, E2, R2>(
+    getStream2: (lastElement: Option.Option<A1>) => Stream.Stream<A2, E2, R2>,
+  ): <E1, R1>(stream: Stream.Stream<A1, E1, R1>) => Stream.Stream<A1 | A2, E1 | E2, R1 | R2>
+  <A1, E1, R1, A2, E2, R2>(
+    stream: Stream.Stream<A1, E1, R1>,
+    getStream2: (lastElement: Option.Option<A1>) => Stream.Stream<A2, E2, R2>,
+  ): Stream.Stream<A1 | A2, E1 | E2, R1 | R2>
+} = dual(
+  2,
+  <A1, E1, R1, A2, E2, R2>(
+    stream1: Stream.Stream<A1, E1, R1>,
+    getStream2: (lastElement: Option.Option<A1>) => Stream.Stream<A2, E2, R2>,
+  ): Stream.Stream<A1 | A2, E1 | E2, R1 | R2> =>
+    pipe(
+      Ref.make<Option.Option<A1>>(Option.none()),
+      Stream.fromEffect,
+      Stream.flatMap((lastRef) =>
+        pipe(
+          stream1,
+          Stream.tap((value) => Ref.set(lastRef, Option.some(value))),
+          Stream.concat(pipe(Ref.get(lastRef), Effect.map(getStream2), Stream.unwrap)),
+        ),
+      ),
+    ),
+)
+
+/**
+ * Emits a default value if the stream is empty, otherwise passes through all elements.
+ * Uses `concatWithLastElement` internally to detect if the stream was empty.
+ *
+ * @param fallbackValue - The value to emit if the stream is empty
+ * @returns A dual function that can be used in pipe or direct call
+ *
+ * @example
+ * ```ts
+ * // Direct usage
+ * const result = emitIfEmpty(Stream.empty, 'default')
+ * // Emits: 'default'
+ *
+ * // Piped usage
+ * const result = Stream.make(1, 2, 3).pipe(emitIfEmpty('fallback'))
+ * // Emits: 1, 2, 3
+ *
+ * const empty = Stream.empty.pipe(emitIfEmpty('fallback'))
+ * // Emits: 'fallback'
+ * ```
+ */
+export const emitIfEmpty: {
+  <A>(fallbackValue: A): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<A, E, R>
+  <A, E, R>(stream: Stream.Stream<A, E, R>, fallbackValue: A): Stream.Stream<A, E, R>
+} = dual(
+  2,
+  <A, E, R>(stream: Stream.Stream<A, E, R>, fallbackValue: A): Stream.Stream<A, E, R> =>
+    concatWithLastElement(stream, (lastElement) =>
+      lastElement._tag === 'None' ? Stream.make(fallbackValue) : Stream.empty,
+    ),
+)