@cloudbitmaps/gcs 0.19.1 → 0.21.0

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,33 +425,36 @@ var GcsStorageDriver = class {
   threshold;
   readTimeoutMs;
   clock;
+  rng;
   presence;
+  conditionalDelete;
   constructor(options) {
     this.storage = options.storage;
+    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);
   }
   capabilities() {
-    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
+    return {
+      rangeRead: true,
+      maxObjectBytes: this.maxObjectBytes,
+      conditionalPut: true,
+      conditionalDelete: this.conditionalDelete
+    };
   }
   file(name) {
     return this.storage.bucket(this.bucket).file(name);
@@ -468,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);
@@ -486,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);
     }
   }
@@ -494,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(
@@ -553,13 +555,15 @@ 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)
-        return { bytes: new Uint8Array(0), size: await this.sizeOf(objectName, deadline) };
-      if (!Number.isSafeInteger(maxBytes)) {
-        throw new ValidationError3(`invalid tail length ${maxBytes}`);
+      if (maxBytes <= 0) {
+        const meta = await this.metadataOf(objectName, deadline);
+        return withVersion({ bytes: new Uint8Array(0), size: meta.size }, meta.version);
       }
       let res;
       try {
@@ -575,25 +579,32 @@ var GcsStorageDriver = class {
         );
       } catch (err) {
         if (!isInvalidRange(err)) throw err;
-        const size = await this.sizeOf(objectName, deadline);
-        if (size !== 0) throw err;
-        return { bytes: new Uint8Array(0), size };
+        const meta = await this.metadataOf(objectName, deadline);
+        if (meta.size !== 0) throw err;
+        return withVersion({ bytes: new Uint8Array(0), size: 0 }, meta.version);
       }
       if (res.bytes.length === 0) {
-        const size = await this.sizeOf(objectName, deadline);
-        if (size !== 0) throw this.badTail(key, `no bytes returned for an object of ${size}B`);
-        return { bytes: res.bytes, size };
+        const meta = await this.metadataOf(objectName, deadline);
+        if (meta.size !== 0) {
+          throw this.badTail(key, `no bytes returned for an object of ${meta.size}B`);
+        }
+        return withVersion({ bytes: res.bytes, size: 0 }, meta.version);
       }
-      return { bytes: res.bytes, size: this.tailSize(res, maxBytes, key) };
+      const size = this.tailSize(res, maxBytes, key);
+      return withVersion(
+        { bytes: res.bytes, size },
+        objectGeneration(singleHeader(res.headers, "x-goog-generation"))
+      );
     } catch (err) {
       throw await this.readFailure(err, key);
     }
   }
   /**
-   * The object's size from its metadata, validated. Read on the download client and retried as a download is, within
-   * the calling read's `deadline` ({@link withDeadline}), so nothing but the one request in flight runs past it.
+   * The object's size from its metadata, validated, and its generation when the metadata names a usable one. Read on the
+   * download client and retried as a download is, within the calling read's `deadline` ({@link withDeadline}), so
+   * nothing but the one request in flight runs past it.
    */
-  async sizeOf(objectName, deadline) {
+  async metadataOf(objectName, deadline) {
     const [meta] = await retryDownload(
       () => withDeadline(() => this.downloadable(objectName).getMetadata(), deadline),
       deadline
@@ -602,7 +613,12 @@ var GcsStorageDriver = class {
     if (!Number.isSafeInteger(size) || size < 0) {
       throw new ValidationError3(`GCS returned an invalid object size: ${String(meta.size)}`);
     }
-    return size;
+    return {
+      size,
+      version: objectGeneration(
+        meta.generation === void 0 ? void 0 : String(meta.generation)
+      )
+    };
   }
   /**
    * The object's total size from a tail response, refused unless every header agrees with the bytes received. A 206
@@ -635,24 +651,49 @@ var GcsStorageDriver = class {
   badTail(key, why) {
     return new ValidationError3(`GCS tail read of ${key.segment}.${key.generation} refused: ${why}`);
   }
-  async delete(key) {
+  async delete(key, options) {
+    const objectName = storageObjectKey(this.prefix, key);
+    const ifVersion = options?.ifVersion;
+    const conditional = ifVersion !== void 0 && this.conditionalDelete;
     try {
-      await this.file(storageObjectName(this.prefix, key)).delete();
+      await this.file(objectName).delete(
+        ...conditional ? [{ ifGenerationMatch: generationOf(ifVersion, key) }] : []
+      );
     } catch (err) {
       if (isNotFound(err)) return this.presence.confirm();
+      if (conditional && isPreconditionFailed(err)) {
+        if (!await this.exists(objectName)) return;
+        throw new WriteConflictError(
+          `generation ${key.segment}.${key.generation} is another object than the version given; not deleted`
+        );
+      }
       throw this.mapError(err);
     }
   }
+  /** Whether an object is under the name, from its metadata. A read that fails in any other way throws. */
+  async exists(objectName) {
+    try {
+      await this.downloadable(objectName).getMetadata();
+      return true;
+    } catch (err) {
+      if (isNotFound(err)) {
+        await this.presence.confirm();
+        return false;
+      }
+      throw this.mapError(scrubCredentials(err));
+    }
+  }
   async *list(ref) {
     const prefix = segmentObjectPrefix(this.prefix, ref);
     let files;
     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 };
       }
@@ -673,53 +714,47 @@ 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 concatBytes(parts, total) {
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const p of parts) {
-    out.set(p, offset);
-    offset += p.length;
+function withVersion(tail, version) {
+  return version === void 0 ? tail : { ...tail, version };
+}
+function objectGeneration(value) {
+  return value !== void 0 && /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value)) ? value : void 0;
+}
+function generationOf(version, key) {
+  if (objectGeneration(version) === void 0) {
+    throw new ValidationError3(
+      `ifVersion for ${key.segment}.${key.generation} is not a GCS object generation: ${version}`
+    );
   }
-  return out;
+  return Number(version);
 }
 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 = [];
@@ -773,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);
@@ -781,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 {
@@ -817,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));
       }
     }
   }
@@ -842,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
@@ -912,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}`);
@@ -940,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) {
@@ -951,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) {
@@ -962,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) {
@@ -979,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) {
@@ -1016,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())
@@ -1025,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;
@@ -1071,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;
@@ -1126,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);
@@ -1147,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;
@@ -1168,53 +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 }
+      ...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);
   }