TypeScript Types
Core TypeScript interfaces and types used throughout the pg-smart-search SDK.
TypeScript Types
SearchResult
The return type of the engine.search() method (generic over your row type T).
export interface SearchResult<T = Record<string, unknown>> {
data: T[];
pagination: {
page: number;
limit: number;
// Only computed when you explicitly pass `skipTotalCount: false` -- otherwise
// both stay undefined and hasNext is derived from a cheap limit+1 row probe.
total?: number;
totalPages?: number;
hasNext: boolean;
hasPrev: boolean;
};
// Free-form: only set on specific fallback paths (e.g. { aborted: true },
// { correctedFrom }, { transliteratedFrom }). Absent on a normal hit.
metadata?: Record<string, unknown>;
}There is no nextCursor field. For keyset pagination you take the id off the last row
in data yourself and pass it as cursor on the next call -- see
Keyset Pagination.
FilterMap
The type of SearchOptions.filters. Supports plain scalar equality (backward compatible)
and typed operator objects for richer comparisons.
type FilterScalar = string | number | boolean | Date;
interface FilterCondition {
eq?: FilterScalar;
ne?: FilterScalar;
in?: FilterScalar[];
gt?: FilterScalar;
gte?: FilterScalar;
lt?: FilterScalar;
lte?: FilterScalar;
between?: [FilterScalar, FilterScalar];
}
type FilterValue = FilterScalar | FilterCondition;
type FilterMap = Record<string, FilterValue | null | undefined>;// scalar (implicit equality) and operator forms can be mixed freely
filters: {
status: "active", // "status" = $n
age: { gte: 18, lte: 65 }, // "age" >= $n AND "age" <= $n
tags: { in: ["a", "b"] }, // "tags" = ANY($n)
}HealthStatus
The return type of the engine.health() method.
export interface HealthStatus {
healthy: boolean;
database: "ok" | "error";
cache: "ok" | "error" | "disabled";
details?: Record<string, unknown>;
}There is no vectorProvider field -- health() checks the database and the configured
cache provider, not the embedding API.
EngineMetrics
The shape returned by engine.metrics.getSummary(). engine.metrics itself is a
MetricsCollector instance, not a plain object -- call .getSummary() to get this snapshot.
export interface EngineMetrics {
totalSearches: number;
cacheHits: number;
cacheMisses: number;
cacheHitRate: number; // cacheHits / (cacheHits + cacheMisses), 0 if no data yet
dbLatencies: number[]; // last 1000 raw DB latency samples (ms)
avgDbLatencyMs: number;
providerErrors: number; // VECTOR-tier embedding API failures only
searchErrors: number; // any other failed search (DB error, validation, etc.)
strategyUsage: Record<string, number>;
}