@goatlab/typesense 0.0.2 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -0
- package/package.json +7 -4
package/README.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# @goatlab/typesense
|
|
2
|
+
|
|
3
|
+
A modern, type-safe TypeScript wrapper for the Typesense search engine API. This package provides a comprehensive client with built-in resilience, multi-tenancy support, and a clean, grouped API interface.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @goatlab/typesense
|
|
9
|
+
# or
|
|
10
|
+
pnpm add @goatlab/typesense
|
|
11
|
+
# or
|
|
12
|
+
yarn add @goatlab/typesense
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Basic Usage
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { TypesenseApi } from '@goatlab/typesense'
|
|
19
|
+
|
|
20
|
+
// Initialize the client
|
|
21
|
+
const typesense = new TypesenseApi({
|
|
22
|
+
prefixUrl: 'http://localhost:8108',
|
|
23
|
+
token: 'your-api-key',
|
|
24
|
+
collectionName: 'products' // default collection name
|
|
25
|
+
})
|
|
26
|
+
|
|
27
|
+
// Create a collection
|
|
28
|
+
await typesense.collections.create({
|
|
29
|
+
name: 'products',
|
|
30
|
+
fields: [
|
|
31
|
+
{ name: 'id', type: 'string' },
|
|
32
|
+
{ name: 'title', type: 'string' },
|
|
33
|
+
{ name: 'price', type: 'float' },
|
|
34
|
+
{ name: 'description', type: 'string' }
|
|
35
|
+
]
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
// Insert a document
|
|
39
|
+
await typesense.documents.insert({
|
|
40
|
+
id: '1',
|
|
41
|
+
title: 'iPhone 15',
|
|
42
|
+
price: 999.99,
|
|
43
|
+
description: 'Latest Apple smartphone'
|
|
44
|
+
})
|
|
45
|
+
|
|
46
|
+
// Search documents
|
|
47
|
+
const results = await typesense.search.query({
|
|
48
|
+
q: 'iphone',
|
|
49
|
+
query_by: 'title,description'
|
|
50
|
+
})
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Key Features
|
|
54
|
+
|
|
55
|
+
- **Grouped API Interface**: Organized methods under logical namespaces (collections, documents, search, admin)
|
|
56
|
+
- **Multi-tenancy Support**: Built-in tenant isolation with automatic collection name prefixing
|
|
57
|
+
- **Resilience Features**: Circuit breaker pattern, rate limiting, and automatic retries
|
|
58
|
+
- **Type Safety**: Full TypeScript support with comprehensive type definitions
|
|
59
|
+
- **Schema Management**: Automatic schema caching and version compatibility checks
|
|
60
|
+
- **Stream Support**: Efficient document export with streaming capabilities
|
|
61
|
+
- **Advanced Search**: Support for text search, vector search, and multi-search operations
|
|
62
|
+
|
|
63
|
+
## Available Methods
|
|
64
|
+
|
|
65
|
+
### Collections
|
|
66
|
+
- `collections.create()` - Create a new collection
|
|
67
|
+
- `collections.get()` - Retrieve collection details
|
|
68
|
+
- `collections.update()` - Update collection schema
|
|
69
|
+
- `collections.delete()` - Delete a collection
|
|
70
|
+
- `collections.list()` - List all collections
|
|
71
|
+
- `collections.getOrCreate()` - Get existing or create new collection
|
|
72
|
+
|
|
73
|
+
### Documents
|
|
74
|
+
- `documents.insert()` - Insert a single document
|
|
75
|
+
- `documents.upsert()` - Insert or update a document
|
|
76
|
+
- `documents.update()` - Update an existing document
|
|
77
|
+
- `documents.delete()` - Delete a document by ID
|
|
78
|
+
- `documents.getById()` - Retrieve a document by ID
|
|
79
|
+
- `documents.import()` - Bulk import documents
|
|
80
|
+
- `documents.export()` - Export documents (with optional filtering)
|
|
81
|
+
- `documents.exportStream()` - Export documents as a stream
|
|
82
|
+
- `documents.deleteByFilter()` - Delete documents matching a filter
|
|
83
|
+
- `documents.clear()` - Clear all documents in a collection
|
|
84
|
+
|
|
85
|
+
### Search
|
|
86
|
+
- `search.query()` - Perform a search query
|
|
87
|
+
- `search.text()` - Text-based search
|
|
88
|
+
- `search.vector()` - Vector similarity search
|
|
89
|
+
- `search.multi()` - Execute multiple searches in one request
|
|
90
|
+
|
|
91
|
+
### Admin
|
|
92
|
+
- `admin.health()` - Check server health
|
|
93
|
+
- `admin.waitForHealth()` - Wait for server to be healthy
|
|
94
|
+
- `admin.getMetrics()` - Get server metrics
|
|
95
|
+
- `admin.getStats()` - Get server statistics
|
|
96
|
+
- `admin.getCollectionStats()` - Get collection-specific statistics
|
|
97
|
+
|
|
98
|
+
### Additional Features (v29+)
|
|
99
|
+
- **Aliases**: Create and manage collection aliases
|
|
100
|
+
- **Synonyms**: Define search synonyms
|
|
101
|
+
- **Overrides**: Set up search result overrides
|
|
102
|
+
- **Presets**: Configure search presets
|
|
103
|
+
|
|
104
|
+
## Advanced Configuration
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
const typesense = new TypesenseApi({
|
|
108
|
+
prefixUrl: 'https://typesense.example.com',
|
|
109
|
+
token: 'your-api-key',
|
|
110
|
+
|
|
111
|
+
// Multi-tenancy
|
|
112
|
+
tenantId: 'customer-123',
|
|
113
|
+
|
|
114
|
+
// Timeouts
|
|
115
|
+
searchTimeout: 5000,
|
|
116
|
+
importTimeout: 60000,
|
|
117
|
+
defaultTimeout: 10000,
|
|
118
|
+
|
|
119
|
+
// Resilience settings
|
|
120
|
+
resilience: {
|
|
121
|
+
maxFailures: 5,
|
|
122
|
+
resetTimeout: 60000,
|
|
123
|
+
halfOpenRequests: 3
|
|
124
|
+
},
|
|
125
|
+
|
|
126
|
+
// Other options
|
|
127
|
+
autoCreateCollection: true,
|
|
128
|
+
enableVersionCheck: true,
|
|
129
|
+
suppressLogs: false
|
|
130
|
+
})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Components
|
|
134
|
+
|
|
135
|
+
The package includes several utility components that can be used independently:
|
|
136
|
+
|
|
137
|
+
- `TypesenseHttpClient` - HTTP client with built-in authentication
|
|
138
|
+
- `ResiliencePolicy` - Circuit breaker and rate limiting implementation
|
|
139
|
+
- `CollectionSchemaManager` - Schema caching and management
|
|
140
|
+
- `TypesenseFilterBuilder` - Fluent filter query builder
|
|
141
|
+
- `ExportFormatter` - Document export formatting utilities
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"main": "./dist/index.js",
|
|
4
4
|
"author": "ignacio.cabrera@goatlab.io",
|
|
5
5
|
"name": "@goatlab/typesense",
|
|
6
|
-
"version": "0.0.
|
|
6
|
+
"version": "0.0.3",
|
|
7
7
|
"private": false,
|
|
8
8
|
"publishConfig": {
|
|
9
9
|
"access": "public"
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"@goatlab/js-utils": "0.8.42",
|
|
14
14
|
"@goatlab/tsconfig": "0.0.15"
|
|
15
15
|
},
|
|
16
|
-
"description": "
|
|
16
|
+
"description": "Modern TypeScript wrapper for Typesense search engine API",
|
|
17
17
|
"devDependencies": {
|
|
18
18
|
"@testcontainers/mysql": "^11.0.3",
|
|
19
19
|
"@types/node": "^18.15.9",
|
|
@@ -38,10 +38,13 @@
|
|
|
38
38
|
],
|
|
39
39
|
"homepage": "https://docs.goatlab.io",
|
|
40
40
|
"keywords": [
|
|
41
|
-
"
|
|
41
|
+
"typesense",
|
|
42
|
+
"search",
|
|
42
43
|
"api",
|
|
43
44
|
"wrapper",
|
|
44
|
-
"typescript"
|
|
45
|
+
"typescript",
|
|
46
|
+
"search-engine",
|
|
47
|
+
"full-text-search"
|
|
45
48
|
],
|
|
46
49
|
"scripts": {
|
|
47
50
|
"build": "tsc",
|