@btravstack/storage 0.4.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 > The object-storage port for [`@btravstack/core`](../core): one `Storage` an
 > application depends on, an in-memory adapter, an S3-compatible one with
-> presigned reads, and a span, a count and a log line per operation.
+> presigned reads and writes, and a span, a count and a log line per operation.
 
 📖 **[Documentation](https://btravstack.github.io/btravstack/reference/storage)** ·
 [API Reference](https://btravstack.github.io/btravstack/api/storage/)
@@ -16,7 +16,7 @@ Four peer dependencies, plus `@aws-sdk/client-s3` and
 S3 adapter. Instrumentation needs no peer of its own: the `Logger`, `Tracer`
 and `Meter` it depends on are
 [the kernel's ports](https://btravstack.github.io/btravstack/reference/core/observability).
-Node `>=20`.
+Node `>=22`.
 
 ## A worked example
 
@@ -129,5 +129,5 @@ says so instead of minting a URL that would fail only in production.
 
 **It does not decide** what your keys look like, whether a failed write should
 fail your request, or how long a link should live. There is no streaming, no
-presigned writes, no listing and no bucket management; the reasons are in
+no listing and no bucket management; the reasons are in
 [`CLAUDE.md`](./CLAUDE.md).

package/dist/index.cjs

@@ -32,7 +32,8 @@ const memoryStorageBackend = () => {
 			objects.delete(key);
 			return (0, unthrown.OkAsync)();
 		},
-		presignedUrl: (key) => (0, unthrown.ErrAsync)(new require_storage.PresignNotSupported({ key }))
+		presignedUrl: (key) => (0, unthrown.ErrAsync)(new require_storage.PresignNotSupported({ key })),
+		presignedUpload: (key) => (0, unthrown.ErrAsync)(new require_storage.PresignNotSupported({ key }))
 	};
 };
 /** The adapter as a provider, which is the shape `@btravstack/testing`'s `overridden` takes. */
@@ -95,7 +96,8 @@ const instrument = (backend, logger, tracer, meter) => {
 		put: (key, bytes, options) => observed(() => backend.put(key, bytes, options), context("put", key)),
 		get: (key) => observed(() => backend.get(key), context("get", key)),
 		delete: (key) => observed(() => backend.delete(key), context("delete", key)),
-		presignedUrl: (key, options) => observed(() => backend.presignedUrl(key, options), context("presigned_url", key))
+		presignedUrl: (key, options) => observed(() => backend.presignedUrl(key, options), context("presigned_url", key)),
+		presignedUpload: (key, options) => observed(() => backend.presignedUpload(key, options), context("presigned_upload", key))
 	};
 };
 //#endregion
@@ -113,25 +115,31 @@ const instrument = (backend, logger, tracer, meter) => {
 * application depends on must not be the one an adapter provides, which is also
 * why instrumentation is a flag on the composition rather than a wrapper.
 */
-const storage = ({ adapter, instrumented }) => instrumented !== false ? (0, _btravstack_di.Module)("InstrumentedStorage")({
-	needs: [
-		_btravstack_core.Logger,
-		_btravstack_core.Meter,
-		_btravstack_core.Tracer
-	],
-	imports: [adapter],
-	provides: [(0, _btravstack_di.Provider)(require_storage.Storage)({
-		backend: require_storage.StorageBackend,
-		logger: _btravstack_core.Logger,
-		tracer: _btravstack_core.Tracer,
-		meter: _btravstack_core.Meter
-	}, { sync: ({ backend, logger, tracer, meter }) => instrument(backend, logger, tracer, meter) })],
-	exports: [require_storage.Storage]
-}) : (0, _btravstack_di.Module)("Storage")({
-	imports: [adapter],
-	provides: [(0, _btravstack_di.Provider)(require_storage.Storage)({ backend: require_storage.StorageBackend }, { sync: ({ backend }) => backend })],
-	exports: [require_storage.Storage]
-});
+const storage = ({ adapter, instrumented }) => {
+	const healthCheck = _btravstack_di.Provider.member(_btravstack_core.HealthChecks)({ backend: require_storage.StorageBackend }, { sync: ({ backend }) => ({
+		name: "storage",
+		check: () => backend.get("btravstack:health").map(() => void 0).flatMapErrCases((matcher) => matcher.with(unthrown.P.tag("ObjectNotFound"), () => (0, unthrown.Ok)(void 0)).with(unthrown.P.tag("StorageUnavailable"), ({ reason }) => (0, unthrown.Err)(new _btravstack_core.HealthCheckFailed({ reason: `storage unavailable (${reason})` }))))
+	}) });
+	return instrumented !== false ? (0, _btravstack_di.Module)("InstrumentedStorage")({
+		needs: [
+			_btravstack_core.Logger,
+			_btravstack_core.Meter,
+			_btravstack_core.Tracer
+		],
+		imports: [adapter],
+		provides: [(0, _btravstack_di.Provider)(require_storage.Storage)({
+			backend: require_storage.StorageBackend,
+			logger: _btravstack_core.Logger,
+			tracer: _btravstack_core.Tracer,
+			meter: _btravstack_core.Meter
+		}, { sync: ({ backend, logger, tracer, meter }) => instrument(backend, logger, tracer, meter) }), healthCheck],
+		exports: [require_storage.Storage, _btravstack_core.HealthChecks]
+	}) : (0, _btravstack_di.Module)("Storage")({
+		imports: [adapter],
+		provides: [(0, _btravstack_di.Provider)(require_storage.Storage)({ backend: require_storage.StorageBackend }, { sync: ({ backend }) => backend }), healthCheck],
+		exports: [require_storage.Storage, _btravstack_core.HealthChecks]
+	});
+};
 //#endregion
 exports.ObjectNotFound = require_storage.ObjectNotFound;
 exports.PresignNotSupported = require_storage.PresignNotSupported;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-C9j3zj7r.cjs";
+import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-Cu27C7Oq.cjs";
 import { Module, Provider } from "@btravstack/di";
-import { Logger, Meter, Tracer } from "@btravstack/core";
+import { HealthChecks, Logger, Meter, Tracer } from "@btravstack/core";
 //#region src/memory.d.ts
 /**
  * The in-process adapter: a `Map`, and an honest refusal to presign.
@@ -51,6 +51,6 @@ type StorageOptions<E, N, Instrumented extends boolean> = {
  * application depends on must not be the one an adapter provides, which is also
  * why instrumentation is a flag on the composition rather than a wrapper.
  */
-declare const storage: <E, N, Instrumented extends boolean = true>({ adapter, instrumented }: StorageOptions<E, N, Instrumented>) => Module<Storage, E, Instrumented extends true ? N | Logger | Meter | Tracer : N>;
+declare const storage: <E, N, Instrumented extends boolean = true>({ adapter, instrumented }: StorageOptions<E, N, Instrumented>) => Module<Storage | HealthChecks, E, Instrumented extends true ? N | Logger | Meter | Tracer : N>;
 //#endregion
 export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-C9j3zj7r.mjs";
+import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-Cu27C7Oq.mjs";
 import { Module, Provider } from "@btravstack/di";
-import { Logger, Meter, Tracer } from "@btravstack/core";
+import { HealthChecks, Logger, Meter, Tracer } from "@btravstack/core";
 //#region src/memory.d.ts
 /**
  * The in-process adapter: a `Map`, and an honest refusal to presign.
@@ -51,6 +51,6 @@ type StorageOptions<E, N, Instrumented extends boolean> = {
  * application depends on must not be the one an adapter provides, which is also
  * why instrumentation is a flag on the composition rather than a wrapper.
  */
-declare const storage: <E, N, Instrumented extends boolean = true>({ adapter, instrumented }: StorageOptions<E, N, Instrumented>) => Module<Storage, E, Instrumented extends true ? N | Logger | Meter | Tracer : N>;
+declare const storage: <E, N, Instrumented extends boolean = true>({ adapter, instrumented }: StorageOptions<E, N, Instrumented>) => Module<Storage | HealthChecks, E, Instrumented extends true ? N | Logger | Meter | Tracer : N>;
 //#endregion
 export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { a as StorageUnavailable, i as StorageBackend, n as PresignNotSupported, r as Storage, t as ObjectNotFound } from "./storage-CRkwIhac.mjs";
 import { Module, Provider } from "@btravstack/di";
-import { ErrAsync, OkAsync } from "unthrown";
-import { Logger, Meter, SPAN_STATUS, Tracer } from "@btravstack/core";
+import { Err, ErrAsync, Ok, OkAsync, P } from "unthrown";
+import { HealthCheckFailed, HealthChecks, Logger, Meter, SPAN_STATUS, Tracer } from "@btravstack/core";
 //#region src/memory.ts
 /**
 * The in-process adapter: a `Map`, and an honest refusal to presign.
@@ -31,7 +31,8 @@ const memoryStorageBackend = () => {
 			objects.delete(key);
 			return OkAsync();
 		},
-		presignedUrl: (key) => ErrAsync(new PresignNotSupported({ key }))
+		presignedUrl: (key) => ErrAsync(new PresignNotSupported({ key })),
+		presignedUpload: (key) => ErrAsync(new PresignNotSupported({ key }))
 	};
 };
 /** The adapter as a provider, which is the shape `@btravstack/testing`'s `overridden` takes. */
@@ -94,7 +95,8 @@ const instrument = (backend, logger, tracer, meter) => {
 		put: (key, bytes, options) => observed(() => backend.put(key, bytes, options), context("put", key)),
 		get: (key) => observed(() => backend.get(key), context("get", key)),
 		delete: (key) => observed(() => backend.delete(key), context("delete", key)),
-		presignedUrl: (key, options) => observed(() => backend.presignedUrl(key, options), context("presigned_url", key))
+		presignedUrl: (key, options) => observed(() => backend.presignedUrl(key, options), context("presigned_url", key)),
+		presignedUpload: (key, options) => observed(() => backend.presignedUpload(key, options), context("presigned_upload", key))
 	};
 };
 //#endregion
@@ -112,24 +114,30 @@ const instrument = (backend, logger, tracer, meter) => {
 * application depends on must not be the one an adapter provides, which is also
 * why instrumentation is a flag on the composition rather than a wrapper.
 */
-const storage = ({ adapter, instrumented }) => instrumented !== false ? Module("InstrumentedStorage")({
-	needs: [
-		Logger,
-		Meter,
-		Tracer
-	],
-	imports: [adapter],
-	provides: [Provider(Storage)({
-		backend: StorageBackend,
-		logger: Logger,
-		tracer: Tracer,
-		meter: Meter
-	}, { sync: ({ backend, logger, tracer, meter }) => instrument(backend, logger, tracer, meter) })],
-	exports: [Storage]
-}) : Module("Storage")({
-	imports: [adapter],
-	provides: [Provider(Storage)({ backend: StorageBackend }, { sync: ({ backend }) => backend })],
-	exports: [Storage]
-});
+const storage = ({ adapter, instrumented }) => {
+	const healthCheck = Provider.member(HealthChecks)({ backend: StorageBackend }, { sync: ({ backend }) => ({
+		name: "storage",
+		check: () => backend.get("btravstack:health").map(() => void 0).flatMapErrCases((matcher) => matcher.with(P.tag("ObjectNotFound"), () => Ok(void 0)).with(P.tag("StorageUnavailable"), ({ reason }) => Err(new HealthCheckFailed({ reason: `storage unavailable (${reason})` }))))
+	}) });
+	return instrumented !== false ? Module("InstrumentedStorage")({
+		needs: [
+			Logger,
+			Meter,
+			Tracer
+		],
+		imports: [adapter],
+		provides: [Provider(Storage)({
+			backend: StorageBackend,
+			logger: Logger,
+			tracer: Tracer,
+			meter: Meter
+		}, { sync: ({ backend, logger, tracer, meter }) => instrument(backend, logger, tracer, meter) }), healthCheck],
+		exports: [Storage, HealthChecks]
+	}) : Module("Storage")({
+		imports: [adapter],
+		provides: [Provider(Storage)({ backend: StorageBackend }, { sync: ({ backend }) => backend }), healthCheck],
+		exports: [Storage, HealthChecks]
+	});
+};
 //#endregion
 export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };

package/dist/s3.cjs

@@ -63,7 +63,13 @@ const s3StorageBackend = (client, bucket) => ({
 	presignedUrl: (key, options) => (0, unthrown.fromPromise)((0, _aws_sdk_s3_request_presigner.getSignedUrl)(client, new _aws_sdk_client_s3.GetObjectCommand({
 		Bucket: bucket,
 		Key: key
-	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUrl", key, cause))
+	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUrl", key, cause)),
+	presignedUpload: (key, options) => (0, unthrown.fromPromise)((0, _aws_sdk_s3_request_presigner.getSignedUrl)(client, new _aws_sdk_client_s3.PutObjectCommand({
+		Bucket: bucket,
+		Key: key,
+		ContentType: options.contentType,
+		ContentLength: options.contentLength
+	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUpload", key, cause))
 });
 /**
 * The S3 adapter: one client, built with the scope and destroyed with it, and

package/dist/s3.d.cts

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

package/dist/s3.d.mts

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

package/dist/s3.mjs

@@ -62,7 +62,13 @@ const s3StorageBackend = (client, bucket) => ({
 	presignedUrl: (key, options) => fromPromise(getSignedUrl(client, new GetObjectCommand({
 		Bucket: bucket,
 		Key: key
-	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUrl", key, cause))
+	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUrl", key, cause)),
+	presignedUpload: (key, options) => fromPromise(getSignedUrl(client, new PutObjectCommand({
+		Bucket: bucket,
+		Key: key,
+		ContentType: options.contentType,
+		ContentLength: options.contentLength
+	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUpload", key, cause))
 });
 /**
 * The S3 adapter: one client, built with the scope and destroyed with it, and

package/dist/{storage-C9j3zj7r.d.cts → storage-Cu27C7Oq.d.cts}

@@ -13,7 +13,7 @@ declare class ObjectNotFound extends ObjectNotFound_base<{
 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";
+  readonly operation: "put" | "get" | "delete" | "presignedUrl" | "presignedUpload";
   readonly key: string;
   readonly reason: string;
 }> {}
@@ -40,6 +40,27 @@ type StorageService = {
   readonly presignedUrl: (key: string, options: {
     readonly ttlMs: number;
   }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
+  /**
+   * A URL that writes the object for `ttlMs`, without the caller holding
+   * credentials — so the bytes go from the client to the store and never
+   * through this process.
+   *
+   * **`contentType` and `contentLength` are signed, not advisory.** They are
+   * part of the signature, so a client sending different ones is refused by the
+   * store: the URL grants exactly one write, of exactly that many bytes, of
+   * exactly that type. `contentLength` is therefore required — an unsigned
+   * length would hand out an unbounded write, and there is no ceiling a
+   * presigned PUT can express other than the exact number.
+   *
+   * The application still decides every input: whether this caller may write
+   * this key, how long the URL lives, and what size it is willing to accept.
+   * The adapter computes a signature over that decision and nothing more.
+   */
+  readonly presignedUpload: (key: string, options: {
+    readonly ttlMs: number;
+    readonly contentType: string;
+    readonly contentLength: number;
+  }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
 };
 declare const Storage_base: import("@btravstack/di").PortClass<"Storage">;
 /**

package/dist/{storage-C9j3zj7r.d.mts → storage-Cu27C7Oq.d.mts}

@@ -13,7 +13,7 @@ declare class ObjectNotFound extends ObjectNotFound_base<{
 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";
+  readonly operation: "put" | "get" | "delete" | "presignedUrl" | "presignedUpload";
   readonly key: string;
   readonly reason: string;
 }> {}
@@ -40,6 +40,27 @@ type StorageService = {
   readonly presignedUrl: (key: string, options: {
     readonly ttlMs: number;
   }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
+  /**
+   * A URL that writes the object for `ttlMs`, without the caller holding
+   * credentials — so the bytes go from the client to the store and never
+   * through this process.
+   *
+   * **`contentType` and `contentLength` are signed, not advisory.** They are
+   * part of the signature, so a client sending different ones is refused by the
+   * store: the URL grants exactly one write, of exactly that many bytes, of
+   * exactly that type. `contentLength` is therefore required — an unsigned
+   * length would hand out an unbounded write, and there is no ceiling a
+   * presigned PUT can express other than the exact number.
+   *
+   * The application still decides every input: whether this caller may write
+   * this key, how long the URL lives, and what size it is willing to accept.
+   * The adapter computes a signature over that decision and nothing more.
+   */
+  readonly presignedUpload: (key: string, options: {
+    readonly ttlMs: number;
+    readonly contentType: string;
+    readonly contentLength: number;
+  }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
 };
 declare const Storage_base: import("@btravstack/di").PortClass<"Storage">;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/storage",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -67,19 +67,19 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.4.0",
-    "@btravstack/core": "0.4.0",
-    "@btravstack/di": "0.4.0",
+    "@btravstack/config": "0.6.0",
+    "@btravstack/di": "0.6.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/observability": "0.4.0"
+    "@btravstack/core": "0.6.0",
+    "@btravstack/observability": "0.6.0"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.1000.0",
     "@aws-sdk/s3-request-presigner": "^3.1000.0",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.4.0",
-    "@btravstack/core": "^0.4.0",
-    "@btravstack/di": "^0.4.0"
+    "@btravstack/config": "^0.6.0",
+    "@btravstack/core": "^0.6.0",
+    "@btravstack/di": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -90,7 +90,7 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsdown src/index.ts src/s3.ts --format cjs,esm --dts --clean",