@tsctl/cli 0.2.0

package/src/resources/override.ts

@@ -0,0 +1,174 @@
+import { getClient } from "../client/index.js";
+import type { OverrideConfig } from "../types/index.js";
+
+/**
+ * Convert our OverrideConfig to Typesense API format
+ */
+function toTypesenseOverride(config: OverrideConfig): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    rule: config.rule,
+  };
+
+  if (config.includes) result.includes = config.includes;
+  if (config.excludes) result.excludes = config.excludes;
+  if (config.filter_by) result.filter_by = config.filter_by;
+  if (config.sort_by) result.sort_by = config.sort_by;
+  if (config.replace_query) result.replace_query = config.replace_query;
+  if (config.remove_matched_tokens !== undefined)
+    result.remove_matched_tokens = config.remove_matched_tokens;
+  if (config.filter_curated_hits !== undefined)
+    result.filter_curated_hits = config.filter_curated_hits;
+  if (config.effective_from_ts !== undefined)
+    result.effective_from_ts = config.effective_from_ts;
+  if (config.effective_to_ts !== undefined)
+    result.effective_to_ts = config.effective_to_ts;
+  if (config.stop_processing !== undefined)
+    result.stop_processing = config.stop_processing;
+
+  return result;
+}
+
+/**
+ * Override default values in Typesense
+ * These are stripped when importing to keep configs minimal
+ */
+const OVERRIDE_DEFAULTS = {
+  remove_matched_tokens: false,
+  filter_curated_hits: false,
+  stop_processing: true,
+} as const;
+
+/**
+ * Convert Typesense API override to our OverrideConfig format
+ * Strips default values to keep config minimal
+ */
+function fromTypesenseOverride(
+  override: Record<string, unknown>,
+  collection: string
+): OverrideConfig {
+  const config: OverrideConfig = {
+    id: override.id as string,
+    collection,
+    rule: override.rule as OverrideConfig["rule"],
+  };
+
+  // These have no defaults, always include if present
+  if (override.includes)
+    config.includes = override.includes as OverrideConfig["includes"];
+  if (override.excludes)
+    config.excludes = override.excludes as OverrideConfig["excludes"];
+  if (override.filter_by) config.filter_by = override.filter_by as string;
+  if (override.sort_by) config.sort_by = override.sort_by as string;
+  if (override.replace_query)
+    config.replace_query = override.replace_query as string;
+  if (override.effective_from_ts !== undefined)
+    config.effective_from_ts = override.effective_from_ts as number;
+  if (override.effective_to_ts !== undefined)
+    config.effective_to_ts = override.effective_to_ts as number;
+
+  // Only include non-default values
+  if (
+    override.remove_matched_tokens !== undefined &&
+    override.remove_matched_tokens !== OVERRIDE_DEFAULTS.remove_matched_tokens
+  )
+    config.remove_matched_tokens = override.remove_matched_tokens as boolean;
+  if (
+    override.filter_curated_hits !== undefined &&
+    override.filter_curated_hits !== OVERRIDE_DEFAULTS.filter_curated_hits
+  )
+    config.filter_curated_hits = override.filter_curated_hits as boolean;
+  if (
+    override.stop_processing !== undefined &&
+    override.stop_processing !== OVERRIDE_DEFAULTS.stop_processing
+  )
+    config.stop_processing = override.stop_processing as boolean;
+
+  return config;
+}
+
+/**
+ * Get an override from Typesense
+ */
+export async function getOverride(
+  id: string,
+  collection: string
+): Promise<OverrideConfig | null> {
+  const client = getClient();
+
+  try {
+    const override = await client.collections(collection).overrides(id).retrieve();
+    return fromTypesenseOverride(override as unknown as Record<string, unknown>, collection);
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      error.httpStatus === 404
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all overrides for a collection from Typesense
+ */
+export async function listOverrides(collection: string): Promise<OverrideConfig[]> {
+  const client = getClient();
+
+  try {
+    const response = await client.collections(collection).overrides().retrieve();
+    return response.overrides.map((override) =>
+      fromTypesenseOverride(override as unknown as Record<string, unknown>, collection)
+    );
+  } catch (error: unknown) {
+    // Collection might not exist
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      error.httpStatus === 404
+    ) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all overrides across all collections
+ */
+export async function listAllOverrides(
+  collections: string[]
+): Promise<OverrideConfig[]> {
+  const allOverrides: OverrideConfig[] = [];
+
+  for (const collection of collections) {
+    const overrides = await listOverrides(collection);
+    allOverrides.push(...overrides);
+  }
+
+  return allOverrides;
+}
+
+/**
+ * Create or update an override in Typesense
+ * Overrides are upserted in Typesense
+ */
+export async function upsertOverride(config: OverrideConfig): Promise<void> {
+  const client = getClient();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  await client
+    .collections(config.collection)
+    .overrides()
+    .upsert(config.id, toTypesenseOverride(config) as any);
+}
+
+/**
+ * Delete an override from Typesense
+ */
+export async function deleteOverride(id: string, collection: string): Promise<void> {
+  const client = getClient();
+  await client.collections(collection).overrides(id).delete();
+}

package/src/resources/preset.ts

@@ -0,0 +1,83 @@
+import { getClient } from "../client/index.js";
+import type { PresetConfig } from "../types/index.js";
+
+/**
+ * Get a preset from Typesense
+ */
+export async function getPreset(
+  name: string
+): Promise<PresetConfig | null> {
+  const client = getClient();
+
+  try {
+    const data = await client.presets(name).retrieve();
+    return {
+      name: data.name,
+      value: data.value as Record<string, unknown>,
+    };
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      error.httpStatus === 404
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all presets from Typesense
+ */
+export async function listPresets(): Promise<PresetConfig[]> {
+  const client = getClient();
+
+  try {
+    const response = await client.presets().retrieve();
+    return response.presets.map((p) => ({
+      name: p.name,
+      value: p.value as Record<string, unknown>,
+    }));
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      (error.httpStatus === 404 || error.httpStatus === 400)
+    ) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Create or update a preset in Typesense
+ */
+export async function upsertPreset(config: PresetConfig): Promise<void> {
+  const client = getClient();
+  await client.presets().upsert(config.name, {
+    value: config.value as any,
+  });
+}
+
+/**
+ * Delete a preset from Typesense
+ */
+export async function deletePreset(name: string): Promise<void> {
+  const client = getClient();
+  await client.presets(name).delete();
+}
+
+/**
+ * Compare two preset configs for equality
+ */
+export function presetConfigsEqual(
+  a: PresetConfig,
+  b: PresetConfig
+): boolean {
+  if (a.name !== b.name) return false;
+  return JSON.stringify(a.value) === JSON.stringify(b.value);
+}

package/src/resources/stemmingdictionary.ts

@@ -0,0 +1,103 @@
+import { getClient } from "../client/index.js";
+import type { StemmingDictionaryConfig, StemmingWord } from "../types/index.js";
+
+/**
+ * Get a stemming dictionary from Typesense
+ */
+export async function getStemmingDictionary(
+  id: string
+): Promise<StemmingDictionaryConfig | null> {
+  const client = getClient();
+
+  try {
+    const data = await client.stemming.dictionaries(id).retrieve();
+    return {
+      id: data.id,
+      words: data.words.map((w) => ({
+        word: w.word,
+        root: w.root,
+      })),
+    };
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      (error.httpStatus === 404 || error.httpStatus === 400)
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all stemming dictionaries from Typesense
+ */
+export async function listStemmingDictionaries(): Promise<
+  StemmingDictionaryConfig[]
+> {
+  const client = getClient();
+
+  try {
+    const response = await client.stemming.dictionaries().retrieve();
+    const dictionaries: StemmingDictionaryConfig[] = [];
+
+    for (const dictId of response.dictionaries) {
+      try {
+        const dict = await client.stemming.dictionaries(dictId).retrieve();
+        dictionaries.push({
+          id: dict.id,
+          words: dict.words.map((w) => ({
+            word: w.word,
+            root: w.root,
+          })),
+        });
+      } catch {
+        // Skip dictionaries we can't retrieve
+      }
+    }
+
+    return dictionaries;
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      (error.httpStatus === 404 || error.httpStatus === 400)
+    ) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Create or update a stemming dictionary in Typesense
+ * Stemming dictionaries are uploaded as arrays of word/root pairs
+ */
+export async function upsertStemmingDictionary(
+  config: StemmingDictionaryConfig
+): Promise<void> {
+  const client = getClient();
+  await client.stemming.dictionaries().upsert(
+    config.id,
+    config.words.map((w) => ({ word: w.word, root: w.root }))
+  );
+}
+
+/**
+ * Compare two stemming dictionary configs for equality
+ */
+export function stemmingDictionaryConfigsEqual(
+  a: StemmingDictionaryConfig,
+  b: StemmingDictionaryConfig
+): boolean {
+  if (a.id !== b.id) return false;
+  if (a.words.length !== b.words.length) return false;
+
+  const aWords = [...a.words].sort((x, y) => x.word.localeCompare(y.word));
+  const bWords = [...b.words].sort((x, y) => x.word.localeCompare(y.word));
+
+  return JSON.stringify(aWords) === JSON.stringify(bWords);
+}

package/src/resources/stopword.ts

@@ -0,0 +1,100 @@
+import { getClient } from "../client/index.js";
+import type { StopwordSetConfig } from "../types/index.js";
+
+/**
+ * Get a stopword set from Typesense
+ */
+export async function getStopwordSet(
+  id: string
+): Promise<StopwordSetConfig | null> {
+  const client = getClient();
+
+  try {
+    const raw = await client.stopwords(id).retrieve();
+    // The retrieve response may wrap the data in a "stopwords" key
+    const data = (raw as any).stopwords || raw;
+    const config: StopwordSetConfig = {
+      id: data.id || id,
+      stopwords: Array.isArray(data.stopwords) ? data.stopwords : [],
+    };
+    if (data.locale) config.locale = data.locale;
+    return config;
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      error.httpStatus === 404
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all stopword sets from Typesense
+ */
+export async function listStopwordSets(): Promise<StopwordSetConfig[]> {
+  const client = getClient();
+
+  try {
+    const response = await client.stopwords().retrieve();
+    return response.stopwords.map((s) => {
+      const config: StopwordSetConfig = {
+        id: s.id,
+        stopwords: Array.isArray(s.stopwords) ? s.stopwords : [],
+      };
+      if (s.locale) config.locale = s.locale;
+      return config;
+    });
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      (error.httpStatus === 404 || error.httpStatus === 400)
+    ) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Create or update a stopword set in Typesense
+ */
+export async function upsertStopwordSet(
+  config: StopwordSetConfig
+): Promise<void> {
+  const client = getClient();
+
+  const params: { stopwords: string[]; locale?: string } = {
+    stopwords: config.stopwords,
+  };
+  if (config.locale) params.locale = config.locale;
+
+  await client.stopwords().upsert(config.id, params);
+}
+
+/**
+ * Delete a stopword set from Typesense
+ */
+export async function deleteStopwordSet(id: string): Promise<void> {
+  const client = getClient();
+  await client.stopwords(id).delete();
+}
+
+/**
+ * Compare two stopword set configs for equality
+ */
+export function stopwordSetConfigsEqual(
+  a: StopwordSetConfig,
+  b: StopwordSetConfig
+): boolean {
+  if (a.id !== b.id) return false;
+  if (a.locale !== b.locale) return false;
+  const aSorted = [...a.stopwords].sort();
+  const bSorted = [...b.stopwords].sort();
+  return JSON.stringify(aSorted) === JSON.stringify(bSorted);
+}

package/src/resources/synonym.ts

@@ -0,0 +1,152 @@
+import { getClient } from "../client/index.js";
+import type { SynonymConfig } from "../types/index.js";
+
+/**
+ * Convert our SynonymConfig to Typesense API format
+ */
+function toTypesenseSynonym(config: SynonymConfig): {
+  synonyms?: string[];
+  root?: string;
+  symbols_to_index?: string[];
+  locale?: string;
+} {
+  const result: {
+    synonyms?: string[];
+    root?: string;
+    symbols_to_index?: string[];
+    locale?: string;
+  } = {};
+
+  if (config.synonyms) result.synonyms = config.synonyms;
+  if (config.root) result.root = config.root;
+  if (config.symbols_to_index) result.symbols_to_index = config.symbols_to_index;
+  if (config.locale) result.locale = config.locale;
+
+  return result;
+}
+
+/**
+ * Convert Typesense API synonym to our SynonymConfig format
+ */
+function fromTypesenseSynonym(
+  synonym: {
+    id: string;
+    synonyms?: string[];
+    root?: string;
+    symbols_to_index?: string[];
+    locale?: string;
+  },
+  collection: string
+): SynonymConfig {
+  const config: SynonymConfig = {
+    id: synonym.id,
+    collection,
+  };
+
+  if (synonym.synonyms) config.synonyms = synonym.synonyms;
+  if (synonym.root) config.root = synonym.root;
+  if (synonym.symbols_to_index) config.symbols_to_index = synonym.symbols_to_index;
+  if (synonym.locale) config.locale = synonym.locale;
+
+  return config;
+}
+
+/**
+ * Get a synonym from Typesense
+ */
+export async function getSynonym(
+  id: string,
+  collection: string
+): Promise<SynonymConfig | null> {
+  const client = getClient();
+
+  try {
+    const synonym = await client.collections(collection).synonyms(id).retrieve();
+    return fromTypesenseSynonym(synonym, collection);
+  } catch (error: unknown) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      error.httpStatus === 404
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all synonyms for a collection from Typesense
+ */
+export async function listSynonyms(collection: string): Promise<SynonymConfig[]> {
+  const client = getClient();
+
+  try {
+    const response = await client.collections(collection).synonyms().retrieve();
+    return response.synonyms.map((synonym: {
+      id: string;
+      synonyms?: string[];
+      root?: string;
+      symbols_to_index?: string[];
+      locale?: string;
+    }) => fromTypesenseSynonym(synonym, collection));
+  } catch (error: unknown) {
+    // Collection might not exist
+    if (
+      error &&
+      typeof error === "object" &&
+      "httpStatus" in error &&
+      error.httpStatus === 404
+    ) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * List all synonyms across all collections
+ */
+export async function listAllSynonyms(
+  collections: string[]
+): Promise<SynonymConfig[]> {
+  const allSynonyms: SynonymConfig[] = [];
+
+  for (const collection of collections) {
+    const synonyms = await listSynonyms(collection);
+    allSynonyms.push(...synonyms);
+  }
+
+  return allSynonyms;
+}
+
+/**
+ * Create or update a synonym in Typesense
+ * Synonyms are upserted in Typesense
+ */
+export async function upsertSynonym(config: SynonymConfig): Promise<void> {
+  const client = getClient();
+  const synonymData = toTypesenseSynonym(config);
+
+  // Typesense requires either synonyms or root to be present
+  if (!synonymData.synonyms && !synonymData.root) {
+    throw new Error(
+      `Synonym ${config.id} must have either 'synonyms' or 'root' defined`
+    );
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  await client
+    .collections(config.collection)
+    .synonyms()
+    .upsert(config.id, synonymData as any);
+}
+
+/**
+ * Delete a synonym from Typesense
+ */
+export async function deleteSynonym(id: string, collection: string): Promise<void> {
+  const client = getClient();
+  await client.collections(collection).synonyms(id).delete();
+}