@btravstack/storage 0.36.0 → 0.37.0

package/README.md

@@ -121,7 +121,7 @@ which is this list's one detailed home.
 ## What it decides, and what it does not
 
 **It decides** that a missing object is an ordinary answer rather than a fault
-(counted `not_found`, logged at `info`), that `delete` is idempotent, that
+(counted `not_found`, logged at `info`), that a held key under `putIfAbsent` is an ordinary answer (`ObjectExists`, counted `exists`), that `delete` is idempotent, that
 presigning asks the store nothing — and that an adapter which cannot presign
 says so instead of minting a URL that would fail only in production.
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_storage = require("./storage-QVPXOcO6.cjs");
+const require_storage = require("./storage-DlAQXJ1t.cjs");
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 let _btravstack_core = require("@btravstack/core");
@@ -24,6 +24,14 @@ const memoryStorageBackend = () => {
 			});
 			return (0, unthrown.OkAsync)();
 		},
+		putIfAbsent: (key, bytes, options) => {
+			if (objects.has(key)) return (0, unthrown.ErrAsync)(new require_storage.ObjectExists({ key }));
+			objects.set(key, {
+				bytes,
+				contentType: options.contentType
+			});
+			return (0, unthrown.OkAsync)();
+		},
 		get: (key) => {
 			const object = objects.get(key);
 			return object === void 0 ? (0, unthrown.ErrAsync)(new require_storage.ObjectNotFound({ key })) : (0, unthrown.OkAsync)(object);
@@ -59,17 +67,23 @@ const memoryStorage = () => (0, _btravstack_di.Module)("MemoryStorage")({
 */
 const failed = (failure) => {
 	const cause = failure.tag === "Err" ? failure.error : failure.cause;
-	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectNotFound" ? "the object was not there" : failure.error._tag === "PresignNotSupported" ? "this store cannot mint a url" : void 0;
+	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectExists" ? {
+		result: "exists",
+		reason: "an object already held the key"
+	} : failure.error._tag === "ObjectNotFound" ? {
+		result: "not_found",
+		reason: "the object was not there"
+	} : failure.error._tag === "PresignNotSupported" ? {
+		result: "not_found",
+		reason: "this store cannot mint a url"
+	} : void 0;
 	return ordinary === void 0 ? {
 		outcome: "error",
 		attributes: { result: "error" },
 		cause
 	} : {
 		outcome: "ok",
-		attributes: {
-			result: "not_found",
-			reason: ordinary
-		}
+		attributes: ordinary
 	};
 };
 /** The KEY is a detail, not a dimension: on the span and the line, never on an instrument. */
@@ -90,6 +104,7 @@ const instrument = (backend, observers) => {
 	const observe = through(observers);
 	return {
 		put: (key, bytes, options) => observe("put", key, () => backend.put(key, bytes, options)),
+		putIfAbsent: (key, bytes, options) => observe("put_if_absent", key, () => backend.putIfAbsent(key, bytes, options)),
 		get: (key) => observe("get", key, () => backend.get(key)),
 		delete: (key) => observe("delete", key, () => backend.delete(key)),
 		presignedUrl: (key, options) => observe("presigned_url", key, () => backend.presignedUrl(key, options)),
@@ -139,6 +154,7 @@ const storage = ({ adapter }) => {
 	});
 };
 //#endregion
+exports.ObjectExists = require_storage.ObjectExists;
 exports.ObjectNotFound = require_storage.ObjectNotFound;
 exports.PresignNotSupported = require_storage.PresignNotSupported;
 exports.Storage = require_storage.Storage;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-BLJtJ7KF.cjs";
+import { a as StorageBackend, c as StoredObject, i as Storage, n as ObjectNotFound, o as StorageService, r as PresignNotSupported, s as StorageUnavailable, t as ObjectExists } from "./storage-uSBWFyB2.cjs";
 import { Module, Provider } from "@btravstack/di";
 import { HealthChecks } from "@btravstack/core";
 //#region src/memory.d.ts
@@ -47,4 +47,4 @@ type StorageOptions<E, N> = {
  */
 export declare const storage: <E, N>({ adapter }: StorageOptions<E, N>) => Module<Storage | HealthChecks, E, N>;
 //#endregion
-export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };
+export { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-BLJtJ7KF.mjs";
+import { a as StorageBackend, c as StoredObject, i as Storage, n as ObjectNotFound, o as StorageService, r as PresignNotSupported, s as StorageUnavailable, t as ObjectExists } from "./storage-uSBWFyB2.mjs";
 import { Module, Provider } from "@btravstack/di";
 import { HealthChecks } from "@btravstack/core";
 //#region src/memory.d.ts
@@ -47,4 +47,4 @@ type StorageOptions<E, N> = {
  */
 export declare const storage: <E, N>({ adapter }: StorageOptions<E, N>) => Module<Storage | HealthChecks, E, N>;
 //#endregion
-export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };
+export { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as StorageUnavailable, i as StorageBackend, n as PresignNotSupported, r as Storage, t as ObjectNotFound } from "./storage-CRkwIhac.mjs";
+import { a as StorageBackend, i as Storage, n as ObjectNotFound, o as StorageUnavailable, r as PresignNotSupported, t as ObjectExists } from "./storage-BmbyYPIE.mjs";
 import { Module, Provider } from "@btravstack/di";
 import { Err, ErrAsync, Ok, OkAsync, P } from "unthrown";
 import { HealthCheckFailed, HealthChecks, Observers, noObserverMember, observed } from "@btravstack/core";
@@ -23,6 +23,14 @@ const memoryStorageBackend = () => {
 			});
 			return OkAsync();
 		},
+		putIfAbsent: (key, bytes, options) => {
+			if (objects.has(key)) return ErrAsync(new ObjectExists({ key }));
+			objects.set(key, {
+				bytes,
+				contentType: options.contentType
+			});
+			return OkAsync();
+		},
 		get: (key) => {
 			const object = objects.get(key);
 			return object === void 0 ? ErrAsync(new ObjectNotFound({ key })) : OkAsync(object);
@@ -58,17 +66,23 @@ const memoryStorage = () => Module("MemoryStorage")({
 */
 const failed = (failure) => {
 	const cause = failure.tag === "Err" ? failure.error : failure.cause;
-	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectNotFound" ? "the object was not there" : failure.error._tag === "PresignNotSupported" ? "this store cannot mint a url" : void 0;
+	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectExists" ? {
+		result: "exists",
+		reason: "an object already held the key"
+	} : failure.error._tag === "ObjectNotFound" ? {
+		result: "not_found",
+		reason: "the object was not there"
+	} : failure.error._tag === "PresignNotSupported" ? {
+		result: "not_found",
+		reason: "this store cannot mint a url"
+	} : void 0;
 	return ordinary === void 0 ? {
 		outcome: "error",
 		attributes: { result: "error" },
 		cause
 	} : {
 		outcome: "ok",
-		attributes: {
-			result: "not_found",
-			reason: ordinary
-		}
+		attributes: ordinary
 	};
 };
 /** The KEY is a detail, not a dimension: on the span and the line, never on an instrument. */
@@ -89,6 +103,7 @@ const instrument = (backend, observers) => {
 	const observe = through(observers);
 	return {
 		put: (key, bytes, options) => observe("put", key, () => backend.put(key, bytes, options)),
+		putIfAbsent: (key, bytes, options) => observe("put_if_absent", key, () => backend.putIfAbsent(key, bytes, options)),
 		get: (key) => observe("get", key, () => backend.get(key)),
 		delete: (key) => observe("delete", key, () => backend.delete(key)),
 		presignedUrl: (key, options) => observe("presigned_url", key, () => backend.presignedUrl(key, options)),
@@ -138,4 +153,4 @@ const storage = ({ adapter }) => {
 	});
 };
 //#endregion
-export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };
+export { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };

package/dist/s3.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_storage = require("./storage-QVPXOcO6.cjs");
+const require_storage = require("./storage-DlAQXJ1t.cjs");
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 let _aws_sdk_client_s3 = require("@aws-sdk/client-s3");
@@ -35,6 +35,8 @@ const unavailable = (operation, key, cause) => new require_storage.StorageUnavai
 	key,
 	reason: cause instanceof Error ? cause.message : String(cause)
 });
+/** S3's answer to `If-None-Match: *` on a key that is held: HTTP 412. */
+const isPreconditionFailed = (cause) => cause?.$metadata?.httpStatusCode === 412;
 /** A missing key is S3's `NoSuchKey`, which is a different fact from "the store is down". */
 const isMissing = (cause) => cause instanceof Error && (cause.name === "NoSuchKey" || cause.name === "NotFound");
 /**
@@ -49,6 +51,13 @@ const s3StorageBackend = (client, bucket) => ({
 		Body: bytes,
 		ContentType: options.contentType
 	})), (cause) => unavailable("put", key, cause)).map(() => void 0),
+	putIfAbsent: (key, bytes, options) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.PutObjectCommand({
+		Bucket: bucket,
+		Key: key,
+		Body: bytes,
+		ContentType: options.contentType,
+		IfNoneMatch: "*"
+	})), (cause) => isPreconditionFailed(cause) ? new require_storage.ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0),
 	get: (key) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.GetObjectCommand({
 		Bucket: bucket,
 		Key: key

package/dist/s3.d.cts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend } from "./storage-BLJtJ7KF.cjs";
+import { a as StorageBackend, o as StorageService } from "./storage-uSBWFyB2.cjs";
 import { Module, Scope } from "@btravstack/di";
 import { S3Client } from "@aws-sdk/client-s3";
 import { ConfigInvalid, EnvReading } from "@btravstack/config";

package/dist/s3.d.mts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend } from "./storage-BLJtJ7KF.mjs";
+import { a as StorageBackend, o as StorageService } from "./storage-uSBWFyB2.mjs";
 import { Module, Scope } from "@btravstack/di";
 import { S3Client } from "@aws-sdk/client-s3";
 import { ConfigInvalid, EnvReading } from "@btravstack/config";

package/dist/s3.mjs

@@ -1,4 +1,4 @@
-import { a as StorageUnavailable, i as StorageBackend, t as ObjectNotFound } from "./storage-CRkwIhac.mjs";
+import { a as StorageBackend, n as ObjectNotFound, o as StorageUnavailable, t as ObjectExists } from "./storage-BmbyYPIE.mjs";
 import { Module, Port, Provider } from "@btravstack/di";
 import { Ok, fromPromise } from "unthrown";
 import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
@@ -34,6 +34,8 @@ const unavailable = (operation, key, cause) => new StorageUnavailable({
 	key,
 	reason: cause instanceof Error ? cause.message : String(cause)
 });
+/** S3's answer to `If-None-Match: *` on a key that is held: HTTP 412. */
+const isPreconditionFailed = (cause) => cause?.$metadata?.httpStatusCode === 412;
 /** A missing key is S3's `NoSuchKey`, which is a different fact from "the store is down". */
 const isMissing = (cause) => cause instanceof Error && (cause.name === "NoSuchKey" || cause.name === "NotFound");
 /**
@@ -48,6 +50,13 @@ const s3StorageBackend = (client, bucket) => ({
 		Body: bytes,
 		ContentType: options.contentType
 	})), (cause) => unavailable("put", key, cause)).map(() => void 0),
+	putIfAbsent: (key, bytes, options) => fromPromise(client.send(new PutObjectCommand({
+		Bucket: bucket,
+		Key: key,
+		Body: bytes,
+		ContentType: options.contentType,
+		IfNoneMatch: "*"
+	})), (cause) => isPreconditionFailed(cause) ? new ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0),
 	get: (key) => fromPromise(client.send(new GetObjectCommand({
 		Bucket: bucket,
 		Key: key

package/dist/{storage-CRkwIhac.mjs → storage-BmbyYPIE.mjs}

@@ -3,6 +3,8 @@ import { TaggedError } from "unthrown";
 //#region src/storage.ts
 /** The key is not there. Only `get` answers it — see `delete` and `presignedUrl` below. */
 var ObjectNotFound = class extends TaggedError("ObjectNotFound") {};
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+var ObjectExists = class extends TaggedError("ObjectExists") {};
 /** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
 var StorageUnavailable = class extends TaggedError("StorageUnavailable") {};
 /** The adapter cannot mint a time-limited URL, and says so rather than pretending. */
@@ -22,4 +24,4 @@ var Storage = class extends Port("Storage") {};
 /** The port every adapter provides, and the one an application never depends on. */
 var StorageBackend = class extends Port("StorageBackend") {};
 //#endregion
-export { StorageUnavailable as a, StorageBackend as i, PresignNotSupported as n, Storage as r, ObjectNotFound as t };
+export { StorageBackend as a, Storage as i, ObjectNotFound as n, StorageUnavailable as o, PresignNotSupported as r, ObjectExists as t };

package/dist/{storage-QVPXOcO6.cjs → storage-DlAQXJ1t.cjs}

@@ -3,6 +3,8 @@ let unthrown = require("unthrown");
 //#region src/storage.ts
 /** The key is not there. Only `get` answers it — see `delete` and `presignedUrl` below. */
 var ObjectNotFound = class extends (0, unthrown.TaggedError)("ObjectNotFound") {};
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+var ObjectExists = class extends (0, unthrown.TaggedError)("ObjectExists") {};
 /** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
 var StorageUnavailable = class extends (0, unthrown.TaggedError)("StorageUnavailable") {};
 /** The adapter cannot mint a time-limited URL, and says so rather than pretending. */
@@ -22,6 +24,12 @@ var Storage = class extends (0, _btravstack_di.Port)("Storage") {};
 /** The port every adapter provides, and the one an application never depends on. */
 var StorageBackend = class extends (0, _btravstack_di.Port)("StorageBackend") {};
 //#endregion
+Object.defineProperty(exports, "ObjectExists", {
+	enumerable: true,
+	get: function() {
+		return ObjectExists;
+	}
+});
 Object.defineProperty(exports, "ObjectNotFound", {
 	enumerable: true,
 	get: function() {

package/dist/{storage-BLJtJ7KF.d.cts → storage-uSBWFyB2.d.cts}

@@ -10,10 +10,15 @@ declare const ObjectNotFound_base: import("unthrown").TaggedErrorConstructor<"Ob
 declare class ObjectNotFound extends ObjectNotFound_base<{
   readonly key: string;
 }> {}
+declare const ObjectExists_base: import("unthrown").TaggedErrorConstructor<"ObjectExists">;
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+declare class ObjectExists extends ObjectExists_base<{
+  readonly key: string;
+}> {}
 declare const StorageUnavailable_base: import("unthrown").TaggedErrorConstructor<"StorageUnavailable">;
 /** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
 declare class StorageUnavailable extends StorageUnavailable_base<{
-  readonly operation: "put" | "get" | "delete" | "presignedUrl" | "presignedUpload";
+  readonly operation: "put" | "putIfAbsent" | "get" | "delete" | "presignedUrl" | "presignedUpload";
   readonly key: string;
   readonly reason: string;
 }> {}
@@ -26,6 +31,10 @@ type StorageService = {
   readonly put: (key: string, bytes: Uint8Array, options: {
     readonly contentType: string;
   }) => AsyncResult<void, StorageUnavailable>;
+  /** Writes the object only if no object holds the key: the first writer wins, atomically, in the store. */
+  readonly putIfAbsent: (key: string, bytes: Uint8Array, options: {
+    readonly contentType: string;
+  }) => AsyncResult<void, ObjectExists | StorageUnavailable>;
   readonly get: (key: string) => AsyncResult<StoredObject, ObjectNotFound | StorageUnavailable>;
   /** Deleting a key nobody stored is `Ok`: delete is idempotent, which is S3's own behaviour rather than a fiction over it. */
   readonly delete: (key: string) => AsyncResult<void, StorageUnavailable>;
@@ -80,4 +89,4 @@ declare const StorageBackend_base: import("@btravstack/di").PortClass<"StorageBa
 /** The port every adapter provides, and the one an application never depends on. */
 declare class StorageBackend extends StorageBackend_base<StorageService> {}
 //#endregion
-export { StorageService as a, StorageBackend as i, PresignNotSupported as n, StorageUnavailable as o, Storage as r, StoredObject as s, ObjectNotFound as t };
+export { StorageBackend as a, StoredObject as c, Storage as i, ObjectNotFound as n, StorageService as o, PresignNotSupported as r, StorageUnavailable as s, ObjectExists as t };

package/dist/{storage-BLJtJ7KF.d.mts → storage-uSBWFyB2.d.mts}

@@ -10,10 +10,15 @@ declare const ObjectNotFound_base: import("unthrown").TaggedErrorConstructor<"Ob
 declare class ObjectNotFound extends ObjectNotFound_base<{
   readonly key: string;
 }> {}
+declare const ObjectExists_base: import("unthrown").TaggedErrorConstructor<"ObjectExists">;
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+declare class ObjectExists extends ObjectExists_base<{
+  readonly key: string;
+}> {}
 declare const StorageUnavailable_base: import("unthrown").TaggedErrorConstructor<"StorageUnavailable">;
 /** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
 declare class StorageUnavailable extends StorageUnavailable_base<{
-  readonly operation: "put" | "get" | "delete" | "presignedUrl" | "presignedUpload";
+  readonly operation: "put" | "putIfAbsent" | "get" | "delete" | "presignedUrl" | "presignedUpload";
   readonly key: string;
   readonly reason: string;
 }> {}
@@ -26,6 +31,10 @@ type StorageService = {
   readonly put: (key: string, bytes: Uint8Array, options: {
     readonly contentType: string;
   }) => AsyncResult<void, StorageUnavailable>;
+  /** Writes the object only if no object holds the key: the first writer wins, atomically, in the store. */
+  readonly putIfAbsent: (key: string, bytes: Uint8Array, options: {
+    readonly contentType: string;
+  }) => AsyncResult<void, ObjectExists | StorageUnavailable>;
   readonly get: (key: string) => AsyncResult<StoredObject, ObjectNotFound | StorageUnavailable>;
   /** Deleting a key nobody stored is `Ok`: delete is idempotent, which is S3's own behaviour rather than a fiction over it. */
   readonly delete: (key: string) => AsyncResult<void, StorageUnavailable>;
@@ -80,4 +89,4 @@ declare const StorageBackend_base: import("@btravstack/di").PortClass<"StorageBa
 /** The port every adapter provides, and the one an application never depends on. */
 declare class StorageBackend extends StorageBackend_base<StorageService> {}
 //#endregion
-export { StorageService as a, StorageBackend as i, PresignNotSupported as n, StorageUnavailable as o, Storage as r, StoredObject as s, ObjectNotFound as t };
+export { StorageBackend as a, StoredObject as c, Storage as i, ObjectNotFound as n, StorageService as o, PresignNotSupported as r, StorageUnavailable as s, ObjectExists as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/storage",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "A Storage port for @btravstack/core: an in-memory adapter, an S3-compatible adapter with presigned reads, and a composition that spans, counts and logs every operation",
   "keywords": [
     "dependency-injection",
@@ -55,11 +55,11 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "3.1149.0",
     "@aws-sdk/s3-request-presigner": "3.1149.0",
-    "@btravstack/config": "0.36.0",
-    "@btravstack/core": "0.36.0",
-    "@btravstack/di": "0.36.0",
+    "@btravstack/config": "0.37.0",
+    "@btravstack/core": "0.37.0",
+    "@btravstack/di": "0.37.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/observability": "0.36.0",
+    "@btravstack/observability": "0.37.0",
     "@btravstack/tsconfig": "0.4.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/sdk-metrics": "2.12.0",
@@ -76,9 +76,9 @@
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.1000.0",
     "@aws-sdk/s3-request-presigner": "^3.1000.0",
-    "@btravstack/config": "^0.36.0",
-    "@btravstack/core": "^0.36.0",
-    "@btravstack/di": "^0.36.0",
+    "@btravstack/config": "^0.37.0",
+    "@btravstack/core": "^0.37.0",
+    "@btravstack/di": "^0.37.0",
     "unthrown": "^5.0.0"
   },
   "peerDependenciesMeta": {