Omnio class
Reference for the Omnio constructor, properties, and public methods.
Overview
Omnio is the facade that combines an entity store, an index, and an embedder.
import { Omnio } from "omnio";
const omnio = new Omnio({
entity,
index,
embedder,
});
await omnio.open();
Every method accepts an AbortSignal, either as signal in its input object or as the last argument. close() aborts running operations through the lifecycle signal.
Constructor
new Omnio(options: OmnioOptions)
| Option | Type | Required | Description |
|---|---|---|---|
entity |
IOmnioEntityBuilder |
Yes | A unikvs builder configured through persist(). |
index |
IObjectIndex |
Yes | Metadata and vector index. |
embedder |
IEmbedder |
Yes | Embedding runtime. |
purgeGracePeriodMs |
number |
No | Delay before entity bytes are physically deleted. Defaults to 60000. |
The constructor calls entity.build() and injects the checksum middleware. Inputs are validated with valibot and throw ValiError when invalid.
Properties
isOpen
readonly isOpen: boolean
true when both the entity store and the index are open.
Lifecycle
open
open(signal?: AbortSignal): Promise<void>
Opens the entity store and the index. Opening the index applies migrations and marks objects whose embedding model changed as dirty.
Calling open() on an open instance does nothing. When signal is omitted, the operation times out after 30 seconds.
close
close(signal?: AbortSignal): Promise<void>
Aborts running operations, waits for background work, and closes the index and entity store.
When signal is omitted, the operation times out after 30 seconds. If closing the index or entity store fails, it throws, and a later close() can retry.
Writing objects
putObject
putObject<TUserMetadata>(input: PutObjectInput<TUserMetadata>): Promise<OmnioObject<TUserMetadata>>
Saves an object and overwrites an existing key.
| Input | Type | Required | Default |
|---|---|---|---|
key |
string | OmnioKey |
Yes | - |
data |
Uint8Array | Blob | ReadableStream<Uint8Array> |
Yes | - |
contentType |
string |
Yes | - |
description |
string |
No | - |
tags |
readonly string[] |
No | [] |
userMetadata |
TUserMetadata |
No | {} |
embedding |
Float32Array |
No | - |
embed |
boolean |
No | true |
signal |
AbortSignal |
No | - |
When description is present, embedding is absent, and embed is not false, Omnio generates an embedding for the description.
An overwrite creates a new entityId. It keeps createdAt and sets updatedAt to the current time.
copyObject
copyObject<TUserMetadata>(
sourceKey: string | OmnioKey,
destinationKey: string | OmnioKey,
signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>
Copies bytes and metadata. The destination gets a new entityId. An existing destination is overwritten and keeps its creation time.
A missing source returns null. The same key returns the original object.
renameObject
renameObject<TUserMetadata>(
sourceKey: string | OmnioKey,
destinationKey: string | OmnioKey,
signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>
Changes the key without moving the bytes and keeps the same entityId. An existing destination is overwritten and its old entity is deleted in the background.
A missing source returns null. The same key returns the original object.
updateObjectMetadata
updateObjectMetadata<TUserMetadata>(
input: UpdateObjectMetadataInput<TUserMetadata>,
): Promise<OmnioObject<TUserMetadata> | null>
Updates only mutable metadata. A missing key returns null.
| Input | Type | Description |
|---|---|---|
key |
string | OmnioKey |
Key to update. |
contentType |
string |
Omit to leave unchanged. |
description |
string |
Omit to leave unchanged. |
tags |
readonly string[] |
Omit to leave unchanged. An empty array removes all tags. |
userMetadata |
TUserMetadata |
Omit to leave unchanged. |
signal |
AbortSignal |
Abort signal. |
Size, hash, creation time, entityId, and the embedding cannot be updated. Changing the description does not rebuild the embedding.
Reading objects
getObject
getObject(key: string | OmnioKey, signal?: AbortSignal): Promise<Uint8Array | null>
Returns the entity bytes. Returns null when the key is missing or deleted.
When the index records hashAlgorithm: "sha256", the checksum is verified before the bytes are returned. A record with missing bytes throws EntityMissingError.
streamObject
streamObject(
key: string | OmnioKey,
signal?: AbortSignal,
): Promise<IValueStream<Uint8Array> | null>
Returns the entity as a stream. Returns null when the key is missing or deleted.
The checksum is verified at the end of the stream. It is not verified if the stream is cancelled or not fully consumed. Dispose of the stream on the caller side.
headObject
headObject<TUserMetadata>(
key: string | OmnioKey,
signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>
headObject<TUserMetadata, const TSelect extends HeadObjectSelect>(
key: string | OmnioKey,
options: HeadObjectOptions<TSelect>,
): Promise<Pick<OmnioObject<TUserMetadata>, SelectedHeadObjectField<TSelect>> | null>
Returns metadata, or null when the key is missing.
Omitting select returns every field. When select is provided, only fields set to true are returned.
const head = await omnio.headObject("notes/a.txt", {
select: { key: true, size: true, tags: true },
});
hasObject
hasObject(key: string | OmnioKey, signal?: AbortSignal): Promise<boolean>
Returns whether the index has metadata for the key. It does not touch entity storage. A deleted object returns false.
listObjects
listObjects<TUserMetadata>(
options?: {
limit?: number;
cursor?: string | null;
filter?: MetadataFilter;
},
signal?: AbortSignal,
): Promise<IObjectIndex.ListResult<TUserMetadata>>
Returns active objects in ascending key order. The default limit is 100. When nextCursor is not null, pass it to the next call.
type ListResult<TUserMetadata> = {
items: readonly OmnioObject<TUserMetadata>[];
nextCursor: string | null;
};
searchObjects
searchObjects<TUserMetadata>(
input: SearchObjectsInput,
): Promise<IndexedObject<TUserMetadata>[]>
Runs a semantic search and returns results in descending score order.
| Input | Type | Default |
|---|---|---|
query |
{ text } | { image, mimeType? } | { vector } |
- |
topK |
number |
20 |
minScore |
number |
- |
filter |
MetadataFilter |
- |
includeEmbedding |
boolean |
true |
signal |
AbortSignal |
- |
query.text and query.image are embedded with the current embedder, and only stored vectors with the same embedder.info.name are considered. query.vector does not filter by model name.
searchObjects uses the index’s default similarity, which is cosine similarity. To use L2 distance, call IObjectIndex.search directly.
deleteObject
deleteObject(key: string | OmnioKey, signal?: AbortSignal): Promise<boolean>
Logically deletes the object. Returns true when the object was marked deleted and false when the key did not exist.
The entity bytes are physically deleted in the background after purgeGracePeriodMs.
Reindexing
reindexObject
reindexObject<TUserMetadata>(
key: string | OmnioKey,
signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>
Rebuilds the description embedding with the current embedder. A missing key returns null. If there is no description, nothing changes and the current object is returned.
Cancellation and timeouts
openandclosetime out after 30 seconds when no signal is passed.- Other methods combine the caller’s signal with the lifecycle signal used by
close. - An aborted operation fails with the signal’s reason, such as
OperationAbortedError.