@bymax-one/nest-storage 1.1.0 → 1.1.2

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,5 +1,5 @@
1
1
  import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
2
- import { S3Client } from '@aws-sdk/client-s3';
2
+ import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
3
3
 
4
4
  /**
5
5
  * @fileoverview Pluggable upload-validator contract. Implementations run in order
@@ -360,7 +360,7 @@ interface DownloadOptions {
360
360
  */
361
361
  /** Outcome of an upload — returned to the caller. */
362
362
  interface UploadResult {
363
- /** Final key after normalization and the global key prefix. */
363
+ /** The object key relative to `keyPrefix`: pass it back to any method as is. */
364
364
  key: string;
365
365
  bucket: string;
366
366
  etag: string;
@@ -712,17 +712,33 @@ declare class StorageService {
712
712
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
713
713
  * window, the cached result is returned without re-uploading.
714
714
  *
715
+ * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
716
+ * upload is rejected for any reason (configuration, validation, scan, provider failure)
717
+ * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
718
+ * that nothing listens to), which releases the file handle or socket behind it; a cache hit
719
+ * destroys it unread. A stream consumed by a successful upload ends on its own.
720
+ *
715
721
  * @param options - The upload request.
716
722
  * @returns The upload result.
717
723
  * @throws StorageException for missing configuration, body, or content type.
718
724
  */
719
725
  upload(options: UploadOptions): Promise<UploadResult>;
726
+ /** The upload itself; `upload()` destroys a stream body when this rejects. */
727
+ private uploadOwningBody;
728
+ /**
729
+ * In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
730
+ * and the upload see the same bytes; a stream is single-use, and one the scanner
731
+ * had consumed would leave the upload with nothing to send. The read is bounded by
732
+ * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
733
+ * buffered without limit. Other bodies and modes pass through unchanged.
734
+ */
735
+ private bufferForPreUploadScan;
720
736
  /** Runs a pre-upload scan when configured; throws on infected. */
721
737
  private runPreUploadScan;
722
738
  /**
723
- * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
724
- * the scanner always receives its declared contract type; streams pass through
725
- * unchanged.
739
+ * Coerces the scan body to a `Buffer` so the scanner always receives its declared
740
+ * contract type. In pre-upload mode a stream has already been buffered by
741
+ * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
726
742
  */
727
743
  private normalizeScanBody;
728
744
  /**
@@ -987,6 +1003,7 @@ declare class SignedUrlService {
987
1003
  * @param options - The multipart URL options.
988
1004
  * @returns `uploadId`, `partUrls`, and `completeUrl`.
989
1005
  * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
1006
+ * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
990
1007
  * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
991
1008
  * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
992
1009
  */
@@ -999,6 +1016,146 @@ declare class SignedUrlService {
999
1016
  private resolveBucket;
1000
1017
  }
1001
1018
 
1019
+ /**
1020
+ * @fileoverview Public contracts for `BucketLifecycleService`: the rule shape
1021
+ * the library owns, the per-call bucket override, and the provider rule type.
1022
+ * @layer server/interfaces
1023
+ */
1024
+
1025
+ /**
1026
+ * A lifecycle rule exactly as the provider stores it. Reads return every rule in
1027
+ * the bucket, including ones this library did not write (transitions, tag
1028
+ * filters, multipart aborts), and writes send them back unchanged.
1029
+ */
1030
+ type BucketLifecycleRule = LifecycleRule;
1031
+ /**
1032
+ * A rule as `get()` returns it. `isOutsideKeyPrefix` is set (to `true`) only on a rule
1033
+ * that is not confined to the module's `keyPrefix` — written by another application, or
1034
+ * by hand — and `upsert()` / `remove()` refuse to change such a rule.
1035
+ */
1036
+ type BucketLifecycleRuleView = BucketLifecycleRule & {
1037
+ isOutsideKeyPrefix?: true;
1038
+ };
1039
+ /** Per-call override of the target bucket. */
1040
+ interface LifecycleBucketOptions {
1041
+ /** Defaults to the module's configured bucket. */
1042
+ bucket?: string;
1043
+ }
1044
+ /** A rule `BucketLifecycleService.upsert()` writes: expire a prefix after N days. */
1045
+ interface ExpirationRuleInput {
1046
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1047
+ id: string;
1048
+ /** Key prefix the rule applies to. Relative to the module's `keyPrefix`, like every other key. */
1049
+ prefix: string;
1050
+ /** Days after creation until an object under the prefix expires. A positive integer. */
1051
+ expirationDays: number;
1052
+ /** A rule is an expiration or an abort rule, never both. */
1053
+ abortIncompleteMultipartDays?: never;
1054
+ }
1055
+ /**
1056
+ * A rule `BucketLifecycleService.upsert()` writes: abort multipart uploads that were not completed
1057
+ * within N days of starting, which frees the parts they hold.
1058
+ */
1059
+ interface AbortMultipartRuleInput {
1060
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1061
+ id: string;
1062
+ /**
1063
+ * Key prefix the rule applies to, relative to the module's `keyPrefix`. May be empty, which means
1064
+ * every upload in the module's namespace: unlike expiration, aborting a stale upload deletes no object.
1065
+ */
1066
+ prefix: string;
1067
+ /** Days after an upload starts until it is aborted. A positive integer. */
1068
+ abortIncompleteMultipartDays: number;
1069
+ /** A rule is an expiration or an abort rule, never both. */
1070
+ expirationDays?: never;
1071
+ }
1072
+ /** Either rule shape `BucketLifecycleService.upsert()` accepts. */
1073
+ type LifecycleRuleInput = ExpirationRuleInput | AbortMultipartRuleInput;
1074
+
1075
+ /**
1076
+ * Manages the bucket's lifecycle configuration without disturbing rules it did
1077
+ * not write.
1078
+ *
1079
+ * Concurrency: `upsert` and `remove` read the configuration, change it in memory
1080
+ * and write all of it back. S3 has no conditional write for lifecycle
1081
+ * configuration, so another writer that changes the bucket between the read and
1082
+ * the write is overwritten. Serialize lifecycle changes in the caller (one
1083
+ * operator command, or a single deployment step) rather than relying on this
1084
+ * service to lock.
1085
+ */
1086
+ declare class BucketLifecycleService {
1087
+ private readonly options;
1088
+ private readonly s3Provider;
1089
+ private readonly keyResolver;
1090
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1091
+ /**
1092
+ * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
1093
+ * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
1094
+ * relative to it, as `list()` returns keys, so a prefix read here can be passed
1095
+ * straight to `upsert()` without being prefixed twice. A rule that is not confined
1096
+ * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
1097
+ * everything else about a rule is returned as the provider stores it.
1098
+ *
1099
+ * @param options - Optional per-call bucket override.
1100
+ * @returns Every rule in the bucket.
1101
+ * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
1102
+ */
1103
+ get(options?: LifecycleBucketOptions): Promise<BucketLifecycleRuleView[]>;
1104
+ /**
1105
+ * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
1106
+ * the full set back. Rules with other ids are sent exactly as they were read.
1107
+ *
1108
+ * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
1109
+ * @param options - Optional per-call bucket override.
1110
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
1111
+ * that names a rule outside `keyPrefix`;
1112
+ * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
1113
+ * @example
1114
+ * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
1115
+ */
1116
+ upsert(rule: LifecycleRuleInput, options?: LifecycleBucketOptions): Promise<void>;
1117
+ /**
1118
+ * Removes the rule with this id. When it was the last rule the configuration is
1119
+ * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
1120
+ *
1121
+ * @param id - The rule id.
1122
+ * @param options - Optional per-call bucket override.
1123
+ * @returns `true` when a rule was removed, `false` when no rule had that id.
1124
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
1125
+ * outside `keyPrefix`; a provider failure otherwise.
1126
+ */
1127
+ remove(id: string, options?: LifecycleBucketOptions): Promise<boolean>;
1128
+ /**
1129
+ * Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
1130
+ * with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
1131
+ * (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
1132
+ */
1133
+ private isWithinKeyPrefix;
1134
+ /** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
1135
+ private toView;
1136
+ /** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
1137
+ private assertOwnable;
1138
+ /**
1139
+ * Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
1140
+ * carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
1141
+ * `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
1142
+ */
1143
+ private stripRulePrefixes;
1144
+ /** Reads the configuration; "none yet" is an empty snapshot. */
1145
+ private read;
1146
+ /**
1147
+ * Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
1148
+ * requires at least one rule on a put. The default-minimum-object-size setting
1149
+ * read earlier is sent back so a write does not silently change transition behaviour.
1150
+ */
1151
+ private write;
1152
+ /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
1153
+ private toRule;
1154
+ private assertRuleId;
1155
+ private assertConfigured;
1156
+ private resolveBucket;
1157
+ }
1158
+
1002
1159
  /**
1003
1160
  * @fileoverview No-operation upload validator — always passes. Use as the
1004
1161
  * default when no custom validation logic is needed.
@@ -1142,8 +1299,6 @@ declare const BYMAX_STORAGE_OPTIONS: unique symbol;
1142
1299
  declare const BYMAX_STORAGE_S3_CLIENT: unique symbol;
1143
1300
  declare const BYMAX_STORAGE_UPLOAD_VALIDATORS: unique symbol;
1144
1301
  declare const BYMAX_STORAGE_FILE_SCANNER: unique symbol;
1145
- declare const BYMAX_STORAGE_LOGGER: unique symbol;
1146
- declare const BYMAX_STORAGE_IDEMPOTENCY_CACHE: unique symbol;
1147
1302
 
1148
1303
  /**
1149
1304
  * @fileoverview Provider-recipe contract — a factory that produces
@@ -1182,6 +1337,11 @@ declare const STORAGE_ERROR_CODES: {
1182
1337
  readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
1183
1338
  readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
1184
1339
  readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
1340
+ readonly STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID";
1341
+ readonly STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED";
1342
+ readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
1343
+ readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
1344
+ readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
1185
1345
  };
1186
1346
  /** Union of every stable storage error code. */
1187
1347
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1207,4 +1367,4 @@ declare class StorageException extends HttpException {
1207
1367
  statusCode?: HttpStatus, details?: Record<string, unknown>);
1208
1368
  }
1209
1369
 
1210
- export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_IDEMPOTENCY_CACHE, BYMAX_STORAGE_LOGGER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
1370
+ export { type AbortMultipartRuleInput, BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, type BucketLifecycleRule, type BucketLifecycleRuleView, BucketLifecycleService, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type ExpirationRuleInput, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type LifecycleBucketOptions, type LifecycleRuleInput, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
@@ -1,5 +1,5 @@
1
1
  import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
2
- import { S3Client } from '@aws-sdk/client-s3';
2
+ import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
3
3
 
4
4
  /**
5
5
  * @fileoverview Pluggable upload-validator contract. Implementations run in order
@@ -360,7 +360,7 @@ interface DownloadOptions {
360
360
  */
361
361
  /** Outcome of an upload — returned to the caller. */
362
362
  interface UploadResult {
363
- /** Final key after normalization and the global key prefix. */
363
+ /** The object key relative to `keyPrefix`: pass it back to any method as is. */
364
364
  key: string;
365
365
  bucket: string;
366
366
  etag: string;
@@ -712,17 +712,33 @@ declare class StorageService {
712
712
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
713
713
  * window, the cached result is returned without re-uploading.
714
714
  *
715
+ * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
716
+ * upload is rejected for any reason (configuration, validation, scan, provider failure)
717
+ * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
718
+ * that nothing listens to), which releases the file handle or socket behind it; a cache hit
719
+ * destroys it unread. A stream consumed by a successful upload ends on its own.
720
+ *
715
721
  * @param options - The upload request.
716
722
  * @returns The upload result.
717
723
  * @throws StorageException for missing configuration, body, or content type.
718
724
  */
719
725
  upload(options: UploadOptions): Promise<UploadResult>;
726
+ /** The upload itself; `upload()` destroys a stream body when this rejects. */
727
+ private uploadOwningBody;
728
+ /**
729
+ * In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
730
+ * and the upload see the same bytes; a stream is single-use, and one the scanner
731
+ * had consumed would leave the upload with nothing to send. The read is bounded by
732
+ * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
733
+ * buffered without limit. Other bodies and modes pass through unchanged.
734
+ */
735
+ private bufferForPreUploadScan;
720
736
  /** Runs a pre-upload scan when configured; throws on infected. */
721
737
  private runPreUploadScan;
722
738
  /**
723
- * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
724
- * the scanner always receives its declared contract type; streams pass through
725
- * unchanged.
739
+ * Coerces the scan body to a `Buffer` so the scanner always receives its declared
740
+ * contract type. In pre-upload mode a stream has already been buffered by
741
+ * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
726
742
  */
727
743
  private normalizeScanBody;
728
744
  /**
@@ -987,6 +1003,7 @@ declare class SignedUrlService {
987
1003
  * @param options - The multipart URL options.
988
1004
  * @returns `uploadId`, `partUrls`, and `completeUrl`.
989
1005
  * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
1006
+ * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
990
1007
  * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
991
1008
  * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
992
1009
  */
@@ -999,6 +1016,146 @@ declare class SignedUrlService {
999
1016
  private resolveBucket;
1000
1017
  }
1001
1018
 
1019
+ /**
1020
+ * @fileoverview Public contracts for `BucketLifecycleService`: the rule shape
1021
+ * the library owns, the per-call bucket override, and the provider rule type.
1022
+ * @layer server/interfaces
1023
+ */
1024
+
1025
+ /**
1026
+ * A lifecycle rule exactly as the provider stores it. Reads return every rule in
1027
+ * the bucket, including ones this library did not write (transitions, tag
1028
+ * filters, multipart aborts), and writes send them back unchanged.
1029
+ */
1030
+ type BucketLifecycleRule = LifecycleRule;
1031
+ /**
1032
+ * A rule as `get()` returns it. `isOutsideKeyPrefix` is set (to `true`) only on a rule
1033
+ * that is not confined to the module's `keyPrefix` — written by another application, or
1034
+ * by hand — and `upsert()` / `remove()` refuse to change such a rule.
1035
+ */
1036
+ type BucketLifecycleRuleView = BucketLifecycleRule & {
1037
+ isOutsideKeyPrefix?: true;
1038
+ };
1039
+ /** Per-call override of the target bucket. */
1040
+ interface LifecycleBucketOptions {
1041
+ /** Defaults to the module's configured bucket. */
1042
+ bucket?: string;
1043
+ }
1044
+ /** A rule `BucketLifecycleService.upsert()` writes: expire a prefix after N days. */
1045
+ interface ExpirationRuleInput {
1046
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1047
+ id: string;
1048
+ /** Key prefix the rule applies to. Relative to the module's `keyPrefix`, like every other key. */
1049
+ prefix: string;
1050
+ /** Days after creation until an object under the prefix expires. A positive integer. */
1051
+ expirationDays: number;
1052
+ /** A rule is an expiration or an abort rule, never both. */
1053
+ abortIncompleteMultipartDays?: never;
1054
+ }
1055
+ /**
1056
+ * A rule `BucketLifecycleService.upsert()` writes: abort multipart uploads that were not completed
1057
+ * within N days of starting, which frees the parts they hold.
1058
+ */
1059
+ interface AbortMultipartRuleInput {
1060
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1061
+ id: string;
1062
+ /**
1063
+ * Key prefix the rule applies to, relative to the module's `keyPrefix`. May be empty, which means
1064
+ * every upload in the module's namespace: unlike expiration, aborting a stale upload deletes no object.
1065
+ */
1066
+ prefix: string;
1067
+ /** Days after an upload starts until it is aborted. A positive integer. */
1068
+ abortIncompleteMultipartDays: number;
1069
+ /** A rule is an expiration or an abort rule, never both. */
1070
+ expirationDays?: never;
1071
+ }
1072
+ /** Either rule shape `BucketLifecycleService.upsert()` accepts. */
1073
+ type LifecycleRuleInput = ExpirationRuleInput | AbortMultipartRuleInput;
1074
+
1075
+ /**
1076
+ * Manages the bucket's lifecycle configuration without disturbing rules it did
1077
+ * not write.
1078
+ *
1079
+ * Concurrency: `upsert` and `remove` read the configuration, change it in memory
1080
+ * and write all of it back. S3 has no conditional write for lifecycle
1081
+ * configuration, so another writer that changes the bucket between the read and
1082
+ * the write is overwritten. Serialize lifecycle changes in the caller (one
1083
+ * operator command, or a single deployment step) rather than relying on this
1084
+ * service to lock.
1085
+ */
1086
+ declare class BucketLifecycleService {
1087
+ private readonly options;
1088
+ private readonly s3Provider;
1089
+ private readonly keyResolver;
1090
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1091
+ /**
1092
+ * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
1093
+ * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
1094
+ * relative to it, as `list()` returns keys, so a prefix read here can be passed
1095
+ * straight to `upsert()` without being prefixed twice. A rule that is not confined
1096
+ * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
1097
+ * everything else about a rule is returned as the provider stores it.
1098
+ *
1099
+ * @param options - Optional per-call bucket override.
1100
+ * @returns Every rule in the bucket.
1101
+ * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
1102
+ */
1103
+ get(options?: LifecycleBucketOptions): Promise<BucketLifecycleRuleView[]>;
1104
+ /**
1105
+ * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
1106
+ * the full set back. Rules with other ids are sent exactly as they were read.
1107
+ *
1108
+ * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
1109
+ * @param options - Optional per-call bucket override.
1110
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
1111
+ * that names a rule outside `keyPrefix`;
1112
+ * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
1113
+ * @example
1114
+ * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
1115
+ */
1116
+ upsert(rule: LifecycleRuleInput, options?: LifecycleBucketOptions): Promise<void>;
1117
+ /**
1118
+ * Removes the rule with this id. When it was the last rule the configuration is
1119
+ * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
1120
+ *
1121
+ * @param id - The rule id.
1122
+ * @param options - Optional per-call bucket override.
1123
+ * @returns `true` when a rule was removed, `false` when no rule had that id.
1124
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
1125
+ * outside `keyPrefix`; a provider failure otherwise.
1126
+ */
1127
+ remove(id: string, options?: LifecycleBucketOptions): Promise<boolean>;
1128
+ /**
1129
+ * Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
1130
+ * with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
1131
+ * (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
1132
+ */
1133
+ private isWithinKeyPrefix;
1134
+ /** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
1135
+ private toView;
1136
+ /** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
1137
+ private assertOwnable;
1138
+ /**
1139
+ * Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
1140
+ * carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
1141
+ * `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
1142
+ */
1143
+ private stripRulePrefixes;
1144
+ /** Reads the configuration; "none yet" is an empty snapshot. */
1145
+ private read;
1146
+ /**
1147
+ * Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
1148
+ * requires at least one rule on a put. The default-minimum-object-size setting
1149
+ * read earlier is sent back so a write does not silently change transition behaviour.
1150
+ */
1151
+ private write;
1152
+ /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
1153
+ private toRule;
1154
+ private assertRuleId;
1155
+ private assertConfigured;
1156
+ private resolveBucket;
1157
+ }
1158
+
1002
1159
  /**
1003
1160
  * @fileoverview No-operation upload validator — always passes. Use as the
1004
1161
  * default when no custom validation logic is needed.
@@ -1142,8 +1299,6 @@ declare const BYMAX_STORAGE_OPTIONS: unique symbol;
1142
1299
  declare const BYMAX_STORAGE_S3_CLIENT: unique symbol;
1143
1300
  declare const BYMAX_STORAGE_UPLOAD_VALIDATORS: unique symbol;
1144
1301
  declare const BYMAX_STORAGE_FILE_SCANNER: unique symbol;
1145
- declare const BYMAX_STORAGE_LOGGER: unique symbol;
1146
- declare const BYMAX_STORAGE_IDEMPOTENCY_CACHE: unique symbol;
1147
1302
 
1148
1303
  /**
1149
1304
  * @fileoverview Provider-recipe contract — a factory that produces
@@ -1182,6 +1337,11 @@ declare const STORAGE_ERROR_CODES: {
1182
1337
  readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
1183
1338
  readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
1184
1339
  readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
1340
+ readonly STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID";
1341
+ readonly STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED";
1342
+ readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
1343
+ readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
1344
+ readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
1185
1345
  };
1186
1346
  /** Union of every stable storage error code. */
1187
1347
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1207,4 +1367,4 @@ declare class StorageException extends HttpException {
1207
1367
  statusCode?: HttpStatus, details?: Record<string, unknown>);
1208
1368
  }
1209
1369
 
1210
- export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_IDEMPOTENCY_CACHE, BYMAX_STORAGE_LOGGER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
1370
+ export { type AbortMultipartRuleInput, BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, type BucketLifecycleRule, type BucketLifecycleRuleView, BucketLifecycleService, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type ExpirationRuleInput, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type LifecycleBucketOptions, type LifecycleRuleInput, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };