@statewalker/webrun-files-s3 0.9.0 → 0.10.2

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,14 +142,25 @@ 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.
-- A **zero-byte key ending in `/` is a directory, not a file**. That is the
-  marker `mkdir()` writes so an empty directory is visible, and it is skipped
+- **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`.
 
@@ -221,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

@@ -154,10 +154,32 @@ var S3FilesApi = class {
 		});
 		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({
@@ -165,35 +187,60 @@ 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: (0, _statewalker_webrun_files.basename)(dirPath),
-					path: dirPath
-				};
+				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);
@@ -314,5 +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;

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 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 = 5242880;
@@ -153,10 +153,32 @@ var S3FilesApi = class {
 		});
 		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({
@@ -164,35 +186,60 @@ 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
-				};
+				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);
@@ -313,5 +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 };

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;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;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAiExE;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"}
+{"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.9.0",
+  "version": "0.10.2",
   "private": false,
   "type": "module",
   "description": "S3-backed FilesApi implementation for webrun-files",
@@ -19,6 +19,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.cjs"
@@ -29,20 +30,20 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "0.9.0"
+    "@statewalker/webrun-files": "^0.10.1"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.1032.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.1110.0",
-    "@types/node": "^26.2.0",
+    "@aws-sdk/client-s3": "^3.1146.0",
+    "@types/node": "^26.6.4",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
-    "testcontainers": "^12.1.0",
+    "rolldown": "^1.2.12",
+    "testcontainers": "^12.2.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10",
-    "@statewalker/webrun-files-tests": "2.0.0"
+    "vitest": "^5.0.3",
+    "@statewalker/webrun-files-tests": "^3.0.0"
   },
   "sideEffects": false,
   "publishConfig": {

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,58 +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);
-
-          // 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.
-          yield {
-            kind: "directory",
-            name: basename(dirPath),
-            path: dirPath,
-          };
-        }
+      // 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;
-          // 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`.
-          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> {
@@ -530,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);
+}