@bymax-one/nest-storage 1.1.4 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -13,6 +13,52 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.5] - 2026-11-01
17
+
18
+ ### Fixed
19
+
20
+ - **With a `keyPrefix`, a post-upload scan never removed the object it rejected.** The cleanup passed
21
+ the already-prefixed key to `delete()`, which prefixes it again, so it deleted `prefix/prefix/key`
22
+ (nothing), succeeded, and the rejected object stayed stored: no error beyond the scan verdict and no
23
+ log line. The cleanup now targets the object's real key.
24
+ - **A failed cleanup or abort is no longer reported as a clean outcome.** These paths told the caller
25
+ one thing while the provider held another:
26
+ - A `post-upload` scan that rejected an object deleted it and rejected with the verdict; when that
27
+ delete failed, the caller saw only the verdict (`STORAGE_SCAN_INFECTED`) while the object stayed
28
+ stored, and the failure was a log line. The verdict is still the error, and its `details` now
29
+ carry `cleanup: 'failed'`, the `key` and the delete failure (`cleanupError`); the log line is at
30
+ error level with the code `STORAGE_SCAN_CLEANUP_FAILED`.
31
+ - A multipart upload whose `CompleteMultipartUpload` failed was reported as aborted but was never
32
+ aborted: the upload and its parts stayed open on the provider. The library now sends
33
+ `AbortMultipartUpload` itself.
34
+ - When the abort also failed, the SDK threw the abort failure in place of the failure that caused
35
+ it. The original failure is now the error, and `details.abort` is `'completed'` or `'failed'`
36
+ (with `abortError`). The same holds for the silent-source abort (`STORAGE_TIMEOUT`,
37
+ `details.phase: 'source-idle'`).
38
+ - After `delete()` or `deleteMany()` removed an object, a repeated `upload()` with the same
39
+ `idempotencyKey` was answered from the cache with a success (`fromIdempotencyCache: true`) for an
40
+ object that no longer existed. Both now drop the cache entries of the objects they delete. The
41
+ cache is per instance, so a delete made by another replica or outside the library still does not
42
+ reach it.
43
+
44
+ **Apply to a derived backend:** if you use a `keyPrefix` together with a `post-upload` scanner,
45
+ **audit your bucket** for objects that failed a scan in an earlier version: they were never removed
46
+ and nothing was logged, so your logs will not list them. Re-scan the prefix, or delete what your
47
+ scanner flagged. Error shapes also change, not codes. Code that reads `error.details` of
48
+ `STORAGE_SCAN_INFECTED`, `STORAGE_SCAN_INCONCLUSIVE`, `STORAGE_MULTIPART_ABORTED` or the
49
+ source-idle `STORAGE_TIMEOUT` gains the fields above: treat `details.cleanup === 'failed'` as
50
+ "rejected but still stored" and alert on it. A failed multipart upload now costs one more request,
51
+ the `AbortMultipartUpload` the SDK used to send (the credentials already needed
52
+ `s3:AbortMultipartUpload`). A repeated `upload()` after a `delete()` now stores the object again
53
+ instead of returning the earlier result. `exists()` is unchanged and still returns `false` for any
54
+ failure that is not a 404; the README now says so next to the method.
55
+
56
+ ### Changed
57
+
58
+ - **The Stryker gate is 100.** `stryker.config.json` now fails a mutation run below 100 (`thresholds.break`
59
+ and `low` were 95), and the README states the gate. Equivalent mutants stay documented inline; the gate is
60
+ not lowered. Nothing in the published code changes.
61
+
16
62
  ## [1.1.4] - 2026-11-01
17
63
 
18
64
  ### Changed
@@ -507,4 +553,5 @@ have regressed from. They are kept because the reasoning is worth having.
507
553
  [1.1.2]: https://github.com/bymaxone/nest-storage/compare/v1.1.1...v1.1.2
508
554
  [1.1.3]: https://github.com/bymaxone/nest-storage/compare/v1.1.2...v1.1.3
509
555
  [1.1.4]: https://github.com/bymaxone/nest-storage/compare/v1.1.3...v1.1.4
510
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.4...HEAD
556
+ [1.1.5]: https://github.com/bymaxone/nest-storage/compare/v1.1.4...v1.1.5
557
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.5...HEAD
package/README.md CHANGED
@@ -385,6 +385,12 @@ const r2 = await storage.upload(opts) // returns cached result instantly
385
385
  console.log(r2.fromIdempotencyCache) // true
386
386
  ```
387
387
 
388
+ A repeated upload is answered from the cache only while this instance still believes the object
389
+ exists: `delete()` and `deleteMany()` drop the entries of the objects they remove, so uploading
390
+ again after a delete stores the object again. The cache is **per instance**. A delete made by
391
+ another replica, or outside this library, does not reach it, and there a repeated upload can be
392
+ answered with a success for an object that no longer exists.
393
+
388
394
  ---
389
395
 
390
396
  ## ⬇️ Download
@@ -571,6 +577,14 @@ arrives, and the scanner and the upload then share that buffer. The read is boun
571
577
  refused with a reason that says to set it or use `post-upload`. Buffer bodies and `post-upload`
572
578
  mode are not affected; `post-upload` hands the scanner no body, only the key.
573
579
 
580
+ **A rejected object that could not be removed.** In `post-upload` mode the object is already
581
+ stored when the scanner rejects it, so the library deletes it and rejects `upload()` with the
582
+ verdict (`STORAGE_SCAN_INFECTED` or `STORAGE_SCAN_INCONCLUSIVE`). When that delete fails, the
583
+ verdict is still the error, and `details` says so: `cleanup: 'failed'`, the `key` and the delete
584
+ failure in `cleanupError`; the failure is also logged at error level with the code
585
+ `STORAGE_SCAN_CLEANUP_FAILED`. No `details.cleanup` means the object was removed; `cleanup:
586
+ 'failed'` means it is **still stored** and has to be removed by other means.
587
+
574
588
  ---
575
589
 
576
590
  ## ♻️ Lifecycle Operations
@@ -736,7 +750,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
736
750
  | `STORAGE_MIME_NOT_ALLOWED` | 415 | `contentType` outside `mimeWhitelist` |
737
751
  | `STORAGE_SIZE_EXCEEDED` | 413 | `size > maxSizeBytes` |
738
752
  | `STORAGE_VALIDATION_FAILED` | 400 | `IUploadValidator` rejected the file (`details.reason`) |
739
- | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`) |
753
+ | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`); `details.cleanup: 'failed'` means the object is still stored |
740
754
  | `STORAGE_SCAN_INCONCLUSIVE` | 422 | Scanner returned `'unknown'` and `rejectOnUnknown: true` |
741
755
  | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
742
756
  | `STORAGE_PROVIDER_ERROR` | 502 | AWS SDK error (network, 5xx, throttling, `AccessControlListNotSupported`); `details` carries `awsCode`, `awsMessage`, `httpStatus`, `requestId` plus the operation context (`op`, `bucket`, and `key` or `prefix`) |
@@ -744,7 +758,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
744
758
  | `STORAGE_PART_TOO_SMALL` | 400 | Reserved: a `multipart.partSizeBytes` below 5 MiB is rejected at init as `STORAGE_INVALID_CONFIG` |
745
759
  | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts` not an integer from 1 to 10 000 (`details.provided`, `details.reason`) |
746
760
  | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
747
- | `STORAGE_MULTIPART_ABORTED` | 500 | Multipart upload failed and was aborted |
761
+ | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed. `details.abort` is `'completed'` when the library aborted it and `'failed'` (with `abortError`) when the abort itself failed: that upload stays open on the provider until a lifecycle rule removes it |
748
762
  | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
749
763
  | `STORAGE_TIMEOUT` | 504 | An attempt got no response headers within `requestTimeoutMs` (the SDK's `TimeoutError`); a multipart source that stays silent for `uploadIdleTimeoutMs` also surfaces as `STORAGE_TIMEOUT` (`details.phase: 'source-idle'`); any other failure inside a multipart upload surfaces as `STORAGE_MULTIPART_ABORTED` |
750
764
  | `STORAGE_LIFECYCLE_RULE_INVALID` | 400 | `BucketLifecycleService` input rejected: empty or over-long `id`, non-positive or non-integer `expirationDays`, bad `prefix`, or an id naming a rule outside `keyPrefix` (`details.reason`) |
@@ -792,6 +806,11 @@ This is the index.
792
806
  | `copy` | `(options: CopyOptions) => Promise<{ etag }>` | Server-side; the bytes never reach this process |
793
807
  | `checkBucket` | `(options?) => Promise<void>` | One `HeadBucket` for a readiness check; resolves when the bucket is reachable, otherwise rejects `STORAGE_BUCKET_NOT_FOUND`, `STORAGE_BUCKET_ACCESS_DENIED`, `STORAGE_BUCKET_REGION_MISMATCH` or `STORAGE_TIMEOUT`; needs `s3:ListBucket`; never called at boot |
794
808
 
809
+ > **`exists()` returns `false` for any failure that is not a 404** (a 403, a 5xx, a timeout), after
810
+ > logging a warning, so a transient provider error reads as "absent". Do not use it to decide whether
811
+ > to overwrite or to create (`if (!(await exists(k))) await upload(k)` can overwrite an object
812
+ > that is there); use `head()` and branch on the error code.
813
+
795
814
  **A missing bucket and `head()` / `exists()`.** A `HEAD` response has no body, so the provider cannot say which of the bucket and the key is missing: AWS documents that "if the `HEAD` request generates an error, it returns a generic code, such as `400 Bad Request`, `403 Forbidden`, `404 Not Found` ... It's not possible to retrieve the exact exception of these error codes" ([HeadObject][aws-head-object]). `head()` therefore rejects `STORAGE_OBJECT_NOT_FOUND` and `exists()` returns `false` for a missing bucket too. Call `checkBucket()` to tell the two apart, for example from a readiness endpoint.
796
815
 
797
816
  ### `SignedUrlService`
@@ -1030,7 +1049,7 @@ place stays there — so the suite is held to a bar beyond "the tests pass".
1030
1049
 
1031
1050
  - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
1032
1051
  - ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
1033
- `break: 95`; every survivor was killed by a strengthened assertion, and the eight provable
1052
+ `break: 100`; every survivor was killed by a strengthened assertion, and the provable
1034
1053
  equivalents are documented inline
1035
1054
  - ✅ **Real object storage in e2e** — MinIO through Testcontainers, so multipart, presigning
1036
1055
  and listing are exercised against an actual S3 API rather than a mock
@@ -1047,7 +1066,7 @@ place stays there — so the suite is held to a bar beyond "the tests pass".
1047
1066
  pnpm test # unit tests (Jest)
1048
1067
  pnpm test:cov # unit tests with the 100% coverage gate
1049
1068
  pnpm test:e2e # end-to-end against MinIO (requires Docker)
1050
- pnpm mutation # Stryker mutation testing (break: 95)
1069
+ pnpm mutation # Stryker mutation testing (break: 100)
1051
1070
  pnpm typecheck # tsc strict check
1052
1071
  pnpm lint # ESLint
1053
1072
  ```
@@ -1108,6 +1108,70 @@ function mapMultipartError(err, context) {
1108
1108
  awsMessage: describeError(err)
1109
1109
  });
1110
1110
  }
1111
+ function knownStatus(error) {
1112
+ const name = common.HttpStatus[error.getStatus()];
1113
+ return name === void 0 ? void 0 : common.HttpStatus[name];
1114
+ }
1115
+ function withCleanupFailure(scanError, key, cleanupError) {
1116
+ if (!(scanError instanceof StorageException)) {
1117
+ return scanError;
1118
+ }
1119
+ const body = scanError.getResponse();
1120
+ return new StorageException(scanError.code, knownStatus(scanError), {
1121
+ ...body.error?.details ?? {},
1122
+ key,
1123
+ cleanup: "failed",
1124
+ cleanupError: describeError(cleanupError)
1125
+ });
1126
+ }
1127
+ async function closeMultipartUpload(client, bucket, key, uploadId) {
1128
+ if (uploadId === void 0) {
1129
+ return {};
1130
+ }
1131
+ try {
1132
+ await client.send(
1133
+ new clientS3.AbortMultipartUploadCommand({ Bucket: bucket, Key: key, UploadId: uploadId })
1134
+ );
1135
+ return { abort: "completed" };
1136
+ } catch (err) {
1137
+ if (err?.name === "NoSuchUpload") {
1138
+ return { abort: "completed" };
1139
+ }
1140
+ return { abort: "failed", abortError: describeError(err) };
1141
+ }
1142
+ }
1143
+ async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
1144
+ const deleted = [];
1145
+ const failed = [];
1146
+ try {
1147
+ const response = await client.send(
1148
+ new clientS3.DeleteObjectsCommand({
1149
+ Bucket: bucket,
1150
+ // `Quiet: false` returns both successes and per-key errors.
1151
+ Delete: { Objects: chunk.map((key) => ({ Key: key })), Quiet: false }
1152
+ })
1153
+ );
1154
+ for (const ok of response.Deleted ?? []) {
1155
+ if (ok.Key !== void 0) {
1156
+ deleted.push(stripPrefix(ok.Key));
1157
+ }
1158
+ }
1159
+ for (const failure of response.Errors ?? []) {
1160
+ if (failure.Key !== void 0) {
1161
+ failed.push({
1162
+ key: stripPrefix(failure.Key),
1163
+ error: `${failure.Code ?? "Unknown"}: ${failure.Message ?? ""}`
1164
+ });
1165
+ }
1166
+ }
1167
+ } catch (err) {
1168
+ const message = describeError(err);
1169
+ for (const key of chunk) {
1170
+ failed.push({ key: stripPrefix(key), error: message });
1171
+ }
1172
+ }
1173
+ return { deleted, failed };
1174
+ }
1111
1175
  function mapBucketCheckError(err, context) {
1112
1176
  const failure = err ?? {};
1113
1177
  const status = failure.$metadata?.httpStatusCode;
@@ -1349,12 +1413,16 @@ exports.StorageService = class StorageService {
1349
1413
  ...options.size !== void 0 ? { size: options.size } : {}
1350
1414
  });
1351
1415
  } catch (scanErr) {
1352
- await this.delete(finalKey, { bucket }).catch((deleteErr) => {
1416
+ const key = this.keyResolver.stripPrefix(finalKey);
1417
+ try {
1418
+ await this.delete(key, { bucket });
1419
+ } catch (deleteErr) {
1353
1420
  this.logger.error(
1354
- `Post-upload cleanup failed for infected/inconclusive object: ${finalKey}`,
1421
+ `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${key}`,
1355
1422
  describeError(deleteErr)
1356
1423
  );
1357
- });
1424
+ throw withCleanupFailure(scanErr, key, deleteErr);
1425
+ }
1358
1426
  throw scanErr;
1359
1427
  }
1360
1428
  }
@@ -1475,12 +1543,12 @@ exports.StorageService = class StorageService {
1475
1543
  await this.s3Provider.getClient().send(new clientS3.DeleteObjectCommand({ Bucket: bucket, Key: finalKey }));
1476
1544
  } catch (err) {
1477
1545
  const mapped = mapAwsError(err, { key: finalKey, bucket, op: "delete" });
1478
- if (mapped.code === STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
1479
- this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${finalKey}`);
1480
- return;
1546
+ if (mapped.code !== STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
1547
+ throw mapped;
1481
1548
  }
1482
- throw mapped;
1549
+ this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${finalKey}`);
1483
1550
  }
1551
+ this.idempotencyCache.invalidate(bucket, this.keyResolver.stripPrefix(finalKey));
1484
1552
  }
1485
1553
  /**
1486
1554
  * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
@@ -1590,8 +1658,10 @@ exports.StorageService = class StorageService {
1590
1658
  }
1591
1659
  }
1592
1660
  /**
1593
- * Multipart upload via `@aws-sdk/lib-storage`. `leavePartsOnError: false` makes
1594
- * the SDK abort and clean up parts on failure, so no manual abort is issued.
1661
+ * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
1662
+ * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
1663
+ * abort replaced the failure that caused it, and a failed `CompleteMultipartUpload` was never
1664
+ * aborted. This method aborts the upload itself and reports the outcome in the error details.
1595
1665
  */
1596
1666
  async uploadMultipart(options, finalKey, bucket) {
1597
1667
  const params = {
@@ -1613,14 +1683,9 @@ exports.StorageService = class StorageService {
1613
1683
  params,
1614
1684
  queueSize: this.options.multipart.queueSize,
1615
1685
  partSize: this.options.multipart.partSizeBytes,
1616
- leavePartsOnError: false
1686
+ leavePartsOnError: true
1617
1687
  });
1618
- if (options.onProgress) {
1619
- const onProgress = options.onProgress;
1620
- uploader.on("httpUploadProgress", (event) => {
1621
- this.emitProgress(onProgress, event.loaded, event.total, event.part);
1622
- });
1623
- }
1688
+ this.forwardProgress(uploader, options.onProgress);
1624
1689
  try {
1625
1690
  const response = await uploader.done();
1626
1691
  return this.buildUploadResult({
@@ -1633,9 +1698,26 @@ exports.StorageService = class StorageService {
1633
1698
  multipart: true
1634
1699
  });
1635
1700
  } catch (err) {
1636
- throw mapMultipartError(err, { key: finalKey, bucket });
1701
+ return this.failMultipart(err, finalKey, bucket, uploader.uploadId);
1637
1702
  }
1638
1703
  }
1704
+ /** Relays the uploader's progress events to the caller's callback, when there is one. */
1705
+ forwardProgress(uploader, onProgress) {
1706
+ if (!onProgress) return;
1707
+ uploader.on("httpUploadProgress", (event) => {
1708
+ this.emitProgress(onProgress, event.loaded, event.total, event.part);
1709
+ });
1710
+ }
1711
+ /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
1712
+ async failMultipart(err, finalKey, bucket, uploadId) {
1713
+ const abort = await closeMultipartUpload(
1714
+ this.s3Provider.getClient(),
1715
+ bucket,
1716
+ finalKey,
1717
+ uploadId
1718
+ );
1719
+ throw mapMultipartError(err, { key: finalKey, bucket, ...abort });
1720
+ }
1639
1721
  /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
1640
1722
  normalizeSingleShotBody(body) {
1641
1723
  if (isBufferLike(body)) {
@@ -1748,42 +1830,17 @@ exports.StorageService = class StorageService {
1748
1830
  const failed = [];
1749
1831
  for (let i = 0; i < normalized.length; i += DELETE_BATCH_LIMIT) {
1750
1832
  const chunk = normalized.slice(i, i + DELETE_BATCH_LIMIT);
1751
- const outcome = await this.deleteChunk(bucket, chunk);
1833
+ const outcome = await deleteObjectsChunk(
1834
+ this.s3Provider.getClient(),
1835
+ bucket,
1836
+ chunk,
1837
+ (key) => this.keyResolver.stripPrefix(key)
1838
+ );
1752
1839
  deleted.push(...outcome.deleted);
1753
1840
  failed.push(...outcome.failed);
1754
1841
  }
1755
- return { deleted, failed };
1756
- }
1757
- /** Deletes one chunk (≤ 1000 keys); a whole-chunk failure fails every key. */
1758
- async deleteChunk(bucket, chunk) {
1759
- const deleted = [];
1760
- const failed = [];
1761
- try {
1762
- const response = await this.s3Provider.getClient().send(
1763
- new clientS3.DeleteObjectsCommand({
1764
- Bucket: bucket,
1765
- // `Quiet: false` returns both successes and per-key errors.
1766
- Delete: { Objects: chunk.map((key) => ({ Key: key })), Quiet: false }
1767
- })
1768
- );
1769
- for (const ok of response.Deleted ?? []) {
1770
- if (ok.Key !== void 0) {
1771
- deleted.push(this.keyResolver.stripPrefix(ok.Key));
1772
- }
1773
- }
1774
- for (const failure of response.Errors ?? []) {
1775
- if (failure.Key !== void 0) {
1776
- failed.push({
1777
- key: this.keyResolver.stripPrefix(failure.Key),
1778
- error: `${failure.Code ?? "Unknown"}: ${failure.Message ?? ""}`
1779
- });
1780
- }
1781
- }
1782
- } catch (err) {
1783
- const message = describeError(err);
1784
- for (const key of chunk) {
1785
- failed.push({ key: this.keyResolver.stripPrefix(key), error: message });
1786
- }
1842
+ for (const key of deleted) {
1843
+ this.idempotencyCache.invalidate(bucket, key);
1787
1844
  }
1788
1845
  return { deleted, failed };
1789
1846
  }
@@ -2084,6 +2141,24 @@ var IdempotencyCache = class {
2084
2141
  }
2085
2142
  }
2086
2143
  }
2144
+ /**
2145
+ * Drops every entry whose cached result is this object, so a repeated upload after the object
2146
+ * was deleted runs instead of being answered with a success that no longer holds.
2147
+ *
2148
+ * @param bucket - The bucket of the deleted object.
2149
+ * @param key - The object's key, relative to `keyPrefix`, as `UploadResult.key` carries it.
2150
+ * @returns How many entries were dropped.
2151
+ */
2152
+ invalidate(bucket, key) {
2153
+ let dropped = 0;
2154
+ for (const [cacheKey, entry] of this.entries) {
2155
+ if (entry.value.bucket === bucket && entry.value.key === key) {
2156
+ this.entries.delete(cacheKey);
2157
+ dropped += 1;
2158
+ }
2159
+ }
2160
+ return dropped;
2161
+ }
2087
2162
  /**
2088
2163
  * Reports the current number of cached entries.
2089
2164
  *
@@ -691,6 +691,15 @@ declare class IdempotencyCache {
691
691
  * @param value - The upload result to cache.
692
692
  */
693
693
  set(cacheKey: string, value: UploadResult): void;
694
+ /**
695
+ * Drops every entry whose cached result is this object, so a repeated upload after the object
696
+ * was deleted runs instead of being answered with a success that no longer holds.
697
+ *
698
+ * @param bucket - The bucket of the deleted object.
699
+ * @param key - The object's key, relative to `keyPrefix`, as `UploadResult.key` carries it.
700
+ * @returns How many entries were dropped.
701
+ */
702
+ invalidate(bucket: string, key: string): number;
694
703
  /**
695
704
  * Reports the current number of cached entries.
696
705
  *
@@ -842,10 +851,16 @@ declare class StorageService {
842
851
  /** Single `PutObject` upload for bodies below the multipart threshold. */
843
852
  private uploadSingleShot;
844
853
  /**
845
- * Multipart upload via `@aws-sdk/lib-storage`. `leavePartsOnError: false` makes
846
- * the SDK abort and clean up parts on failure, so no manual abort is issued.
854
+ * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
855
+ * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
856
+ * abort replaced the failure that caused it, and a failed `CompleteMultipartUpload` was never
857
+ * aborted. This method aborts the upload itself and reports the outcome in the error details.
847
858
  */
848
859
  private uploadMultipart;
860
+ /** Relays the uploader's progress events to the caller's callback, when there is one. */
861
+ private forwardProgress;
862
+ /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
863
+ private failMultipart;
849
864
  /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
850
865
  private normalizeSingleShotBody;
851
866
  /** Assembles an `UploadResult`, omitting optional fields that are absent. */
@@ -884,8 +899,6 @@ declare class StorageService {
884
899
  * @returns The deleted keys and the per-key failures.
885
900
  */
886
901
  deleteMany(keys: string[], options?: DeleteManyOptions): Promise<DeleteManyResult>;
887
- /** Deletes one chunk (≤ 1000 keys); a whole-chunk failure fails every key. */
888
- private deleteChunk;
889
902
  }
890
903
 
891
904
  /**
@@ -691,6 +691,15 @@ declare class IdempotencyCache {
691
691
  * @param value - The upload result to cache.
692
692
  */
693
693
  set(cacheKey: string, value: UploadResult): void;
694
+ /**
695
+ * Drops every entry whose cached result is this object, so a repeated upload after the object
696
+ * was deleted runs instead of being answered with a success that no longer holds.
697
+ *
698
+ * @param bucket - The bucket of the deleted object.
699
+ * @param key - The object's key, relative to `keyPrefix`, as `UploadResult.key` carries it.
700
+ * @returns How many entries were dropped.
701
+ */
702
+ invalidate(bucket: string, key: string): number;
694
703
  /**
695
704
  * Reports the current number of cached entries.
696
705
  *
@@ -842,10 +851,16 @@ declare class StorageService {
842
851
  /** Single `PutObject` upload for bodies below the multipart threshold. */
843
852
  private uploadSingleShot;
844
853
  /**
845
- * Multipart upload via `@aws-sdk/lib-storage`. `leavePartsOnError: false` makes
846
- * the SDK abort and clean up parts on failure, so no manual abort is issued.
854
+ * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
855
+ * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
856
+ * abort replaced the failure that caused it, and a failed `CompleteMultipartUpload` was never
857
+ * aborted. This method aborts the upload itself and reports the outcome in the error details.
847
858
  */
848
859
  private uploadMultipart;
860
+ /** Relays the uploader's progress events to the caller's callback, when there is one. */
861
+ private forwardProgress;
862
+ /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
863
+ private failMultipart;
849
864
  /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
850
865
  private normalizeSingleShotBody;
851
866
  /** Assembles an `UploadResult`, omitting optional fields that are absent. */
@@ -884,8 +899,6 @@ declare class StorageService {
884
899
  * @returns The deleted keys and the per-key failures.
885
900
  */
886
901
  deleteMany(keys: string[], options?: DeleteManyOptions): Promise<DeleteManyResult>;
887
- /** Deletes one chunk (≤ 1000 keys); a whole-chunk failure fails every key. */
888
- private deleteChunk;
889
902
  }
890
903
 
891
904
  /**
@@ -1,5 +1,5 @@
1
1
  import { HttpStatus, Injectable, Inject, Global, Module, Logger, HttpException } from '@nestjs/common';
2
- import { S3Client, GetBucketLifecycleConfigurationCommand, DeleteBucketLifecycleCommand, PutBucketLifecycleConfigurationCommand, HeadObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadBucketCommand, PutObjectCommand, ListObjectsV2Command, CopyObjectCommand, DeleteObjectsCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand } from '@aws-sdk/client-s3';
2
+ import { S3Client, GetBucketLifecycleConfigurationCommand, DeleteBucketLifecycleCommand, PutBucketLifecycleConfigurationCommand, HeadObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadBucketCommand, PutObjectCommand, ListObjectsV2Command, CopyObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand, AbortMultipartUploadCommand, DeleteObjectsCommand } from '@aws-sdk/client-s3';
3
3
  import { Upload } from '@aws-sdk/lib-storage';
4
4
  import { PassThrough, Readable } from 'stream';
5
5
  import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
@@ -1106,6 +1106,70 @@ function mapMultipartError(err, context) {
1106
1106
  awsMessage: describeError(err)
1107
1107
  });
1108
1108
  }
1109
+ function knownStatus(error) {
1110
+ const name = HttpStatus[error.getStatus()];
1111
+ return name === void 0 ? void 0 : HttpStatus[name];
1112
+ }
1113
+ function withCleanupFailure(scanError, key, cleanupError) {
1114
+ if (!(scanError instanceof StorageException)) {
1115
+ return scanError;
1116
+ }
1117
+ const body = scanError.getResponse();
1118
+ return new StorageException(scanError.code, knownStatus(scanError), {
1119
+ ...body.error?.details ?? {},
1120
+ key,
1121
+ cleanup: "failed",
1122
+ cleanupError: describeError(cleanupError)
1123
+ });
1124
+ }
1125
+ async function closeMultipartUpload(client, bucket, key, uploadId) {
1126
+ if (uploadId === void 0) {
1127
+ return {};
1128
+ }
1129
+ try {
1130
+ await client.send(
1131
+ new AbortMultipartUploadCommand({ Bucket: bucket, Key: key, UploadId: uploadId })
1132
+ );
1133
+ return { abort: "completed" };
1134
+ } catch (err) {
1135
+ if (err?.name === "NoSuchUpload") {
1136
+ return { abort: "completed" };
1137
+ }
1138
+ return { abort: "failed", abortError: describeError(err) };
1139
+ }
1140
+ }
1141
+ async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
1142
+ const deleted = [];
1143
+ const failed = [];
1144
+ try {
1145
+ const response = await client.send(
1146
+ new DeleteObjectsCommand({
1147
+ Bucket: bucket,
1148
+ // `Quiet: false` returns both successes and per-key errors.
1149
+ Delete: { Objects: chunk.map((key) => ({ Key: key })), Quiet: false }
1150
+ })
1151
+ );
1152
+ for (const ok of response.Deleted ?? []) {
1153
+ if (ok.Key !== void 0) {
1154
+ deleted.push(stripPrefix(ok.Key));
1155
+ }
1156
+ }
1157
+ for (const failure of response.Errors ?? []) {
1158
+ if (failure.Key !== void 0) {
1159
+ failed.push({
1160
+ key: stripPrefix(failure.Key),
1161
+ error: `${failure.Code ?? "Unknown"}: ${failure.Message ?? ""}`
1162
+ });
1163
+ }
1164
+ }
1165
+ } catch (err) {
1166
+ const message = describeError(err);
1167
+ for (const key of chunk) {
1168
+ failed.push({ key: stripPrefix(key), error: message });
1169
+ }
1170
+ }
1171
+ return { deleted, failed };
1172
+ }
1109
1173
  function mapBucketCheckError(err, context) {
1110
1174
  const failure = err ?? {};
1111
1175
  const status = failure.$metadata?.httpStatusCode;
@@ -1347,12 +1411,16 @@ var StorageService = class {
1347
1411
  ...options.size !== void 0 ? { size: options.size } : {}
1348
1412
  });
1349
1413
  } catch (scanErr) {
1350
- await this.delete(finalKey, { bucket }).catch((deleteErr) => {
1414
+ const key = this.keyResolver.stripPrefix(finalKey);
1415
+ try {
1416
+ await this.delete(key, { bucket });
1417
+ } catch (deleteErr) {
1351
1418
  this.logger.error(
1352
- `Post-upload cleanup failed for infected/inconclusive object: ${finalKey}`,
1419
+ `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${key}`,
1353
1420
  describeError(deleteErr)
1354
1421
  );
1355
- });
1422
+ throw withCleanupFailure(scanErr, key, deleteErr);
1423
+ }
1356
1424
  throw scanErr;
1357
1425
  }
1358
1426
  }
@@ -1473,12 +1541,12 @@ var StorageService = class {
1473
1541
  await this.s3Provider.getClient().send(new DeleteObjectCommand({ Bucket: bucket, Key: finalKey }));
1474
1542
  } catch (err) {
1475
1543
  const mapped = mapAwsError(err, { key: finalKey, bucket, op: "delete" });
1476
- if (mapped.code === STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
1477
- this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${finalKey}`);
1478
- return;
1544
+ if (mapped.code !== STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
1545
+ throw mapped;
1479
1546
  }
1480
- throw mapped;
1547
+ this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${finalKey}`);
1481
1548
  }
1549
+ this.idempotencyCache.invalidate(bucket, this.keyResolver.stripPrefix(finalKey));
1482
1550
  }
1483
1551
  /**
1484
1552
  * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
@@ -1588,8 +1656,10 @@ var StorageService = class {
1588
1656
  }
1589
1657
  }
1590
1658
  /**
1591
- * Multipart upload via `@aws-sdk/lib-storage`. `leavePartsOnError: false` makes
1592
- * the SDK abort and clean up parts on failure, so no manual abort is issued.
1659
+ * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
1660
+ * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
1661
+ * abort replaced the failure that caused it, and a failed `CompleteMultipartUpload` was never
1662
+ * aborted. This method aborts the upload itself and reports the outcome in the error details.
1593
1663
  */
1594
1664
  async uploadMultipart(options, finalKey, bucket) {
1595
1665
  const params = {
@@ -1611,14 +1681,9 @@ var StorageService = class {
1611
1681
  params,
1612
1682
  queueSize: this.options.multipart.queueSize,
1613
1683
  partSize: this.options.multipart.partSizeBytes,
1614
- leavePartsOnError: false
1684
+ leavePartsOnError: true
1615
1685
  });
1616
- if (options.onProgress) {
1617
- const onProgress = options.onProgress;
1618
- uploader.on("httpUploadProgress", (event) => {
1619
- this.emitProgress(onProgress, event.loaded, event.total, event.part);
1620
- });
1621
- }
1686
+ this.forwardProgress(uploader, options.onProgress);
1622
1687
  try {
1623
1688
  const response = await uploader.done();
1624
1689
  return this.buildUploadResult({
@@ -1631,9 +1696,26 @@ var StorageService = class {
1631
1696
  multipart: true
1632
1697
  });
1633
1698
  } catch (err) {
1634
- throw mapMultipartError(err, { key: finalKey, bucket });
1699
+ return this.failMultipart(err, finalKey, bucket, uploader.uploadId);
1635
1700
  }
1636
1701
  }
1702
+ /** Relays the uploader's progress events to the caller's callback, when there is one. */
1703
+ forwardProgress(uploader, onProgress) {
1704
+ if (!onProgress) return;
1705
+ uploader.on("httpUploadProgress", (event) => {
1706
+ this.emitProgress(onProgress, event.loaded, event.total, event.part);
1707
+ });
1708
+ }
1709
+ /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
1710
+ async failMultipart(err, finalKey, bucket, uploadId) {
1711
+ const abort = await closeMultipartUpload(
1712
+ this.s3Provider.getClient(),
1713
+ bucket,
1714
+ finalKey,
1715
+ uploadId
1716
+ );
1717
+ throw mapMultipartError(err, { key: finalKey, bucket, ...abort });
1718
+ }
1637
1719
  /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
1638
1720
  normalizeSingleShotBody(body) {
1639
1721
  if (isBufferLike(body)) {
@@ -1746,42 +1828,17 @@ var StorageService = class {
1746
1828
  const failed = [];
1747
1829
  for (let i = 0; i < normalized.length; i += DELETE_BATCH_LIMIT) {
1748
1830
  const chunk = normalized.slice(i, i + DELETE_BATCH_LIMIT);
1749
- const outcome = await this.deleteChunk(bucket, chunk);
1831
+ const outcome = await deleteObjectsChunk(
1832
+ this.s3Provider.getClient(),
1833
+ bucket,
1834
+ chunk,
1835
+ (key) => this.keyResolver.stripPrefix(key)
1836
+ );
1750
1837
  deleted.push(...outcome.deleted);
1751
1838
  failed.push(...outcome.failed);
1752
1839
  }
1753
- return { deleted, failed };
1754
- }
1755
- /** Deletes one chunk (≤ 1000 keys); a whole-chunk failure fails every key. */
1756
- async deleteChunk(bucket, chunk) {
1757
- const deleted = [];
1758
- const failed = [];
1759
- try {
1760
- const response = await this.s3Provider.getClient().send(
1761
- new DeleteObjectsCommand({
1762
- Bucket: bucket,
1763
- // `Quiet: false` returns both successes and per-key errors.
1764
- Delete: { Objects: chunk.map((key) => ({ Key: key })), Quiet: false }
1765
- })
1766
- );
1767
- for (const ok of response.Deleted ?? []) {
1768
- if (ok.Key !== void 0) {
1769
- deleted.push(this.keyResolver.stripPrefix(ok.Key));
1770
- }
1771
- }
1772
- for (const failure of response.Errors ?? []) {
1773
- if (failure.Key !== void 0) {
1774
- failed.push({
1775
- key: this.keyResolver.stripPrefix(failure.Key),
1776
- error: `${failure.Code ?? "Unknown"}: ${failure.Message ?? ""}`
1777
- });
1778
- }
1779
- }
1780
- } catch (err) {
1781
- const message = describeError(err);
1782
- for (const key of chunk) {
1783
- failed.push({ key: this.keyResolver.stripPrefix(key), error: message });
1784
- }
1840
+ for (const key of deleted) {
1841
+ this.idempotencyCache.invalidate(bucket, key);
1785
1842
  }
1786
1843
  return { deleted, failed };
1787
1844
  }
@@ -2082,6 +2139,24 @@ var IdempotencyCache = class {
2082
2139
  }
2083
2140
  }
2084
2141
  }
2142
+ /**
2143
+ * Drops every entry whose cached result is this object, so a repeated upload after the object
2144
+ * was deleted runs instead of being answered with a success that no longer holds.
2145
+ *
2146
+ * @param bucket - The bucket of the deleted object.
2147
+ * @param key - The object's key, relative to `keyPrefix`, as `UploadResult.key` carries it.
2148
+ * @returns How many entries were dropped.
2149
+ */
2150
+ invalidate(bucket, key) {
2151
+ let dropped = 0;
2152
+ for (const [cacheKey, entry] of this.entries) {
2153
+ if (entry.value.bucket === bucket && entry.value.key === key) {
2154
+ this.entries.delete(cacheKey);
2155
+ dropped += 1;
2156
+ }
2157
+ }
2158
+ return dropped;
2159
+ }
2085
2160
  /**
2086
2161
  * Reports the current number of cached entries.
2087
2162
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.1.4",
3
+ "version": "1.1.5",
4
4
  "description": "Provider-agnostic S3-compatible object storage for NestJS. Works with AWS S3, DigitalOcean Spaces, Cloudflare R2, Backblaze B2, MinIO, Wasabi.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",
@@ -45,6 +45,7 @@
45
45
  },
46
46
  "scripts": {
47
47
  "build": "pnpm clean && tsup",
48
+ "check:api": "node scripts/check-api-surface.mjs",
48
49
  "check:exports": "attw --pack . --profile strict",
49
50
  "check:mutants": "node scripts/check-mutation-directives.mjs",
50
51
  "check:published": "node scripts/check-published-surface.mjs",