Entity storage
Reference for IOmnioEntity, IOmnioEntityBuilder, and the unikvs integration.
Role
Entity storage keeps object bytes under an entityId. Omnio stores the key-to-entity mapping in the index and reads the bytes from entity storage.
IOmnioEntity
interface IOmnioEntity {
open(options?: { signal?: AbortSignal }): Promise<void>;
close(options?: { signal?: AbortSignal }): Promise<void>;
has(key: string, options?: { signal?: AbortSignal }): Promise<boolean>;
get(key: string, options?: IOmnioEntityReadOptions): Promise<Uint8Array>;
set(
key: string,
value: Uint8Array | ReadableStream<Uint8Array>,
options?: { vars?: IOmnioEntityVariables; signal?: AbortSignal },
): Promise<void>;
copy(key: string, destinationKey: string, options?: { signal?: AbortSignal }): Promise<void>;
delete(key: string, options?: { signal?: AbortSignal }): Promise<void>;
stream(key: string, options?: IOmnioEntityReadOptions): Promise<IValueStream<Uint8Array>>;
}
| Method | Description |
|---|---|
open |
Opens storage. |
close |
Closes storage. |
has |
Returns whether a key exists. |
get |
Returns bytes. Missing keys throw. |
set |
Saves bytes or a stream. |
copy |
Copies bytes to another key. |
delete |
Deletes bytes. Missing keys are ignored. |
stream |
Returns a byte stream. |
get and stream accept vars. Omnio passes the expected SHA-256 value there, and the storage middleware verifies it on read.
IOmnioEntityBuilder
interface IOmnioEntityBuilder {
build(options?: UniKvsBuildOptions): IOmnioEntity;
}
Omnio calls build() in its constructor and passes checksum middleware through beforeAll. Implementations must forward the options to unikvs build().
type EntityMapping = Record<string, unikvs.Value<Uint8Array>>;
const entity = new unikvs.Builder<EntityMapping>().persist(new NodeFs("./data/entities"));
unikvs stores
| Package | Storage | Use case |
|---|---|---|
@unikvs/memory |
Memory | Tests and prototypes. |
@unikvs/fs.node |
Node.js file system | Node.js persistence. |
@unikvs/opfs |
Origin Private File System | Browser persistence. |
NodeFs takes a root directory. Opfs takes a root name inside OPFS.
import { NodeFs } from "@unikvs/fs.node";
const entity = new unikvs.Builder<EntityMapping>().persist(new NodeFs("./data/entities"));
import { Opfs } from "@unikvs/opfs";
const entity = new unikvs.Builder<EntityMapping>().persist(new Opfs("omnio-entities"));
Entity immutability
Omnio never changes the bytes for an existing entityId.
putObjectandcopyObjectcreate a newentityId.renameObjectkeeps the sameentityId.- An overwrite also creates a new
entityId.
Changing the bytes for an entityId outside Omnio can break checksum verification or corrupt an in-flight stream.
Checksums
Omnio injects SHA-256 middleware into the entity builder. It records the hash during a write and stores hash and hashAlgorithm: "sha256" in the index.
Reads behave as follows.
getObject: verifies the checksum before returning bytes. A mismatch throwsChecksumMismatchError.streamObject: verifies at the end of the stream. A cancelled stream is not verified.
If the entity builder already contains another ChecksumSha256, only the instance injected by Omnio is used.
Streams
IOmnioEntity.stream returns IValueStream<Uint8Array>. Consume or dispose of streams returned by streamObject.
const stream = await omnio.streamObject("large/file.bin");
if (stream !== null) {
for await (const chunk of stream) {
// Process the chunk.
}
}