@bymax-one/nest-storage 1.1.1 → 1.1.3

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,151 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.3] - 2026-11-01
17
+
18
+ ### Fixed
19
+
20
+ - **A stream that stops delivering no longer holds a multipart upload open forever.** A multipart upload
21
+ waiting for the next bytes of a stream has no request in flight, so `requestTimeoutMs` never fired:
22
+ a client that sent a few MiB and went silent left `upload()` pending and the upload (and its parts)
23
+ open on the provider until a lifecycle rule reaped it. A new `uploadIdleTimeoutMs` bounds the silence.
24
+ Past it the library sends `AbortMultipartUpload`, destroys your stream and rejects `upload()` with
25
+ `STORAGE_TIMEOUT` and `details.phase: 'source-idle'`. The clock restarts on every chunk and runs only
26
+ while the library is waiting for data.
27
+
28
+ **Apply to a derived backend:** a behaviour change, on by default. A stream source that delivers no
29
+ bytes for `uploadIdleTimeoutMs` now aborts the multipart upload and rejects `STORAGE_TIMEOUT`; the
30
+ limit defaults to `requestTimeoutMs` (30 s). Set `uploadIdleTimeoutMs: 0` to restore the old
31
+ behaviour, or raise it for a source that legitimately pauses longer. It applies only to a stream that
32
+ takes the multipart path (no `size`, or at or above `multipart.thresholdBytes`); single-shot uploads
33
+ and `Buffer` bodies are unchanged. An invalid value (negative, fractional, not a number) is rejected
34
+ at startup as `STORAGE_INVALID_CONFIG`.
35
+ - **Reporting a failure can no longer replace it.** `deleteMany()`, the post-upload cleanup, `exists()` and
36
+ the multipart error mapping built a message with `String(err)` or `err.message`; for a rejection value
37
+ with no usable `toString` (an object with no prototype, one whose `toString` throws) that raised from
38
+ inside the catch and the new error escaped in place of the one being reported. A value is now described
39
+ by its string `message`, else its string form, else `non-printable rejection value`, and never throws.
40
+
41
+ ## [1.1.2] - 2026-10-31
42
+
43
+ ### Changed
44
+
45
+ - **Keys the library returns are relative to `keyPrefix`, so every one can be passed back.**
46
+ `UploadResult.key` and `ObjectMetadata.key` (from `head`, `download`, `downloadBuffer`) carried
47
+ the `keyPrefix`, while every method prepends it again, so with a prefix set `head(r.key)`,
48
+ `exists`, `download`, `delete` and a signed-URL call addressed `prefix/prefix/key`. `delete`
49
+ was the quiet one: it removed nothing and reported success. `list()` and `deleteMany()` already
50
+ returned relative keys. `UploadResult.publicUrl` is unchanged and still carries the prefix.
51
+
52
+ **Apply to a derived backend:** only a deployment with a non-empty `keyPrefix` is affected. In
53
+ 1.0.0 to 1.1.1 the returned key is `prefix/name` and cannot be passed back; from this release it is
54
+ `name`. A `.key` value you stored from an earlier version carries the prefix: strip it once (for
55
+ example `stored.slice(prefix.length + 1)`, where `prefix` is the normalized `keyPrefix` without
56
+ surrounding slashes) before passing it to the library, and when you read keys from your database
57
+ stop adding or removing the prefix yourself.
58
+ - **`upload()` destroys a `Readable` body it rejects.** A rejected upload (invalid key or content
59
+ type, a validation or scan failure, a provider error) used to leave the caller's stream open, so the
60
+ file handle or the connection behind it stayed held. The library now takes ownership of the stream, as
61
+ `stream.pipeline` does, and destroys it; a cache hit destroys it unread. The stream is destroyed
62
+ without an error, because the AWS SDK (under its default checksum setting) wraps a stream body in its
63
+ own Readable and forwards the source's error to it, and nothing listens to that wrapper once the
64
+ request has failed; the failure is the rejection of `upload()`, and a listener on the stream sees
65
+ `'close'`. Destroying can still emit `'error'` when the stream's own cleanup fails, so the library
66
+ attaches a no-op listener first.
67
+
68
+ **Apply to a derived backend:** do not reuse a stream you passed to `upload()`. A caller that
69
+ fixed a validation error and retried with the same, still unread, stream must open a new one.
70
+
71
+ ### Added
72
+
73
+ - **`STORAGE_NOT_MODIFIED` (304) and `STORAGE_PRECONDITION_FAILED` (412).** `download()` with
74
+ `ifNoneMatch` equal to the current ETag, or `ifMatch` that differs, used to surface as a generic
75
+ `STORAGE_PROVIDER_ERROR` (502); they now have their own codes, so a caller can branch on them.
76
+ A 304 is thrown, not returned.
77
+ - **`BucketLifecycleService.upsert` writes multipart-abort rules.** An input with
78
+ `abortIncompleteMultipartDays` instead of `expirationDays` adds or replaces an
79
+ `AbortIncompleteMultipartUpload` rule, so abandoned multipart uploads stop holding storage. The
80
+ read-modify-write, the preservation of other rules and the `keyPrefix` rules are the same; an empty
81
+ prefix is allowed for this rule only (it means the module's whole namespace, and aborting deletes no
82
+ object). Types `AbortMultipartRuleInput` and `LifecycleRuleInput`. MinIO does not accept this rule
83
+ through the S3 API (the end-to-end suite shows the typed `STORAGE_LIFECYCLE_REJECTED`); AWS and R2
84
+ document it.
85
+ - **`BucketLifecycleService`: bucket lifecycle rules.** `get()` returns the rules (an empty array when
86
+ the bucket has no configuration), `upsert({ id, prefix, expirationDays })` adds or replaces one
87
+ expiration rule by id, and `remove(id)` deletes one. Both writes read the configuration, change
88
+ only the rule with that id and write the full set back, so every other rule (transitions, tag
89
+ filters, multipart aborts) is sent back as the provider returned it. Removing the last rule calls
90
+ `DeleteBucketLifecycle`, because S3 rejects a put with no rules. The read-modify-write is not
91
+ atomic: S3 has no conditional lifecycle write, so a concurrent writer can be overwritten.
92
+ The service is exported from the package and from the module.
93
+ - **Error codes:** `STORAGE_LIFECYCLE_RULE_INVALID` (400), `STORAGE_LIFECYCLE_UNSUPPORTED`
94
+ (501) and `STORAGE_LIFECYCLE_REJECTED` (422).
95
+ - Types `BucketLifecycleRule`, `BucketLifecycleRuleView`, `LifecycleBucketOptions` and
96
+ `ExpirationRuleInput`.
97
+
98
+ **Apply to a derived backend:** additive; nothing existing changes. A consumer that applies
99
+ lifecycle rules through the raw `S3Client` can switch to this service. Rule prefixes are relative
100
+ to `keyPrefix`; with a `keyPrefix` set, rules outside it are returned flagged and are not changed.
101
+ Providers other than MinIO (tested) and Cloudflare R2 (documented) are unverified; see the README.
102
+
103
+ ### Fixed
104
+
105
+ - **`requestTimeoutMs` now takes effect.** It was resolved and defaulted to 30 000 ms but never
106
+ passed to the S3 client, so a request to an endpoint that stopped answering waited forever. It is
107
+ now the client's `requestTimeout` with `throwOnRequestTimeout`, and an attempt that gets no
108
+ response headers in time fails as `STORAGE_TIMEOUT` (504). A failure inside a multipart upload
109
+ still surfaces as `STORAGE_MULTIPART_ABORTED`.
110
+
111
+ **Apply to a derived backend:** a behaviour change. The 30 s default now applies to every
112
+ attempt, and an upload body counts toward it: a single-shot upload that needs longer than 30 s
113
+ (a slow link, a body near `multipart.thresholdBytes`) now fails. Raise `requestTimeoutMs` for
114
+ such workloads before upgrading. It does not limit reading a download stream.
115
+ - **A stream body under a pre-upload scanner no longer hangs the upload.** The scanner and the upload
116
+ were handed the same stream object; a scanner that read it left the upload with nothing to send, and
117
+ `upload()` never returned (nothing was stored). In `pre-upload` mode a stream is now read into one
118
+ buffer, bounded by `validation.maxSizeBytes`, and the scanner and the upload share that buffer. A
119
+ stream longer than the limit, or any stream when `maxSizeBytes` is unset, is refused with
120
+ `STORAGE_VALIDATION_FAILED`.
121
+
122
+ **Apply to a derived backend:** if you scan streams before upload, set `validation.maxSizeBytes`
123
+ (or switch the scanner to `post-upload`), and expect the stream to be held in memory up to that size.
124
+ With `requestTimeoutMs` an upload whose stream was consumed fails as `STORAGE_TIMEOUT` instead of
125
+ hanging.
126
+ - **`getMultipartUploadUrls` validates `parts`.** Only `parts <= 0` was refused, so a fraction, `NaN`
127
+ or a count above S3's 10 000 part numbers was accepted. `parts` must now be an integer from 1 to
128
+ 10 000, or the call throws `STORAGE_INVALID_PART_COUNT`. The README documents the 5 MiB minimum for
129
+ every part but the last, the absence of an abort URL, and the `AbortIncompleteMultipartUpload`
130
+ lifecycle rule recommended against orphaned uploads.
131
+ - **`signedUrls.maxTtlSeconds` above 604 800 is reduced at init.** The SigV4 signer rejects any
132
+ expiry over 7 days, so a larger configured ceiling made every request above 7 days fail with a
133
+ provider error while shorter requests worked. The ceiling is now capped at 604 800 s when the
134
+ module starts, with one warning naming both values. A boot that worked before still boots.
135
+ - **`STORAGE_PART_TOO_SMALL` is documented as reserved.** Nothing throws it: a part size under the
136
+ S3 minimum is rejected at init as `STORAGE_INVALID_CONFIG`. The code stays in the contract.
137
+ - **The published-surface gate now fails on a wrong option, method or field in a README snippet.**
138
+ `check:published` ran `tsc` on the snippets, which stops after syntax errors and so never reported
139
+ the semantic ones once any snippet had a parse error; it compiled only snippets that import the
140
+ package; and it ignored every undeclared name, so a call through one resolved to `any`. Every
141
+ snippet is now compiled with the syntactic and semantic diagnostics together, public names are
142
+ imported for it, and the names a snippet takes from the surrounding prose are typed in
143
+ `scripts/readme-prelude.ts`. A diagnostic about a missing property is excused as an abbreviated
144
+ example only when the type is a plain identifier the snippet declares itself, searched outside its
145
+ imports, so a wrong method on an imported or union type fails.
146
+ The prelude is compiled as a `.ts` file, so a type in it that stops resolving is an error rather than
147
+ an `any`, and any syntax error in a snippet fails the gate.
148
+ - **README option defaults and examples now match the code.** The configuration table listed
149
+ `signedUrls.defaultTtlSeconds` (no such option; the options are `defaultGetTtlSeconds` and
150
+ `defaultPutTtlSeconds`, both 300 s, not 3600), a 10 MiB multipart threshold and an 8 MiB part size
151
+ (both are 5 MiB), a `'NONE'` module-level encryption value (accepted per upload only) and a "sensible
152
+ default" MIME whitelist (there is none). The validator, scanner-mode and multipart-URL examples used
153
+ names that do not exist (`validators`, `'both'`, `partCount`, `valid`). The error-code table now
154
+ matches the key guard (it rejects an empty key and a null byte, not "empty after normalization"),
155
+ and the `STORAGE_PART_TOO_SMALL` note says what the code does.
156
+ A new spec parses the README option-default table and the error-code table and fails when either
157
+ drifts from the code.
158
+
159
+ **Apply to a derived backend:** documentation only; no behaviour changed.
160
+
16
161
  ## [1.1.1] - 2026-10-30
17
162
 
18
163
  Apart from the removal below, nothing here changes the published bundle: the remaining entries are
@@ -334,4 +479,6 @@ have regressed from. They are kept because the reasoning is worth having.
334
479
  [1.0.6]: https://github.com/bymaxone/nest-storage/compare/v1.0.5...v1.0.6
335
480
  [1.1.0]: https://github.com/bymaxone/nest-storage/compare/v1.0.6...v1.1.0
336
481
  [1.1.1]: https://github.com/bymaxone/nest-storage/compare/v1.1.0...v1.1.1
337
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.1...HEAD
482
+ [1.1.2]: https://github.com/bymaxone/nest-storage/compare/v1.1.1...v1.1.2
483
+ [1.1.3]: https://github.com/bymaxone/nest-storage/compare/v1.1.2...v1.1.3
484
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.3...HEAD