tsense 0.0.4 → 0.0.6

package/README.md

@@ -1,125 +1,151 @@
-## TSense (WIP)
+# TSense
 
-Opinionated, fully-typed typesense client
+Opinionated, fully-typed Typesense client powered by [Arktype](https://arktype.io/)
 
-# TO-DO
-- [ ] Remove base typesense dependency
-- [ ] Better filter support (includes, exact, etc...)
-- [ ] Documentation
-- [ ] Improve tests
-- [ ] Facet
+## Installation
+
+```bash
+bun add tsense arktype
+```
+
+## Example
 
-# Example
 ```typescript
-import { Client } from "typesense";
+import { type } from "arktype";
 import { TSense } from "tsense";
 
-export const client = new Client({
-	nodes: [
-		{
-			host: "127.0.0.1",
-			port: 8108,
-			protocol: "http",
-		},
-	],
-	apiKey: "123",
-	connectionTimeoutSeconds: 2,
+const UsersCollection = new TSense({
+  name: "users",
+  schema: type({
+    "id?": "string",
+    email: "string",
+    age: type("number.integer").configure({ type: "int32", sort: true }),
+    "company?": type.enumerated("netflix", "google").configure({ facet: true }),
+    "phone?": "string",
+    name: type("string").configure({ sort: true }),
+    "work_history?": type({
+      company: "string",
+      date: "string",
+    })
+      .array()
+      .configure({ type: "object[]", index: false }),
+  }),
+  connection: {
+    host: "127.0.0.1",
+    port: 8108,
+    protocol: "http",
+    apiKey: "123",
+  },
+  defaultSearchField: "name",
+  validateOnUpsert: true,
 });
 
-export const UsersCollection = new TSense("users", {
-	client,
-	fields: {
-		// specify the typesense type directly as a string
-		email: "string",
-		age: "int32",
-		// suffix it with a "?" to mark as optional
-		phone: "string?",
-		name: {
-			type: "string",
-			sort: true,
-		},
-		company: {
-			type: "string",
-			override: {} as "netflix" | "google",
-			facet: true,
-			optional: true,
-		},
-		work_history: {
-			// object and object[] auto-infers enable_nested_fields
-			type: "object[]",
-			index: false,
-			optional: true,
-			override: {} as {
-				company: string;
-				date: string;
-			}[],
-		},
-	},
-	default_search_field: "name",
+await UsersCollection.create();
+
+await UsersCollection.upsert([
+  { id: "1", email: "john@example.com", age: 30, name: "John Doe", company: "netflix" },
+  { id: "2", email: "jane@example.com", age: 25, name: "Jane Smith", company: "google" },
+]);
+
+const results = await UsersCollection.search({
+  query: "john",
+  queryBy: ["name", "email"],
+  sortBy: ["age:desc", "name:asc"],
+  filter: {
+    age: { min: 20 },
+    OR: [{ company: "google" }, { company: "netflix" }],
+  },
 });
 
-// infer the collection type (undefined at runtime)
-typeof UsersCollection.infer;
-/*
- {
-     id?: string | undefined;
-     phone?: string | null | undefined;
-     work_history?: {
-         company: string;
-         date: string;
-     }[] | null | undefined;
-     email: string;
-     age: number;
-     name: string;
- }
- */
-
-const results = await UsersCollection.searchDocuments({
-	search: "john",
-	search_keys: ["name"],
-	// can sort multiple fields
-	order_by: ["age desc", "name asc"],
-	// compiles into
-	// age:>=20&&((email:=@google.com)||(email:=@netflix.com))
-	filter: {
-		// min and max range on numbers
-		age: {
-			min: 20,
-		},
-		// OR syntax similar to prisma
-		OR: [
-			{
-				email: "@google.com",
-			},
-			{
-				email: "@netflix.com",
-			},
-		],
-	},
+const faceted = await UsersCollection.search({
+  query: "john",
+  facetBy: ["company"],
 });
 
-/*
-   typed as
-   count: number;
-   data: {
-        id?: string | undefined;
-        phone?: string | null | undefined;
-        ...
-	}[];
-   facet: {
-        netflix: number;
-        google: number;
-		// enabled by enable_facet_total
-        total: number;
-    };
- */
-const faceted = await UsersCollection.searchDocuments(
-	{
-		search: "john",
-	},
-	{
-		facet_by: "company",
-		enable_facet_total: true,
-	},
-);
-```
+const highlighted = await UsersCollection.search({
+  query: "john",
+  highlight: true,
+});
+
+await UsersCollection.drop();
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new TSense({
+  name: string,
+  schema: Type,
+  connection: ConnectionConfig,
+  defaultSearchField?: keyof T,
+  defaultSortingField?: keyof T,
+  batchSize?: number,
+  validateOnUpsert?: boolean,
+})
+```
+
+### ConnectionConfig
+
+| Option     | Type                  | Description           |
+| ---------- | --------------------- | --------------------- |
+| `host`     | `string`              | Typesense server host |
+| `port`     | `number`              | Typesense server port |
+| `protocol` | `"http"` \| `"https"` | Connection protocol   |
+| `apiKey`   | `string`              | Typesense API key     |
+
+### Schema Configuration
+
+Use `.configure()` to set Typesense field options:
+
+```typescript
+type("string").configure({
+  type: "string",
+  facet: true,
+  sort: true,
+  index: true,
+});
+```
+
+### Collection Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `create()` | Creates the collection in Typesense |
+| `drop()` | Deletes the collection |
+| `get(id)` | Retrieves a document by ID |
+| `delete(id)` | Deletes a document by ID |
+| `deleteMany(filter)` | Deletes documents matching filter |
+| `update(id, data)` | Updates a document by ID |
+| `updateMany(filter, data)` | Updates documents matching filter |
+| `upsert(docs)` | Inserts or updates documents |
+| `search(options)` | Searches the collection |
+
+### Search Options
+
+| Option      | Type                              | Description              |
+| ----------- | --------------------------------- | ------------------------ |
+| `query`     | `string`                          | Text search query        |
+| `queryBy`   | `(keyof T)[]`                     | Fields to search in      |
+| `filter`    | `FilterFor<T>`                    | Filter conditions        |
+| `sortBy`    | `"field:asc\|desc"[]`             | Sort order               |
+| `facetBy`   | `(keyof T)[]`                     | Fields to facet by       |
+| `page`      | `number`                          | Page number              |
+| `limit`     | `number`                          | Results per page         |
+| `pick`      | `(keyof T)[]`                     | Only return these fields |
+| `omit`      | `(keyof T)[]`                     | Exclude these fields     |
+| `highlight` | `boolean \| HighlightOptions<T>`  | Enable highlighting      |
+
+Note: `pick` and `omit` are mutually exclusive.
+
+### Filter Syntax
+
+```typescript
+filter: { name: "John" }                    // Exact match
+filter: { age: 30 }                         // Numeric match
+filter: { age: [25, 30, 35] }               // IN
+filter: { age: { min: 20, max: 40 } }       // Range
+filter: { name: { not: "John" } }           // Not equal
+filter: { OR: [{ age: 25 }, { age: 30 }] }  // OR conditions
+```

package/dist/env.d.ts

@@ -0,0 +1,12 @@
+export type TsenseFieldType = "string" | "int32" | "int64" | "float" | "bool" | "image" | "string[]" | "int32[]" | "int64[]" | "float[]" | "bool[]" | "geopoint" | "geopoint[]" | "object" | "object[]" | "auto" | "string*";
+export type TsenseFieldMeta = {
+    type?: TsenseFieldType;
+    facet?: boolean;
+    sort?: boolean;
+    index?: boolean;
+};
+declare global {
+    interface ArkEnv {
+        meta(): TsenseFieldMeta;
+    }
+}

package/dist/index.d.ts

@@ -1 +1,3 @@
+export type { TsenseFieldMeta, TsenseFieldType } from "./env.js";
 export { TSense } from "./tsense.js";
+export type { ConnectionConfig, DeleteResult, FilterFor, HighlightOptions, SearchOptions, SearchResult, TsenseOptions, UpdateResult, UpsertResult, } from "./types.js";

package/dist/tsense.d.ts

@@ -1,34 +1,24 @@
-import type { Client } from "typesense";
-import type { CustomCollectionField, Filters, InferCollectionTypes } from "./types/core.js";
-import type { Simplify } from "./types/helpers.js";
-export declare class TSense<Options extends CustomCollectionField, Fields extends Record<string, Options>, Inferred = InferCollectionTypes<Fields>> {
-    private name;
-    private data;
-    infer: Inferred;
-    constructor(name: string, data: {
-        fields: Fields;
-        client: Client;
-        default_search_field?: NoInfer<keyof Inferred>;
-        default_sorting_field?: NoInfer<keyof Inferred>;
-        batch_size?: number;
-        enable_nested_fields?: boolean;
-    });
-    private checkNested;
+import type { Type } from "arktype";
+import type { DeleteResult, FilterFor, SearchOptions, SearchResult, TsenseOptions, UpdateResult, UpsertResult } from "./types.js";
+export declare class TSense<T extends Type> {
+    private options;
+    private fields;
+    private enableNested;
+    private baseURL;
+    private headers;
+    constructor(options: TsenseOptions<T>);
+    private inferType;
+    private extractFields;
     private buildObjectFilter;
-    private buildSort;
     private buildFilter;
-    private maybeArray;
-    delete(): Promise<void>;
+    private buildSort;
     create(): Promise<this>;
-    searchDocuments<FacetBy extends keyof Inferred, EnableFacetTotal extends boolean | undefined = undefined>(data: Filters<Inferred>, facet?: {
-        facet_by?: FacetBy;
-        enable_facet_total?: EnableFacetTotal;
-    }): Promise<{
-        count: number;
-        data: Inferred[];
-        facet: FacetBy extends keyof Inferred ? Simplify<Record<NonNullable<Inferred[FacetBy]> extends string ? NonNullable<Inferred[FacetBy]> : never, number> & (EnableFacetTotal extends true ? {
-            total: number;
-        } : {})> : never;
-    }>;
-    upsertDocuments(items: Inferred | Inferred[]): Promise<any[] | undefined>;
+    drop(): Promise<void>;
+    get(id: string): Promise<T["infer"] | null>;
+    delete(id: string): Promise<boolean>;
+    deleteMany(filter: FilterFor<T["infer"]>): Promise<DeleteResult>;
+    update(id: string, data: Partial<T["infer"]>): Promise<T["infer"]>;
+    updateMany(filter: FilterFor<T["infer"]>, data: Partial<T["infer"]>): Promise<UpdateResult>;
+    search(options: SearchOptions<T["infer"]>): Promise<SearchResult<T["infer"]>>;
+    upsert(docs: T["infer"] | T["infer"][]): Promise<UpsertResult[]>;
 }

package/dist/tsense.js

@@ -7,32 +7,73 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var _a;
+import redaxios from "redaxios";
+const axios = (_a = redaxios.default) !== null && _a !== void 0 ? _a : redaxios;
 const requiresNested = ["object", "object[]"];
+const arkToTsense = {
+    string: "string",
+    number: "float",
+    "number.integer": "int64",
+    boolean: "bool",
+    "string[]": "string[]",
+    "number[]": "float[]",
+    "boolean[]": "bool[]",
+};
 export class TSense {
-    constructor(name, data) {
-        this.name = name;
-        this.data = data;
-        this.infer = undefined;
+    constructor(options) {
+        this.options = options;
+        this.fields = [];
+        this.enableNested = false;
+        const { connection } = options;
+        this.baseURL = `${connection.protocol}://${connection.host}:${connection.port}`;
+        this.headers = { "X-TYPESENSE-API-KEY": connection.apiKey };
+        this.extractFields();
     }
-    checkNested(fields) {
-        if (this.data.enable_nested_fields) {
-            return;
-        }
-        for (const field of fields) {
-            requiresNested.includes(field.type);
-            this.data.enable_nested_fields = true;
-            return;
+    inferType(arkType) {
+        const direct = arkToTsense[arkType];
+        if (direct)
+            return direct;
+        if (arkType.includes("[]"))
+            return "object[]";
+        if (arkType.includes("{") || arkType.includes("|"))
+            return "object";
+        if (arkType.startsWith("'") || arkType.includes("'"))
+            return "string";
+        return "string";
+    }
+    extractFields() {
+        var _a;
+        const internal = this.options.schema;
+        for (const prop of internal.structure.props) {
+            const meta = prop.value.meta;
+            const expression = String(prop.value.expression);
+            const domain = prop.value.domain;
+            const tsType = (_a = meta === null || meta === void 0 ? void 0 : meta.type) !== null && _a !== void 0 ? _a : this.inferType(domain !== null && domain !== void 0 ? domain : expression);
+            if (requiresNested.includes(tsType)) {
+                this.enableNested = true;
+            }
+            this.fields.push({
+                name: prop.key,
+                type: tsType,
+                optional: prop.kind === "optional",
+                facet: meta === null || meta === void 0 ? void 0 : meta.facet,
+                sort: meta === null || meta === void 0 ? void 0 : meta.sort,
+                index: meta === null || meta === void 0 ? void 0 : meta.index,
+            });
         }
     }
     buildObjectFilter(key, value) {
+        var _a, _b;
         if (Array.isArray(value)) {
             return `(${key}:[${value.join(",")}])`;
         }
-        if ("not" in value) {
-            return `${key}:!=${value.not}`;
+        const v = value;
+        if ("not" in v) {
+            return `${key}:!=${v.not}`;
         }
-        const min = value.min != null ? value.min : undefined;
-        const max = value.max != null ? value.max : undefined;
+        const min = (_a = v.min) !== null && _a !== void 0 ? _a : undefined;
+        const max = (_b = v.max) !== null && _b !== void 0 ? _b : undefined;
         if (min != null && max != null) {
             return `${key}:[${min}..${max}]`;
         }
@@ -43,173 +84,263 @@ export class TSense {
             return `${key}:>=${min}`;
         }
     }
-    buildSort(data) {
-        var _a;
-        if (!data.order_by) {
-            return;
-        }
-        const order = [];
-        for (const key of this.maybeArray(data.order_by)) {
-            const splitted = key.split(" ");
-            let direction = splitted.at(-1);
-            if (direction !== "asc" && direction !== "desc") {
-                direction = (_a = data.direction) !== null && _a !== void 0 ? _a : "desc";
-            }
-            // safeguard
-            if (splitted[0] === "undefined") {
-                continue;
-            }
-            if (splitted[0] === "score") {
-                splitted[0] = "_text_match";
-            }
-            order.push(`${splitted[0]}:${direction}`);
-        }
-        return order.join(",");
-    }
-    buildFilter(data) {
-        var _a;
-        const filter = [];
-        for (const entry of Object.entries((_a = data.filter) !== null && _a !== void 0 ? _a : {})) {
+    buildFilter(filter) {
+        const result = [];
+        for (const entry of Object.entries(filter !== null && filter !== void 0 ? filter : {})) {
             const [key, value] = entry;
             if (value == null)
                 continue;
             if (key === "OR") {
                 const orFilter = [];
                 for (const condition of value) {
-                    const filter = this.buildFilter({ filter: condition });
-                    orFilter.push(`(${filter.join("||")})`);
+                    const inner = this.buildFilter(condition);
+                    orFilter.push(`(${inner.join("||")})`);
                 }
-                filter.push(`(${orFilter.join("||")})`);
+                result.push(`(${orFilter.join("||")})`);
                 continue;
             }
             switch (typeof value) {
                 case "string":
                 case "number":
                 case "boolean":
-                    filter.push(`${key}:=${value}`);
+                    result.push(`${key}:=${value}`);
                     break;
                 case "object": {
                     const built = this.buildObjectFilter(key, value);
-                    if (built) {
-                        filter.push(built);
-                    }
+                    if (built)
+                        result.push(built);
                     break;
                 }
-                default: {
+                default:
                     break;
-                }
             }
         }
-        return filter;
+        return result;
     }
-    maybeArray(d) {
-        if (Array.isArray(d)) {
-            return d;
+    buildSort(options) {
+        if (!options.sortBy)
+            return;
+        const result = [];
+        for (const item of options.sortBy) {
+            const [field, direction] = item.split(":");
+            if (field === "undefined")
+                continue;
+            const realField = field === "score" ? "_text_match" : field;
+            result.push(`${realField}:${direction}`);
         }
-        return [d];
+        return result.join(",");
     }
-    delete() {
+    create() {
         return __awaiter(this, void 0, void 0, function* () {
-            yield this.data.client.collections(this.name).delete();
+            yield axios({
+                method: "POST",
+                baseURL: this.baseURL,
+                url: "/collections",
+                headers: this.headers,
+                data: {
+                    name: this.options.name,
+                    fields: this.fields,
+                    default_sorting_field: this.options.defaultSortingField,
+                    enable_nested_fields: this.enableNested,
+                },
+            });
+            return this;
         });
     }
-    create() {
+    drop() {
         return __awaiter(this, void 0, void 0, function* () {
-            const fields = [];
-            for (const [name, field] of Object.entries(this.data.fields)) {
-                const isSimpleField = typeof field === "string";
-                if (isSimpleField) {
-                    const isOptional = field[field.length - 1] === "?";
-                    const realType = isOptional ? field.slice(0, -1) : field;
-                    fields.push({
-                        name,
-                        type: realType,
-                        optional: isOptional,
-                    });
-                    continue;
-                }
-                fields.push({
-                    name,
-                    type: field.type,
-                    optional: field.optional,
-                    facet: field.facet,
-                    index: field.index,
-                    sort: field.sort,
-                });
+            yield axios({
+                method: "DELETE",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}`,
+                headers: this.headers,
+            });
+        });
+    }
+    get(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield axios({
+                method: "GET",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents/${id}`,
+                headers: this.headers,
+            }).catch((e) => {
+                if (e.status === 404)
+                    return { data: null };
+                throw e;
+            });
+            return data;
+        });
+    }
+    delete(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data } = yield axios({
+                method: "DELETE",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents/${id}`,
+                headers: this.headers,
+            }).catch((e) => {
+                if (e.status === 404)
+                    return { data: null };
+                throw e;
+            });
+            return data != null;
+        });
+    }
+    deleteMany(filter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const filterBy = this.buildFilter(filter).join("&&");
+            if (!filterBy) {
+                throw new Error("FILTER_REQUIRED");
             }
-            this.checkNested(fields);
-            yield this.data.client.collections().create({
-                name: this.name,
-                fields,
-                default_sorting_field: this.data.default_sorting_field,
-                enable_nested_fields: this.data.enable_nested_fields,
+            const { data } = yield axios({
+                method: "DELETE",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents`,
+                headers: this.headers,
+                params: { filter_by: filterBy },
             });
-            return this;
+            return { deleted: data.num_deleted };
         });
     }
-    searchDocuments(data, facet) {
+    update(id, data) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
-            const res = yield this.data.client
-                .collections(this.name)
-                .documents()
-                .search({
-                q: (_a = data.search) !== null && _a !== void 0 ? _a : "",
-                query_by: (_b = data.search_keys) !== null && _b !== void 0 ? _b : [this.data.default_search_field],
-                sort_by: this.buildSort(data),
-                filter_by: this.buildFilter(data).join("&&"),
-                page: data.page,
-                limit: data.limit,
-                facet_by: facet === null || facet === void 0 ? void 0 : facet.facet_by,
+            const { data: updated } = yield axios({
+                method: "PATCH",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents/${id}`,
+                headers: this.headers,
+                data,
             });
-            const facet_result = (facet === null || facet === void 0 ? void 0 : facet.facet_by)
-                ? facet.enable_facet_total
-                    ? { total: 0 }
-                    : {}
-                : undefined;
-            if ((_d = (_c = res.facet_counts) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.counts) {
-                for (const iter of res.facet_counts[0].counts) {
-                    facet_result[iter.value] = iter.count;
-                    if (facet === null || facet === void 0 ? void 0 : facet.enable_facet_total)
-                        facet_result.total += iter.count;
+            return updated;
+        });
+    }
+    updateMany(filter, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const filterBy = this.buildFilter(filter).join("&&");
+            if (!filterBy) {
+                throw new Error("FILTER_REQUIRED");
+            }
+            const { data: result } = yield axios({
+                method: "PATCH",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents`,
+                headers: this.headers,
+                params: { filter_by: filterBy },
+                data,
+            });
+            return { updated: result.num_updated };
+        });
+    }
+    search(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g;
+            const params = {
+                q: (_a = options.query) !== null && _a !== void 0 ? _a : "",
+                query_by: ((_b = options.queryBy) !== null && _b !== void 0 ? _b : [
+                    this.options.defaultSearchField,
+                ]).join(","),
+            };
+            const sortBy = this.buildSort(options);
+            if (sortBy)
+                params.sort_by = sortBy;
+            const filterBy = this.buildFilter(options.filter).join("&&");
+            if (filterBy)
+                params.filter_by = filterBy;
+            if (options.page != null)
+                params.page = options.page;
+            if (options.limit != null)
+                params.per_page = options.limit;
+            const facetBy = (_c = options.facetBy) === null || _c === void 0 ? void 0 : _c.join(",");
+            if (facetBy)
+                params.facet_by = facetBy;
+            if ("pick" in options && options.pick) {
+                params.include_fields = options.pick.join(",");
+            }
+            if ("omit" in options && options.omit) {
+                params.exclude_fields = options.omit.join(",");
+            }
+            const highlight = options.highlight;
+            const highlightEnabled = !!highlight;
+            let highlightOpts;
+            if (typeof highlight === "object") {
+                highlightOpts = highlight;
+                if (highlightOpts.fields) {
+                    params.highlight_fields = highlightOpts.fields.join(",");
+                }
+                if (highlightOpts.startTag) {
+                    params.highlight_start_tag = highlightOpts.startTag;
+                }
+                if (highlightOpts.endTag) {
+                    params.highlight_end_tag = highlightOpts.endTag;
                 }
             }
-            const result = [];
-            for (const hit of (_e = res.hits) !== null && _e !== void 0 ? _e : []) {
-                if (data.highlight) {
-                    for (const [key, value] of Object.entries(hit.highlight)) {
-                        if (value) {
-                            // @ts-expect-error
-                            hit.document[key] = value.snippet;
-                        }
+            const { data: res } = yield axios({
+                method: "GET",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents/search`,
+                headers: this.headers,
+                params,
+            });
+            const data = [];
+            const scores = [];
+            for (const hit of (_d = res.hits) !== null && _d !== void 0 ? _d : []) {
+                if (highlightEnabled) {
+                    const fieldsToHighlight = highlightOpts === null || highlightOpts === void 0 ? void 0 : highlightOpts.fields;
+                    for (const [key, value] of Object.entries((_e = hit.highlight) !== null && _e !== void 0 ? _e : {})) {
+                        if (!(value === null || value === void 0 ? void 0 : value.snippet))
+                            continue;
+                        if (fieldsToHighlight && !fieldsToHighlight.includes(key))
+                            continue;
+                        hit.document[key] = value.snippet;
                     }
                 }
-                result.push(hit.document);
+                data.push(hit.document);
+                scores.push((_f = hit.text_match) !== null && _f !== void 0 ? _f : 0);
+            }
+            const facets = {};
+            for (const facetCount of (_g = res.facet_counts) !== null && _g !== void 0 ? _g : []) {
+                const fieldName = facetCount.field_name;
+                facets[fieldName] = {};
+                for (const item of facetCount.counts) {
+                    facets[fieldName][item.value] = item.count;
+                }
             }
             return {
-                data: result,
                 count: res.found,
-                facet: facet_result,
+                data,
+                facets,
+                scores,
             };
         });
     }
-    upsertDocuments(items) {
+    upsert(docs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const parsed = [];
-            for (const item of this.maybeArray(items)) {
-                parsed.push(JSON.stringify(item));
+            const items = Array.isArray(docs) ? docs : [docs];
+            if (!items.length)
+                return [];
+            if (this.options.validateOnUpsert) {
+                for (const item of items) {
+                    this.options.schema.assert(item);
+                }
             }
-            if (!parsed.length) {
-                return;
+            const payload = items.map((item) => JSON.stringify(item)).join("\n");
+            const params = { action: "upsert" };
+            if (this.options.batchSize) {
+                params.batch_size = this.options.batchSize;
             }
-            const res = yield this.data.client
-                .collections(this.name)
-                .documents()
-                .import(parsed.join("\n"), {
-                action: "upsert",
-                batch_size: this.data.batch_size,
+            const { data } = yield axios({
+                method: "POST",
+                baseURL: this.baseURL,
+                url: `/collections/${this.options.name}/documents/import`,
+                headers: Object.assign(Object.assign({}, this.headers), { "Content-Type": "text/plain" }),
+                params,
+                data: payload,
             });
-            return res.split("\n").map((v) => JSON.parse(v));
+            if (typeof data === "string") {
+                return data.split("\n").map((v) => JSON.parse(v));
+            }
+            return [data];
         });
     }
 }

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+import type { Type } from "arktype";
+type BaseIfArray<T> = T extends (infer Q)[] ? Q : T;
+export type FieldSchema = {
+    name: string;
+    type: string;
+    facet?: boolean;
+    sort?: boolean;
+    index?: boolean;
+    optional?: boolean;
+};
+export type SearchHit<T> = {
+    document: T;
+    highlight?: Record<string, {
+        snippet?: string;
+    }>;
+    text_match?: number;
+};
+export type SearchApiResponse<T> = {
+    found: number;
+    hits?: SearchHit<T>[];
+    facet_counts?: {
+        field_name: string;
+        counts: {
+            value: string;
+            count: number;
+        }[];
+    }[];
+};
+export type ConnectionConfig = {
+    host: string;
+    port: number;
+    protocol: "http" | "https";
+    apiKey: string;
+    timeout?: number;
+};
+export type TsenseOptions<T extends Type> = {
+    name: string;
+    schema: T;
+    connection: ConnectionConfig;
+    defaultSearchField?: keyof T["infer"];
+    defaultSortingField?: keyof T["infer"];
+    batchSize?: number;
+    validateOnUpsert?: boolean;
+};
+type SingleFilter<T> = Partial<{
+    [K in keyof T]: BaseIfArray<T[K]> | NonNullable<BaseIfArray<T[K]>>[] | {
+        not?: BaseIfArray<T[K]>;
+    } | (NonNullable<T[K]> extends number ? {
+        min?: number;
+        max?: number;
+    } : never);
+}>;
+export type FilterFor<T> = SingleFilter<T> & {
+    OR?: FilterFor<T>[];
+};
+export type HighlightOptions<T> = {
+    fields?: (keyof T)[];
+    startTag?: string;
+    endTag?: string;
+};
+type SortableField<T> = Extract<keyof T, string> | "score";
+type BaseSearchOptions<T> = {
+    query?: string;
+    queryBy?: (keyof T)[];
+    filter?: FilterFor<T>;
+    sortBy?: `${SortableField<T>}:${"asc" | "desc"}`[];
+    facetBy?: (keyof T)[];
+    page?: number;
+    limit?: number;
+    highlight?: boolean | HighlightOptions<T>;
+};
+export type SearchOptions<T> = BaseSearchOptions<T> & ({
+    pick?: (keyof T)[];
+    omit?: never;
+} | {
+    omit?: (keyof T)[];
+    pick?: never;
+} | {
+    pick?: never;
+    omit?: never;
+});
+export type SearchResult<T> = {
+    count: number;
+    data: T[];
+    facets: Record<string, Record<string, number>>;
+    scores: number[];
+};
+export type DeleteResult = {
+    deleted: number;
+};
+export type UpdateResult = {
+    updated: number;
+};
+export type UpsertResult = {
+    success: boolean;
+    error?: string;
+    document?: unknown;
+};
+export {};

package/package.json

@@ -1,6 +1,18 @@
 {
 	"name": "tsense",
-	"version": "0.0.4",
+	"version": "0.0.6",
+	"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": {
@@ -9,33 +21,9 @@
 			"import": "./dist/index.js"
 		}
 	},
-	"files": [
-		"dist"
-	],
-	"sideEffects": false,
-	"description": "Opinionated, fully typed typesense client",
-	"license": "MIT",
-	"keywords": [
-		"typesense"
-	],
 	"publishConfig": {
 		"access": "public"
 	},
-	"homepage": "https://github.com/lobomfz/tsense",
-	"type": "module",
-	"private": false,
-	"devDependencies": {
-		"@arethetypeswrong/cli": "^0.18.2",
-		"@biomejs/biome": "2.1.4",
-		"@changesets/cli": "^2.29.7",
-		"@types/bun": "latest"
-	},
-	"peerDependencies": {
-		"typescript": "^5"
-	},
-	"dependencies": {
-		"typesense": "^2.1.0"
-	},
 	"scripts": {
 		"build": "tsc",
 		"ci": "bun run build && bun run format && bun run check-exports",
@@ -44,5 +32,19 @@
 		"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",
+		"@biomejs/biome": "2.1.4",
+		"@changesets/cli": "^2.29.7",
+		"@types/bun": "latest",
+		"arktype": "^2.1.29"
+	},
+	"peerDependencies": {
+		"arktype": "^2.1.29",
+		"typescript": "^5"
 	}
-}
+}

package/dist/collection.d.ts

@@ -1,27 +0,0 @@
-import type { Client } from "typesense";
-import type { CustomCollectionField, Filters, InferCollectionTypes } from "./types/core.js";
-export declare class TSense<Options extends CustomCollectionField, Fields extends Record<string, Options>, Inferred = InferCollectionTypes<Fields>> {
-    private name;
-    private data;
-    infer: Inferred;
-    constructor(name: string, data: {
-        fields: Fields;
-        client: Client;
-        default_search_field?: NoInfer<keyof Inferred>;
-        default_sorting_field?: NoInfer<keyof Inferred>;
-        batch_size?: number;
-        enable_nested_fields?: boolean;
-    });
-    private checkNested;
-    private buildObjectFilter;
-    private buildSort;
-    private buildFilter;
-    private maybeArray;
-    delete(): Promise<void>;
-    create(): Promise<this>;
-    searchDocuments(data: Filters<Inferred>): Promise<{
-        count: number;
-        data: Inferred[];
-    }>;
-    upsertDocuments(items: Inferred | Inferred[]): Promise<any[] | undefined>;
-}

package/dist/collection.js

@@ -1,200 +0,0 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-const requiresNested = ["object", "object[]"];
-export class TSense {
-    constructor(name, data) {
-        this.name = name;
-        this.data = data;
-        this.infer = undefined;
-    }
-    checkNested(fields) {
-        if (this.data.enable_nested_fields) {
-            return;
-        }
-        for (const field of fields) {
-            requiresNested.includes(field.type);
-            this.data.enable_nested_fields = true;
-            return;
-        }
-    }
-    buildObjectFilter(key, value) {
-        if (Array.isArray(value)) {
-            return `(${key}:[${value.join(",")}])`;
-        }
-        if ("not" in value) {
-            return `${key}:!=${value.not}`;
-        }
-        const min = value.min != null ? value.min : undefined;
-        const max = value.max != null ? value.max : undefined;
-        if (min != null && max != null) {
-            return `${key}:[${min}..${max}]`;
-        }
-        if (max != null) {
-            return `${key}:<=${max}`;
-        }
-        if (min != null) {
-            return `${key}:>=${min}`;
-        }
-    }
-    buildSort(data) {
-        var _a;
-        if (!data.order_by) {
-            return;
-        }
-        const order = [];
-        for (const key of this.maybeArray(data.order_by)) {
-            const splitted = key.split(" ");
-            let direction = splitted.at(-1);
-            if (direction !== "asc" && direction !== "desc") {
-                direction = (_a = data.direction) !== null && _a !== void 0 ? _a : "desc";
-            }
-            // safeguard
-            if (splitted[0] === "undefined") {
-                continue;
-            }
-            if (splitted[0] === "score") {
-                splitted[0] = "_text_match";
-            }
-            order.push(`${splitted[0]}:${direction}`);
-        }
-        return order.join(",");
-    }
-    buildFilter(data) {
-        var _a;
-        const filter = [];
-        for (const entry of Object.entries((_a = data.filter) !== null && _a !== void 0 ? _a : {})) {
-            const [key, value] = entry;
-            if (value == null)
-                continue;
-            if (key === "OR") {
-                const orFilter = [];
-                for (const condition of value) {
-                    const filter = this.buildFilter({ filter: condition });
-                    orFilter.push(`(${filter.join("||")})`);
-                }
-                filter.push(`(${orFilter.join("||")})`);
-                continue;
-            }
-            switch (typeof value) {
-                case "string":
-                case "number":
-                case "boolean":
-                    filter.push(`${key}:=${value}`);
-                    break;
-                case "object": {
-                    const built = this.buildObjectFilter(key, value);
-                    if (built) {
-                        filter.push(built);
-                    }
-                    break;
-                }
-                default: {
-                    break;
-                }
-            }
-        }
-        return filter;
-    }
-    maybeArray(d) {
-        if (Array.isArray(d)) {
-            return d;
-        }
-        return [d];
-    }
-    delete() {
-        return __awaiter(this, void 0, void 0, function* () {
-            yield this.data.client.collections(this.name).delete();
-        });
-    }
-    create() {
-        return __awaiter(this, void 0, void 0, function* () {
-            const fields = [
-                {
-                    name: "id",
-                    type: "int32",
-                },
-            ];
-            for (const [name, field] of Object.entries(this.data.fields)) {
-                const isSimpleField = typeof field === "string";
-                if (isSimpleField) {
-                    const isOptional = field[field.length - 1] === "?";
-                    const realType = isOptional ? field.slice(0, -1) : field;
-                    fields.push({
-                        name,
-                        type: realType,
-                        optional: isOptional,
-                    });
-                    continue;
-                }
-                fields.push({
-                    name,
-                    type: field.type,
-                    optional: field.optional,
-                    facet: field.facet,
-                    index: field.index,
-                    sort: field.sort,
-                });
-            }
-            this.checkNested(fields);
-            yield this.data.client.collections().create({
-                name: this.name,
-                fields,
-                default_sorting_field: this.data.default_sorting_field,
-                enable_nested_fields: this.data.enable_nested_fields,
-            });
-            return this;
-        });
-    }
-    searchDocuments(data) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
-            const res = yield this.data.client
-                .collections(this.name)
-                .documents()
-                .search({
-                q: (_a = data.search) !== null && _a !== void 0 ? _a : "",
-                query_by: (_b = data.search_keys) !== null && _b !== void 0 ? _b : [this.data.default_search_field],
-                sort_by: this.buildSort(data),
-                filter_by: this.buildFilter(data).join("&&"),
-                page: data.page,
-                limit: data.limit,
-            });
-            const result = [];
-            if ((_c = res.hits) === null || _c === void 0 ? void 0 : _c.length) {
-                for (const hit of res.hits) {
-                    result.push(hit.document);
-                }
-            }
-            return {
-                data: result,
-                count: res.found,
-            };
-        });
-    }
-    upsertDocuments(items) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const parsed = [];
-            for (const item of this.maybeArray(items)) {
-                parsed.push(JSON.stringify(item));
-            }
-            if (!parsed.length) {
-                return;
-            }
-            const res = yield this.data.client
-                .collections(this.name)
-                .documents()
-                .import(parsed.join("\n"), {
-                action: "upsert",
-                batch_size: this.data.batch_size,
-            });
-            return res.split("\n").map((v) => JSON.parse(v));
-        });
-    }
-}

package/dist/types/core.d.ts

@@ -1,66 +0,0 @@
-import type { FieldType } from "typesense/lib/Typesense/Collection.js";
-import type { BaseIfArray, Simplify, UndefinedToOptional } from "./helpers.js";
-export type CustomCollectionField = FieldType | `${FieldType}?` | {
-    type: FieldType;
-    optional?: boolean;
-    facet?: boolean;
-    index?: boolean;
-    override?: any;
-    sort?: boolean;
-};
-type TypesenseToTS = {
-    string: string;
-    int32: number;
-    int64: number;
-    float: number;
-    bool: boolean;
-    image: string;
-    "string[]": string[];
-    "int32[]": number[];
-    "int64[]": number[];
-    "float[]": number[];
-    "bool[]": boolean[];
-    geopoint: unknown;
-    "geopoint[]": unknown[];
-    object: unknown;
-    "object[]": unknown[];
-    auto: unknown;
-    "string*": unknown;
-};
-type ValidFieldType = keyof TypesenseToTS;
-export type InferCollectionTypes<Fields> = Simplify<{
-    id?: string;
-} & UndefinedToOptional<{
-    [K in keyof Fields]: Fields[K] extends ValidFieldType ? TypesenseToTS[Fields[K]] : Fields[K] extends {
-        override: infer Override;
-    } ? Fields[K] extends {
-        optional: true;
-    } ? Override | null | undefined : Override : Fields[K] extends {
-        type: infer T;
-    } ? T extends ValidFieldType ? Fields[K] extends {
-        optional: true;
-    } ? TypesenseToTS[T] | null | undefined : TypesenseToTS[T] : never : Fields[K] extends `${infer RealType}?` ? RealType extends ValidFieldType ? TypesenseToTS[RealType] | null | undefined : never : never;
-}>>;
-type OrderBy<Inferred, Options = keyof Inferred | "score"> = Options | Options[] | (Options extends infer Q ? Q extends string ? `${Q} ${"asc" | "desc"}` : never : never)[];
-type SingleFilter<Inferred> = Partial<{
-    [K in keyof Inferred]: BaseIfArray<Inferred[K]> | NonNullable<BaseIfArray<Inferred[K]>>[] | {
-        not?: string | string[] | boolean | null;
-    } | (NonNullable<Inferred[K]> extends number ? {
-        min?: number;
-        max?: number;
-    } : never);
-}>;
-type RecursiveFilter<Inferred> = SingleFilter<Inferred> & {
-    OR?: RecursiveFilter<Inferred>[];
-};
-export type Filters<Inferred> = {
-    search?: string;
-    filter?: RecursiveFilter<Inferred>;
-    order_by?: OrderBy<Inferred> | undefined;
-    direction?: "asc" | "desc";
-    page?: number;
-    limit?: number;
-    search_keys?: (keyof Inferred)[];
-    highlight?: boolean;
-};
-export {};

package/dist/types/helpers.d.ts

@@ -1,11 +0,0 @@
-export type UndefinedToOptional<T> = {
-    [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
-} & {
-    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
-};
-export type BaseIfArray<T> = T extends (infer Q)[] ? Q : T;
-type DrainOuterGeneric<T> = [T] extends [unknown] ? T : never;
-export type Simplify<T> = DrainOuterGeneric<{
-    [K in keyof T]: T[K];
-} & {}>;
-export {};