@duckedup/nidus 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,285 @@
+/**
+ * A typed attribute value, externally tagged exactly as `nidus` serde-encodes
+ * `Value` on the wire: `{ Str }`, `{ Int }`, `{ Bool }`, `{ List }`, or the bare
+ * string `"Null"`.
+ *
+ * `Null` is distinct from an absent key: absence means "not set / not indexed",
+ * `Null` means "set, and empty/none".
+ */
+type Value = {
+    Str: string;
+} | {
+    Int: number;
+} | {
+    Bool: boolean;
+} | {
+    List: string[];
+} | "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).
+ */
+type AttrInput = Value | string | number | boolean | string[] | null;
+/** A document: caller-supplied `id`, an optional embedding, and typed metadata. */
+interface NidusRecord {
+    id: string;
+    /** Omit for a text-only doc (indexed by FTS/metadata only, never by vector search). */
+    vector?: number[];
+    attrs: Record<string, Value>;
+}
+/** Like {@link NidusRecord} but accepts plain JS values in `attrs` (auto-normalized). */
+interface RecordInput {
+    id: string;
+    vector?: number[];
+    attrs: Record<string, AttrInput>;
+}
+/** A record read back from the server, with `attrs` decoded to plain JS values. */
+interface DecodedRecord {
+    id: string;
+    vector?: number[];
+    attrs: Record<string, DecodedValue>;
+}
+/** A single attribute predicate, externally tagged as `nidus` encodes `Predicate`. */
+type Predicate = {
+    Eq: [string, Value];
+} | {
+    Ne: [string, Value];
+} | {
+    Glob: [string, string];
+} | {
+    In: [string, Value[]];
+} | {
+    NotIn: [string, Value[]];
+} | {
+    Lt: [string, Value];
+} | {
+    Le: [string, Value];
+} | {
+    Gt: [string, Value];
+} | {
+    Ge: [string, Value];
+};
+/**
+ * A conjunction (AND) of predicates. On the wire `Filter` is a newtype over
+ * `Vec<Predicate>`, so it serializes as a bare array — an empty array matches
+ * everything.
+ */
+type Filter = Predicate[];
+/** A search/list result row, decoded so `attrs` holds plain JS values. */
+interface Hit {
+    collection: string;
+    id: string;
+    score: number;
+    attrs: Record<string, DecodedValue>;
+}
+/** A {@link Value} decoded back to a plain JS value. */
+type DecodedValue = string | number | boolean | string[] | null;
+/** On-disk footprint, mirroring `FootprintDto`. */
+interface Footprint {
+    rows: number;
+    dead_rows: number;
+    dimension: number;
+    vector_bytes: number;
+    doc_count: number;
+}
+/** Active ANN-index configuration, mirroring `AnnDto` (`null` when exact search). */
+interface AnnInfo {
+    kind: string;
+    overscan: number;
+    seed: number;
+    m?: number;
+    ef_construction?: number;
+    ef_search?: number;
+    n_lists?: number;
+    n_probe?: number;
+}
+/** Store-wide introspection, mirroring the `/stats` response. */
+interface Stats {
+    dimension: number;
+    distance: string;
+    ann: AnnInfo | null;
+    collections: string[];
+    footprint: Footprint;
+}
+/** Options for {@link NidusClient.search}. An empty/omitted `scope` searches every collection. */
+interface SearchOptions {
+    query: number[];
+    scope?: string[];
+    topK?: number;
+    minScore?: number;
+    filter?: Filter;
+}
+/** Options for {@link NidusClient.textSearch} (BM25). */
+interface TextSearchOptions {
+    field: string;
+    query: string;
+    scope?: string[];
+    topK?: 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[];
+    field: string;
+    text: string;
+    scope?: string[];
+    topK?: number;
+    filter?: Filter;
+    rrfK?: number;
+    candidates?: number;
+}
+/** Options for {@link NidusClient.list} (metadata-only, paginated). */
+interface ListOptions {
+    scope?: string[];
+    offset?: number;
+    limit?: number;
+    filter?: Filter;
+}
+
+/** Minimal `fetch` signature the client needs — satisfied by the platform global. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Construction options for {@link NidusClient}. */
+interface NidusClientOptions {
+    /** Base URL of the server, e.g. `http://127.0.0.1:7700`. Trailing slash optional. */
+    baseUrl: string;
+    /** Bearer token, when the server was started with `--token`. */
+    token?: string;
+    /** Override the `fetch` implementation (defaults to `globalThis.fetch`). */
+    fetch?: FetchLike;
+    /** Per-request timeout in milliseconds. Omit (or `0`) to disable. */
+    timeoutMs?: number;
+    /** Extra headers sent on every request. */
+    headers?: Record<string, string>;
+}
+declare class NidusClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly doFetch;
+    private readonly timeoutMs;
+    private readonly extraHeaders;
+    constructor(options: NidusClientOptions);
+    /** Liveness check. Returns `true` when the server answers `/health`. */
+    health(): Promise<boolean>;
+    /** Store-wide introspection: dimension, distance, ANN config, collections, footprint. */
+    stats(): Promise<Stats>;
+    /** List every collection name. */
+    collections(): Promise<string[]>;
+    /** Create a collection. Idempotent on the server side. */
+    createCollection(name: string): Promise<void>;
+    /** Drop a collection and all its records. */
+    dropCollection(name: string): Promise<void>;
+    /** Read a collection's free-form string metadata. */
+    getMeta(name: string): Promise<Record<string, string>>;
+    /** Replace a collection's free-form string metadata. */
+    setMeta(name: string, meta: Record<string, string>): Promise<void>;
+    /**
+     * Insert or replace records (idempotent on `id` within the collection).
+     * `attrs` accept plain JS values or `v.*` helpers; they are normalized for you.
+     * Returns the number of records upserted.
+     */
+    upsert(name: string, records: RecordInput[]): Promise<number>;
+    /** Delete records by id. Returns the number deleted. */
+    delete(name: string, opts: {
+        ids: string[];
+    }): Promise<number>;
+    /** Delete every record matching `filter`. Returns the number deleted. */
+    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>;
+    /** Vector (cosine) nearest-neighbour search. Empty `scope` searches all collections. */
+    search(opts: SearchOptions): Promise<Hit[]>;
+    /** BM25 full-text search over one indexed field. */
+    textSearch(opts: TextSearchOptions): Promise<Hit[]>;
+    /** Hybrid search: fuse a vector query and a BM25 text query via RRF. */
+    hybridSearch(opts: HybridSearchOptions): Promise<Hit[]>;
+    /** Metadata-only listing (no vector), paginated by `offset`/`limit`. */
+    list(opts?: ListOptions): Promise<Hit[]>;
+    /** Force a durability flush. */
+    flush(): Promise<void>;
+    /** Compact the store (reclaim space from deleted/overwritten rows). */
+    compact(): Promise<void>;
+    /** Run a search-family request and decode the resulting hits' attrs. */
+    private searchRequest;
+    /** 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. */
+    private raw;
+}
+
+/** An error returned by a `nidus` server, or a transport failure reaching it. */
+declare class NidusError extends Error {
+    /** The HTTP status code, or `0` for a transport/timeout failure (no response). */
+    readonly status: number;
+    constructor(message: string, status: number);
+    /** A malformed request the server rejected (HTTP 400). */
+    get isBadRequest(): boolean;
+    /** The store is read-only (HTTP 403). */
+    get isReadOnly(): boolean;
+    /** The writer lock is held by another process (HTTP 409). */
+    get isLocked(): boolean;
+    /** Out of capacity: `max_vector_bytes` exceeded or OOM (HTTP 507). */
+    get isOutOfCapacity(): boolean;
+}
+
+/**
+ * Predicate constructors. Each accepts a plain JS value (auto-normalized) or an
+ * explicit `v.*` {@link Value}. Combine results into a {@link Filter} array, or
+ * use {@link f.and} for readability.
+ */
+declare const f: {
+    /** `attrs[key] === value`. */
+    readonly eq: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is present and `!== value`. */
+    readonly ne: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is a `Str` matching the glob pattern (`*`, `?`, `[..]`). */
+    readonly glob: (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`. */
+    readonly notIn: (key: string, values: AttrInput[]) => Predicate;
+    /** `attrs[key] < value` (same-type, orderable). */
+    readonly lt: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key] <= value` (same-type, orderable). */
+    readonly le: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key] > value` (same-type, orderable). */
+    readonly gt: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key] >= value` (same-type, orderable). */
+    readonly ge: (key: string, value: AttrInput) => 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).
+ */
+declare const v: {
+    readonly str: (s: string) => Value;
+    readonly int: (n: number) => Value;
+    readonly bool: (b: boolean) => Value;
+    readonly list: (items: string[]) => 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.
+ */
+declare function encodeValue(input: AttrInput): Value;
+/** Normalize a whole `attrs` map of {@link AttrInput} into wire {@link Value}s. */
+declare function encodeAttrs(attrs: Record<string, AttrInput>): Record<string, Value>;
+/** Decode a wire {@link Value} back to a plain JS value. */
+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 RecordInput, type SearchOptions, type Stats, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+/**
+ * A typed attribute value, externally tagged exactly as `nidus` serde-encodes
+ * `Value` on the wire: `{ Str }`, `{ Int }`, `{ Bool }`, `{ List }`, or the bare
+ * string `"Null"`.
+ *
+ * `Null` is distinct from an absent key: absence means "not set / not indexed",
+ * `Null` means "set, and empty/none".
+ */
+type Value = {
+    Str: string;
+} | {
+    Int: number;
+} | {
+    Bool: boolean;
+} | {
+    List: string[];
+} | "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).
+ */
+type AttrInput = Value | string | number | boolean | string[] | null;
+/** A document: caller-supplied `id`, an optional embedding, and typed metadata. */
+interface NidusRecord {
+    id: string;
+    /** Omit for a text-only doc (indexed by FTS/metadata only, never by vector search). */
+    vector?: number[];
+    attrs: Record<string, Value>;
+}
+/** Like {@link NidusRecord} but accepts plain JS values in `attrs` (auto-normalized). */
+interface RecordInput {
+    id: string;
+    vector?: number[];
+    attrs: Record<string, AttrInput>;
+}
+/** A record read back from the server, with `attrs` decoded to plain JS values. */
+interface DecodedRecord {
+    id: string;
+    vector?: number[];
+    attrs: Record<string, DecodedValue>;
+}
+/** A single attribute predicate, externally tagged as `nidus` encodes `Predicate`. */
+type Predicate = {
+    Eq: [string, Value];
+} | {
+    Ne: [string, Value];
+} | {
+    Glob: [string, string];
+} | {
+    In: [string, Value[]];
+} | {
+    NotIn: [string, Value[]];
+} | {
+    Lt: [string, Value];
+} | {
+    Le: [string, Value];
+} | {
+    Gt: [string, Value];
+} | {
+    Ge: [string, Value];
+};
+/**
+ * A conjunction (AND) of predicates. On the wire `Filter` is a newtype over
+ * `Vec<Predicate>`, so it serializes as a bare array — an empty array matches
+ * everything.
+ */
+type Filter = Predicate[];
+/** A search/list result row, decoded so `attrs` holds plain JS values. */
+interface Hit {
+    collection: string;
+    id: string;
+    score: number;
+    attrs: Record<string, DecodedValue>;
+}
+/** A {@link Value} decoded back to a plain JS value. */
+type DecodedValue = string | number | boolean | string[] | null;
+/** On-disk footprint, mirroring `FootprintDto`. */
+interface Footprint {
+    rows: number;
+    dead_rows: number;
+    dimension: number;
+    vector_bytes: number;
+    doc_count: number;
+}
+/** Active ANN-index configuration, mirroring `AnnDto` (`null` when exact search). */
+interface AnnInfo {
+    kind: string;
+    overscan: number;
+    seed: number;
+    m?: number;
+    ef_construction?: number;
+    ef_search?: number;
+    n_lists?: number;
+    n_probe?: number;
+}
+/** Store-wide introspection, mirroring the `/stats` response. */
+interface Stats {
+    dimension: number;
+    distance: string;
+    ann: AnnInfo | null;
+    collections: string[];
+    footprint: Footprint;
+}
+/** Options for {@link NidusClient.search}. An empty/omitted `scope` searches every collection. */
+interface SearchOptions {
+    query: number[];
+    scope?: string[];
+    topK?: number;
+    minScore?: number;
+    filter?: Filter;
+}
+/** Options for {@link NidusClient.textSearch} (BM25). */
+interface TextSearchOptions {
+    field: string;
+    query: string;
+    scope?: string[];
+    topK?: 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[];
+    field: string;
+    text: string;
+    scope?: string[];
+    topK?: number;
+    filter?: Filter;
+    rrfK?: number;
+    candidates?: number;
+}
+/** Options for {@link NidusClient.list} (metadata-only, paginated). */
+interface ListOptions {
+    scope?: string[];
+    offset?: number;
+    limit?: number;
+    filter?: Filter;
+}
+
+/** Minimal `fetch` signature the client needs — satisfied by the platform global. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Construction options for {@link NidusClient}. */
+interface NidusClientOptions {
+    /** Base URL of the server, e.g. `http://127.0.0.1:7700`. Trailing slash optional. */
+    baseUrl: string;
+    /** Bearer token, when the server was started with `--token`. */
+    token?: string;
+    /** Override the `fetch` implementation (defaults to `globalThis.fetch`). */
+    fetch?: FetchLike;
+    /** Per-request timeout in milliseconds. Omit (or `0`) to disable. */
+    timeoutMs?: number;
+    /** Extra headers sent on every request. */
+    headers?: Record<string, string>;
+}
+declare class NidusClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly doFetch;
+    private readonly timeoutMs;
+    private readonly extraHeaders;
+    constructor(options: NidusClientOptions);
+    /** Liveness check. Returns `true` when the server answers `/health`. */
+    health(): Promise<boolean>;
+    /** Store-wide introspection: dimension, distance, ANN config, collections, footprint. */
+    stats(): Promise<Stats>;
+    /** List every collection name. */
+    collections(): Promise<string[]>;
+    /** Create a collection. Idempotent on the server side. */
+    createCollection(name: string): Promise<void>;
+    /** Drop a collection and all its records. */
+    dropCollection(name: string): Promise<void>;
+    /** Read a collection's free-form string metadata. */
+    getMeta(name: string): Promise<Record<string, string>>;
+    /** Replace a collection's free-form string metadata. */
+    setMeta(name: string, meta: Record<string, string>): Promise<void>;
+    /**
+     * Insert or replace records (idempotent on `id` within the collection).
+     * `attrs` accept plain JS values or `v.*` helpers; they are normalized for you.
+     * Returns the number of records upserted.
+     */
+    upsert(name: string, records: RecordInput[]): Promise<number>;
+    /** Delete records by id. Returns the number deleted. */
+    delete(name: string, opts: {
+        ids: string[];
+    }): Promise<number>;
+    /** Delete every record matching `filter`. Returns the number deleted. */
+    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>;
+    /** Vector (cosine) nearest-neighbour search. Empty `scope` searches all collections. */
+    search(opts: SearchOptions): Promise<Hit[]>;
+    /** BM25 full-text search over one indexed field. */
+    textSearch(opts: TextSearchOptions): Promise<Hit[]>;
+    /** Hybrid search: fuse a vector query and a BM25 text query via RRF. */
+    hybridSearch(opts: HybridSearchOptions): Promise<Hit[]>;
+    /** Metadata-only listing (no vector), paginated by `offset`/`limit`. */
+    list(opts?: ListOptions): Promise<Hit[]>;
+    /** Force a durability flush. */
+    flush(): Promise<void>;
+    /** Compact the store (reclaim space from deleted/overwritten rows). */
+    compact(): Promise<void>;
+    /** Run a search-family request and decode the resulting hits' attrs. */
+    private searchRequest;
+    /** 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. */
+    private raw;
+}
+
+/** An error returned by a `nidus` server, or a transport failure reaching it. */
+declare class NidusError extends Error {
+    /** The HTTP status code, or `0` for a transport/timeout failure (no response). */
+    readonly status: number;
+    constructor(message: string, status: number);
+    /** A malformed request the server rejected (HTTP 400). */
+    get isBadRequest(): boolean;
+    /** The store is read-only (HTTP 403). */
+    get isReadOnly(): boolean;
+    /** The writer lock is held by another process (HTTP 409). */
+    get isLocked(): boolean;
+    /** Out of capacity: `max_vector_bytes` exceeded or OOM (HTTP 507). */
+    get isOutOfCapacity(): boolean;
+}
+
+/**
+ * Predicate constructors. Each accepts a plain JS value (auto-normalized) or an
+ * explicit `v.*` {@link Value}. Combine results into a {@link Filter} array, or
+ * use {@link f.and} for readability.
+ */
+declare const f: {
+    /** `attrs[key] === value`. */
+    readonly eq: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is present and `!== value`. */
+    readonly ne: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key]` is a `Str` matching the glob pattern (`*`, `?`, `[..]`). */
+    readonly glob: (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`. */
+    readonly notIn: (key: string, values: AttrInput[]) => Predicate;
+    /** `attrs[key] < value` (same-type, orderable). */
+    readonly lt: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key] <= value` (same-type, orderable). */
+    readonly le: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key] > value` (same-type, orderable). */
+    readonly gt: (key: string, value: AttrInput) => Predicate;
+    /** `attrs[key] >= value` (same-type, orderable). */
+    readonly ge: (key: string, value: AttrInput) => 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).
+ */
+declare const v: {
+    readonly str: (s: string) => Value;
+    readonly int: (n: number) => Value;
+    readonly bool: (b: boolean) => Value;
+    readonly list: (items: string[]) => 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.
+ */
+declare function encodeValue(input: AttrInput): Value;
+/** Normalize a whole `attrs` map of {@link AttrInput} into wire {@link Value}s. */
+declare function encodeAttrs(attrs: Record<string, AttrInput>): Record<string, Value>;
+/** Decode a wire {@link Value} back to a plain JS value. */
+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 RecordInput, type SearchOptions, type Stats, type TextSearchOptions, type Value, decodeAttrs, decodeValue, encodeAttrs, encodeValue, f, v };