@statewalker/webrun-files-s3 0.7.0 → 0.10.0

package/README.md

@@ -50,7 +50,7 @@ console.log(content); // "Hello, S3!"
 
 // List directory contents
 for await (const entry of files.list('/docs')) {
-  console.log(entry.name, entry.kind, entry.size);
+  console.log(entry.name, entry.kind, entry.kind === 'file' ? entry.size : '');
 }
 ```
 
@@ -142,6 +142,28 @@ S3 doesn't have real directories, but this implementation simulates them using:
 - **ListObjectsV2** with `Delimiter="/"` to get "subdirectories" via `CommonPrefixes`
 - Files are returned from `Contents`
 
+With `{ recursive: true }` the delimiter is omitted and only file entries are yielded: directories,
+including empty ones created by `mkdir()`, do not appear in a recursive listing.
+
+Entries come out in path order (code-point order, as every `FilesApi` lists), and `{ after }` is
+sent to S3 as `StartAfter`, so resuming a listing does not re-list what came before. Keys list in
+UTF-8 byte order, which is already that order for files; but a directory `a` arrives as the common
+prefix `a/` *after* keys such as `a-x` and `a.txt` that must follow it. A non-recursive listing
+therefore holds back the few entries a directory still to come could precede, across page
+boundaries, and releases them in order. When a key `a` and keys under `a/` both exist, the path
+`/a` is listed once, as the file — the same answer `stats()` gives.
+
+Because `FileStats` is a discriminated union, this implementation has to commit
+to two things a store without real directories could otherwise leave vague:
+
+- A **common prefix is the directory variant** - `{ kind: "directory" }` and
+  nothing more. There is no size or modification time to report for something
+  that exists only as an artefact of key naming.
+- **Any key ending in `/` is a directory, not a file** — such as the zero-byte
+  marker `mkdir()` writes so an empty directory is visible — and it is skipped
+  when reading `Contents`. Every other key is a file, and a genuinely empty
+  object is the file variant with `size: 0`.
+
 ```typescript
 // List /docs with prefix "my-app"
 // S3 request: ListObjectsV2(Prefix="my-app/docs/", Delimiter="/")
@@ -210,31 +232,26 @@ This implementation works with any S3-compatible storage:
 
 ## Testing
 
-Tests use [testcontainers](https://github.com/testcontainers/testcontainers-node) with MinIO:
+The package has integration tests only. They need Docker and run against a real S3-compatible
+server, [RustFS](https://github.com/rustfs/rustfs), started through
+[testcontainers](https://github.com/testcontainers/testcontainers-node) as a `GenericContainer` of
+`rustfs/rustfs:latest` (override the image with `RUSTFS_IMAGE`). They run the shared
+`createFilesApiTests` and `createBigFilesApiTests` suites from `@statewalker/webrun-files-tests`.
 
-```typescript
-import { MinioContainer } from '@testcontainers/minio';
-import { S3Client, CreateBucketCommand } from '@aws-sdk/client-s3';
-import { S3FilesApi } from '@statewalker/webrun-files-s3';
+```bash
+pnpm test               # unit profile: excludes *.integration.test.ts, so no Docker needed (runs nothing today)
+pnpm test:integration   # Docker: RustFS container, all suites including the 256 MiB big-file suite
+```
 
-const minioContainer = await new MinioContainer().start();
+The client the tests build is the one to use against any S3-compatible server on a custom endpoint:
 
+```typescript
 const s3Client = new S3Client({
-  endpoint: minioContainer.getConnectionUrl(),
+  endpoint: `http://${container.getHost()}:${container.getMappedPort(9000)}`,
   region: 'us-east-1',
-  credentials: {
-    accessKeyId: minioContainer.getUsername(),
-    secretAccessKey: minioContainer.getPassword(),
-  },
+  credentials: { accessKeyId: 'rustfsadmin', secretAccessKey: 'rustfsadmin' },
   forcePathStyle: true,
 });
-
-await s3Client.send(new CreateBucketCommand({ Bucket: 'test-bucket' }));
-
-const files = new S3FilesApi({
-  client: s3Client,
-  bucket: 'test-bucket',
-});
 ```
 
 ## License

package/dist/cjs/index.cjs

@@ -1,11 +1,11 @@
-let __aws_sdk_client_s3 = require("@aws-sdk/client-s3");
-let __statewalker_webrun_files = require("@statewalker/webrun-files");
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _aws_sdk_client_s3 = require("@aws-sdk/client-s3");
+let _statewalker_webrun_files = require("@statewalker/webrun-files");
 //#region src/s3-files-api.ts
 /** Default part size for multipart uploads: 5MB (S3 minimum) */
-const DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+const DEFAULT_PART_SIZE = 5242880;
 /** Threshold for using multipart upload: 5MB */
-const MULTIPART_THRESHOLD = 5 * 1024 * 1024;
+const MULTIPART_THRESHOLD = 5242880;
 /**
 * S3 filesystem implementation of FilesApi.
 *
@@ -24,7 +24,7 @@ var S3FilesApi = class {
 		this.partSize = options.multipartPartSize ?? DEFAULT_PART_SIZE;
 	}
 	resolveKey(path) {
-		const normalized = (0, __statewalker_webrun_files.normalizePath)(path);
+		const normalized = (0, _statewalker_webrun_files.normalizePath)(path);
 		const relativePath = normalized.startsWith("/") ? normalized.substring(1) : normalized;
 		if (this.prefix) return relativePath ? `${this.prefix}/${relativePath}` : this.prefix;
 		return relativePath;
@@ -45,7 +45,7 @@ var S3FilesApi = class {
 			if (length === 0) return;
 			let range;
 			if (start > 0 || length !== void 0) range = `bytes=${start}-${length !== void 0 ? start + length - 1 : ""}`;
-			const command = new __aws_sdk_client_s3.GetObjectCommand({
+			const command = new _aws_sdk_client_s3.GetObjectCommand({
 				Bucket: this.bucket,
 				Key: key,
 				Range: range
@@ -80,7 +80,7 @@ var S3FilesApi = class {
 			buffer = [];
 			bufferSize = 0;
 			if (!uploadId && isLast && partLength < MULTIPART_THRESHOLD) {
-				const command = new __aws_sdk_client_s3.PutObjectCommand({
+				const command = new _aws_sdk_client_s3.PutObjectCommand({
 					Bucket: this.bucket,
 					Key: key,
 					Body: partBuffer,
@@ -90,7 +90,7 @@ var S3FilesApi = class {
 				return;
 			}
 			if (!uploadId) {
-				const createCommand = new __aws_sdk_client_s3.CreateMultipartUploadCommand({
+				const createCommand = new _aws_sdk_client_s3.CreateMultipartUploadCommand({
 					Bucket: this.bucket,
 					Key: key
 				});
@@ -98,7 +98,7 @@ var S3FilesApi = class {
 				if (!UploadId) throw new Error("Failed to create multipart upload");
 				uploadId = UploadId;
 			}
-			const uploadCommand = new __aws_sdk_client_s3.UploadPartCommand({
+			const uploadCommand = new _aws_sdk_client_s3.UploadPartCommand({
 				Bucket: this.bucket,
 				Key: key,
 				UploadId: uploadId,
@@ -121,7 +121,7 @@ var S3FilesApi = class {
 			}
 			await flushPart(true);
 			if (uploadId) {
-				const completeCommand = new __aws_sdk_client_s3.CompleteMultipartUploadCommand({
+				const completeCommand = new _aws_sdk_client_s3.CompleteMultipartUploadCommand({
 					Bucket: this.bucket,
 					Key: key,
 					UploadId: uploadId,
@@ -131,7 +131,7 @@ var S3FilesApi = class {
 			}
 		} catch (error) {
 			if (uploadId) {
-				const abortCommand = new __aws_sdk_client_s3.AbortMultipartUploadCommand({
+				const abortCommand = new _aws_sdk_client_s3.AbortMultipartUploadCommand({
 					Bucket: this.bucket,
 					Key: key,
 					UploadId: uploadId
@@ -146,65 +146,108 @@ var S3FilesApi = class {
 	async mkdir(path) {
 		const key = this.resolveKey(path);
 		const dirKey = key.endsWith("/") ? key : `${key}/`;
-		const command = new __aws_sdk_client_s3.PutObjectCommand({
+		const command = new _aws_sdk_client_s3.PutObjectCommand({
 			Bucket: this.bucket,
 			Key: dirKey,
-			Body: new Uint8Array(0),
+			Body: /* @__PURE__ */ new Uint8Array(0),
 			ContentLength: 0
 		});
 		await this.client.send(command);
 	}
+	/**
+	* Keys list in UTF-8 byte order, which is `comparePaths` order for files.
+	* A recursive listing is therefore already ordered. A non-recursive one is
+	* not quite: the directory `a` arrives as the common prefix `a/`, after keys
+	* such as `a-x` and `a.txt` that must follow it, so entries pass through a
+	* small reorder buffer (see {@link releaseBound}).
+	*/
 	async *list(path, options) {
 		const recursive = options?.recursive ?? false;
+		const after = options?.after;
+		const dirPath = (0, _statewalker_webrun_files.normalizePath)(path);
 		const prefix = this.resolveKey(path);
 		const normalizedPrefix = prefix ? `${prefix}/` : this.prefix ? `${this.prefix}/` : "";
+		const dirPrefix = dirPath === "/" ? "" : dirPath;
+		let startAfter;
+		if (after !== void 0) {
+			if (after.startsWith(`${dirPrefix}/`)) startAfter = normalizedPrefix + after.slice(dirPrefix.length + 1);
+			else if ((0, _statewalker_webrun_files.comparePaths)(after, `${dirPrefix}/`) >= 0) return;
+		}
+		const pending = [];
+		let released;
+		const release = (entry) => {
+			if (entry.path === released) return false;
+			released = entry.path;
+			return after === void 0 || (0, _statewalker_webrun_files.comparePaths)(entry.path, after) > 0;
+		};
 		let continuationToken;
 		do {
-			const command = new __aws_sdk_client_s3.ListObjectsV2Command({
+			const command = new _aws_sdk_client_s3.ListObjectsV2Command({
 				Bucket: this.bucket,
 				Prefix: normalizedPrefix,
 				Delimiter: recursive ? void 0 : "/",
 				ContinuationToken: continuationToken,
+				StartAfter: continuationToken ? void 0 : startAfter,
 				MaxKeys: 1e3
 			});
 			const response = await this.client.send(command);
-			if (!recursive && response.CommonPrefixes) for (const cpPrefix of response.CommonPrefixes) {
+			const page = [];
+			for (const cpPrefix of recursive ? [] : response.CommonPrefixes ?? []) {
 				if (!cpPrefix.Prefix) continue;
 				const dirKey = cpPrefix.Prefix.endsWith("/") ? cpPrefix.Prefix.slice(0, -1) : cpPrefix.Prefix;
-				const dirPath = this.keyToPath(dirKey);
-				yield {
-					kind: "directory",
-					name: (0, __statewalker_webrun_files.basename)(dirPath),
-					path: dirPath,
-					lastModified: 0
-				};
+				const childPath = this.keyToPath(dirKey);
+				page.push({
+					key: cpPrefix.Prefix,
+					entry: {
+						kind: "directory",
+						name: (0, _statewalker_webrun_files.basename)(childPath),
+						path: childPath
+					}
+				});
 			}
-			if (response.Contents) for (const obj of response.Contents) {
+			for (const obj of response.Contents ?? []) {
 				if (!obj.Key) continue;
 				if (obj.Key === normalizedPrefix) continue;
 				if (`${obj.Key}/` === normalizedPrefix) continue;
-				if (obj.Key.endsWith("/")) continue;
+				if (obj.Key.endsWith("/")) {
+					page.push({ key: obj.Key });
+					continue;
+				}
 				const filePath = this.keyToPath(obj.Key);
-				yield {
-					kind: "file",
-					name: (0, __statewalker_webrun_files.basename)(filePath),
-					path: filePath,
-					size: obj.Size ?? 0,
-					lastModified: obj.LastModified?.getTime() ?? 0
-				};
+				page.push({
+					key: obj.Key,
+					entry: {
+						kind: "file",
+						name: (0, _statewalker_webrun_files.basename)(filePath),
+						path: filePath,
+						size: obj.Size ?? 0,
+						lastModified: obj.LastModified?.getTime() ?? 0
+					}
+				});
+			}
+			page.sort((x, y) => (0, _statewalker_webrun_files.comparePaths)(x.key, y.key));
+			for (const { key, entry } of page) {
+				if (recursive) {
+					if (entry && release(entry)) yield entry;
+					continue;
+				}
+				if (entry) insertInOrder(pending, entry);
+				const bound = releaseBound(this.keyToPath(key));
+				while (pending.length > 0 && (0, _statewalker_webrun_files.comparePaths)(pending[0].path, bound) < 0) {
+					const next = pending.shift();
+					if (release(next)) yield next;
+				}
 			}
 			continuationToken = response.NextContinuationToken;
 		} while (continuationToken);
+		for (const entry of pending) if (release(entry)) yield entry;
 	}
 	async stats(path) {
-		const normalized = (0, __statewalker_webrun_files.normalizePath)(path);
+		const normalized = (0, _statewalker_webrun_files.normalizePath)(path);
 		const key = this.resolveKey(path);
-		if (normalized === "/") return {
-			kind: "directory",
-			lastModified: 0
-		};
+		if (normalized === "/") return { kind: "directory" };
 		try {
-			const command = new __aws_sdk_client_s3.HeadObjectCommand({
+			const command = new _aws_sdk_client_s3.HeadObjectCommand({
 				Bucket: this.bucket,
 				Key: key
 			});
@@ -219,16 +262,13 @@ var S3FilesApi = class {
 			if (err.name !== "NotFound" && err.$metadata?.httpStatusCode !== 404) throw error;
 		}
 		const prefix = key ? `${key}/` : "";
-		const listCommand = new __aws_sdk_client_s3.ListObjectsV2Command({
+		const listCommand = new _aws_sdk_client_s3.ListObjectsV2Command({
 			Bucket: this.bucket,
 			Prefix: prefix,
 			MaxKeys: 1
 		});
 		const listResponse = await this.client.send(listCommand);
-		if (listResponse.Contents && listResponse.Contents.length > 0 || listResponse.CommonPrefixes && listResponse.CommonPrefixes.length > 0) return {
-			kind: "directory",
-			lastModified: 0
-		};
+		if (listResponse.Contents && listResponse.Contents.length > 0 || listResponse.CommonPrefixes && listResponse.CommonPrefixes.length > 0) return { kind: "directory" };
 	}
 	async exists(path) {
 		return await this.stats(path) !== void 0;
@@ -236,12 +276,12 @@ var S3FilesApi = class {
 	async remove(path) {
 		const key = this.resolveKey(path);
 		try {
-			const headCommand = new __aws_sdk_client_s3.HeadObjectCommand({
+			const headCommand = new _aws_sdk_client_s3.HeadObjectCommand({
 				Bucket: this.bucket,
 				Key: key
 			});
 			await this.client.send(headCommand);
-			const deleteCommand = new __aws_sdk_client_s3.DeleteObjectCommand({
+			const deleteCommand = new _aws_sdk_client_s3.DeleteObjectCommand({
 				Bucket: this.bucket,
 				Key: key
 			});
@@ -255,7 +295,7 @@ var S3FilesApi = class {
 		const keysToDelete = [];
 		let continuationToken;
 		do {
-			const listCommand = new __aws_sdk_client_s3.ListObjectsV2Command({
+			const listCommand = new _aws_sdk_client_s3.ListObjectsV2Command({
 				Bucket: this.bucket,
 				Prefix: prefix,
 				ContinuationToken: continuationToken
@@ -268,7 +308,7 @@ var S3FilesApi = class {
 		} while (continuationToken);
 		if (keysToDelete.length === 0) return false;
 		for (const keyToDelete of keysToDelete) {
-			const deleteCommand = new __aws_sdk_client_s3.DeleteObjectCommand({
+			const deleteCommand = new _aws_sdk_client_s3.DeleteObjectCommand({
 				Bucket: this.bucket,
 				Key: keyToDelete
 			});
@@ -286,7 +326,7 @@ var S3FilesApi = class {
 		const sourceStats = await this.stats(source);
 		if (!sourceStats) return false;
 		if (sourceStats.kind === "file") {
-			const command = new __aws_sdk_client_s3.CopyObjectCommand({
+			const command = new _aws_sdk_client_s3.CopyObjectCommand({
 				Bucket: this.bucket,
 				Key: targetKey,
 				CopySource: encodeURIComponent(`${this.bucket}/${sourceKey}`)
@@ -299,7 +339,7 @@ var S3FilesApi = class {
 		let continuationToken;
 		let copied = false;
 		do {
-			const listCommand = new __aws_sdk_client_s3.ListObjectsV2Command({
+			const listCommand = new _aws_sdk_client_s3.ListObjectsV2Command({
 				Bucket: this.bucket,
 				Prefix: sourcePrefix,
 				ContinuationToken: continuationToken
@@ -308,7 +348,7 @@ var S3FilesApi = class {
 			if (response.Contents) for (const obj of response.Contents) {
 				if (!obj.Key) continue;
 				const newKey = targetPrefix + obj.Key.substring(sourcePrefix.length);
-				const copyCommand = new __aws_sdk_client_s3.CopyObjectCommand({
+				const copyCommand = new _aws_sdk_client_s3.CopyObjectCommand({
 					Bucket: this.bucket,
 					Key: newKey,
 					CopySource: encodeURIComponent(`${this.bucket}/${obj.Key}`)
@@ -321,6 +361,21 @@ var S3FilesApi = class {
 		return copied;
 	}
 };
-
+/**
+* Once a delimited listing has reached key position `position` (as a path), a
+* directory still to come — which arrives as `D + "/"` at or after that
+* position — has a path of at least this bound: the shortest prefix of
+* `position` followed by a character that sorts before `/`, or `position`
+* itself if there is none. Buffered entries below the bound are final.
+*/
+function releaseBound(position) {
+	for (let i = 0; i < position.length; i++) if (position.charCodeAt(i) < 47) return position.slice(0, i);
+	return position;
+}
+function insertInOrder(entries, entry) {
+	let i = entries.length;
+	while (i > 0 && (0, _statewalker_webrun_files.comparePaths)(entries[i - 1].path, entry.path) > 0) i--;
+	entries.splice(i, 0, entry);
+}
 //#endregion
-exports.S3FilesApi = S3FilesApi;
+exports.S3FilesApi = S3FilesApi;

package/dist/esm/index.js

@@ -1,11 +1,10 @@
 import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CopyObjectCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, UploadPartCommand } from "@aws-sdk/client-s3";
-import { basename, normalizePath } from "@statewalker/webrun-files";
-
+import { basename, comparePaths, normalizePath } from "@statewalker/webrun-files";
 //#region src/s3-files-api.ts
 /** Default part size for multipart uploads: 5MB (S3 minimum) */
-const DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+const DEFAULT_PART_SIZE = 5242880;
 /** Threshold for using multipart upload: 5MB */
-const MULTIPART_THRESHOLD = 5 * 1024 * 1024;
+const MULTIPART_THRESHOLD = 5242880;
 /**
 * S3 filesystem implementation of FilesApi.
 *
@@ -149,15 +148,37 @@ var S3FilesApi = class {
 		const command = new PutObjectCommand({
 			Bucket: this.bucket,
 			Key: dirKey,
-			Body: new Uint8Array(0),
+			Body: /* @__PURE__ */ new Uint8Array(0),
 			ContentLength: 0
 		});
 		await this.client.send(command);
 	}
+	/**
+	* Keys list in UTF-8 byte order, which is `comparePaths` order for files.
+	* A recursive listing is therefore already ordered. A non-recursive one is
+	* not quite: the directory `a` arrives as the common prefix `a/`, after keys
+	* such as `a-x` and `a.txt` that must follow it, so entries pass through a
+	* small reorder buffer (see {@link releaseBound}).
+	*/
 	async *list(path, options) {
 		const recursive = options?.recursive ?? false;
+		const after = options?.after;
+		const dirPath = normalizePath(path);
 		const prefix = this.resolveKey(path);
 		const normalizedPrefix = prefix ? `${prefix}/` : this.prefix ? `${this.prefix}/` : "";
+		const dirPrefix = dirPath === "/" ? "" : dirPath;
+		let startAfter;
+		if (after !== void 0) {
+			if (after.startsWith(`${dirPrefix}/`)) startAfter = normalizedPrefix + after.slice(dirPrefix.length + 1);
+			else if (comparePaths(after, `${dirPrefix}/`) >= 0) return;
+		}
+		const pending = [];
+		let released;
+		const release = (entry) => {
+			if (entry.path === released) return false;
+			released = entry.path;
+			return after === void 0 || comparePaths(entry.path, after) > 0;
+		};
 		let continuationToken;
 		do {
 			const command = new ListObjectsV2Command({
@@ -165,44 +186,65 @@ var S3FilesApi = class {
 				Prefix: normalizedPrefix,
 				Delimiter: recursive ? void 0 : "/",
 				ContinuationToken: continuationToken,
+				StartAfter: continuationToken ? void 0 : startAfter,
 				MaxKeys: 1e3
 			});
 			const response = await this.client.send(command);
-			if (!recursive && response.CommonPrefixes) for (const cpPrefix of response.CommonPrefixes) {
+			const page = [];
+			for (const cpPrefix of recursive ? [] : response.CommonPrefixes ?? []) {
 				if (!cpPrefix.Prefix) continue;
 				const dirKey = cpPrefix.Prefix.endsWith("/") ? cpPrefix.Prefix.slice(0, -1) : cpPrefix.Prefix;
-				const dirPath = this.keyToPath(dirKey);
-				yield {
-					kind: "directory",
-					name: basename(dirPath),
-					path: dirPath,
-					lastModified: 0
-				};
+				const childPath = this.keyToPath(dirKey);
+				page.push({
+					key: cpPrefix.Prefix,
+					entry: {
+						kind: "directory",
+						name: basename(childPath),
+						path: childPath
+					}
+				});
 			}
-			if (response.Contents) for (const obj of response.Contents) {
+			for (const obj of response.Contents ?? []) {
 				if (!obj.Key) continue;
 				if (obj.Key === normalizedPrefix) continue;
 				if (`${obj.Key}/` === normalizedPrefix) continue;
-				if (obj.Key.endsWith("/")) continue;
+				if (obj.Key.endsWith("/")) {
+					page.push({ key: obj.Key });
+					continue;
+				}
 				const filePath = this.keyToPath(obj.Key);
-				yield {
-					kind: "file",
-					name: basename(filePath),
-					path: filePath,
-					size: obj.Size ?? 0,
-					lastModified: obj.LastModified?.getTime() ?? 0
-				};
+				page.push({
+					key: obj.Key,
+					entry: {
+						kind: "file",
+						name: basename(filePath),
+						path: filePath,
+						size: obj.Size ?? 0,
+						lastModified: obj.LastModified?.getTime() ?? 0
+					}
+				});
+			}
+			page.sort((x, y) => comparePaths(x.key, y.key));
+			for (const { key, entry } of page) {
+				if (recursive) {
+					if (entry && release(entry)) yield entry;
+					continue;
+				}
+				if (entry) insertInOrder(pending, entry);
+				const bound = releaseBound(this.keyToPath(key));
+				while (pending.length > 0 && comparePaths(pending[0].path, bound) < 0) {
+					const next = pending.shift();
+					if (release(next)) yield next;
+				}
 			}
 			continuationToken = response.NextContinuationToken;
 		} while (continuationToken);
+		for (const entry of pending) if (release(entry)) yield entry;
 	}
 	async stats(path) {
 		const normalized = normalizePath(path);
 		const key = this.resolveKey(path);
-		if (normalized === "/") return {
-			kind: "directory",
-			lastModified: 0
-		};
+		if (normalized === "/") return { kind: "directory" };
 		try {
 			const command = new HeadObjectCommand({
 				Bucket: this.bucket,
@@ -225,10 +267,7 @@ var S3FilesApi = class {
 			MaxKeys: 1
 		});
 		const listResponse = await this.client.send(listCommand);
-		if (listResponse.Contents && listResponse.Contents.length > 0 || listResponse.CommonPrefixes && listResponse.CommonPrefixes.length > 0) return {
-			kind: "directory",
-			lastModified: 0
-		};
+		if (listResponse.Contents && listResponse.Contents.length > 0 || listResponse.CommonPrefixes && listResponse.CommonPrefixes.length > 0) return { kind: "directory" };
 	}
 	async exists(path) {
 		return await this.stats(path) !== void 0;
@@ -321,6 +360,21 @@ var S3FilesApi = class {
 		return copied;
 	}
 };
-
+/**
+* Once a delimited listing has reached key position `position` (as a path), a
+* directory still to come — which arrives as `D + "/"` at or after that
+* position — has a path of at least this bound: the shortest prefix of
+* `position` followed by a character that sorts before `/`, or `position`
+* itself if there is none. Buffered entries below the bound are final.
+*/
+function releaseBound(position) {
+	for (let i = 0; i < position.length; i++) if (position.charCodeAt(i) < 47) return position.slice(0, i);
+	return position;
+}
+function insertInOrder(entries, entry) {
+	let i = entries.length;
+	while (i > 0 && comparePaths(entries[i - 1].path, entry.path) > 0) i--;
+	entries.splice(i, 0, entry);
+}
 //#endregion
-export { S3FilesApi };
+export { S3FilesApi };

package/dist/s3-files-api.d.ts

@@ -43,6 +43,13 @@ export declare class S3FilesApi implements FilesApi {
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
     mkdir(path: string): Promise<void>;
+    /**
+     * Keys list in UTF-8 byte order, which is `comparePaths` order for files.
+     * A recursive listing is therefore already ordered. A non-recursive one is
+     * not quite: the directory `a` arrives as the common prefix `a/`, after keys
+     * such as `a-x` and `a.txt` that must follow it, so entries pass through a
+     * small reorder buffer (see {@link releaseBound}).
+     */
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;

package/dist/s3-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"s3-files-api.d.ts","sourceRoot":"","sources":["../src/s3-files-api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAanD,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,MAAM,EAAE,QAAQ,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,QAAQ;IACzC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,iBAAiB;IAOtC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,SAAS;IAWV,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IA+CrE,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAoHV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IA4DnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAuDnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoEtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAyD7D"}
+{"version":3,"file":"s3-files-api.d.ts","sourceRoot":"","sources":["../src/s3-files-api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAanD,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,MAAM,EAAE,QAAQ,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,QAAQ;IACzC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,OAAO,EAAE,iBAAiB,EAKrC;IAED,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,SAAS;IAWV,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CA6C1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAkHf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvC;IAED;;;;;;OAMG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CA0GxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CA+CxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAkE3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAwD3D;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-s3",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "private": false,
   "type": "module",
   "description": "S3-backed FilesApi implementation for webrun-files",
@@ -29,21 +29,20 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "0.7.0"
+    "@statewalker/webrun-files": "0.10.0"
   },
   "peerDependencies": {
-    "@aws-sdk/client-s3": "^3.0.0"
+    "@aws-sdk/client-s3": "^3.1032.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.0.0",
-    "@testcontainers/minio": "^10.0.0",
-    "@types/node": "^24.10.1",
-    "rimraf": "^6.1.2",
-    "rolldown": "^1.0.0-beta.53",
-    "testcontainers": "^10.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^4.0.12",
-    "@statewalker/webrun-files-tests": "1.0.0"
+    "@aws-sdk/client-s3": "^3.1110.0",
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "testcontainers": "^12.1.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-files-tests": "3.0.0"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -51,7 +50,8 @@
   },
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
-    "test": "vitest run",
-    "lint": "biome lint src tests"
+    "lint": "biome lint src tests",
+    "test": "vitest run --passWithNoTests",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
   }
 }

package/src/s3-files-api.ts

@@ -24,7 +24,7 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
-import { basename, normalizePath } from "@statewalker/webrun-files";
+import { basename, comparePaths, normalizePath } from "@statewalker/webrun-files";
 
 /** Default part size for multipart uploads: 5MB (S3 minimum) */
 const DEFAULT_PART_SIZE = 5 * 1024 * 1024;
@@ -277,11 +277,42 @@ export class S3FilesApi implements FilesApi {
     await this.client.send(command);
   }
 
+  /**
+   * Keys list in UTF-8 byte order, which is `comparePaths` order for files.
+   * A recursive listing is therefore already ordered. A non-recursive one is
+   * not quite: the directory `a` arrives as the common prefix `a/`, after keys
+   * such as `a-x` and `a.txt` that must follow it, so entries pass through a
+   * small reorder buffer (see {@link releaseBound}).
+   */
   async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
     const recursive = options?.recursive ?? false;
+    const after = options?.after;
+    const dirPath = normalizePath(path);
     const prefix = this.resolveKey(path);
     const normalizedPrefix = prefix ? `${prefix}/` : this.prefix ? `${this.prefix}/` : "";
 
+    // `after` as a key, by raw prefix replacement: normalising the path could
+    // move the cursor past entries that sort after it.
+    const dirPrefix = dirPath === "/" ? "" : dirPath;
+    let startAfter: string | undefined;
+    if (after !== undefined) {
+      if (after.startsWith(`${dirPrefix}/`)) {
+        startAfter = normalizedPrefix + after.slice(dirPrefix.length + 1);
+      } else if (comparePaths(after, `${dirPrefix}/`) >= 0) {
+        return; // the whole directory lies at or before the cursor
+      }
+    }
+
+    const pending: FileInfo[] = [];
+    // A key `a` and keys under `a/` make a file and a directory with the same
+    // path. A listing is strictly increasing, so the first released — the file,
+    // as `stats` also reports — is kept.
+    let released: string | undefined;
+    const release = (entry: FileInfo): boolean => {
+      if (entry.path === released) return false;
+      released = entry.path;
+      return after === undefined || comparePaths(entry.path, after) > 0;
+    };
     let continuationToken: string | undefined;
 
     do {
@@ -290,51 +321,75 @@ export class S3FilesApi implements FilesApi {
         Prefix: normalizedPrefix,
         Delimiter: recursive ? undefined : "/",
         ContinuationToken: continuationToken,
+        StartAfter: continuationToken ? undefined : startAfter,
         MaxKeys: 1000,
       });
 
       const response = await this.client.send(command);
 
-      if (!recursive && response.CommonPrefixes) {
-        for (const cpPrefix of response.CommonPrefixes) {
-          if (!cpPrefix.Prefix) continue;
-
-          const dirKey = cpPrefix.Prefix.endsWith("/")
-            ? cpPrefix.Prefix.slice(0, -1)
-            : cpPrefix.Prefix;
-
-          const dirPath = this.keyToPath(dirKey);
-
-          yield {
-            kind: "directory",
-            name: basename(dirPath),
-            path: dirPath,
-            lastModified: 0,
-          };
-        }
+      // Common prefixes and contents each come sorted; interleave them by key.
+      const page: { key: string; entry?: FileInfo }[] = [];
+      for (const cpPrefix of recursive ? [] : (response.CommonPrefixes ?? [])) {
+        if (!cpPrefix.Prefix) continue;
+        const dirKey = cpPrefix.Prefix.endsWith("/")
+          ? cpPrefix.Prefix.slice(0, -1)
+          : cpPrefix.Prefix;
+        const childPath = this.keyToPath(dirKey);
+        // A common prefix IS the directory variant: it exists only as an
+        // artefact of key naming, so there is nothing to report about it
+        // beyond its being a directory.
+        page.push({
+          key: cpPrefix.Prefix,
+          entry: { kind: "directory", name: basename(childPath), path: childPath },
+        });
       }
-
-      if (response.Contents) {
-        for (const obj of response.Contents) {
-          if (!obj.Key) continue;
-          if (obj.Key === normalizedPrefix) continue;
-          if (`${obj.Key}/` === normalizedPrefix) continue;
-          if (obj.Key.endsWith("/")) continue;
-
-          const filePath = this.keyToPath(obj.Key);
-
-          yield {
+      for (const obj of response.Contents ?? []) {
+        if (!obj.Key) continue;
+        if (obj.Key === normalizedPrefix) continue;
+        if (`${obj.Key}/` === normalizedPrefix) continue;
+        // A key ending in "/" is the zero-byte marker `mkdir` writes to make
+        // an empty directory visible. It is NOT a file with `size: 0` — it
+        // is how this store spells a directory, and it surfaces through
+        // `CommonPrefixes` above. Every other key is a file, and a genuinely
+        // empty object is the file variant with `size: 0`. It still moves
+        // the listing's position forward.
+        if (obj.Key.endsWith("/")) {
+          page.push({ key: obj.Key });
+          continue;
+        }
+        const filePath = this.keyToPath(obj.Key);
+        page.push({
+          key: obj.Key,
+          entry: {
             kind: "file",
             name: basename(filePath),
             path: filePath,
             size: obj.Size ?? 0,
             lastModified: obj.LastModified?.getTime() ?? 0,
-          };
+          },
+        });
+      }
+      page.sort((x, y) => comparePaths(x.key, y.key));
+
+      for (const { key, entry } of page) {
+        if (recursive) {
+          if (entry && release(entry)) yield entry;
+          continue;
+        }
+        if (entry) insertInOrder(pending, entry);
+        const bound = releaseBound(this.keyToPath(key));
+        while (pending.length > 0 && comparePaths(pending[0].path, bound) < 0) {
+          const next = pending.shift() as FileInfo;
+          if (release(next)) yield next;
         }
       }
 
       continuationToken = response.NextContinuationToken;
     } while (continuationToken);
+
+    for (const entry of pending) {
+      if (release(entry)) yield entry;
+    }
   }
 
   async stats(path: string): Promise<FileStats | undefined> {
@@ -342,10 +397,7 @@ export class S3FilesApi implements FilesApi {
     const key = this.resolveKey(path);
 
     if (normalized === "/") {
-      return {
-        kind: "directory",
-        lastModified: 0,
-      };
+      return { kind: "directory" };
     }
 
     // Try as file first
@@ -383,10 +435,7 @@ export class S3FilesApi implements FilesApi {
       (listResponse.Contents && listResponse.Contents.length > 0) ||
       (listResponse.CommonPrefixes && listResponse.CommonPrefixes.length > 0)
     ) {
-      return {
-        kind: "directory",
-        lastModified: 0,
-      };
+      return { kind: "directory" };
     }
 
     return undefined;
@@ -529,3 +578,24 @@ export class S3FilesApi implements FilesApi {
     return copied;
   }
 }
+
+/**
+ * Once a delimited listing has reached key position `position` (as a path), a
+ * directory still to come — which arrives as `D + "/"` at or after that
+ * position — has a path of at least this bound: the shortest prefix of
+ * `position` followed by a character that sorts before `/`, or `position`
+ * itself if there is none. Buffered entries below the bound are final.
+ */
+function releaseBound(position: string): string {
+  for (let i = 0; i < position.length; i++) {
+    if (position.charCodeAt(i) < 0x2f) return position.slice(0, i);
+  }
+  return position;
+}
+
+function insertInOrder(entries: FileInfo[], entry: FileInfo): void {
+  let i = entries.length;
+  // Equal paths keep arrival order: a file arrives before its same-named prefix.
+  while (i > 0 && comparePaths(entries[i - 1].path, entry.path) > 0) i--;
+  entries.splice(i, 0, entry);
+}