@cloudbitmaps/gcs 0.20.0 → 0.21.0

package/dist/registry.d.ts

@@ -36,7 +36,7 @@
 import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
 import type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';
 import type { Storage } from '@google-cloud/storage';
-export interface GcsRegistryDriverOptions {
+interface GcsRegistryDriverOptions {
     /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
     readonly storage: Storage;
     /** The client the downloads go through; `storage` when absent (see `GcsStorageDriverOptions.readStorage`). */
@@ -87,3 +87,4 @@ export declare class GcsRegistryStore implements ObjectRegistryStore {
 export declare class GcsRegistryDriver extends ObjectStoreRegistry {
     constructor(options: GcsRegistryDriverOptions);
 }
+export {};

package/dist/storage.d.ts

@@ -1,10 +1,9 @@
 import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps, StorageDeleteOptions, TailRead } from '@cloudbitmaps/core/driver-kit';
+import type { Clock, Rng } from '@cloudbitmaps/core';
 import type { Storage } from '@google-cloud/storage';
 /** What the throttle backoff waits on. */
-interface Sleeper {
-    sleep(ms: number): Promise<void>;
-}
-export interface GcsStorageDriverOptions {
+type Sleeper = Pick<Clock, 'sleep'>;
+interface GcsStorageDriverOptions {
     /** A constructed `@google-cloud/storage` `Storage` client (point `apiEndpoint` at fake-gcs-server locally). */
     readonly storage: Storage;
     /**
@@ -32,6 +31,8 @@ export interface GcsStorageDriverOptions {
     readonly readTimeoutMs?: number;
     /** What the backoff before re-sending a throttled upload waits on; real time when absent. */
     readonly clock?: Sleeper;
+    /** Where the jitter of that backoff is drawn from; `Math.random` when absent. */
+    readonly rng?: Rng;
     /**
      * Whether a delete given `ifVersion` is sent with `ifGenerationMatch`, so it removes the object only while it is the
      * one that generation names. Defaults to `false`, on the public endpoint too, as the registry's option does: whether
@@ -51,6 +52,7 @@ export declare class GcsStorageDriver implements IStorageDriver {
     private readonly threshold;
     private readonly readTimeoutMs;
     private readonly clock;
+    private readonly rng;
     private readonly presence;
     private readonly conditionalDelete;
     constructor(options: GcsStorageDriverOptions);
@@ -96,10 +98,11 @@ export declare class GcsStorageDriver implements IStorageDriver {
     /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
     private mapReadError;
     /**
-     * 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.
      */
     private mapError;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/gcs",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Google Cloud Storage for CloudBitmaps",
   "keywords": [
     "cloudbitmaps",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@google-cloud/storage": "^7 || ^8",
-    "@cloudbitmaps/core": "^0.20.0"
+    "@cloudbitmaps/core": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/keys.d.ts

@@ -1,31 +0,0 @@
-/**
- * Logical-ref → GCS object-name mapping for {@link GcsStorageDriver}.
- *
- * Pure string logic, no SDK dependency — unit-testable without GCS or an emulator. Uses the **same
- * backend-agnostic `.crbm` object-name scheme** as the S3 + LocalFs storage drivers
- * (`<prefix><ns>/segments/<segment>.<gen>.crbm`), so a segment reads identically whichever storage backend holds
- * it. The default (absent) namespace maps to `_default`, which cannot collide with a real namespace because a
- * caller's `_default` encodes to `%5Fdefault` while the sentinel is emitted literally.
- *
- * The storage-key layout is shared, not copied: `prefixPart` and the name encoders come from
- * `@cloudbitmaps/core/driver-kit`, so a segment written by one driver reads identically under another. Two
- * drivers disagreeing about how a name becomes a key would be a silent cross-driver incompatibility on the
- * same bucket, which is exactly the kind of thing a local copy drifts into.
- */
-import type { GenKey, SegmentRef } from '@cloudbitmaps/core/driver-kit';
-/** Validate a caller-supplied key prefix. The rule is shared with every other object store. */
-export { normalizeObjectPrefix as normalizeGcsPrefix } from '@cloudbitmaps/core/driver-kit';
-/**
- * The GCS object-name prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`.
- * Used both as the `getFiles` prefix and as the string stripped by {@link parseGenerationFromName}.
- */
-export declare function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string;
-/** The full GCS object name of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */
-export declare function storageObjectName(prefix: string | undefined, key: GenKey): string;
-/**
- * Parse a generation number out of a full object name, given its segment prefix, or `null` if it doesn't
- * match. Canonical decimal only — no leading zeros (so `…s.07.crbm` can't alias `…s.7.crbm`) and within
- * safe-integer range. Also rejects a *different* segment whose name merely shares the prefix (its middle
- * isn't all digits).
- */
-export declare function parseGenerationFromName(segmentPrefix: string, objectName: string): number | null;