@cloudbitmaps/gcs 0.20.0 → 0.21.0

package/dist/bucket-presence.d.ts

@@ -12,7 +12,7 @@
  *                                              ▼
  *                              list one object in the bucket
  *                               ├─ answered ──────────▶ remember the bucket; the 404 is an object's
- *                               ├─ 404 ───────────────▶ reject: the bucket does not exist
+ *                               ├─ 404 ───────────────▶ reject: ValidationError, the bucket does not exist
  *                               ├─ transient ─────────▶ reject: TransientError (asked again next time)
  *                               ├─ 403 ───────────────▶ remember it as unknowable; the 404 is an object's
  *                               └─ anything else ─────▶ the 404 is an object's (asked again next time)
@@ -31,7 +31,7 @@ export declare class BucketPresence {
     private settled;
     private asking;
     constructor(storage: Storage, bucket: string);
-    /** Resolve when a 404 can be read as an object's; reject when the bucket does not exist or the listing failed in transit. */
+    /** Resolve when a 404 can be read as an object's; reject with `ValidationError` when the bucket does not exist, `TransientError` when the listing failed in transit. */
     confirm(): Promise<void>;
     private ask;
 }

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/gcs-errors.d.ts

@@ -7,6 +7,7 @@
  * `.code` (a number); dropped/timed-out sockets surface as a Node error with a string `.code` (`ECONNRESET`,
  * `ETIMEDOUT`, …).
  */
+import { ValidationError } from '@cloudbitmaps/core/driver-kit';
 /**
  * A conditional `ifGenerationMatch: 0` write lost the write-once race — the object already existed, so GCS
  * returns **412 Precondition Failed**. Maps to `WriteConflictError` (caller OCC), never a blind retry.
@@ -27,9 +28,17 @@ export declare function isNotFound(err: unknown): boolean;
  * the message and each `errors[].message` are GCS's own. A wording this does not match reads as an absent object.
  */
 export declare function isMissingBucket(err: unknown): boolean;
+/**
+ * The {@link ValidationError} a missing bucket is: it names the bucket and what to check, and carries the service's
+ * error as its `cause`. A wiring fault is not an absent object, so it is not a `NotFoundError`: a read re-resolves on
+ * that, and would treat a misnamed bucket as a miss it can heal.
+ */
+export declare function missingBucketError(bucket: string, cause: unknown): ValidationError;
+/** `err`, or {@link missingBucketError} when `err` says the bucket does not exist. */
+export declare function asMissingBucket(err: unknown, bucket: string): unknown;
 /** A range request started past EOF (HTTP 416 Requested Range Not Satisfiable). */
 export declare function isInvalidRange(err: unknown): boolean;
-/** A download that failed in transit rather than with an HTTP status: one of {@link TRANSPORT_CODES}. */
+/** A download that failed in transit rather than with an HTTP status: a connection fault ({@link isConnectionFault}). */
 export declare function isTransportFault(err: unknown): boolean;
 /**
  * Whether the driver retries a failed download, which it does in the SDK's place: the statuses the SDK's predicate
@@ -44,3 +53,8 @@ export declare function isDownloadRetryable(err: unknown): boolean;
  * a blind transient (a retried doomed conditional write would just fail again, and mask an OCC conflict).
  */
 export declare function isTransient(err: unknown): boolean;
+/**
+ * The message a transient GCS fault is handed on with: `transient GCS fault: <code>`, the HTTP status the SDK puts on
+ * `code` or Node's connection code, else the error's name.
+ */
+export declare function transientFaultMessage(err: unknown): string;

package/dist/index.js

@@ -1,16 +1,33 @@
 // src/backend.ts
-import { ValidationError as ValidationError6, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import {
+  ValidationError as ValidationError5,
+  brandAsBackend,
+  refuseUnknownOptions
+} from "@cloudbitmaps/core/driver-kit";
 import { Storage as GcsClient } from "@google-cloud/storage";
 
+// src/defined.ts
+function defined(values) {
+  return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
+}
+
 // src/storage.ts
 import {
   NotFoundError,
   TransientError as TransientError2,
   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 { once as once2 } from "node:events";
@@ -19,6 +36,10 @@ import { once as once2 } from "node:events";
 import { TransientError } from "@cloudbitmaps/core/driver-kit";
 
 // src/gcs-errors.ts
+import {
+  ValidationError,
+  isTransportFault as isNodeTransportFault
+} from "@cloudbitmaps/core/driver-kit";
 function httpStatus(err) {
   const e = err;
   if (typeof e?.code === "number") return e.code;
@@ -46,6 +67,17 @@ function isMissingBucket(err) {
   if (says(e.message)) return true;
   return Array.isArray(e.errors) && e.errors.some((inner) => says(inner?.message));
 }
+function missingBucketError(bucket, cause) {
+  return Object.assign(
+    new ValidationError(
+      `the GCS bucket does not exist: ${bucket}; check the bucket name and the project the client is built for`
+    ),
+    { cause }
+  );
+}
+function asMissingBucket(err, bucket) {
+  return isMissingBucket(err) ? missingBucketError(bucket, err) : err;
+}
 function isInvalidRange(err) {
   return httpStatus(err) === 416;
 }
@@ -53,22 +85,11 @@ var SDK_RETRIED_STATUSES = [408, 429, 500, 502, 503, 504];
 function isSdkConnectionProblem(reason) {
   return reason.includes("eai_again") || reason === "econnreset" || reason === "unexpected connection closure" || reason === "epipe" || reason === "socket connection timeout";
 }
-var TRANSPORT_CODES = /* @__PURE__ */ new Set([
-  "ECONNRESET",
-  "ECONNREFUSED",
-  "ECONNABORTED",
-  "ETIMEDOUT",
-  "ENOTFOUND",
-  "EAI_AGAIN",
-  "EHOSTUNREACH",
-  "ENETUNREACH",
-  "EPIPE",
-  "ERR_STREAM_PREMATURE_CLOSE"
-]);
+function isConnectionFault(err) {
+  return isNodeTransportFault(err) || networkCode(err) === "ERR_STREAM_PREMATURE_CLOSE";
+}
 function isTransportFault(err) {
-  if (httpStatus(err) !== void 0) return false;
-  const code = networkCode(err);
-  return code !== void 0 && TRANSPORT_CODES.has(code);
+  return httpStatus(err) === void 0 && isConnectionFault(err);
 }
 function isDownloadRetryable(err) {
   if (err === null || typeof err !== "object") return false;
@@ -92,8 +113,11 @@ function isTransient(err) {
   const status = httpStatus(err);
   if (status === 408 || status === 429 || status !== void 0 && status >= 500 && status < 600)
     return true;
-  const net = networkCode(err);
-  return net !== void 0 && TRANSPORT_CODES.has(net);
+  return isConnectionFault(err);
+}
+function transientFaultMessage(err) {
+  const e = err;
+  return `transient GCS fault: ${String(e?.code ?? e?.name ?? "unknown")}`;
 }
 
 // src/scrub-error.ts
@@ -186,7 +210,7 @@ var BucketPresence = class {
   bucket;
   settled = false;
   asking;
-  /** Resolve when a 404 can be read as an object's; reject when the bucket does not exist or the listing failed in transit. */
+  /** Resolve when a 404 can be read as an object's; reject with `ValidationError` when the bucket does not exist, `TransientError` when the listing failed in transit. */
   async confirm() {
     if (this.settled) return;
     this.asking ??= this.ask().finally(() => {
@@ -205,7 +229,7 @@ var BucketPresence = class {
       const err = scrubCredentials(failure.raised);
       const status = err?.code;
       if (status === 404) {
-        throw new Error(`the GCS bucket does not exist: ${this.bucket}`, { cause: err });
+        throw missingBucketError(this.bucket, err);
       }
       if (isTransient(err)) {
         throw new TransientError(
@@ -221,34 +245,6 @@ var BucketPresence = class {
   }
 };
 
-// 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 storageObjectName(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 parseGenerationFromName(segmentPrefix, objectName) {
-  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;
-  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);
-  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
-  const generation = Number(middle);
-  return Number.isSafeInteger(generation) ? generation : null;
-}
-
 // src/read-timeout.ts
 import { ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
 var DEFAULT_READ_TIMEOUT_MS = 0;
@@ -411,13 +407,14 @@ function readOnce(file, options, maxBytes, oversize, deadline) {
 }
 
 // src/storage.ts
-var DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;
+var GCS_MAX_OBJECT_BYTES = 5 * 1024 ** 4;
 var WRITE_ID_KEY = "cbwid";
 var THROTTLE_RESENDS = 3;
 var THROTTLE_BASE_DELAY_MS = 500;
 var REAL_TIME = {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 };
+var REAL_RNG = { next: () => Math.random() };
 var DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;
 var GcsStorageDriver = class {
   storage;
@@ -428,34 +425,25 @@ var GcsStorageDriver = class {
   threshold;
   readTimeoutMs;
   clock;
+  rng;
   presence;
   conditionalDelete;
   constructor(options) {
     this.storage = options.storage;
-    if (options.conditionalDelete !== void 0 && typeof options.conditionalDelete !== "boolean") {
-      throw new ValidationError3(
-        `conditionalDelete must be a boolean; got ${String(options.conditionalDelete)}`
-      );
-    }
-    this.conditionalDelete = options.conditionalDelete ?? false;
+    this.conditionalDelete = requireBool("conditionalDelete", options.conditionalDelete) ?? false;
     this.clock = options.clock ?? REAL_TIME;
+    this.rng = options.rng ?? REAL_RNG;
     this.readStorage = options.readStorage ?? options.storage;
     this.bucket = options.bucket;
     this.prefix = normalizeObjectPrefix(options.prefix);
-    for (const [name, value] of [
-      ["maxObjectBytes", options.maxObjectBytes],
-      ["simpleUploadThresholdBytes", options.simpleUploadThresholdBytes]
-    ]) {
-      if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) {
-        throw new ValidationError3(`${name} must be a positive safe integer; got ${value}`);
-      }
-    }
-    if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > 5 * 1024 ** 4) {
+    requirePositiveInt("maxObjectBytes", options.maxObjectBytes);
+    requirePositiveInt("simpleUploadThresholdBytes", options.simpleUploadThresholdBytes);
+    if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > GCS_MAX_OBJECT_BYTES) {
       throw new ValidationError3(
-        `maxObjectBytes must be at most GCS's 5 TiB object limit (${5 * 1024 ** 4}); got ${options.maxObjectBytes}`
+        `maxObjectBytes must be at most GCS's 5 TiB object limit (${GCS_MAX_OBJECT_BYTES}); got ${options.maxObjectBytes}`
       );
     }
-    this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;
+    this.maxObjectBytes = options.maxObjectBytes ?? GCS_MAX_OBJECT_BYTES;
     this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;
     this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
     this.presence = new BucketPresence(this.storage, this.bucket);
@@ -480,12 +468,13 @@ var GcsStorageDriver = class {
     return startDeadline(this.readTimeoutMs, `${read} of ${key.segment}.${key.generation}`);
   }
   async putImmutable(key, write) {
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
     const sink = new GcsUploadSink(
       this.file(objectName),
       this.maxObjectBytes,
       this.threshold,
-      this.clock
+      this.clock,
+      this.rng
     );
     try {
       await write(sink);
@@ -498,6 +487,7 @@ var GcsStorageDriver = class {
         );
       }
       if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) throw err;
+      if (isNotFound(err)) await this.presence.confirm();
       throw this.mapError(err);
     }
   }
@@ -506,7 +496,7 @@ var GcsStorageDriver = class {
       throw new ValidationError3(`invalid range offset=${offset} length=${length}`);
     }
     if (length === 0) return new Uint8Array(0);
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
     try {
       const deadline = this.deadline("range read", key);
       const res = await retryDownload(
@@ -565,16 +555,16 @@ var GcsStorageDriver = class {
     );
   }
   async getTail(key, maxBytes) {
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
+    if (!Number.isSafeInteger(maxBytes)) {
+      throw new ValidationError3(`invalid tail length ${String(maxBytes)}`);
+    }
     const deadline = this.deadline("tail read", key);
     try {
       if (maxBytes <= 0) {
         const meta = await this.metadataOf(objectName, deadline);
         return withVersion({ bytes: new Uint8Array(0), size: meta.size }, meta.version);
       }
-      if (!Number.isSafeInteger(maxBytes)) {
-        throw new ValidationError3(`invalid tail length ${maxBytes}`);
-      }
       let res;
       try {
         res = await retryDownload(
@@ -662,7 +652,7 @@ var GcsStorageDriver = class {
     return new ValidationError3(`GCS tail read of ${key.segment}.${key.generation} refused: ${why}`);
   }
   async delete(key, options) {
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
     const ifVersion = options?.ifVersion;
     const conditional = ifVersion !== void 0 && this.conditionalDelete;
     try {
@@ -699,10 +689,11 @@ var GcsStorageDriver = class {
     try {
       [files] = await this.storage.bucket(this.bucket).getFiles({ prefix });
     } catch (err) {
+      if (isNotFound(err)) throw missingBucketError(this.bucket, scrubCredentials(err));
       throw this.mapError(err);
     }
     for (const f of files) {
-      const generation = parseGenerationFromName(prefix, f.name);
+      const generation = parseGenerationFromKey(prefix, f.name);
       if (generation !== null) {
         yield { namespace: ref.namespace, segment: ref.segment, generation };
       }
@@ -723,31 +714,18 @@ var GcsStorageDriver = class {
       return new ValidationError3(`range out of bounds for ${key.segment}.${key.generation}`);
     }
     if (err instanceof ReadTimedOut) return new TransientError2(err.message, { cause: err });
-    if (isTransportFault(err)) {
-      return new TransientError2(
-        `transient GCS fault: ${String(err.code)}`,
-        {
-          cause: err
-        }
-      );
-    }
     return this.mapError(err);
   }
   /**
-   * Reclassify a transient GCS 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-call site: an HTTP status and a fault
-   * in transit arrive typed, and anything else (a checksum mismatch, a credentials failure) as the SDK raised it.
+   * Reclassify a transient GCS 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-call site: an HTTP status and a fault in transit arrive typed, and anything else (a checksum mismatch, a
+   * credentials failure) as the SDK raised it.
    */
   mapError(err) {
-    err = scrubCredentials(err);
-    if (isTransient(err)) {
-      return new TransientError2(
-        `transient GCS fault: ${err?.code ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
+    const scrubbed = asMissingBucket(scrubCredentials(err), this.bucket);
+    return toTransient(scrubbed, isTransient, transientFaultMessage);
   }
 };
 function withVersion(tail, version) {
@@ -764,26 +742,19 @@ function generationOf(version, key) {
   }
   return Number(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 GcsUploadSink = class _GcsUploadSink {
-  constructor(file, maxObjectBytes, threshold, clock) {
+  constructor(file, maxObjectBytes, threshold, clock, rng) {
     this.file = file;
     this.maxObjectBytes = maxObjectBytes;
     this.threshold = threshold;
     this.clock = clock;
+    this.rng = rng;
   }
   file;
   maxObjectBytes;
   threshold;
   clock;
+  rng;
   hash = createHash("sha256");
   total = 0;
   buffered = [];
@@ -837,7 +808,7 @@ var GcsUploadSink = class _GcsUploadSink {
       this.failure ??= e;
     });
     this.done.catch(() => void 0);
-    const buf = concatBytes(this.buffered, this.bufferedLen);
+    const buf = concatBytes(this.buffered);
     this.buffered.length = 0;
     this.bufferedLen = 0;
     stream.write(buf);
@@ -845,7 +816,7 @@ var GcsUploadSink = class _GcsUploadSink {
   async finish() {
     const sha256 = this.hash.digest("hex");
     if (this.stream === void 0) {
-      await this.sendSimple(concatBytes(this.buffered, this.bufferedLen));
+      await this.sendSimple(concatBytes(this.buffered));
       return { size: this.total, sha256 };
     }
     try {
@@ -881,7 +852,7 @@ var GcsUploadSink = class _GcsUploadSink {
             { 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));
       }
     }
   }
@@ -906,9 +877,10 @@ import {
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
   TransientError as TransientError3,
-  ValidationError as ValidationError4,
   WriteConflictError as WriteConflictError2,
-  normalizeObjectPrefix as normalizeObjectPrefix2
+  normalizeObjectPrefix as normalizeObjectPrefix2,
+  requireBool as requireBool2,
+  toTransient as toTransient2
 } from "@cloudbitmaps/core/driver-kit";
 
 // src/crc32c.ts
@@ -976,7 +948,7 @@ var GcsRegistryStore = class {
         await this.presence.confirm();
         return null;
       }
-      throw mapReadError(err);
+      throw mapReadError(err, this.bucket);
     }
     if (res.status !== 200) {
       throw new IntegrityError(`registry read answered HTTP ${res.status}, not 200: ${key}`);
@@ -1004,7 +976,8 @@ var GcsRegistryStore = class {
       if (isPreconditionFailed(err)) {
         throw new WriteConflictError2(`registry OCC conflict for ${key}`);
       }
-      throw mapError(err);
+      if (isNotFound(err)) await this.presence.confirm();
+      throw mapError(err, this.bucket);
     }
   }
   async delete(key, expect) {
@@ -1015,7 +988,7 @@ var GcsRegistryStore = class {
         if (isNotFound(err)) await this.presence.confirm();
         throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
       }
-      throw mapError(err);
+      throw mapError(err, this.bucket);
     }
   }
   async *listKeys(prefix) {
@@ -1026,7 +999,8 @@ var GcsRegistryStore = class {
       try {
         [files, next] = await this.storage.bucket(this.bucket).getFiles({ prefix, autoPaginate: false, maxResults: 1e3, pageToken });
       } catch (err) {
-        throw mapError(err);
+        if (isNotFound(err)) throw missingBucketError(this.bucket, scrubCredentials(err));
+        throw mapError(err, this.bucket);
       }
       for (const f of files ?? []) yield f.name;
       if (next?.pageToken !== void 0 && next.pageToken === pageToken) {
@@ -1043,34 +1017,17 @@ function generationFence(version, key) {
   }
   return generation;
 }
-function mapReadError(err) {
+function mapReadError(err, bucket) {
   err = scrubCredentials(err);
   if (err instanceof ReadTimedOut) return new TransientError3(err.message, { cause: err });
-  if (isTransportFault(err)) {
-    return new TransientError3(`transient GCS fault: ${String(err.code)}`, {
-      cause: err
-    });
-  }
-  return mapError(err);
+  return mapError(err, bucket);
 }
-function mapError(err) {
-  err = scrubCredentials(err);
-  if (isTransient(err)) {
-    return new TransientError3(
-      `transient GCS fault: ${err?.code ?? err?.name ?? "unknown"}`,
-      { cause: err }
-    );
-  }
-  return err;
-}
-function resolveConditionalDelete(value) {
-  if (value === void 0) {
-    return false;
-  }
-  if (typeof value !== "boolean") {
-    throw new ValidationError4(`conditionalDelete must be a boolean; got ${String(value)}`);
-  }
-  return value;
+function mapError(err, bucket) {
+  return toTransient2(
+    asMissingBucket(scrubCredentials(err), bucket),
+    isTransient,
+    transientFaultMessage
+  );
 }
 var GcsRegistryDriver = class extends ObjectStoreRegistry {
   constructor(options) {
@@ -1080,7 +1037,7 @@ var GcsRegistryDriver = class extends ObjectStoreRegistry {
         options.readStorage ?? options.storage,
         options.bucket,
         resolveReadTimeoutMs(options.readTimeoutMs),
-        resolveConditionalDelete(options.conditionalDelete)
+        requireBool2("conditionalDelete", options.conditionalDelete) ?? false
       ),
       normalizeObjectPrefix2(options.prefix),
       options.now ?? (() => Date.now())
@@ -1089,7 +1046,7 @@ var GcsRegistryDriver = class extends ObjectStoreRegistry {
 };
 
 // src/read-client.ts
-import { ValidationError as ValidationError5 } from "@cloudbitmaps/core/driver-kit";
+import { ValidationError as ValidationError4 } from "@cloudbitmaps/core/driver-kit";
 function downloadClient(client, supplied) {
   if (!isSdkClient(client)) {
     if (client.retryOptions?.autoRetry === false) return client;
@@ -1135,12 +1092,12 @@ function isSdkClient(client) {
   return client.authClient !== void 0 && typeof factory === "function" && factory.authClient === client.authClient;
 }
 function overridesBucket(client) {
-  let defined = 0;
+  let defined2 = 0;
   for (let proto = Object.getPrototypeOf(client); proto !== null; ) {
-    if (Object.hasOwn(proto, "bucket")) defined++;
+    if (Object.hasOwn(proto, "bucket")) defined2++;
     proto = Object.getPrototypeOf(proto);
   }
-  return defined > 1;
+  return defined2 > 1;
 }
 function twinOf(client) {
   const Own = client.constructor;
@@ -1190,7 +1147,7 @@ function unfaithful(client, twin) {
   return void 0;
 }
 function refusal(supplied, why, remedy, cause) {
-  const err = new ValidationError5(
+  const err = new ValidationError4(
     (supplied ? `GcsStorage cannot send the supplied client's downloads without the SDK's retries: ${why}` : `GcsStorage cannot build a client that sends downloads without the SDK's retries: ${why}`) + (remedy === void 0 ? "" : `. ${remedy}`)
   );
   if (cause !== void 0) err.cause = scrubCredentials(cause);
@@ -1211,20 +1168,6 @@ var GCS_STORAGE_OPTION_KEYS = [
   "conditionalDelete"
 ];
 var CLIENT_SETTINGS = ["projectId", "apiEndpoint"];
-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 GcsStorage = class {
   storage;
   registry;
@@ -1232,54 +1175,52 @@ var GcsStorage = class {
   client;
   constructor(options) {
     let readClient;
-    refuseUnknown(
+    refuseUnknownOptions(
       "GcsStorage",
       options,
       GCS_STORAGE_OPTION_KEYS,
       "a @google-cloud/storage client goes in `client`"
     );
     if (typeof options.bucket !== "string" || options.bucket.length === 0) {
-      throw new ValidationError6("GcsStorage needs a `bucket`: the name of one, a non-empty string");
+      throw new ValidationError5("GcsStorage 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(
         "GcsStorage'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(
           `GcsStorage 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;
       readClient = downloadClient(options.client, true);
     } else {
-      const settings = {
-        ...options.projectId === void 0 ? {} : { projectId: options.projectId },
-        ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint }
-      };
-      this.client = new GcsClient(settings);
+      this.client = new GcsClient(
+        defined({ projectId: options.projectId, apiEndpoint: options.apiEndpoint })
+      );
       readClient = downloadClient(this.client, false);
     }
     const shared = {
       storage: this.client,
       readStorage: readClient,
       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 GcsStorageDriver({
       ...shared,
-      ...options.maxObjectBytes === void 0 ? {} : { maxObjectBytes: options.maxObjectBytes },
-      ...options.simpleUploadThresholdBytes === void 0 ? {} : { simpleUploadThresholdBytes: options.simpleUploadThresholdBytes },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({
+        maxObjectBytes: options.maxObjectBytes,
+        simpleUploadThresholdBytes: options.simpleUploadThresholdBytes,
+        conditionalDelete: options.conditionalDelete
+      })
     });
     this.registry = new GcsRegistryDriver({
       ...shared,
-      ...options.now === void 0 ? {} : { now: options.now },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({ now: options.now, conditionalDelete: options.conditionalDelete })
     });
     brandAsBackend(this);
   }