@volter/twin-upstashvector 0.1.0

package/dist/src/upstashvector-filter.js

@@ -0,0 +1,564 @@
+// UPSTASH VECTOR METADATA FILTERING — a REAL tokenizer, recursive-descent parser and evaluator for
+// the filter language documented at upstash.com/docs/vector/features/filtering.
+//
+// This is a genuine language implementation, not a substring match: `filter` strings arrive as
+// opaque text on `/query`, `/delete` and `/update`, and a twin that "supported filtering" by
+// checking `metadata[k] === v` for the one shape its own tests used would be exactly the fake
+// success this repo forbids. The grammar below is parsed to an AST and the AST is evaluated
+// against each candidate's metadata, so an expression the tests never anticipated still works and
+// a malformed one is REJECTED with a parse error rather than silently matching everything.
+//
+// ── GROUNDED (2026-08-19) ─────────────────────────────────────────────────────────────────────
+// upstash.com/docs/vector/features/filtering, quoted where it is quotable:
+//   • operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `GLOB`, `NOT GLOB`, `IN`, `NOT IN`, `CONTAINS`,
+//     `NOT CONTAINS`, `HAS FIELD`, `HAS NOT FIELD`, combined with `AND` / `OR`;
+//   • "Nested objects can be at arbitrary depths, so more than one `.` accessor can be used in the
+//     same identifier";
+//   • "individual array elements can also be filtered by referencing them with the `[]` accessor by
+//     their indexes", and "it is possible to index from the back using the `#` character with
+//     negative values" (`arr[#-1]` is the last element);
+//   • "The string literals can be either single or double quoted";
+//   • "Boolean literals are represented as `1` or `0`" — while the docs' own `!=` example uses
+//     `is_capital != true`, so BOTH spellings are accepted here (see `parseOperand`);
+//   • "`AND` will have higher precedence than `OR`" when no parentheses are given — which is why
+//     `parseOr` sits above `parseAnd` below rather than the two sharing one precedence level.
+//
+// ── WHAT IS DELIBERATELY NOT CLAIMED ──────────────────────────────────────────────────────────
+// Upstash does not publish the literal text of its parse errors, and this pack has no live index to
+// probe (unlike its sibling upstash, which live-probed every string). So `FilterError.message`
+// is TWIN-AUTHORED and says so; what is faithful — and what the capability manifest asserts — is
+// that a malformed filter is REJECTED with the vendor's documented `{error,status}` envelope at
+// HTTP 400 rather than being ignored. A filter that silently matched everything would turn a typo
+// into a data leak, which is the failure this module exists to prevent.
+/** A filter that could not be parsed. The handler maps this to the vendor's 400 envelope. */
+export class FilterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FilterError';
+    }
+}
+const OPERATOR_CHARS = new Set(['=', '!', '<', '>']);
+/** Reserved words. Case-INSENSITIVE in the docs' examples (`and` and `AND` both appear). */
+const WORDS = new Set(['AND', 'OR', 'NOT', 'IN', 'GLOB', 'CONTAINS', 'HAS', 'FIELD']);
+/**
+ * Split a filter string into tokens.
+ *
+ * Identifiers carry their `.`/`[]` accessors as ONE token (`geography.coordinates.latitude`,
+ * `major_industries[0]`, `tags[#-1]`) because the path is resolved as a unit at evaluation time;
+ * splitting them would force the parser to re-join them and lose the distinction between the
+ * accessor dot and a decimal point.
+ */
+export function tokenizeFilter(input) {
+    const tokens = [];
+    let i = 0;
+    while (i < input.length) {
+        const c = input[i];
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+            i++;
+            continue;
+        }
+        const pos = i;
+        if (c === '(' || c === ')' || c === ',') {
+            tokens.push({ kind: 'punct', value: c, pos });
+            i++;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            // A quoted string. The closing quote must match the opening one, so an apostrophe inside a
+            // double-quoted literal is ordinary text.
+            const quote = c;
+            i++;
+            let out = '';
+            let closed = false;
+            while (i < input.length) {
+                const ch = input[i];
+                // NO BACKSLASH ESCAPE. An earlier draft treated `\x` as an escape for `x`; §9 round 1
+                // showed that is both undocumented by Upstash and a source of SILENT WRONG ANSWERS:
+                // with it, `path = 'C:\Users'` matched a vector whose stored path was `C:Users` and did
+                // NOT match the one holding `C:\Users` — a confidently wrong row at HTTP 200. Upstash's
+                // filter language is SQLite-family (`GLOB`, `IN`, `HAS FIELD`), and no member of that
+                // family gives backslash a special meaning inside a string literal. A backslash is an
+                // ordinary character; a quote is closed only by its own kind, which is what the two
+                // quote styles are for.
+                if (ch === quote) {
+                    closed = true;
+                    i++;
+                    break;
+                }
+                out += ch;
+                i++;
+            }
+            if (!closed)
+                throw new FilterError(`upstashvector: unterminated string literal starting at position ${pos} in filter`);
+            tokens.push({ kind: 'string', value: out, pos });
+            continue;
+        }
+        if (OPERATOR_CHARS.has(c)) {
+            const two = input.slice(i, i + 2);
+            if (two === '!=' || two === '<=' || two === '>=') {
+                tokens.push({ kind: 'op', value: two, pos });
+                i += 2;
+                continue;
+            }
+            if (c === '=' || c === '<' || c === '>') {
+                tokens.push({ kind: 'op', value: c, pos });
+                i++;
+                continue;
+            }
+            throw new FilterError(`upstashvector: unexpected character '${c}' at position ${pos} in filter (did you mean '!='?)`);
+        }
+        // A number: an optional sign is handled by the operand parser, not here, so that `a>-1` still
+        // tokenizes as `a` `>` `-1`.
+        if (/[0-9]/.test(c) || (c === '-' && /[0-9.]/.test(input[i + 1] ?? ''))) {
+            let out = c;
+            i++;
+            while (i < input.length && /[0-9._eE+-]/.test(input[i])) {
+                // Stop before an `e+`/`e-` that is not part of an exponent, so `a=1 e` does not swallow.
+                const ch = input[i];
+                if ((ch === '+' || ch === '-') && !/[eE]/.test(out[out.length - 1] ?? ''))
+                    break;
+                out += ch;
+                i++;
+            }
+            if (!Number.isFinite(Number(out)))
+                throw new FilterError(`upstashvector: '${out}' at position ${pos} is not a valid number in filter`);
+            tokens.push({ kind: 'number', value: out, pos });
+            continue;
+        }
+        if (/[A-Za-z_]/.test(c)) {
+            let out = '';
+            while (i < input.length && /[A-Za-z0-9_.[\]#-]/.test(input[i])) {
+                // `-` is legal inside a bracket subscript (`[#-1]`) but is NOT an identifier character
+                // otherwise — otherwise `a-b` would read as one name and a typo would become a field.
+                if (input[i] === '-' && !out.includes('['))
+                    break;
+                if (input[i] === '-' && out.lastIndexOf('[') < out.lastIndexOf(']'))
+                    break;
+                out += input[i];
+                i++;
+            }
+            tokens.push({ kind: WORDS.has(out.toUpperCase()) ? 'word' : 'ident', value: out, pos });
+            continue;
+        }
+        throw new FilterError(`upstashvector: unexpected character '${c}' at position ${pos} in filter`);
+    }
+    return tokens;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// PARSER (recursive descent; AND binds tighter than OR, per the docs)
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+class Parser {
+    tokens;
+    source;
+    at = 0;
+    constructor(tokens, source) {
+        this.tokens = tokens;
+        this.source = source;
+    }
+    peek() { return this.tokens[this.at]; }
+    next() { return this.tokens[this.at++]; }
+    isWord(word, offset = 0) {
+        const t = this.tokens[this.at + offset];
+        return t !== undefined && t.kind === 'word' && t.value.toUpperCase() === word;
+    }
+    expectWord(word) {
+        if (!this.isWord(word))
+            throw new FilterError(`upstashvector: expected ${word} in filter '${this.source}'`);
+        this.at++;
+    }
+    parse() {
+        if (this.tokens.length === 0)
+            throw new FilterError('upstashvector: empty filter expression');
+        const node = this.parseOr();
+        const rest = this.peek();
+        if (rest !== undefined) {
+            throw new FilterError(`upstashvector: unexpected '${rest.value}' at position ${rest.pos} in filter '${this.source}'`);
+        }
+        // Validate every metadata PATH eagerly, at parse time.
+        //
+        // §9 round 1 found the bug this closes: a path like `a[0` (an unterminated subscript)
+        // tokenizes and parses fine, and only `parsePath` — called from `resolvePath` DURING
+        // EVALUATION — rejects it. That made the failure DATA-DEPENDENT: with rows present the
+        // FilterError escaped as an internal HTTP 500, and against an empty namespace the evaluator
+        // was never reached at all, so the same malformed filter answered 200 `[]`. A filter is either
+        // well-formed or it is not; that cannot depend on how many vectors happen to be stored.
+        validatePaths(node);
+        return node;
+    }
+    /** OR binds LOOSEST — "AND will have higher precedence than OR" (docs). */
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.isWord('OR')) {
+            this.at++;
+            left = { kind: 'or', left, right: this.parseAnd() };
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseUnary();
+        while (this.isWord('AND')) {
+            this.at++;
+            left = { kind: 'and', left, right: this.parseUnary() };
+        }
+        return left;
+    }
+    parseUnary() {
+        const t = this.peek();
+        if (t === undefined)
+            throw new FilterError(`upstashvector: unexpected end of filter '${this.source}'`);
+        if (t.kind === 'punct' && t.value === '(') {
+            this.at++;
+            const inner = this.parseOr();
+            const close = this.next();
+            if (close === undefined || close.value !== ')')
+                throw new FilterError(`upstashvector: unbalanced parenthesis in filter '${this.source}'`);
+            return inner;
+        }
+        // `HAS FIELD x` / `HAS NOT FIELD x` — the only prefix-form operators in the language.
+        if (this.isWord('HAS')) {
+            this.at++;
+            let negated = false;
+            if (this.isWord('NOT')) {
+                this.at++;
+                negated = true;
+            }
+            this.expectWord('FIELD');
+            const ident = this.next();
+            if (ident === undefined || ident.kind !== 'ident') {
+                throw new FilterError(`upstashvector: HAS ${negated ? 'NOT ' : ''}FIELD needs a metadata key in filter '${this.source}'`);
+            }
+            return { kind: 'hasField', path: ident.value, negated };
+        }
+        return this.parseComparison();
+    }
+    parseComparison() {
+        const ident = this.next();
+        if (ident === undefined || ident.kind !== 'ident') {
+            throw new FilterError(`upstashvector: expected a metadata key but found '${ident?.value ?? 'end of input'}' in filter '${this.source}'`);
+        }
+        const path = ident.value;
+        let negated = false;
+        if (this.isWord('NOT')) {
+            this.at++;
+            negated = true;
+        }
+        const op = this.next();
+        if (op === undefined)
+            throw new FilterError(`upstashvector: '${path}' has no operator in filter '${this.source}'`);
+        if (op.kind === 'word' && op.value.toUpperCase() === 'IN') {
+            return { kind: 'in', path, negated, values: this.parseList() };
+        }
+        if (op.kind === 'word' && op.value.toUpperCase() === 'GLOB') {
+            return { kind: 'compare', path, op: negated ? 'NOT GLOB' : 'GLOB', value: this.parseOperand() };
+        }
+        if (op.kind === 'word' && op.value.toUpperCase() === 'CONTAINS') {
+            return { kind: 'compare', path, op: negated ? 'NOT CONTAINS' : 'CONTAINS', value: this.parseOperand() };
+        }
+        if (negated) {
+            // `NOT` only prefixes IN / GLOB / CONTAINS; `a NOT = 1` is not the language.
+            throw new FilterError(`upstashvector: NOT must be followed by IN, GLOB or CONTAINS in filter '${this.source}'`);
+        }
+        if (op.kind !== 'op') {
+            throw new FilterError(`upstashvector: '${op.value}' is not a comparison operator in filter '${this.source}'`);
+        }
+        return { kind: 'compare', path, op: op.value, value: this.parseOperand() };
+    }
+    parseList() {
+        const open = this.next();
+        if (open === undefined || open.value !== '(')
+            throw new FilterError(`upstashvector: IN needs a parenthesised list in filter '${this.source}'`);
+        const values = [];
+        for (;;) {
+            const t = this.peek();
+            if (t === undefined)
+                throw new FilterError(`upstashvector: unterminated IN list in filter '${this.source}'`);
+            if (t.kind === 'punct' && t.value === ')') {
+                this.at++;
+                break;
+            }
+            values.push(this.parseOperand());
+            const sep = this.peek();
+            if (sep !== undefined && sep.kind === 'punct' && sep.value === ',') {
+                this.at++;
+                continue;
+            }
+            if (sep !== undefined && sep.kind === 'punct' && sep.value === ')') {
+                this.at++;
+                break;
+            }
+            throw new FilterError(`upstashvector: expected ',' or ')' in IN list in filter '${this.source}'`);
+        }
+        if (values.length === 0)
+            throw new FilterError(`upstashvector: empty IN list in filter '${this.source}'`);
+        return values;
+    }
+    /**
+     * A literal operand.
+     *
+     * BOOLEANS: the docs say "Boolean literals are represented as `1` or `0`", but their own `!=`
+     * example is `is_capital != true`. Both are accepted; `1`/`0` stay NUMBERS (so `population > 0`
+     * still compares numerically) and are matched against a boolean field by `looseEquals`.
+     */
+    parseOperand() {
+        const t = this.next();
+        if (t === undefined)
+            throw new FilterError(`upstashvector: expected a value in filter '${this.source}'`);
+        if (t.kind === 'string')
+            return t.value;
+        if (t.kind === 'number')
+            return Number(t.value);
+        if (t.kind === 'ident' || t.kind === 'word') {
+            const lower = t.value.toLowerCase();
+            if (lower === 'true')
+                return true;
+            if (lower === 'false')
+                return false;
+            // A bare word is not a literal — an unquoted string is the single commonest filter typo, and
+            // matching it against the field name would silently compare a value to itself.
+            throw new FilterError(`upstashvector: '${t.value}' at position ${t.pos} is not a literal — string values must be quoted in filter '${this.source}'`);
+        }
+        throw new FilterError(`upstashvector: unexpected '${t.value}' where a value was expected in filter '${this.source}'`);
+    }
+}
+/**
+ * Walk the AST and parse every metadata path, so a malformed one is a PARSE error.
+ * See the note in `Parser.parse` for the data-dependent-status bug this closes.
+ */
+function validatePaths(node) {
+    switch (node.kind) {
+        case 'and':
+        case 'or':
+            validatePaths(node.left);
+            validatePaths(node.right);
+            return;
+        case 'compare':
+        case 'in':
+        case 'hasField':
+            parsePath(node.path); // throws FilterError on a malformed path
+    }
+}
+/** Parse a filter string into an AST. Throws `FilterError` on anything malformed. */
+export function parseFilter(filter) {
+    return new Parser(tokenizeFilter(filter), filter).parse();
+}
+/**
+ * Split `geography.coordinates[0]` / `tags[#-1]` into steps.
+ *
+ * `[#-1]` is the docs' "index from the back using the `#` character with negative values": the
+ * `#` marks end-relative addressing and the value that follows is the offset, so `[#-1]` is the
+ * LAST element. A plain `[0]` is head-relative.
+ */
+export function parsePath(path) {
+    const steps = [];
+    let buf = '';
+    let i = 0;
+    const flush = () => { if (buf !== '') {
+        steps.push({ key: buf });
+        buf = '';
+    } };
+    while (i < path.length) {
+        const c = path[i];
+        if (c === '.') {
+            flush();
+            i++;
+            continue;
+        }
+        if (c === '[') {
+            flush();
+            const close = path.indexOf(']', i);
+            if (close === -1)
+                throw new FilterError(`upstashvector: unterminated '[' in metadata path '${path}'`);
+            const raw = path.slice(i + 1, close);
+            const fromEnd = raw.startsWith('#');
+            const digits = fromEnd ? raw.slice(1) : raw;
+            // `Number('')` is 0, so a BARE `a[]` used to parse as `a[0]` — silently addressing the first
+            // element of an array the caller never named an index for. Require an explicit integer
+            // literal rather than trusting the numeric coercion.
+            if (!/^-?\d+$/.test(digits)) {
+                throw new FilterError(`upstashvector: '${raw}' is not an array index in metadata path '${path}'`);
+            }
+            const n = Number(digits);
+            if (!Number.isInteger(n))
+                throw new FilterError(`upstashvector: '${raw}' is not an array index in metadata path '${path}'`);
+            steps.push({ index: n, fromEnd });
+            i = close + 1;
+            continue;
+        }
+        buf += c;
+        i++;
+    }
+    flush();
+    if (steps.length === 0)
+        throw new FilterError(`upstashvector: empty metadata path in filter`);
+    return steps;
+}
+/** The sentinel for "this path is not present". Distinct from a stored `null`, which IS present. */
+export const MISSING = Symbol('upstashvector.missing');
+/** Resolve a metadata path. Returns `MISSING` when any step is absent. */
+export function resolvePath(metadata, path) {
+    let cur = metadata;
+    for (const step of parsePath(path)) {
+        if (cur === null || cur === undefined)
+            return MISSING;
+        if ('key' in step) {
+            if (typeof cur !== 'object' || Array.isArray(cur))
+                return MISSING;
+            const rec = cur;
+            if (!Object.prototype.hasOwnProperty.call(rec, step.key))
+                return MISSING;
+            cur = rec[step.key];
+            continue;
+        }
+        if (!Array.isArray(cur))
+            return MISSING;
+        // `[#-1]` addresses from the end; `[0]` from the start. A negative head-relative index is not
+        // the documented spelling, so it simply misses rather than silently wrapping.
+        const idx = step.fromEnd ? cur.length + step.index : step.index;
+        if (!Number.isInteger(idx) || idx < 0 || idx >= cur.length)
+            return MISSING;
+        cur = cur[idx];
+    }
+    return cur;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// GLOB
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * SQLite-style GLOB: `*` any run, `?` one character, `[abc]` a class, `[^abc]` a negated class,
+ * `[a-z]` a range. Case-SENSITIVE (that is what distinguishes GLOB from LIKE).
+ *
+ * Implemented as a backtracking matcher rather than by translating to a RegExp: a translation has
+ * to escape every regex metacharacter that is ORDINARY in a glob (`.`, `+`, `(`, `$`, …), and
+ * missing one turns a filter into a different filter — a silent wrong-answer bug rather than an
+ * error. The docs' own example, `city GLOB '?[sz]*[^m-z]'`, exercises all four constructs.
+ */
+export function globMatch(pattern, subject) {
+    const walk = (p, s) => {
+        if (p === pattern.length)
+            return s === subject.length;
+        const pc = pattern[p];
+        if (pc === '*') {
+            // Collapse runs of `*` so `a**b` costs no more than `a*b`.
+            let q = p;
+            while (q < pattern.length && pattern[q] === '*')
+                q++;
+            for (let k = s; k <= subject.length; k++)
+                if (walk(q, k))
+                    return true;
+            return false;
+        }
+        if (s === subject.length)
+            return false;
+        if (pc === '?')
+            return walk(p + 1, s + 1);
+        if (pc === '[') {
+            const close = classEnd(pattern, p);
+            if (close === -1)
+                return pattern[p] === subject[s] && walk(p + 1, s + 1); // an unclosed '[' is a literal
+            const negated = pattern[p + 1] === '^';
+            const body = pattern.slice(p + 1 + (negated ? 1 : 0), close);
+            return inClass(body, subject[s]) !== negated && walk(close + 1, s + 1);
+        }
+        return pc === subject[s] && walk(p + 1, s + 1);
+    };
+    return walk(0, 0);
+}
+/** Index of the `]` closing the class opened at `open`, or -1. A `]` FIRST in the class is literal. */
+function classEnd(pattern, open) {
+    let i = open + 1;
+    if (pattern[i] === '^')
+        i++;
+    if (pattern[i] === ']')
+        i++; // a leading ']' is a literal member, not the terminator
+    for (; i < pattern.length; i++)
+        if (pattern[i] === ']')
+            return i;
+    return -1;
+}
+function inClass(body, ch) {
+    for (let i = 0; i < body.length; i++) {
+        // A range needs a `-` with members on BOTH sides; a trailing `-` is a literal hyphen.
+        if (body[i + 1] === '-' && i + 2 < body.length) {
+            const lo = body[i];
+            const hi = body[i + 2];
+            if (ch >= lo && ch <= hi)
+                return true;
+            i += 2;
+            continue;
+        }
+        if (body[i] === ch)
+            return true;
+    }
+    return false;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// EVALUATOR
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Compare a stored metadata value with a filter literal for EQUALITY.
+ *
+ * `1`/`0` are the docs' own boolean spelling, so a numeric 1 matches a stored `true`. Everything
+ * else is compared by JS `===` after that coercion, so `'5'` (a string literal) does NOT equal a
+ * stored number 5 — a filter language that silently coerced across types would make
+ * `price = '10'` match a `price: 10` field and mask the caller's bug.
+ */
+function looseEquals(stored, literal) {
+    if (typeof stored === 'boolean' && typeof literal === 'number')
+        return stored === (literal === 1);
+    if (typeof stored === 'boolean' && typeof literal === 'boolean')
+        return stored === literal;
+    return stored === literal;
+}
+/** Ordering comparison. Only like-typed operands are ordered; anything else simply does not match. */
+function ordered(stored, literal, op) {
+    if (typeof stored === 'number' && typeof literal === 'number') {
+        return op === '<' ? stored < literal : op === '>' ? stored > literal : op === '<=' ? stored <= literal : stored >= literal;
+    }
+    if (typeof stored === 'string' && typeof literal === 'string') {
+        return op === '<' ? stored < literal : op === '>' ? stored > literal : op === '<=' ? stored <= literal : stored >= literal;
+    }
+    return false;
+}
+/** Evaluate a parsed filter against one vector's metadata. */
+export function evaluateFilter(node, metadata) {
+    switch (node.kind) {
+        case 'and': return evaluateFilter(node.left, metadata) && evaluateFilter(node.right, metadata);
+        case 'or': return evaluateFilter(node.left, metadata) || evaluateFilter(node.right, metadata);
+        case 'hasField': {
+            const present = resolvePath(metadata, node.path) !== MISSING;
+            return node.negated ? !present : present;
+        }
+        case 'in': {
+            const v = resolvePath(metadata, node.path);
+            // A MISSING field is in no list — and is also not "NOT IN" anything, because the vendor's
+            // HAS FIELD operator exists precisely so that absence is asked about explicitly. Treating
+            // absence as a NOT IN match would make `country NOT IN ('X')` select vectors with no
+            // `country` at all, which is the classic filter-language footgun.
+            if (v === MISSING)
+                return false;
+            const hit = node.values.some((lit) => looseEquals(v, lit));
+            return node.negated ? !hit : hit;
+        }
+        case 'compare': {
+            const v = resolvePath(metadata, node.path);
+            if (v === MISSING)
+                return false; // same rule as IN: absence never satisfies a comparison
+            switch (node.op) {
+                case '=': return looseEquals(v, node.value);
+                case '!=': return !looseEquals(v, node.value);
+                case '<':
+                case '>':
+                case '<=':
+                case '>=': return ordered(v, node.value, node.op);
+                case 'GLOB': return typeof v === 'string' && typeof node.value === 'string' && globMatch(node.value, v);
+                case 'NOT GLOB': return typeof v === 'string' && typeof node.value === 'string' && !globMatch(node.value, v);
+                case 'CONTAINS': return Array.isArray(v) && v.some((el) => looseEquals(el, node.value));
+                case 'NOT CONTAINS': return Array.isArray(v) && !v.some((el) => looseEquals(el, node.value));
+            }
+        }
+    }
+}
+/** Parse + evaluate in one step. Exported for the handler's single call site. */
+export function matchesFilter(filter, metadata) {
+    return evaluateFilter(parseFilter(filter), metadata);
+}

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

@@ -0,0 +1,32 @@
+import type { SimilarityFunction } from './upstashvector-store.js';
+export type UpstashVectorServerOptions = {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    /** The token the twin demands. Omit to accept any non-empty credential (still 401s a missing one). */
+    token?: string;
+    /** The dimension this index enforces. Omit to let the first upsert lock one in. */
+    dimension?: number;
+    /** The metric this index ranks with. Defaults to COSINE. */
+    similarityFunction?: SimilarityFunction;
+    /** The injected clock. Returns the ISO instant this request "happens at". */
+    now?: () => string;
+};
+/** Options every Upstash Vector-twin HTTP surface needs, independent of who owns the socket. */
+export interface UpstashVectorTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    /** The token the twin demands. Omit to accept any non-empty credential (still 401s a missing one). */
+    token?: string;
+    /** The dimension this index enforces. Omit to let the first upsert lock one in. */
+    dimension?: number;
+    /** The metric this index ranks with. Defaults to COSINE. */
+    similarityFunction?: SimilarityFunction;
+    /** The injected clock. Returns the ISO instant this request "happens at". */
+    now?: () => string;
+}
+export declare function createUpstashVectorTwinFetch(options?: UpstashVectorTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createUpstashVectorTwinServer(options?: UpstashVectorServerOptions): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/upstashvector-server.js

@@ -0,0 +1,56 @@
+// upstashvector twin HTTP server — serve the Upstash Vector REST twin over HTTP so the real
+// `@upstash/vector` SDK (pointed at it with nothing but its own public `url` option) works
+// UNMODIFIED.
+//
+// ── THE INDEX IS CONFIGURED HERE, NOT DISCOVERED ──────────────────────────────────────────────
+// A real Upstash Vector index is created with a fixed `dimension` and `similarityFunction` and can
+// never change them. A twin has no creation step, so those become server options: pass them and the
+// index behaves exactly like one created that way (including the vendor's 422 on a mismatched
+// vector); omit `dimension` and the FIRST upsert locks one in, which is the convenient local
+// default. `similarityFunction` defaults to COSINE, the console's own default.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createUpstashVectorTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): replies carry ONLY the handler's own headers, and the clock is
+// an injectable seam.
+import { serveHttp } from '@volter/world-core';
+import { handleUpstashVectorTwinRequest } from "./upstashvector-twin.js";
+import { worldNow, statefulTwinManifest } from '@volter/world-core';
+export function createUpstashVectorTwinFetch(options = {}) {
+    const readOnly = options.readOnly ?? false;
+    const now = options.now ?? (() => worldNow());
+    return async function upstashVectorTwinFetch(request) {
+        const url = new URL(request.url);
+        // GET /twin — the discovery manifest (education inside the twin).
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+            return Response.json(statefulTwinManifest({ vendor: 'upstashvector', twinOf: 'the Upstash Vector REST API', stores: 'namespaces and vectors, queried by a real scorer' }));
+        }
+        const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.text() : '';
+        const headers = {};
+        request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+        const { status, body: out, headers: outHeaders } = await handleUpstashVectorTwinRequest({
+            method: request.method,
+            path: url.pathname + (url.search || ''),
+            body,
+            headers,
+            readOnly,
+            occurredAt: now(),
+            ...(options.root !== undefined ? { root: options.root } : {}),
+            ...(options.token !== undefined ? { token: options.token } : {}),
+            ...(options.dimension !== undefined ? { dimension: options.dimension } : {}),
+            ...(options.similarityFunction !== undefined ? { similarityFunction: options.similarityFunction } : {}),
+        });
+        // A null body means "no body at all" (HEAD, CORS preflight).
+        if (out === null)
+            return new Response(null, { status, headers: { ...(outHeaders ?? {}) } });
+        return new Response(JSON.stringify(out), { status, headers: { ...(outHeaders ?? {}) } });
+    };
+}
+export async function createUpstashVectorTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createUpstashVectorTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}