@loams/client 0.1.0 → 0.1.2

package/dist/builders/filter.d.ts

@@ -0,0 +1,96 @@
+import { type JsonObject, type JsonValue } from '@bufbuild/protobuf';
+import { type Query } from '../vendor/proto/gen/loams/collection/v1/query_pb.js';
+/** One filter, as the proto3 JSON of a `loams.collection.v1.Query`. */
+export type FilterJson = JsonObject;
+/** A document id, as a filter or a document call takes it. A `number` must be
+ * a safe integer; pass a `bigint` above 2^53. */
+export type DocId = number | bigint | string | {
+    uuid: string;
+} | {
+    uint: string | number | bigint;
+};
+/** `{"auto": {}}` or an exact number of edits, 0 to 2. */
+export type Fuzziness = 'auto' | 0 | 1 | 2;
+/** A document id as the `Query.ids` `Value` spells it: `{"uint": "1"}`,
+ * `{"uuid": "…"}` or a bare string. */
+export declare function idValue(id: DocId): JsonValue;
+/** The bounds of a range: any of `gt`, `gte`, `lt`, `lte`. */
+export interface Bounds {
+    gt?: JsonValue;
+    gte?: JsonValue;
+    lt?: JsonValue;
+    lte?: JsonValue;
+}
+/** The options of a `match`. */
+export interface MatchOptions {
+    /** `'or'` (the default) or `'and'`. */
+    operator?: 'or' | 'and';
+    minimumShouldMatch?: string | number;
+    fuzziness?: Fuzziness;
+    analyzer?: string;
+}
+/** The options of a `query_string`. */
+export interface QueryStringOptions {
+    fields?: string[];
+    operator?: 'or' | 'and';
+}
+/** The options of a `multi_match`. */
+export interface MultiMatchOptions {
+    /** `best_fields` (the default), `most_fields`, `cross_fields`, `phrase`,
+     * `phrase_prefix`. */
+    kind?: 'best_fields' | 'most_fields' | 'cross_fields' | 'phrase' | 'phrase_prefix';
+    operator?: 'or' | 'and';
+    tieBreaker?: number;
+}
+/** The filter verbs. */
+export declare const Filter: {
+    /** Every document. */
+    readonly all: () => FilterJson;
+    /** No document. */
+    readonly none: () => FilterJson;
+    /** The field equals `value` (a term query). */
+    readonly eq: (field: string, value: JsonValue) => FilterJson;
+    /** The field equals any of `values` (a terms query). */
+    readonly in: (field: string, values: JsonValue[]) => FilterJson;
+    /** The field is within the bounds; an omitted bound is open. */
+    readonly range: (field: string, bounds: Bounds) => FilterJson;
+    /** The field is present, whatever its value. */
+    readonly exists: (field: string) => FilterJson;
+    /** The field is `null` or absent. */
+    readonly isNull: (field: string) => FilterJson;
+    /** The field is an empty string, list or object. */
+    readonly isEmpty: (field: string) => FilterJson;
+    /** The field starts with `value`. */
+    readonly prefix: (field: string, value: string) => FilterJson;
+    /** The field matches a `*`/`?` pattern. */
+    readonly wildcard: (field: string, pattern: string) => FilterJson;
+    /** The field is within `fuzziness` edits of `value`. */
+    readonly fuzzy: (field: string, value: string, edits?: Fuzziness) => FilterJson;
+    /** A full-text match on one field. */
+    readonly match: (field: string, text: string, options?: MatchOptions) => FilterJson;
+    /** The words of `text`, in order, at most `slop` positions apart. */
+    readonly phrase: (field: string, text: string, slop?: number) => FilterJson;
+    /** A full-text match over several fields; `'title^2'` boosts one. */
+    readonly multiMatch: (fields: string[], text: string, options?: MultiMatchOptions) => FilterJson;
+    /** The query-string syntax, over `fields` or the collection's defaults. */
+    readonly queryString: (query: string, options?: QueryStringOptions) => FilterJson;
+    /** The documents with these ids, and no others. */
+    readonly ids: (...ids: DocId[]) => FilterJson;
+    /** Every query matches (a bool `must`). */
+    readonly and: (...queries: FilterJson[]) => FilterJson;
+    /** At least one of the queries matches (a bool `should`). */
+    readonly or: (...queries: FilterJson[]) => FilterJson;
+    /** At least `minimumShouldMatch` of the queries match: `or` with an explicit
+     * `minimum_should_match`. */
+    readonly anyOf: (queries: FilterJson[], minimumShouldMatch: number | string) => FilterJson;
+    /** None of the queries match (a bool `must_not`). */
+    readonly not: (...queries: FilterJson[]) => FilterJson;
+    /** Every query matches, without scoring (a bool `filter`). */
+    readonly filter: (...queries: FilterJson[]) => FilterJson;
+    /** Multiplies the query's score by `boost`. */
+    readonly boost: (query: FilterJson, boost: number) => FilterJson;
+    /** Every match of `query` scores `score`. */
+    readonly constantScore: (query: FilterJson, score: number) => FilterJson;
+};
+/** Decodes a filter into the generated `Query` message. */
+export declare function toQuery(filter: FilterJson): Query;

package/dist/builders/filter.js

@@ -0,0 +1,190 @@
+// The filter builder (SDKP §2.4): one verb per arm of `loams.collection.v1.Query`.
+//
+//   Filter.and(Filter.eq('tags', 'policy'), Filter.range('n', { gte: 2 }))
+//
+// Every verb is a pure function that returns the arm's **proto3 JSON**, which
+// is also how the builder corpus (`sdks/fixtures/builders/*.json`) spells its
+// expectations, so one case is one comparison. `toQuery` decodes it into the
+// generated message when a caller wants the typed form; the search builder and
+// the document calls do that for you.
+//
+// Values are JSON: a string, a number, a bool, `null`, or the IR's tagged
+// objects (`{"date": "<RFC 3339>"}`, `{"uuid": "…"}`).
+import { fromJson } from '@bufbuild/protobuf';
+import { QuerySchema } from '../vendor/proto/gen/loams/collection/v1/query_pb.js';
+function fuzziness(value) {
+    return value === 'auto' ? { auto: {} } : { edits: value };
+}
+/** A document id as the `Query.ids` `Value` spells it: `{"uint": "1"}`,
+ * `{"uuid": "…"}` or a bare string. */
+export function idValue(id) {
+    if (typeof id === 'number') {
+        if (!Number.isSafeInteger(id) || id < 0) {
+            throw new RangeError(`a numeric document id must be a non-negative safe integer, not ${id}; pass a bigint`);
+        }
+        return { uint: String(id) };
+    }
+    if (typeof id === 'bigint') {
+        return { uint: id.toString() };
+    }
+    if (typeof id === 'string') {
+        return id;
+    }
+    if ('uuid' in id) {
+        return { uuid: id.uuid };
+    }
+    return { uint: String(id.uint) };
+}
+function definedBounds(bounds) {
+    const out = {};
+    for (const key of ['gt', 'gte', 'lt', 'lte']) {
+        if (bounds[key] !== undefined) {
+            out[key] = bounds[key];
+        }
+    }
+    return out;
+}
+function boolOperator(operator) {
+    return operator === 'and' ? 'BOOL_OPERATOR_AND' : 'BOOL_OPERATOR_OR';
+}
+/** A field name and an optional `^boost`, for `multi_match`. */
+function multiMatchField(spec) {
+    const at = spec.lastIndexOf('^');
+    if (at > 0) {
+        const boost = Number(spec.slice(at + 1));
+        if (Number.isFinite(boost)) {
+            return { field: spec.slice(0, at), boost };
+        }
+    }
+    return { field: spec };
+}
+/** The filter verbs. */
+export const Filter = {
+    /** Every document. */
+    all() {
+        return { matchAll: {} };
+    },
+    /** No document. */
+    none() {
+        return { matchNone: {} };
+    },
+    /** The field equals `value` (a term query). */
+    eq(field, value) {
+        return { term: { field, value } };
+    },
+    /** The field equals any of `values` (a terms query). */
+    in(field, values) {
+        return { terms: { field, values } };
+    },
+    /** The field is within the bounds; an omitted bound is open. */
+    range(field, bounds) {
+        return { range: { field, ...definedBounds(bounds) } };
+    },
+    /** The field is present, whatever its value. */
+    exists(field) {
+        return { exists: { field } };
+    },
+    /** The field is `null` or absent. */
+    isNull(field) {
+        return { isNull: { field } };
+    },
+    /** The field is an empty string, list or object. */
+    isEmpty(field) {
+        return { isEmpty: { field } };
+    },
+    /** The field starts with `value`. */
+    prefix(field, value) {
+        return { prefix: { field, value } };
+    },
+    /** The field matches a `*`/`?` pattern. */
+    wildcard(field, pattern) {
+        return { wildcard: { field, pattern } };
+    },
+    /** The field is within `fuzziness` edits of `value`. */
+    fuzzy(field, value, edits) {
+        return { fuzzy: { field, value, ...(edits === undefined ? {} : { fuzziness: fuzziness(edits) }) } };
+    },
+    /** A full-text match on one field. */
+    match(field, text, options = {}) {
+        const match = { field, text };
+        if (options.operator !== undefined) {
+            match.operator = options.operator;
+        }
+        if (options.minimumShouldMatch !== undefined) {
+            match.minimumShouldMatch = String(options.minimumShouldMatch);
+        }
+        if (options.fuzziness !== undefined) {
+            match.fuzziness = fuzziness(options.fuzziness);
+        }
+        if (options.analyzer !== undefined) {
+            match.analyzer = options.analyzer;
+        }
+        return { match };
+    },
+    /** The words of `text`, in order, at most `slop` positions apart. */
+    phrase(field, text, slop) {
+        return { matchPhrase: { field, text, ...(slop === undefined ? {} : { slop }) } };
+    },
+    /** A full-text match over several fields; `'title^2'` boosts one. */
+    multiMatch(fields, text, options = {}) {
+        const query = { fields: fields.map(multiMatchField), text };
+        if (options.kind !== undefined) {
+            query.kind = `MULTI_MATCH_KIND_${options.kind.toUpperCase()}`;
+        }
+        if (options.operator !== undefined) {
+            query.operator = boolOperator(options.operator);
+        }
+        if (options.tieBreaker !== undefined) {
+            query.tieBreaker = options.tieBreaker;
+        }
+        return { multiMatch: query };
+    },
+    /** The query-string syntax, over `fields` or the collection's defaults. */
+    queryString(query, options = {}) {
+        const out = { query };
+        if (options.fields !== undefined && options.fields.length > 0) {
+            out.defaultFields = options.fields;
+        }
+        if (options.operator !== undefined) {
+            out.defaultOperator = boolOperator(options.operator);
+        }
+        return { queryString: out };
+    },
+    /** The documents with these ids, and no others. */
+    ids(...ids) {
+        return { ids: ids.map(idValue) };
+    },
+    /** Every query matches (a bool `must`). */
+    and(...queries) {
+        return { bool: { must: queries } };
+    },
+    /** At least one of the queries matches (a bool `should`). */
+    or(...queries) {
+        return { bool: { should: queries } };
+    },
+    /** At least `minimumShouldMatch` of the queries match: `or` with an explicit
+     * `minimum_should_match`. */
+    anyOf(queries, minimumShouldMatch) {
+        return { bool: { should: queries, minimumShouldMatch: String(minimumShouldMatch) } };
+    },
+    /** None of the queries match (a bool `must_not`). */
+    not(...queries) {
+        return { bool: { mustNot: queries } };
+    },
+    /** Every query matches, without scoring (a bool `filter`). */
+    filter(...queries) {
+        return { bool: { filter: queries } };
+    },
+    /** Multiplies the query's score by `boost`. */
+    boost(query, boost) {
+        return { boost: { query, boost } };
+    },
+    /** Every match of `query` scores `score`. */
+    constantScore(query, score) {
+        return { constantScore: { query, score } };
+    },
+};
+/** Decodes a filter into the generated `Query` message. */
+export function toQuery(filter) {
+    return fromJson(QuerySchema, filter);
+}

package/dist/builders/schema.d.ts

@@ -0,0 +1,50 @@
+import type { JsonObject } from '@bufbuild/protobuf';
+/** What every field takes. */
+export interface FieldOptions {
+    /** Whether the field is in the inverted index. Default `true`. */
+    indexed?: boolean;
+    /** Whether the field has a columnar copy for sorting, ranges and
+     * aggregations. Default `false` for text and `true` for every other kind. */
+    fast?: boolean;
+    /** Where the value comes from in `_source`. Default: the field's name. */
+    sourcePath?: string;
+}
+/** A text field's options. */
+export interface TextOptions extends FieldOptions {
+    /** `standard` (the default), `english`, `simple`, `whitespace` or `keyword`. */
+    analyzer?: string;
+    /** Whether positions are indexed, which phrase queries need. Default `true`. */
+    positions?: boolean;
+}
+/** A dense vector's distance function. */
+export type Distance = 'cosine' | 'dot' | 'euclid' | 'manhattan';
+/** What a write does with a `_source` path no field maps. */
+export type DynamicMapping = 'ignore' | 'strict' | 'map';
+/** The schema builder. Each verb appends and returns the builder. */
+export declare class Schema {
+    #private;
+    /** A full-text field. */
+    text(name: string, options?: TextOptions): this;
+    /** An exact-match string field. */
+    keyword(name: string, options?: FieldOptions): this;
+    /** A signed 64-bit integer field. */
+    i64(name: string, options?: FieldOptions): this;
+    /** A 64-bit float field. */
+    f64(name: string, options?: FieldOptions): this;
+    /** A boolean field. */
+    bool(name: string, options?: FieldOptions): this;
+    /** An RFC 3339 timestamp field (the schema's `date` kind). */
+    timestamp(name: string, options?: FieldOptions): this;
+    /** A UUID field. */
+    uuid(name: string, options?: FieldOptions): this;
+    /** A named dense vector of `dim` dimensions. */
+    vector(name: string, dim: number, distance?: Distance): this;
+    /** A named sparse vector; `idf` reweights the query by IDF at search time. */
+    sparseVector(name: string, modifier?: 'none' | 'idf'): this;
+    /** What a write does with unmapped `_source` paths. Default `ignore`. */
+    dynamic(mode: DynamicMapping): this;
+    /** The most fields, vectors and sparse vectors together. Default 1000. */
+    maxFields(n: number): this;
+    /** The schema `Struct`, as `CreateCollectionRequest.schema` takes it. */
+    toJson(): JsonObject;
+}

package/dist/builders/schema.js

@@ -0,0 +1,92 @@
+// The schema builder (SDKP §2.6): `CreateCollectionRequest.schema`, a `Struct`
+// in the REST route's schema JSON, without writing the JSON by hand.
+//
+//   const schema = new Schema()
+//     .text('title').text('body').keyword('tags').i64('n')
+//     .vector('embedding', 4);
+//   await loams.collections.create({ name: 'notes', schema: schema.toJson() });
+//
+// The output is the shape `crates/loams/tests/connect_collections.rs`
+// `kb_schema()` sends: every field spelled out (`name`, `source_path`, `kind`,
+// `indexed`, `fast`), the vectors and sparse vectors as lists, and `dynamic`
+// and `max_fields` always present, so what the builder sends is what the
+// server stores and nothing rides on a server default.
+/** The schema builder. Each verb appends and returns the builder. */
+export class Schema {
+    #fields = [];
+    #vectors = [];
+    #sparse = [];
+    #dynamic = 'ignore';
+    #maxFields = 1000;
+    #field(name, kind, fastByDefault, options) {
+        this.#fields.push({
+            name,
+            source_path: options.sourcePath ?? name,
+            kind,
+            indexed: options.indexed ?? true,
+            fast: options.fast ?? fastByDefault,
+        });
+        return this;
+    }
+    /** A full-text field. */
+    text(name, options = {}) {
+        return this.#field(name, { text: { analyzer: options.analyzer ?? 'standard', positions: options.positions ?? true } }, false, options);
+    }
+    /** An exact-match string field. */
+    keyword(name, options = {}) {
+        return this.#field(name, 'keyword', true, options);
+    }
+    /** A signed 64-bit integer field. */
+    i64(name, options = {}) {
+        return this.#field(name, 'i64', true, options);
+    }
+    /** A 64-bit float field. */
+    f64(name, options = {}) {
+        return this.#field(name, 'f64', true, options);
+    }
+    /** A boolean field. */
+    bool(name, options = {}) {
+        return this.#field(name, 'bool', true, options);
+    }
+    /** An RFC 3339 timestamp field (the schema's `date` kind). */
+    timestamp(name, options = {}) {
+        return this.#field(name, 'date', true, options);
+    }
+    /** A UUID field. */
+    uuid(name, options = {}) {
+        return this.#field(name, 'uuid', true, options);
+    }
+    /** A named dense vector of `dim` dimensions. */
+    vector(name, dim, distance = 'cosine') {
+        if (!Number.isInteger(dim) || dim <= 0) {
+            throw new RangeError(`a vector's dim must be a positive integer, not ${dim}`);
+        }
+        this.#vectors.push({ name, dim, distance });
+        return this;
+    }
+    /** A named sparse vector; `idf` reweights the query by IDF at search time. */
+    sparseVector(name, modifier) {
+        this.#sparse.push(modifier === undefined ? { name } : { name, modifier });
+        return this;
+    }
+    /** What a write does with unmapped `_source` paths. Default `ignore`. */
+    dynamic(mode) {
+        this.#dynamic = mode;
+        return this;
+    }
+    /** The most fields, vectors and sparse vectors together. Default 1000. */
+    maxFields(n) {
+        this.#maxFields = n;
+        return this;
+    }
+    /** The schema `Struct`, as `CreateCollectionRequest.schema` takes it. */
+    toJson() {
+        return {
+            fields: this.#fields.map((field) => ({ ...field })),
+            vectors: this.#vectors.map((vector) => ({ ...vector })),
+            sparse_vectors: this.#sparse.map((sparse) => ({ ...sparse })),
+            dynamic: this.#dynamic,
+            max_fields: this.#maxFields,
+        };
+    }
+}

package/dist/builders/search.d.ts

@@ -0,0 +1,159 @@
+import { type JsonObject, type JsonValue } from '@bufbuild/protobuf';
+import { type Value } from '@bufbuild/protobuf/wkt';
+import { type SearchRequest } from '../vendor/proto/gen/loams/collection/v1/query_pb.js';
+import { ConsistencyToken } from '../runtime/consistency.js';
+import { type FilterJson } from './filter.js';
+/** A fusion, as the proto3 JSON of `loams.collection.v1.Fusion`. */
+export type FusionJson = JsonObject;
+/** Reciprocal-rank fusion; `k` absent is the engine's 60. */
+export declare function rrf(k?: number): FusionJson;
+/** Distance-based score fusion, with the engine's parameters. */
+export declare function dbsf(): FusionJson;
+/** A weighted sum, one weight per retriever in the order they were added. */
+export declare function weighted(...weights: number[]): FusionJson;
+/** The fusions, as one namespace. */
+export declare const Fusion: {
+    readonly rrf: typeof rrf;
+    readonly dbsf: typeof dbsf;
+    readonly weighted: typeof weighted;
+};
+/** One key of the sort, as the proto3 JSON of `SortKey`. */
+export type SortJson = JsonObject;
+type Order = 'asc' | 'desc';
+/** The sort keys. The primary key ascending always breaks ties on the server,
+ * but `queryAll` needs it spelled out to page. */
+export declare const Sort: {
+    /** By score; descending unless told otherwise. */
+    readonly score: (direction?: Order) => SortJson;
+    /** By primary key; ascending unless told otherwise. */
+    readonly pk: (direction?: Order) => SortJson;
+    /** By a fast field. `missing` puts documents without it first or last. */
+    readonly field: (name: string, direction?: Order, missing?: "first" | "last") => SortJson;
+};
+/** The options of a text retriever. */
+export interface TextOptions {
+    /** One field is a `match`; several are a `multi_match`; none is a
+     * `query_string` over the collection's default fields. */
+    fields?: string[];
+    /** How many candidates the retriever contributes. */
+    k?: number;
+}
+/** A vector retriever's options: the candidate count and the ANN knobs. */
+export interface VectorOptions {
+    k?: number;
+    exact?: boolean;
+    nprobes?: number;
+    refineFactor?: number;
+    ef?: number;
+    oversampling?: number;
+    /** Overrides the schema's distance for this query. */
+    distance?: string;
+    /** A pre-filter on this retriever's candidates. */
+    filter?: FilterJson;
+}
+/** A sparse retriever's options. */
+export interface SparseOptions {
+    k?: number;
+    filter?: FilterJson;
+}
+/** What to return of each hit. */
+export interface SelectOptions {
+    /** `_source` paths to keep; absent keeps everything. */
+    include?: string[];
+    /** `_source` paths to drop. */
+    exclude?: string[];
+    /** `true` returns no `_source` at all. */
+    noSource?: boolean;
+    /** Vectors to return by name. */
+    vectors?: string[];
+    /** Fast fields to return by name. */
+    fields?: string[];
+}
+/** A highlighted field's options. */
+export interface HighlightOptions {
+    pre?: string;
+    post?: string;
+    fragmentSize?: number;
+    fragments?: number;
+}
+/** A graph expansion from the top hits (design §07 §5.2). */
+export interface ExpandOptions {
+    /** The source field holding the vertex key. */
+    fromField?: string;
+    seedLabel?: string;
+    seeds?: number;
+    hops?: number;
+    direction?: 'out' | 'in' | 'both';
+    edgeTypes?: string[];
+    limitPerSeed?: number;
+    limit?: number;
+    output?: 'nested' | 'flat';
+}
+/** How fresh the read must be. A token, or its text, is `at_least`. */
+export type ConsistencyLevel = 'strong' | 'eventual' | ConsistencyToken | string;
+/** The proto3 JSON of a `loams.collection.v1.Consistency`. */
+export declare function consistencyJson(level: ConsistencyLevel): JsonObject;
+/** A hit's sort value, as `Hit.sort_values` answers it or as JSON. */
+export type SortValue = JsonValue | Value;
+/** The search builder. */
+export declare class Search {
+    #private;
+    private constructor();
+    /** A search of `collection` (a name or an alias). */
+    static on(collection: string, options?: {
+        namespace?: string;
+    }): Search;
+    /** A builder over an existing request's proto3 JSON. */
+    static fromJson(json: JsonObject): Search;
+    /** The namespace, when it is not the client's default. */
+    namespace(namespace: string): Search;
+    /** A text retriever. A string is a `match`/`multi_match`/`query_string`
+     * by `fields`; a `Filter` (`match`, `multiMatch`, `phrase`…) is used as is. */
+    text(text: string | FilterJson, options?: TextOptions): Search;
+    /** A dense-vector kNN retriever on `field`. */
+    vector(field: string, values: readonly number[], options?: VectorOptions): Search;
+    /** A sparse-vector retriever: `{indices, values}`, or a term-to-weight map
+     * whose keys are the indices. */
+    sparse(field: string, terms: {
+        indices: number[];
+        values: number[];
+    } | Record<number, number>, options?: SparseOptions): Search;
+    /** How the retrievers' ranked lists combine: `rrf()`, `dbsf()` or
+     * `weighted(…)`. */
+    fuse(fusion: FusionJson): Search;
+    /** The filter every candidate must match. */
+    filter(filter: FilterJson): Search;
+    /** The sort, replacing any earlier one. */
+    sort(...keys: SortJson[]): Search;
+    /** The window size; the engine's default is 10. */
+    limit(limit: number): Search;
+    /** How many hits to skip before the window. */
+    offset(offset: number): Search;
+    /** The page after the hit whose `sortValues` these are. */
+    after(sortValues: readonly SortValue[]): Search;
+    /** Drops hits scoring below `score`. */
+    minScore(score: number): Search;
+    /** What to return of each hit. */
+    select(options: SelectOptions): Search;
+    /** Highlights `field` in each hit; call once per field. */
+    highlight(field: string, options?: HighlightOptions): Search;
+    /** Groups the hits by `field`: `size` hits per group, `limit` groups. */
+    groupBy(field: string, options?: {
+        size?: number;
+        limit?: number;
+    }): Search;
+    /** Walks `graph` from the top hits and returns their neighbours. */
+    expand(graph: string, options?: ExpandOptions): Search;
+    /** How fresh the read must be. */
+    consistency(level: ConsistencyLevel): Search;
+    /** The collection searched. */
+    get collection(): string;
+    /** Whether the sort ends in a primary-key tiebreaker, which `queryAll`
+     * needs to page without skipping or repeating a hit. */
+    get hasTiebreak(): boolean;
+    /** The request's proto3 JSON. */
+    toJson(): JsonObject;
+    /** The request as the generated message, checked. */
+    build(): SearchRequest;
+}
+export {};