Skip to main content
@moss-dev/moss / MossClient

MossClient

MossClient - Async-first semantic search client for vector similarity operations. All mutations (createIndex, addDocs, deleteDocs) are async operations that run server-side and poll until complete.

Example

Constructors

Constructor

new MossClient(projectId, projectKey): MossClient
Creates a new MossClient instance.

Parameters

Returns

MossClient

Constructor (custom authenticator)

new MossClient(projectId, authenticator): MossClient
Creates a new MossClient instance with a custom authenticator. Use this pattern from browser or untrusted clients where the projectKey must never be embedded in shipped code. See the Custom Authenticator guide for details.

Parameters

Methods

createIndex()

createIndex(indexName, docs, options?): Promise<MutationResult>
Creates a new index with the provided documents via async upload. Handles the full flow: init, upload, build, then poll until complete. Returns when the index is ready. When all documents have pre-computed embeddings, they are serialized as raw float32 in the binary upload. When no documents have embeddings, the server generates embeddings in batches (dimension=0 flow). Mixed documents (some with embeddings, some without) are rejected.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the index is ready.

Throws

If the index already exists or creation fails.

Example


getIndex()

getIndex(indexName): Promise<IndexInfo>
Gets information about a specific index.

Parameters

Returns

Promise<IndexInfo> Promise that resolves to IndexInfo object.

Throws

If the index does not exist.

Example


listIndexes()

listIndexes(): Promise<IndexInfo[]>
Lists all available indexes.

Returns

Promise<IndexInfo[]> Promise that resolves to array of IndexInfo objects.

Example


deleteIndex()

deleteIndex(indexName): Promise<boolean>
Deletes an index and all its data.

Parameters

Returns

Promise<boolean> Promise that resolves to true if successful.

Throws

If the index does not exist.

Example


addDocs()

addDocs(indexName, docs, options?): Promise<MutationResult>
Adds or updates documents in an index asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example


deleteDocs()

deleteDocs(indexName, docIds, options?): Promise<MutationResult>
Deletes documents from an index by their IDs asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example


getJobStatus()

getJobStatus(jobId): Promise<JobStatusResponse>
Gets the current status of an async job.

Parameters

Returns

Promise<JobStatusResponse> Promise that resolves to JobStatusResponse with progress details.

Example


getDocs()

getDocs(indexName, options?): Promise<DocumentInfo[]>
Retrieves documents from an index.

Parameters

Returns

Promise<DocumentInfo[]> Promise that resolves to array of documents.

Throws

If the index does not exist.

Example


loadIndex()

loadIndex(indexName, options?): Promise<string>
Downloads an index from the cloud into memory for fast local querying. How it works:
  1. Fetches the index assets from the cloud
  2. Loads the embedding model for generating query embeddings
  3. Executes a local similarity match between the query embedding and the retrieved index.
Why use this? An index must be loaded before you can query() it. Once loaded, queries run entirely in-memory (~1-10ms). Reload behavior: If the index is already loaded, calling loadIndex() again will:
  • Stop any existing auto-refresh polling
  • Download a fresh copy from the cloud
  • Replace the in-memory index
Auto-refresh (optional): Enable autoRefresh: true to periodically poll the cloud for updates. When a newer version is detected, the index is automatically hot-swapped without interrupting queries.

Parameters

Returns

Promise<string> Promise that resolves to the index name.

Throws

If the index does not exist in the cloud or loading fails.

Example


query()

query(indexName, query, options?): Promise<SearchResult>
Performs a semantic similarity search against a loaded index. Call loadIndex() first; queries then run entirely in-memory. Metadata filtering is supported on loaded indexes.

Parameters

Returns

Promise<SearchResult> Promise that resolves to SearchResult with matching documents.

Throws

If the specified index does not exist.

Example


getAuthToken()

getAuthToken(): Promise<AuthToken>
Returns a short-lived auth token for the current project. This is primarily useful for custom-authenticator patterns, where your backend mints tokens for untrusted clients instead of shipping the projectKey. See the Custom Authenticator guide for details.

Returns

Promise<AuthToken> Promise that resolves to an AuthToken containing the token string and its expiresIn lifetime in seconds.

Example


session()

session(indexName, modelId?): Promise<SessionIndex>
Creates or resumes a local-first SessionIndex. If a cloud index with the given name already exists it is loaded into the session (no re-embedding); otherwise the session starts empty. The indexName is also the target when pushIndex() is called. Requires a client constructed with a project key. Calling session() on a client built with a custom IAuthenticator throws.

Parameters

Returns

Promise<SessionIndex>

Example