@btravstack/storage

---

@btravstack/storage / index

index

Classes

ObjectNotFound

Defined in: packages/storage/src/storage.ts:11

The key is not there. Only get answers it — see delete and presignedUrl below.

Extends

• TaggedErrorInstance<"ObjectNotFound", { key: string; }>

Constructors

Constructor

new ObjectNotFound(args): ObjectNotFound;

Defined in: node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
args	object & object

Returns

ObjectNotFound

Inherited from

TaggedError("ObjectNotFound")<{
  readonly key: string;
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
_tag	readonly	"ObjectNotFound"	TaggedError("ObjectNotFound")._tag	node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2011
cause?	public	unknown	TaggedError("ObjectNotFound").cause	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
key	readonly	string	TaggedError("ObjectNotFound").key	packages/storage/src/storage.ts:12
message	public	string	TaggedError("ObjectNotFound").message	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
name	public	string	TaggedError("ObjectNotFound").name	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?	public	string	TaggedError("ObjectNotFound").stack	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

---

PresignNotSupported

Defined in: packages/storage/src/storage.ts:23

The adapter cannot mint a time-limited URL, and says so rather than pretending.

Extends

• TaggedErrorInstance<"PresignNotSupported", { key: string; }>

Constructors

Constructor

new PresignNotSupported(args): PresignNotSupported;

Defined in: node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
args	object & object

Returns

PresignNotSupported

Inherited from

TaggedError("PresignNotSupported")<{
  readonly key: string;
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
_tag	readonly	"PresignNotSupported"	TaggedError("PresignNotSupported")._tag	node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2011
cause?	public	unknown	TaggedError("PresignNotSupported").cause	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
key	readonly	string	TaggedError("PresignNotSupported").key	packages/storage/src/storage.ts:24
message	public	string	TaggedError("PresignNotSupported").message	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
name	public	string	TaggedError("PresignNotSupported").name	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?	public	string	TaggedError("PresignNotSupported").stack	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

---

Storage

Defined in: packages/storage/src/storage.ts:85

The port an application depends on.

Keys are plain strings the caller composes, tenant included: a store is an application service, and the framework has no concept of a tenant to put in a slot.

Bytes, not streams. An object here is a document. Streaming would change every signature, adapter and test to serve a case that wants a different design anyway — a stated non-goal, not an oversight.

Extends

• PortInstance<"Storage", StorageService>

Constructors

Constructor

new Storage(): Storage;

Defined in: packages/di/dist/index.d.mts:16

Returns

Storage

Inherited from

Port("Storage")<StorageService>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
[ID]	readonly	"Storage"	Port("Storage").[ID]	packages/di/dist/index.d.mts:12
[SERVICE]	readonly	StorageService	Port("Storage").[SERVICE]	packages/di/dist/index.d.mts:13
portId	readonly	"Storage"	Port("Storage").portId	packages/di/dist/index.d.mts:17

---

StorageBackend

Defined in: packages/storage/src/storage.ts:88

The port every adapter provides, and the one an application never depends on.

Extends

• PortInstance<"StorageBackend", StorageService>

Constructors

Constructor

new StorageBackend(): StorageBackend;

Defined in: packages/di/dist/index.d.mts:16

Returns

StorageBackend

Inherited from

Port("StorageBackend")<StorageService>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
[ID]	readonly	"StorageBackend"	Port("StorageBackend").[ID]	packages/di/dist/index.d.mts:12
[SERVICE]	readonly	StorageService	Port("StorageBackend").[SERVICE]	packages/di/dist/index.d.mts:13
portId	readonly	"StorageBackend"	Port("StorageBackend").portId	packages/di/dist/index.d.mts:17

---

StorageUnavailable

Defined in: packages/storage/src/storage.ts:16

The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone.

Extends

• TaggedErrorInstance<"StorageUnavailable", { key: string; operation: "put" | "get" | "delete" | "presignedUrl" | "presignedUpload"; reason: string; }>

Constructors

Constructor

new StorageUnavailable(args): StorageUnavailable;

Defined in: node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
args	object & object

Returns

StorageUnavailable

Inherited from

TaggedError("StorageUnavailable")<{
  readonly operation: "put" | "get" | "delete" | "presignedUrl" | "presignedUpload";
  readonly key: string;
  readonly reason: string;
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
_tag	readonly	"StorageUnavailable"	TaggedError("StorageUnavailable")._tag	node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2011
cause?	public	unknown	TaggedError("StorageUnavailable").cause	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
key	readonly	string	TaggedError("StorageUnavailable").key	packages/storage/src/storage.ts:18
message	public	string	TaggedError("StorageUnavailable").message	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
name	public	string	TaggedError("StorageUnavailable").name	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
operation	readonly	"put" | "get" | "delete" | "presignedUrl" | "presignedUpload"	TaggedError("StorageUnavailable").operation	packages/storage/src/storage.ts:17
reason	readonly	string	TaggedError("StorageUnavailable").reason	packages/storage/src/storage.ts:19
stack?	public	string	TaggedError("StorageUnavailable").stack	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Type Aliases

StorageOptions

type StorageOptions<E, N> = object;

Defined in: packages/storage/src/module.ts:8

Type Parameters

Type Parameter
E
N

Properties

Property	Modifier	Type	Description	Defined in
adapter	readonly	Module<StorageBackend, E, N>	The adapter module: memoryStorage() from this entry point, s3Storage() from @btravstack/storage/s3, or one an application wrote itself over StorageBackend.	packages/storage/src/module.ts:14

---

StorageService

type StorageService = object;

Defined in: packages/storage/src/storage.ts:27

Properties

Property	Modifier	Type	Description	Defined in
delete	readonly	(key) => AsyncResult<void, StorageUnavailable>	Deleting a key nobody stored is Ok: delete is idempotent, which is S3's own behaviour rather than a fiction over it.	packages/storage/src/storage.ts:35
get	readonly	(key) => AsyncResult<StoredObject, | ObjectNotFound | StorageUnavailable>	-	packages/storage/src/storage.ts:33
presignedUpload	readonly	(key, options) => 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.	packages/storage/src/storage.ts:64
presignedUrl	readonly	(key, options) => AsyncResult<string, | PresignNotSupported | StorageUnavailable>	A URL that reads the object for ttlMs, without the caller holding credentials. There is no ObjectNotFound arm: presigning is a signature computation that asks the store nothing, so a URL for an absent key is minted happily and 404s when followed. Checking would cost a HEAD per call.	packages/storage/src/storage.ts:44
put	readonly	(key, bytes, options) => AsyncResult<void, StorageUnavailable>	-	packages/storage/src/storage.ts:28

---

StoredObject

type StoredObject = object;

Defined in: packages/storage/src/storage.ts:5

One stored object: its bytes and what they are.

Properties

Property	Modifier	Type	Defined in
bytes	readonly	Uint8Array	packages/storage/src/storage.ts:6
contentType	readonly	string	packages/storage/src/storage.ts:7

Functions

memoryStorage()

function memoryStorage(): Module<StorageBackend, never, never>;

Defined in: packages/storage/src/memory.ts:48

The adapter as a module, which is the shape storage({ adapter }) takes.

Returns

Module<StorageBackend, never, never>

---

memoryStorageBackend()

function memoryStorageBackend(): StorageService;

Defined in: packages/storage/src/memory.ts:22

The in-process adapter: a Map, and an honest refusal to presign.

presignedUrl answers PresignNotSupported rather than minting a fake URL, which would be the worst kind of double — one that passes locally and fails in the deployment for a reason no test could have shown.

ponytail: no size limit, so a process storing unbounded objects grows unbounded. The upgrade path is the S3 adapter.

Returns

StorageService

---

memoryStorageProvider()

function memoryStorageProvider(): Provider<StorageBackend, never, never> & object;

Defined in: packages/storage/src/memory.ts:44

The adapter as a provider, which is the shape @btravstack/testing's overridden takes.

Returns

Provider<StorageBackend, never, never> & object

---

storage()

function storage<E, N>(__namedParameters): Module<Storage | HealthChecks, E, N>;

Defined in: packages/storage/src/module.ts:33

The storage starter: an adapter, and Storage provided from it.

storage({ adapter: s3Storage() });

Two ports, because di allows one provider per port per graph: the port an application depends on must not be the one an adapter provides, which is what lets this function be the seam.

There is no instrumented flag. Every operation is handed to whatever contributed to Observers; a graph that composed no observability has only this module's own no-op member, so it costs one call per operation and nothing else.

Type Parameters

Type Parameter
E
N

Parameters

Parameter	Type
__namedParameters	StorageOptions<E, N>

Returns

Module<Storage | HealthChecks, E, N>