@tranquilload/core 0.1.0

package/src/oneshot/index.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Cause, Effect, Exit } from "effect"
+import { AbortError } from "../errors/upload-error.js"
+import { compress } from "../pipeline/compress.js"
+import type { Transform } from "../pipeline/middleware.js"
+import { uploadOnce } from "./index.js"
+import type { UploadCompleted } from "../progress/upload-event.js"
+
+// Helper: read all events from the ReadableStream
+const readAllEvents = async <T>(rs: ReadableStream<T>): Promise<T[]> => {
+  const reader = rs.getReader()
+  const events: T[] = []
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    events.push(value)
+  }
+  return events
+}
+
+describe("uploadOnce — Dual API entry point", () => {
+  it.effect("success (plain void callback): events emits UploadCompleted, result resolves with UploadCompleted", () =>
+    Effect.gen(function* () {
+      const { events, result } = uploadOnce({
+        stream: new ReadableStream(),
+        upload: () => Promise.resolve(),
+      })
+
+      const [evts, res] = yield* Effect.all([
+        Effect.promise(() => readAllEvents(events)),
+        Effect.promise(() => result),
+      ])
+
+      expect(evts).toHaveLength(1)
+      expect(evts[0]!._tag).toBe("UploadCompleted")
+      expect((evts[0]! as UploadCompleted).totalParts).toBe(1)
+      expect(res._tag).toBe("UploadCompleted")
+      expect(res).toBe(evts[0]) // same object reference
+    })
+  )
+
+  it.effect("success (Promise callback): result resolves with UploadCompleted", () =>
+    Effect.gen(function* () {
+      let callCount = 0
+      const { result } = uploadOnce({
+        stream: new ReadableStream(),
+        upload: (_stream) => {
+          callCount++
+          return Promise.resolve()
+        },
+      })
+
+      const res = yield* Effect.promise(() => result)
+      expect(res._tag).toBe("UploadCompleted")
+      // Callback invoked exactly once (single-run guarantee)
+      expect(callCount).toBe(1)
+    })
+  )
+
+  it.effect("abort: result rejects with AbortError, events closes cleanly", () =>
+    Effect.gen(function* () {
+      const controller = new AbortController()
+      controller.abort()
+
+      const { events, result } = uploadOnce({
+        stream: new ReadableStream(),
+        upload: () => new Promise<void>(() => {}), // never resolves
+        signal: controller.signal,
+      })
+
+      // events closes cleanly — no error thrown to stream consumer
+      const evts = yield* Effect.promise(() => readAllEvents(events))
+      expect(evts).toHaveLength(0)
+
+      // result rejects with AbortError — use tryPromise to capture rejection as typed failure
+      const resultExit = yield* Effect.exit(
+        Effect.tryPromise({
+          try: () => result,
+          catch: (e) => e,
+        })
+      )
+      expect(Exit.isFailure(resultExit)).toBe(true)
+      if (Exit.isFailure(resultExit)) {
+        const errOption = Cause.failureOption(resultExit.cause)
+        expect(errOption._tag).toBe("Some")
+        const err = (errOption as { _tag: "Some"; value: unknown }).value
+        expect(err).toBeInstanceOf(AbortError)
+        expect((err as AbortError)._tag).toBe("AbortError")
+      }
+    })
+  )
+
+  it.effect("uploadOnce.effect returns a Stream (effect escape hatch)", () =>
+    Effect.gen(function* () {
+      // Calling .effect should not throw — returns a Stream (lazy, not executed)
+      const stream = uploadOnce.effect({
+        stream: new ReadableStream(),
+        upload: () => Promise.resolve(),
+      })
+      // Stream has a pipe method (duck-type check — we don't run it)
+      expect(typeof stream.pipe).toBe("function")
+    })
+  )
+
+  it.effect("applies plain Transform pipeline — upload callback receives transformed stream", () =>
+    Effect.gen(function* () {
+      let receivedStream: ReadableStream<Uint8Array> | undefined
+
+      // Pipeline that returns a known marker stream
+      const markerStream = new ReadableStream<Uint8Array>({ start(c) { c.close() } })
+      const pipeline: Transform = () => markerStream
+
+      const { result } = uploadOnce({
+        stream: new ReadableStream({ start(c) { c.close() } }),
+        pipeline,
+        upload: (s) => {
+          receivedStream = s
+          return Promise.resolve()
+        },
+      })
+
+      yield* Effect.promise(() => result)
+      // upload callback received the transformed stream (identity check)
+      expect(receivedStream).toBe(markerStream)
+    })
+  )
+
+  it.effect("applies Effect pipeline (compress) — upload callback receives compressed bytes", () =>
+    Effect.gen(function* () {
+      let receivedByteCount = 0
+      const original = new Uint8Array([1, 2, 3, 4, 5])
+
+      const { result } = uploadOnce({
+        stream: new ReadableStream({
+          start(c) { c.enqueue(original); c.close() },
+        }),
+        pipeline: compress("deflate-raw"),
+        upload: async (stream) => {
+          const reader = stream.getReader()
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            receivedByteCount += value.length
+          }
+        },
+      })
+
+      yield* Effect.promise(() => result)
+      // Compressed output is non-empty
+      expect(receivedByteCount).toBeGreaterThan(0)
+    })
+  )
+})

package/src/oneshot/index.ts

@@ -0,0 +1,76 @@
+import { Cause, Effect, Exit, Stream } from "effect"
+import type { UploadCompleted, UploadEvent } from "../progress/upload-event.js"
+import type { Transform } from "../pipeline/middleware.js"
+import { CompressionServiceLive } from "../services/compression-service.js"
+import { LoggerServiceLive } from "../services/logger-service.js"
+import { uploadOnceEffect, type UploadOnceOptions } from "./upload.js"
+
+export type UploadResult = UploadCompleted
+export type { UploadOnceOptions }
+
+export interface OneShotPublicOptions extends UploadOnceOptions {
+  readonly pipeline?: Transform | Effect.Effect<Transform, unknown, unknown>
+}
+
+export const uploadOnce = (
+  options: OneShotPublicOptions
+): {
+  events: ReadableStream<UploadEvent>
+  result: Promise<UploadResult>
+} => {
+  const collected: Promise<ReadonlyArray<UploadEvent>> = (async () => {
+    let processedStream = options.stream
+    if (options.pipeline !== undefined) {
+      if (typeof options.pipeline === "function") {
+        processedStream = options.pipeline(options.stream)
+      } else {
+        const transform = await Effect.runPromise(
+          Effect.provide(
+            options.pipeline as Effect.Effect<Transform, unknown, never>,
+            CompressionServiceLive
+          )
+        )
+        processedStream = transform(options.stream)
+      }
+    }
+
+    const program = uploadOnceEffect({ ...options, stream: processedStream }).pipe(
+      Stream.provideLayer(LoggerServiceLive)
+    )
+
+    const exit = await Stream.runCollect(program).pipe(
+      Effect.map((chunk) => Array.from(chunk)),
+      Effect.runPromiseExit
+    )
+    if (Exit.isSuccess(exit)) return exit.value
+    return Promise.reject(Cause.squash(exit.cause))
+  })()
+
+  // events: ReadableStream built from collected array; closes cleanly on error
+  const events = new ReadableStream<UploadEvent>({
+    async start(controller) {
+      try {
+        const evts = await collected
+        for (const event of evts) controller.enqueue(event)
+        controller.close()
+      } catch (_) {
+        // Close cleanly — abort/upload errors surface via `result` only
+        controller.close()
+      }
+    },
+  })
+
+  // result: resolves with UploadCompleted, rejects with UploadError on failure
+  const result: Promise<UploadResult> = collected.then((evts) => {
+    const last = evts[evts.length - 1]
+    if (last === undefined) {
+      return Promise.reject(new Error("uploadOnce: stream ended without emitting an event"))
+    }
+    return last as UploadResult
+  })
+
+  return { events, result }
+}
+
+// Effect escape hatch — LoggerService layer left open for user composition
+uploadOnce.effect = uploadOnceEffect

package/src/oneshot/upload.test.ts

@@ -0,0 +1,130 @@
+import { Cause, Effect, Exit, Fiber, Stream } from "effect"
+import { it, describe, expect } from "@effect/vitest"
+import { uploadOnceEffect } from "./upload.js"
+import { AbortError, CompleteUploadError } from "../errors/upload-error.js"
+import { LoggerServiceLive } from "../services/logger-service.js"
+import type { UploadCompleted } from "../progress/upload-event.js"
+
+const runStream = (opts: Parameters<typeof uploadOnceEffect>[0]) =>
+  Stream.runCollect(uploadOnceEffect(opts)).pipe(
+    Effect.provide(LoggerServiceLive),
+    Effect.exit
+  )
+
+describe("uploadOnceEffect", () => {
+  it.effect("emits UploadCompleted on success (plain value callback)", () =>
+    Effect.gen(function* () {
+      const mockStream = new ReadableStream()
+      const exit = yield* runStream({
+        stream: mockStream,
+        upload: () => undefined,
+      })
+      expect(Exit.isSuccess(exit)).toBe(true)
+      if (Exit.isSuccess(exit)) {
+        const events = Array.from(exit.value)
+        expect(events).toHaveLength(1)
+        expect(events[0]!._tag).toBe("UploadCompleted")
+        expect((events[0]! as UploadCompleted).totalParts).toBe(1)
+        expect(typeof events[0]!.timestamp).toBe("number")
+      }
+    })
+  )
+
+  it.effect("emits UploadCompleted on success (Promise callback)", () =>
+    Effect.gen(function* () {
+      const mockStream = new ReadableStream()
+      const exit = yield* runStream({
+        stream: mockStream,
+        upload: () => Promise.resolve(),
+      })
+      expect(Exit.isSuccess(exit)).toBe(true)
+      if (Exit.isSuccess(exit)) {
+        const events = Array.from(exit.value)
+        expect(events).toHaveLength(1)
+        expect(events[0]!._tag).toBe("UploadCompleted")
+        expect((events[0]! as UploadCompleted).totalParts).toBe(1)
+      }
+    })
+  )
+
+  it.effect("sync throw from callback → CompleteUploadError with correct cause", () =>
+    Effect.gen(function* () {
+      const originalError = new Error("network failure")
+      const exit = yield* runStream({
+        stream: new ReadableStream(),
+        upload: () => {
+          throw originalError
+        },
+      })
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const failure = Cause.failureOption(exit.cause)
+        expect(failure._tag).toBe("Some")
+        const err = (failure as { _tag: "Some"; value: unknown }).value
+        expect(err).toBeInstanceOf(CompleteUploadError)
+        expect((err as CompleteUploadError)._tag).toBe("CompleteUploadError")
+        expect((err as CompleteUploadError).cause).toBe(originalError)
+      }
+    })
+  )
+
+  it.effect("Promise rejection → CompleteUploadError with correct cause", () =>
+    Effect.gen(function* () {
+      const originalError = new Error("async failure")
+      const exit = yield* runStream({
+        stream: new ReadableStream(),
+        upload: () => Promise.reject(originalError),
+      })
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const failure = Cause.failureOption(exit.cause)
+        expect(failure._tag).toBe("Some")
+        const err = (failure as { _tag: "Some"; value: unknown }).value
+        expect(err).toBeInstanceOf(CompleteUploadError)
+        expect((err as CompleteUploadError)._tag).toBe("CompleteUploadError")
+        expect((err as CompleteUploadError).cause).toBe(originalError)
+      }
+    })
+  )
+
+  it.effect("abort mid-upload → AbortError with correct tag and message", () =>
+    Effect.gen(function* () {
+      const controller = new AbortController()
+      const fiber = yield* Effect.fork(
+        Stream.runCollect(
+          uploadOnceEffect({
+            stream: new ReadableStream(),
+            upload: () => new Promise<void>(() => {}), // never resolves
+            signal: controller.signal,
+          })
+        ).pipe(Effect.provide(LoggerServiceLive))
+      )
+      yield* Effect.sync(() => controller.abort())
+      const exit = yield* Fiber.await(fiber)
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const failure = Cause.failureOption(exit.cause)
+        expect(failure._tag).toBe("Some")
+        const err = (failure as { _tag: "Some"; value: unknown }).value
+        expect(err).toBeInstanceOf(AbortError)
+        expect((err as AbortError)._tag).toBe("AbortError")
+        expect((err as AbortError).message).toBe("Upload aborted")
+      }
+    })
+  )
+
+  it.effect("abort fires after upload completes → success (no spurious abort)", () =>
+    Effect.gen(function* () {
+      const controller = new AbortController()
+      const exit = yield* runStream({
+        stream: new ReadableStream(),
+        upload: () => Promise.resolve(),
+        signal: controller.signal,
+      })
+      // Abort after upload completes - should not affect the result
+      yield* Effect.sync(() => controller.abort())
+      expect(Exit.isSuccess(exit)).toBe(true)
+    })
+  )
+})

package/src/oneshot/upload.ts

@@ -0,0 +1,52 @@
+import { Effect, Stream } from "effect"
+import type { UploadError } from "../errors/upload-error.js"
+import { AbortError, CompleteUploadError } from "../errors/upload-error.js"
+import { LoggerService } from "../services/logger-service.js"
+import { fromAbortSignal } from "../utils/abort-interop.js"
+import { normalizeCallback } from "../utils/normalize-callback.js"
+import type { UploadEvent } from "../progress/upload-event.js"
+
+export interface UploadOnceOptions {
+  readonly stream: ReadableStream<Uint8Array>
+  readonly upload: (
+    stream: ReadableStream<Uint8Array>
+  ) => void | Promise<void> | Effect.Effect<void, UploadError>
+  readonly signal?: AbortSignal
+}
+
+export const uploadOnceEffect = (
+  options: UploadOnceOptions
+): Stream.Stream<UploadEvent, UploadError, LoggerService> => {
+  const { stream, upload, signal } = options
+
+  const program: Effect.Effect<UploadEvent, UploadError, LoggerService> = Effect.gen(
+    function* () {
+      const logger = yield* LoggerService
+      yield* Effect.sync(() => logger.log("info", "One-shot upload starting"))
+
+      const uploadEffect: Effect.Effect<void, UploadError> = normalizeCallback(
+        () => upload(stream)
+      ).pipe(
+        Effect.mapError((cause): UploadError => {
+          if (cause instanceof AbortError) return cause
+          return new CompleteUploadError(cause)
+        })
+      )
+
+      yield* signal
+        ? Effect.raceFirst(uploadEffect, fromAbortSignal(signal))
+        : uploadEffect
+
+      yield* Effect.sync(() => logger.log("info", "One-shot upload completed"))
+
+      return {
+        _tag: "UploadCompleted" as const,
+        uploadId: "",
+        totalParts: 1,
+        timestamp: Date.now(),
+      } satisfies UploadEvent
+    }
+  )
+
+  return Stream.fromEffect(program)
+}

package/src/pipeline/compress.test.ts

@@ -0,0 +1,69 @@
+import { it, describe, expect } from "@effect/vitest"
+import { Cause, Effect, Layer } from "effect"
+import { compress } from "./compress.js"
+import {
+  CompressionService,
+  CompressionServiceLive,
+  CompressionUnavailableError,
+} from "../services/compression-service.js"
+
+describe("compress", () => {
+  it.effect("uses custom CompressionService when provided", () =>
+    Effect.gen(function* () {
+      const marker = new ReadableStream<Uint8Array>()
+      let receivedAlgorithm = ""
+      const TestLayer = Layer.succeed(CompressionService, {
+        compress: (stream, algorithm) => {
+          receivedAlgorithm = algorithm
+          return marker
+        },
+      })
+      const transform = yield* Effect.provide(compress("deflate-raw"), TestLayer)
+      const input = new ReadableStream<Uint8Array>()
+      const result = transform(input)
+      expect(result).toBe(marker)
+      expect(receivedAlgorithm).toBe("deflate-raw")
+    })
+  )
+
+  it.effect("CompressionServiceLive produces compressed bytes (deflate-raw)", () =>
+    Effect.gen(function* () {
+      const transform = yield* Effect.provide(compress("deflate-raw"), CompressionServiceLive)
+      const input = new ReadableStream<Uint8Array>({
+        start(ctrl) {
+          ctrl.enqueue(new Uint8Array([1, 2, 3, 4]))
+          ctrl.close()
+        },
+      })
+      const compressed = transform(input)
+      const reader = compressed.getReader()
+      const chunks: Uint8Array[] = []
+      while (true) {
+        const { done, value } = yield* Effect.promise(() => reader.read())
+        if (done) break
+        chunks.push(value)
+      }
+      const totalBytes = chunks.reduce((acc, c) => acc + c.length, 0)
+      expect(totalBytes).toBeGreaterThan(0)
+    })
+  )
+
+  it.effect("fails with typed CompressionUnavailableError when CompressionStream is absent", () =>
+    Effect.gen(function* () {
+      const AbsentLayer: Layer.Layer<CompressionService, CompressionUnavailableError> =
+        Layer.effect(CompressionService, Effect.fail(new CompressionUnavailableError()))
+      const result = yield* Effect.exit(
+        Effect.provide(compress("deflate-raw"), AbsentLayer)
+      )
+      expect(result._tag).toBe("Failure")
+      if (result._tag === "Failure") {
+        const failure = Cause.failureOption(result.cause)
+        expect(failure._tag).toBe("Some")
+        if (failure._tag === "Some") {
+          expect(failure.value).toBeInstanceOf(CompressionUnavailableError)
+          expect(failure.value._tag).toBe("CompressionUnavailableError")
+        }
+      }
+    })
+  )
+})

package/src/pipeline/compress.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect"
+import { CompressionService } from "../services/compression-service.js"
+import type { Transform } from "./middleware.js"
+
+export const compress = (
+  algorithm: CompressionFormat = "deflate-raw"
+): Effect.Effect<Transform, never, CompressionService> =>
+  Effect.map(CompressionService, (svc) => (stream) => svc.compress(stream, algorithm))

package/src/pipeline/index.ts

@@ -0,0 +1,3 @@
+export type { Transform } from "./middleware.js"
+export { compose } from "./middleware.js"
+export { compress } from "./compress.js"

package/src/pipeline/middleware.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest"
+import { it as effectIt } from "@effect/vitest"
+import { Effect } from "effect"
+import { compose, type Transform } from "./middleware.js"
+import { compress } from "./compress.js"
+import { CompressionServiceLive } from "../services/compression-service.js"
+
+// Helper: creates a ReadableStream emitting a single Uint8Array chunk
+function makeStream(data: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(data)
+      controller.close()
+    }
+  })
+}
+
+// Helper: collects all chunks from a ReadableStream
+async function collect(stream: ReadableStream<Uint8Array>): Promise<Uint8Array[]> {
+  const reader = stream.getReader()
+  const chunks: Uint8Array[] = []
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    chunks.push(value)
+  }
+  return chunks
+}
+
+describe("compose", () => {
+  it("zero transforms: stream passes through unchanged", async () => {
+    const data = new Uint8Array([1, 2, 3])
+    const pipeline = compose()
+    const result = await collect(pipeline(makeStream(data)))
+    expect(result).toEqual([data])
+  })
+
+  it("single transform: applied to stream", async () => {
+    const data = new Uint8Array([1, 2, 3])
+    const double = (stream: ReadableStream<Uint8Array>) =>
+      new ReadableStream<Uint8Array>({
+        async start(controller) {
+          const chunks = await collect(stream)
+          for (const chunk of chunks) controller.enqueue(chunk.map(b => b * 2))
+          controller.close()
+        }
+      })
+    const result = await collect(compose(double)(makeStream(data)))
+    expect(result).toEqual([new Uint8Array([2, 4, 6])])
+  })
+
+  it("two transforms: applied left-to-right", async () => {
+    const order: string[] = []
+    const t1 = (stream: ReadableStream<Uint8Array>) => { order.push("t1"); return stream }
+    const t2 = (stream: ReadableStream<Uint8Array>) => { order.push("t2"); return stream }
+    compose(t1, t2)(makeStream(new Uint8Array([1])))
+    expect(order).toEqual(["t1", "t2"])
+  })
+
+  it("three transforms: applied left-to-right", async () => {
+    const order: string[] = []
+    const t1 = (stream: ReadableStream<Uint8Array>) => { order.push("t1"); return stream }
+    const t2 = (stream: ReadableStream<Uint8Array>) => { order.push("t2"); return stream }
+    const t3 = (stream: ReadableStream<Uint8Array>) => { order.push("t3"); return stream }
+    compose(t1, t2, t3)(makeStream(new Uint8Array([1])))
+    expect(order).toEqual(["t1", "t2", "t3"])
+  })
+
+  it("compose with plain transforms is still a plain Transform function", () => {
+    const t1: Transform = (s) => s
+    const t2: Transform = (s) => s
+    const composed = compose(t1, t2)
+    expect(typeof composed).toBe("function")
+  })
+
+  effectIt.effect("compose(compress()) returns an Effect that resolves to a working Transform", () =>
+    Effect.gen(function* () {
+      const transformEffect = compose(compress("deflate-raw"))
+      // Confirm it's an Effect (has .pipe method, not a function)
+      expect(typeof transformEffect).not.toBe("function")
+
+      // Resolve it with CompressionServiceLive
+      const transform = yield* Effect.provide(transformEffect, CompressionServiceLive)
+      expect(typeof transform).toBe("function")
+
+      // Apply the transform to a stream
+      const input = new ReadableStream<Uint8Array>({
+        start(c) { c.enqueue(new Uint8Array([1, 2, 3])); c.close() }
+      })
+      const output = transform(input)
+      const reader = output.getReader()
+      const chunks: Uint8Array[] = []
+      while (true) {
+        const { done, value } = yield* Effect.promise(() => reader.read())
+        if (done) break
+        chunks.push(value)
+      }
+      const totalBytes = chunks.reduce((acc, c) => acc + c.length, 0)
+      expect(totalBytes).toBeGreaterThan(0)
+    })
+  )
+})

package/src/pipeline/middleware.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect"
+
+export type Transform = (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>
+
+export function compose(): Transform
+export function compose(...transforms: Transform[]): Transform
+export function compose<E, R>(
+  ...transforms: Array<Transform | Effect.Effect<Transform, E, R>>
+): Effect.Effect<Transform, E, R>
+export function compose(
+  ...transforms: Array<Transform | Effect.Effect<Transform, any, any>>
+): Transform | Effect.Effect<Transform, any, any> {
+  const hasEffect = transforms.some((t) => typeof t !== "function")
+  if (!hasEffect || transforms.length === 0) {
+    return (stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> =>
+      (transforms as Transform[]).reduce((s, t) => t(s), stream)
+  }
+  return Effect.map(
+    Effect.all(
+      transforms.map((t) =>
+        typeof t === "function"
+          ? Effect.succeed(t as Transform)
+          : (t as Effect.Effect<Transform, any, any>)
+      )
+    ),
+    (resolved) =>
+      (stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> =>
+        resolved.reduce((s, t) => t(s), stream)
+  )
+}