@cloudbitmaps/s3 0.20.0 → 0.21.0

package/README.md

@@ -57,8 +57,9 @@ It builds its own client from your usual AWS credentials. Any other key is refus
   MinIO, 3.640.0 silently overwrites an existing object, which loses a published generation. `If-Match` on
   `PutObject`, which the registry's compare-and-swap is built on, is modelled from 3.700.0: 3.699.0's serializer
   omits it, so a fenced row write goes out unconditionally and can land over a concurrent writer's. This package's
-  own range never resolves below 3.700.0. The registry also checks, before its first request, that the client it is given sends `If-Match` on
-  `PutObject` and `DeleteObject`, and refuses a write it would send without its precondition.
+  own range never resolves below 3.700.0. The registry also checks, before its first request, that the client it is given sends `If-None-Match` and
+  `If-Match` on `PutObject`, and refuses a registry write it would send without its precondition; a client that does
+  not send `If-Match` on `DeleteObject` turns `conditionalDelete` off.
 - **Grant `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:AbortMultipartUpload` and `s3:ListBucket`.** Without
   `s3:ListBucket`, S3 answers a missing key with `403` instead of `404`.
 - **Add a lifecycle rule that aborts incomplete multipart uploads**, and never one that expires current objects or the

package/dist/aws-errors.d.ts

@@ -1,10 +1,3 @@
-/**
- * SDK-free helpers for classifying AWS-style errors (used by the S3 drivers).
- *
- * These only read structural shapes an AWS SDK v3 error carries — `name`, `$metadata.httpStatusCode`, a
- * lower-level `code`/`errno`, and the SDK's own `$retryable` marker — so the (subtle, easy-to-get-wrong)
- * transient-vs-fatal decision is unit-testable without a live backend or even the SDK installed. They import no SDK.
- */
 export declare function httpStatus(err: unknown): number | undefined;
 export declare function errorName(err: unknown): string | undefined;
 /** A lower-level transport code (e.g. `ECONNRESET`) — the Node networking layer sets `code`. */
@@ -13,5 +6,8 @@ export declare function errorCode(err: unknown): string | undefined;
 export declare function isSdkRetryable(err: unknown): boolean;
 /** Any 5xx is a server-side fault that's safe to retry (the request didn't deterministically fail). */
 export declare function isServerSide(err: unknown): boolean;
-/** A dropped/timed-out connection — transient by nature; a retry on a fresh connection usually succeeds. */
+/**
+ * A dropped/timed-out connection — transient by nature; a retry on a fresh connection usually succeeds. The SDK's
+ * transport error names, the codes Node gives a failed connection ({@link isTransportFault}), and the messages above.
+ */
 export declare function isNetworkOrTimeout(err: unknown): boolean;

package/dist/bounded-body.d.ts

@@ -1,5 +1,5 @@
 /** The `GetObject` response body, narrowed to the parts used. */
-export type ResponseBody = {
+type ResponseBody = {
     transformToByteArray?: () => Promise<Uint8Array>;
     [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
     destroy?: () => void;
@@ -12,3 +12,4 @@ export declare function destroyBody(body: unknown): void;
  * propagates as it is.
  */
 export declare function readBounded(body: ResponseBody, maxBytes: number, oversize: () => Error, advertised?: number): Promise<Uint8Array>;
+export {};

package/dist/client-probe.d.ts

@@ -24,11 +24,6 @@ export declare function probeClient(client: S3Client, bucket: string): Promise<C
  * asked, since an S3-compatible store (MinIO, for one) can accept the header and ignore it.
  */
 export declare function appliesDeleteIfMatch(explicit: boolean | undefined, facts: ClientFacts | undefined): boolean;
-/**
- * A `conditionalDelete` option, checked: `undefined` leaves the decision to the client ({@link appliesDeleteIfMatch}),
- * and anything but a boolean is refused.
- */
-export declare function checkConditionalDelete(value: unknown): boolean | undefined;
 /**
  * Whether `hostname` is an AWS S3 host, by its structure: under an AWS domain, with a label that names S3 (`s3`,
  * `s3-fips`, an access point's, a multi-region access point's `s3-global`, Object Lambda's, an Outpost's, a dash-joined

package/dist/defined.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `values` without the entries that are `undefined`, typed as optional properties, so a constructor can pass on the
+ * options it was given: `exactOptionalPropertyTypes` refuses `{ x: undefined }` for an optional `x`, and a sub-driver
+ * must see an option the caller left out as absent.
+ */
+export declare function defined<T extends Record<string, unknown>>(values: T): {
+    [K in keyof T]?: Exclude<T[K], undefined>;
+};

package/dist/index.js

@@ -1,17 +1,35 @@
 // src/backend.ts
-import { ValidationError as ValidationError6, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import {
+  ValidationError as ValidationError5,
+  brandAsBackend,
+  refuseUnknownOptions,
+  requirePositiveInt as requirePositiveInt2
+} from "@cloudbitmaps/core/driver-kit";
 import { S3Client } from "@aws-sdk/client-s3";
 
+// src/defined.ts
+function defined(values) {
+  return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
+}
+
 // src/storage.ts
 import {
   IntegrityError,
   NotFoundError as NotFoundError2,
   TransientError as TransientError2,
-  ValidationError as ValidationError4,
+  ValidationError as ValidationError3,
   WriteConflictError,
+  concatBytes,
   isNotFoundError,
   isValidationError,
-  isWriteConflictError
+  isWriteConflictError,
+  normalizeObjectPrefix,
+  parseGenerationFromKey,
+  requireBool,
+  requirePositiveInt,
+  segmentObjectPrefix,
+  storageObjectKey,
+  toTransient
 } from "@cloudbitmaps/core/driver-kit";
 import { createHash, randomBytes } from "node:crypto";
 import {
@@ -26,44 +44,17 @@ import {
   UploadPartCommand
 } from "@aws-sdk/client-s3";
 
-// src/keys.ts
-import {
-  ValidationError,
-  encodeNameForKey,
-  namespaceKeyPart,
-  prefixPart,
-  validateSegmentRef
-} from "@cloudbitmaps/core/driver-kit";
-import { normalizeObjectPrefix } from "@cloudbitmaps/core/driver-kit";
-var SUFFIX = ".crbm";
-function segmentObjectPrefix(prefix, ref) {
-  validateSegmentRef(ref);
-  return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;
-}
-function storageObjectKey(prefix, key) {
-  if (!Number.isInteger(key.generation) || key.generation < 0) {
-    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
-  }
-  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
-}
-function parseGenerationFromKey(segmentPrefix, objectKey) {
-  if (!objectKey.startsWith(segmentPrefix) || !objectKey.endsWith(SUFFIX)) return null;
-  const middle = objectKey.slice(segmentPrefix.length, objectKey.length - SUFFIX.length);
-  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
-  const generation = Number(middle);
-  return Number.isSafeInteger(generation) ? generation : null;
-}
+// src/s3-errors.ts
+import { ValidationError } from "@cloudbitmaps/core/driver-kit";
 
 // src/aws-errors.ts
+import { isTransportFault } from "@cloudbitmaps/core/driver-kit";
 function httpStatus(err) {
   return err?.$metadata?.httpStatusCode;
 }
 function errorName(err) {
   return err?.name;
 }
-function errorCode(err) {
-  return err?.code;
-}
 function isSdkRetryable(err) {
   return err?.$retryable != null;
 }
@@ -78,19 +69,10 @@ var NETWORK_NAMES = /* @__PURE__ */ new Set([
   "NetworkingError",
   "AbortError"
 ]);
-var NETWORK_CODES = /* @__PURE__ */ new Set([
-  "ETIMEDOUT",
-  "ECONNRESET",
-  "ECONNREFUSED",
-  "EPIPE",
-  "ENOTFOUND",
-  "EAI_AGAIN",
-  "ECONNABORTED"
-]);
 var NETWORK_MESSAGE = /socket hang up|network (error|failure)|(connection|request|socket|operation|read|write)\s+tim(e|ed)\s?out|connection (reset|refused|aborted|closed)/i;
 function isNetworkOrTimeout(err) {
   if (NETWORK_NAMES.has(errorName(err) ?? "")) return true;
-  if (NETWORK_CODES.has(errorCode(err) ?? "")) return true;
+  if (isTransportFault(err)) return true;
   return NETWORK_MESSAGE.test(err?.message ?? "");
 }
 
@@ -110,6 +92,15 @@ function isNoSuchUpload(err) {
 function isMissingBucket(err) {
   return errorName(err) === "NoSuchBucket";
 }
+function asMissingBucket(err, bucket) {
+  if (!isMissingBucket(err)) return err;
+  return Object.assign(
+    new ValidationError(
+      `the S3 bucket does not exist: ${bucket}; check the bucket name, and the region and endpoint of the client`
+    ),
+    { cause: err }
+  );
+}
 function isNotFound(err) {
   if (isMissingBucket(err)) return false;
   const name = errorName(err);
@@ -126,6 +117,9 @@ function isTransient(err) {
   if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
   return errorName(err) === "SlowDown" || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err) || isClockSkewCorrected(err);
 }
+function transientFaultMessage(err) {
+  return `transient S3 fault: ${errorName(err) ?? "unknown"}`;
+}
 function spanFromContentRange(contentRange) {
   if (contentRange === void 0) return void 0;
   const match = /^\s*bytes\s+(\d+)-(\d+)\//.exec(contentRange);
@@ -314,7 +308,6 @@ function scrubCredentials(err) {
 }
 
 // src/client-probe.ts
-import { ValidationError as ValidationError3 } from "@cloudbitmaps/core/driver-kit";
 import { DeleteObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 var PROBE_KEY = "cloudbitmaps-probe";
 var PLACEHOLDER_CREDENTIALS = { accessKeyId: "cloudbitmaps-probe", secretAccessKey: "unused" };
@@ -403,13 +396,6 @@ function appliesDeleteIfMatch(explicit, facts) {
   if (explicit === true) return facts?.sendsDeleteIfMatch !== false;
   return facts !== void 0 && facts.sendsDeleteIfMatch && isAwsS3Host(facts.host);
 }
-function checkConditionalDelete(value) {
-  if (value === void 0) return void 0;
-  if (typeof value !== "boolean") {
-    throw new ValidationError3(`conditionalDelete must be a boolean; got ${String(value)}`);
-  }
-  return value;
-}
 var AWS_DOMAINS = [".amazonaws.com", ".amazonaws.com.cn"];
 var S3_LABELS = /* @__PURE__ */ new Set([
   "s3",
@@ -454,6 +440,7 @@ var THROTTLE_BASE_DELAY_MS = 500;
 var REAL_TIME = {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 };
+var REAL_RNG = { next: () => Math.random() };
 var S3StorageDriver = class {
   client;
   bucket;
@@ -462,32 +449,28 @@ var S3StorageDriver = class {
   partBytes;
   readTimeoutMs;
   clock;
+  rng;
   sockets;
   explicitConditionalDelete;
   probed;
   facts;
   constructor(options) {
     this.client = options.client;
-    this.explicitConditionalDelete = checkConditionalDelete(options.conditionalDelete);
+    this.explicitConditionalDelete = requireBool("conditionalDelete", options.conditionalDelete);
     this.sockets = options.sockets;
     this.bucket = options.bucket;
     this.prefix = normalizeObjectPrefix(options.prefix);
     this.clock = options.clock ?? REAL_TIME;
-    for (const [name, value] of [
-      ["partBytes", options.partBytes],
-      ["maxObjectBytes", options.maxObjectBytes]
-    ]) {
-      if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) {
-        throw new ValidationError4(`${name} must be a positive safe integer; got ${value}`);
-      }
-    }
+    this.rng = options.rng ?? REAL_RNG;
+    requirePositiveInt("partBytes", options.partBytes);
+    requirePositiveInt("maxObjectBytes", options.maxObjectBytes);
     if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > S3_MAX_OBJECT_BYTES) {
-      throw new ValidationError4(
+      throw new ValidationError3(
         `maxObjectBytes must be at most S3's 5 TiB object limit (${S3_MAX_OBJECT_BYTES}); got ${options.maxObjectBytes}`
       );
     }
     if (options.partBytes !== void 0 && options.partBytes > S3_MAX_PART_BYTES) {
-      throw new ValidationError4(
+      throw new ValidationError3(
         `partBytes must be at most S3's 5 GiB part limit (${S3_MAX_PART_BYTES}); got ${options.partBytes}`
       );
     }
@@ -520,7 +503,8 @@ var S3StorageDriver = class {
       this.partBytes,
       this.maxObjectBytes,
       this.readTimeoutMs,
-      this.clock
+      this.clock,
+      this.rng
     );
     try {
       await write(sink);
@@ -540,7 +524,7 @@ var S3StorageDriver = class {
   }
   async getRange(key, offset, length) {
     if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
-      throw new ValidationError4(`invalid range offset=${offset} length=${length}`);
+      throw new ValidationError3(`invalid range offset=${offset} length=${length}`);
     }
     const objectKey = storageObjectKey(this.prefix, key);
     if (length === 0) return new Uint8Array(0);
@@ -560,7 +544,7 @@ var S3StorageDriver = class {
         res.ContentLength
       );
       if (bytes.length !== length) {
-        throw new ValidationError4(
+        throw new ValidationError3(
           `range [${offset}, ${offset + length}) out of bounds (got ${bytes.length}B)`
         );
       }
@@ -578,6 +562,9 @@ var S3StorageDriver = class {
   }
   async getTail(key, maxBytes) {
     const objectKey = storageObjectKey(this.prefix, key);
+    if (!Number.isSafeInteger(maxBytes)) {
+      throw new ValidationError3(`invalid tail length ${String(maxBytes)}`);
+    }
     if (maxBytes <= 0) {
       const head = await this.head(key, objectKey);
       return withVersion({ bytes: new Uint8Array(0), size: head.size ?? 0 }, head.version);
@@ -628,7 +615,7 @@ var S3StorageDriver = class {
     return withVersion({ bytes, size }, version);
   }
   badRead(key, what, why) {
-    return new ValidationError4(
+    return new ValidationError3(
       `S3 ${what} read of ${key.segment}.${key.generation} refused: ${why}`
     );
   }
@@ -737,41 +724,26 @@ var S3StorageDriver = class {
       return new NotFoundError2(`no such generation: ${key.segment}.${key.generation}`);
     }
     if (isInvalidRange(err)) {
-      return new ValidationError4(`range out of bounds for ${key.segment}.${key.generation}`);
+      return new ValidationError3(`range out of bounds for ${key.segment}.${key.generation}`);
     }
     return this.mapError(err);
   }
   /**
-   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError},
-   * so the store's read retry can ride it out and a write's caller can tell it from a deterministic failure;
-   * everything else propagates unchanged. The final fallback at every `client.send` site, so callers and the
-   * read retry only ever see typed errors.
+   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}, so the
+   * store's read retry can ride it out and a write's caller can tell it from a deterministic failure, and a missing
+   * bucket as a `ValidationError` that names it; everything else propagates unchanged. The final fallback at every
+   * `client.send` site, so callers and the read retry only ever see typed errors.
    */
   mapError(err) {
-    err = scrubCredentials(err);
-    if (isTransient(err)) {
-      return new TransientError2(
-        `transient S3 fault: ${err?.name ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
+    const scrubbed = asMissingBucket(scrubCredentials(err), this.bucket);
+    return toTransient(scrubbed, isTransient, transientFaultMessage);
   }
 };
 function withVersion(tail, version) {
   return version === void 0 ? tail : { ...tail, version };
 }
-function concatBytes(parts, total) {
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const p of parts) {
-    out.set(p, offset);
-    offset += p.length;
-  }
-  return out;
-}
 var S3MultipartSink = class {
-  constructor(client, bucket, objectKey, partBytes, maxObjectBytes, readTimeoutMs, clock) {
+  constructor(client, bucket, objectKey, partBytes, maxObjectBytes, readTimeoutMs, clock, rng) {
     this.client = client;
     this.bucket = bucket;
     this.objectKey = objectKey;
@@ -779,6 +751,7 @@ var S3MultipartSink = class {
     this.maxObjectBytes = maxObjectBytes;
     this.readTimeoutMs = readTimeoutMs;
     this.clock = clock;
+    this.rng = rng;
   }
   client;
   bucket;
@@ -787,6 +760,7 @@ var S3MultipartSink = class {
   maxObjectBytes;
   readTimeoutMs;
   clock;
+  rng;
   hash = createHash("sha256");
   pending = [];
   pendingLen = 0;
@@ -800,7 +774,7 @@ var S3MultipartSink = class {
     if (bytes.length === 0) return;
     this.total += bytes.length;
     if (this.total > this.maxObjectBytes) {
-      throw new ValidationError4(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
+      throw new ValidationError3(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
     }
     this.hash.update(bytes);
     this.pending.push(new Uint8Array(bytes));
@@ -823,12 +797,12 @@ var S3MultipartSink = class {
       }
       this.uploadId = res2.UploadId;
     }
-    const body = concatBytes(this.pending, this.pendingLen);
+    const body = concatBytes(this.pending);
     this.pending.length = 0;
     this.pendingLen = 0;
     this.partNumber += 1;
     if (this.partNumber > S3_MAX_PARTS) {
-      throw new ValidationError4(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);
+      throw new ValidationError3(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);
     }
     const res = await this.client.send(
       new UploadPartCommand({
@@ -845,7 +819,7 @@ var S3MultipartSink = class {
   async finish() {
     const sha256 = this.hash.digest("hex");
     if (this.uploadId === void 0) {
-      const body = concatBytes(this.pending, this.pendingLen);
+      const body = concatBytes(this.pending);
       await this.commit(
         "PutObject",
         () => sendOnce(
@@ -922,7 +896,7 @@ var S3MultipartSink = class {
             { cause: err }
           );
         }
-        await this.clock.sleep(Math.floor(Math.random() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
+        await this.clock.sleep(Math.floor(this.rng.next() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
       }
     }
   }
@@ -966,10 +940,11 @@ import {
   isIntegrityError,
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
-  TransientError as TransientError3,
-  ValidationError as ValidationError5,
+  ValidationError as ValidationError4,
   WriteConflictError as WriteConflictError2,
-  normalizeObjectPrefix as normalizeObjectPrefix2
+  normalizeObjectPrefix as normalizeObjectPrefix2,
+  requireBool as requireBool2,
+  toTransient as toTransient2
 } from "@cloudbitmaps/core/driver-kit";
 import {
   DeleteObjectCommand as DeleteObjectCommand3,
@@ -1011,7 +986,7 @@ var S3RegistryStore = class {
     const header = expect === "absent" ? "If-None-Match" : "If-Match";
     const sent = expect === "absent" ? this.facts?.sendsPutIfNoneMatch : this.facts?.sendsPutIfMatch;
     if (sent === false) {
-      throw new ValidationError5(
+      throw new ValidationError4(
         `the S3 client does not send ${header} on a PutObject: its @aws-sdk/client-s3 predates the member, so a registry write would overwrite whatever is there and lose a concurrent writer's change. Use a newer @aws-sdk/client-s3; the registry sent nothing`
       );
     }
@@ -1027,7 +1002,7 @@ var S3RegistryStore = class {
         );
       } catch (err) {
         if (isNotFound(err)) return null;
-        throw mapError(err);
+        throw mapError(err, this.bucket);
       }
       try {
         if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {
@@ -1046,7 +1021,7 @@ var S3RegistryStore = class {
         return { bytes, version: res.ETag ?? "" };
       } catch (err) {
         destroyBody(res.Body);
-        throw isIntegrityError(err) ? err : mapError(err);
+        throw isIntegrityError(err) ? err : mapError(err, this.bucket);
       }
     });
   }
@@ -1069,7 +1044,7 @@ var S3RegistryStore = class {
       if (isConditionalConflict(err)) {
         throw new WriteConflictError2(`registry OCC conflict for ${key}`);
       }
-      throw mapError(err);
+      throw mapError(err, this.bucket);
     }
   }
   async delete(key, expect) {
@@ -1082,7 +1057,7 @@ var S3RegistryStore = class {
       if (isConditionalConflict(err) || isNotFound(err)) {
         throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
       }
-      throw mapError(err);
+      throw mapError(err, this.bucket);
     }
   }
   async *listKeys(prefix) {
@@ -1099,7 +1074,7 @@ var S3RegistryStore = class {
           })
         );
       } catch (err) {
-        throw mapError(err);
+        throw mapError(err, this.bucket);
       }
       for (const obj of res.Contents ?? []) {
         if (obj.Key !== void 0) yield obj.Key;
@@ -1114,15 +1089,12 @@ var S3RegistryStore = class {
     } while (token !== void 0);
   }
 };
-function mapError(err) {
-  err = scrubCredentials(err);
-  if (isTransient(err)) {
-    return new TransientError3(
-      `transient S3 fault: ${err?.name ?? "unknown"}`,
-      { cause: err }
-    );
-  }
-  return err;
+function mapError(err, bucket) {
+  return toTransient2(
+    asMissingBucket(scrubCredentials(err), bucket),
+    isTransient,
+    transientFaultMessage
+  );
 }
 var S3RegistryDriver = class extends ObjectStoreRegistry {
   constructor(options) {
@@ -1131,7 +1103,7 @@ var S3RegistryDriver = class extends ObjectStoreRegistry {
         options.client,
         options.bucket,
         resolveReadTimeoutMs(options.readTimeoutMs),
-        checkConditionalDelete(options.conditionalDelete)
+        requireBool2("conditionalDelete", options.conditionalDelete)
       ),
       normalizeObjectPrefix2(options.prefix),
       options.now ?? (() => Date.now())
@@ -1269,20 +1241,6 @@ function limitSockets(client, maxSockets) {
     return handle(request, options);
   };
 }
-function refuseUnknown(name, options, keys, hint) {
-  if (options === null || typeof options !== "object") {
-    throw new ValidationError6(
-      `${name} needs an options object \u2014 got ${options === null ? "null" : typeof options}`
-    );
-  }
-  const unknown = Object.keys(options).filter((k) => !keys.includes(k));
-  if (unknown.length > 0) {
-    const list = (ks) => ks.map((k) => `\`${k}\``).join(", ");
-    throw new ValidationError6(
-      `${name} does not take ${list(unknown)}. It takes ${list(keys)}; ${hint}.`
-    );
-  }
-}
 var S3Storage = class {
   storage;
   registry;
@@ -1290,56 +1248,58 @@ var S3Storage = class {
   client;
   sockets;
   constructor(options) {
-    refuseUnknown("S3Storage", options, S3_STORAGE_OPTION_KEYS, "an S3 client goes in `client`");
+    refuseUnknownOptions(
+      "S3Storage",
+      options,
+      S3_STORAGE_OPTION_KEYS,
+      "an S3 client goes in `client`"
+    );
     if (typeof options.bucket !== "string" || options.bucket.length === 0) {
-      throw new ValidationError6("S3Storage needs a `bucket`: the name of one, a non-empty string");
+      throw new ValidationError5("S3Storage needs a `bucket`: the name of one, a non-empty string");
     }
     if (options.now !== void 0 && typeof options.now !== "function") {
-      throw new ValidationError6(
+      throw new ValidationError5(
         "S3Storage's `now` must be a function that returns epoch milliseconds"
       );
     }
     if (options.client !== void 0 && options.client !== null) {
       const ignored = CLIENT_SETTINGS.filter((k) => options[k] !== void 0);
       if (ignored.length > 0) {
-        throw new ValidationError6(
+        throw new ValidationError5(
           `S3Storage takes \`client\` OR ${CLIENT_SETTINGS.map((k) => `\`${k}\``).join(" / ")}, not both \u2014 got \`client\` with ${ignored.map((k) => `\`${k}\``).join(", ")}; the \`client\` already carries them, so configure them on the client, or drop \`client\``
         );
       }
       this.client = options.client;
     } else {
-      const { maxSockets = DEFAULT_MAX_SOCKETS } = options;
-      if (!Number.isSafeInteger(maxSockets) || maxSockets < 1) {
-        throw new ValidationError6(
-          `maxSockets must be a positive safe integer; got ${describe(options.maxSockets)}`
-        );
-      }
-      this.client = new S3Client({
-        ...options.region === void 0 ? {} : { region: options.region },
-        ...options.endpoint === void 0 ? {} : { endpoint: options.endpoint },
-        ...options.pathStyle === void 0 ? {} : { forcePathStyle: options.pathStyle },
-        ...options.credentials === void 0 ? {} : { credentials: options.credentials }
-      });
+      const maxSockets = requirePositiveInt2("maxSockets", options.maxSockets) ?? DEFAULT_MAX_SOCKETS;
+      this.client = new S3Client(
+        defined({
+          credentials: options.credentials,
+          region: options.region,
+          endpoint: options.endpoint,
+          forcePathStyle: options.pathStyle
+        })
+      );
       limitSockets(this.client, maxSockets);
     }
     this.sockets = new SocketAdvisory(this.client, options.bucket);
     const shared = {
       client: this.client,
       bucket: options.bucket,
-      ...options.prefix === void 0 ? {} : { prefix: options.prefix },
-      ...options.readTimeoutMs === void 0 ? {} : { readTimeoutMs: options.readTimeoutMs }
+      ...defined({ prefix: options.prefix, readTimeoutMs: options.readTimeoutMs })
     };
     this.storage = new S3StorageDriver({
       ...shared,
       sockets: this.sockets,
-      ...options.maxObjectBytes === void 0 ? {} : { maxObjectBytes: options.maxObjectBytes },
-      ...options.partBytes === void 0 ? {} : { partBytes: options.partBytes },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({
+        maxObjectBytes: options.maxObjectBytes,
+        partBytes: options.partBytes,
+        conditionalDelete: options.conditionalDelete
+      })
     });
     this.registry = new S3RegistryDriver({
       ...shared,
-      ...options.now === void 0 ? {} : { now: options.now },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({ now: options.now, conditionalDelete: options.conditionalDelete })
     });
     brandAsBackend(this);
   }