@tsproxy/api 0.0.1

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import {
+  createApp,
+  proxyConfigToConfig
+} from "./chunk-VL6QOQ2T.js";
+
+// src/cli.ts
+import { resolve } from "path";
+import { existsSync } from "fs";
+import { pathToFileURL } from "url";
+import { serve } from "@hono/node-server";
+var args = process.argv.slice(2);
+var command = args[0] || "dev";
+if (command === "--help" || command === "-h") {
+  console.log(`
+tsproxy - Typesense Proxy Server
+
+Usage:
+  tsproxy dev          Start in development mode (with hot reload hints)
+  tsproxy start        Start in production mode
+  tsproxy validate     Validate the config file
+  tsproxy --help       Show this help
+
+Options:
+  --config, -c <path>  Path to config file (default: tsproxy.config.ts)
+  --port, -p <port>    Override the port
+
+Config File:
+  Create a tsproxy.config.ts in your project root:
+
+  import { defineConfig } from "@tsproxy/api";
+
+  export default defineConfig({
+    typesense: {
+      host: "localhost",
+      port: 8108,
+      apiKey: "your-api-key",
+    },
+    collections: {
+      products: {
+        fields: {
+          title: { type: "string", searchable: true },
+          price: { type: "float", sortable: true },
+          category: { type: "string", facet: true },
+        },
+        locales: ["en", "fr"],
+      },
+    },
+  });
+`);
+  process.exit(0);
+}
+if (command === "--version" || command === "-V") {
+  console.log("0.1.0");
+  process.exit(0);
+}
+var configPath;
+var portOverride;
+for (let i = 1; i < args.length; i++) {
+  const arg = args[i];
+  if ((arg === "--config" || arg === "-c") && args[i + 1]) {
+    configPath = args[++i];
+  } else if ((arg === "--port" || arg === "-p") && args[i + 1]) {
+    portOverride = parseInt(args[++i], 10);
+  }
+}
+async function loadProxyConfig() {
+  if (configPath) {
+    const filePath = resolve(configPath);
+    if (existsSync(filePath)) {
+      return importConfig(filePath);
+    }
+    return null;
+  }
+  const configNames = ["tsproxy.config.ts", "tsproxy.config.js", "tsproxy.config.mjs"];
+  let dir = resolve(process.cwd());
+  const root = resolve("/");
+  while (dir !== root) {
+    for (const name of configNames) {
+      const filePath = resolve(dir, name);
+      if (existsSync(filePath)) {
+        return importConfig(filePath);
+      }
+    }
+    dir = resolve(dir, "..");
+  }
+  return null;
+}
+async function importConfig(filePath) {
+  try {
+    const fileUrl = pathToFileURL(filePath).href;
+    const mod = await import(`${fileUrl}?t=${Date.now()}`);
+    const config = mod.default || mod;
+    console.log(`Loaded config from ${filePath}`);
+    return config;
+  } catch (error) {
+    console.error(`Error loading config from ${filePath}:`, error);
+    process.exit(1);
+  }
+}
+async function main() {
+  const proxyConfig = await loadProxyConfig();
+  if (command === "validate") {
+    if (!proxyConfig) {
+      console.error("No config file found. Create tsproxy.config.ts");
+      process.exit(1);
+    }
+    console.log("Config is valid!");
+    console.log(`Collections: ${Object.keys(proxyConfig.collections || {}).join(", ") || "(none)"}`);
+    if (proxyConfig.typesense) {
+      console.log(`Typesense: ${proxyConfig.typesense.protocol || "http"}://${proxyConfig.typesense.host}:${proxyConfig.typesense.port}`);
+    }
+    process.exit(0);
+  }
+  const config = proxyConfig ? proxyConfigToConfig(proxyConfig) : void 0;
+  if (portOverride && config) {
+    config.proxy.port = portOverride;
+  }
+  const { app, config: finalConfig } = createApp(config, proxyConfig?.collections);
+  const port = portOverride || finalConfig.proxy.port;
+  const isDev = command === "dev";
+  if (isDev) {
+    console.log("\n  tsproxy dev server\n");
+  } else {
+    console.log("\n  tsproxy production server\n");
+  }
+  console.log(`  Typesense:  ${finalConfig.typesense.protocol}://${finalConfig.typesense.host}:${finalConfig.typesense.port}`);
+  console.log(`  Cache:      TTL=${finalConfig.cache.ttl}s, max=${finalConfig.cache.maxSize}`);
+  console.log(`  Queue:      concurrency=${finalConfig.queue.concurrency}, max=${finalConfig.queue.maxSize}`);
+  console.log(`  Rate limit: search=${finalConfig.rateLimit.search}/min, ingest=${finalConfig.rateLimit.ingest}/min`);
+  const collectionNames = Object.keys(finalConfig.collections.collections);
+  if (collectionNames.length > 0) {
+    console.log(`  Collections: ${collectionNames.join(", ")}`);
+  }
+  console.log();
+  serve(
+    {
+      fetch: app.fetch,
+      port
+    },
+    (info) => {
+      console.log(`  Listening on http://localhost:${info.port}`);
+      console.log(`  API docs:   http://localhost:${info.port}/api/docs`);
+      console.log(`  Health:     http://localhost:${info.port}/api/health`);
+      console.log();
+    }
+  );
+}
+main().catch((error) => {
+  console.error("Failed to start:", error);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+import * as hono_types from 'hono/types';
+import { Hono } from 'hono';
+
+interface LocaleMap {
+    [locale: string]: string;
+}
+interface CollectionConfig {
+    locales?: LocaleMap;
+}
+interface CollectionsConfig {
+    collections: Record<string, CollectionConfig>;
+}
+interface Config {
+    typesense: {
+        host: string;
+        port: number;
+        protocol: string;
+        apiKey: string;
+    };
+    proxy: {
+        port: number;
+        apiKey: string;
+    };
+    cache: {
+        ttl: number;
+        maxSize: number;
+    };
+    queue: {
+        concurrency: number;
+        maxSize: number;
+        redis?: {
+            host: string;
+            port: number;
+        };
+    };
+    rateLimit: {
+        search: number;
+        ingest: number;
+    };
+    collections: CollectionsConfig;
+}
+declare function loadConfig(): Config;
+declare function resolveCollection(config: CollectionsConfig, collection: string, locale?: string): string;
+
+/**
+ * Field type definition for a collection field
+ */
+interface FieldConfig {
+    type: "string" | "string[]" | "int32" | "int32[]" | "int64" | "int64[]" | "float" | "float[]" | "bool" | "bool[]" | "geopoint" | "geopoint[]" | "object" | "object[]" | "auto";
+    /** Make this field searchable (included in query_by) */
+    searchable?: boolean;
+    /** Enable faceting on this field */
+    facet?: boolean;
+    /** Enable sorting on this field */
+    sortable?: boolean;
+    /** Allow null/missing values */
+    optional?: boolean;
+    /** Language locale for stemming */
+    locale?: string;
+    /** Enable infix search */
+    infix?: boolean;
+    /**
+     * Compute this field's value from the document during ingestion.
+     * The function receives the full document and the locale (if available)
+     * and returns the field value.
+     * Computed fields are automatically added before sending to Typesense.
+     *
+     * Example:
+     * ```ts
+     * category_page_slug: {
+     *   type: "string",
+     *   facet: true,
+     *   compute: (doc, locale) => {
+     *     const color = String(doc.color || "").toLowerCase();
+     *     const category = String(doc.category || "").toLowerCase();
+     *     return `${color}-${category}`.replace(/\s+/g, '-');
+     *   },
+     * }
+     * ```
+     */
+    compute?: (doc: Record<string, unknown>, locale?: string) => unknown;
+}
+/**
+ * Collection definition in the proxy config
+ */
+interface CollectionDefinition {
+    /** Field definitions */
+    fields: Record<string, FieldConfig>;
+    /** Supported locales — creates separate collections per locale */
+    locales?: string[];
+    /** Default sorting field */
+    defaultSortBy?: string;
+    /** Token separators */
+    tokenSeparators?: string[];
+    /** Symbols to index */
+    symbolsToIndex?: string[];
+    /** Enable nested fields */
+    enableNestedFields?: boolean;
+}
+/**
+ * Proxy configuration file schema (tsproxy.config.ts)
+ */
+interface ProxyConfig {
+    /** Typesense connection settings */
+    typesense?: {
+        host?: string;
+        port?: number;
+        protocol?: "http" | "https";
+        apiKey?: string;
+    };
+    /** Proxy server settings */
+    server?: {
+        port?: number;
+        /** API key required for ingest endpoints */
+        apiKey?: string;
+    };
+    /** Search cache settings */
+    cache?: {
+        /** TTL in seconds (default: 60) */
+        ttl?: number;
+        /** Max cached entries (default: 1000) */
+        maxSize?: number;
+    };
+    /** Ingestion queue settings */
+    queue?: {
+        /** Max concurrent Typesense writes (default: 5) */
+        concurrency?: number;
+        /** Max queued tasks before rejecting (default: 10000) */
+        maxSize?: number;
+        /** Redis connection for persistent queue (falls back to in-memory) */
+        redis?: {
+            host?: string;
+            port?: number;
+        };
+    };
+    /** Rate limiting (requests per minute) */
+    rateLimit?: {
+        /** Search endpoint rate limit (default: 100) */
+        search?: number;
+        /** Ingest endpoint rate limit (default: 30) */
+        ingest?: number;
+    };
+    /** Collection definitions */
+    collections?: Record<string, CollectionDefinition>;
+}
+/**
+ * Helper to define a typed proxy config
+ */
+declare function defineConfig(config: ProxyConfig): ProxyConfig;
+/**
+ * Convert ProxyConfig to the internal Config format
+ */
+declare function proxyConfigToConfig(proxyConfig: ProxyConfig): Config;
+/**
+ * Get searchable fields from a collection definition
+ */
+declare function getSearchableFields(def: CollectionDefinition): string[];
+/**
+ * Get facet fields from a collection definition
+ */
+declare function getFacetFields(def: CollectionDefinition): string[];
+/**
+ * Get sortable fields from a collection definition
+ */
+declare function getSortableFields(def: CollectionDefinition): string[];
+/**
+ * Convert a collection definition to a Typesense collection schema
+ * (compatible with tsctl's defineConfig format)
+ */
+declare function toTypesenseSchema(name: string, def: CollectionDefinition): {
+    enable_nested_fields?: boolean | undefined;
+    symbols_to_index?: string[] | undefined;
+    token_separators?: string[] | undefined;
+    default_sorting_field?: string | undefined;
+    name: string;
+    fields: Record<string, unknown>[];
+};
+/**
+ * Get computed fields from a collection definition
+ */
+declare function getComputedFields(def: CollectionDefinition): Array<{
+    name: string;
+    compute: (doc: Record<string, unknown>, locale?: string) => unknown;
+}>;
+/**
+ * Apply computed fields to a document.
+ * Runs all compute functions defined in the collection config
+ * and adds the resulting values to the document.
+ * The locale is passed to compute functions for localized field generation.
+ */
+declare function applyComputedFields(doc: Record<string, unknown>, collectionDef: CollectionDefinition, locale?: string): Record<string, unknown>;
+/**
+ * Apply computed fields to an array of documents.
+ */
+declare function applyComputedFieldsBatch(docs: Record<string, unknown>[], collectionDef: CollectionDefinition, locale?: string): Record<string, unknown>[];
+
+interface CacheStats {
+    size: number;
+    maxSize: number;
+    ttl: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
+declare class LRUCache<T = unknown> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttl;
+    private hits;
+    private misses;
+    constructor(options: {
+        maxSize: number;
+        ttl: number;
+    });
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    invalidate(key?: string): void;
+    stats(): CacheStats;
+}
+
+interface QueueStats {
+    pending: number;
+    active: number;
+    completed: number;
+    failed: number;
+    maxSize: number;
+    concurrency: number;
+    backend: "redis" | "memory";
+}
+interface QueueOptions {
+    concurrency: number;
+    maxSize: number;
+    redis?: {
+        host?: string;
+        port?: number;
+    };
+}
+/**
+ * Ingestion queue backed by BullMQ (Redis) with in-memory fallback.
+ *
+ * When Redis is available, jobs are persisted and survive server restarts.
+ * When Redis is unavailable, falls back to a simple in-memory queue.
+ */
+declare class IngestionQueue {
+    private readonly concurrency;
+    private readonly maxSize;
+    private backend;
+    private bullQueue;
+    private bullWorker;
+    private jobHandlers;
+    private memPending;
+    private memActiveCount;
+    private memCompletedCount;
+    private memFailedCount;
+    constructor(options: QueueOptions);
+    private initRedis;
+    private fallbackToMemory;
+    enqueue<T>(fn: () => Promise<T>): Promise<T>;
+    private enqueueRedis;
+    private enqueueMemory;
+    stats(): Promise<QueueStats>;
+    close(): Promise<void>;
+    private processMemory;
+}
+
+/**
+ * Transform between Algolia InstantSearch format and Typesense search format.
+ */
+interface AlgoliaSearchRequest {
+    indexName: string;
+    params: string | Record<string, unknown>;
+}
+interface AlgoliaMultiSearchRequest {
+    requests: AlgoliaSearchRequest[];
+}
+interface AlgoliaHighlightResult {
+    value: string;
+    matchLevel: "none" | "partial" | "full";
+    matchedWords: string[];
+    fullyHighlighted?: boolean;
+}
+interface AlgoliaHit {
+    objectID: string;
+    _highlightResult: Record<string, AlgoliaHighlightResult>;
+    [key: string]: unknown;
+}
+interface AlgoliaSearchResult {
+    hits: AlgoliaHit[];
+    nbHits: number;
+    page: number;
+    nbPages: number;
+    hitsPerPage: number;
+    processingTimeMS: number;
+    query: string;
+    params: string;
+    facets: Record<string, Record<string, number>>;
+    facets_stats: Record<string, unknown>;
+    exhaustiveNbHits: boolean;
+}
+interface AlgoliaMultiSearchResponse {
+    results: AlgoliaSearchResult[];
+}
+interface TypesenseSearchParams {
+    q: string;
+    query_by?: string;
+    filter_by?: string;
+    sort_by?: string;
+    facet_by?: string;
+    max_facet_values?: number;
+    page?: number;
+    per_page?: number;
+    highlight_full_fields?: string;
+    highlight_affix_num_tokens?: number;
+    highlight_start_tag?: string;
+    highlight_end_tag?: string;
+    [key: string]: unknown;
+}
+interface TypesenseMultiSearchParams {
+    searches: Array<TypesenseSearchParams & {
+        collection: string;
+    }>;
+}
+interface TypesenseHighlight {
+    field: string;
+    snippet?: string;
+    value?: string;
+    matched_tokens?: string[];
+    snippets?: Array<{
+        value: string;
+        matched_tokens?: string[];
+    }>;
+    indices?: number[];
+}
+interface TypesenseHit {
+    document: Record<string, unknown>;
+    highlights?: TypesenseHighlight[];
+    text_match?: number;
+    text_match_info?: Record<string, unknown>;
+}
+interface TypesenseFacetCount {
+    field_name: string;
+    counts: Array<{
+        value: string;
+        count: number;
+    }>;
+    stats?: {
+        min?: number;
+        max?: number;
+        avg?: number;
+        sum?: number;
+    };
+}
+interface TypesenseSearchResponse {
+    found: number;
+    hits?: TypesenseHit[];
+    search_time_ms: number;
+    facet_counts?: TypesenseFacetCount[];
+    page?: number;
+    out_of?: number;
+    request_params?: Record<string, unknown>;
+}
+interface TypesenseMultiSearchResponse {
+    results: TypesenseSearchResponse[];
+}
+declare function transformAlgoliaRequestToTypesense(request: AlgoliaSearchRequest, resolvedCollection: string): TypesenseSearchParams & {
+    collection: string;
+};
+declare function transformTypesenseResponseToAlgolia(tsResponse: TypesenseSearchResponse, originalRequest: AlgoliaSearchRequest): AlgoliaSearchResult;
+declare function transformMultiSearchResponse(tsResponse: TypesenseMultiSearchResponse, originalRequests: AlgoliaSearchRequest[]): AlgoliaMultiSearchResponse;
+
+declare function createApp(config?: Config, collectionDefs?: Record<string, CollectionDefinition>): {
+    app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    config: Config;
+    searchCache: LRUCache<unknown>;
+    ingestQueue: IngestionQueue;
+};
+
+export { type AlgoliaHighlightResult, type AlgoliaHit, type AlgoliaMultiSearchRequest, type AlgoliaMultiSearchResponse, type AlgoliaSearchRequest, type AlgoliaSearchResult, type CacheStats, type CollectionDefinition, type Config, type FieldConfig, IngestionQueue, LRUCache, type ProxyConfig, type QueueStats, type TypesenseMultiSearchParams, type TypesenseMultiSearchResponse, type TypesenseSearchParams, type TypesenseSearchResponse, applyComputedFields, applyComputedFieldsBatch, createApp, defineConfig, getComputedFields, getFacetFields, getSearchableFields, getSortableFields, loadConfig, proxyConfigToConfig, resolveCollection, toTypesenseSchema, transformAlgoliaRequestToTypesense, transformMultiSearchResponse, transformTypesenseResponseToAlgolia };

package/dist/index.js

@@ -0,0 +1,38 @@
+import {
+  IngestionQueue,
+  LRUCache,
+  applyComputedFields,
+  applyComputedFieldsBatch,
+  createApp,
+  defineConfig,
+  getComputedFields,
+  getFacetFields,
+  getSearchableFields,
+  getSortableFields,
+  loadConfig,
+  proxyConfigToConfig,
+  resolveCollection,
+  toTypesenseSchema,
+  transformAlgoliaRequestToTypesense,
+  transformMultiSearchResponse,
+  transformTypesenseResponseToAlgolia
+} from "./chunk-VL6QOQ2T.js";
+export {
+  IngestionQueue,
+  LRUCache,
+  applyComputedFields,
+  applyComputedFieldsBatch,
+  createApp,
+  defineConfig,
+  getComputedFields,
+  getFacetFields,
+  getSearchableFields,
+  getSortableFields,
+  loadConfig,
+  proxyConfigToConfig,
+  resolveCollection,
+  toTypesenseSchema,
+  transformAlgoliaRequestToTypesense,
+  transformMultiSearchResponse,
+  transformTypesenseResponseToAlgolia
+};

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,19 @@
+import {
+  createApp
+} from "./chunk-VL6QOQ2T.js";
+
+// src/server.ts
+import { serve } from "@hono/node-server";
+var { app, config } = createApp();
+console.log(`Starting Typesense Proxy on port ${config.proxy.port}...`);
+console.log(`Typesense backend: ${config.typesense.protocol}://${config.typesense.host}:${config.typesense.port}`);
+serve(
+  {
+    fetch: app.fetch,
+    port: config.proxy.port
+  },
+  (info) => {
+    console.log(`Proxy server listening on http://localhost:${info.port}`);
+    console.log(`API docs available at http://localhost:${info.port}/api/docs`);
+  }
+);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@tsproxy/api",
+  "version": "0.0.1",
+  "description": "HonoJS proxy server for Typesense with caching, rate limiting, and ingestion queue",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "tsproxy-server": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akshitkrnagpal/tsproxy.git",
+    "directory": "packages/api"
+  },
+  "license": "MIT",
+  "keywords": [
+    "typesense",
+    "search",
+    "proxy",
+    "hono",
+    "cache",
+    "rate-limit"
+  ],
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@hono/zod-openapi": "^0.18.0",
+    "bullmq": "^5.73.0",
+    "hono": "^4.7.0",
+    "hono-rate-limiter": "^0.5.0",
+    "typesense": "^3.0.0-2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "dev": "tsx watch src/cli.ts dev",
+    "build": "tsup src/index.ts src/server.ts src/cli.ts --format esm --dts --tsconfig tsconfig.build.json",
+    "start": "node dist/cli.js start",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}