TextSearch

KIT · class · Runtime value

Optional App-side full-text index. No storage, identity, model calls or Core dependencies.

Only declared fields are indexed and only storedFields come back with a hit, so a document never leaks extra properties into search results.

Import

TypeScript

import { TextSearch } from '@jangts/agent-core/kits/search';

JavaScript

import { TextSearch } from '@jangts/agent-core/kits/search';

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/kits, @jangts/agent-core/kits/search.

Definition

class TextSearch<Document>

Type parameters

Type parameter	Constraint	Default type
Document	{ id: string }	—

Constructor

new TextSearch<Document extends { id: string; }>(registration: TextSearchOptions<Document>): TextSearch<Document>

Compile the index configuration and validate it before any document is added.

Parameter	Type	Passing	Description
registration	TextSearchOptions<Document>	Required	—

Fields of registration

Field	Type	Required	Description
indexRevision	string	Required	Read-only. App-owned revision of the field/tokenizer configuration; a change invalidates snapshots.
fields	readonly (keyof Document & string)[]	Required	Read-only. Fields that are indexed and searchable.
storedFields	readonly (keyof Document & string)[]	Required	Read-only. Fields returned in a hit; the indexed body is not implicitly returned.
tokenize	((text: string, fieldName?: string) => string[]) | undefined	Optional	Read-only. Tokenizer override; defaults to MiniSearch's default tokenizer.
boost	Readonly<Partial<Record<keyof Document & string, number>>> | undefined	Optional	Read-only. Per-field relevance multiplier; omitted fields keep the default weight.
combineWith	"AND" | "OR" | undefined	Optional	Read-only. How multiple query terms combine; defaults to the engine default (OR).

Returns: TextSearch<Document>.

Member index

Member	Purpose
restore	Static. Rebuild an index from a snapshot.
upsert	Insert or replace one document.
search	Search the index and return at most limit hits.
remove	Remove one document. Vacuum before returning so deleted terms do not survive the next serialized checkpoint.
clear	Drop every document while keeping the compiled configuration.
snapshot	Serialize the index together with the configuration used to build it.

Member details

restore

Static member.

Rebuild an index from a snapshot.

TextSearch.restore<Document extends { id: string; }>(definition: TextSearchOptions<Document>, snapshot: TextSearchSnapshot): TextSearch<Document>

Rebuild an index from a snapshot.

Type parameter	Constraint	Default type
Document	{ id: string; }	—

Parameter	Type	Passing	Description
definition	TextSearchOptions<Document>	Required	—
snapshot	TextSearchSnapshot	Required	—

Fields of definition

Field	Type	Required	Description
indexRevision	string	Required	Read-only. App-owned revision of the field/tokenizer configuration; a change invalidates snapshots.
fields	readonly (keyof Document & string)[]	Required	Read-only. Fields that are indexed and searchable.
storedFields	readonly (keyof Document & string)[]	Required	Read-only. Fields returned in a hit; the indexed body is not implicitly returned.
tokenize	((text: string, fieldName?: string) => string[]) | undefined	Optional	Read-only. Tokenizer override; defaults to MiniSearch's default tokenizer.
boost	Readonly<Partial<Record<keyof Document & string, number>>> | undefined	Optional	Read-only. Per-field relevance multiplier; omitted fields keep the default weight.
combineWith	"AND" | "OR" | undefined	Optional	Read-only. How multiple query terms combine; defaults to the engine default (OR).

Fields of snapshot

Field	Type	Required	Description
version	2	Required	Read-only. Snapshot format version; other versions are not loaded.
engine	"minisearch-7"	Required	Read-only. Engine that produced the snapshot; a different engine cannot restore it.
configurationFingerprint	string	Required	Read-only. Fingerprint of the field and tokenizer configuration that built the index.
serializedIndex	string	Required	Read-only. Serialized MiniSearch index.

Returns: TextSearch<Document>.

upsert

Instance method.

Insert or replace one document.

upsert(document: Document): void

Insert or replace one document.

Parameter	Type	Passing	Description
document	Document	Required	—

Returns: void.

search

Instance method.

Search the index and return at most limit hits.

search(options: TextSearchQuery<Document> & { query: string; }): TextSearchHit<Document>[]

Search the index and return at most limit hits.

Parameter	Type	Passing	Description
options	TextSearchQuery<Document> & { query: string; }	Required	—

Fields of options

Field	Type	Required	Description
limit	number	Required	Read-only. Maximum number of hits returned.
filter	(document: Readonly<Partial<Document>> & { id: string; }) => boolean	Required	Read-only. Required on every query; the application owns authorization and applicability.
query	string	Required	See the type definition and usage context.

Returns: TextSearchHit<Document>[].

remove

Instance method.

Remove one document.

Vacuum before returning so deleted terms do not survive the next serialized checkpoint.

remove(id: string): Promise<boolean>

Remove one document.

Vacuum before returning so deleted terms do not survive the next serialized checkpoint.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Promise<boolean>.

Awaited value: boolean.

clear

Instance method.

Drop every document while keeping the compiled configuration.

clear(): void

Drop every document while keeping the compiled configuration.

No call parameters.

Returns: void.

snapshot

Instance method.

Serialize the index together with the configuration used to build it.

snapshot(): TextSearchSnapshot

Serialize the index together with the configuration used to build it.

No call parameters.

Returns: TextSearchSnapshot.

Return value structure

Field	Type	Required	Description
version	2	Required	Read-only. Snapshot format version; other versions are not loaded.
engine	"minisearch-7"	Required	Read-only. Engine that produced the snapshot; a different engine cannot restore it.
configurationFingerprint	string	Required	Read-only. Fingerprint of the field and tokenizer configuration that built the index.
serializedIndex	string	Required	Read-only. Serialized MiniSearch index.

Examples

• TextSearch: App-side full-text index: Build a local index over declared fields; every query must supply an application filter.

First index two interface documents

Beginner · Node.js

TypeScript

import { TextSearch } from '@jangts/agent-core/kits/search';
type Document = { id: string; title: string; body: string };
const index = new TextSearch<Document>({ indexRevision: 'manual-v1', fields: ['title', 'body'], storedFields: ['title'] });
index.upsert({ id: 'workflow', title: 'Workflow', body: 'Define reusable agent nodes.' });
index.upsert({ id: 'model', title: 'Model', body: 'Bind a model provider.' });
console.log(index.search({ query: 'agent', limit: 5, filter: () => true }));

JavaScript

import { TextSearch } from '@jangts/agent-core/kits/search';
const index = new TextSearch({ indexRevision: 'manual-v1', fields: ['title', 'body'], storedFields: ['title'] });
index.upsert({ id: 'workflow', title: 'Workflow', body: 'Define reusable agent nodes.' });
index.upsert({ id: 'model', title: 'Model', body: 'Bind a model provider.' });
console.log(index.search({ query: 'agent', limit: 5, filter: () => true }));

Add access filtering, weighting, and a snapshot to the same search

Configuration · Node.js

Metadata allowed for filtering must be registered as storedFields; field filtering must rely on a trusted App identity and must not trust an identity the model claims.

TypeScript

import { TextSearch } from '@jangts/agent-core/kits/search';
type Document = { id: string; title: string; body: string; audience: string };
const options = { indexRevision: 'manual-v2', fields: ['title', 'body'] as const, storedFields: ['title', 'audience'] as const, boost: { title: 3 }, combineWith: 'AND' as const };
const index = new TextSearch<Document>(options);
index.upsert({ id: 'workflow', title: 'Agent Workflow', body: 'Define reusable nodes.', audience: 'public' });
index.upsert({ id: 'private', title: 'Agent internals', body: 'Internal notes.', audience: 'owner' });
const restored = TextSearch.restore<Document>(options, index.snapshot());
console.log(restored.search({ query: 'agent', limit: 5, filter: document => document.audience === 'public' }));
await restored.remove('workflow');

JavaScript

import { TextSearch } from '@jangts/agent-core/kits/search';
const options = { indexRevision: 'manual-v2', fields: ['title', 'body'], storedFields: ['title', 'audience'], boost: { title: 3 }, combineWith: 'AND' };
const index = new TextSearch(options);
index.upsert({ id: 'workflow', title: 'Agent Workflow', body: 'Define reusable nodes.', audience: 'public' });
index.upsert({ id: 'private', title: 'Agent internals', body: 'Internal notes.', audience: 'owner' });
const restored = TextSearch.restore(options, index.snapshot());
console.log(restored.search({ query: 'agent', limit: 5, filter: document => document.audience === 'public' }));
await restored.remove('workflow');

Related policy source

• Index fields, filtering, snapshot fingerprint, and removal

Related definitions

• TextSearchHit
• TextSearchOptions
• TextSearchQuery
• TextSearchSnapshot