tsense 0.1.0 → 0.2.0-next.0

package/dist/tsense.js

@@ -9,6 +9,23 @@ function chunkArray(arr, size) {
     return chunks;
 }
 const redaxiosInstance = redaxios.default ?? redaxios;
+function escapeFilterValue(value) {
+    if (typeof value === "string") {
+        return `\`${value.replaceAll("`", "")}\``;
+    }
+    if (Array.isArray(value)) {
+        return value.map(escapeFilterValue);
+    }
+    return value;
+}
+const filterOperators = {
+    not: (k, v) => `${k}:!=${v}`,
+    gt: (k, v) => `${k}:>${v}`,
+    gte: (k, v) => `${k}:>=${v}`,
+    lt: (k, v) => `${k}:<${v}`,
+    lte: (k, v) => `${k}:<=${v}`,
+    notIn: (k, v) => `${k}:!=[${v.join(",")}]`,
+};
 const arkToTsense = {
     string: "string",
     number: "float",
@@ -27,16 +44,13 @@ export class TSense {
     fieldTransformers = new Map();
     dataSyncConfig;
     infer = undefined;
-    getFields() {
-        return this.fields;
-    }
     constructor(options) {
         this.options = options;
         this.axios = redaxiosInstance.create({
             baseURL: `${options.connection.protocol}://${options.connection.host}:${options.connection.port}`,
             headers: { "X-TYPESENSE-API-KEY": options.connection.apiKey },
         });
-        this.extractFields(options.transformers ?? defaultTransformers);
+        this.fields = this.extractFields(options.transformers ?? defaultTransformers);
         this.dataSyncConfig = options.dataSync;
     }
     getBaseType(expression, domain) {
@@ -80,27 +94,38 @@ export class TSense {
         if (Array.isArray(value)) {
             return value.map((v) => transformer.serialize(v));
         }
-        if (typeof value === "object" && value !== null) {
-            const v = value;
-            const isFilterObject = "min" in v || "max" in v || "not" in v;
-            if (!isFilterObject) {
-                return transformer.serialize(value);
+        if (typeof value === "object" &&
+            value !== null &&
+            Object.getPrototypeOf(value) === Object.prototype) {
+            const result = {};
+            for (const [opKey, opValue] of Object.entries(value)) {
+                if (opValue == null) {
+                    result[opKey] = opValue;
+                    continue;
+                }
+                if (Array.isArray(opValue)) {
+                    result[opKey] = opValue.map((item) => transformer.serialize(item));
+                }
+                else {
+                    result[opKey] = transformer.serialize(opValue);
+                }
             }
-            const result = { ...v };
-            if ("min" in v && v.min != null)
-                result.min = transformer.serialize(v.min);
-            if ("max" in v && v.max != null)
-                result.max = transformer.serialize(v.max);
-            if ("not" in v && v.not != null)
-                result.not = transformer.serialize(v.not);
             return result;
         }
         return transformer.serialize(value);
     }
     extractFields(transformers) {
         const internal = this.options.schema;
+        const fields = [];
         for (const prop of internal.structure.props) {
-            const innerType = prop.value.branches?.[0] ?? prop.value;
+            const branches = prop.value.branches ?? [];
+            const enumValues = [];
+            for (const branch of branches) {
+                if (typeof branch.unit === "string") {
+                    enumValues.push(branch.unit);
+                }
+            }
+            const innerType = branches[0] ?? prop.value;
             const meta = (innerType.meta ?? prop.value.meta);
             const expression = String(prop.value.expression);
             const domain = prop.value.domain;
@@ -108,26 +133,31 @@ export class TSense {
             const transformer = transformers.find((t) => t.match(expression, domain) || t.match(baseType, domain));
             if (transformer) {
                 this.fieldTransformers.set(prop.key, transformer);
-                this.fields.push({
+                fields.push({
                     name: prop.key,
                     type: transformer.storageType,
+                    sourceExpression: expression,
                     optional: prop.kind === "optional",
                     facet: meta?.facet,
                     sort: meta?.sort,
                     index: meta?.index,
+                    enumValues,
                 });
                 continue;
             }
             const type = meta?.type ?? this.inferType(baseType);
-            this.fields.push({
+            fields.push({
                 name: prop.key,
                 type,
+                sourceExpression: expression,
                 optional: prop.kind === "optional",
                 facet: meta?.facet,
                 sort: meta?.sort,
                 index: meta?.index,
+                enumValues,
             });
         }
+        return fields;
     }
     async ensureSynced(force) {
         if (!force && (this.synced || !this.options.autoSyncSchema))
@@ -139,24 +169,30 @@ export class TSense {
         await this.ensureSynced(true);
     }
     buildObjectFilter(key, value) {
-        if (Array.isArray(value)) {
-            return `(${key}:[${value.join(",")}])`;
-        }
-        const v = value;
-        if ("not" in v) {
-            return `${key}:!=${v.not}`;
-        }
-        const min = v.min ?? undefined;
-        const max = v.max ?? undefined;
-        if (min != null && max != null) {
-            return `${key}:[${min}..${max}]`;
-        }
-        if (max != null) {
-            return `${key}:<=${max}`;
+        if (value.gte != null && value.lte != null) {
+            const escaped = escapeFilterValue(value.gte);
+            const escapedLte = escapeFilterValue(value.lte);
+            const parts = [`${key}:[${escaped}..${escapedLte}]`];
+            for (const [op, opValue] of Object.entries(value)) {
+                if (op === "gte" || op === "lte" || opValue == null)
+                    continue;
+                const builder = filterOperators[op];
+                if (builder) {
+                    parts.push(builder(key, escapeFilterValue(opValue)));
+                }
+            }
+            return parts;
         }
-        if (min != null) {
-            return `${key}:>=${min}`;
+        const parts = [];
+        for (const [op, opValue] of Object.entries(value)) {
+            if (opValue == null)
+                continue;
+            const builder = filterOperators[op];
+            if (builder) {
+                parts.push(builder(key, escapeFilterValue(opValue)));
+            }
         }
+        return parts;
     }
     buildFilter(filter) {
         const result = [];
@@ -165,33 +201,40 @@ export class TSense {
             if (rawValue == null)
                 continue;
             if (key === "OR") {
-                const orFilter = [];
+                const orParts = [];
                 for (const condition of rawValue) {
                     const inner = this.buildFilter(condition);
-                    orFilter.push(`(${inner.join("||")})`);
+                    orParts.push(`(${inner.join("&&")})`);
                 }
-                result.push(`(${orFilter.join("||")})`);
+                result.push(`(${orParts.join("||")})`);
                 continue;
             }
             const value = this.serializeFilterValue(key, rawValue);
-            switch (typeof value) {
-                case "string":
-                case "number":
-                case "boolean":
-                    result.push(`${key}:=${value}`);
-                    break;
-                case "object": {
-                    const built = this.buildObjectFilter(key, value);
-                    if (built)
-                        result.push(built);
-                    break;
-                }
-                default:
-                    break;
+            const escaped = escapeFilterValue(value);
+            if (typeof escaped === "string" ||
+                typeof escaped === "number" ||
+                typeof escaped === "boolean") {
+                result.push(`${key}:=${escaped}`);
+                continue;
+            }
+            if (Array.isArray(escaped)) {
+                result.push(`${key}:[${escaped.join(",")}]`);
+                continue;
+            }
+            if (typeof value === "object" && value !== null) {
+                result.push(...this.buildObjectFilter(key, value));
             }
         }
         return result;
     }
+    validateFields(fields) {
+        const valid = new Set(this.fields.map((f) => f.name));
+        for (const field of fields) {
+            if (field !== "score" && !valid.has(field)) {
+                throw new Error(`INVALID_FIELD: ${field}`);
+            }
+        }
+    }
     buildSort(options) {
         if (!options.sortBy)
             return;
@@ -289,9 +332,22 @@ export class TSense {
     }
     async search(options) {
         await this.ensureSynced();
+        const queryByFields = options.queryBy ?? [
+            this.options.defaultSearchField,
+        ];
+        this.validateFields(queryByFields);
+        if (options.sortBy) {
+            this.validateFields(options.sortBy
+                .map((s) => s.split(":")[0])
+                .filter((f) => f !== "undefined"));
+        }
+        if (options.facetBy) {
+            this.validateFields(options.facetBy);
+        }
+        const queryBy = queryByFields.join(",");
         const params = {
-            q: options.query ?? "",
-            query_by: (options.queryBy ?? [this.options.defaultSearchField]).join(","),
+            q: options.query ?? "*",
+            query_by: queryBy,
         };
         const sortBy = this.buildSort(options);
         if (sortBy)
@@ -313,10 +369,8 @@ export class TSense {
             params.exclude_fields = options.omit.join(",");
         }
         const highlight = options.highlight;
-        const highlightEnabled = !!highlight;
-        let highlightOpts;
-        if (typeof highlight === "object") {
-            highlightOpts = highlight;
+        const highlightOpts = typeof highlight === "object" ? highlight : undefined;
+        if (highlightOpts) {
             if (highlightOpts.fields) {
                 params.highlight_fields = highlightOpts.fields.join(",");
             }
@@ -335,7 +389,7 @@ export class TSense {
         const data = [];
         const scores = [];
         for (const hit of res.hits ?? []) {
-            if (highlightEnabled) {
+            if (highlight) {
                 const fieldsToHighlight = highlightOpts?.fields;
                 for (const [key, value] of Object.entries(hit.highlight ?? {})) {
                     if (!value?.snippet)
@@ -365,35 +419,22 @@ export class TSense {
         };
     }
     async searchList(options) {
-        await this.ensureSynced();
-        const limit = Math.min(options.limit ?? 20, 100);
-        const field = options.sort.field;
         const page = options.cursor ? Number(options.cursor) : 1;
-        const params = {
-            q: options.query ?? "",
-            query_by: (options.queryBy ?? [this.options.defaultSearchField]).join(","),
-            per_page: limit,
+        const limit = Math.min(options.limit ?? 20, 100);
+        const result = await this.search({
+            query: options.query,
+            queryBy: options.queryBy,
+            filter: options.filter,
+            sortBy: [options.sortBy],
             page,
-            sort_by: `${field}:${options.sort.direction}`,
-        };
-        const filterParts = this.buildFilter(options.filter);
-        const filterBy = filterParts.join("&&");
-        if (filterBy)
-            params.filter_by = filterBy;
-        const { data: res } = await this.axios({
-            method: "GET",
-            url: `/collections/${this.options.name}/documents/search`,
-            params,
+            limit,
         });
-        const hits = res.hits ?? [];
-        const data = [];
-        for (const hit of hits) {
-            const doc = this.deserializeDoc(hit.document);
-            data.push(doc);
-        }
-        const hasMore = page * limit < res.found;
-        const nextCursor = hasMore ? String(page + 1) : null;
-        return { data, nextCursor, total: res.found };
+        const hasMore = page * limit < result.count;
+        return {
+            data: result.data,
+            nextCursor: hasMore ? String(page + 1) : null,
+            total: result.count,
+        };
     }
     async count(filter) {
         await this.ensureSynced();
@@ -405,15 +446,16 @@ export class TSense {
             });
             return data.num_documents;
         }
+        const params = {
+            q: "*",
+            query_by: this.options.defaultSearchField,
+            per_page: 0,
+            filter_by: filterBy,
+        };
         const { data } = await this.axios({
             method: "GET",
             url: `/collections/${this.options.name}/documents/search`,
-            params: {
-                q: "*",
-                query_by: this.options.defaultSearchField,
-                per_page: 0,
-                filter_by: filterBy,
-            },
+            params,
         });
         return data.found;
     }
@@ -427,7 +469,9 @@ export class TSense {
                 this.options.schema.assert(item);
             }
         }
-        const payload = items.map((item) => JSON.stringify(this.serializeDoc(item))).join("\n");
+        const payload = items
+            .map((item) => JSON.stringify(this.serializeDoc(item)))
+            .join("\n");
         const params = { action: "upsert" };
         if (this.options.batchSize) {
             params.batch_size = this.options.batchSize;
@@ -492,4 +536,19 @@ export class TSense {
             .filter((line) => line.length)
             .map((line) => JSON.parse(line).id);
     }
+    scoped(baseFilter) {
+        return {
+            search: (options) => this.search({
+                ...options,
+                filter: { ...options.filter, ...baseFilter },
+            }),
+            searchList: (options) => this.searchList({
+                ...options,
+                filter: { ...options.filter, ...baseFilter },
+            }),
+            count: (filter) => this.count({ ...filter, ...baseFilter }),
+            deleteMany: (filter) => this.deleteMany({ ...filter, ...baseFilter }),
+            updateMany: (filter, data) => this.updateMany({ ...filter, ...baseFilter }, data),
+        };
+    }
 }

package/dist/types.d.ts

@@ -4,10 +4,12 @@ type BaseIfArray<T> = T extends (infer Q)[] ? Q : T;
 export type FieldSchema = {
     name: string;
     type: string;
+    sourceExpression?: string;
     facet?: boolean;
     sort?: boolean;
     index?: boolean;
     optional?: boolean;
+    enumValues?: string[];
 };
 export type SearchHit<T> = {
     document: T;
@@ -46,13 +48,29 @@ export type TsenseOptions<T extends Type> = {
     transformers?: FieldTransformer[];
     dataSync?: SyncConfig<T["infer"]>;
 };
+export type StringFilter = {
+    not?: string;
+    notIn?: string[];
+};
+export type NumberFilter = {
+    not?: number;
+    notIn?: number[];
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+};
+type DateFilter = {
+    not?: Date;
+    notIn?: Date[];
+    gt?: Date;
+    gte?: Date;
+    lt?: Date;
+    lte?: Date;
+};
+type FilterValueFor<T> = [T] extends [boolean] ? boolean : [T] extends [Date] ? Date | Date[] | DateFilter : [T] extends [number] ? number | number[] | NumberFilter : [T] extends [string] ? T | T[] | StringFilter : never;
 type SingleFilter<T> = Partial<{
-    [K in keyof T]: BaseIfArray<T[K]> | NonNullable<BaseIfArray<T[K]>>[] | {
-        not?: BaseIfArray<T[K]>;
-    } | (NonNullable<T[K]> extends number | Date ? NonNullable<T[K]> extends infer Type ? {
-        min?: Type;
-        max?: Type;
-    } : never : never);
+    [K in keyof T]: FilterValueFor<NonNullable<BaseIfArray<T[K]>>>;
 }>;
 export type FilterFor<T> = SingleFilter<T> & {
     OR?: FilterFor<T>[];
@@ -108,15 +126,17 @@ export type UpsertResult = {
     error?: string;
     document?: unknown;
 };
-type SearchListSort<T> = {
-    field: keyof T;
-    direction: "asc" | "desc";
+export type SearchInput<T> = {
+    query?: string;
+    filter?: FilterFor<T>;
+    page?: number;
+    limit?: number;
 };
 export type SearchListOptions<T> = {
     query?: string;
     queryBy?: (keyof T)[];
     filter?: FilterFor<T>;
-    sort: SearchListSort<T>;
+    sortBy: `${Extract<keyof T, string>}:${"asc" | "desc"}`;
     limit?: number;
     cursor?: string;
 };
@@ -125,6 +145,13 @@ export type SearchListResult<T> = {
     nextCursor: string | null;
     total: number;
 };
+export type ScopedCollection<T> = {
+    search: <const O extends SearchOptions<T> = SearchOptionsPlain<T>>(options: O) => Promise<SearchResult<ProjectSearch<T, O>>>;
+    searchList: (options: SearchListOptions<T>) => Promise<SearchListResult<T>>;
+    count: (filter?: FilterFor<T>) => Promise<number>;
+    deleteMany: (filter: FilterFor<T>) => Promise<DeleteResult>;
+    updateMany: (filter: FilterFor<T>, data: Partial<T>) => Promise<UpdateResult>;
+};
 export type SyncConfig<T> = {
     getAllIds: () => Promise<string[]>;
     getItems: (ids: string[]) => Promise<T[]>;

package/package.json

@@ -1,51 +1,70 @@
 {
-	"name": "tsense",
-	"version": "0.1.0",
-	"private": false,
-	"description": "Opinionated, fully typed typesense client",
-	"keywords": [
-		"typesense"
-	],
-	"homepage": "https://github.com/lobomfz/tsense",
-	"license": "MIT",
-	"files": [
-		"dist"
-	],
-	"type": "module",
-	"sideEffects": false,
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"scripts": {
-		"build": "tsc",
-		"ci": "bun run build && bun run format && bun run check-exports",
-		"test": "bun test",
-		"format": "oxfmt check --write src tests",
-		"check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
-		"local-release": "changeset version && changeset publish",
-		"prepublishOnly": "bun run ci"
-	},
-	"dependencies": {
-		"redaxios": "^0.5.1"
-	},
-	"devDependencies": {
-		"@arethetypeswrong/cli": "^0.18.2",
-		"@changesets/cli": "^2.30.0",
-		"@types/bun": "latest",
-		"@typescript/native-preview": "^7.0.0-dev.20260324.1",
-		"arktype": "^2.2.0",
-		"oxfmt": "^0.42.0",
-		"oxlint": "^1.57.0"
-	},
-	"peerDependencies": {
-		"arktype": "^2.1.29"
-	}
-}
+  "name": "tsense",
+  "version": "0.2.0-next.0",
+  "private": false,
+  "description": "Opinionated, fully typed typesense client",
+  "keywords": [
+    "typesense"
+  ],
+  "homepage": "https://github.com/lobomfz/tsense",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./filters": {
+      "types": "./dist/filters/index.d.ts",
+      "import": "./dist/filters/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsgo",
+    "check": "bun run scripts/check.ts",
+    "ci": "bun run build && bun run format && bun run check-exports",
+    "test": "bun test",
+    "format": "oxfmt check --write src tests",
+    "check-exports": "attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution",
+    "local-release": "changeset version && changeset publish",
+    "prepublishOnly": "bun run ci"
+  },
+  "dependencies": {
+    "redaxios": "^0.5.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@changesets/cli": "^2.30.0",
+    "@types/bun": "latest",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@typescript/native-preview": "^7.0.0-dev.20260324.1",
+    "arktype": "^2.2.0",
+    "jscpd": "^4.0.8",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "react": "^19.2.4"
+  },
+  "peerDependencies": {
+    "arktype": "^2.1.29",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}