tsense 0.1.0 → 0.2.0-next.0

package/README.md

@@ -1,168 +1,163 @@
 # TSense
 
-Opinionated, fully-typed Typesense client powered by [Arktype](https://arktype.io/)
+Fully-typed Typesense client powered by [Arktype](https://arktype.io/).
 
-## Installation
+Define your schema once. Get type-safe search, filtering, and automatic filter UIs — all from the same source of truth.
 
 ```bash
 bun add tsense arktype
 ```
 
-## Example
+## Define a collection
 
 ```typescript
 import { type } from "arktype";
 import { TSense } from "tsense";
 
-const UsersCollection = new TSense({
+const Users = new TSense({
   name: "users",
   schema: type({
     "id?": "string",
-    email: "string",
+    name: type("string").configure({ sort: true, index: true }),
     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 }),
+    company: type
+      .enumerated("netflix", "google", "apple")
+      .configure({ facet: true }),
+    active: type("boolean").configure({ facet: true }),
+    "joined_at?": "Date",
   }),
   connection: {
     host: "127.0.0.1",
     port: 8108,
     protocol: "http",
-    apiKey: "123",
+    apiKey: "xyz123",
   },
   defaultSearchField: "name",
-  validateOnUpsert: true,
 });
+```
 
-type User = typeof UsersCollection.infer;
-
-await UsersCollection.create();
+## Search with typed filters
 
-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" },
-]);
+Operators are restricted per field type — the compiler catches invalid combinations.
 
-const results = await UsersCollection.search({
-  query: "john",
-  queryBy: ["name", "email"],
-  sortBy: ["age:desc", "name:asc"],
+```typescript
+await Users.search({
   filter: {
-    age: { min: 20 },
-    OR: [{ company: "google" }, { company: "netflix" }],
+    age: { gte: 18, lte: 40 },
+    company: ["netflix", "google"],
+    name: { not: "admin" },
   },
 });
+```
 
-const faceted = await UsersCollection.search({
-  query: "john",
-  facetBy: ["company"],
-});
+## Paginated lists
 
-const highlighted = await UsersCollection.search({
-  query: "john",
-  highlight: true,
+```typescript
+const page1 = await Users.searchList({
+  sortBy: "age:asc",
+  filter: { active: true },
+  limit: 20,
 });
 
-await UsersCollection.drop();
+const page2 = await Users.searchList({
+  sortBy: "age:asc",
+  filter: { active: true },
+  limit: 20,
+  cursor: page1.nextCursor!,
+});
 ```
 
-## API Reference
+## Count
 
-### Schema Configuration
+```typescript
+const total = await Users.count();
+const active = await Users.count({ active: true });
+```
 
-Use `.configure()` to set Typesense field options:
+## Multi-tenancy with scoped
+
+`scoped()` returns a narrowed instance where a base filter is merged into every operation. The caller cannot override it.
 
 ```typescript
-type("string").configure({
-  type: "string",
-  facet: true,
-  sort: true,
-  index: true,
-});
-```
+const myUsers = Users.scoped({ owner_id: currentUser.id });
 
-### Collection Methods
+await myUsers.search({ filter: { active: true } });
+// filter_by = "active:=true && owner_id:=`user-1`"
 
-| Method/Property            | 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                   |
-| `syncSchema()`             | Syncs schema (creates/patches collection) |
-| `syncData(options)`        | Syncs data from external source           |
-| `fields`                   | Array of generated field schemas          |
+await myUsers.count({ active: true });
+await myUsers.deleteMany({ active: false });
+```
 
-### Schema Sync
+## Build filter UIs from the schema
 
-Automatically sync schema before the first operation:
+Declare which fields are filterable. tsense introspects the arktype schema, detects enums, and produces a descriptor that travels to the frontend as JSON.
 
 ```typescript
-const Collection = new TSense({
-  // ...
-  autoSyncSchema: true,
+import { createFilterBuilder } from "tsense/filters";
+
+const filters = createFilterBuilder(Users, {
+  name: { label: "Name" },
+  age: {
+    label: "Age",
+    presets: { "Over 18": { age: { gte: 18 } } },
+  },
+  company: {
+    label: "Company",
+    labels: { netflix: "Netflix", google: "Google", apple: "Apple" },
+  },
+  active: { label: "Active" },
+  joined_at: { label: "Joined At" },
 });
+
+const descriptor = filters.describe();
 ```
 
-Or manually:
+## Render it
 
-```typescript
-await Collection.syncSchema();
+Drop the descriptor into the React component. The user picks columns, conditions, and values. You get a typed `FilterFor<User>` back.
+
+```tsx
+import { FilterBuilder } from "tsense/react";
+
+<FilterBuilder descriptor={descriptor} onChange={(filter) => search(filter)} />;
 ```
 
-### Data Sync
+Every slot is replaceable via render props — or use the headless `useFilterBuilder` hook for full control.
+
+## Wire it end-to-end
 
-Sync documents from an external source (database, API, etc.):
+Backend validates input with the filter builder schema, scopes results by user, and exposes the descriptor. Frontend renders the builder and fires queries.
 
 ```typescript
-const Collection = new TSense({
-  // ...
-  dataSync: {
-    getAllIds: async () => {
-      return db
-        .selectFrom("users")
-        .select("id")
-        .execute()
-        .then((rows) => rows.map((r) => r.id));
-    },
-    getItems: async (ids) => {
-      return db.selectFrom("users").where("id", "in", ids).execute();
-    },
-    chunkSize: 100, // optional, default 500
-  },
+// backend
+const filters = createFilterBuilder(Users, config);
+
+const authed = base.use(({ context, next }) => {
+  if (!context.user) throw new ORPCError("UNAUTHORIZED");
+  return next({ context: { user: context.user } });
 });
 
-// Full sync
-await Collection.syncData();
+const router = base.router({
+  search: authed
+    .input(filters.schema())
+    .handler(({ input, context }) =>
+      Users.scoped({ owner_id: context.user.id }).search(input),
+    ),
+});
+```
 
-// Partial sync (specific IDs)
-await Collection.syncData({ ids: ["id1", "id2"] });
+```tsx
+// frontend
+import { describe } from "./api/describe" with { type: "macro" };
 
-// Full sync + remove orphan documents
-await Collection.syncData({ purge: true });
+const descriptor = describe();
+const [filter, setFilter] = useState<typeof descriptor.infer>({});
 
-// Override chunk size
-await Collection.syncData({ chunkSize: 50 });
+<FilterBuilder descriptor={descriptor} onChange={setFilter} />;
+
+const { data: results } = useQuery(api.search, { filter });
 ```
 
-### Filter Syntax
+The descriptor is inlined at build time via [Bun macros](https://bun.sh/docs/bundler/macros) — no RPC call needed.
 
-```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
-```
+A working example with docker-compose, seed data, and a full UI lives in [`examples/`](./examples).

package/dist/filters/filter-state.d.ts

@@ -0,0 +1,22 @@
+import type { FilterDescriptor } from "./index.js";
+export type FilterValue = string | string[] | number | boolean | Date | [FilterValue | undefined, FilterValue | undefined] | undefined;
+export type FilterRow = {
+    id: number;
+    field?: string;
+    condition?: string;
+    value?: FilterValue;
+};
+export type FilterState = {
+    rows: FilterRow[];
+};
+export declare function createInitialState(): FilterState;
+export declare function addRow(state: FilterState): FilterState;
+export declare function removeRow(state: FilterState, index: number): FilterState;
+export declare function setRowField(state: FilterState, index: number, field: string): FilterState;
+export declare function setRowCondition(state: FilterState, index: number, condition: string): FilterState;
+export declare function setRowValue(state: FilterState, index: number, value: FilterValue): FilterState;
+export declare function clearState(): FilterState;
+export declare function applyPreset<T>(state: FilterState, descriptor: FilterDescriptor<T>, field: string, name: string): FilterState;
+export declare function conditionsFor<T>(descriptor: FilterDescriptor<T>, field: string): FilterDescriptor<T>["columns"][number]["conditions"];
+export declare function columnFor<T>(descriptor: FilterDescriptor<T>, field: string): FilterDescriptor<T>["columns"][number];
+export declare function buildResult(state: FilterState): Record<string, unknown>;

package/dist/filters/filter-state.js

@@ -0,0 +1,145 @@
+const conditionToOperator = {
+    equals: null,
+    not_equals: "not",
+    gt: "gt",
+    gte: "gte",
+    lt: "lt",
+    lte: "lte",
+    between: null,
+    is_in: null,
+    is_not_in: "notIn",
+};
+let nextRowId = 0;
+export function createInitialState() {
+    return { rows: [{ id: ++nextRowId }] };
+}
+export function addRow(state) {
+    return { rows: [...state.rows, { id: ++nextRowId }] };
+}
+export function removeRow(state, index) {
+    return { rows: state.rows.filter((_, i) => i !== index) };
+}
+export function setRowField(state, index, field) {
+    return {
+        rows: state.rows.map((row, i) => i === index ? { id: row.id, field } : row),
+    };
+}
+export function setRowCondition(state, index, condition) {
+    return {
+        rows: state.rows.map((row, i) => i === index ? { ...row, condition, value: undefined } : row),
+    };
+}
+export function setRowValue(state, index, value) {
+    return {
+        rows: state.rows.map((row, i) => (i === index ? { ...row, value } : row)),
+    };
+}
+export function clearState() {
+    return { rows: [] };
+}
+export function applyPreset(state, descriptor, field, name) {
+    const column = descriptor.columns.find((c) => c.key === field);
+    const preset = column?.presets?.find((p) => p.name === name);
+    if (!preset)
+        return state;
+    const filterValue = preset.filter[field];
+    if (filterValue == null)
+        return state;
+    if (Array.isArray(filterValue)) {
+        return {
+            rows: [
+                ...state.rows,
+                { id: ++nextRowId, field, condition: "is_in", value: filterValue },
+            ],
+        };
+    }
+    if (typeof filterValue !== "object" || filterValue instanceof Date) {
+        return {
+            rows: [
+                ...state.rows,
+                { id: ++nextRowId, field, condition: "equals", value: filterValue },
+            ],
+        };
+    }
+    const ops = filterValue;
+    const keys = Object.keys(ops);
+    if (keys.includes("gte") && keys.includes("lte")) {
+        return {
+            rows: [
+                ...state.rows,
+                {
+                    id: ++nextRowId,
+                    field,
+                    condition: "between",
+                    value: [ops.gte, ops.lte],
+                },
+            ],
+        };
+    }
+    if (keys[0]) {
+        return {
+            rows: [
+                ...state.rows,
+                { id: ++nextRowId, field, condition: keys[0], value: ops[keys[0]] },
+            ],
+        };
+    }
+    return state;
+}
+export function conditionsFor(descriptor, field) {
+    const column = descriptor.columns.find((c) => c.key === field);
+    return column?.conditions ?? [];
+}
+export function columnFor(descriptor, field) {
+    const column = descriptor.columns.find((c) => c.key === field);
+    if (!column) {
+        throw new Error(`Column not found: ${field}`);
+    }
+    return column;
+}
+function isRowComplete(row) {
+    if (!row.field || !row.condition || row.value == null)
+        return false;
+    if (row.condition === "between") {
+        return (Array.isArray(row.value) && row.value[0] != null && row.value[1] != null);
+    }
+    if (row.condition === "is_in" || row.condition === "is_not_in") {
+        return Array.isArray(row.value) && row.value.length > 0;
+    }
+    return true;
+}
+export function buildResult(state) {
+    const result = {};
+    for (const row of state.rows) {
+        if (!isRowComplete(row))
+            continue;
+        if (row.condition === "equals" || row.condition === "is_in") {
+            result[row.field] = row.value;
+            continue;
+        }
+        if (row.condition === "between") {
+            const [min, max] = row.value;
+            const existing = typeof result[row.field] === "object" && result[row.field] !== null
+                ? result[row.field]
+                : {};
+            result[row.field] = { ...existing, gte: min, lte: max };
+            continue;
+        }
+        const operator = conditionToOperator[row.condition];
+        if (!operator)
+            continue;
+        const existing = result[row.field];
+        if (typeof existing === "object" &&
+            existing !== null &&
+            !Array.isArray(existing)) {
+            result[row.field] = {
+                ...existing,
+                [operator]: row.value,
+            };
+        }
+        else {
+            result[row.field] = { [operator]: row.value };
+        }
+    }
+    return result;
+}

package/dist/filters/index.d.ts

@@ -0,0 +1,40 @@
+export { deserializeFilter, serializeFilter } from "./url.js";
+import type { Type } from "arktype";
+import type { TSense } from "../tsense.js";
+import type { FilterFor, SearchInput } from "../types.js";
+export type FilterDescriptor<T = Record<string, unknown>> = {
+    infer: FilterFor<T>;
+    columns: {
+        key: keyof T & string;
+        label: string;
+        type: "string" | "number" | "boolean" | "date";
+        conditions: {
+            key: string;
+            label: string;
+        }[];
+        values?: {
+            value: string;
+            label: string;
+        }[];
+        presets?: {
+            name: string;
+            filter: Record<string, unknown>;
+        }[];
+    }[];
+};
+type FilterBuilderFieldConfig<T> = {
+    label: string;
+    labels?: Record<string, string>;
+    presets?: Record<string, FilterFor<T> | (() => FilterFor<T>)>;
+};
+type FilterBuilderReturn<T> = {
+    describe(): FilterDescriptor<T>;
+    schema(): Type<SearchInput<T>>;
+};
+type ColumnType = FilterDescriptor["columns"][number]["type"];
+type FilterBuilderOptions = {
+    conditionLabels?: Partial<Record<ColumnType | "enum", Partial<Record<string, string>>>>;
+};
+export declare function createFilterBuilder<T extends Type>(collection: TSense<T>, config: {
+    [K in keyof T["infer"]]?: FilterBuilderFieldConfig<T["infer"]>;
+}, options?: FilterBuilderOptions): FilterBuilderReturn<T["infer"]>;

package/dist/filters/index.js

@@ -0,0 +1,128 @@
+export { deserializeFilter, serializeFilter } from "./url.js";
+import { type } from "arktype";
+const tsenseTypeMap = {
+    string: "string",
+    "string*": "string",
+    "string[]": "string",
+    int32: "number",
+    int64: "number",
+    float: "number",
+    "int32[]": "number",
+    "int64[]": "number",
+    "float[]": "number",
+    bool: "boolean",
+    "bool[]": "boolean",
+    auto: "string",
+    image: "string",
+};
+const enumConditions = [
+    { key: "is_in", label: "is in" },
+    { key: "is_not_in", label: "is not in" },
+];
+const conditionsByType = {
+    string: [
+        { key: "equals", label: "equals" },
+        { key: "not_equals", label: "not equals" },
+    ],
+    number: [
+        { key: "equals", label: "equals" },
+        { key: "not_equals", label: "not equals" },
+        { key: "gt", label: "greater than" },
+        { key: "gte", label: "greater than or equal" },
+        { key: "lt", label: "less than" },
+        { key: "lte", label: "less than or equal" },
+        { key: "between", label: "between" },
+    ],
+    boolean: [{ key: "equals", label: "equals" }],
+    date: [
+        { key: "equals", label: "equals" },
+        { key: "not_equals", label: "not equals" },
+        { key: "gt", label: "after" },
+        { key: "lt", label: "before" },
+        { key: "between", label: "between" },
+    ],
+};
+export function createFilterBuilder(collection, config, options) {
+    const fields = collection.fields;
+    return {
+        schema() {
+            const numberOps = type.raw({
+                "not?": "number",
+                "gt?": "number",
+                "gte?": "number",
+                "lt?": "number",
+                "lte?": "number",
+                "notIn?": "number[]",
+            });
+            const stringOps = type.raw({
+                "not?": "string",
+                "notIn?": "string[]",
+            });
+            const fieldSchemas = {
+                number: type.raw("number").or(type.raw("number[]")).or(numberOps),
+                string: type.raw("string").or(type.raw("string[]")).or(stringOps),
+                boolean: type.raw("boolean"),
+                date: type.raw("number").or(type.raw("number[]")).or(numberOps),
+            };
+            const descriptor = this.describe();
+            const filterDef = {};
+            for (const column of descriptor.columns) {
+                filterDef[`${column.key}?`] = fieldSchemas[column.type];
+            }
+            return type
+                .raw({
+                "query?": "string",
+                "filter?": type.raw(filterDef),
+                "page?": "number",
+                "limit?": "number",
+            })
+                .as();
+        },
+        describe() {
+            const columns = [];
+            const withLabels = (conditions, typeKey) => {
+                const overrides = options?.conditionLabels?.[typeKey];
+                if (!overrides) {
+                    return conditions;
+                }
+                return conditions.map((c) => ({
+                    key: c.key,
+                    label: overrides[c.key] ?? c.label,
+                }));
+            };
+            for (const field of fields) {
+                const fieldConfig = config[field.name];
+                if (!fieldConfig)
+                    continue;
+                const columnType = field.sourceExpression === "Date"
+                    ? "date"
+                    : tsenseTypeMap[field.type];
+                if (!columnType)
+                    continue;
+                const column = {
+                    key: field.name,
+                    label: fieldConfig.label,
+                    type: columnType,
+                    conditions: withLabels(conditionsByType[columnType], columnType),
+                };
+                if (field.enumValues?.length) {
+                    column.values = field.enumValues.map((v) => ({
+                        value: v,
+                        label: fieldConfig.labels?.[v] ?? v,
+                    }));
+                    column.conditions = withLabels(enumConditions, "enum");
+                }
+                if (fieldConfig.presets) {
+                    column.presets = Object.entries(fieldConfig.presets).map(([name, filterOrFn]) => ({
+                        name,
+                        filter: (typeof filterOrFn === "function"
+                            ? filterOrFn()
+                            : filterOrFn),
+                    }));
+                }
+                columns.push(column);
+            }
+            return { infer: undefined, columns };
+        },
+    };
+}

package/dist/filters/url.d.ts

@@ -0,0 +1,3 @@
+import type { FilterDescriptor } from "./index.js";
+export declare function serializeFilter(filter: Record<string, unknown>, descriptor: FilterDescriptor): URLSearchParams;
+export declare function deserializeFilter(params: URLSearchParams, descriptor: FilterDescriptor): Record<string, unknown>;