@bymax-one/nest-storage 1.1.10 → 1.1.12

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.
@@ -1,4 +1,4 @@
1
- import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
1
+ import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException } from '@nestjs/common';
2
2
  import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
3
3
 
4
4
  /**
@@ -139,7 +139,10 @@ interface BymaxStorageModuleOptions {
139
139
  validation?: {
140
140
  /** MIME whitelist — supports wildcards like `'image/*'`. */
141
141
  mimeWhitelist?: readonly string[];
142
- /** Max upload size in bytes. */
142
+ /**
143
+ * Max upload size in bytes. A buffer is checked by its length and a stream is counted as it
144
+ * is read, so the limit holds whether or not the caller declares `size`.
145
+ */
143
146
  maxSizeBytes?: number;
144
147
  /** Custom validators run in order; the first rejection short-circuits. */
145
148
  customValidators?: readonly IUploadValidator[];
@@ -164,16 +167,24 @@ interface BymaxStorageModuleOptions {
164
167
  requestChecksumCalculation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
165
168
  /** S3Client `responseChecksumValidation` (checksum mode on GET). Same provider caveat. */
166
169
  responseChecksumValidation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
167
- /** Total attempts including the first try (maps to `maxAttempts`). Default: `3`. */
170
+ /** Total attempts including the first try (maps to `maxAttempts`). An integer of at least `1`. Default: `3`. */
168
171
  maxAttempts?: number;
169
- /** Per-request timeout. Default: `30000` ms. */
172
+ /** Per-attempt timeout until the response headers arrive. An integer from `1` to `2147483647` (the longest a timer holds). Default: `30000` ms. */
170
173
  requestTimeoutMs?: number;
171
174
  /**
172
175
  * Longest silence, in milliseconds, tolerated from a stream body while a multipart upload
173
176
  * waits for its next bytes; past it the upload is aborted and rejects `STORAGE_TIMEOUT`.
174
- * An integer of at least `0`; `0` turns the guard off. Default: `requestTimeoutMs`.
177
+ * An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard off. Default: `requestTimeoutMs`.
175
178
  */
176
179
  uploadIdleTimeoutMs?: number;
180
+ /**
181
+ * Longest silence, in milliseconds, tolerated from a download body while the caller is waiting
182
+ * for its next bytes; past it the stream fails with `STORAGE_TIMEOUT` (`details.phase` is
183
+ * `'body-idle'`) and the connection is released. The clock runs only while a read is pending, so
184
+ * a consumer that is slow to read never trips it. An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard
185
+ * off. Default: `requestTimeoutMs`.
186
+ */
187
+ bodyIdleTimeoutMs?: number;
177
188
  }
178
189
  /**
179
190
  * Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
@@ -303,6 +314,7 @@ interface ResolvedBymaxStorageOptions {
303
314
  maxAttempts: number;
304
315
  requestTimeoutMs: number;
305
316
  uploadIdleTimeoutMs: number;
317
+ bodyIdleTimeoutMs: number;
306
318
  /** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
307
319
  hasCredentials: boolean;
308
320
  }
@@ -335,6 +347,14 @@ interface UploadOptions {
335
347
  * cached `UploadResult` is returned without re-uploading.
336
348
  */
337
349
  idempotencyKey?: string;
350
+ /**
351
+ * Ends the upload when it aborts: the request is dropped, a multipart upload is aborted so no part
352
+ * stays stored, and the call rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the
353
+ * signal's reason name and, for multipart, `details.abort`. A signal that is already aborted makes
354
+ * no request. As for any rejected upload, a stream `body` is destroyed. The library keeps no
355
+ * listener on the signal after the call.
356
+ */
357
+ abortSignal?: AbortSignal;
338
358
  /** Progress callback fired after each multipart part (or once for single). */
339
359
  onProgress?: (event: {
340
360
  loaded: number;
@@ -344,7 +364,7 @@ interface UploadOptions {
344
364
  }
345
365
 
346
366
  /**
347
- * @fileoverview Per-call options for `StorageService.download()`.
367
+ * @fileoverview Per-call options for `StorageService.download()` and `downloadBuffer()`.
348
368
  * @layer server/interfaces
349
369
  */
350
370
  /** Options for a single download call. */
@@ -357,6 +377,25 @@ interface DownloadOptions {
357
377
  ifNoneMatch?: string;
358
378
  /** Conditional GET — only return if the ETag matches. */
359
379
  ifMatch?: string;
380
+ /**
381
+ * Ends the call when it aborts: the request is dropped and the call rejects
382
+ * `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal that is
383
+ * already aborted makes no request. A body stream already returned errors too: as
384
+ * `STORAGE_REQUEST_ABORTED` while the idle guard is on (the default `bodyIdleTimeoutMs`), as the
385
+ * raw `AbortError` when `bodyIdleTimeoutMs` is `0`. The library keeps no listener on the signal
386
+ * after the call.
387
+ */
388
+ abortSignal?: AbortSignal;
389
+ }
390
+ /** Options for a single `downloadBuffer()` call. */
391
+ interface DownloadBufferOptions extends DownloadOptions {
392
+ /**
393
+ * The most bytes `downloadBuffer()` will hold. An object whose `Content-Length` is larger is
394
+ * refused before its body is read, and a body that turns out longer than this (a missing or
395
+ * wrong `Content-Length`) is cut off as it is counted; both reject `STORAGE_SIZE_EXCEEDED` and
396
+ * release the connection. An integer of at least `1`. Without it the whole object is buffered.
397
+ */
398
+ maxBytes?: number;
360
399
  }
361
400
 
362
401
  /**
@@ -425,6 +464,12 @@ interface ListOptions {
425
464
  * sub-prefixes are aggregated into `commonPrefixes`.
426
465
  */
427
466
  delimiter?: string;
467
+ /**
468
+ * Ends the call when it aborts: the request is dropped, a multipart upload is aborted and the call
469
+ * rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal
470
+ * that is already aborted makes no request. The library keeps no listener on it after the call.
471
+ */
472
+ abortSignal?: AbortSignal;
428
473
  }
429
474
  /** Result of a single list call. */
430
475
  interface ListResult {
@@ -725,6 +770,8 @@ declare class IdempotencyCache {
725
770
  /** Per-call options that only need to override the target bucket. */
726
771
  interface BucketScopedOptions {
727
772
  bucket?: string;
773
+ /** Ends the call when it aborts, rejecting `STORAGE_REQUEST_ABORTED`; an aborted signal makes no request. */
774
+ abortSignal?: AbortSignal;
728
775
  }
729
776
  declare class StorageService {
730
777
  private readonly options;
@@ -763,12 +810,8 @@ declare class StorageService {
763
810
  private bufferForPreUploadScan;
764
811
  /** Runs a pre-upload scan when configured; throws on infected. */
765
812
  private runPreUploadScan;
766
- /**
767
- * Coerces the scan body to a `Buffer` so the scanner always receives its declared
768
- * contract type. In pre-upload mode a stream has already been buffered by
769
- * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
770
- */
771
- private normalizeScanBody;
813
+ /** Remembers the result of an upload under its idempotency key, when it has one. */
814
+ private rememberUpload;
772
815
  /**
773
816
  * Runs a post-upload scan. On infection, deletes the just-uploaded object
774
817
  * (logging delete failures as errors) and re-throws the scan exception.
@@ -815,13 +858,15 @@ declare class StorageService {
815
858
  metadata: ObjectMetadata;
816
859
  }>;
817
860
  /**
818
- * Materializes an object fully into memory via the sdk-stream-mixin. NOT
819
- * recommended for files larger than 10 MB — use {@link download} for those.
861
+ * Reads an object fully into memory through the same idle-guarded stream as {@link download}.
862
+ * Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
820
863
  *
821
- * @param options - The download request.
864
+ * @param options - The download request; `maxBytes` is the most bytes to hold.
822
865
  * @returns The object buffer and its metadata.
866
+ * @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
867
+ * bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
823
868
  */
824
- downloadBuffer(options: DownloadOptions): Promise<{
869
+ downloadBuffer(options: DownloadBufferOptions): Promise<{
825
870
  buffer: Buffer;
826
871
  metadata: ObjectMetadata;
827
872
  }>;
@@ -849,15 +894,6 @@ declare class StorageService {
849
894
  private assertConfigured;
850
895
  /** Resolves the target bucket from a per-call override or the module default. */
851
896
  private resolveBucket;
852
- /** Builds a public URL, avoiding a duplicated bucket segment in the base. */
853
- private buildPublicUrl;
854
- /**
855
- * Reports whether the base URL already carries the bucket as a real segment —
856
- * the leading host label (virtual-hosted-style `bucket.host`) or a path segment
857
- * (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
858
- * so `bucket="test"` is not matched by a `latest` elsewhere in the base.
859
- */
860
- private baseCarriesBucket;
861
897
  /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
862
898
  private toObjectMetadata;
863
899
  /** Single `PutObject` upload for bodies below the multipart threshold. */
@@ -869,16 +905,13 @@ declare class StorageService {
869
905
  * aborted. This method aborts the upload itself and reports the outcome in the error details.
870
906
  */
871
907
  private uploadMultipart;
872
- /** Relays the uploader's progress events to the caller's callback, when there is one. */
873
- private forwardProgress;
874
- /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
908
+ /**
909
+ * Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
910
+ * the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
911
+ * real failure into one. An upload id the provider answered late is waited for, within the cleanup
912
+ * deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
913
+ */
875
914
  private failMultipart;
876
- /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
877
- private normalizeSingleShotBody;
878
- /** Assembles an `UploadResult`, omitting optional fields that are absent. */
879
- private buildUploadResult;
880
- /** Emits a progress event, omitting `total`/`part` when they are unknown. */
881
- private emitProgress;
882
915
  /**
883
916
  * Lists objects in the bucket as a single page. Applies the global key prefix
884
917
  * to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
@@ -1389,6 +1422,7 @@ declare const STORAGE_ERROR_CODES: {
1389
1422
  readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
1390
1423
  readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
1391
1424
  readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
1425
+ readonly STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED";
1392
1426
  };
1393
1427
  /** Union of every stable storage error code. */
1394
1428
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1411,10 +1445,10 @@ declare class StorageException extends HttpException {
1411
1445
  readonly code: StorageErrorCode;
1412
1446
  constructor(code: StorageErrorCode,
1413
1447
  /** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
1414
- statusCode?: HttpStatus, details?: Record<string, unknown>,
1448
+ statusCode?: number, details?: Record<string, unknown>,
1415
1449
  /** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
1416
1450
  message?: string);
1417
1451
  }
1418
1452
 
1419
1453
  export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BucketLifecycleService, BymaxStorageModule, NoOpFileScanner, NoOpUploadValidator, STORAGE_ERROR_CODES, SignedUrlService, StorageException, StorageService, providerRecipes };
1420
- export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
1454
+ export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
@@ -1,4 +1,4 @@
1
- import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
1
+ import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException } from '@nestjs/common';
2
2
  import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
3
3
 
4
4
  /**
@@ -139,7 +139,10 @@ interface BymaxStorageModuleOptions {
139
139
  validation?: {
140
140
  /** MIME whitelist — supports wildcards like `'image/*'`. */
141
141
  mimeWhitelist?: readonly string[];
142
- /** Max upload size in bytes. */
142
+ /**
143
+ * Max upload size in bytes. A buffer is checked by its length and a stream is counted as it
144
+ * is read, so the limit holds whether or not the caller declares `size`.
145
+ */
143
146
  maxSizeBytes?: number;
144
147
  /** Custom validators run in order; the first rejection short-circuits. */
145
148
  customValidators?: readonly IUploadValidator[];
@@ -164,16 +167,24 @@ interface BymaxStorageModuleOptions {
164
167
  requestChecksumCalculation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
165
168
  /** S3Client `responseChecksumValidation` (checksum mode on GET). Same provider caveat. */
166
169
  responseChecksumValidation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
167
- /** Total attempts including the first try (maps to `maxAttempts`). Default: `3`. */
170
+ /** Total attempts including the first try (maps to `maxAttempts`). An integer of at least `1`. Default: `3`. */
168
171
  maxAttempts?: number;
169
- /** Per-request timeout. Default: `30000` ms. */
172
+ /** Per-attempt timeout until the response headers arrive. An integer from `1` to `2147483647` (the longest a timer holds). Default: `30000` ms. */
170
173
  requestTimeoutMs?: number;
171
174
  /**
172
175
  * Longest silence, in milliseconds, tolerated from a stream body while a multipart upload
173
176
  * waits for its next bytes; past it the upload is aborted and rejects `STORAGE_TIMEOUT`.
174
- * An integer of at least `0`; `0` turns the guard off. Default: `requestTimeoutMs`.
177
+ * An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard off. Default: `requestTimeoutMs`.
175
178
  */
176
179
  uploadIdleTimeoutMs?: number;
180
+ /**
181
+ * Longest silence, in milliseconds, tolerated from a download body while the caller is waiting
182
+ * for its next bytes; past it the stream fails with `STORAGE_TIMEOUT` (`details.phase` is
183
+ * `'body-idle'`) and the connection is released. The clock runs only while a read is pending, so
184
+ * a consumer that is slow to read never trips it. An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard
185
+ * off. Default: `requestTimeoutMs`.
186
+ */
187
+ bodyIdleTimeoutMs?: number;
177
188
  }
178
189
  /**
179
190
  * Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
@@ -303,6 +314,7 @@ interface ResolvedBymaxStorageOptions {
303
314
  maxAttempts: number;
304
315
  requestTimeoutMs: number;
305
316
  uploadIdleTimeoutMs: number;
317
+ bodyIdleTimeoutMs: number;
306
318
  /** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
307
319
  hasCredentials: boolean;
308
320
  }
@@ -335,6 +347,14 @@ interface UploadOptions {
335
347
  * cached `UploadResult` is returned without re-uploading.
336
348
  */
337
349
  idempotencyKey?: string;
350
+ /**
351
+ * Ends the upload when it aborts: the request is dropped, a multipart upload is aborted so no part
352
+ * stays stored, and the call rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the
353
+ * signal's reason name and, for multipart, `details.abort`. A signal that is already aborted makes
354
+ * no request. As for any rejected upload, a stream `body` is destroyed. The library keeps no
355
+ * listener on the signal after the call.
356
+ */
357
+ abortSignal?: AbortSignal;
338
358
  /** Progress callback fired after each multipart part (or once for single). */
339
359
  onProgress?: (event: {
340
360
  loaded: number;
@@ -344,7 +364,7 @@ interface UploadOptions {
344
364
  }
345
365
 
346
366
  /**
347
- * @fileoverview Per-call options for `StorageService.download()`.
367
+ * @fileoverview Per-call options for `StorageService.download()` and `downloadBuffer()`.
348
368
  * @layer server/interfaces
349
369
  */
350
370
  /** Options for a single download call. */
@@ -357,6 +377,25 @@ interface DownloadOptions {
357
377
  ifNoneMatch?: string;
358
378
  /** Conditional GET — only return if the ETag matches. */
359
379
  ifMatch?: string;
380
+ /**
381
+ * Ends the call when it aborts: the request is dropped and the call rejects
382
+ * `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal that is
383
+ * already aborted makes no request. A body stream already returned errors too: as
384
+ * `STORAGE_REQUEST_ABORTED` while the idle guard is on (the default `bodyIdleTimeoutMs`), as the
385
+ * raw `AbortError` when `bodyIdleTimeoutMs` is `0`. The library keeps no listener on the signal
386
+ * after the call.
387
+ */
388
+ abortSignal?: AbortSignal;
389
+ }
390
+ /** Options for a single `downloadBuffer()` call. */
391
+ interface DownloadBufferOptions extends DownloadOptions {
392
+ /**
393
+ * The most bytes `downloadBuffer()` will hold. An object whose `Content-Length` is larger is
394
+ * refused before its body is read, and a body that turns out longer than this (a missing or
395
+ * wrong `Content-Length`) is cut off as it is counted; both reject `STORAGE_SIZE_EXCEEDED` and
396
+ * release the connection. An integer of at least `1`. Without it the whole object is buffered.
397
+ */
398
+ maxBytes?: number;
360
399
  }
361
400
 
362
401
  /**
@@ -425,6 +464,12 @@ interface ListOptions {
425
464
  * sub-prefixes are aggregated into `commonPrefixes`.
426
465
  */
427
466
  delimiter?: string;
467
+ /**
468
+ * Ends the call when it aborts: the request is dropped, a multipart upload is aborted and the call
469
+ * rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal
470
+ * that is already aborted makes no request. The library keeps no listener on it after the call.
471
+ */
472
+ abortSignal?: AbortSignal;
428
473
  }
429
474
  /** Result of a single list call. */
430
475
  interface ListResult {
@@ -725,6 +770,8 @@ declare class IdempotencyCache {
725
770
  /** Per-call options that only need to override the target bucket. */
726
771
  interface BucketScopedOptions {
727
772
  bucket?: string;
773
+ /** Ends the call when it aborts, rejecting `STORAGE_REQUEST_ABORTED`; an aborted signal makes no request. */
774
+ abortSignal?: AbortSignal;
728
775
  }
729
776
  declare class StorageService {
730
777
  private readonly options;
@@ -763,12 +810,8 @@ declare class StorageService {
763
810
  private bufferForPreUploadScan;
764
811
  /** Runs a pre-upload scan when configured; throws on infected. */
765
812
  private runPreUploadScan;
766
- /**
767
- * Coerces the scan body to a `Buffer` so the scanner always receives its declared
768
- * contract type. In pre-upload mode a stream has already been buffered by
769
- * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
770
- */
771
- private normalizeScanBody;
813
+ /** Remembers the result of an upload under its idempotency key, when it has one. */
814
+ private rememberUpload;
772
815
  /**
773
816
  * Runs a post-upload scan. On infection, deletes the just-uploaded object
774
817
  * (logging delete failures as errors) and re-throws the scan exception.
@@ -815,13 +858,15 @@ declare class StorageService {
815
858
  metadata: ObjectMetadata;
816
859
  }>;
817
860
  /**
818
- * Materializes an object fully into memory via the sdk-stream-mixin. NOT
819
- * recommended for files larger than 10 MB — use {@link download} for those.
861
+ * Reads an object fully into memory through the same idle-guarded stream as {@link download}.
862
+ * Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
820
863
  *
821
- * @param options - The download request.
864
+ * @param options - The download request; `maxBytes` is the most bytes to hold.
822
865
  * @returns The object buffer and its metadata.
866
+ * @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
867
+ * bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
823
868
  */
824
- downloadBuffer(options: DownloadOptions): Promise<{
869
+ downloadBuffer(options: DownloadBufferOptions): Promise<{
825
870
  buffer: Buffer;
826
871
  metadata: ObjectMetadata;
827
872
  }>;
@@ -849,15 +894,6 @@ declare class StorageService {
849
894
  private assertConfigured;
850
895
  /** Resolves the target bucket from a per-call override or the module default. */
851
896
  private resolveBucket;
852
- /** Builds a public URL, avoiding a duplicated bucket segment in the base. */
853
- private buildPublicUrl;
854
- /**
855
- * Reports whether the base URL already carries the bucket as a real segment —
856
- * the leading host label (virtual-hosted-style `bucket.host`) or a path segment
857
- * (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
858
- * so `bucket="test"` is not matched by a `latest` elsewhere in the base.
859
- */
860
- private baseCarriesBucket;
861
897
  /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
862
898
  private toObjectMetadata;
863
899
  /** Single `PutObject` upload for bodies below the multipart threshold. */
@@ -869,16 +905,13 @@ declare class StorageService {
869
905
  * aborted. This method aborts the upload itself and reports the outcome in the error details.
870
906
  */
871
907
  private uploadMultipart;
872
- /** Relays the uploader's progress events to the caller's callback, when there is one. */
873
- private forwardProgress;
874
- /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
908
+ /**
909
+ * Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
910
+ * the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
911
+ * real failure into one. An upload id the provider answered late is waited for, within the cleanup
912
+ * deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
913
+ */
875
914
  private failMultipart;
876
- /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
877
- private normalizeSingleShotBody;
878
- /** Assembles an `UploadResult`, omitting optional fields that are absent. */
879
- private buildUploadResult;
880
- /** Emits a progress event, omitting `total`/`part` when they are unknown. */
881
- private emitProgress;
882
915
  /**
883
916
  * Lists objects in the bucket as a single page. Applies the global key prefix
884
917
  * to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
@@ -1389,6 +1422,7 @@ declare const STORAGE_ERROR_CODES: {
1389
1422
  readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
1390
1423
  readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
1391
1424
  readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
1425
+ readonly STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED";
1392
1426
  };
1393
1427
  /** Union of every stable storage error code. */
1394
1428
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1411,10 +1445,10 @@ declare class StorageException extends HttpException {
1411
1445
  readonly code: StorageErrorCode;
1412
1446
  constructor(code: StorageErrorCode,
1413
1447
  /** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
1414
- statusCode?: HttpStatus, details?: Record<string, unknown>,
1448
+ statusCode?: number, details?: Record<string, unknown>,
1415
1449
  /** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
1416
1450
  message?: string);
1417
1451
  }
1418
1452
 
1419
1453
  export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BucketLifecycleService, BymaxStorageModule, NoOpFileScanner, NoOpUploadValidator, STORAGE_ERROR_CODES, SignedUrlService, StorageException, StorageService, providerRecipes };
1420
- export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
1454
+ export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };