tsense 0.0.1

package/README.md

@@ -0,0 +1,92 @@
+## TSense (WIP)
+
+Opinionated, fully-typed typesense client
+
+# TO-DO
+- [ ] Remove base typesense dependency
+- [ ] Better filter support
+- [ ] Documentation
+- [ ] Improve tests
+- [ ] Facet
+
+# Example
+```typescript
+import { Client } from "typesense";
+import { TSense } from "tsense";
+
+export const client = new Client({
+	nodes: [
+		{
+			host: "127.0.0.1",
+			port: 8108,
+			protocol: "http",
+		},
+	],
+	apiKey: "123",
+	connectionTimeoutSeconds: 2,
+});
+
+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,
+		},
+		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",
+});
+
+// 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", "id asc"],
+	filter: {
+		// min and max range on numbers
+		age: {
+			min: 20,
+		},
+		// OR syntax similar to prisma
+		OR: [
+			{
+				email: "@google.com",
+			},
+			{
+				email: "@netflix.com",
+			},
+		],
+	},
+});
+```

package/dist/collection.d.ts

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,195 @@
+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 = [];
+            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/index.d.ts

@@ -0,0 +1 @@
+export { TSense } from "./collection.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { TSense } from "./collection.js";

package/dist/types/core.d.ts

@@ -0,0 +1,66 @@
+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/core.js

@@ -0,0 +1 @@
+export {};

package/dist/types/helpers.d.ts

@@ -0,0 +1,11 @@
+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 {};

package/dist/types/helpers.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "tsense",
+	"version": "0.0.1",
+	"main": "dist/index.js",
+	"files": [
+		"dist"
+	],
+	"description": "Opinionated, fully typed typesense client, inspired by prisma syntax",
+	"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",
+		"test": "bun test",
+		"format": "biome check --write",
+		"check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
+		"local-release": "changeset version && changeset publish",
+		"prepublishOnly": "bun run ci"
+	}
+}