@duckedup/nidus 0.2.0 → 0.53.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * A typed attribute value, externally tagged exactly as `nidus` serde-encodes
- * `Value` on the wire: `{ Str }`, `{ Int }`, `{ Bool }`, `{ List }`, or the bare
- * string `"Null"`.
+ * `Value` on the wire: `{ Str }`, `{ Int }`, `{ Bool }`, `{ List }`, `{ Float }`,
+ * `{ DateTime }` (epoch milliseconds, UTC), or the bare string `"Null"`.
  *
  * `Null` is distinct from an absent key: absence means "not set / not indexed",
  * `Null` means "set, and empty/none".
@@ -14,15 +14,20 @@ type Value = {
     Bool: boolean;
 } | {
     List: string[];
+} | {
+    Float: number;
+} | {
+    DateTime: number;
 } | "Null";
 /**
  * What callers may pass anywhere a {@link Value} is expected: either an
  * explicitly-tagged `Value` (from the `v.*` helpers) or a plain JS scalar that
- * the SDK normalizes — `string → Str`, `boolean → Bool`, integer `number → Int`,
- * `string[] → List`, `null → Null`. A non-integer number throws (the store has no
- * float attribute type; floats belong in the vector, not in attrs).
+ * the SDK normalizes — `string → Str`, `boolean → Bool`, `string[] → List`,
+ * `Date → DateTime`, `null → Null`, and a `number` to `Int` or `Float` by
+ * `Number.isInteger` (JS has no int type, so the value has to decide; use
+ * {@link v.float} to pin a whole-numbered field to `Float`).
  */
-type AttrInput = Value | string | number | boolean | string[] | null;
+type AttrInput = Value | string | number | boolean | string[] | Date | null;
 /** A document: caller-supplied `id`, an optional embedding, and typed metadata. */
 interface NidusRecord {
     id: string;
@@ -49,6 +54,8 @@ type Predicate = {
     Ne: [string, Value];
 } | {
     Glob: [string, string];
+} | {
+    IGlob: [string, string];
 } | {
     In: [string, Value[]];
 } | {
@@ -61,6 +68,30 @@ type Predicate = {
     Gt: [string, Value];
 } | {
     Ge: [string, Value];
+} | {
+    Contains: [string, Value];
+} | {
+    NotContains: [string, Value];
+} | {
+    ContainsAny: [string, Value[]];
+} | {
+    All: Predicate[];
+} | {
+    Any: Predicate[];
+} | {
+    Not: Predicate;
+}
+/** The one three-element leaf: key, text, and the edit budget. */
+ | {
+    Fuzzy: [string, string, number];
+} | {
+    ContainsAllTokens: [string, string];
+} | {
+    ContainsAnyToken: [string, string];
+} | {
+    ContainsTokenSequence: [string, string];
+} | {
+    Regex: [string, string];
 };
 /**
  * A conjunction (AND) of predicates. On the wire `Filter` is a newtype over
@@ -74,9 +105,52 @@ interface Hit {
     id: string;
     score: number;
     attrs: Record<string, DecodedValue>;
+    /** Why this hit matched — present only when the query asked to `explain` or highlight. */
+    annotations?: Annotations;
+}
+/** One fusion leg's own view of a hit: its rank in that leg (0-based) and that leg's score. */
+interface LegScore {
+    rank: number;
+    score: number;
+}
+/** One BM25 clause's contribution to a hit's text score. Only matched clauses appear. */
+interface ClauseScore {
+    field: string;
+    score: number;
+}
+/**
+ * An excerpt of a field's stored text plus the ranges a query term matched. The server
+ * reports UTF-8 **byte** offsets; the SDK converts them to JS string indices (UTF-16 code
+ * units), so `text.slice(...span)` is the matched term even when the excerpt is not ASCII.
+ */
+interface Fragment {
+    text: string;
+    spans: [number, number][];
 }
-/** A {@link Value} decoded back to a plain JS value. */
-type DecodedValue = string | number | boolean | string[] | null;
+/** The fragments found in one full-text field. */
+interface Highlight {
+    field: string;
+    fragments: Fragment[];
+}
+/**
+ * Why a hit matched. Every part is opt-in and absent when it carries nothing, so a hit
+ * annotated by `explain` alone has no `highlights` key.
+ */
+interface Annotations {
+    /** The vector leg's rank and score, on a hybrid hit that leg returned. */
+    vector?: LegScore;
+    /** The BM25 leg's rank and combined text score, on a hybrid hit that leg returned. */
+    text?: LegScore;
+    /** Each matched clause's own BM25 score, in query order. */
+    clauses?: ClauseScore[];
+    /** Highlighted fragments, one entry per clause field that had a match. */
+    highlights?: Highlight[];
+}
+/**
+ * A {@link Value} decoded back to a plain JS value. A `DateTime` comes back as a
+ * `Date`, not a number, so a decoded `attrs` map re-encodes to what it came from.
+ */
+type DecodedValue = string | number | boolean | string[] | Date | null;
 /** On-disk footprint, mirroring `FootprintDto`. */
 interface Footprint {
     rows: number;
@@ -104,41 +178,242 @@ interface Stats {
     collections: string[];
     footprint: Footprint;
 }
+/**
+ * Which attrs the returned hits carry. Omit both for every attr (the default).
+ * Sending both is a `400` — the server refuses rather than picking one.
+ */
+interface ProjectionOptions {
+    /** Return only these attrs. A named attr the record lacks is simply absent. */
+    includeAttributes?: string[];
+    /** Return every attr but these. */
+    excludeAttributes?: string[];
+}
+/**
+ * Recency decay over a timestamp attribute. The penalty is *subtracted* from the base
+ * score — `score = base - lambda * (1 - decay ^ (age / scale))` — so it stays meaningful
+ * for a metric whose scores are negative or unbounded (Euclidean, dot product, BM25).
+ */
+interface Decay {
+    /** The timestamp attribute: a `DateTime`, or an `Int` of epoch milliseconds. */
+    field: string;
+    /**
+     * "Now". Ages are measured back from here rather than from the wall clock, so the same
+     * query against an unchanged store ranks the same way twice. A `Date` or epoch ms.
+     */
+    origin: Date | number;
+    /** Age in milliseconds at which the factor equals `decay` (default: 7 days). */
+    scale?: number;
+    /** Factor reached at exactly `scale` old, in `(0, 1)`; the default `0.5` makes it a half-life. */
+    decay?: number;
+    /** Score a fully-decayed hit gives up (default `1`). */
+    lambda?: number;
+    /** Factor for a record whose `field` is missing or not a timestamp. Defaults to `1` — no penalty. */
+    missing?: number;
+}
+/**
+ * A ranking expression layered over the store's distance metric. Omitting it is the bare
+ * metric — the ranking nidus has always returned.
+ */
+type RankBy = {
+    decay: Decay;
+};
+/**
+ * Cap how many hits may carry any one value of an attribute — "at most 2 hits per file".
+ * Records *missing* the attribute form one shared group, so an absent value cannot evade
+ * the cap. Approximate: it thins the ranking rather than searching deeper to refill it.
+ */
+interface LimitPer {
+    field: string;
+    max: number;
+}
+/**
+ * Sort a {@link NidusClient.list} by an attribute instead of storage order. Values of
+ * another type, unorderable ones (`null`/lists/`NaN`), and records missing the attribute
+ * sort into one trailing bucket, which stays trailing in both directions.
+ */
+interface OrderBy {
+    field: string;
+    descending?: boolean;
+}
+/** Ranking knobs shared by {@link NidusClient.search} and {@link NidusClient.textSearch}. */
+interface RankingOptions {
+    rankBy?: RankBy;
+    limitPer?: LimitPer;
+}
+/** How several {@link TextClause}s fold into one text score. */
+type FtsCombine = "Sum" | "Max";
+/** One clause of a multi-field text query: an indexed field and the query text for it. */
+interface TextClause {
+    field: string;
+    query: string;
+}
+/** How much text a highlight carries. `fragmentChars` is a character budget, not bytes. */
+interface HighlightOptions {
+    /** Most fragments returned per field (default `1`). */
+    maxFragments?: number;
+    /** Characters per fragment (default `160`): leading context, then the match and its tail. */
+    fragmentChars?: number;
+}
+/** Annotation knobs shared by {@link NidusClient.textSearch} and {@link NidusClient.hybridSearch}. */
+interface AnnotationOptions {
+    /** Report each leg's and each matched clause's own score in a hit's `annotations`. */
+    explain?: boolean;
+    /**
+     * Return highlighted fragments; `true` takes the defaults. Highlighting reads the
+     * stored text, so it still works on a field the projection dropped.
+     */
+    highlight?: boolean | HighlightOptions;
+}
 /** Options for {@link NidusClient.search}. An empty/omitted `scope` searches every collection. */
-interface SearchOptions {
+interface SearchOptions extends ProjectionOptions, RankingOptions {
     query: number[];
     scope?: string[];
     topK?: number;
+    /** Skip this many top-ranked hits, for pagination. `offset + topK` may not exceed 10000. */
+    offset?: number;
     minScore?: number;
     filter?: Filter;
+    /**
+     * Force the exact scan for this query, bypassing any ANN index and the
+     * quantized first pass. The index stays in place for every other query.
+     */
+    exact?: boolean;
 }
-/** Options for {@link NidusClient.textSearch} (BM25). */
-interface TextSearchOptions {
+/**
+ * The two accepted spellings of a text query: one `field` plus its `query`, or a list of
+ * `clauses` each carrying its own text. Sending both, or an empty list, is a `400` — an
+ * empty result would otherwise read as "no matches" rather than "no query".
+ */
+type TextQuerySpelling = {
     field: string;
     query: string;
+    clauses?: never;
+    combine?: never;
+} | {
+    clauses: TextClause[];
+    combine?: FtsCombine;
+    field?: never;
+    query?: never;
+};
+/** The knobs of {@link TextSearchOptions} that do not name what to search. */
+interface TextSearchBase extends ProjectionOptions, RankingOptions, AnnotationOptions {
     scope?: string[];
     topK?: number;
+    /** Skip this many top-ranked hits, for pagination. */
+    offset?: number;
     /** A raw BM25 score floor (not cosine). */
     minScore?: number;
     filter?: Filter;
 }
-/** Options for {@link NidusClient.hybridSearch} (vector + BM25 fused via RRF). */
-interface HybridSearchOptions {
-    vector: number[];
+/** Options for {@link NidusClient.textSearch} (BM25). */
+type TextSearchOptions = TextSearchBase & TextQuerySpelling;
+/**
+ * One entry of {@link NidusClient.setFtsSchema}'s `fields`: the attribute to index
+ * plus any BM25/analyzer knobs to override. Every knob is optional — omit them all
+ * (or pass the bare field name instead) for the server's defaults, `k1 = 1.2`,
+ * `b = 0.75`, US English, no folding, no token-length cap.
+ */
+interface FtsField {
+    /** The attribute to full-text index. */
+    field: string;
+    /** BM25 term-frequency saturation (default `1.2`). */
+    k1?: number;
+    /** BM25 length normalization, `0`–`1` (default `0.75`). */
+    b?: number;
+    /** Analyzer language; `"english"` is the only one today. */
+    language?: string;
+    /** Fold Latin diacritics to ASCII, so `café` and `cafe` share a term. */
+    asciiFolding?: boolean;
+    /** Drop tokens longer than this many characters (default: no cap). */
+    maxTokenLen?: number;
+}
+/** {@link TextQuerySpelling} for hybrid search, whose single form spells the text `text`. */
+type HybridQuerySpelling = {
     field: string;
     text: string;
+    clauses?: never;
+    combine?: never;
+} | {
+    clauses: TextClause[];
+    combine?: FtsCombine;
+    field?: never;
+    text?: never;
+};
+/** The knobs of {@link HybridSearchOptions} that do not name what the text leg searches. */
+interface HybridSearchBase extends AnnotationOptions {
+    vector: number[];
     scope?: string[];
     topK?: number;
+    /** Skip this many hits of the *fused* ranking, for pagination. */
+    offset?: number;
     filter?: Filter;
     rrfK?: number;
     candidates?: number;
+    /** Weight on the vector leg's RRF contribution. Both weights at `1` is plain fusion. */
+    vectorWeight?: number;
+    /** Weight on the BM25 leg's RRF contribution (default `1`). */
+    textWeight?: number;
 }
+/** Options for {@link NidusClient.hybridSearch} (vector + BM25 fused via RRF). */
+type HybridSearchOptions = HybridSearchBase & HybridQuerySpelling;
 /** Options for {@link NidusClient.list} (metadata-only, paginated). */
-interface ListOptions {
+interface ListOptions extends ProjectionOptions {
     scope?: string[];
     offset?: number;
     limit?: number;
     filter?: Filter;
+    /** Sort by an attribute instead of storage order. */
+    orderBy?: OrderBy;
+}
+/** Options for {@link NidusClient.aggregate}. An empty/omitted `scope` covers every collection. */
+interface AggregateOptions {
+    scope?: string[];
+    filter?: Filter;
+    /** Attributes to sum. A missing or non-numeric value is skipped, not counted as zero. */
+    sum?: string[];
+    /**
+     * Report one {@link Group} per distinct value of this attribute, alongside the
+     * whole-scope totals. An empty string is a `400`, not "no grouping" — omit it instead.
+     */
+    groupBy?: string;
+}
+/** What {@link NidusClient.aggregate} answers: the match count plus one sum per named field. */
+interface Aggregation {
+    count: number;
+    /** One entry per requested `sum` field, decoded from its tagged `Int`/`Float`. */
+    sums: Record<string, number>;
+    /** One row per distinct `groupBy` value, largest first. Absent when none was asked for. */
+    groups?: Group[];
+    /** Distinct values outran the server's cap and later ones were dropped. */
+    groupsTruncated?: boolean;
+}
+/**
+ * One distinct `groupBy` value with the aggregates over just its records. `value` is `null`
+ * for the records missing the attribute — a different group from those holding a `null`.
+ */
+interface Group {
+    value: DecodedValue | null;
+    count: number;
+    sums: Record<string, number>;
+}
+/**
+ * Options for {@link NidusClient.batchSearch}: several vector queries answered in one
+ * round-trip, capped at 16 by the server. Each entry is an ordinary {@link SearchOptions}.
+ */
+interface BatchSearchOptions {
+    queries: SearchOptions[];
+    /** Merge the per-query rankings into ONE list instead of returning them side by side. */
+    fuse?: BatchFuse;
+}
+/**
+ * Cross-query Reciprocal Rank Fusion — the same fusion `hybridSearch` runs, over N query
+ * legs. `weights` must be empty or exactly as long as `queries`; the server refuses a short
+ * list rather than silently re-weighting the wrong leg.
+ */
+interface BatchFuse {
+    rrfK?: number;
+    weights?: number[];
+    topK?: number;
 }
 /**
  * Options for {@link NidusClient.remember} (text-native ingest). The server
@@ -212,16 +487,40 @@ declare class NidusClient {
     deleteWhere(name: string, filter: Filter): Promise<number>;
     /** Fetch every record in a collection (attrs decoded to plain JS values). */
     records(name: string): Promise<DecodedRecord[]>;
-    /** Declare the full-text-indexed attribute fields for a collection. */
-    setFtsSchema(name: string, fields: string[]): Promise<void>;
+    /**
+     * Declare the full-text-indexed attribute fields for a collection. A bare string
+     * takes the server's BM25/analyzer defaults; an {@link FtsField} object tunes `k1`,
+     * `b`, and the analyzer for that field alone.
+     */
+    setFtsSchema(name: string, fields: (string | FtsField)[]): Promise<void>;
     /** Vector (cosine) nearest-neighbour search. Empty `scope` searches all collections. */
     search(opts: SearchOptions): Promise<Hit[]>;
-    /** BM25 full-text search over one indexed field. */
+    /**
+     * BM25 full-text search over one indexed field, or over a `clauses` list folded by
+     * `combine` (`"Sum"` unless said otherwise). Naming the fields both ways is a `400`.
+     */
     textSearch(opts: TextSearchOptions): Promise<Hit[]>;
-    /** Hybrid search: fuse a vector query and a BM25 text query via RRF. */
+    /**
+     * Hybrid search: fuse a vector query and a BM25 text query via RRF. The text leg takes
+     * the same single-field / `clauses` choice as {@link NidusClient.textSearch}.
+     */
     hybridSearch(opts: HybridSearchOptions): Promise<Hit[]>;
     /** Metadata-only listing (no vector), paginated by `offset`/`limit`. */
     list(opts?: ListOptions): Promise<Hit[]>;
+    /**
+     * Count the records matching a filter and sum the named attributes. Answered from the
+     * in-RAM index alone — no record is built and no vector is read.
+     */
+    aggregate(opts?: AggregateOptions): Promise<Aggregation>;
+    /**
+     * Answer several vector queries in one round-trip (16 max). Returns one ranking per
+     * query in request order, or — with `opts.fuse` — a single array holding the one fused
+     * ranking, so the return shape is uniform either way.
+     *
+     * The server validates the whole batch before running any leg, so a malformed query
+     * fails the call rather than returning a partial answer that cannot be told apart.
+     */
+    batchSearch(opts: BatchSearchOptions): Promise<Hit[][]>;
     /**
      * Embed `text` and upsert it under `id` in `collection` (idempotent on `id`).
      * With `opts.mode === "summarize"` the server summarizes first, embeds the
@@ -242,6 +541,8 @@ declare class NidusClient {
     compact(): Promise<void>;
     /** Run a search-family request and decode the resulting hits' attrs. */
     private searchRequest;
+    /** One wire hit into a {@link Hit}. Shared so every search surface decodes identically. */
+    private decodeHit;
     /** Issue a request and parse a JSON body, mapping a non-2xx to {@link NidusError}. */
     private request;
     /** The bare transport: headers, auth, timeout, and transport-error mapping. */
@@ -275,6 +576,11 @@ declare const f: {
     readonly ne: (key: string, value: AttrInput) => Predicate;
     /** `attrs[key]` is a `Str` matching the glob pattern (`*`, `?`, `[..]`). */
     readonly glob: (key: string, pattern: string) => Predicate;
+    /**
+     * {@link f.glob}, ignoring **ASCII** case on both sides — `"Src/*"` matches
+     * `"src/main.rs"`. Non-ASCII is not folded (`É` does not match `é`).
+     */
+    readonly iglob: (key: string, pattern: string) => Predicate;
     /** `attrs[key]` equals one of `values`. */
     readonly in: (key: string, values: AttrInput[]) => Predicate;
     /** `attrs[key]` is present and equals none of `values`. */
@@ -287,27 +593,69 @@ declare const f: {
     readonly gt: (key: string, value: AttrInput) => Predicate;
     /** `attrs[key] >= value` (same-type, orderable). */
     readonly ge: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is a `List` containing `value` (whole-element, not substring). */
+    readonly contains: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is a present `List` not containing `value`. */
+    readonly notContains: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is a `List` sharing at least one element with `values`. */
+    readonly containsAny: (key: string, values: AttrInput[]) => Predicate;
+    /** Every sub-predicate holds. `all()` is `true`. */
+    readonly all: (...preds: Predicate[]) => Predicate;
+    /** At least one sub-predicate holds. `any()` is `false`. */
+    readonly any: (...preds: Predicate[]) => Predicate;
+    /**
+     * The sub-predicate does not hold. Differs from {@link f.ne} on an absent key:
+     * `not(eq(k, v))` matches a record with no `k`, `ne(k, v)` does not.
+     */
+    readonly not: (pred: Predicate) => Predicate;
+    /**
+     * `attrs[key]` is within `maxEdits` Levenshtein edits of `text`, ASCII-case-folded on
+     * both sides; a `List` matches if any element does. The only three-element predicate.
+     * A `maxEdits` above 8 is refused by the server, not clamped.
+     */
+    readonly fuzzy: (key: string, text: string, maxEdits: number) => Predicate;
+    /**
+     * Every token of `text` appears among `attrs[key]`'s tokens, in any order. Tokens are
+     * ASCII-case-folded runs of alphanumerics; a `List` matches if any single element does.
+     */
+    readonly containsAllTokens: (key: string, text: string) => Predicate;
+    /** At least one token of `text` appears among `attrs[key]`'s tokens. Empty never matches. */
+    readonly containsAnyToken: (key: string, text: string) => Predicate;
+    /** `text`'s tokens appear consecutively and in order — a phrase match. */
+    readonly containsTokenSequence: (key: string, text: string) => Predicate;
+    /**
+     * `attrs[key]` matches the regular expression, **anchored at both ends** like
+     * {@link f.glob} — `.*` opts back into a substring search, and `(?i)` into case folding.
+     * The syntax is Rust's `regex`, not JS's: no backreferences and no lookaround.
+     */
+    readonly regex: (key: string, pattern: string) => Predicate;
     /** Collect predicates into a {@link Filter} (purely sugar — they already AND). */
     readonly and: (...preds: Predicate[]) => Filter;
 };
 
 /**
  * Value constructors mirroring the `Value` variants. `v.int` requires a safe
- * integer (the store's attribute integer is an `i64`; a non-integer would be a
- * silent type error since there is no float attribute).
+ * integer and `v.float` a finite number — `NaN`/`Infinity` have no JSON spelling,
+ * and `JSON.stringify` would quietly write `null`.
  */
 declare const v: {
     readonly str: (s: string) => Value;
     readonly int: (n: number) => Value;
+    readonly float: (n: number) => Value;
     readonly bool: (b: boolean) => Value;
     readonly list: (items: string[]) => Value;
+    /**
+     * A UTC instant, from a `Date` or a raw epoch-millisecond count. Milliseconds is
+     * the wire type, so there is no sub-millisecond precision and no timezone.
+     */
+    readonly datetime: (when: Date | number) => Value;
     /** The explicit `Null` value — set-but-empty, distinct from an absent key. */
     readonly nil: () => Value;
 };
 /**
  * Normalize a caller-supplied {@link AttrInput} into the wire {@link Value} shape.
  * Plain scalars map by type; an already-tagged `Value` passes through unchanged.
- * Throws on a non-integer number or a non-string list element.
+ * Throws on a non-finite number, an invalid `Date`, or a non-string list element.
  */
 declare function encodeValue(input: AttrInput): Value;
 /** Normalize a whole `attrs` map of {@link AttrInput} into wire {@link Value}s. */
@@ -317,4 +665,4 @@ declare function decodeValue(value: Value): DecodedValue;
 /** Decode a whole wire `attrs` map back to plain JS values. */
 declare function decodeAttrs(attrs: Record<string, Value>): Record<string, DecodedValue>;
 
-export { type AnnInfo, type AttrInput, type DecodedRecord, type DecodedValue, type FetchLike, type Filter, type Footprint, type Hit, type HybridSearchOptions, type ListOptions, NidusClient, type NidusClientOptions, NidusError, type NidusRecord, type Predicate, type RecallOptions, type RecordInput, type RememberOptions, type SearchOptions, type Stats, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };
+export { type AggregateOptions, type Aggregation, type AnnInfo, type AnnotationOptions, type Annotations, type AttrInput, type ClauseScore, type Decay, type DecodedRecord, type DecodedValue, type FetchLike, type Filter, type Footprint, type Fragment, type FtsCombine, type FtsField, type Highlight, type HighlightOptions, type Hit, type HybridQuerySpelling, type HybridSearchBase, type HybridSearchOptions, type LegScore, type LimitPer, type ListOptions, NidusClient, type NidusClientOptions, NidusError, type NidusRecord, type OrderBy, type Predicate, type ProjectionOptions, type RankBy, type RankingOptions, type RecallOptions, type RecordInput, type RememberOptions, type SearchOptions, type Stats, type TextClause, type TextQuerySpelling, type TextSearchBase, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };