@tsctl/cli 0.2.0

package/src/__tests__/state.test.ts

@@ -0,0 +1,312 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import {
+  ensureStateCollection,
+  loadState,
+  saveState,
+  computeChecksum,
+  formatResourceId,
+  parseResourceId,
+  findResource,
+  upsertResource,
+  removeResource,
+} from "../state/index.js";
+import type { State, ManagedResource, ResourceIdentifier } from "../types/index.js";
+
+describe("state", () => {
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  describe("ensureStateCollection", () => {
+    test("creates state collection if it doesn't exist", async () => {
+      await ensureStateCollection();
+      const client = (await import("../client/index.js")).getClient();
+      const collection = await client.collections("_tsctl_state").retrieve();
+      expect(collection.name).toBe("_tsctl_state");
+    });
+
+    test("does not fail if state collection already exists", async () => {
+      await ensureStateCollection();
+      await ensureStateCollection(); // second call should not throw
+    });
+  });
+
+  describe("loadState / saveState", () => {
+    test("returns empty state when no state exists", async () => {
+      const state = await loadState();
+      expect(state.version).toBe("1.0");
+      expect(state.resources).toEqual([]);
+    });
+
+    test("saves and loads state", async () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "products" },
+            config: { name: "products", fields: [{ name: "title", type: "string" }] },
+            checksum: "abc123",
+            lastUpdated: new Date().toISOString(),
+          },
+        ],
+      };
+
+      await saveState(state);
+      const loaded = await loadState();
+
+      expect(loaded.version).toBe("1.0");
+      expect(loaded.resources).toHaveLength(1);
+      expect(loaded.resources[0]!.identifier.name).toBe("products");
+    });
+
+    test("overwrites previous state on save", async () => {
+      const state1: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "old" },
+            config: { name: "old", fields: [{ name: "x", type: "string" }] },
+            checksum: "aaa",
+            lastUpdated: new Date().toISOString(),
+          },
+        ],
+      };
+
+      const state2: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "new" },
+            config: { name: "new", fields: [{ name: "y", type: "string" }] },
+            checksum: "bbb",
+            lastUpdated: new Date().toISOString(),
+          },
+        ],
+      };
+
+      await saveState(state1);
+      await saveState(state2);
+      const loaded = await loadState();
+
+      expect(loaded.resources).toHaveLength(1);
+      expect(loaded.resources[0]!.identifier.name).toBe("new");
+    });
+  });
+
+  describe("computeChecksum", () => {
+    test("returns consistent checksum for same config", () => {
+      const config = { name: "products", fields: [{ name: "title", type: "string" as const }] };
+      const checksum1 = computeChecksum(config);
+      const checksum2 = computeChecksum(config);
+      expect(checksum1).toBe(checksum2);
+    });
+
+    test("returns different checksum for different configs", () => {
+      const config1 = { name: "a", fields: [{ name: "x", type: "string" as const }] };
+      const config2 = { name: "b", fields: [{ name: "y", type: "string" as const }] };
+      expect(computeChecksum(config1)).not.toBe(computeChecksum(config2));
+    });
+
+    test("returns 16-character hex string", () => {
+      const checksum = computeChecksum({ name: "test", collection: "x" });
+      expect(checksum).toMatch(/^[a-f0-9]{16}$/);
+    });
+  });
+
+  describe("formatResourceId / parseResourceId", () => {
+    test("formats collection identifier", () => {
+      expect(formatResourceId({ type: "collection", name: "products" })).toBe(
+        "collection.products"
+      );
+    });
+
+    test("formats scoped identifier", () => {
+      expect(
+        formatResourceId({ type: "synonym", name: "syn1", collection: "products" })
+      ).toBe("synonym.products.syn1");
+    });
+
+    test("parses simple identifier", () => {
+      const id = parseResourceId("collection.products");
+      expect(id.type).toBe("collection");
+      expect(id.name).toBe("products");
+      expect(id.collection).toBeUndefined();
+    });
+
+    test("parses scoped identifier", () => {
+      const id = parseResourceId("synonym.products.syn1");
+      expect(id.type).toBe("synonym");
+      expect(id.collection).toBe("products");
+      expect(id.name).toBe("syn1");
+    });
+
+    test("roundtrips correctly", () => {
+      const identifier: ResourceIdentifier = {
+        type: "override",
+        name: "ov1",
+        collection: "products",
+      };
+      const formatted = formatResourceId(identifier);
+      const parsed = parseResourceId(formatted);
+      expect(parsed).toEqual(identifier);
+    });
+  });
+
+  describe("findResource", () => {
+    test("finds existing resource", () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "products" },
+            config: { name: "products", fields: [] },
+            checksum: "abc",
+            lastUpdated: "",
+          },
+        ],
+      };
+      const found = findResource(state, { type: "collection", name: "products" });
+      expect(found).toBeDefined();
+      expect(found!.identifier.name).toBe("products");
+    });
+
+    test("returns undefined for missing resource", () => {
+      const state: State = { version: "1.0", resources: [] };
+      const found = findResource(state, { type: "collection", name: "missing" });
+      expect(found).toBeUndefined();
+    });
+
+    test("matches by collection scope", () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "synonym", name: "syn1", collection: "products" },
+            config: { id: "syn1", collection: "products", synonyms: ["a", "b"] },
+            checksum: "abc",
+            lastUpdated: "",
+          },
+          {
+            identifier: { type: "synonym", name: "syn1", collection: "users" },
+            config: { id: "syn1", collection: "users", synonyms: ["c", "d"] },
+            checksum: "def",
+            lastUpdated: "",
+          },
+        ],
+      };
+
+      const found = findResource(state, {
+        type: "synonym",
+        name: "syn1",
+        collection: "products",
+      });
+      expect(found).toBeDefined();
+      expect((found!.config as any).collection).toBe("products");
+    });
+  });
+
+  describe("upsertResource", () => {
+    test("adds new resource", () => {
+      const state: State = { version: "1.0", resources: [] };
+      const resource: ManagedResource = {
+        identifier: { type: "collection", name: "products" },
+        config: { name: "products", fields: [] },
+        checksum: "abc",
+        lastUpdated: "",
+      };
+      const newState = upsertResource(state, resource);
+      expect(newState.resources).toHaveLength(1);
+    });
+
+    test("updates existing resource", () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "products" },
+            config: { name: "products", fields: [] },
+            checksum: "old",
+            lastUpdated: "",
+          },
+        ],
+      };
+      const resource: ManagedResource = {
+        identifier: { type: "collection", name: "products" },
+        config: { name: "products", fields: [{ name: "title", type: "string" }] },
+        checksum: "new",
+        lastUpdated: "",
+      };
+      const newState = upsertResource(state, resource);
+      expect(newState.resources).toHaveLength(1);
+      expect(newState.resources[0]!.checksum).toBe("new");
+    });
+
+    test("does not mutate original state", () => {
+      const state: State = { version: "1.0", resources: [] };
+      const resource: ManagedResource = {
+        identifier: { type: "collection", name: "products" },
+        config: { name: "products", fields: [] },
+        checksum: "abc",
+        lastUpdated: "",
+      };
+      upsertResource(state, resource);
+      expect(state.resources).toHaveLength(0);
+    });
+  });
+
+  describe("removeResource", () => {
+    test("removes existing resource", () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "products" },
+            config: { name: "products", fields: [] },
+            checksum: "abc",
+            lastUpdated: "",
+          },
+        ],
+      };
+      const newState = removeResource(state, { type: "collection", name: "products" });
+      expect(newState.resources).toHaveLength(0);
+    });
+
+    test("does nothing for non-existent resource", () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "products" },
+            config: { name: "products", fields: [] },
+            checksum: "abc",
+            lastUpdated: "",
+          },
+        ],
+      };
+      const newState = removeResource(state, { type: "collection", name: "missing" });
+      expect(newState.resources).toHaveLength(1);
+    });
+
+    test("does not mutate original state", () => {
+      const state: State = {
+        version: "1.0",
+        resources: [
+          {
+            identifier: { type: "collection", name: "products" },
+            config: { name: "products", fields: [] },
+            checksum: "abc",
+            lastUpdated: "",
+          },
+        ],
+      };
+      removeResource(state, { type: "collection", name: "products" });
+      expect(state.resources).toHaveLength(1);
+    });
+  });
+});

package/src/__tests__/stemmingdictionaries.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import { getTypesenseVersion } from "./helpers.js";
+import {
+  upsertStemmingDictionary,
+  getStemmingDictionary,
+  listStemmingDictionaries,
+  stemmingDictionaryConfigsEqual,
+} from "../resources/stemmingdictionary.js";
+
+describe("stemming dictionaries", () => {
+  let version: number;
+
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+    version = await getTypesenseVersion();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  test("upsertStemmingDictionary creates a dictionary", async () => {
+    if (version < 28) return; // Stemming API requires v28+
+    await upsertStemmingDictionary({
+      id: "english-plurals",
+      words: [
+        { word: "dogs", root: "dog" },
+        { word: "cats", root: "cat" },
+        { word: "mice", root: "mouse" },
+      ],
+    });
+
+    const result = await getStemmingDictionary("english-plurals");
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe("english-plurals");
+    expect(result!.words).toHaveLength(3);
+  });
+
+  test("getStemmingDictionary returns null for non-existent", async () => {
+    if (version < 28) return;
+    const result = await getStemmingDictionary("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  test("listStemmingDictionaries returns all dictionaries", async () => {
+    if (version < 28) return;
+    await upsertStemmingDictionary({
+      id: "dict1",
+      words: [{ word: "running", root: "run" }],
+    });
+    await upsertStemmingDictionary({
+      id: "dict2",
+      words: [{ word: "jumping", root: "jump" }],
+    });
+
+    const dicts = await listStemmingDictionaries();
+    const ids = dicts.map((d) => d.id);
+    expect(ids).toContain("dict1");
+    expect(ids).toContain("dict2");
+  });
+
+  test("upsertStemmingDictionary updates existing dictionary", async () => {
+    if (version < 28) return;
+    await upsertStemmingDictionary({
+      id: "my-dict",
+      words: [{ word: "dogs", root: "dog" }],
+    });
+    await upsertStemmingDictionary({
+      id: "my-dict",
+      words: [
+        { word: "dogs", root: "dog" },
+        { word: "cats", root: "cat" },
+      ],
+    });
+
+    const result = await getStemmingDictionary("my-dict");
+    expect(result!.words).toHaveLength(2);
+  });
+
+  test("stemmingDictionaryConfigsEqual compares correctly", () => {
+    const a = {
+      id: "test",
+      words: [
+        { word: "dogs", root: "dog" },
+        { word: "cats", root: "cat" },
+      ],
+    };
+    const b = {
+      id: "test",
+      words: [
+        { word: "cats", root: "cat" },
+        { word: "dogs", root: "dog" },
+      ],
+    };
+    expect(stemmingDictionaryConfigsEqual(a, b)).toBe(true);
+  });
+
+  test("stemmingDictionaryConfigsEqual detects differences", () => {
+    const a = {
+      id: "test",
+      words: [{ word: "dogs", root: "dog" }],
+    };
+    const b = {
+      id: "test",
+      words: [{ word: "cats", root: "cat" }],
+    };
+    expect(stemmingDictionaryConfigsEqual(a, b)).toBe(false);
+  });
+});

package/src/__tests__/stopwords.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import {
+  upsertStopwordSet,
+  getStopwordSet,
+  listStopwordSets,
+  deleteStopwordSet,
+  stopwordSetConfigsEqual,
+} from "../resources/stopword.js";
+
+describe("stopwords", () => {
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  test("upsertStopwordSet creates a stopword set", async () => {
+    await upsertStopwordSet({
+      id: "english-stopwords",
+      stopwords: ["the", "a", "an", "is", "are"],
+    });
+
+    const result = await getStopwordSet("english-stopwords");
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe("english-stopwords");
+    expect(result!.stopwords).toContain("the");
+    expect(result!.stopwords).toContain("a");
+  });
+
+  test("upsertStopwordSet creates with locale", async () => {
+    await upsertStopwordSet({
+      id: "german-stopwords",
+      stopwords: ["der", "die", "das"],
+      locale: "de",
+    });
+
+    const result = await getStopwordSet("german-stopwords");
+    expect(result).not.toBeNull();
+    expect(result!.locale).toBe("de");
+  });
+
+  test("getStopwordSet returns null for non-existent", async () => {
+    const result = await getStopwordSet("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  test("listStopwordSets returns all stopword sets", async () => {
+    await upsertStopwordSet({
+      id: "english",
+      stopwords: ["the", "a"],
+    });
+    await upsertStopwordSet({
+      id: "german",
+      stopwords: ["der", "die"],
+    });
+
+    const sets = await listStopwordSets();
+    expect(sets.length).toBeGreaterThanOrEqual(2);
+    const ids = sets.map((s) => s.id);
+    expect(ids).toContain("english");
+    expect(ids).toContain("german");
+  });
+
+  test("upsertStopwordSet updates existing set", async () => {
+    await upsertStopwordSet({
+      id: "english",
+      stopwords: ["the", "a"],
+    });
+    await upsertStopwordSet({
+      id: "english",
+      stopwords: ["the", "a", "an"],
+    });
+
+    const result = await getStopwordSet("english");
+    expect(result!.stopwords).toHaveLength(3);
+  });
+
+  test("deleteStopwordSet removes set", async () => {
+    await upsertStopwordSet({
+      id: "to-delete",
+      stopwords: ["the"],
+    });
+    await deleteStopwordSet("to-delete");
+    const result = await getStopwordSet("to-delete");
+    expect(result).toBeNull();
+  });
+
+  test("stopwordSetConfigsEqual compares correctly", () => {
+    const a = { id: "test", stopwords: ["a", "b", "c"] };
+    const b = { id: "test", stopwords: ["c", "b", "a"] };
+    expect(stopwordSetConfigsEqual(a, b)).toBe(true);
+  });
+
+  test("stopwordSetConfigsEqual detects differences", () => {
+    const a = { id: "test", stopwords: ["a", "b"] };
+    const b = { id: "test", stopwords: ["a", "c"] };
+    expect(stopwordSetConfigsEqual(a, b)).toBe(false);
+  });
+
+  test("stopwordSetConfigsEqual considers locale", () => {
+    const a = { id: "test", stopwords: ["a"], locale: "en" };
+    const b = { id: "test", stopwords: ["a"], locale: "de" };
+    expect(stopwordSetConfigsEqual(a, b)).toBe(false);
+  });
+});

package/src/__tests__/synonymsets.test.ts

@@ -0,0 +1,170 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import { getTypesenseVersion } from "./helpers.js";
+import {
+  createSynonymSet,
+  getSynonymSet,
+  listSynonymSets,
+  updateSynonymSet,
+  deleteSynonymSet,
+  synonymSetConfigsEqual,
+} from "../resources/synonymset.js";
+import type { SynonymSetConfig } from "../types/index.js";
+
+describe("synonym sets (global)", () => {
+  let version: number;
+
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+    version = await getTypesenseVersion();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  test("createSynonymSet creates a set", async () => {
+    if (version < 28) return; // Synonym sets require v28+
+    const config: SynonymSetConfig = {
+      name: "clothing-synonyms",
+      items: [
+        { id: "pants", synonyms: ["pants", "trousers", "slacks"] },
+        { id: "shirt", synonyms: ["shirt", "top", "blouse"] },
+      ],
+    };
+
+    await createSynonymSet(config);
+    const result = await getSynonymSet("clothing-synonyms");
+    expect(result).not.toBeNull();
+    expect(result!.name).toBe("clothing-synonyms");
+    expect(result!.items).toHaveLength(2);
+  });
+
+  test("getSynonymSet returns null for non-existent", async () => {
+    if (version < 28) return;
+    const result = await getSynonymSet("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  test("createSynonymSet with one-way synonyms", async () => {
+    if (version < 28) return;
+    const config: SynonymSetConfig = {
+      name: "tv-synonyms",
+      items: [
+        { id: "tv", root: "television", synonyms: ["tv", "telly"] },
+      ],
+    };
+
+    await createSynonymSet(config);
+    const result = await getSynonymSet("tv-synonyms");
+    expect(result).not.toBeNull();
+    expect(result!.items[0]!.root).toBe("television");
+  });
+
+  test("listSynonymSets returns all sets", async () => {
+    if (version < 28) return;
+    await createSynonymSet({
+      name: "set1",
+      items: [{ id: "a", synonyms: ["x", "y"] }],
+    });
+    await createSynonymSet({
+      name: "set2",
+      items: [{ id: "b", synonyms: ["m", "n"] }],
+    });
+
+    const sets = await listSynonymSets();
+    const names = sets.map((s) => s.name);
+    expect(names).toContain("set1");
+    expect(names).toContain("set2");
+  });
+
+  test("updateSynonymSet modifies items", async () => {
+    if (version < 28) return;
+    const initial: SynonymSetConfig = {
+      name: "my-synonyms",
+      items: [{ id: "a", synonyms: ["x", "y"] }],
+    };
+    await createSynonymSet(initial);
+
+    const updated: SynonymSetConfig = {
+      name: "my-synonyms",
+      items: [
+        { id: "a", synonyms: ["x", "y"] },
+        { id: "b", synonyms: ["m", "n"] },
+      ],
+    };
+    await updateSynonymSet(updated, initial);
+
+    const result = await getSynonymSet("my-synonyms");
+    expect(result!.items).toHaveLength(2);
+  });
+
+  test("deleteSynonymSet removes set", async () => {
+    if (version < 28) return;
+    await createSynonymSet({
+      name: "to-delete",
+      items: [{ id: "a", synonyms: ["x", "y"] }],
+    });
+    await deleteSynonymSet("to-delete");
+    const result = await getSynonymSet("to-delete");
+    expect(result).toBeNull();
+  });
+
+  test("synonymSetConfigsEqual compares correctly", () => {
+    const a: SynonymSetConfig = {
+      name: "test",
+      items: [
+        { id: "a", synonyms: ["x", "y"] },
+        { id: "b", synonyms: ["m", "n"] },
+      ],
+    };
+    const b: SynonymSetConfig = {
+      name: "test",
+      items: [
+        { id: "b", synonyms: ["m", "n"] },
+        { id: "a", synonyms: ["x", "y"] },
+      ],
+    };
+    expect(synonymSetConfigsEqual(a, b)).toBe(true);
+  });
+
+  test("synonymSetConfigsEqual detects differences", () => {
+    const a: SynonymSetConfig = {
+      name: "test",
+      items: [{ id: "a", synonyms: ["x", "y"] }],
+    };
+    const b: SynonymSetConfig = {
+      name: "test",
+      items: [{ id: "a", synonyms: ["x", "z"] }],
+    };
+    expect(synonymSetConfigsEqual(a, b)).toBe(false);
+  });
+
+  test("synonymSetConfigsEqual detects name difference", () => {
+    const a: SynonymSetConfig = {
+      name: "test1",
+      items: [{ id: "a", synonyms: ["x"] }],
+    };
+    const b: SynonymSetConfig = {
+      name: "test2",
+      items: [{ id: "a", synonyms: ["x"] }],
+    };
+    expect(synonymSetConfigsEqual(a, b)).toBe(false);
+  });
+
+  test("synonymSetConfigsEqual detects length difference", () => {
+    const a: SynonymSetConfig = {
+      name: "test",
+      items: [{ id: "a", synonyms: ["x"] }],
+    };
+    const b: SynonymSetConfig = {
+      name: "test",
+      items: [
+        { id: "a", synonyms: ["x"] },
+        { id: "b", synonyms: ["y"] },
+      ],
+    };
+    expect(synonymSetConfigsEqual(a, b)).toBe(false);
+  });
+});