@nestm/storage 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/index.js

@@ -1,8 +1,6 @@
-export { DEFAULT_BUFFER_LIMIT, StorageClient, } from './storage.client.js';
-export { StorageError, StorageErrorCode, isStorageError, normalizeStorageError, } from './storage.error.js';
+export * from './core/index.js';
 export { InjectStorage } from './inject-storage.decorator.js';
 export { StorageModule } from './storage.module.js';
 export { StorageService } from './storage.service.js';
 export { DEFAULT_STORAGE_NAME, STORAGE, getStorageToken, } from './storage.tokens.js';
-export { StorageUploadControl, } from './storage-upload-control.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,aAAa,GAEd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,GAEtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAapD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,OAAO,EACP,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAGrB,MAAM,6BAA6B,CAAC","sourcesContent":["export {\n  DEFAULT_BUFFER_LIMIT,\n  StorageClient,\n  type StorageFileHandle,\n} from './storage.client.js';\nexport type { StorageDriver } from './storage.driver.js';\nexport {\n  StorageError,\n  StorageErrorCode,\n  isStorageError,\n  normalizeStorageError,\n  type StorageErrorOptions,\n} from './storage.error.js';\nexport { InjectStorage } from './inject-storage.decorator.js';\nexport { StorageModule } from './storage.module.js';\nexport type {\n  StorageAsyncStoreDefinition,\n  StorageClassStoreDefinition,\n  StorageDriverFactory,\n  StorageExistingStoreDefinition,\n  StorageFactoryStoreDefinition,\n  StorageFeatureAsyncOptions,\n  StorageFeatureOptions,\n  StorageModuleAsyncOptions,\n  StorageModuleOptions,\n  StorageStoreDefinition,\n} from './storage-module.options.js';\nexport { StorageService } from './storage.service.js';\nexport {\n  DEFAULT_STORAGE_NAME,\n  STORAGE,\n  getStorageToken,\n} from './storage.tokens.js';\nexport {\n  StorageUploadControl,\n  type StorageResumableToken,\n  type StorageUploadStatus,\n} from './storage-upload-control.js';\nexport type * from './storage.types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAapD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,OAAO,EACP,eAAe,GAChB,MAAM,qBAAqB,CAAC","sourcesContent":["export * from './core/index.js';\nexport { InjectStorage } from './inject-storage.decorator.js';\nexport { StorageModule } from './storage.module.js';\nexport type {\n  StorageAsyncStoreDefinition,\n  StorageClassStoreDefinition,\n  StorageDriverFactory,\n  StorageExistingStoreDefinition,\n  StorageFactoryStoreDefinition,\n  StorageFeatureAsyncOptions,\n  StorageFeatureOptions,\n  StorageModuleAsyncOptions,\n  StorageModuleOptions,\n  StorageStoreDefinition,\n} from './storage-module.options.js';\nexport { StorageService } from './storage.service.js';\nexport {\n  DEFAULT_STORAGE_NAME,\n  STORAGE,\n  getStorageToken,\n} from './storage.tokens.js';\n"]}

package/dist/inject-storage.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"inject-storage.decorator.js","sourceRoot":"","sources":["../src/inject-storage.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE5E,MAAM,UAAU,aAAa,CAC3B,OAAe,oBAAoB;IAEnC,OAAO,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC","sourcesContent":["import { Inject } from '@nestjs/common';\n\nimport { DEFAULT_STORAGE_NAME, getStorageToken } from './storage.tokens.js';\n\nexport function InjectStorage(\n  name: string = DEFAULT_STORAGE_NAME,\n): ParameterDecorator & PropertyDecorator {\n  return Inject(getStorageToken(name));\n}\n"]}
+{"version":3,"file":"inject-storage.decorator.js","sourceRoot":"","sources":["../src/inject-storage.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE5E,MAAM,UAAU,aAAa,CAC3B,IAAI,GAAW,oBAAoB;IAEnC,OAAO,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC","sourcesContent":["import { Inject } from '@nestjs/common';\n\nimport { DEFAULT_STORAGE_NAME, getStorageToken } from './storage.tokens.js';\n\nexport function InjectStorage(\n  name: string = DEFAULT_STORAGE_NAME,\n): ParameterDecorator & PropertyDecorator {\n  return Inject(getStorageToken(name));\n}\n"]}

package/dist/storage-etag.d.ts

@@ -0,0 +1,13 @@
+/** Maximum UTF-8 byte length of a normalized storage ETag. */
+export declare const MAX_STORAGE_ETAG_BYTES = 1024;
+/** Returns whether a value is the package's canonical bare ETag form. */
+export declare function isCanonicalStorageEtag(value: unknown): value is string;
+/**
+ * Normalizes one provider-returned strong entity tag to the canonical bare
+ * form. Providers may return either the HTTP-quoted representation or an
+ * already-normalized value; lists, weak tags, and malformed values fail.
+ */
+export declare function normalizeProviderStorageEtag(value: unknown): string | undefined;
+/** Serializes one canonical bare ETag as exactly one HTTP entity tag. */
+export declare function storageEtagHeader(value: unknown): string | undefined;
+//# sourceMappingURL=storage-etag.d.ts.map

package/dist/storage-etag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-etag.d.ts","sourceRoot":"","sources":["../src/storage-etag.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAQ3C,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAMtE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,SAAS,CASpB;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEpE"}

package/dist/storage-etag.js

@@ -0,0 +1,31 @@
+/** Maximum UTF-8 byte length of a normalized storage ETag. */
+export const MAX_STORAGE_ETAG_BYTES = 1024;
+// Deliberately narrower than RFC 9110's etagc grammar. Commas and backslashes
+// are excluded so a normalized value cannot be confused with an entity-tag
+// list or be interpreted differently by legacy HTTP implementations.
+const canonicalStorageEtag = /^(?!\*$)(?![Ww]\/)[\x21\x23-\x2B\x2D-\x5B\x5D-\x7E]+$/u;
+/** Returns whether a value is the package's canonical bare ETag form. */
+export function isCanonicalStorageEtag(value) {
+    return (typeof value === 'string' &&
+        value.length <= MAX_STORAGE_ETAG_BYTES &&
+        canonicalStorageEtag.test(value));
+}
+/**
+ * Normalizes one provider-returned strong entity tag to the canonical bare
+ * form. Providers may return either the HTTP-quoted representation or an
+ * already-normalized value; lists, weak tags, and malformed values fail.
+ */
+export function normalizeProviderStorageEtag(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const opaque = value.startsWith('"') && value.endsWith('"') && value.length >= 3
+        ? value.slice(1, -1)
+        : value;
+    return isCanonicalStorageEtag(opaque) ? opaque : undefined;
+}
+/** Serializes one canonical bare ETag as exactly one HTTP entity tag. */
+export function storageEtagHeader(value) {
+    return isCanonicalStorageEtag(value) ? `"${value}"` : undefined;
+}
+//# sourceMappingURL=storage-etag.js.map

package/dist/storage-etag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-etag.js","sourceRoot":"","sources":["../src/storage-etag.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C,8EAA8E;AAC9E,2EAA2E;AAC3E,qEAAqE;AACrE,MAAM,oBAAoB,GACxB,wDAAwD,CAAC;AAE3D,yEAAyE;AACzE,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,IAAI,sBAAsB;QACtC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CACjC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAAc;IAEd,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GACV,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAC/D,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC;IACZ,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC","sourcesContent":["/** Maximum UTF-8 byte length of a normalized storage ETag. */\nexport const MAX_STORAGE_ETAG_BYTES = 1024;\n\n// Deliberately narrower than RFC 9110's etagc grammar. Commas and backslashes\n// are excluded so a normalized value cannot be confused with an entity-tag\n// list or be interpreted differently by legacy HTTP implementations.\nconst canonicalStorageEtag =\n  /^(?!\\*$)(?![Ww]\\/)[\\x21\\x23-\\x2B\\x2D-\\x5B\\x5D-\\x7E]+$/u;\n\n/** Returns whether a value is the package's canonical bare ETag form. */\nexport function isCanonicalStorageEtag(value: unknown): value is string {\n  return (\n    typeof value === 'string' &&\n    value.length <= MAX_STORAGE_ETAG_BYTES &&\n    canonicalStorageEtag.test(value)\n  );\n}\n\n/**\n * Normalizes one provider-returned strong entity tag to the canonical bare\n * form. Providers may return either the HTTP-quoted representation or an\n * already-normalized value; lists, weak tags, and malformed values fail.\n */\nexport function normalizeProviderStorageEtag(\n  value: unknown,\n): string | undefined {\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n  const opaque =\n    value.startsWith('\"') && value.endsWith('\"') && value.length >= 3\n      ? value.slice(1, -1)\n      : value;\n  return isCanonicalStorageEtag(opaque) ? opaque : undefined;\n}\n\n/** Serializes one canonical bare ETag as exactly one HTTP entity tag. */\nexport function storageEtagHeader(value: unknown): string | undefined {\n  return isCanonicalStorageEtag(value) ? `\"${value}\"` : undefined;\n}\n"]}

package/dist/storage-upload-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-upload-control.d.ts","sourceRoot":"","sources":["../src/storage-upload-control.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,mBAAmB,GAC7B,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAkHD,qBAAa,oBAAoB;;IAK/B,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB;IAmBjD,IAAI,MAAM,IAAI,mBAAmB,CAEhC;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAE9B;IAED,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,IAAI;IAId,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,MAAM,IAAI,qBAAqB,GAAG,SAAS;CAY5C"}
+{"version":3,"file":"storage-upload-control.d.ts","sourceRoot":"","sources":["../src/storage-upload-control.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,mBAAmB,GAC7B,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAkHD,qBAAa,oBAAoB;IAC/B,cAEC;IAED,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAiBhD;IAED,IAAI,MAAM,IAAI,mBAAmB,CAEhC;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAE9B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,MAAM,IAAI,IAAI,CAEb;IAED,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAErC;IAED,MAAM,IAAI,qBAAqB,GAAG,SAAS,CAW1C;CACF"}

package/dist/storage.client.d.ts

@@ -1,24 +1,28 @@
-import type { OnApplicationShutdown } from '@nestjs/common';
 import type { StorageDriver } from './storage.driver.js';
-import type { StorageBody, StorageBufferedDownloadOptions, StorageBulkOptions, StorageCapabilities, StorageDeleteManyResult, StorageDownloadManyResult, StorageDownloadOptions, StorageExistsManyResult, StorageHeadManyResult, StorageListOptions, StorageListResult, StorageObject, StorageObjectMetadata, StorageOperationOptions, StoragePlugin, StorageSearchOptions, StorageSignedDownloadOptions, StorageSignedUpload, StorageSignedUploadOptions, StorageUploadManyItem, StorageUploadManyOptions, StorageUploadManyResult, StorageUploadOptions, StorageUploadResult } from './storage.types.js';
+import type { StorageBody, StorageBufferedDownloadOptions, StorageBulkOptions, StorageCapabilities, StorageConditionalDeleteOptions, StorageConditionalReadOptions, StorageConditionalUploadOptions, StorageDeleteManyResult, StorageDownloadManyResult, StorageDownloadOptions, StorageExistsManyResult, StorageHeadManyResult, StorageListOptions, StorageListResult, StorageObject, StorageObjectMetadata, StorageOperationOptions, StoragePlugin, StoragePromotionOptions, StorageSearchOptions, StorageSignedDownloadOptions, StorageSignedUpload, StorageSignedUploadOptions, StorageUploadManyItem, StorageUploadManyOptions, StorageUploadManyResult, StorageUploadOptions, StorageUploadResult } from './storage.types.js';
 export declare const DEFAULT_BUFFER_LIMIT: number;
 type BulkOperationOptions = StorageBulkOptions & StorageOperationOptions;
 type DownloadManyOptions = StorageBulkOptions & StorageDownloadOptions;
 export interface StorageFileHandle {
     readonly key: string;
     upload(body: StorageBody, options?: StorageUploadOptions): Promise<StorageUploadResult>;
+    uploadConditional(body: StorageBody, options: StorageConditionalUploadOptions): Promise<StorageUploadResult>;
     download(options?: StorageDownloadOptions): Promise<StorageObject>;
+    downloadConditional(options: StorageConditionalReadOptions): Promise<StorageObject>;
     bytes(options?: StorageBufferedDownloadOptions): Promise<Uint8Array>;
     text(options?: StorageBufferedDownloadOptions): Promise<string>;
     head(options?: StorageOperationOptions): Promise<StorageObjectMetadata>;
     exists(options?: StorageOperationOptions): Promise<boolean>;
     delete(options?: StorageOperationOptions): Promise<void>;
+    deleteConditional(options: StorageConditionalDeleteOptions): Promise<void>;
     signDownload(options?: StorageSignedDownloadOptions): Promise<string>;
     signUpload(options: StorageSignedUploadOptions): Promise<StorageSignedUpload>;
     copyTo(destinationKey: string, options?: StorageOperationOptions): Promise<void>;
     moveTo(destinationKey: string, options?: StorageOperationOptions): Promise<void>;
+    /** Conditionally copies this staged object and deliberately retains it. */
+    promoteTo(destinationKey: string, options: StoragePromotionOptions): Promise<void>;
 }
-export declare class StorageClient implements OnApplicationShutdown {
+export declare class StorageClient {
     #private;
     readonly name: string;
     constructor(name: string, driver: StorageDriver, plugins?: readonly StoragePlugin[]);
@@ -26,15 +30,23 @@ export declare class StorageClient implements OnApplicationShutdown {
     get capabilities(): Readonly<StorageCapabilities>;
     file(key: string): StorageFileHandle;
     upload(key: string, body: StorageBody, options?: StorageUploadOptions): Promise<StorageUploadResult>;
+    uploadConditional(key: string, body: StorageBody, options: StorageConditionalUploadOptions): Promise<StorageUploadResult>;
     downloadStream(key: string, options?: StorageDownloadOptions): Promise<StorageObject>;
+    downloadConditional(key: string, options: StorageConditionalReadOptions): Promise<StorageObject>;
     downloadBytes(key: string, options?: StorageBufferedDownloadOptions): Promise<Uint8Array>;
     downloadText(key: string, options?: StorageBufferedDownloadOptions): Promise<string>;
     downloadJson<Result = unknown>(key: string, options?: StorageBufferedDownloadOptions): Promise<Result>;
     head(key: string, options?: StorageOperationOptions): Promise<StorageObjectMetadata>;
     exists(key: string, options?: StorageOperationOptions): Promise<boolean>;
     delete(key: string, options?: StorageOperationOptions): Promise<void>;
+    deleteConditional(key: string, options: StorageConditionalDeleteOptions): Promise<void>;
     copy(sourceKey: string, destinationKey: string, options?: StorageOperationOptions): Promise<void>;
     move(sourceKey: string, destinationKey: string, options?: StorageOperationOptions): Promise<void>;
+    /**
+     * Conditionally copies a staged object to a final key. This operation does
+     * not delete the source; delete it after the application commit succeeds.
+     */
+    promote(sourceKey: string, destinationKey: string, options: StoragePromotionOptions): Promise<void>;
     list(options?: StorageListOptions): Promise<StorageListResult>;
     listAll(options?: StorageListOptions): AsyncGenerator<StorageObjectMetadata, void>;
     search(pattern: string | RegExp, options?: StorageSearchOptions): AsyncIterable<StorageObjectMetadata>;

package/dist/storage.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.client.d.ts","sourceRoot":"","sources":["../src/storage.client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.client.d.ts","sourceRoot":"","sources":["../src/storage.client.ts"],"names":[],"mappings":"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"}

package/dist/storage.client.js

@@ -1,4 +1,5 @@
 import { settleMany } from './internal/settle-many.js';
+import { isCanonicalStorageEtag } from './storage-etag.js';
 import { StorageError, StorageErrorCode, normalizeStorageError, } from './storage.error.js';
 export const DEFAULT_BUFFER_LIMIT = 10 * 1024 * 1024;
 function assertKey(key, label = 'key') {
@@ -146,27 +147,116 @@ export class StorageClient {
         return {
             copyTo: (destinationKey, options) => this.copy(key, destinationKey, options),
             delete: (options) => this.delete(key, options),
+            deleteConditional: (options) => this.deleteConditional(key, options),
             download: (options) => this.downloadStream(key, options),
+            downloadConditional: (options) => this.downloadConditional(key, options),
             exists: (options) => this.exists(key, options),
             head: (options) => this.head(key, options),
             key,
             moveTo: (destinationKey, options) => this.move(key, destinationKey, options),
+            promoteTo: (destinationKey, options) => this.promote(key, destinationKey, options),
             signDownload: (options) => this.signDownload(key, options),
             signUpload: (options) => this.signUpload(key, options),
             bytes: (options) => this.downloadBytes(key, options),
             text: (options) => this.downloadText(key, options),
             upload: (body, options) => this.upload(key, body, options),
+            uploadConditional: (body, options) => this.uploadConditional(key, body, options),
         };
     }
     upload(key, body, options) {
         assertKey(key);
         return this.#execute({ key, operation: 'upload', store: this.name }, () => this.#driver.upload(key, body, options));
     }
+    uploadConditional(key, body, options) {
+        assertKey(key);
+        const condition = options.condition;
+        if (condition === undefined ||
+            (condition.type !== 'create' && condition.type !== 'replace')) {
+            invalidArgument('condition.type must be "create" or "replace".');
+        }
+        if (condition.type === 'replace' &&
+            !isCanonicalStorageEtag(condition.etag)) {
+            invalidArgument('condition.etag must be a canonical storage ETag.');
+        }
+        const capability = condition.type === 'create'
+            ? this.#driver.capabilities.conditionalCreate
+            : this.#driver.capabilities.conditionalReplace;
+        const uploadConditional = this.#driver.uploadConditional;
+        const multipartRequested = options.multipart !== undefined && options.multipart !== false;
+        const multipartCapability = this.#driver.capabilities.conditionalMultipartCompletion;
+        const multipartSupported = !multipartRequested ||
+            (condition.type === 'create'
+                ? multipartCapability?.create === true
+                : multipartCapability?.replace === true);
+        if (capability === undefined ||
+            !multipartSupported ||
+            uploadConditional === undefined) {
+            throw new StorageError(`Store "${this.name}" does not support the requested conditional upload.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'upload',
+                permanent: true,
+                store: this.name,
+            });
+        }
+        return this.#execute({ key, operation: 'upload', store: this.name }, () => uploadConditional.call(this.#driver, key, body, options), (result) => {
+            if (capability.resultEtag && !isCanonicalStorageEtag(result.etag)) {
+                throw new StorageError(`Store "${this.name}" committed a conditional upload without the advertised result ETag.`, {
+                    code: StorageErrorCode.PROVIDER,
+                    key,
+                    operation: 'upload',
+                    permanent: true,
+                    store: this.name,
+                });
+            }
+            return {
+                ...(isCanonicalStorageEtag(result.etag) && {
+                    appliedEtag: result.etag,
+                }),
+            };
+        });
+    }
     downloadStream(key, options) {
         assertKey(key);
         assertDownloadOptions(options);
         return this.#execute({ key, operation: 'download', store: this.name }, () => this.#driver.download(key, options));
     }
+    downloadConditional(key, options) {
+        assertKey(key);
+        assertDownloadOptions(options);
+        if (options === undefined ||
+            options.condition === undefined ||
+            typeof options.condition !== 'object' ||
+            options.condition === null) {
+            invalidArgument('conditional read requires a condition object.');
+        }
+        const { etag, version } = options.condition;
+        if (etag !== undefined && !isCanonicalStorageEtag(etag)) {
+            invalidArgument('condition.etag must be a canonical storage ETag.');
+        }
+        if (version !== undefined &&
+            (typeof version !== 'string' || version.length === 0)) {
+            invalidArgument('condition.version must be a non-empty string.');
+        }
+        if (etag === undefined && version === undefined) {
+            invalidArgument('conditional read requires an etag, version, or both.');
+        }
+        const capability = this.#driver.capabilities.conditionalRead;
+        const downloadConditional = this.#driver.downloadConditional;
+        if (downloadConditional === undefined ||
+            capability === undefined ||
+            (etag !== undefined && !capability.etag) ||
+            (version !== undefined && !capability.version)) {
+            throw new StorageError(`Store "${this.name}" does not support the requested conditional read.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'download',
+                permanent: true,
+                store: this.name,
+            });
+        }
+        return this.#execute({ key, operation: 'download', store: this.name }, () => downloadConditional.call(this.#driver, key, options));
+    }
     async downloadBytes(key, options) {
         const { maxBytes = DEFAULT_BUFFER_LIMIT, ...download } = options ?? {};
         const object = await this.downloadStream(key, download);
@@ -203,6 +293,25 @@ export class StorageClient {
         assertKey(key);
         return this.#execute({ key, operation: 'delete', store: this.name }, () => this.#driver.delete(key, options));
     }
+    deleteConditional(key, options) {
+        assertKey(key);
+        if (options.condition === undefined ||
+            !isCanonicalStorageEtag(options.condition.etag)) {
+            invalidArgument('condition.etag must be a canonical storage ETag.');
+        }
+        const capability = this.#driver.capabilities.conditionalDelete;
+        const deleteConditional = this.#driver.deleteConditional;
+        if (capability?.etag !== true || deleteConditional === undefined) {
+            throw new StorageError(`Store "${this.name}" does not support conditional delete.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'delete',
+                permanent: true,
+                store: this.name,
+            });
+        }
+        return this.#execute({ key, operation: 'delete', store: this.name }, () => deleteConditional.call(this.#driver, key, options), () => ({}));
+    }
     copy(sourceKey, destinationKey, options) {
         assertKey(sourceKey, 'source key');
         assertKey(destinationKey, 'destination key');
@@ -223,6 +332,73 @@ export class StorageClient {
             to: destinationKey,
         }, () => this.#driver.move(sourceKey, destinationKey, options));
     }
+    /**
+     * Conditionally copies a staged object to a final key. This operation does
+     * not delete the source; delete it after the application commit succeeds.
+     */
+    promote(sourceKey, destinationKey, options) {
+        assertKey(sourceKey, 'source key');
+        assertKey(destinationKey, 'destination key');
+        const sourceEtag = options.sourceEtag;
+        const sourceVersion = options.sourceVersion;
+        if (sourceEtag !== undefined && !isCanonicalStorageEtag(sourceEtag)) {
+            invalidArgument('sourceEtag must be a canonical storage ETag.');
+        }
+        if (sourceVersion !== undefined &&
+            (typeof sourceVersion !== 'string' || sourceVersion.length === 0)) {
+            invalidArgument('sourceVersion must be a non-empty string.');
+        }
+        const destination = options.destination;
+        if (destination !== undefined &&
+            (typeof destination !== 'object' ||
+                destination === null ||
+                (destination.type !== 'create' && destination.type !== 'replace'))) {
+            invalidArgument('destination.type must be "create" or "replace".');
+        }
+        if (sourceEtag === undefined &&
+            sourceVersion === undefined &&
+            destination === undefined) {
+            invalidArgument('promote requires a source or destination precondition.');
+        }
+        if (destination?.type === 'replace' &&
+            !isCanonicalStorageEtag(destination.etag)) {
+            invalidArgument('destination.etag must be a canonical storage ETag.');
+        }
+        const sourceCapability = this.#driver.capabilities.conditionalCopySource;
+        const destinationCapability = this.#driver.capabilities.conditionalCopyDestination;
+        const promote = this.#driver.promote;
+        const hasSourcePredicate = sourceEtag !== undefined || sourceVersion !== undefined;
+        if (promote === undefined ||
+            (sourceEtag !== undefined && sourceCapability?.etag !== true) ||
+            (sourceVersion !== undefined && sourceCapability?.version !== true) ||
+            (hasSourcePredicate &&
+                destination === undefined &&
+                sourceCapability?.requiresDestinationPredicate === true) ||
+            (destination?.type === 'create' &&
+                destinationCapability?.create !== true) ||
+            (destination?.type === 'replace' &&
+                destinationCapability?.replace !== true) ||
+            (destination !== undefined &&
+                !hasSourcePredicate &&
+                destinationCapability?.requiresSourcePredicate === true) ||
+            (destination !== undefined &&
+                hasSourcePredicate &&
+                destinationCapability?.atomicWithSource !== true)) {
+            throw new StorageError(`Store "${this.name}" does not support the requested conditional promotion.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key: sourceKey,
+                operation: 'promote',
+                permanent: true,
+                store: this.name,
+            });
+        }
+        return this.#execute({
+            from: sourceKey,
+            operation: 'promote',
+            store: this.name,
+            to: destinationKey,
+        }, () => promote.call(this.#driver, sourceKey, destinationKey, options), () => ({}));
+    }
     list(options) {
         assertListOptions(options);
         return this.#execute({ operation: 'list', store: this.name }, () => this.#driver.list(options));
@@ -363,23 +539,49 @@ export class StorageClient {
         this.#closed = true;
         await this.#driver.close?.();
     }
-    async #execute(context, operation) {
+    async #execute(context, operation, appliedMutation) {
+        let appliedSettlement;
         try {
             for (const plugin of this.#plugins) {
                 await plugin.beforeOperation?.(context);
             }
             const result = await operation();
+            if (appliedMutation !== undefined) {
+                // Settle before describing the result so even an unexpected local
+                // result-validation failure cannot turn a committed mutation into a
+                // safe-to-retry error.
+                appliedSettlement = {};
+                appliedSettlement = appliedMutation(result);
+            }
             for (const plugin of this.#plugins) {
                 await plugin.afterOperation?.(context, result);
             }
             return result;
         }
         catch (error) {
-            const normalized = normalizeStorageError(error, {
+            let normalized = normalizeStorageError(error, {
                 ...(context.key !== undefined && { key: context.key }),
                 operation: context.operation,
                 store: this.name,
             });
+            if (appliedSettlement !== undefined) {
+                normalized = new StorageError(normalized.message, {
+                    aborted: normalized.aborted,
+                    applied: true,
+                    ...(isCanonicalStorageEtag(appliedSettlement.appliedEtag) && {
+                        appliedEtag: appliedSettlement.appliedEtag,
+                    }),
+                    cause: normalized.cause,
+                    code: normalized.code,
+                    ...(normalized.key !== undefined && { key: normalized.key }),
+                    ...(normalized.operation !== undefined && {
+                        operation: normalized.operation,
+                    }),
+                    permanent: normalized.permanent,
+                    ...(normalized.store !== undefined && { store: normalized.store }),
+                    timedOut: normalized.timedOut,
+                });
+            }
             for (const plugin of this.#plugins) {
                 try {
                     await plugin.onError?.(context, normalized);