@rubixstudios/payload-typesense 1.0.0

package/dist/endpoints/search.js

@@ -0,0 +1,375 @@
+import { searchCache } from '../lib/cache.js';
+import { getValidationErrors, validateSearchParams } from '../lib/config-validation.js';
+import { createDetailedHealthCheckHandler, createHealthCheckHandler } from './health.js';
+// Universal search across all collections
+const searchAllCollections = async (typesenseClient, pluginOptions, query, options)=>{
+    try {
+        // Universal search logic
+        // Check cache first
+        const cachedResult = searchCache.get(query, 'universal', options);
+        if (cachedResult) {
+            // Return cached result
+            return Response.json(cachedResult);
+        }
+        const enabledCollections = Object.entries(pluginOptions.collections || {}).filter(([_, config])=>config?.enabled);
+        // Process enabled collections
+        if (enabledCollections.length === 0) {
+            return Response.json({
+                error: 'No collections enabled for search'
+            }, {
+                status: 400
+            });
+        }
+        // Search all collections in parallel
+        const searchPromises = enabledCollections.map(async ([collectionName, config])=>{
+            try {
+                const searchParameters = {
+                    highlight_full_fields: config?.searchFields?.join(',') || 'title,content',
+                    num_typos: 0,
+                    page: options.page,
+                    per_page: Math.ceil(options.per_page / enabledCollections.length),
+                    q: query,
+                    query_by: config?.searchFields?.join(',') || 'title,content',
+                    snippet_threshold: 30,
+                    typo_tokens_threshold: 1
+                };
+                // Search collection
+                const results = await typesenseClient.collections(collectionName).documents().search(searchParameters);
+                // Process results
+                // Add collection metadata to each hit
+                return {
+                    collection: collectionName,
+                    displayName: config?.displayName || collectionName,
+                    icon: config?.icon || '📄',
+                    ...results,
+                    hits: results.hits?.map((hit)=>({
+                            ...hit,
+                            collection: collectionName,
+                            displayName: config?.displayName || collectionName,
+                            icon: config?.icon || '📄'
+                        })) || []
+                };
+            } catch (_error) {
+                // Handle search error
+                return {
+                    collection: collectionName,
+                    displayName: config?.displayName || collectionName,
+                    error: _error instanceof Error ? _error.message : 'Unknown error',
+                    found: 0,
+                    hits: [],
+                    icon: config?.icon || '📄'
+                };
+            }
+        });
+        const results = await Promise.all(searchPromises);
+        // Combine results
+        const combinedHits = results.flatMap((result)=>result.hits || []);
+        const totalFound = results.reduce((sum, result)=>sum + (result.found || 0), 0);
+        // Sort combined results by relevance (text_match score)
+        combinedHits.sort((a, b)=>(b.text_match || 0) - (a.text_match || 0));
+        const searchResult = {
+            collections: results.map((r)=>({
+                    collection: r.collection,
+                    displayName: r.displayName,
+                    error: r.error,
+                    found: r.found || 0,
+                    icon: r.icon
+                })),
+            found: totalFound,
+            hits: combinedHits.slice(0, options.per_page),
+            page: options.page,
+            request_params: {
+                per_page: options.per_page,
+                q: query
+            },
+            search_cutoff: false,
+            search_time_ms: 0
+        };
+        // Cache the result
+        searchCache.set(query, searchResult, 'universal', options);
+        return Response.json(searchResult);
+    } catch (error) {
+        // Handle universal search error
+        return Response.json({
+            details: error instanceof Error ? error.message : 'Unknown error',
+            error: 'Universal search failed'
+        }, {
+            status: 500
+        });
+    }
+};
+export const createSearchEndpoints = (typesenseClient, pluginOptions, lastSyncTime)=>{
+    return [
+        {
+            handler: createCollectionsHandler(pluginOptions),
+            method: 'get',
+            path: '/search/collections'
+        },
+        {
+            handler: createSuggestHandler(typesenseClient, pluginOptions),
+            method: 'get',
+            path: '/search/:collectionName/suggest'
+        },
+        {
+            handler: createSearchHandler(typesenseClient, pluginOptions),
+            method: 'get',
+            path: '/search/:collectionName'
+        },
+        {
+            handler: createAdvancedSearchHandler(typesenseClient, pluginOptions),
+            method: 'post',
+            path: '/search/:collectionName'
+        },
+        {
+            handler: createSearchHandler(typesenseClient, pluginOptions),
+            method: 'get',
+            path: '/search'
+        },
+        {
+            handler: createHealthCheckHandler(typesenseClient, pluginOptions, lastSyncTime),
+            method: 'get',
+            path: '/search/health'
+        },
+        {
+            handler: createDetailedHealthCheckHandler(typesenseClient, pluginOptions, lastSyncTime),
+            method: 'get',
+            path: '/search/health/detailed'
+        }
+    ];
+};
+const createSearchHandler = (typesenseClient, pluginOptions)=>{
+    return async (request)=>{
+        try {
+            // Extract query parameters from the request
+            const { params, query } = request;
+            // Extract collection name from URL path (fallback to params if available)
+            let collectionName;
+            let collectionNameStr;
+            if (request.url && typeof request.url === 'string') {
+                const url = new URL(request.url);
+                const pathParts = url.pathname.split('/');
+                const searchIndex = pathParts.indexOf('search');
+                if (searchIndex !== -1 && pathParts[searchIndex + 1]) {
+                    collectionName = pathParts[searchIndex + 1] || '';
+                    collectionNameStr = String(collectionName);
+                } else {
+                    collectionName = '';
+                    collectionNameStr = '';
+                }
+            } else {
+                // Fallback to params extraction
+                const { collectionName: paramCollectionName } = params || {};
+                collectionName = String(paramCollectionName || '');
+                collectionNameStr = collectionName;
+            }
+            // Extract search parameters
+            const q = typeof query?.q === 'string' ? query.q : '';
+            const pageParam = query?.page;
+            const perPageParam = query?.per_page;
+            const page = typeof pageParam === 'string' || typeof pageParam === 'number' ? parseInt(String(pageParam), 10) : 1;
+            const per_page = typeof perPageParam === 'string' || typeof perPageParam === 'number' ? parseInt(String(perPageParam), 10) : 10;
+            const sort_by = query?.sort_by;
+            // Validate parsed numbers
+            if (isNaN(page) || page < 1) {
+                return Response.json({
+                    error: 'Invalid page parameter'
+                }, {
+                    status: 400
+                });
+            }
+            if (isNaN(per_page) || per_page < 1 || per_page > 250) {
+                return Response.json({
+                    error: 'Invalid per_page parameter'
+                }, {
+                    status: 400
+                });
+            }
+            // Process search request
+            // Validate search parameters
+            const searchParams = {
+                page,
+                per_page,
+                q,
+                sort_by: sort_by
+            };
+            const validation = validateSearchParams(searchParams);
+            if (!validation.success) {
+                return Response.json({
+                    details: getValidationErrors(validation.errors || []),
+                    error: 'Invalid search parameters'
+                }, {
+                    status: 400
+                });
+            }
+            // If no collection specified, search across all enabled collections
+            if (!collectionName) {
+                if (!q || q.trim() === '') {
+                    return Response.json({
+                        details: 'Please provide a search query using ?q=your_search_term',
+                        error: 'Query parameter "q" is required',
+                        example: '/api/search?q=example'
+                    }, {
+                        status: 400
+                    });
+                }
+                const searchOptions = {
+                    filters: {},
+                    page,
+                    per_page
+                };
+                if (sort_by && typeof sort_by === 'string') {
+                    searchOptions.sort_by = sort_by;
+                }
+                return await searchAllCollections(typesenseClient, pluginOptions, q, searchOptions);
+            }
+            // Validate collection is enabled
+            if (!pluginOptions.collections?.[collectionNameStr]?.enabled) {
+                return Response.json({
+                    error: 'Collection not enabled for search'
+                }, {
+                    status: 400
+                });
+            }
+            if (!q) {
+                return Response.json({
+                    error: 'Query parameter "q" is required'
+                }, {
+                    status: 400
+                });
+            }
+            const searchParameters = {
+                highlight_full_fields: pluginOptions.collections?.[collectionNameStr]?.searchFields?.join(',') || 'title,content',
+                num_typos: 0,
+                page: Number(page),
+                per_page: Number(per_page),
+                q: String(q),
+                query_by: pluginOptions.collections?.[collectionNameStr]?.searchFields?.join(',') || 'title,content',
+                snippet_threshold: 30,
+                typo_tokens_threshold: 1
+            };
+            // Add sorting
+            if (sort_by && typeof sort_by === 'string') {
+                searchParameters.sort_by = sort_by;
+            }
+            // Execute Typesense search
+            // Check cache first
+            const cacheOptions = {
+                collection: collectionName,
+                page,
+                per_page,
+                sort_by
+            };
+            const cachedResult = searchCache.get(q, collectionNameStr, cacheOptions);
+            if (cachedResult) {
+                // Return cached result
+                return Response.json(cachedResult);
+            }
+            const searchResults = await typesenseClient.collections(collectionNameStr).documents().search(searchParameters);
+            // Process search results
+            // Cache the result
+            searchCache.set(q, searchResults, collectionNameStr, cacheOptions);
+            return Response.json(searchResults);
+        } catch (_error) {
+            // Handle search error
+            return Response.json({
+                details: _error instanceof Error ? _error.message : 'Unknown error',
+                error: 'Search handler failed'
+            }, {
+                status: 500
+            });
+        }
+    };
+};
+const createAdvancedSearchHandler = (typesenseClient, pluginOptions)=>{
+    return async (request)=>{
+        const { params, req } = request;
+        const { collectionName } = params || {};
+        const collectionNameStr = String(collectionName || '');
+        const body = await req?.json?.() || {};
+        if (!pluginOptions.collections?.[collectionNameStr]?.enabled) {
+            return Response.json({
+                error: 'Collection not enabled for search'
+            }, {
+                status: 400
+            });
+        }
+        try {
+            const searchResults = await typesenseClient.collections(collectionNameStr).documents().search(body);
+            return Response.json(searchResults);
+        } catch (_error) {
+            // Handle advanced search error
+            return Response.json({
+                error: 'Advanced search failed'
+            }, {
+                status: 500
+            });
+        }
+    };
+};
+const createSuggestHandler = (typesenseClient, pluginOptions)=>{
+    return async (request)=>{
+        // Extract collection name from URL path
+        const url = new URL(request.url);
+        const pathParts = url.pathname.split('/');
+        const collectionName = pathParts[pathParts.indexOf('search') + 1];
+        const collectionNameStr = String(collectionName || '');
+        // Extract query parameters
+        const q = url.searchParams.get('q');
+        const limit = url.searchParams.get('limit') || '5';
+        if (!collectionName || !pluginOptions.collections?.[collectionNameStr]?.enabled) {
+            return Response.json({
+                error: 'Collection not enabled for search'
+            }, {
+                status: 400
+            });
+        }
+        if (!q) {
+            return Response.json({
+                error: 'Query parameter "q" is required'
+            }, {
+                status: 400
+            });
+        }
+        try {
+            const suggestResults = await typesenseClient.collections(collectionNameStr).documents().search({
+                highlight_full_fields: pluginOptions.collections?.[collectionNameStr]?.searchFields?.join(',') || 'title,content',
+                per_page: Number(limit),
+                q,
+                query_by: pluginOptions.collections?.[collectionNameStr]?.searchFields?.join(',') || 'title,content',
+                snippet_threshold: 30
+            });
+            return Response.json(suggestResults);
+        } catch (_error) {
+            // Handle suggest error
+            return Response.json({
+                error: 'Suggest failed'
+            }, {
+                status: 500
+            });
+        }
+    };
+};
+const createCollectionsHandler = (pluginOptions)=>{
+    return ()=>{
+        try {
+            const collections = Object.entries(pluginOptions.collections || {}).filter(([_, config])=>config?.enabled).map(([slug, config])=>({
+                    slug,
+                    displayName: config?.displayName || slug.charAt(0).toUpperCase() + slug.slice(1),
+                    facetFields: config?.facetFields || [],
+                    icon: config?.icon || '📄',
+                    searchFields: config?.searchFields || []
+                }));
+            return Response.json({
+                categorized: pluginOptions.settings?.categorized || false,
+                collections
+            });
+        } catch (_error) {
+            // Handle collections error
+            return Response.json({
+                error: 'Failed to get collections'
+            }, {
+                status: 500
+            });
+        }
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { Config } from 'payload';
+export * from './components/index.js';
+export type TypesenseSearchConfig = {
+    /**
+     * Collections to index in Typesense
+     */
+    collections?: Partial<Record<string, {
+        displayName?: string;
+        enabled: boolean;
+        facetFields?: string[];
+        icon?: string;
+        searchFields?: string[];
+        sortFields?: string[];
+    }>>;
+    disabled?: boolean;
+    /**
+     * Global plugin settings
+     */
+    settings?: {
+        autoSync?: boolean;
+        batchSize?: number;
+        categorized?: boolean;
+        searchEndpoint?: string;
+    };
+    /**
+     * Typesense server configuration
+     */
+    typesense: {
+        apiKey: string;
+        connectionTimeoutSeconds?: number;
+        nodes: Array<{
+            host: string;
+            port: number | string;
+            protocol: 'http' | 'https';
+        }>;
+    };
+};
+export declare const typesenseSearch: (pluginOptions: TypesenseSearchConfig) => (config: Config) => Config;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAQrC,cAAc,uBAAuB,CAAA;AAErC,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CACnB,MAAM,CACJ,MAAM,EACN;QACE,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,OAAO,EAAE,OAAO,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;QACtB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;QACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KACtB,CACF,CACF,CAAA;IAED,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,WAAW,CAAC,EAAE,OAAO,CAAA;QACrB,cAAc,CAAC,EAAE,MAAM,CAAA;KACxB,CAAA;IAED;;OAEG;IACH,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAA;QACd,wBAAwB,CAAC,EAAE,MAAM,CAAA;QACjC,KAAK,EAAE,KAAK,CAAC;YACX,IAAI,EAAE,MAAM,CAAA;YACZ,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;YACrB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;SAC3B,CAAC,CAAA;KACH,CAAA;CACF,CAAA;AAED,eAAO,MAAM,eAAe,GACzB,eAAe,qBAAqB,MACpC,QAAQ,MAAM,KAAG,MA6DjB,CAAA"}

package/dist/index.js

@@ -0,0 +1,148 @@
+import { createSearchEndpoints } from './endpoints/search.js';
+import { initializeTypesenseCollections } from './lib/initialization.js';
+import { mapPayloadDocumentToTypesense } from './lib/schema-mapper.js';
+import { createTypesenseClient } from './lib/typesense-client.js';
+export * from './components/index.js';
+export const typesenseSearch = (pluginOptions)=>(config)=>{
+        if (pluginOptions.disabled) {
+            return config;
+        }
+        // Initialize Typesense client
+        const typesenseClient = createTypesenseClient(pluginOptions.typesense);
+        // Add search endpoints
+        config.endpoints = [
+            ...config.endpoints || [],
+            ...createSearchEndpoints(typesenseClient, pluginOptions, Date.now())
+        ];
+        // Apply hooks to individual collections
+        if (pluginOptions.settings?.autoSync !== false && pluginOptions.collections) {
+            config.collections = (config.collections || []).map((collection)=>{
+                const collectionConfig = pluginOptions.collections?.[collection.slug];
+                if (collectionConfig?.enabled) {
+                    return {
+                        ...collection,
+                        hooks: {
+                            ...collection.hooks,
+                            afterChange: [
+                                ...collection.hooks?.afterChange || [],
+                                async ({ doc, operation, req: _req })=>{
+                                    await syncDocumentToTypesense(typesenseClient, collection.slug, doc, operation, collectionConfig);
+                                }
+                            ],
+                            afterDelete: [
+                                ...collection.hooks?.afterDelete || [],
+                                async ({ doc, req: _req })=>{
+                                    await deleteDocumentFromTypesense(typesenseClient, collection.slug, doc.id);
+                                }
+                            ]
+                        }
+                    };
+                }
+                return collection;
+            });
+        }
+        // Initialize collections in Typesense
+        const incomingOnInit = config.onInit;
+        config.onInit = async (payload)=>{
+            if (incomingOnInit) {
+                await incomingOnInit(payload);
+            }
+            await initializeTypesenseCollections(payload, typesenseClient, pluginOptions);
+        };
+        return config;
+    };
+// Helper function to create collection if it doesn't exist
+const createCollectionIfNotExists = async (typesenseClient, collectionSlug, config)=>{
+    const searchableFields = config?.searchFields || [
+        'title',
+        'content',
+        'description'
+    ];
+    const facetFields = config?.facetFields || [];
+    // Base fields that every collection should have
+    const baseFields = [
+        {
+            name: 'id',
+            type: 'string'
+        },
+        {
+            name: 'createdAt',
+            type: 'int64'
+        },
+        {
+            name: 'updatedAt',
+            type: 'int64'
+        }
+    ];
+    // Map searchable fields
+    const searchFields = searchableFields.map((field)=>({
+            name: field,
+            type: 'string',
+            facet: facetFields.includes(field)
+        }));
+    // Map facet-only fields (not in searchable fields)
+    const facetOnlyFields = facetFields.filter((field)=>!searchableFields.includes(field)).map((field)=>({
+            name: field,
+            type: 'string',
+            facet: true
+        }));
+    const schema = {
+        name: collectionSlug,
+        fields: [
+            ...baseFields,
+            ...searchFields,
+            ...facetOnlyFields
+        ]
+    };
+    await typesenseClient.collections().create(schema);
+// Collection created successfully
+};
+// Sync functions for hooks
+const syncDocumentToTypesense = async (typesenseClient, collectionSlug, doc, operation, config)=>{
+    try {
+        // First check if the collection exists, create it if it doesn't
+        try {
+            await typesenseClient.collections(collectionSlug).retrieve();
+        } catch (collectionError) {
+            if (collectionError.httpStatus === 404) {
+                // Collection not found, creating it
+                await createCollectionIfNotExists(typesenseClient, collectionSlug, config);
+            } else {
+                throw collectionError;
+            }
+        }
+        const typesenseDoc = mapPayloadDocumentToTypesense(doc, collectionSlug, config);
+        await typesenseClient.collections(collectionSlug).documents().upsert(typesenseDoc);
+    // Document synced successfully
+    } catch (error) {
+        // Handle document sync error
+        // Log the problematic document for debugging
+        if (error.message.includes('validation')) {
+        // Log problematic document details
+        }
+    }
+};
+const deleteDocumentFromTypesense = async (typesenseClient, collectionSlug, docId)=>{
+    try {
+        // First check if the collection exists
+        try {
+            await typesenseClient.collections(collectionSlug).retrieve();
+        } catch (collectionError) {
+            if (collectionError.httpStatus === 404) {
+                // Collection not found, skipping delete
+                return;
+            }
+            throw collectionError;
+        }
+        // Try to delete the document
+        await typesenseClient.collections(collectionSlug).documents(docId).delete();
+    // Document deleted successfully
+    } catch (error) {
+        // Handle specific error cases
+        if (error.httpStatus === 404) {
+        // Document not found, already deleted
+        } else {
+        // Handle document deletion error
+        }
+    }
+};

package/dist/lib/cache.d.ts

@@ -0,0 +1,41 @@
+import type { CacheOptions } from './types.js';
+export declare class SearchCache<T = any> {
+    private cache;
+    private readonly defaultTTL;
+    private readonly maxSize;
+    constructor(options?: CacheOptions);
+    /**
+     * Generate cache key from search parameters
+     */
+    private generateKey;
+    /**
+     * Clear expired entries
+     */
+    cleanup(): void;
+    /**
+     * Clear cache entries matching pattern
+     */
+    clear(pattern?: string): void;
+    /**
+     * Get cached search result
+     */
+    get(query: string, collection?: string, params?: Record<string, any>): null | T;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        hitRate?: number;
+        maxSize: number;
+        size: number;
+    };
+    /**
+     * Check if cache has valid entry
+     */
+    has(query: string, collection?: string, params?: Record<string, any>): boolean;
+    /**
+     * Set cached search result
+     */
+    set(query: string, data: T, collection?: string, params?: Record<string, any>, ttl?: number): void;
+}
+export declare const searchCache: SearchCache<any>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/lib/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/lib/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,YAAY,CAAA;AAE1D,qBAAa,WAAW,CAAC,CAAC,GAAG,GAAG;IAC9B,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;gBAEpB,OAAO,GAAE,YAAiB;IAKtC;;OAEG;IACH,OAAO,CAAC,WAAW;IAYnB;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAa7B;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;IAiB/E;;OAEG;IACH,QAAQ,IAAI;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAO/D;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO;IAI9E;;OAEG;IACH,GAAG,CACD,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EACP,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,GAAG,CAAC,EAAE,MAAM,GACX,IAAI;CAiBR;AAGD,eAAO,MAAM,WAAW,kBAGtB,CAAA"}