@bymax-one/nest-storage 1.1.17 → 1.1.19

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.
@@ -669,6 +669,121 @@ declare class ValidationService {
669
669
  private runCustomValidators;
670
670
  }
671
671
 
672
+ /** The operations the library counts and times. */
673
+ declare const STORAGE_OPERATIONS: readonly ["upload", "download", "head", "delete", "delete_many", "list", "copy", "get_download_url", "get_upload_url", "get_multipart_upload_urls", "check_bucket", "lifecycle_get", "lifecycle_upsert", "lifecycle_remove"];
674
+ /** What an operation ended as. */
675
+ declare const STORAGE_OUTCOMES: readonly ["success", "not_found", "aborted", "error"];
676
+ /** What a scan ended as. */
677
+ declare const SCAN_VERDICTS: readonly ["clean", "infected", "unknown", "timeout", "error"];
678
+ /** One of {@link STORAGE_OPERATIONS}. */
679
+ type StorageOperation = (typeof STORAGE_OPERATIONS)[number];
680
+ /** One of {@link STORAGE_OUTCOMES}. */
681
+ type StorageOutcome = (typeof STORAGE_OUTCOMES)[number];
682
+ /** One of {@link SCAN_VERDICTS}. */
683
+ type ScanVerdict = (typeof SCAN_VERDICTS)[number];
684
+
685
+ /** Told how long an operation took, once it ended. Typed to return a value: a listener typed `void` can still return a promise. */
686
+ type DurationListener = (operation: StorageOperation, seconds: number) => unknown;
687
+ /**
688
+ * Counts what the storage operations do. Each count is keyed by a closed set (see `storage-operations`), so no
689
+ * label can grow with the traffic, and nothing a caller or a host supplied is ever a key. The optional
690
+ * `observability` subpath reads these numbers when it is scraped, and feeds a duration histogram through
691
+ * {@link StorageMetricsTally.onDuration}.
692
+ */
693
+ declare class StorageMetricsTally {
694
+ #private;
695
+ /** An operation ended as `outcome` after `seconds`. */
696
+ operation(operation: StorageOperation, outcome: StorageOutcome, seconds: number): void;
697
+ /** `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. */
698
+ bytesUploaded(bytes: number | undefined): void;
699
+ /** A scan ended as `verdict`. */
700
+ scan(verdict: ScanVerdict): void;
701
+ /** Calls `listener` with the duration of every operation that ends from now on. */
702
+ onDuration(listener: DurationListener): void;
703
+ /** The counts so far, as copies. */
704
+ snapshot(): {
705
+ readonly operations: Readonly<Record<StorageOperation, Readonly<Record<StorageOutcome, number>>>>;
706
+ readonly bytesUploaded: number;
707
+ readonly scans: Readonly<Record<ScanVerdict, number>>;
708
+ };
709
+ }
710
+
711
+ /** The span names the library starts. */
712
+ type StorageSpanName = 'storage.upload' | 'storage.download_url' | 'storage.scan';
713
+ /** Attributes are closed: an operation, an outcome, a mode or a flag, never a key, a bucket or a payload. */
714
+ type StorageSpanAttributes = Readonly<Record<string, string>>;
715
+ /** What a span states of a result, once the operation succeeded. */
716
+ type ResultAttributes<T> = (result: T) => StorageSpanAttributes;
717
+ /**
718
+ * Starts a span around an operation when `@opentelemetry/api` is installed, and runs it bare otherwise.
719
+ *
720
+ * The peer is optional, so it is loaded with a dynamic `import()` that a missing package turns into a no-op:
721
+ * the server bundle never names it statically, and an application that does not trace installs nothing. With
722
+ * the API present and no SDK registered the API itself is a no-op. A span carries a closed set of attributes
723
+ * and, on failure, the library error code and nothing of the message.
724
+ */
725
+ declare class StorageTracing implements OnModuleInit {
726
+ #private;
727
+ /** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
728
+ onModuleInit(): Promise<void>;
729
+ /** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
730
+ private traced;
731
+ /**
732
+ * Runs `run` inside a span named `name`.
733
+ *
734
+ * The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
735
+ * throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
736
+ * otherwise, and its own result or error is what comes back.
737
+ *
738
+ * @param name - One of the library's span names.
739
+ * @param attributes - Closed-set attributes of the span.
740
+ * @param run - The operation; its result or its error passes through unchanged.
741
+ * @param describe - What the span states of a successful result; a throw of its own is the operation's own.
742
+ */
743
+ span<T>(name: StorageSpanName, attributes: StorageSpanAttributes, run: () => Promise<T>, describe?: ResultAttributes<T>): Promise<T>;
744
+ }
745
+
746
+ /** What an observed operation adds to the plain count and timing. */
747
+ interface ObservedOptions<T> {
748
+ /** The span to start around the operation. */
749
+ readonly span?: StorageSpanName;
750
+ /** Attributes the span starts with. */
751
+ readonly attributes?: StorageSpanAttributes;
752
+ /** What the span states of a successful result. */
753
+ readonly describe?: (result: T) => StorageSpanAttributes;
754
+ /** The bytes of a successful result that reached the provider, for the upload counter. */
755
+ readonly bytes?: (result: T) => number | undefined;
756
+ }
757
+ /**
758
+ * Observes the operations of the library.
759
+ *
760
+ * It is a seam between the services and two optional consumers: the tally the `observability` subpath
761
+ * publishes from, and the span the host's OpenTelemetry SDK records. A service that is built without one
762
+ * (a unit test, say) runs its operations bare.
763
+ */
764
+ declare class StorageObserver {
765
+ private readonly tally;
766
+ private readonly tracing;
767
+ constructor(tally: StorageMetricsTally, tracing: StorageTracing);
768
+ /**
769
+ * Runs `run`, counting how it ended and how long it took.
770
+ *
771
+ * @param operation - The operation, one of the closed set.
772
+ * @param run - The operation; its result or its error passes through unchanged.
773
+ * @param options - A span to start, and what to state of the result.
774
+ */
775
+ observe<T>(operation: StorageOperation, run: () => Promise<T>, options?: ObservedOptions<T>): Promise<T>;
776
+ /**
777
+ * Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
778
+ *
779
+ * @param mode - When the scan runs, `pre-upload` or `post-upload`.
780
+ * @param run - The scan; its result or its error passes through unchanged.
781
+ */
782
+ scan<T extends {
783
+ readonly status: string;
784
+ }>(mode: string, run: () => Promise<T>): Promise<T>;
785
+ }
786
+
672
787
  /** Input shape for a scan request. */
673
788
  interface ScanInput {
674
789
  mode: 'pre-upload' | 'post-upload';
@@ -681,8 +796,9 @@ interface ScanInput {
681
796
  declare class FileScannerService {
682
797
  private readonly options;
683
798
  private readonly scanner;
799
+ private readonly observer?;
684
800
  private readonly logger;
685
- constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
801
+ constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null, observer?: StorageObserver | undefined);
686
802
  /**
687
803
  * Returns `true` when both a scanner implementation and scanner options are
688
804
  * configured.
@@ -708,13 +824,22 @@ declare class FileScannerService {
708
824
  * says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
709
825
  *
710
826
  * @param input - The scan input.
827
+ * @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
828
+ * bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
711
829
  * @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
712
830
  * @throws Error when called without a configured scanner.
713
831
  * @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
714
832
  * @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
715
833
  * @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
716
834
  */
717
- scan(input: ScanInput): Promise<FileScanResult>;
835
+ scan(input: ScanInput, caller?: Record<string, unknown>): Promise<FileScanResult>;
836
+ /** Runs the scanner and applies the library's policy to what it answered. */
837
+ private evaluate;
838
+ /**
839
+ * `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
840
+ * exactly one of the three): the object is not known to be clean, so it is not stored.
841
+ */
842
+ private rejectInconclusive;
718
843
  /**
719
844
  * Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
720
845
  * line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
@@ -813,8 +938,9 @@ declare class StorageService {
813
938
  private readonly idempotencyCache;
814
939
  private readonly validation;
815
940
  private readonly scanner;
941
+ protected readonly observer?: StorageObserver | undefined;
816
942
  private readonly logger;
817
- constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
943
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService, observer?: StorageObserver | undefined);
818
944
  /**
819
945
  * Uploads an object, choosing single-shot or multipart automatically. When an
820
946
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
@@ -929,14 +1055,12 @@ declare class StorageService {
929
1055
  * `STORAGE_BUCKET_UNDEFINED` before any request.
930
1056
  */
931
1057
  checkBucket(options?: BucketScopedOptions): Promise<void>;
1058
+ /** What the single-shot upload needs of this service. */
1059
+ private get uploadContext();
932
1060
  /** Throws when the S3 client was never built (missing credentials). */
933
1061
  private assertConfigured;
934
1062
  /** Resolves the target bucket from a per-call override or the module default. */
935
1063
  private resolveBucket;
936
- /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
937
- private toObjectMetadata;
938
- /** Single `PutObject` upload for bodies below the multipart threshold. */
939
- private uploadSingleShot;
940
1064
  /**
941
1065
  * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
942
1066
  * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
@@ -1060,7 +1184,8 @@ declare class SignedUrlService {
1060
1184
  private readonly options;
1061
1185
  private readonly s3Provider;
1062
1186
  private readonly keyResolver;
1063
- constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1187
+ protected readonly observer?: StorageObserver | undefined;
1188
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
1064
1189
  /**
1065
1190
  * Issues a presigned GET URL for downloading an object.
1066
1191
  *
@@ -1203,7 +1328,8 @@ declare class BucketLifecycleService {
1203
1328
  private readonly options;
1204
1329
  private readonly s3Provider;
1205
1330
  private readonly keyResolver;
1206
- constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1331
+ protected readonly observer?: StorageObserver | undefined;
1332
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
1207
1333
  /**
1208
1334
  * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
1209
1335
  * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
@@ -1489,5 +1615,5 @@ declare class StorageException extends HttpException {
1489
1615
  message?: string);
1490
1616
  }
1491
1617
 
1492
- 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 };
1493
- 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 };
1618
+ export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BucketLifecycleService, BymaxStorageModule, NoOpFileScanner, NoOpUploadValidator, SCAN_VERDICTS, STORAGE_ERROR_CODES, STORAGE_OPERATIONS, STORAGE_OUTCOMES, SignedUrlService, StorageException, StorageMetricsTally, StorageService, providerRecipes };
1619
+ 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, ScanVerdict, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, StorageOperation, StorageOutcome, UploadOptions, UploadResult };
@@ -669,6 +669,121 @@ declare class ValidationService {
669
669
  private runCustomValidators;
670
670
  }
671
671
 
672
+ /** The operations the library counts and times. */
673
+ declare const STORAGE_OPERATIONS: readonly ["upload", "download", "head", "delete", "delete_many", "list", "copy", "get_download_url", "get_upload_url", "get_multipart_upload_urls", "check_bucket", "lifecycle_get", "lifecycle_upsert", "lifecycle_remove"];
674
+ /** What an operation ended as. */
675
+ declare const STORAGE_OUTCOMES: readonly ["success", "not_found", "aborted", "error"];
676
+ /** What a scan ended as. */
677
+ declare const SCAN_VERDICTS: readonly ["clean", "infected", "unknown", "timeout", "error"];
678
+ /** One of {@link STORAGE_OPERATIONS}. */
679
+ type StorageOperation = (typeof STORAGE_OPERATIONS)[number];
680
+ /** One of {@link STORAGE_OUTCOMES}. */
681
+ type StorageOutcome = (typeof STORAGE_OUTCOMES)[number];
682
+ /** One of {@link SCAN_VERDICTS}. */
683
+ type ScanVerdict = (typeof SCAN_VERDICTS)[number];
684
+
685
+ /** Told how long an operation took, once it ended. Typed to return a value: a listener typed `void` can still return a promise. */
686
+ type DurationListener = (operation: StorageOperation, seconds: number) => unknown;
687
+ /**
688
+ * Counts what the storage operations do. Each count is keyed by a closed set (see `storage-operations`), so no
689
+ * label can grow with the traffic, and nothing a caller or a host supplied is ever a key. The optional
690
+ * `observability` subpath reads these numbers when it is scraped, and feeds a duration histogram through
691
+ * {@link StorageMetricsTally.onDuration}.
692
+ */
693
+ declare class StorageMetricsTally {
694
+ #private;
695
+ /** An operation ended as `outcome` after `seconds`. */
696
+ operation(operation: StorageOperation, outcome: StorageOutcome, seconds: number): void;
697
+ /** `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. */
698
+ bytesUploaded(bytes: number | undefined): void;
699
+ /** A scan ended as `verdict`. */
700
+ scan(verdict: ScanVerdict): void;
701
+ /** Calls `listener` with the duration of every operation that ends from now on. */
702
+ onDuration(listener: DurationListener): void;
703
+ /** The counts so far, as copies. */
704
+ snapshot(): {
705
+ readonly operations: Readonly<Record<StorageOperation, Readonly<Record<StorageOutcome, number>>>>;
706
+ readonly bytesUploaded: number;
707
+ readonly scans: Readonly<Record<ScanVerdict, number>>;
708
+ };
709
+ }
710
+
711
+ /** The span names the library starts. */
712
+ type StorageSpanName = 'storage.upload' | 'storage.download_url' | 'storage.scan';
713
+ /** Attributes are closed: an operation, an outcome, a mode or a flag, never a key, a bucket or a payload. */
714
+ type StorageSpanAttributes = Readonly<Record<string, string>>;
715
+ /** What a span states of a result, once the operation succeeded. */
716
+ type ResultAttributes<T> = (result: T) => StorageSpanAttributes;
717
+ /**
718
+ * Starts a span around an operation when `@opentelemetry/api` is installed, and runs it bare otherwise.
719
+ *
720
+ * The peer is optional, so it is loaded with a dynamic `import()` that a missing package turns into a no-op:
721
+ * the server bundle never names it statically, and an application that does not trace installs nothing. With
722
+ * the API present and no SDK registered the API itself is a no-op. A span carries a closed set of attributes
723
+ * and, on failure, the library error code and nothing of the message.
724
+ */
725
+ declare class StorageTracing implements OnModuleInit {
726
+ #private;
727
+ /** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
728
+ onModuleInit(): Promise<void>;
729
+ /** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
730
+ private traced;
731
+ /**
732
+ * Runs `run` inside a span named `name`.
733
+ *
734
+ * The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
735
+ * throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
736
+ * otherwise, and its own result or error is what comes back.
737
+ *
738
+ * @param name - One of the library's span names.
739
+ * @param attributes - Closed-set attributes of the span.
740
+ * @param run - The operation; its result or its error passes through unchanged.
741
+ * @param describe - What the span states of a successful result; a throw of its own is the operation's own.
742
+ */
743
+ span<T>(name: StorageSpanName, attributes: StorageSpanAttributes, run: () => Promise<T>, describe?: ResultAttributes<T>): Promise<T>;
744
+ }
745
+
746
+ /** What an observed operation adds to the plain count and timing. */
747
+ interface ObservedOptions<T> {
748
+ /** The span to start around the operation. */
749
+ readonly span?: StorageSpanName;
750
+ /** Attributes the span starts with. */
751
+ readonly attributes?: StorageSpanAttributes;
752
+ /** What the span states of a successful result. */
753
+ readonly describe?: (result: T) => StorageSpanAttributes;
754
+ /** The bytes of a successful result that reached the provider, for the upload counter. */
755
+ readonly bytes?: (result: T) => number | undefined;
756
+ }
757
+ /**
758
+ * Observes the operations of the library.
759
+ *
760
+ * It is a seam between the services and two optional consumers: the tally the `observability` subpath
761
+ * publishes from, and the span the host's OpenTelemetry SDK records. A service that is built without one
762
+ * (a unit test, say) runs its operations bare.
763
+ */
764
+ declare class StorageObserver {
765
+ private readonly tally;
766
+ private readonly tracing;
767
+ constructor(tally: StorageMetricsTally, tracing: StorageTracing);
768
+ /**
769
+ * Runs `run`, counting how it ended and how long it took.
770
+ *
771
+ * @param operation - The operation, one of the closed set.
772
+ * @param run - The operation; its result or its error passes through unchanged.
773
+ * @param options - A span to start, and what to state of the result.
774
+ */
775
+ observe<T>(operation: StorageOperation, run: () => Promise<T>, options?: ObservedOptions<T>): Promise<T>;
776
+ /**
777
+ * Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
778
+ *
779
+ * @param mode - When the scan runs, `pre-upload` or `post-upload`.
780
+ * @param run - The scan; its result or its error passes through unchanged.
781
+ */
782
+ scan<T extends {
783
+ readonly status: string;
784
+ }>(mode: string, run: () => Promise<T>): Promise<T>;
785
+ }
786
+
672
787
  /** Input shape for a scan request. */
673
788
  interface ScanInput {
674
789
  mode: 'pre-upload' | 'post-upload';
@@ -681,8 +796,9 @@ interface ScanInput {
681
796
  declare class FileScannerService {
682
797
  private readonly options;
683
798
  private readonly scanner;
799
+ private readonly observer?;
684
800
  private readonly logger;
685
- constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
801
+ constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null, observer?: StorageObserver | undefined);
686
802
  /**
687
803
  * Returns `true` when both a scanner implementation and scanner options are
688
804
  * configured.
@@ -708,13 +824,22 @@ declare class FileScannerService {
708
824
  * says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
709
825
  *
710
826
  * @param input - The scan input.
827
+ * @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
828
+ * bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
711
829
  * @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
712
830
  * @throws Error when called without a configured scanner.
713
831
  * @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
714
832
  * @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
715
833
  * @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
716
834
  */
717
- scan(input: ScanInput): Promise<FileScanResult>;
835
+ scan(input: ScanInput, caller?: Record<string, unknown>): Promise<FileScanResult>;
836
+ /** Runs the scanner and applies the library's policy to what it answered. */
837
+ private evaluate;
838
+ /**
839
+ * `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
840
+ * exactly one of the three): the object is not known to be clean, so it is not stored.
841
+ */
842
+ private rejectInconclusive;
718
843
  /**
719
844
  * Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
720
845
  * line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
@@ -813,8 +938,9 @@ declare class StorageService {
813
938
  private readonly idempotencyCache;
814
939
  private readonly validation;
815
940
  private readonly scanner;
941
+ protected readonly observer?: StorageObserver | undefined;
816
942
  private readonly logger;
817
- constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
943
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService, observer?: StorageObserver | undefined);
818
944
  /**
819
945
  * Uploads an object, choosing single-shot or multipart automatically. When an
820
946
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
@@ -929,14 +1055,12 @@ declare class StorageService {
929
1055
  * `STORAGE_BUCKET_UNDEFINED` before any request.
930
1056
  */
931
1057
  checkBucket(options?: BucketScopedOptions): Promise<void>;
1058
+ /** What the single-shot upload needs of this service. */
1059
+ private get uploadContext();
932
1060
  /** Throws when the S3 client was never built (missing credentials). */
933
1061
  private assertConfigured;
934
1062
  /** Resolves the target bucket from a per-call override or the module default. */
935
1063
  private resolveBucket;
936
- /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
937
- private toObjectMetadata;
938
- /** Single `PutObject` upload for bodies below the multipart threshold. */
939
- private uploadSingleShot;
940
1064
  /**
941
1065
  * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
942
1066
  * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
@@ -1060,7 +1184,8 @@ declare class SignedUrlService {
1060
1184
  private readonly options;
1061
1185
  private readonly s3Provider;
1062
1186
  private readonly keyResolver;
1063
- constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1187
+ protected readonly observer?: StorageObserver | undefined;
1188
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
1064
1189
  /**
1065
1190
  * Issues a presigned GET URL for downloading an object.
1066
1191
  *
@@ -1203,7 +1328,8 @@ declare class BucketLifecycleService {
1203
1328
  private readonly options;
1204
1329
  private readonly s3Provider;
1205
1330
  private readonly keyResolver;
1206
- constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1331
+ protected readonly observer?: StorageObserver | undefined;
1332
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
1207
1333
  /**
1208
1334
  * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
1209
1335
  * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
@@ -1489,5 +1615,5 @@ declare class StorageException extends HttpException {
1489
1615
  message?: string);
1490
1616
  }
1491
1617
 
1492
- 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 };
1493
- 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 };
1618
+ export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BucketLifecycleService, BymaxStorageModule, NoOpFileScanner, NoOpUploadValidator, SCAN_VERDICTS, STORAGE_ERROR_CODES, STORAGE_OPERATIONS, STORAGE_OUTCOMES, SignedUrlService, StorageException, StorageMetricsTally, StorageService, providerRecipes };
1619
+ 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, ScanVerdict, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, StorageOperation, StorageOutcome, UploadOptions, UploadResult };