Skip to content
Omnio-js
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  • open and close time 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.

Next steps

Was this page helpful?