@cloudbitmaps/s3 0.19.1 → 0.20.0

package/dist/registry.d.ts

@@ -59,8 +59,7 @@ export interface S3RegistryDriverOptions {
     readonly readTimeoutMs?: number;
     /**
      * Whether a delete removes a row for good, by a `DeleteObject` sent with `If-Match: <the ETag it read>`, rather than
-     * leaving a tombstone. Only a row born with an incarnation id is removed; a row a release before 0.12 wrote is
-     * always tombstoned.
+     * leaving a tombstone.
      *
      * Defaults to `true` when the host the client resolves is an AWS S3 host (`*.amazonaws.com`, `*.amazonaws.com.cn`: the
      * FIPS, dual-stack, access-point and VPC interface forms included), where `If-Match` on `DeleteObject` is documented

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps } from '@cloudbitmaps/core/driver-kit';
+import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps, StorageDeleteOptions, TailRead } from '@cloudbitmaps/core/driver-kit';
 import { type S3Client } from '@aws-sdk/client-s3';
 import type { SocketAdvisory } from './socket-advisory.js';
 /** What the throttle backoff waits on. */
@@ -38,6 +38,15 @@ export interface S3StorageDriverOptions {
     readonly sockets?: SocketAdvisory;
     /** What the backoff before re-sending a throttled commit waits on; real time when absent. */
     readonly clock?: Sleeper;
+    /**
+     * Whether a delete given `ifVersion` is sent with `If-Match`, so it removes the object only while it is the one that
+     * ETag names. Defaults as the registry's option does: on when the host the client resolves is an AWS S3 host and the
+     * SDK sends the header, resolved on the first such delete (until then `capabilities()` reads `false`), and off for any
+     * other host, and for a client that cannot be resolved then (no region), whose deletes stay unconditional. Set it for
+     * an S3-compatible store only once you know the store applies `If-Match` on a delete. A `true` never overrides an SDK
+     * that does not send the header.
+     */
+    readonly conditionalDelete?: boolean;
 }
 export declare class S3StorageDriver implements IStorageDriver {
     private readonly client;
@@ -48,26 +57,33 @@ export declare class S3StorageDriver implements IStorageDriver {
     private readonly readTimeoutMs;
     private readonly clock;
     private readonly sockets;
+    private readonly explicitConditionalDelete;
+    private probed;
+    private facts;
     constructor(options: S3StorageDriverOptions);
     capabilities(): StorageCaps;
+    /** Ask the client once where its requests go and whether it sends `If-Match` on a delete; it sends nothing. */
+    private settle;
     putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
         size: number;
         sha256: string;
     }>;
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
-    getTail(key: GenKey, maxBytes: number): Promise<{
-        bytes: Uint8Array;
-        size: number;
-    }>;
+    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
     private badRead;
-    /** The object's size from a `HeadObject`, or `undefined` when the response does not carry one. */
-    private headSize;
+    /**
+     * The object's size and ETag from a `HeadObject`, each `undefined` when the response does not carry it. A missing
+     * object throws {@link NotFoundError}.
+     */
+    private head;
     /**
      * One read request under the read timeout, its failures mapped to the driver vocabulary. The timeout's own
      * `TransientError` is raised outside the mapping, so it reaches the caller as it is.
      */
     private read;
-    delete(key: GenKey): Promise<void>;
+    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
+    /** Whether an object is under the key, from one `HeadObject`. A read that fails in any other way throws. */
+    private exists;
     list(ref: SegmentRef): AsyncIterable<GenKey>;
     /** Map S3 read errors to the driver vocabulary; pass everything else through {@link mapError}. */
     private mapReadError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/s3",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "S3 and S3-compatible storage (R2, MinIO, Ceph, Wasabi, B2) for CloudBitmaps",
   "keywords": [
     "cloudbitmaps",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": ">=3.700.0 <4",
-    "@cloudbitmaps/core": "^0.19.1"
+    "@cloudbitmaps/core": "^0.20.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",