2.2 KiB
Capability Spec: storage
- Capability:
storage - Package:
@suaveplan/storage - Change: storage-set-partial
- Date: 2026-04-28
Requirements
STORAGE-01 — setPartial is part of the abstract surface
AbstractStorage MUST declare abstract setPartial(key: string, offset: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>. Every concrete subclass MUST provide an implementation. A protected defaultSetPartial helper MUST exist as the read-modify-write reference fallback. defaultSetPartial MUST reject non-integer or negative offset values.
Verified by: src/abstract/abstract.spec-conformance.test.ts (STORAGE-01).
STORAGE-02 — sparse extension semantics
When setPartial(key, offset, bytes) is called on a non-existent key or on an existing object shorter than offset + bytes.byteLength, the storage object MUST be created/extended to length max(currentLength, offset + bytes.byteLength). Bytes in the gap [currentLength, offset) MUST be zero (0x00) on subsequent reads.
Verified by: src/abstract/abstract.spec-conformance.test.ts (STORAGE-02).
STORAGE-03 — overlap is in-place overwrite
When setPartial(key, offset, bytes) is called on a key whose existing object overlaps the written range, bytes within [offset, offset + bytes.byteLength) MUST be overwritten with bytes. Bytes outside that range MUST be preserved exactly. Zero-length writes MUST be a no-op.
Verified by: src/abstract/abstract.spec-conformance.test.ts (STORAGE-03).
STORAGE-04 — capabilities are explicit
AbstractStorage MUST expose a readonly capabilities property of shape { partialReads: boolean; partialWrites: boolean; nativeStreams: boolean; atomicWrites: boolean; contentAddressable: boolean }. Defaults MUST be all false (DEFAULT_STORAGE_CAPABILITIES). Subclasses MUST override per native support. MemoryStorage.capabilities.partialWrites MUST be true. NamespacedStorage.capabilities MUST mirror its inner storage. S3.capabilities.partialWrites MUST be false (multipart-upload native impl deferred).
Verified by: src/abstract/abstract.spec-conformance.test.ts (STORAGE-04); packages/storage/storage-s3/src/s3/s3.test.ts (setPartial describe block).