Align Queue and TxQueue APIs with unified completion semantics

packages/effect/src/Cause.ts

@@ -47,6 +47,7 @@ import type { Pipeable } from "./interfaces/Pipeable.ts"
 import * as core from "./internal/core.ts"
 import * as effect from "./internal/effect.ts"
 import * as ServiceMap from "./ServiceMap.ts"
+import type * as Pull from "./stream/Pull.ts"
 import type { Span } from "./Tracer.ts"
 import type { NoInfer } from "./types/Types.ts"
 
@@ -692,6 +693,79 @@ export interface NoSuchElementError extends YieldableError {
  */
 export const NoSuchElementError: new(message?: string) => NoSuchElementError = core.NoSuchElementError
 
+/**
+ * Tests if a value is a `Done` error.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ *
+ * console.log(Cause.isDone(Cause.Done)) // true
+ * console.log(Cause.isDone("not an error")) // false
+ * ```
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isDone: (u: unknown) => u is Done = core.isDone
+
+/**
+ * @since 4.0.0
+ * @category errors
+ */
+export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
+
+/**
+ * Represents a graceful completion signal for queues and streams.
+ *
+ * `Done` is used to signal that a queue or stream has completed normally
+ * and no more elements will be produced. This is distinct from an error
+ * or interruption - it represents successful completion.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import { Queue } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const queue = yield* Queue.bounded<number, Cause.Done>(10)
+ *
+ *   yield* Queue.offer(queue, 1)
+ *   yield* Queue.offer(queue, 2)
+ *
+ *   // Signal completion
+ *   yield* Queue.end(queue)
+ *
+ *   // Taking from ended queue fails with Done
+ *   const result = yield* Effect.flip(Queue.take(queue))
+ *   console.log(Cause.isDone(result)) // true
+ * })
+ * ```
+ *
+ * @since 4.0.0
+ * @category errors
+ */
+export interface Done extends Pull.Halt<void>, YieldableError {
+  readonly [DoneTypeId]: typeof DoneTypeId
+  readonly _tag: "Done"
+}
+
+/**
+ * Singleton instance of `Done` error to signal graceful completion.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ *
+ * console.log(Cause.Done._tag) // "Done"
+ * console.log(Cause.isDone(Cause.Done)) // true
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Done: Done = core.Done
+
 /**
  * @category errors
  * @since 4.0.0