@aigne/afs-s3 1.11.0-beta.6

package/dist/index.mjs

@@ -0,0 +1,1260 @@
+import { AFSBaseProvider, AFSError, AFSNotFoundError, Actions, Delete, List, Meta, Read, Stat, Write } from "@aigne/afs";
+import { camelize, optionalize, zodParse } from "@aigne/afs/utils/zod";
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectVersionsCommand, ListObjectsV2Command, PutObjectCommand, S3Client, SelectObjectContentCommand, UploadPartCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { z } from "zod";
+
+//#region src/cache.ts
+/**
+* LRU Cache with TTL support
+*/
+var LRUCache = class {
+	cache = /* @__PURE__ */ new Map();
+	maxSize;
+	defaultTtl;
+	/**
+	* Create a new LRU cache
+	*
+	* @param maxSize - Maximum number of entries (default: 1000)
+	* @param defaultTtl - Default TTL in seconds (default: 60)
+	*/
+	constructor(maxSize = 1e3, defaultTtl = 60) {
+		this.maxSize = maxSize;
+		this.defaultTtl = defaultTtl;
+	}
+	/**
+	* Get a value from the cache
+	*
+	* @param key - Cache key
+	* @returns Cached value or undefined if not found/expired
+	*/
+	get(key) {
+		const entry = this.cache.get(key);
+		if (!entry) return;
+		if (Date.now() > entry.expiresAt) {
+			this.cache.delete(key);
+			return;
+		}
+		this.cache.delete(key);
+		this.cache.set(key, entry);
+		return entry.value;
+	}
+	/**
+	* Set a value in the cache
+	*
+	* @param key - Cache key
+	* @param value - Value to cache
+	* @param ttl - TTL in seconds (optional, uses default)
+	*/
+	set(key, value, ttl) {
+		if (this.cache.has(key)) this.cache.delete(key);
+		while (this.cache.size >= this.maxSize) {
+			const oldestKey = this.cache.keys().next().value;
+			if (oldestKey) this.cache.delete(oldestKey);
+		}
+		const expiresAt = Date.now() + (ttl ?? this.defaultTtl) * 1e3;
+		this.cache.set(key, {
+			value,
+			expiresAt
+		});
+	}
+	/**
+	* Delete a value from the cache
+	*
+	* @param key - Cache key
+	*/
+	delete(key) {
+		this.cache.delete(key);
+	}
+	/**
+	* Delete all entries matching a prefix
+	*
+	* @param prefix - Key prefix to match
+	*/
+	deleteByPrefix(prefix) {
+		for (const key of this.cache.keys()) if (key.startsWith(prefix)) this.cache.delete(key);
+	}
+	/**
+	* Clear all entries
+	*/
+	clear() {
+		this.cache.clear();
+	}
+	/**
+	* Get the number of entries in the cache
+	*/
+	get size() {
+		return this.cache.size;
+	}
+	/**
+	* Prune expired entries
+	*/
+	prune() {
+		const now = Date.now();
+		for (const [key, entry] of this.cache.entries()) if (now > entry.expiresAt) this.cache.delete(key);
+	}
+};
+/**
+* Create a cache key from bucket, prefix, and path
+*/
+function createCacheKey(bucket, prefix, path, suffix) {
+	const base = `${bucket}:${prefix}:${path}`;
+	return suffix ? `${base}:${suffix}` : base;
+}
+
+//#endregion
+//#region src/client.ts
+/**
+* S3 Client Factory
+*
+* Creates and configures AWS S3 clients.
+*/
+/**
+* Create an S3 client with the given options
+*
+* Uses AWS SDK's default credential chain:
+* 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+* 2. Shared credentials file (~/.aws/credentials)
+* 3. IAM role (EC2/ECS/Lambda)
+* 4. SSO credentials
+*
+* @param options - S3 provider options
+* @returns Configured S3 client
+*/
+function createS3Client(options) {
+	const config = {};
+	if (options.region) config.region = options.region;
+	else if (options.endpoint) config.region = "us-east-1";
+	if (options.endpoint) config.endpoint = options.endpoint;
+	if (options.forcePathStyle) config.forcePathStyle = true;
+	if (options.credentials) config.credentials = {
+		accessKeyId: options.credentials.accessKeyId,
+		secretAccessKey: options.credentials.secretAccessKey,
+		sessionToken: options.credentials.sessionToken
+	};
+	return new S3Client(config);
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* S3 Error Handling
+*
+* Maps AWS S3 errors to AFS errors.
+*/
+/**
+* AFS error codes
+*/
+const AFSErrorCode = {
+	ENTRY_NOT_FOUND: "ENTRY_NOT_FOUND",
+	MODULE_NOT_FOUND: "MODULE_NOT_FOUND",
+	PERMISSION_DENIED: "PERMISSION_DENIED",
+	AUTH_ERROR: "AUTH_ERROR",
+	RATE_LIMITED: "RATE_LIMITED",
+	TYPE_MISMATCH: "TYPE_MISMATCH",
+	INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+/**
+* AFS Error class
+*/
+var AFSError$1 = class extends Error {
+	code;
+	retryAfter;
+	constructor(code, message, options) {
+		super(message);
+		this.name = "AFSError";
+		this.code = code;
+		this.retryAfter = options?.retryAfter;
+	}
+};
+/**
+* Map S3 error to AFS error
+*
+* @param error - AWS S3 error
+* @param path - Optional path for AFSNotFoundError (with leading slash)
+* @returns AFS error (or throws the original error if it's already an AFS error)
+*/
+function mapS3Error(error, path) {
+	if (error && typeof error === "object" && "name" in error) {
+		const errorObj = error;
+		if (errorObj.name === "AFSNotFoundError" || errorObj.name === "AFSError" || errorObj.code === "AFS_NOT_FOUND") throw error;
+	}
+	if (error && typeof error === "object" && "name" in error) {
+		const awsError = error;
+		const message = awsError.message ?? "Unknown S3 error";
+		switch (awsError.name) {
+			case "NoSuchBucket": return new AFSError$1(AFSErrorCode.MODULE_NOT_FOUND, `Bucket not found: ${message}`);
+			case "NoSuchKey":
+			case "NotFound":
+				if (path) return new AFSNotFoundError(path);
+				return new AFSError$1(AFSErrorCode.ENTRY_NOT_FOUND, `Object not found: ${message}`);
+			case "AccessDenied":
+			case "Forbidden": return new AFSError$1(AFSErrorCode.PERMISSION_DENIED, `Access denied: ${message}`);
+			case "InvalidAccessKeyId":
+			case "SignatureDoesNotMatch":
+			case "ExpiredToken":
+			case "TokenRefreshRequired": return new AFSError$1(AFSErrorCode.AUTH_ERROR, `Authentication failed: ${message}`);
+			case "SlowDown":
+			case "ServiceUnavailable": return new AFSError$1(AFSErrorCode.RATE_LIMITED, `Rate limited: ${message}`, { retryAfter: 1e3 });
+			default: {
+				const statusCode = awsError.$metadata?.httpStatusCode;
+				if (statusCode === 404) {
+					if (path) return new AFSNotFoundError(path);
+					return new AFSError$1(AFSErrorCode.ENTRY_NOT_FOUND, message);
+				}
+				if (statusCode === 403) return new AFSError$1(AFSErrorCode.PERMISSION_DENIED, message);
+				if (statusCode === 401) return new AFSError$1(AFSErrorCode.AUTH_ERROR, message);
+				if (statusCode === 429 || statusCode === 503) return new AFSError$1(AFSErrorCode.RATE_LIMITED, message, { retryAfter: 1e3 });
+				return new AFSError$1(AFSErrorCode.INTERNAL_ERROR, message);
+			}
+		}
+	}
+	if (error instanceof Error) return new AFSError$1(AFSErrorCode.INTERNAL_ERROR, error.message);
+	return new AFSError$1(AFSErrorCode.INTERNAL_ERROR, String(error));
+}
+
+//#endregion
+//#region src/operations/multipart.ts
+/**
+* S3 Multipart Upload (Phase 2)
+*
+* Handles multipart upload for large files (>5GB).
+* S3 requires multipart upload for objects larger than 5GB.
+*/
+/**
+* Minimum part size (5MB) - AWS S3 requirement
+*/
+const MIN_PART_SIZE = 5 * 1024 * 1024;
+/**
+* Maximum part size (5GB) - AWS S3 requirement
+*/
+const MAX_PART_SIZE = 5 * 1024 * 1024 * 1024;
+/**
+* Threshold for switching to multipart upload (100MB)
+* Files larger than this will use multipart upload
+*/
+const MULTIPART_THRESHOLD = 100 * 1024 * 1024;
+/**
+* Default part size (10MB)
+*/
+const DEFAULT_PART_SIZE = 10 * 1024 * 1024;
+/**
+* Maximum number of parts (10,000) - AWS S3 requirement
+*/
+const MAX_PARTS = 1e4;
+/**
+* Calculate optimal part size based on file size
+*/
+function calculatePartSize(fileSize, requestedPartSize) {
+	let partSize = requestedPartSize ?? DEFAULT_PART_SIZE;
+	if (partSize < MIN_PART_SIZE) partSize = MIN_PART_SIZE;
+	if (partSize > MAX_PART_SIZE) partSize = MAX_PART_SIZE;
+	if (Math.ceil(fileSize / partSize) > MAX_PARTS) {
+		partSize = Math.ceil(fileSize / MAX_PARTS);
+		partSize = Math.ceil(partSize / (1024 * 1024)) * 1024 * 1024;
+	}
+	return partSize;
+}
+/**
+* Upload a large file using multipart upload
+*
+* @param client - S3 client
+* @param bucket - Bucket name
+* @param key - Object key
+* @param data - File content as Buffer
+* @param options - Upload options
+* @returns Upload result with ETag
+*/
+async function multipartUpload(client, bucket, key, data, options) {
+	const fileSize = data.length;
+	const partSize = calculatePartSize(fileSize, options?.partSize);
+	const createCommand = new CreateMultipartUploadCommand({
+		Bucket: bucket,
+		Key: key,
+		ContentType: options?.contentType ?? "application/octet-stream",
+		Metadata: options?.metadata
+	});
+	const uploadId = (await client.send(createCommand)).UploadId;
+	if (!uploadId) throw new Error("Failed to initiate multipart upload: no uploadId returned");
+	const parts = [];
+	try {
+		const totalParts = Math.ceil(fileSize / partSize);
+		for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
+			const start = (partNumber - 1) * partSize;
+			const end = Math.min(start + partSize, fileSize);
+			const partData = data.subarray(start, end);
+			const uploadPartCommand = new UploadPartCommand({
+				Bucket: bucket,
+				Key: key,
+				UploadId: uploadId,
+				PartNumber: partNumber,
+				Body: partData
+			});
+			const uploadPartResponse = await client.send(uploadPartCommand);
+			if (!uploadPartResponse.ETag) throw new Error(`Failed to upload part ${partNumber}: no ETag returned`);
+			parts.push({
+				ETag: uploadPartResponse.ETag,
+				PartNumber: partNumber
+			});
+		}
+		const completeCommand = new CompleteMultipartUploadCommand({
+			Bucket: bucket,
+			Key: key,
+			UploadId: uploadId,
+			MultipartUpload: { Parts: parts }
+		});
+		const completeResponse = await client.send(completeCommand);
+		return {
+			etag: completeResponse.ETag?.replace(/"/g, "") ?? "",
+			versionId: completeResponse.VersionId
+		};
+	} catch (error) {
+		try {
+			const abortCommand = new AbortMultipartUploadCommand({
+				Bucket: bucket,
+				Key: key,
+				UploadId: uploadId
+			});
+			await client.send(abortCommand);
+		} catch {}
+		throw mapS3Error(error);
+	}
+}
+/**
+* Check if a file should use multipart upload
+*/
+function shouldUseMultipart(size) {
+	return size >= MULTIPART_THRESHOLD;
+}
+
+//#endregion
+//#region src/operations/select.ts
+/**
+* S3 Select Support (Phase 3)
+*
+* Runs SQL-like queries on CSV and JSON files stored in S3.
+* This enables server-side filtering, reducing data transfer.
+*/
+/**
+* Detect input format from file extension
+*/
+function detectInputFormat(path) {
+	switch (path.toLowerCase().split(".").pop()) {
+		case "csv":
+		case "tsv": return "CSV";
+		case "json":
+		case "jsonl":
+		case "ndjson": return "JSON";
+		case "parquet": return "Parquet";
+		default: return "JSON";
+	}
+}
+/**
+* Run a SQL-like query on an S3 object
+*
+* @param client - S3 client
+* @param bucket - Bucket name
+* @param mountPrefix - Mount prefix from options
+* @param path - Path relative to mount point
+* @param query - SQL query (e.g., "SELECT * FROM s3object WHERE age > 21")
+* @param options - Select options
+* @returns Query results
+*/
+async function selectQuery(client, bucket, mountPrefix, path, query, options) {
+	try {
+		const normalizedPath = path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const key = mountPrefix ? `${mountPrefix}/${normalizedPath}` : normalizedPath;
+		const inputFormat = options?.inputFormat ?? detectInputFormat(path);
+		const outputFormat = options?.outputFormat ?? "JSON";
+		const inputSerialization = {};
+		if (inputFormat === "CSV") inputSerialization.CSV = {
+			FieldDelimiter: options?.csv?.fieldDelimiter ?? ",",
+			RecordDelimiter: options?.csv?.recordDelimiter ?? "\n",
+			FileHeaderInfo: options?.csv?.fileHeaderInfo ?? "USE",
+			QuoteCharacter: options?.csv?.quoteCharacter ?? "\"",
+			Comments: options?.csv?.comments
+		};
+		else if (inputFormat === "JSON") inputSerialization.JSON = { Type: options?.json?.type ?? "DOCUMENT" };
+		else if (inputFormat === "Parquet") inputSerialization.Parquet = {};
+		const outputSerialization = {};
+		if (outputFormat === "JSON") outputSerialization.JSON = {};
+		else outputSerialization.CSV = {};
+		const command = new SelectObjectContentCommand({
+			Bucket: bucket,
+			Key: key,
+			ExpressionType: "SQL",
+			Expression: query,
+			InputSerialization: inputSerialization,
+			OutputSerialization: outputSerialization
+		});
+		const response = await client.send(command);
+		const records = [];
+		let stats;
+		if (response.Payload) for await (const event of response.Payload) {
+			if (event.Records?.Payload) {
+				const lines = new TextDecoder().decode(event.Records.Payload).split("\n").filter((line) => line.trim());
+				for (const line of lines) try {
+					records.push(JSON.parse(line));
+				} catch {
+					records.push(line);
+				}
+			}
+			if (event.Stats?.Details) stats = {
+				bytesScanned: Number(event.Stats.Details.BytesScanned ?? 0),
+				bytesProcessed: Number(event.Stats.Details.BytesProcessed ?? 0),
+				bytesReturned: Number(event.Stats.Details.BytesReturned ?? 0)
+			};
+		}
+		return {
+			records,
+			stats
+		};
+	} catch (error) {
+		throw mapS3Error(error);
+	}
+}
+
+//#endregion
+//#region src/platform-ref.ts
+/**
+* Generate platform reference with AWS Console URL
+*
+* @param bucket - S3 bucket name
+* @param region - AWS region (defaults to us-east-1)
+* @param key - S3 object key (without leading slash)
+* @param isDirectory - Whether this is a directory (prefix)
+* @returns Platform reference with console URL
+*/
+function generatePlatformRef(bucket, region, key, isDirectory) {
+	const effectiveRegion = region || "us-east-1";
+	if (isDirectory) return { consoleUrl: `https://s3.console.aws.amazon.com/s3/buckets/${bucket}?region=${effectiveRegion}&prefix=${key.endsWith("/") ? key : key ? `${key}/` : ""}` };
+	return { consoleUrl: `https://s3.console.aws.amazon.com/s3/object/${bucket}?region=${effectiveRegion}&prefix=${encodeURIComponent(key).replace(/%2F/g, "/")}` };
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* AFS S3 Provider Types
+*/
+/**
+* S3 bucket name validation regex
+* - 3-63 characters
+* - lowercase letters, numbers, hyphens, dots
+* - must start and end with letter or number
+*/
+const BUCKET_NAME_REGEX = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+/**
+* Zod schema for options validation
+*/
+const afss3OptionsSchema = camelize(z.object({
+	name: optionalize(z.string()),
+	description: optionalize(z.string()),
+	bucket: z.string().regex(BUCKET_NAME_REGEX, "Invalid S3 bucket name"),
+	prefix: optionalize(z.string()),
+	region: optionalize(z.string()),
+	accessMode: optionalize(z.enum(["readonly", "readwrite"])),
+	endpoint: optionalize(z.string().url()),
+	forcePathStyle: optionalize(z.boolean()),
+	profile: optionalize(z.string()),
+	credentials: optionalize(z.object({
+		accessKeyId: z.string(),
+		secretAccessKey: z.string(),
+		sessionToken: optionalize(z.string())
+	})),
+	cacheTtl: optionalize(z.number().int().min(0))
+}).strict());
+
+//#endregion
+//#region \0@oxc-project+runtime@0.108.0/helpers/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/s3-afs.ts
+/**
+* AFS S3 Provider
+*
+* S3 provider using AFSBaseProvider decorator routing pattern.
+* Provides access to AWS S3 and S3-compatible storage (MinIO, R2, B2).
+*/
+/**
+* Default URL expiration time (1 hour)
+*/
+const DEFAULT_EXPIRES_IN = 3600;
+/**
+* Maximum expiration time (7 days)
+*/
+const MAX_EXPIRES_IN = 604800;
+/**
+* AFSS3 Provider using Base Provider pattern
+*
+* Provides access to AWS S3 and S3-compatible storage through AFS.
+* Uses decorator routing (@List, @Read, @Write, @Delete, @Meta, @Actions).
+*
+* @example
+* ```typescript
+* const s3 = new AFSS3({
+*   bucket: "my-bucket",
+*   prefix: "data",
+*   region: "us-east-1",
+* });
+*
+* // Mount to AFS
+* afs.mount(s3);
+*
+* // List objects
+* const result = await afs.list("/modules/my-bucket/data");
+*
+* // Read object
+* const content = await afs.read("/modules/my-bucket/data/file.json");
+* ```
+*/
+var AFSS3 = class AFSS3 extends AFSBaseProvider {
+	name;
+	description;
+	accessMode;
+	options;
+	client;
+	listCache;
+	statCache;
+	constructor(options) {
+		super();
+		const { client, ...restOptions } = options;
+		const parsed = afss3OptionsSchema.parse(restOptions);
+		this.options = {
+			...parsed,
+			bucket: parsed.bucket,
+			prefix: parsed.prefix ?? "",
+			accessMode: parsed.accessMode ?? "readonly"
+		};
+		this.name = parsed.name ?? parsed.bucket;
+		this.description = parsed.description ?? `S3 bucket: ${parsed.bucket}`;
+		this.accessMode = this.options.accessMode ?? "readonly";
+		this.client = client ?? createS3Client(this.options);
+		if (parsed.cacheTtl && parsed.cacheTtl > 0) {
+			this.listCache = new LRUCache(1e3, parsed.cacheTtl);
+			this.statCache = new LRUCache(5e3, parsed.cacheTtl);
+		}
+	}
+	/**
+	* Schema for configuration validation
+	*/
+	static schema() {
+		return afss3OptionsSchema;
+	}
+	/**
+	* Load from configuration file
+	*/
+	static async load(params) {
+		return new AFSS3(zodParse(afss3OptionsSchema, params.parsed, { prefix: params.filepath }));
+	}
+	/**
+	* Build the full S3 key from a path
+	*/
+	buildS3Key(path) {
+		const normalizedPath = path.replace(/^\/+/, "").replace(/\/+$/, "");
+		return this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+	}
+	/**
+	* Generate a unique ID for an S3 object
+	*/
+	generateId(key) {
+		return `s3://${this.options.bucket}/${key}`;
+	}
+	/**
+	* Invalidate caches for a given path
+	*/
+	invalidateCache(path) {
+		if (this.statCache) {
+			const statKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", path);
+			this.statCache.delete(statKey);
+		}
+		if (this.listCache) {
+			const parentPath = path.split("/").slice(0, -1).join("/") || "/";
+			const listPrefix = createCacheKey(this.options.bucket, this.options.prefix ?? "", parentPath);
+			this.listCache.deleteByPrefix(listPrefix);
+		}
+	}
+	/**
+	* Clear all caches
+	*/
+	clearCache() {
+		this.listCache?.clear();
+		this.statCache?.clear();
+	}
+	async listHandler(ctx) {
+		try {
+			const normalizedPath = (ctx.params.path ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+			const fullPrefix = this.options.prefix ? normalizedPath ? `${this.options.prefix}/${normalizedPath}/` : `${this.options.prefix}/` : normalizedPath ? `${normalizedPath}/` : "";
+			const opts = ctx.options;
+			const maxChildren = opts?.limit ?? opts?.maxChildren ?? 1e3;
+			if (this.listCache) {
+				const cacheKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", normalizedPath, JSON.stringify(ctx.options ?? {}));
+				const cached = this.listCache.get(cacheKey);
+				if (cached) return cached;
+			}
+			const result = await this.listWithDelimiter(fullPrefix, normalizedPath, maxChildren);
+			if (this.listCache) {
+				const cacheKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", normalizedPath, JSON.stringify(ctx.options ?? {}));
+				this.listCache.set(cacheKey, result);
+				if (this.statCache) for (const entry of result.data) {
+					const statKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", entry.path);
+					this.statCache.set(statKey, entry);
+				}
+			}
+			return result;
+		} catch (error) {
+			throw mapS3Error(error, ctx.params.path ? ctx.params.path.startsWith("/") ? ctx.params.path : `/${ctx.params.path}` : "/");
+		}
+	}
+	/**
+	* List with delimiter (single level)
+	*/
+	async listWithDelimiter(prefix, basePath, maxChildren) {
+		const childEntries = [];
+		let continuationToken;
+		do {
+			const command = new ListObjectsV2Command({
+				Bucket: this.options.bucket,
+				Prefix: prefix,
+				Delimiter: "/",
+				MaxKeys: Math.min(maxChildren - childEntries.length, 1e3),
+				ContinuationToken: continuationToken
+			});
+			const response = await this.client.send(command);
+			if (response.CommonPrefixes) for (const commonPrefix of response.CommonPrefixes) {
+				if (!commonPrefix.Prefix) continue;
+				const dirName = commonPrefix.Prefix.slice(prefix.length).replace(/\/$/, "");
+				if (!dirName) continue;
+				const entryPath = basePath ? `${basePath}/${dirName}` : dirName;
+				const normalizedPath = entryPath.startsWith("/") ? entryPath : `/${entryPath}`;
+				childEntries.push({
+					id: this.generateId(commonPrefix.Prefix),
+					path: normalizedPath,
+					metadata: {
+						childrenCount: 0,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, commonPrefix.Prefix, true)
+					}
+				});
+				if (childEntries.length >= maxChildren) break;
+			}
+			if (response.Contents) for (const object of response.Contents) {
+				if (!object.Key) continue;
+				if (object.Key === prefix) continue;
+				const fileName = object.Key.slice(prefix.length);
+				if (!fileName || fileName.includes("/")) continue;
+				const entryPath = basePath ? `${basePath}/${fileName}` : fileName;
+				const normalizedPath = entryPath.startsWith("/") ? entryPath : `/${entryPath}`;
+				childEntries.push({
+					id: this.generateId(object.Key),
+					path: normalizedPath,
+					updatedAt: object.LastModified,
+					metadata: {
+						size: object.Size,
+						lastModified: object.LastModified?.toISOString(),
+						etag: object.ETag?.replace(/"/g, ""),
+						storageClass: object.StorageClass,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, object.Key, false)
+					}
+				});
+				if (childEntries.length >= maxChildren) break;
+			}
+			continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+		} while (continuationToken && childEntries.length < maxChildren);
+		const selfPath = basePath ? `/${basePath}` : "/";
+		if (childEntries.length === 0 && basePath) {
+			const key = this.options.prefix ? `${this.options.prefix}/${basePath}` : basePath;
+			try {
+				const headCommand = new HeadObjectCommand({
+					Bucket: this.options.bucket,
+					Key: key
+				});
+				const headResponse = await this.client.send(headCommand);
+				return { data: [{
+					id: this.generateId(key),
+					path: selfPath,
+					updatedAt: headResponse.LastModified,
+					metadata: {
+						size: headResponse.ContentLength,
+						contentType: headResponse.ContentType,
+						lastModified: headResponse.LastModified?.toISOString(),
+						etag: headResponse.ETag?.replace(/"/g, ""),
+						childrenCount: 0,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, false)
+					}
+				}] };
+			} catch (error) {
+				if (error?.name === "NotFound" || error?.$metadata?.httpStatusCode === 404) try {
+					const dirMarkerCommand = new HeadObjectCommand({
+						Bucket: this.options.bucket,
+						Key: `${key}/`
+					});
+					await this.client.send(dirMarkerCommand);
+				} catch {
+					throw new AFSNotFoundError(selfPath);
+				}
+				else throw error;
+			}
+		}
+		return { data: [{
+			id: this.generateId(prefix || "/"),
+			path: selfPath,
+			metadata: {
+				kind: "afs:node",
+				childrenCount: childEntries.length,
+				platformRef: generatePlatformRef(this.options.bucket, this.options.region, prefix, true)
+			}
+		}, ...childEntries] };
+	}
+	async listVersionsHandler(ctx) {
+		try {
+			const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+			const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+			const command = new ListObjectVersionsCommand({
+				Bucket: this.options.bucket,
+				Prefix: key,
+				MaxKeys: 1e3
+			});
+			const response = await this.client.send(command);
+			const entries = [];
+			if (response.Versions) {
+				for (const version of response.Versions) if (version.Key === key && version.VersionId) {
+					const versionPath = `/${normalizedPath}/@versions/${version.VersionId}`;
+					entries.push({
+						id: `${this.generateId(key)}:${version.VersionId}`,
+						path: versionPath,
+						updatedAt: version.LastModified,
+						metadata: {
+							versionId: version.VersionId,
+							isLatest: version.IsLatest ?? false,
+							lastModified: version.LastModified?.toISOString(),
+							size: version.Size ?? 0,
+							etag: version.ETag?.replace(/"/g, "")
+						}
+					});
+				}
+			}
+			return { data: entries };
+		} catch (error) {
+			throw mapS3Error(error, `/${ctx.params.path}/@versions`);
+		}
+	}
+	async readHandler(ctx) {
+		const normalizedOutputPath = ctx.path.startsWith("/") ? ctx.path : `/${ctx.path}`;
+		try {
+			const key = this.buildS3Key(ctx.params.path);
+			if (!key) {
+				const listCommand = new ListObjectsV2Command({
+					Bucket: this.options.bucket,
+					Prefix: this.options.prefix ? `${this.options.prefix}/` : "",
+					Delimiter: "/",
+					MaxKeys: 1e3
+				});
+				const listResponse = await this.client.send(listCommand);
+				const childrenCount = (listResponse.CommonPrefixes?.length ?? 0) + (listResponse.Contents?.length ?? 0);
+				return {
+					id: this.generateId("/"),
+					path: "/",
+					content: "",
+					metadata: {
+						kind: "afs:node",
+						childrenCount,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, "", true)
+					}
+				};
+			}
+			try {
+				const command = new GetObjectCommand({
+					Bucket: this.options.bucket,
+					Key: key
+				});
+				const response = await this.client.send(command);
+				if (key.endsWith("/") || response.ContentType === "application/x-directory") return {
+					id: this.generateId(key),
+					path: normalizedOutputPath,
+					content: "",
+					updatedAt: response.LastModified,
+					metadata: {
+						kind: "afs:node",
+						childrenCount: void 0,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, true)
+					}
+				};
+				let content;
+				if (response.Body) {
+					const bytes = await response.Body.transformToByteArray();
+					content = new TextDecoder().decode(bytes);
+				} else content = "";
+				return {
+					id: this.generateId(key),
+					path: normalizedOutputPath,
+					content,
+					updatedAt: response.LastModified,
+					metadata: {
+						size: response.ContentLength,
+						mimeType: response.ContentType,
+						contentType: response.ContentType,
+						contentLength: response.ContentLength,
+						lastModified: response.LastModified?.toISOString(),
+						etag: response.ETag?.replace(/"/g, ""),
+						contentRange: response.ContentRange
+					}
+				};
+			} catch (error) {
+				if (error?.name === "NotFound" || error?.$metadata?.httpStatusCode === 404) {
+					const listCommand = new ListObjectsV2Command({
+						Bucket: this.options.bucket,
+						Prefix: `${key}/`,
+						Delimiter: "/",
+						MaxKeys: 1e3
+					});
+					const listResponse = await this.client.send(listCommand);
+					if (listResponse.Contents && listResponse.Contents.length > 0 || listResponse.CommonPrefixes && listResponse.CommonPrefixes.length > 0) {
+						const childrenCount = (listResponse.CommonPrefixes?.length ?? 0) + (listResponse.Contents?.length ?? 0);
+						return {
+							id: this.generateId(`${key}/`),
+							path: normalizedOutputPath,
+							content: "",
+							metadata: {
+								kind: "afs:node",
+								childrenCount,
+								platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, true)
+							}
+						};
+					}
+					try {
+						const markerCommand = new HeadObjectCommand({
+							Bucket: this.options.bucket,
+							Key: `${key}/`
+						});
+						await this.client.send(markerCommand);
+						return {
+							id: this.generateId(`${key}/`),
+							path: normalizedOutputPath,
+							content: "",
+							metadata: {
+								kind: "afs:node",
+								childrenCount: 0,
+								platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, true)
+							}
+						};
+					} catch {
+						throw new AFSNotFoundError(normalizedOutputPath);
+					}
+				}
+				throw error;
+			}
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapS3Error(error, normalizedOutputPath);
+		}
+	}
+	async readVersionHandler(ctx) {
+		try {
+			const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+			const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+			const command = new GetObjectCommand({
+				Bucket: this.options.bucket,
+				Key: key,
+				VersionId: ctx.params.versionId
+			});
+			const response = await this.client.send(command);
+			const content = response.Body ? await response.Body.transformToString() : "";
+			return {
+				id: `${this.generateId(key)}:${ctx.params.versionId}`,
+				path: ctx.path,
+				content,
+				updatedAt: response.LastModified,
+				metadata: {
+					size: response.ContentLength,
+					contentType: response.ContentType,
+					lastModified: response.LastModified?.toISOString(),
+					etag: response.ETag?.replace(/"/g, ""),
+					versionId: response.VersionId
+				}
+			};
+		} catch (error) {
+			throw mapS3Error(error, `/${ctx.params.path}/@versions/${ctx.params.versionId}`);
+		}
+	}
+	async metaHandler(ctx) {
+		try {
+			const path = ctx.params.path ?? "";
+			const normalizedPath = path.replace(/^\/+/, "").replace(/\/+$/, "");
+			const key = this.options.prefix ? normalizedPath ? `${this.options.prefix}/${normalizedPath}` : this.options.prefix : normalizedPath;
+			if (!key) {
+				const listCommand = new ListObjectsV2Command({
+					Bucket: this.options.bucket,
+					Prefix: this.options.prefix ? `${this.options.prefix}/` : "",
+					Delimiter: "/",
+					MaxKeys: 1e3
+				});
+				const listResponse = await this.client.send(listCommand);
+				const childrenCount = (listResponse.CommonPrefixes?.length ?? 0) + (listResponse.Contents?.length ?? 0);
+				return {
+					id: this.generateId("/"),
+					path: "/.meta",
+					metadata: {
+						kind: "afs:node",
+						childrenCount,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, "", true)
+					}
+				};
+			}
+			if (this.statCache) {
+				const cacheKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", path);
+				const cached = this.statCache.get(cacheKey);
+				if (cached) return {
+					id: cached.id,
+					path: ctx.path,
+					metadata: cached.metadata
+				};
+			}
+			try {
+				const command = new HeadObjectCommand({
+					Bucket: this.options.bucket,
+					Key: key
+				});
+				const response = await this.client.send(command);
+				if (key.endsWith("/") || response.ContentType === "application/x-directory") return {
+					id: this.generateId(key),
+					path: ctx.path,
+					updatedAt: response.LastModified,
+					metadata: {
+						kind: "afs:node",
+						childrenCount: void 0,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, true)
+					}
+				};
+				const result = {
+					id: this.generateId(key),
+					path: ctx.path,
+					updatedAt: response.LastModified,
+					metadata: {
+						kind: "afs:document",
+						size: response.ContentLength,
+						contentType: response.ContentType,
+						lastModified: response.LastModified?.toISOString(),
+						etag: response.ETag?.replace(/"/g, ""),
+						storageClass: response.StorageClass,
+						platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, false)
+					}
+				};
+				if (this.statCache) {
+					const cacheKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", path);
+					this.statCache.set(cacheKey, result);
+				}
+				return result;
+			} catch (error) {
+				if (error?.name === "NotFound" || error?.$metadata?.httpStatusCode === 404) {
+					const listCommand = new ListObjectsV2Command({
+						Bucket: this.options.bucket,
+						Prefix: `${key}/`,
+						MaxKeys: 1
+					});
+					const listResponse = await this.client.send(listCommand);
+					if (listResponse.Contents && listResponse.Contents.length > 0) return {
+						id: this.generateId(`${key}/`),
+						path: ctx.path,
+						metadata: {
+							kind: "afs:node",
+							childrenCount: void 0,
+							platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, true)
+						}
+					};
+					try {
+						const markerCommand = new HeadObjectCommand({
+							Bucket: this.options.bucket,
+							Key: `${key}/`
+						});
+						const markerResponse = await this.client.send(markerCommand);
+						return {
+							id: this.generateId(`${key}/`),
+							path: ctx.path,
+							updatedAt: markerResponse.LastModified,
+							metadata: {
+								kind: "afs:node",
+								childrenCount: void 0,
+								platformRef: generatePlatformRef(this.options.bucket, this.options.region, key, true)
+							}
+						};
+					} catch {
+						throw new AFSNotFoundError(path.startsWith("/") ? path : `/${path}`);
+					}
+				}
+				throw error;
+			}
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapS3Error(error, (ctx.params.path ?? "").startsWith("/") ? ctx.params.path ?? "/" : `/${ctx.params.path ?? ""}`);
+		}
+	}
+	async statHandler(ctx) {
+		const metaEntry = await this.metaHandler({
+			...ctx,
+			path: ctx.path.endsWith("/.meta") ? ctx.path : `${ctx.path}/.meta`
+		});
+		return { data: {
+			path: ctx.path,
+			size: metaEntry.metadata?.size,
+			childrenCount: metaEntry.metadata?.childrenCount,
+			meta: metaEntry.metadata
+		} };
+	}
+	async writeHandler(ctx, payload) {
+		try {
+			const key = this.buildS3Key(ctx.params.path);
+			let body;
+			if (typeof payload.content === "string") body = Buffer.from(payload.content, "utf-8");
+			else if (Buffer.isBuffer(payload.content)) body = payload.content;
+			else if (payload.content !== void 0) body = Buffer.from(JSON.stringify(payload.content), "utf-8");
+			else body = Buffer.from("");
+			const contentType = payload.metadata?.mimeType ?? payload.metadata?.contentType ?? "application/octet-stream";
+			let etag;
+			let versionId;
+			if (shouldUseMultipart(body.length)) {
+				const result = await multipartUpload(this.client, this.options.bucket, key, body, { contentType });
+				etag = result.etag;
+				versionId = result.versionId;
+			} else {
+				const command = new PutObjectCommand({
+					Bucket: this.options.bucket,
+					Key: key,
+					Body: body,
+					ContentType: contentType
+				});
+				const response = await this.client.send(command);
+				etag = response.ETag?.replace(/"/g, "");
+				versionId = response.VersionId;
+			}
+			const normalizedOutputPath = ctx.path.startsWith("/") ? ctx.path : `/${ctx.path}`;
+			this.invalidateCache(ctx.params.path);
+			return { data: {
+				id: this.generateId(key),
+				path: normalizedOutputPath,
+				content: payload.content,
+				metadata: {
+					size: body.length,
+					etag,
+					versionId,
+					...payload.metadata
+				}
+			} };
+		} catch (error) {
+			throw mapS3Error(error, ctx.params.path.startsWith("/") ? ctx.params.path : `/${ctx.params.path}`);
+		}
+	}
+	async deleteHandler(ctx) {
+		try {
+			const key = this.buildS3Key(ctx.params.path);
+			try {
+				const headCommand = new HeadObjectCommand({
+					Bucket: this.options.bucket,
+					Key: key
+				});
+				await this.client.send(headCommand);
+			} catch (error) {
+				if (error?.name === "NotFound" || error?.$metadata?.httpStatusCode === 404) throw new AFSNotFoundError(`/${ctx.params.path}`);
+				throw error;
+			}
+			const command = new DeleteObjectCommand({
+				Bucket: this.options.bucket,
+				Key: key
+			});
+			await this.client.send(command);
+			this.invalidateCache(ctx.params.path);
+			return { message: `Successfully deleted: ${ctx.params.path}` };
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapS3Error(error, `/${ctx.params.path}`);
+		}
+	}
+	async listActionsHandler(ctx) {
+		const basePath = ctx.path.replace(/\/\.actions$/, "");
+		return { data: [
+			{
+				id: "select",
+				path: `${basePath}/.actions/select`,
+				summary: "Query with S3 Select",
+				metadata: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"]
+				}
+			},
+			{
+				id: "presign-download",
+				path: `${basePath}/.actions/presign-download`,
+				summary: "Generate download URL",
+				metadata: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"]
+				}
+			},
+			{
+				id: "presign-upload",
+				path: `${basePath}/.actions/presign-upload`,
+				summary: "Generate upload URL",
+				metadata: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"]
+				}
+			}
+		] };
+	}
+	async selectActionHandler(ctx, args) {
+		const expression = args.expression;
+		if (!expression) throw new AFSError("Missing required argument: expression", "AFS_INVALID_ARGUMENT");
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		const result = await selectQuery(this.client, this.options.bucket, "", key, expression, {
+			inputFormat: args.inputFormat,
+			outputFormat: args.outputFormat
+		});
+		return {
+			success: true,
+			data: {
+				records: result.records,
+				stats: result.stats
+			}
+		};
+	}
+	async presignDownloadActionHandler(ctx, args) {
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		let expiresIn = args.expiresIn ?? DEFAULT_EXPIRES_IN;
+		if (expiresIn > MAX_EXPIRES_IN) expiresIn = MAX_EXPIRES_IN;
+		if (expiresIn < 1) expiresIn = 1;
+		const command = new GetObjectCommand({
+			Bucket: this.options.bucket,
+			Key: key
+		});
+		return {
+			success: true,
+			data: {
+				url: await getSignedUrl(this.client, command, { expiresIn }),
+				expiresAt: new Date(Date.now() + expiresIn * 1e3).toISOString()
+			}
+		};
+	}
+	async presignUploadActionHandler(ctx, args) {
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		let expiresIn = args.expiresIn ?? DEFAULT_EXPIRES_IN;
+		if (expiresIn > MAX_EXPIRES_IN) expiresIn = MAX_EXPIRES_IN;
+		if (expiresIn < 1) expiresIn = 1;
+		const command = new PutObjectCommand({
+			Bucket: this.options.bucket,
+			Key: key,
+			ContentType: args.contentType ?? "application/octet-stream"
+		});
+		return {
+			success: true,
+			data: {
+				url: await getSignedUrl(this.client, command, { expiresIn }),
+				expiresAt: new Date(Date.now() + expiresIn * 1e3).toISOString()
+			}
+		};
+	}
+	/**
+	* Generate a presigned URL for downloading an object
+	* @deprecated Use action /.actions/presign-download instead
+	*/
+	async getPresignedDownloadUrl(path, options) {
+		return (await this.presignDownloadActionHandler({
+			path: `/${path}`,
+			params: { path },
+			options: {}
+		}, { expiresIn: options?.expiresIn })).data.url;
+	}
+	/**
+	* Generate a presigned URL for uploading an object
+	* @deprecated Use action /.actions/presign-upload instead
+	*/
+	async getPresignedUploadUrl(path, options) {
+		return (await this.presignUploadActionHandler({
+			path: `/${path}`,
+			params: { path },
+			options: {}
+		}, {
+			expiresIn: options?.expiresIn,
+			contentType: options?.contentType
+		})).data.url;
+	}
+	/**
+	* List all versions of an object
+	* @deprecated Use list on /:path/@versions instead
+	*/
+	async listVersions(path) {
+		return (await this.listVersionsHandler({
+			path: `/${path}/@versions`,
+			params: { path },
+			options: {}
+		})).data.map((entry) => ({
+			versionId: entry.metadata?.versionId,
+			isLatest: entry.metadata?.isLatest,
+			lastModified: entry.updatedAt,
+			size: entry.metadata?.size ?? 0,
+			etag: entry.metadata?.etag
+		}));
+	}
+	/**
+	* Read a specific version of an object
+	* @deprecated Use read on /:path/@versions/:versionId instead
+	*/
+	async readVersion(path, versionId) {
+		const result = await this.readVersionHandler({
+			path: `/${path}/@versions/${versionId}`,
+			params: {
+				path,
+				versionId
+			},
+			options: {}
+		});
+		return {
+			content: result.content,
+			metadata: result.metadata
+		};
+	}
+	/**
+	* Run a SQL-like query on a CSV/JSON/Parquet file (S3 Select)
+	* @deprecated Use action /.actions/select instead
+	*/
+	async select(path, query, options) {
+		return selectQuery(this.client, this.options.bucket, this.options.prefix ?? "", path, query, options);
+	}
+	/**
+	* Create a directory marker
+	* @deprecated Use write with empty content instead
+	*/
+	async mkdir(path) {
+		const key = this.buildS3Key(path);
+		const dirKey = key.endsWith("/") ? key : `${key}/`;
+		const command = new PutObjectCommand({
+			Bucket: this.options.bucket,
+			Key: dirKey,
+			Body: Buffer.from(""),
+			ContentType: "application/x-directory"
+		});
+		await this.client.send(command);
+	}
+};
+__decorate([List("/"), List("/:path*")], AFSS3.prototype, "listHandler", null);
+__decorate([List("/:path*/@versions")], AFSS3.prototype, "listVersionsHandler", null);
+__decorate([Read("/:path*")], AFSS3.prototype, "readHandler", null);
+__decorate([Read("/:path*/@versions/:versionId")], AFSS3.prototype, "readVersionHandler", null);
+__decorate([Meta("/"), Meta("/:path*")], AFSS3.prototype, "metaHandler", null);
+__decorate([Stat("/"), Stat("/:path*")], AFSS3.prototype, "statHandler", null);
+__decorate([Write("/:path*")], AFSS3.prototype, "writeHandler", null);
+__decorate([Delete("/:path*")], AFSS3.prototype, "deleteHandler", null);
+__decorate([Actions("/:path*")], AFSS3.prototype, "listActionsHandler", null);
+__decorate([Actions.Exec("/:path*", "select")], AFSS3.prototype, "selectActionHandler", null);
+__decorate([Actions.Exec("/:path*", "presign-download")], AFSS3.prototype, "presignDownloadActionHandler", null);
+__decorate([Actions.Exec("/:path*", "presign-upload")], AFSS3.prototype, "presignUploadActionHandler", null);
+
+//#endregion
+export { AFSS3 };
+//# sourceMappingURL=index.mjs.map