@grackle-ai/common 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * as grackle from "./gen/grackle/grackle_pb.js";
 export * as powerline from "./gen/grackle/powerline/powerline_pb.js";
 export * from "./types.js";
 export * from "./enum-converters.js";
+export * from "./search.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAC;AACvD,OAAO,KAAK,SAAS,MAAM,yCAAyC,CAAC;AACrE,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAC;AACvD,OAAO,KAAK,SAAS,MAAM,yCAAyC,CAAC;AACrE,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ export * as grackle from "./gen/grackle/grackle_pb.js";
 export * as powerline from "./gen/grackle/powerline/powerline_pb.js";
 export * from "./types.js";
 export * from "./enum-converters.js";
+export * from "./search.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAC;AACvD,OAAO,KAAK,SAAS,MAAM,yCAAyC,CAAC;AACrE,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAC;AACvD,OAAO,KAAK,SAAS,MAAM,yCAAyC,CAAC;AACrE,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC"}

package/dist/search.d.ts

@@ -0,0 +1,43 @@
+/** Index range describing a matched substring [start, end] (inclusive). */
+export type MatchIndex = readonly [number, number];
+/** Details about which field matched and where. */
+export interface FuzzyMatch {
+    /** The field key that matched (e.g. "title"). */
+    key: string;
+    /** Ranges within the field value that matched the query. */
+    indices: readonly MatchIndex[];
+}
+/** A single fuzzy search result with its matched item and relevance score. */
+export interface FuzzyResult<T> {
+    /** The matched item from the input collection. */
+    item: T;
+    /** Relevance score where 0 is a perfect match and 1 is no match. */
+    score: number;
+    /** Which fields matched and where, useful for highlighting. */
+    matches: FuzzyMatch[];
+}
+/** Configuration for a searchable field with a relative weight. */
+export interface FuzzyKey {
+    /** Property path on the item (e.g. "title", "description"). */
+    name: string;
+    /** Relative weight for this field. Higher = more important. */
+    weight: number;
+}
+/** Options for tuning fuzzy search behavior. */
+export interface FuzzySearchOptions {
+    /** Maximum score threshold (0–1). Results above this are excluded. Default: 0.3. */
+    threshold?: number;
+    /** Maximum number of results to return. Default: no limit. */
+    limit?: number;
+}
+/**
+ * Perform a fuzzy search over a collection of items.
+ *
+ * @param items - The items to search through.
+ * @param query - The search query string. Empty string returns an empty array.
+ * @param keys - Which fields to search, with relative weights.
+ * @param options - Optional threshold and limit overrides.
+ * @returns Matched items sorted by relevance (best first), capped at `limit`.
+ */
+export declare function fuzzySearch<T>(items: T[], query: string, keys: FuzzyKey[], options?: FuzzySearchOptions): FuzzyResult<T>[];
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAMA,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEnD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CAChC;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,kDAAkD;IAClD,IAAI,EAAE,CAAC,CAAC;IACR,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,QAAQ,EAAE,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,WAAW,CAAC,CAAC,CAAC,EAAE,CA8BlB"}

package/dist/search.js

@@ -0,0 +1,42 @@
+/**
+ * Shared fuzzy search utility wrapping fuse.js.
+ * Used by both the web UI (client-side sidebar filter) and the server (fuzzy task search).
+ */
+import Fuse from "fuse.js";
+/**
+ * Perform a fuzzy search over a collection of items.
+ *
+ * @param items - The items to search through.
+ * @param query - The search query string. Empty string returns an empty array.
+ * @param keys - Which fields to search, with relative weights.
+ * @param options - Optional threshold and limit overrides.
+ * @returns Matched items sorted by relevance (best first), capped at `limit`.
+ */
+export function fuzzySearch(items, query, keys, options) {
+    if (!query.trim()) {
+        return [];
+    }
+    const threshold = options?.threshold ?? 0.3;
+    const fuse = new Fuse(items, {
+        keys,
+        threshold,
+        ignoreLocation: true,
+        includeScore: true,
+        includeMatches: true,
+        minMatchCharLength: 2,
+    });
+    const results = fuse.search(query);
+    const mapped = results.map((r) => ({
+        item: r.item,
+        score: r.score ?? 1,
+        matches: (r.matches ?? []).map((m) => ({
+            key: m.key ?? "",
+            indices: m.indices,
+        })),
+    }));
+    if (options?.limit !== undefined) {
+        return mapped.slice(0, options.limit);
+    }
+    return mapped;
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,IAAI,MAAM,SAAS,CAAC;AAuC3B;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,KAAU,EACV,KAAa,EACb,IAAgB,EAChB,OAA4B;IAE5B,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,GAAG,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,EAAE;QAC3B,IAAI;QACJ,SAAS;QACT,cAAc,EAAE,IAAI;QACpB,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;QACpB,kBAAkB,EAAE,CAAC;KACtB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEnC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjC,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;QACnB,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrC,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;YAChB,OAAO,EAAE,CAAC,CAAC,OAAgC;SAC5C,CAAC,CAAC;KACJ,CAAC,CAAC,CAAC;IAEJ,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/search.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search.test.d.ts.map

package/dist/search.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.test.d.ts","sourceRoot":"","sources":["../src/search.test.ts"],"names":[],"mappings":""}

package/dist/search.test.js

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+import { fuzzySearch } from "./search.js";
+const ITEMS = [
+    { title: "Fix login bug", description: "Users cannot login with SSO" },
+    { title: "Add dashboard widget", description: "Create analytics dashboard" },
+    { title: "Update auth middleware", description: "Refactor authentication layer" },
+    { title: "Implement JWT tokens", description: "Add token-based auth" },
+    { title: "Fix signup page", description: "Email validation broken" },
+];
+const KEYS = [
+    { name: "title", weight: 2 },
+    { name: "description", weight: 1 },
+];
+describe("fuzzySearch", () => {
+    it("returns empty array for empty query", () => {
+        expect(fuzzySearch(ITEMS, "", KEYS)).toEqual([]);
+    });
+    it("returns empty array for whitespace-only query", () => {
+        expect(fuzzySearch(ITEMS, "   ", KEYS)).toEqual([]);
+    });
+    it("matches by title substring", () => {
+        const results = fuzzySearch(ITEMS, "login", KEYS);
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].item.title).toBe("Fix login bug");
+    });
+    it("matches by description", () => {
+        const results = fuzzySearch(ITEMS, "analytics", KEYS);
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].item.title).toBe("Add dashboard widget");
+    });
+    it("is case-insensitive", () => {
+        const results = fuzzySearch(ITEMS, "JWT", KEYS);
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].item.title).toBe("Implement JWT tokens");
+    });
+    it("ranks title matches higher than description matches", () => {
+        // "auth" appears in title of "Update auth middleware" and description of "Implement JWT tokens"
+        const results = fuzzySearch(ITEMS, "auth", KEYS);
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].item.title).toBe("Update auth middleware");
+    });
+    it("returns results sorted by score (best first)", () => {
+        const results = fuzzySearch(ITEMS, "fix", KEYS);
+        expect(results.length).toBeGreaterThanOrEqual(2);
+        for (let i = 1; i < results.length; i++) {
+            expect(results[i].score).toBeGreaterThanOrEqual(results[i - 1].score);
+        }
+    });
+    it("respects limit parameter", () => {
+        const results = fuzzySearch(ITEMS, "fix", KEYS, { limit: 1 });
+        expect(results).toHaveLength(1);
+    });
+    it("excludes results above threshold", () => {
+        const results = fuzzySearch(ITEMS, "xyznonexistent", KEYS, { threshold: 0.2 });
+        expect(results).toHaveLength(0);
+    });
+    it("returns score between 0 and 1", () => {
+        const results = fuzzySearch(ITEMS, "login", KEYS);
+        for (const r of results) {
+            expect(r.score).toBeGreaterThanOrEqual(0);
+            expect(r.score).toBeLessThanOrEqual(1);
+        }
+    });
+    it("works with single-field search", () => {
+        const results = fuzzySearch(ITEMS, "dashboard", [{ name: "title", weight: 1 }]);
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].item.title).toBe("Add dashboard widget");
+    });
+});
+//# sourceMappingURL=search.test.js.map

package/dist/search.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.test.js","sourceRoot":"","sources":["../src/search.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grackle-ai/common",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Proto definitions, generated code, and shared types for Grackle",
   "license": "MIT",
   "repository": {
@@ -25,17 +25,20 @@
   ],
   "dependencies": {
     "@bufbuild/protobuf": "^2.5.0",
-    "@connectrpc/connect": "^2.0.0"
+    "@connectrpc/connect": "^2.0.0",
+    "fuse.js": "^7.0.0"
   },
   "devDependencies": {
     "@bufbuild/buf": "^1.50.0",
     "@bufbuild/protoc-gen-es": "^2.5.0",
     "@rushstack/heft": "1.2.4",
+    "vitest": "^3.1.1",
     "@grackle-ai/heft-buf-plugin": "0.0.1",
     "@grackle-ai/heft-rig": "0.0.1"
   },
   "scripts": {
     "build": "heft build --clean",
-    "clean": "heft clean"
+    "clean": "heft clean",
+    "test": "vitest run"
   }
 }