35 lines
2.2 KiB
Markdown
35 lines
2.2 KiB
Markdown
# 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).
|