@tranquilload/adapters 0.1.0

package/src/resilience/optimal-part-size.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { computeOptimalPartSize } from './optimal-part-size.js'
+
+const MB = 1024 * 1024
+
+describe('computeOptimalPartSize', () => {
+  it('returns minPartSize when totalBytes is undefined', () => {
+    expect(
+      computeOptimalPartSize({
+        totalBytes: undefined,
+        targetPartCount: 10,
+        minPartSize: 5 * MB,
+      })
+    ).toBe(5 * MB)
+  })
+
+  it('returns optimal size when raw > minPartSize (AC1: 100MB / 10 = 10MB > 5MB)', () => {
+    expect(
+      computeOptimalPartSize({
+        totalBytes: 100 * MB,
+        targetPartCount: 10,
+        minPartSize: 5 * MB,
+      })
+    ).toBe(10 * MB)
+  })
+
+  it('returns minPartSize when file is too small (AC2: totalBytes/targetPartCount < minPartSize)', () => {
+    expect(
+      computeOptimalPartSize({
+        totalBytes: 8 * MB,
+        targetPartCount: 10,
+        minPartSize: 5 * MB,
+      })
+    ).toBe(5 * MB)
+  })
+
+  it('clamps to maxPartSize when raw part size exceeds max', () => {
+    expect(
+      computeOptimalPartSize({
+        totalBytes: 100 * MB,
+        targetPartCount: 2,
+        minPartSize: 5 * MB,
+        maxPartSize: 20 * MB,
+      })
+    ).toBe(20 * MB)
+  })
+
+  it('returns exact value when totalBytes / targetPartCount === minPartSize', () => {
+    expect(
+      computeOptimalPartSize({
+        totalBytes: 50 * MB,
+        targetPartCount: 10,
+        minPartSize: 5 * MB,
+      })
+    ).toBe(5 * MB)
+  })
+})

package/src/resilience/optimal-part-size.ts

@@ -0,0 +1,34 @@
+/**
+ * Optimal part size calculator for multipart uploads.
+ *
+ * Pure function — computes the ideal chunk size given file size,
+ * target part count, and protocol constraints (min/max part size).
+ *
+ * @module
+ */
+
+export interface OptimalPartSizeOptions {
+  /** Total file size in bytes. Pass `undefined` if unknown (streaming). */
+  totalBytes?: number
+  /** Desired number of parts. */
+  targetPartCount: number
+  /** Protocol minimum part size (e.g. 5 * 1024 * 1024 for S3). Always returned as floor. */
+  minPartSize: number
+  /** Optional maximum part size. Clamps result if provided. */
+  maxPartSize?: number
+}
+
+export function computeOptimalPartSize(options: OptimalPartSizeOptions): number {
+  const { totalBytes, targetPartCount, minPartSize, maxPartSize } = options
+
+  if (totalBytes === undefined) return minPartSize
+
+  const raw = Math.ceil(totalBytes / targetPartCount)
+  let result = Math.max(raw, minPartSize)
+
+  if (maxPartSize !== undefined) {
+    result = Math.min(result, maxPartSize)
+  }
+
+  return result
+}

package/src/sources/from-file.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { fromFile } from './from-file.js'
+
+describe('fromFile', () => {
+  it('returns totalBytes equal to file.size', () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5])
+    const file = new File([bytes], 'test.bin', { type: 'application/octet-stream' })
+
+    const result = fromFile(file)
+
+    expect(result.totalBytes).toBe(5)
+  })
+
+  it('stream yields all file bytes', async () => {
+    const bytes = new Uint8Array([10, 20, 30, 40])
+    const file = new File([bytes], 'test.bin')
+
+    const { stream } = fromFile(file)
+
+    const reader = stream.getReader()
+    const chunks: Uint8Array[] = []
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(value)
+    }
+
+    const all = new Uint8Array(chunks.reduce((acc, c) => acc + c.length, 0))
+    let offset = 0
+    for (const chunk of chunks) {
+      all.set(chunk, offset)
+      offset += chunk.length
+    }
+
+    expect(Array.from(all)).toEqual([10, 20, 30, 40])
+  })
+})

package/src/sources/from-file.ts

@@ -0,0 +1,6 @@
+export function fromFile(file: File): { stream: ReadableStream<Uint8Array>; totalBytes: number } {
+  return {
+    stream: file.stream(),
+    totalBytes: file.size,
+  }
+}

package/src/sources/from-node-readable.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest"
+import { Readable } from "node:stream"
+import { fromNodeReadable } from "./from-node-readable.js"
+
+describe("fromNodeReadable", () => {
+  it("streams all bytes from a Node Readable", async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5])
+    const readable = Readable.from([Buffer.from(bytes)])
+
+    const webStream = fromNodeReadable(readable)
+
+    const reader = webStream.getReader()
+    const chunks: Uint8Array[] = []
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(value)
+    }
+
+    const totalLength = chunks.reduce((n, c) => n + c.length, 0)
+    const all = new Uint8Array(totalLength)
+    let offset = 0
+    for (const chunk of chunks) {
+      all.set(chunk, offset)
+      offset += chunk.length
+    }
+
+    expect(Array.from(all)).toEqual([1, 2, 3, 4, 5])
+  })
+
+  it("propagates Readable errors to the ReadableStream", async () => {
+    const readable = new Readable({
+      read() {
+        this.emit("error", new Error("read failure"))
+      },
+    })
+
+    const webStream = fromNodeReadable(readable)
+    const reader = webStream.getReader()
+
+    await expect(reader.read()).rejects.toThrow("read failure")
+  })
+})

package/src/sources/from-node-readable.ts

@@ -0,0 +1,5 @@
+import { Readable } from "node:stream"
+
+export function fromNodeReadable(readable: Readable): ReadableStream<Uint8Array> {
+  return Readable.toWeb(readable) as ReadableStream<Uint8Array>
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: {
+    'from-file': 'src/sources/from-file.ts',
+    'from-node-readable': 'src/sources/from-node-readable.ts',
+    's3-multipart-upload': 'src/protocols/s3-multipart-upload.ts',
+    'simple-http-upload': 'src/protocols/simple-http-upload.ts',
+    'network-multiplier': 'src/resilience/network-multiplier.ts',
+    'optimal-part-size': 'src/resilience/optimal-part-size.ts',
+  },
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+})

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config'
+import path from 'path'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@tranquilload/core': path.resolve(__dirname, '../tranquilload-core/src'),
+    },
+  },
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+})