@kernl-sdk/turbopuffer 0.1.3 → 0.1.5

package/dist/convert.js

@@ -1,333 +0,0 @@
-/**
- * Codecs for converting between kernl and Turbopuffer types.
- */
-/**
- * Codec for converting kernl scalar types to Turbopuffer attribute types.
- */
-export const SCALAR_TYPE = {
-    encode: (type) => {
-        switch (type) {
-            case "string":
-                return "string";
-            case "int":
-                return "int";
-            case "float":
-                return "int"; // tpuf doesn't have float
-            case "boolean":
-                return "bool";
-            case "date":
-                return "datetime";
-            case "string[]":
-                return "[]string";
-            case "int[]":
-                return "[]int";
-            case "date[]":
-                return "[]datetime";
-            default:
-                return "string";
-        }
-    },
-    decode: (type) => {
-        switch (type) {
-            case "string":
-                return "string";
-            case "int":
-                return "int";
-            case "bool":
-                return "boolean";
-            case "datetime":
-                return "date";
-            case "[]string":
-                return "string[]";
-            case "[]int":
-                return "int[]";
-            case "[]datetime":
-                return "date[]";
-            default:
-                return "string";
-        }
-    },
-};
-/**
- * Codec for converting similarity metric to Turbopuffer distance metric.
- *
- * Turbopuffer supports: cosine_distance, euclidean_squared
- * We support: cosine, euclidean, dot_product
- */
-export const SIMILARITY = {
-    encode: (similarity) => {
-        switch (similarity) {
-            case "euclidean":
-                return "euclidean_squared";
-            case "cosine":
-            case "dot_product":
-            default:
-                return "cosine_distance";
-        }
-    },
-    decode: (metric) => {
-        switch (metric) {
-            case "euclidean_squared":
-                return "euclidean";
-            case "cosine_distance":
-            default:
-                return "cosine";
-        }
-    },
-};
-/**
- * Codec-like converter for FieldSchema to Turbopuffer AttributeSchema.
- *
- * Takes the field name as context since Turbopuffer requires `ann: true`
- * only on the special `vector` attribute.
- */
-export const FIELD_SCHEMA = {
-    encode: (field, name) => {
-        // Vector fields
-        if (field.type === "vector" || field.type === "sparse-vector") {
-            const vf = field;
-            const precision = vf.quantization === "f16" ? "f16" : "f32";
-            return {
-                type: `[${vf.dimensions}]${precision}`,
-                ann: name === "vector",
-            };
-        }
-        // Scalar fields
-        const config = {
-            type: SCALAR_TYPE.encode(field.type),
-        };
-        if (field.filterable) {
-            config.filterable = true;
-        }
-        if (field.fts) {
-            config.full_text_search =
-                typeof field.fts === "object"
-                    ? { language: field.fts.language }
-                    : true;
-        }
-        return config;
-    },
-    decode: () => {
-        throw new Error("FIELD_SCHEMA.decode: not implemented");
-    },
-};
-/**
- * Codec for converting a full schema record.
- *
- * Validates that vector fields are named `vector` since Turbopuffer only
- * supports ANN indexing on that specific attribute name.
- */
-export const INDEX_SCHEMA = {
-    encode: (schema) => {
-        const result = {};
-        for (const [name, field] of Object.entries(schema)) {
-            const isVector = field.type === "vector" || field.type === "sparse-vector";
-            // Enforce vector field naming
-            if (isVector && name !== "vector") {
-                throw new Error(`Turbopuffer requires vector fields to be named "vector", got "${name}". ` +
-                    `Rename your field or use a different search provider.`);
-            }
-            result[name] = FIELD_SCHEMA.encode(field, name);
-        }
-        return result;
-    },
-    decode: () => {
-        throw new Error("INDEX_SCHEMA.decode: not implemented");
-    },
-};
-/**
- * Check if a value is a DenseVector.
- */
-function isDenseVector(val) {
-    return (typeof val === "object" &&
-        val !== null &&
-        "kind" in val &&
-        val.kind === "vector");
-}
-/**
- * Convert a FieldValue to Turbopuffer attribute value.
- * Extracts vector values from DenseVector wrapper.
- */
-function encodeFieldValue(val) {
-    if (isDenseVector(val)) {
-        return val.values;
-    }
-    return val;
-}
-/**
- * Codec for converting SearchDocument to Turbopuffer Row.
- */
-export const DOCUMENT = {
-    encode: (doc) => {
-        const row = { id: doc.id };
-        for (const [key, val] of Object.entries(doc.fields)) {
-            row[key] = encodeFieldValue(val);
-        }
-        return row;
-    },
-    decode: (_row) => {
-        throw new Error("DOCUMENT.decode: not implemented");
-    },
-};
-const FILTER_OP_MAP = {
-    eq: "Eq",
-    neq: "NotEq",
-    gt: "Gt",
-    gte: "Gte",
-    lt: "Lt",
-    lte: "Lte",
-    in: "In",
-    nin: "NotIn",
-    contains: "Contains",
-    starts_with: "Glob", // will add * suffix
-    ends_with: "Glob", // will add * prefix
-    contains_all: "ContainsAny", // closest match
-    contains_any: "ContainsAny",
-};
-/**
- * Type guards for filter expressions.
- */
-function isFieldFilter(f) {
-    return "field" in f && "op" in f && "value" in f;
-}
-function isExistsFilter(f) {
-    return ("field" in f && "op" in f && (f.op === "exists" || f.op === "not_exists"));
-}
-function isAndFilter(f) {
-    return "and" in f;
-}
-function isOrFilter(f) {
-    return "or" in f;
-}
-function isNotFilter(f) {
-    return "not" in f;
-}
-/**
- * Codec for converting FilterExpression to Turbopuffer Filter.
- */
-export const FILTER = {
-    encode: (filter) => {
-        if (isAndFilter(filter)) {
-            return ["And", filter.and.map(FILTER.encode)];
-        }
-        if (isOrFilter(filter)) {
-            return ["Or", filter.or.map(FILTER.encode)];
-        }
-        if (isNotFilter(filter)) {
-            return ["Not", FILTER.encode(filter.not)];
-        }
-        if (isExistsFilter(filter)) {
-            // exists → NotEq null, not_exists → Eq null
-            return filter.op === "exists"
-                ? [filter.field, "NotEq", null]
-                : [filter.field, "Eq", null];
-        }
-        if (isFieldFilter(filter)) {
-            const { field, op, value } = filter;
-            // Handle glob patterns for starts_with/ends_with
-            if (op === "starts_with") {
-                return [field, "Glob", `${value}*`];
-            }
-            if (op === "ends_with") {
-                return [field, "Glob", `*${value}`];
-            }
-            const tpufOp = FILTER_OP_MAP[op];
-            return [field, tpufOp, value];
-        }
-        throw new Error(`Unknown filter type: ${JSON.stringify(filter)}`);
-    },
-    decode: (_filter) => {
-        throw new Error("FILTER.decode: not implemented");
-    },
-};
-/**
- * Build rank_by for vector search.
- */
-function buildVectorRankBy(vector) {
-    return ["vector", "ANN", vector];
-}
-/**
- * Build rank_by for full-text search.
- */
-function buildTextRankBy(text, fields) {
-    if (!fields || fields.length === 0) {
-        throw new Error("textFields required for full-text search");
-    }
-    if (fields.length === 1) {
-        return [fields[0], "BM25", text];
-    }
-    // Multiple fields: combine with Sum
-    const subQueries = fields.map((field) => [field, "BM25", text]);
-    return ["Sum", subQueries];
-}
-/**
- * Codec for converting SearchQuery to Turbopuffer NamespaceQueryParams.
- *
- * Note: Hybrid search (vector + text) requires multi-query which is
- * handled separately.
- */
-export const QUERY = {
-    encode: (query) => {
-        const params = {};
-        // Determine ranking method
-        if (query.vector) {
-            params.rank_by = buildVectorRankBy(query.vector);
-        }
-        else if (query.text) {
-            params.rank_by = buildTextRankBy(query.text, query.textFields);
-        }
-        // Top K
-        if (query.topK !== undefined) {
-            params.top_k = query.topK;
-        }
-        // Filters
-        if (query.filter) {
-            params.filters = FILTER.encode(query.filter);
-        }
-        // Include attributes
-        if (query.includeFields !== undefined) {
-            if (typeof query.includeFields === "boolean") {
-                params.include_attributes = query.includeFields;
-            }
-            else {
-                const attrs = [...query.includeFields];
-                if (query.includeVectors && !attrs.includes("vector")) {
-                    attrs.push("vector");
-                }
-                params.include_attributes = attrs;
-            }
-        }
-        else if (query.includeVectors) {
-            params.include_attributes = true; // include all to get vector
-        }
-        return params;
-    },
-    decode: (_params) => {
-        throw new Error("QUERY.decode: not implemented");
-    },
-};
-/**
- * Codec for converting Turbopuffer Row to SearchHit.
- */
-export const SEARCH_HIT = {
-    encode: (_hit) => {
-        throw new Error("SEARCH_HIT.encode: not implemented");
-    },
-    decode: (row, index) => {
-        const { id, $dist, vector, ...rest } = row;
-        const hit = {
-            id: String(id),
-            index,
-            score: typeof $dist === "number" ? $dist : 0,
-        };
-        // Include vector if present
-        if (vector !== undefined) {
-            hit.vector = vector;
-        }
-        // Include other fields
-        if (Object.keys(rest).length > 0) {
-            hit.fields = rest;
-        }
-        return hit;
-    },
-};