@statewalker/webrun-files-s3 0.7.0 → 0.9.0

package/README.md

@@ -142,6 +142,17 @@ 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`
 
+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
+  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="/")

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,10 +146,10 @@ 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);
@@ -160,7 +160,7 @@ var S3FilesApi = class {
 		const normalizedPrefix = prefix ? `${prefix}/` : this.prefix ? `${this.prefix}/` : "";
 		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 : "/",
@@ -174,9 +174,8 @@ var S3FilesApi = class {
 				const dirPath = this.keyToPath(dirKey);
 				yield {
 					kind: "directory",
-					name: (0, __statewalker_webrun_files.basename)(dirPath),
-					path: dirPath,
-					lastModified: 0
+					name: (0, _statewalker_webrun_files.basename)(dirPath),
+					path: dirPath
 				};
 			}
 			if (response.Contents) for (const obj of response.Contents) {
@@ -187,7 +186,7 @@ var S3FilesApi = class {
 				const filePath = this.keyToPath(obj.Key);
 				yield {
 					kind: "file",
-					name: (0, __statewalker_webrun_files.basename)(filePath),
+					name: (0, _statewalker_webrun_files.basename)(filePath),
 					path: filePath,
 					size: obj.Size ?? 0,
 					lastModified: obj.LastModified?.getTime() ?? 0
@@ -197,14 +196,11 @@ var S3FilesApi = class {
 		} while (continuationToken);
 	}
 	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 +215,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 +229,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 +248,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 +261,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 +279,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 +292,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 +301,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 +314,5 @@ var S3FilesApi = class {
 		return copied;
 	}
 };
-
 //#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";
-
 //#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,7 +148,7 @@ 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);
@@ -175,8 +174,7 @@ var S3FilesApi = class {
 				yield {
 					kind: "directory",
 					name: basename(dirPath),
-					path: dirPath,
-					lastModified: 0
+					path: dirPath
 				};
 			}
 			if (response.Contents) for (const obj of response.Contents) {
@@ -199,10 +197,7 @@ var S3FilesApi = class {
 	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 +220,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 +313,5 @@ var S3FilesApi = class {
 		return copied;
 	}
 };
-
 //#endregion
-export { S3FilesApi };
+export { S3FilesApi };

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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-s3",
-  "version": "0.7.0",
+  "version": "0.9.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.9.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": "2.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

@@ -305,11 +305,13 @@ export class S3FilesApi implements FilesApi {
 
           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,
-            lastModified: 0,
           };
         }
       }
@@ -319,6 +321,11 @@ export class S3FilesApi implements FilesApi {
           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);
@@ -342,10 +349,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 +387,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;