@volter/twin-upstashvector 0.1.0

package/dist/src/upstashvector-store.d.ts

@@ -0,0 +1,248 @@
+import { matchesFilter } from './upstashvector-filter.js';
+export declare const SERVICE = "upstashvector";
+/** The default namespace is named `""` (empty string) — upstash.com/docs/vector/features/namespaces. */
+export declare const DEFAULT_NAMESPACE = "";
+/** The three metrics an Upstash Vector index can be created with (`/info`.similarityFunction). */
+export declare const SIMILARITY_FUNCTIONS: readonly ["COSINE", "EUCLIDEAN", "DOT_PRODUCT"];
+export type SimilarityFunction = typeof SIMILARITY_FUNCTIONS[number];
+/** The `/info`.indexType values. This twin models DENSE only; see `UNSUPPORTED_SPARSE`. */
+export declare const DEFAULT_SIMILARITY: SimilarityFunction;
+/**
+ * A vendor-shaped API failure: a message and the HTTP status it is served with.
+ *
+ * The status codes are the ones upstash.com/docs/vector/api/get-started enumerates — 400 for
+ * "syntax/command errors", 401 for auth, 405 for an unsupported method — plus the 422 the upsert
+ * endpoint's own error example shows for a dimension mismatch.
+ */
+export declare class VectorApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** Thrown when a write is attempted against a read-only twin. Mapped to HTTP 405 by the handler. */
+export declare class ReadOnlyError extends Error {
+    constructor();
+}
+/** Everything a request needs. `root` scopes the kernel state; `occurredAt` stamps the actions. */
+export type VectorContext = {
+    root?: string;
+    occurredAt: string;
+    readOnly?: boolean;
+    /** The dimension this index was created with. Omit to let the FIRST upsert lock one in. */
+    dimension?: number;
+    /** The metric this index was created with. Defaults to COSINE (the console's own default). */
+    similarityFunction?: SimilarityFunction;
+};
+/** One stored vector, in the twin's own storage encoding. */
+export type VectorRow = {
+    ns: string;
+    vid: string;
+    values: number[];
+    metadata: Record<string, unknown> | null;
+    data: string | null;
+    /** A per-subject WRITE ORDINAL — see `nextRev`. Never leaves this module. */
+    _rev?: number;
+};
+/** Σ aᵢ·bᵢ. */
+export declare function dotProduct(a: readonly number[], b: readonly number[]): number;
+/** Σ (aᵢ−bᵢ)² — the SQUARED euclidean distance, which is what the vendor's formula takes. */
+export declare function squaredDistance(a: readonly number[], b: readonly number[]): number;
+/**
+ * dot(a,b) / (‖a‖·‖b‖).
+ *
+ * ZERO-VECTOR EDGE (twin-defined, and the vendor does not document it): the true cosine of a
+ * zero-length vector is undefined — the denominator is 0. Returning the raw `0/0` would put a
+ * `NaN` into the score, which `JSON.stringify` renders as `null`, so a caller would receive a
+ * result row whose `score` key was null and no error anywhere. This returns 0 (a normalized score
+ * of exactly 0.5, "no information") instead, so the response stays well-typed. Documented in the
+ * README's ## Coverage as an unverified edge rather than presented as vendor behaviour.
+ */
+export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/**
+ * The NORMALIZED score Upstash returns, per metric. Quoted verbatim from
+ * upstash.com/docs/vector/features/similarityfunctions:
+ *   COSINE       "(1 + cosine_similarity(v1, v2)) / 2"
+ *   EUCLIDEAN    "1 / (1 + squared_distance(v1, v2))"
+ *   DOT_PRODUCT  "(1 + dot_product(v1, v2)) / 2"
+ * All three are monotonically increasing in similarity, so a higher score is always a better match.
+ */
+export declare function similarityScore(fn: SimilarityFunction, a: readonly number[], b: readonly number[]): number;
+/**
+ * A vector's kernel subject id.
+ *
+ * Both components are percent-encoded, which is what makes the join UNAMBIGUOUS: `encodeURIComponent`
+ * escapes `:` to `%3A`, so a namespace named `a` holding id `b:c` and a namespace named `a:b`
+ * holding id `c` produce different subject ids. A naive `vec:${ns}:${id}` would map both to
+ * `vec:a:b:c` — one vector silently overwriting the other, across namespaces, which is precisely
+ * the isolation namespaces exist to provide.
+ */
+export declare function vectorSubjectId(ns: string, vid: string): string;
+/** A namespace's kernel subject id. */
+export declare function namespaceSubjectId(ns: string): string;
+/** The single index-configuration subject. */
+export declare const CONFIG_SUBJECT_ID = "config:index";
+/** The kernel subject types this twin writes. Mirrored by the conformance check. */
+export declare const UPSTASHVECTOR_RESOURCE_TYPES: readonly ["vector", "namespace", "config"];
+export type UpstashVectorResourceType = typeof UPSTASHVECTOR_RESOURCE_TYPES[number];
+/**
+ * A synchronous in-memory image of the whole index for the duration of ONE request.
+ *
+ * Seeded from `projectResources` (the kernel IS the source of truth); every mutation records what
+ * it touched, and `flush` writes exactly those subjects back. Nothing here outlives the request —
+ * no cache, no singleton, no state a later request could inherit.
+ */
+export declare class IndexSpace {
+    readonly ctx: VectorContext;
+    private readonly rows;
+    private readonly namespaces;
+    private readonly touched;
+    /** subjectId → the last write ordinal seen, INCLUDING for subjects currently deleted. */
+    private readonly revs;
+    private dimension;
+    private similarity;
+    private configDirty;
+    /** True when stored vectors disagree on length, so no dimension can be honestly inferred. */
+    private mixedDimensions;
+    constructor(ctx: VectorContext);
+    private assertWritable;
+    /** The next write ordinal for a subject. Survives deletes — see the constructor's note. */
+    private nextRev;
+    /** The dimension this index enforces, or `null` while no upsert has locked one in yet. */
+    get indexDimension(): number | null;
+    get similarityFunction(): SimilarityFunction;
+    /**
+     * Check a vector's length against the index, LOCKING the dimension in on the first upsert.
+     *
+     * The vendor's index has a dimension chosen at creation time and cannot change it. A local twin
+     * has no creation step, so the first upsert plays that role; from then on the check is exactly
+     * as strict as the vendor's, including the error, which is the ONE message in this pack quoted
+     * verbatim from the vendor's own docs (the /upsert endpoint's 422 example).
+     */
+    private checkDimension;
+    /** Every namespace that currently exists, default first then lexicographic (deterministic). */
+    listNamespaces(): string[];
+    hasNamespace(ns: string): boolean;
+    private ensureNamespace;
+    /**
+     * `POST|DELETE /delete-namespace/{ns}` — remove a namespace AND everything in it.
+     *
+     * Distinct from `/reset/{ns}`, which empties a namespace but leaves it existing. Keeping both
+     * behaviours distinct is why namespaces are tracked as their own kernel subject rather than
+     * derived from "does any vector mention this name" — a derived model would make the two
+     * endpoints indistinguishable, which would quietly drop a real part of the vendor's surface.
+     *
+     * TWIN-DEFINED (unverified): deleting the DEFAULT namespace is refused. The default namespace
+     * has no name to address and `/reset` already empties it, so a request to remove it is far more
+     * likely to be a bug than an intent. Stated in the README's ## Coverage.
+     */
+    deleteNamespace(ns: string): void;
+    /** Every live vector in one namespace, in a DETERMINISTIC order (id ascending). */
+    vectorsIn(ns: string): VectorRow[];
+    getVector(ns: string, vid: string): VectorRow | undefined;
+    private putVector;
+    private removeVector;
+    /**
+     * `POST /upsert[/{ns}]` — insert or REPLACE whole vectors.
+     *
+     * Upsert REPLACES: the vendor's `/update` endpoint exists precisely because `/upsert` does not
+     * merge, so an upsert without `metadata` clears any metadata the id previously had. Getting this
+     * backwards would make `/update`'s whole reason for existing invisible.
+     *
+     * Returns the vendor's `{"result": "Success"}` payload string.
+     */
+    upsert(ns: string, items: unknown[]): 'Success';
+    /** Read one `/upsert` element: `{id, vector, metadata?, data?}`. */
+    private readUpsertItem;
+    /**
+     * `POST /update[/{ns}]` — partially modify ONE existing vector.
+     *
+     * `metadataUpdateMode` (from the vendor's update endpoint): `OVERWRITE` (the default) replaces
+     * the metadata object wholesale; `PATCH` merges the supplied keys over what is there.
+     * Returns `{updated: 0|1}` — 0 when the id does not exist, which is a normal answer, not an error.
+     */
+    update(ns: string, raw: unknown): {
+        updated: number;
+    };
+    /**
+     * `POST /query[/{ns}]` — rank the namespace's vectors against a query vector.
+     *
+     * The ORDER: score DESCENDING, ties broken by id ASCENDING. The tie-break is TWIN-DEFINED (the
+     * vendor does not specify one) and exists so a verify that seeds two equidistant vectors gets a
+     * reproducible answer instead of whatever the map iteration happened to yield.
+     */
+    query(ns: string, raw: unknown): Array<Record<string, unknown>>;
+    /**
+     * `POST /fetch[/{ns}]` — look vectors up BY ID (or by id prefix), unranked.
+     *
+     * By ids: "Array elements can be `null` if no such vector exists with the provided id" (the
+     * vendor's own fetch doc), and the result is positionally aligned with the request. By prefix:
+     * only the matches, so no nulls.
+     */
+    fetch(ns: string, raw: unknown): Array<Record<string, unknown> | null>;
+    /**
+     * `POST /range[/{ns}]` — paginate the namespace in id order.
+     *
+     * The cursor is a decimal OFFSET as a string (the vendor's own example advances `""` → `"2"`),
+     * and `nextCursor` is `""` when the walk is finished. Ordering is id-ascending, which is what
+     * makes the offset cursor stable across pages.
+     */
+    range(ns: string, raw: unknown): {
+        nextCursor: string;
+        vectors: Array<Record<string, unknown>>;
+    };
+    /**
+     * `POST|DELETE /delete[/{ns}]` — by ids, by id prefix, or by metadata filter.
+     *
+     * Returns `{deleted: N}`, the vendor's own shape, where N counts vectors that ACTUALLY existed —
+     * deleting an unknown id is not an error and contributes 0.
+     */
+    delete(ns: string, raw: unknown): {
+        deleted: number;
+    };
+    /**
+     * `POST|DELETE /reset[/{ns}]` and `/reset?all` — empty a namespace (or every namespace).
+     *
+     * Emptying, NOT removing: the namespaces themselves survive a reset. `?all` is how the SDK's
+     * `reset({all:true})` spells it (`ResetCommand` appends the bare `?all` query flag).
+     */
+    reset(opts: {
+        namespace?: string;
+        all?: boolean;
+    }): 'Success';
+    /**
+     * `GET|POST /info` — index-wide counts and configuration.
+     *
+     * Shape quoted from upstash.com/docs/vector/api/endpoints/info. `pendingVectorCount` is always 0
+     * here and that is HONEST rather than a stub: the vendor's pending count reflects vectors still
+     * being indexed asynchronously, and this twin's upsert is synchronous, so nothing is ever
+     * pending. `indexSize` is a byte estimate; the vendor's exact accounting is not published, so
+     * this reports a computed, deterministic size (see `estimateIndexSize`) rather than a constant.
+     */
+    info(): Record<string, unknown>;
+    /**
+     * `indexSize`, computed with the VENDOR'S OWN PUBLISHED FORMULA.
+     *
+     * upstash.com/docs/vector/help/faq states it verbatim: "Each dimension is estimated to be 4
+     * bytes, resulting in vector storage being calculated as vector count * dimension count * 4
+     * bytes", and adds that the storage charge combines that with metadata (up to 48 KB/vector) and
+     * data (up to 1 MB/vector). So this is `dimensions x 4` per vector plus the encoded size of its
+     * metadata and data — not a twin invention. (An earlier draft said the vendor published no
+     * accounting and also counted the id's bytes, which the formula does not include; both were
+     * corrected once the FAQ was found during the §9 pass.)
+     *
+     * It stays an ESTIMATE in the vendor's own sense of the word, and it is a real function of real
+     * state — it grows when you add vectors and shrinks when you delete them.
+     */
+    private estimateIndexSize;
+    /** Did this run write anything? */
+    get dirty(): boolean;
+    /**
+     * Write every touched subject back to the kernel action log.
+     *
+     * The kernel MERGES fields, so a delete writes EVERY field back to its "nothing here" value —
+     * leaving `values`/`metadata` behind would let a later re-upsert of the same id inherit a dead
+     * coordinate array if it ever wrote a partial field set.
+     */
+    flush(): Promise<void>;
+}
+/** Re-exported so the handler can map a filter parse failure without importing the filter module. */
+export { matchesFilter };