@velajs/storage 0.3.1 → 0.3.2

package/dist/index.js

@@ -1,16 +1,1078 @@
-// Public surface of @velajs/storage (the `.` entry).
-// NOTE: drivers live behind their own subpaths (`./drivers/*`) so importing
-// the contract/module never pulls `aws4fetch` or a specific backend.
-// --- Facade ---------------------------------------------------------------
-export { Storage, createStorage } from "./storage.facade.js";
-// --- DI: module / service / tokens / decorator ----------------------------
-export { StorageModule } from "./storage.module.js";
-export { StorageService, lazyDriver } from "./storage.service.js";
-export { InjectStorage } from "./decorators/inject-storage.decorator.js";
-export { DEFAULT_STORAGE_NAME, storageDriverBuilder, storageToken } from "./storage.tokens.js";
-// --- HTTP controller (P1) ---
-export { createStorageController } from "./storage.controller.js";
-// --- Errors ---------------------------------------------------------------
-export { StorageError, isAbort } from "./storage.error.js";
-// --- Key helpers ----------------------------------------------------------
-export { isSafeKey, sanitizeKey, normalizePrefix, joinKey, stripPrefix } from "./object-key.js";
+import { a as isStream, i as countingStream, n as chunkStream, s as toStream, t as byteLengthOf } from "./body-BMUcBeQ0.js";
+import { n as isAbort, t as StorageError } from "./storage.error-DVCOkJhc.js";
+import { n as runWithRetry, t as normalizeRetry } from "./retry-DXtO6R9D.js";
+import { Controller, Get, Inject, Injectable, InjectionToken, Post, Req, defineModule, lazyProvider, stableHash } from "@velajs/vela";
+//#region src/object-key.ts
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/**
+* True when `key` is a safe object key:
+* - non-empty, not longer than 1024 bytes (S3's limit)
+* - no leading `/`
+* - no `.` / `..` path segments (traversal)
+* - no control characters
+* - no backslashes (Windows-style separators)
+*/
+function isSafeKey(key) {
+	if (typeof key !== "string" || key.length === 0 || key.length > 1024) return false;
+	if (key.startsWith("/")) return false;
+	if (key.includes("\\")) return false;
+	if (CONTROL_CHARS.test(key)) return false;
+	for (const segment of key.split("/")) if (segment === "." || segment === "..") return false;
+	return true;
+}
+/** Return `key` if safe, else throw `StorageError('InvalidKey')`. */
+function sanitizeKey(key) {
+	if (!isSafeKey(key)) throw new StorageError("InvalidKey", `unsafe object key: ${JSON.stringify(key)}`);
+	return key;
+}
+/** Normalize a prefix: drop leading/trailing slashes, collapse to '' when empty. */
+function normalizePrefix(prefix) {
+	if (!prefix) return "";
+	return prefix.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+/** Join a normalized prefix and a key with a single '/'. */
+function joinKey(prefix, key) {
+	return prefix ? `${prefix}/${key}` : key;
+}
+/** Strip a normalized prefix from a stored key (for surfacing to callers). */
+function stripPrefix(prefix, key) {
+	if (!prefix) return key;
+	const withSlash = `${prefix}/`;
+	return key.startsWith(withSlash) ? key.slice(withSlash.length) : key;
+}
+//#endregion
+//#region src/storage.facade.ts
+const DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+const DEFAULT_CONCURRENCY = 4;
+const MULTIPART_THRESHOLD = 16 * 1024 * 1024;
+/**
+* The consumer-facing storage handle. Wraps a {@link StorageDriver} with
+* capability-gating (throws before any driver call), retry/timeout/abort,
+* prefix scoping, generic `move`/`deleteMany` fallbacks, multipart
+* orchestration, progress synthesis, and observability hooks.
+*
+* Framework-free — `StorageService` builds and caches one of these per bucket.
+*/
+var Storage = class Storage {
+	#driver;
+	#prefix;
+	#readonly;
+	#opts;
+	constructor(opts) {
+		this.#opts = opts;
+		this.#driver = opts.driver;
+		this.#prefix = normalizePrefix(opts.prefix);
+		this.#readonly = opts.readonly ?? false;
+	}
+	get raw() {
+		return this.#driver.raw;
+	}
+	get driver() {
+		return this.#driver;
+	}
+	get capabilities() {
+		const d = this.#driver;
+		return {
+			rangeRead: !!d.supportsRange,
+			uploadProgress: !!d.reportsUploadProgress,
+			delimiter: !!d.supportsDelimiter,
+			metadata: !!d.supportsMetadata,
+			cacheControl: !!d.supportsCacheControl,
+			serverSideCopy: !!d.supportsServerSideCopy,
+			multipart: typeof d.createMultipartUpload === "function",
+			signedMultipart: d.signedMultipart != null,
+			signedUrl: d.signedUrl ?? {
+				supported: false,
+				upload: false
+			}
+		};
+	}
+	async upload(key, body, opts) {
+		this.#assertWritable();
+		this.#assertUploadSupported(opts);
+		const d = this.#driver;
+		const path = this.#path(key);
+		const len = byteLengthOf(body);
+		const wantsMultipart = opts?.multipart != null && opts.multipart !== false;
+		const unknownStream = isStream(body) && len === void 0;
+		const bigKnown = len != null && len > MULTIPART_THRESHOLD;
+		const canMultipart = typeof d.createMultipartUpload === "function";
+		if (wantsMultipart && !canMultipart) throw new StorageError("Unsupported", `${d.name}: multipart not supported`);
+		if ((wantsMultipart || unknownStream || bigKnown) && canMultipart) return {
+			...await this.#exec("upload", key, false, opts, () => this.#putMultipart(path, body, opts)),
+			key
+		};
+		const streaming = isStream(body);
+		let outBody = body;
+		if (opts?.onProgress && !d.reportsUploadProgress && streaming) outBody = countingStream(body, (loaded) => opts.onProgress({
+			loaded,
+			total: len
+		}));
+		const result = await this.#exec("upload", key, !streaming, opts, (signal) => d.upload(path, outBody, {
+			...opts,
+			signal
+		}));
+		if (opts?.onProgress && !d.reportsUploadProgress && !streaming && len != null) opts.onProgress({
+			loaded: len,
+			total: len
+		});
+		return {
+			...result,
+			key
+		};
+	}
+	async #putMultipart(path, body, opts) {
+		const mp = typeof opts?.multipart === "object" ? opts.multipart : {};
+		const partSize = mp.partSize ?? DEFAULT_PART_SIZE;
+		const concurrency = Math.max(1, mp.concurrency ?? DEFAULT_CONCURRENCY);
+		const total = byteLengthOf(body);
+		const upload = await this.#driver.createMultipartUpload(path, {
+			contentType: opts?.contentType,
+			cacheControl: opts?.cacheControl,
+			metadata: opts?.metadata,
+			signal: opts?.signal
+		});
+		try {
+			const parts = [];
+			let uploadedBytes = 0;
+			let partNumber = 0;
+			const inflight = /* @__PURE__ */ new Set();
+			for await (const chunk of chunkStream(toStream(body), partSize)) {
+				partNumber += 1;
+				const n = partNumber;
+				const size = chunk.byteLength;
+				const tracked = (async () => {
+					const up = await upload.uploadPart(n, chunk, { signal: opts?.signal });
+					parts[n - 1] = {
+						partNumber: n,
+						etag: up.etag,
+						size: up.size ?? size
+					};
+					uploadedBytes += size;
+					opts?.onProgress?.({
+						loaded: uploadedBytes,
+						total
+					});
+				})().finally(() => inflight.delete(tracked));
+				inflight.add(tracked);
+				if (inflight.size >= concurrency) await Promise.race(inflight);
+			}
+			await Promise.all(inflight);
+			return await upload.complete(parts, { signal: opts?.signal });
+		} catch (e) {
+			await upload.abort().catch(() => {});
+			throw StorageError.wrap(e);
+		}
+	}
+	async download(key, opts) {
+		if (opts?.range) this.#assertRange();
+		const file = await this.#exec("download", key, true, opts, (signal) => this.#driver.download(this.#path(key), {
+			...opts,
+			signal
+		}));
+		return this.#relabel(file, key);
+	}
+	async head(key, opts) {
+		const file = await this.#exec("head", key, true, opts, (signal) => this.#driver.head(this.#path(key), {
+			...opts,
+			signal
+		}));
+		return this.#relabel(file, key);
+	}
+	exists(key, opts) {
+		return this.#exec("exists", key, true, opts, (signal) => this.#driver.exists(this.#path(key), {
+			...opts,
+			signal
+		}));
+	}
+	async delete(keyOrKeys, opts) {
+		this.#assertWritable();
+		if (Array.isArray(keyOrKeys)) return this.#deleteMany(keyOrKeys, opts);
+		const key = keyOrKeys;
+		return this.#exec("delete", key, true, opts, (signal) => this.#driver.delete(this.#path(key), {
+			...opts,
+			signal
+		}));
+	}
+	async #deleteMany(keys, opts) {
+		const d = this.#driver;
+		if (d.deleteMany) {
+			const res = await this.#exec("deleteMany", void 0, true, opts, (signal) => d.deleteMany(keys.map((k) => this.#path(k)), {
+				...opts,
+				signal
+			}));
+			return {
+				deleted: res.deleted.map((k) => this.#strip(k)),
+				errors: res.errors?.map((e) => ({
+					key: this.#strip(e.key),
+					error: e.error
+				}))
+			};
+		}
+		const concurrency = Math.max(1, opts?.concurrency ?? 8);
+		const stopOnError = opts?.stopOnError ?? false;
+		const deleted = [];
+		const errors = [];
+		let index = 0;
+		let stopped = false;
+		const worker = async () => {
+			while (index < keys.length && !stopped) {
+				const key = keys[index++];
+				try {
+					await d.delete(this.#path(key), { signal: opts?.signal });
+					deleted.push(key);
+				} catch (e) {
+					const error = StorageError.wrap(e);
+					errors.push({
+						key,
+						error
+					});
+					if (stopOnError) {
+						stopped = true;
+						throw error;
+					}
+				}
+			}
+		};
+		const runners = Array.from({ length: Math.min(concurrency, keys.length) }, worker);
+		if (stopOnError) await Promise.all(runners);
+		else await Promise.allSettled(runners);
+		return {
+			deleted,
+			errors: errors.length ? errors : void 0
+		};
+	}
+	async copy(from, to, opts) {
+		this.#assertWritable();
+		return this.#exec("copy", to, true, opts, (signal) => this.#driver.copy(this.#path(from), this.#path(to), {
+			...opts,
+			signal
+		}));
+	}
+	async move(from, to, opts) {
+		this.#assertWritable();
+		const f = this.#path(from);
+		const t = this.#path(to);
+		if (f === t) return;
+		if (this.#driver.move) {
+			await this.#exec("move", to, true, opts, (signal) => this.#driver.move(f, t, {
+				...opts,
+				signal
+			}));
+			return;
+		}
+		await this.#exec("move", to, true, opts, async (signal) => {
+			await this.#driver.copy(f, t, {
+				...opts,
+				signal
+			});
+			await this.#driver.delete(f, {
+				...opts,
+				signal
+			});
+		});
+	}
+	async list(opts) {
+		if (opts?.delimiter) this.#assertDelimiter();
+		const scopedPrefix = this.#listPrefix(opts?.prefix);
+		const res = await this.#exec("list", void 0, true, opts, (signal) => this.#driver.list({
+			...opts,
+			prefix: scopedPrefix,
+			signal
+		}));
+		return {
+			items: res.items.map((f) => this.#relabel(f, this.#strip(f.key))),
+			prefixes: res.prefixes?.map((p) => this.#strip(p)),
+			cursor: res.cursor
+		};
+	}
+	async *listAll(opts) {
+		let cursor = opts?.cursor;
+		do {
+			const page = await this.list({
+				...opts,
+				cursor
+			});
+			for (const item of page.items) yield item;
+			cursor = page.cursor;
+		} while (cursor);
+	}
+	async url(key, opts) {
+		if (!this.#driver.signedUrl?.supported) throw new StorageError("Unsupported", `${this.#driver.name}: url() not supported`);
+		return this.#exec("url", key, true, opts, (signal) => this.#driver.url(this.#path(key), {
+			...opts,
+			signal
+		}));
+	}
+	async signedUploadUrl(key, opts) {
+		this.#assertWritable();
+		if (!this.#driver.signedUrl?.upload) throw new StorageError("Unsupported", `${this.#driver.name}: signed uploads not supported`);
+		return this.#exec("signedUploadUrl", key, true, opts, (signal) => this.#driver.signedUploadUrl(this.#path(key), {
+			...opts,
+			signal
+		}));
+	}
+	/** Prefix-bound view of the driver's presigned-multipart capability. */
+	get signedMultipart() {
+		const cap = this.#driver.signedMultipart;
+		if (!cap) return void 0;
+		const path = (k) => this.#path(k);
+		return {
+			create: (key, o) => cap.create(path(key), o),
+			signPart: (key, uploadId, partNumber, o) => cap.signPart(path(key), uploadId, partNumber, o),
+			complete: (key, uploadId, parts) => cap.complete(path(key), uploadId, parts),
+			abort: (key, uploadId) => cap.abort(path(key), uploadId)
+		};
+	}
+	async createMultipartUpload(key, opts) {
+		this.#assertWritable();
+		if (typeof this.#driver.createMultipartUpload !== "function") throw new StorageError("Unsupported", `${this.#driver.name}: multipart not supported`);
+		return this.#driver.createMultipartUpload(this.#path(key), opts);
+	}
+	resumeMultipartUpload(key, uploadId) {
+		this.#assertWritable();
+		if (typeof this.#driver.resumeMultipartUpload !== "function") throw new StorageError("Unsupported", `${this.#driver.name}: multipart resume not supported`);
+		return this.#driver.resumeMultipartUpload(this.#path(key), uploadId);
+	}
+	/** A key-bound handle over the common single-object operations. */
+	file(key) {
+		return {
+			key,
+			upload: (body, o) => this.upload(key, body, o),
+			download: (o) => this.download(key, o),
+			head: (o) => this.head(key, o),
+			exists: (o) => this.exists(key, o),
+			delete: (o) => this.delete(key, o),
+			url: (o) => this.url(key, o),
+			signedUploadUrl: (o) => this.signedUploadUrl(key, o)
+		};
+	}
+	/** A read-only clone of this handle (mutations throw `ReadOnly`). */
+	readonly() {
+		return new Storage({
+			...this.#opts,
+			readonly: true
+		});
+	}
+	#path(key) {
+		return joinKey(this.#prefix, sanitizeKey(key));
+	}
+	#strip(storedKey) {
+		return stripPrefix(this.#prefix, storedKey);
+	}
+	#listPrefix(prefix) {
+		if (!this.#prefix) return prefix;
+		return prefix ? `${this.#prefix}/${prefix}` : `${this.#prefix}/`;
+	}
+	#relabel(file, logicalKey) {
+		if (file.key === logicalKey) return file;
+		return {
+			key: logicalKey,
+			name: logicalKey.slice(logicalKey.lastIndexOf("/") + 1),
+			size: file.size,
+			type: file.type,
+			lastModified: file.lastModified,
+			etag: file.etag,
+			metadata: file.metadata,
+			arrayBuffer: () => file.arrayBuffer(),
+			text: () => file.text(),
+			blob: () => file.blob(),
+			stream: () => file.stream()
+		};
+	}
+	#assertWritable() {
+		if (this.#readonly) throw new StorageError("ReadOnly", "storage handle is read-only");
+	}
+	#assertUploadSupported(opts) {
+		const d = this.#driver;
+		if (opts?.metadata && Object.keys(opts.metadata).length > 0 && !d.supportsMetadata) throw new StorageError("Unsupported", `${d.name}: metadata not supported`);
+		if (opts?.cacheControl && !d.supportsCacheControl) throw new StorageError("Unsupported", `${d.name}: cacheControl not supported`);
+	}
+	#assertRange() {
+		if (!this.#driver.supportsRange) throw new StorageError("Unsupported", `${this.#driver.name}: range reads not supported`);
+	}
+	#assertDelimiter() {
+		if (!this.#driver.supportsDelimiter) throw new StorageError("Unsupported", `${this.#driver.name}: delimiter not supported`);
+	}
+	async #exec(type, key, replayable, opts, fn) {
+		const started = Date.now();
+		const retries = replayable ? opts?.retries ?? this.#opts.retries : 0;
+		const maxRetries = normalizeRetry(retries).max;
+		const hooks = this.#opts.hooks;
+		try {
+			const result = await runWithRetry(fn, {
+				retries,
+				timeout: opts?.timeout ?? this.#opts.timeout,
+				signal: opts?.signal ?? this.#opts.signal
+			}, (info) => hooks?.onRetry?.({
+				type,
+				key,
+				attempt: info.attempt,
+				maxRetries,
+				delayMs: info.delayMs,
+				error: info.error
+			}));
+			hooks?.onOperation?.({
+				type,
+				key,
+				status: "success",
+				durationMs: Date.now() - started
+			});
+			return result;
+		} catch (e) {
+			const error = StorageError.wrap(e);
+			hooks?.onError?.({
+				type,
+				key,
+				error
+			});
+			hooks?.onOperation?.({
+				type,
+				key,
+				status: "error",
+				durationMs: Date.now() - started,
+				error
+			});
+			throw error;
+		}
+	}
+};
+function createStorage(opts) {
+	return new Storage(opts);
+}
+//#endregion
+//#region src/http/http-helpers.ts
+/** Map a core error code to (wire code, HTTP status). */
+function mapError(code) {
+	switch (code) {
+		case "NotFound": return {
+			wire: "not_found",
+			status: 404
+		};
+		case "AccessDenied":
+		case "ReadOnly": return {
+			wire: "forbidden",
+			status: 403
+		};
+		case "Unsupported": return {
+			wire: "capability_unsupported",
+			status: 400
+		};
+		case "InvalidKey": return {
+			wire: "invalid_key",
+			status: 400
+		};
+		case "InvalidRequest":
+		case "Aborted": return {
+			wire: "invalid_request",
+			status: 400
+		};
+		case "Conflict": return {
+			wire: "conflict",
+			status: 409
+		};
+		case "RateLimited": return {
+			wire: "rate_limited",
+			status: 429
+		};
+		case "Timeout": return {
+			wire: "upstream_error",
+			status: 504
+		};
+		default: return {
+			wire: "upstream_error",
+			status: 502
+		};
+	}
+}
+function serializeStored(file) {
+	return {
+		key: file.key,
+		name: file.name,
+		size: file.size,
+		type: file.type,
+		lastModified: file.lastModified,
+		etag: file.etag,
+		metadata: file.metadata
+	};
+}
+function clampExpiry(requested, def, max) {
+	return Math.min(requested ?? def, max);
+}
+/** Parse an HTTP `Range` header (single range) into a {@link ByteRange}. */
+function parseRange(header) {
+	if (!header) return void 0;
+	const m = /^bytes=(\d+)-(\d*)$/.exec(header.trim());
+	if (!m) return void 0;
+	return {
+		start: Number(m[1]),
+		end: m[2] === "" ? void 0 : Number(m[2])
+	};
+}
+/** Content-Disposition header — defaults to `attachment` (anti stored-XSS). */
+function dispositionHeader(disposition, name) {
+	const filename = `filename*=UTF-8''${encodeURIComponent(name)}`;
+	return disposition === "inline" ? `inline; ${filename}` : `attachment; ${filename}`;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/storage.controller.ts
+/**
+* Build a vela controller exposing presigned/multipart upload + download
+* endpoints for one bucket. Factory-decorated (like better-auth's catch-all)
+* so `basePath` bakes in at decoration time. Consumes the {@link StorageService}
+* facade so gating/retry/prefix apply uniformly on the HTTP path.
+*/
+function createStorageController(basePath, serviceToken, http) {
+	let StorageController = class StorageController {
+		svc;
+		constructor(svc) {
+			this.svc = svc;
+		}
+		get storage() {
+			return this.svc.storage;
+		}
+		async authorize(c, action) {
+			if (!http.authorize) {
+				if (http.defaultPolicy === "allow") return {};
+				throw new StorageError("AccessDenied", "storage: no authorizer configured (default deny)");
+			}
+			const res = await http.authorize(action, {
+				req: c.req.raw,
+				ctx: c,
+				driver: http.driverName
+			});
+			if (res === false) throw new StorageError("AccessDenied", "not allowed");
+			if (res === true) return {};
+			return res;
+		}
+		fail(c, e) {
+			const err = e instanceof StorageError ? e : StorageError.wrap(e);
+			const { wire, status } = mapError(err.code);
+			const message = err.internal || status >= 500 ? "storage backend error" : err.message;
+			return c.json({ error: {
+				code: wire,
+				message
+			} }, status);
+		}
+		async signUpload(c) {
+			try {
+				const b = await c.req.json();
+				const ov = await this.authorize(c, {
+					type: "sign-upload",
+					key: b.key,
+					contentType: b.contentType,
+					size: b.size
+				});
+				const key = sanitizeKey(ov.key ?? b.key);
+				const upload = await this.storage.signedUploadUrl(key, {
+					expiresIn: clampExpiry(ov.expiresIn ?? b.expiresIn, http.defaultExpiresIn, http.maxExpiresIn),
+					contentType: b.contentType,
+					maxSize: ov.maxSize ?? http.maxUploadSize
+				});
+				return c.json({
+					key,
+					upload
+				});
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async multipartCreate(c) {
+			try {
+				const b = await c.req.json();
+				const ov = await this.authorize(c, {
+					type: "multipart-create",
+					key: b.key,
+					contentType: b.contentType
+				});
+				const key = sanitizeKey(ov.key ?? b.key);
+				const sm = this.storage.signedMultipart;
+				if (!sm) throw new StorageError("Unsupported", "presigned multipart not supported");
+				const created = await sm.create(key, {
+					contentType: b.contentType,
+					metadata: ov.metadata ?? b.metadata,
+					partSize: b.partSize
+				});
+				return c.json({
+					key,
+					uploadId: created.uploadId,
+					partSize: created.partSize
+				});
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async multipartSignPart(c) {
+			try {
+				const b = await c.req.json();
+				const ov = await this.authorize(c, {
+					type: "multipart-sign-part",
+					key: b.key,
+					uploadId: b.uploadId,
+					partNumber: b.partNumber
+				});
+				const key = sanitizeKey(ov.key ?? b.key);
+				const sm = this.storage.signedMultipart;
+				if (!sm) throw new StorageError("Unsupported", "presigned multipart not supported");
+				const part = await sm.signPart(key, b.uploadId, b.partNumber, { expiresIn: clampExpiry(ov.expiresIn, http.defaultExpiresIn, http.maxExpiresIn) });
+				return c.json({
+					partNumber: b.partNumber,
+					method: "PUT",
+					url: part.url,
+					headers: part.headers
+				});
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async multipartComplete(c) {
+			try {
+				const b = await c.req.json();
+				const key = sanitizeKey((await this.authorize(c, {
+					type: "multipart-complete",
+					key: b.key,
+					uploadId: b.uploadId
+				})).key ?? b.key);
+				const sm = this.storage.signedMultipart;
+				if (!sm) throw new StorageError("Unsupported", "presigned multipart not supported");
+				return c.json(await sm.complete(key, b.uploadId, b.parts));
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async multipartAbort(c) {
+			try {
+				const b = await c.req.json();
+				const key = sanitizeKey((await this.authorize(c, {
+					type: "multipart-abort",
+					key: b.key,
+					uploadId: b.uploadId
+				})).key ?? b.key);
+				const sm = this.storage.signedMultipart;
+				if (!sm) throw new StorageError("Unsupported", "presigned multipart not supported");
+				await sm.abort(key, b.uploadId);
+				return c.json({ ok: true });
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async list(c) {
+			try {
+				const prefix = c.req.query("prefix");
+				const ov = await this.authorize(c, {
+					type: "list",
+					prefix
+				});
+				const limit = c.req.query("limit");
+				const res = await this.storage.list({
+					prefix: ov.prefix ?? prefix,
+					cursor: c.req.query("cursor"),
+					delimiter: c.req.query("delimiter"),
+					limit: limit ? Math.min(Number(limit), http.maxListLimit) : void 0
+				});
+				return c.json({
+					items: res.items.map(serializeStored),
+					prefixes: res.prefixes,
+					cursor: res.cursor
+				});
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async head(c) {
+			try {
+				const key = sanitizeKey(c.req.query("key") ?? "");
+				const ov = await this.authorize(c, {
+					type: "head",
+					key
+				});
+				const file = await this.storage.head(sanitizeKey(ov.key ?? key));
+				return c.json(serializeStored(file));
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async delete(c) {
+			try {
+				const keys = (await c.req.json()).keys.map((k) => sanitizeKey(k));
+				const effective = ((await this.authorize(c, {
+					type: "delete",
+					keys
+				})).keys ?? keys).map((k) => sanitizeKey(k));
+				return c.json(await this.storage.delete(effective, { concurrency: http.deleteConcurrency }));
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async download(c) {
+			try {
+				const key = sanitizeKey(c.req.query("key") ?? "");
+				const disp = c.req.query("disposition");
+				const ov = await this.authorize(c, {
+					type: "download",
+					key
+				});
+				const ekey = sanitizeKey(ov.key ?? key);
+				const name = ekey.slice(ekey.lastIndexOf("/") + 1);
+				if (http.download === "redirect" && this.storage.capabilities.signedUrl.supported) {
+					const url = await this.storage.url(ekey, {
+						expiresIn: clampExpiry(ov.expiresIn, http.defaultExpiresIn, http.maxExpiresIn),
+						responseContentDisposition: dispositionHeader(disp, name)
+					});
+					return c.redirect(url, 302);
+				}
+				const range = parseRange(c.req.header("range"));
+				const file = await this.storage.download(ekey, range ? { range } : void 0);
+				const headers = new Headers({
+					"content-type": file.type,
+					"content-length": String(file.size),
+					"content-disposition": dispositionHeader(disp, file.name)
+				});
+				if (file.etag) headers.set("etag", file.etag);
+				if (range) {
+					headers.set("content-range", `bytes ${range.start}-${range.start + file.size - 1}/*`);
+					return new Response(file.stream(), {
+						status: 206,
+						headers
+					});
+				}
+				return new Response(file.stream(), {
+					status: 200,
+					headers
+				});
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+		async signDownload(c) {
+			try {
+				const b = await c.req.json();
+				const ov = await this.authorize(c, {
+					type: "download",
+					key: b.key
+				});
+				const key = sanitizeKey(ov.key ?? b.key);
+				const expiresIn = clampExpiry(ov.expiresIn ?? b.expiresIn, http.defaultExpiresIn, http.maxExpiresIn);
+				const url = await this.storage.url(key, { expiresIn });
+				return c.json({
+					url,
+					expiresAt: Date.now() + expiresIn * 1e3
+				});
+			} catch (e) {
+				return this.fail(c, e);
+			}
+		}
+	};
+	__decorate([
+		Post("/sign-upload"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "signUpload", null);
+	__decorate([
+		Post("/multipart/create"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "multipartCreate", null);
+	__decorate([
+		Post("/multipart/sign-part"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "multipartSignPart", null);
+	__decorate([
+		Post("/multipart/complete"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "multipartComplete", null);
+	__decorate([
+		Post("/multipart/abort"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "multipartAbort", null);
+	__decorate([
+		Get("/list"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "list", null);
+	__decorate([
+		Get("/head"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "head", null);
+	__decorate([
+		Post("/delete"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "delete", null);
+	__decorate([
+		Get("/download"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "download", null);
+	__decorate([
+		Post("/sign-download"),
+		__decorateParam(0, Req()),
+		__decorateMetadata("design:type", Function),
+		__decorateMetadata("design:paramtypes", [Object]),
+		__decorateMetadata("design:returntype", Promise)
+	], StorageController.prototype, "signDownload", null);
+	StorageController = __decorate([
+		Controller(basePath),
+		Injectable(),
+		__decorateParam(0, Inject(serviceToken)),
+		__decorateMetadata("design:paramtypes", [Object])
+	], StorageController);
+	return StorageController;
+}
+//#endregion
+//#region src/storage.service.ts
+/**
+* Build the real driver on first property access and delegate to it. This is
+* the edge-binding-safe seam: the driver factory (which may read Cloudflare
+* bindings / `c.env` secrets) does not run at module load — only on the first
+* storage operation, which happens at request time.
+*
+* Functions are bound to the built driver so class-based drivers keep `this`.
+*/
+function lazyDriver(build) {
+	let built;
+	const ensure = () => built ??= build();
+	return new Proxy({}, {
+		get(_target, prop) {
+			const driver = ensure();
+			const value = driver[prop];
+			return typeof value === "function" ? value.bind(driver) : value;
+		},
+		has(_target, prop) {
+			return prop in ensure();
+		}
+	});
+}
+let StorageService = class StorageService {
+	storage;
+	name;
+	constructor(build, options) {
+		this.name = options.name;
+		this.storage = createStorage({
+			driver: lazyDriver(build),
+			prefix: options.prefix,
+			readonly: options.readonly,
+			hooks: options.hooks
+		});
+	}
+	upload(key, body, opts) {
+		return this.storage.upload(key, body, opts);
+	}
+	download(key, opts) {
+		return this.storage.download(key, opts);
+	}
+	head(key, opts) {
+		return this.storage.head(key, opts);
+	}
+	exists(key, opts) {
+		return this.storage.exists(key, opts);
+	}
+	delete(key, opts) {
+		return this.storage.delete(key, opts);
+	}
+	deleteMany(keys, opts) {
+		return this.storage.delete(keys, opts);
+	}
+	copy(from, to, opts) {
+		return this.storage.copy(from, to, opts);
+	}
+	move(from, to, opts) {
+		return this.storage.move(from, to, opts);
+	}
+	list(opts) {
+		return this.storage.list(opts);
+	}
+	url(key, opts) {
+		return this.storage.url(key, opts);
+	}
+	signedUploadUrl(key, opts) {
+		return this.storage.signedUploadUrl(key, opts);
+	}
+};
+StorageService = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [Function, Object])], StorageService);
+//#endregion
+//#region src/storage.tokens.ts
+/** Bucket name used when a registration omits `name`. */
+const DEFAULT_STORAGE_NAME = "default";
+const builderTokens = /* @__PURE__ */ new Map();
+const serviceTokens = /* @__PURE__ */ new Map();
+/** Internal token holding the lazy driver-construction thunk for `name`. */
+function storageDriverBuilder(name) {
+	let token = builderTokens.get(name);
+	if (!token) {
+		token = new InjectionToken(`vela.storage.Builder:${name}`);
+		builderTokens.set(name, token);
+	}
+	return token;
+}
+/**
+* Token that resolves to the {@link StorageService} for a named bucket.
+* The default bucket uses the `StorageService` class token directly (see
+* `@InjectStorage()`); named buckets use this.
+*/
+function storageToken(name) {
+	let token = serviceTokens.get(name);
+	if (!token) {
+		token = new InjectionToken(`vela.storage.Service:${name}`);
+		serviceTokens.set(name, token);
+	}
+	return token;
+}
+//#endregion
+//#region src/storage.module.ts
+/**
+* The stable, identifying subset of the HTTP options folded into the instance
+* key — matches what `buildControllers` bakes into the mounted controller so
+* two registrations that differ only in HTTP behavior get distinct keys.
+*/
+function httpKeyPart(http) {
+	if (!http || http.mountController === false) return {};
+	return {
+		basePath: http.basePath ?? "/api/storage",
+		download: http.download ?? "redirect",
+		defaultPolicy: http.defaultPolicy ?? "deny"
+	};
+}
+function buildControllers(name, serviceToken, http) {
+	if (!http || http.mountController === false) return [];
+	const resolved = {
+		driverName: name,
+		authorize: http.authorize,
+		defaultPolicy: http.defaultPolicy ?? "deny",
+		download: http.download ?? "redirect",
+		defaultExpiresIn: http.defaultExpiresIn ?? 900,
+		maxExpiresIn: http.maxExpiresIn ?? 3600,
+		maxUploadSize: http.maxUploadSize,
+		maxListLimit: http.maxListLimit ?? 1e3,
+		deleteConcurrency: http.deleteConcurrency ?? 8
+	};
+	return [createStorageController(http.basePath ?? "/api/storage", serviceToken, resolved)];
+}
+const { ConfigurableModuleClass } = defineModule({
+	name: "Storage",
+	key: (o) => stableHash({
+		name: o.name ?? "default",
+		prefix: o.prefix ?? "",
+		readonly: !!o.readonly,
+		hooks: !!o.hooks,
+		...httpKeyPart(o.http)
+	}),
+	setup: ({ OPTIONS, options }) => {
+		const name = options.name ?? "default";
+		const builderToken = storageDriverBuilder(name);
+		const serviceToken = name === "default" ? StorageService : storageToken(name);
+		const svcOptions = {
+			name,
+			prefix: options.prefix,
+			readonly: options.readonly,
+			hooks: options.hooks
+		};
+		return {
+			providers: [lazyProvider({
+				provide: builderToken,
+				inject: [OPTIONS],
+				useFactory: (o) => o.driver()
+			}), {
+				provide: serviceToken,
+				useFactory: (build) => new StorageService(build, svcOptions),
+				inject: [builderToken]
+			}],
+			controllers: buildControllers(name, serviceToken, options.http),
+			exports: [serviceToken, builderToken]
+		};
+	}
+});
+var StorageModule = class StorageModule {
+	/** Synchronous registration — the driver is provided directly. */
+	static forRoot(options) {
+		const { driver, ...rest } = options;
+		return {
+			...ConfigurableModuleClass.forRoot({
+				...rest,
+				driver: () => driver
+			}),
+			module: StorageModule
+		};
+	}
+	/** Deferred / DI-driven registration — `useFactory` runs lazily on first use. */
+	static forRootAsync(options) {
+		const { useFactory, inject, imports, key, ...structural } = options;
+		return {
+			...ConfigurableModuleClass.forRootAsync({
+				imports,
+				inject,
+				key,
+				...structural,
+				useFactory: (...deps) => ({ driver: () => useFactory(...deps) })
+			}),
+			module: StorageModule
+		};
+	}
+};
+//#endregion
+//#region src/decorators/inject-storage.decorator.ts
+/**
+* Inject the {@link StorageService} for a named bucket.
+*
+* ```ts
+* class UploadService {
+*   constructor(
+*     @InjectStorage() private readonly uploads: StorageService,          // default bucket
+*     @InjectStorage('backups') private readonly backups: StorageService, // named bucket
+*   ) {}
+* }
+* ```
+*
+* The default bucket resolves the `StorageService` class token directly (so
+* plain `@Inject(StorageService)` and `Test.overrideProvider(StorageService)`
+* keep working); named buckets resolve their per-name token.
+*/
+function InjectStorage(name = DEFAULT_STORAGE_NAME) {
+	return Inject(name === "default" ? StorageService : storageToken(name));
+}
+//#endregion
+export { DEFAULT_STORAGE_NAME, InjectStorage, Storage, StorageError, StorageModule, StorageService, createStorage, createStorageController, isAbort, isSafeKey, joinKey, lazyDriver, normalizePrefix, sanitizeKey, storageDriverBuilder, storageToken, stripPrefix };
+
+//# sourceMappingURL=index.js.map