@etohq/utils 2.0.4 → 2.0.5

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.
Files changed (149) hide show
  1. package/dist/bundles.d.ts +1 -0
  2. package/dist/bundles.d.ts.map +1 -1
  3. package/dist/bundles.js +2 -1
  4. package/dist/bundles.js.map +1 -1
  5. package/dist/dal/mikro-orm/mikro-orm-create-connection.d.ts.map +1 -1
  6. package/dist/dal/mikro-orm/mikro-orm-create-connection.js +7 -0
  7. package/dist/dal/mikro-orm/mikro-orm-create-connection.js.map +1 -1
  8. package/dist/dml/errors.d.ts +12 -0
  9. package/dist/dml/errors.d.ts.map +1 -1
  10. package/dist/dml/errors.js +21 -1
  11. package/dist/dml/errors.js.map +1 -1
  12. package/dist/dml/helpers/create-mikro-orm-entity.d.ts.map +1 -1
  13. package/dist/dml/helpers/create-mikro-orm-entity.js +25 -5
  14. package/dist/dml/helpers/create-mikro-orm-entity.js.map +1 -1
  15. package/dist/index.d.ts +2 -0
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +2 -0
  18. package/dist/index.js.map +1 -1
  19. package/dist/migrations/index.d.ts.map +1 -1
  20. package/dist/migrations/index.js +5 -2
  21. package/dist/migrations/index.js.map +1 -1
  22. package/dist/modules-sdk/definition.d.ts +5 -0
  23. package/dist/modules-sdk/definition.d.ts.map +1 -1
  24. package/dist/modules-sdk/definition.js +3 -0
  25. package/dist/modules-sdk/definition.js.map +1 -1
  26. package/dist/schema/base-property.d.ts +25 -0
  27. package/dist/schema/base-property.d.ts.map +1 -0
  28. package/dist/schema/base-property.js +25 -0
  29. package/dist/schema/base-property.js.map +1 -0
  30. package/dist/schema/index.d.ts +2 -0
  31. package/dist/schema/index.d.ts.map +1 -0
  32. package/dist/schema/index.js +18 -0
  33. package/dist/schema/index.js.map +1 -0
  34. package/dist/search/abstract-search-provider.d.ts +345 -0
  35. package/dist/search/abstract-search-provider.d.ts.map +1 -0
  36. package/dist/search/abstract-search-provider.js +345 -0
  37. package/dist/search/abstract-search-provider.js.map +1 -0
  38. package/dist/search/define-search-index.d.ts +12 -0
  39. package/dist/search/define-search-index.d.ts.map +1 -0
  40. package/dist/search/define-search-index.js +47 -0
  41. package/dist/search/define-search-index.js.map +1 -0
  42. package/dist/search/definition-helpers.d.ts +112 -0
  43. package/dist/search/definition-helpers.d.ts.map +1 -0
  44. package/dist/search/definition-helpers.js +196 -0
  45. package/dist/search/definition-helpers.js.map +1 -0
  46. package/dist/search/document-utils.d.ts +29 -0
  47. package/dist/search/document-utils.d.ts.map +1 -0
  48. package/dist/search/document-utils.js +134 -0
  49. package/dist/search/document-utils.js.map +1 -0
  50. package/dist/search/index.d.ts +6 -5
  51. package/dist/search/index.d.ts.map +1 -1
  52. package/dist/search/index.js +6 -5
  53. package/dist/search/index.js.map +1 -1
  54. package/dist/search/model/index-builder.d.ts +61 -0
  55. package/dist/search/model/index-builder.d.ts.map +1 -0
  56. package/dist/search/model/index-builder.js +84 -0
  57. package/dist/search/model/index-builder.js.map +1 -0
  58. package/dist/search/model/index.d.ts +3 -0
  59. package/dist/search/model/index.d.ts.map +1 -0
  60. package/dist/search/model/index.js +9 -0
  61. package/dist/search/model/index.js.map +1 -0
  62. package/dist/search/model/properties/base.d.ts +52 -0
  63. package/dist/search/model/properties/base.d.ts.map +1 -0
  64. package/dist/search/model/properties/base.js +139 -0
  65. package/dist/search/model/properties/base.js.map +1 -0
  66. package/dist/search/model/properties/boolean.d.ts +8 -0
  67. package/dist/search/model/properties/boolean.d.ts.map +1 -0
  68. package/dist/search/model/properties/boolean.js +14 -0
  69. package/dist/search/model/properties/boolean.js.map +1 -0
  70. package/dist/search/model/properties/date.d.ts +8 -0
  71. package/dist/search/model/properties/date.d.ts.map +1 -0
  72. package/dist/search/model/properties/date.js +16 -0
  73. package/dist/search/model/properties/date.js.map +1 -0
  74. package/dist/search/model/properties/float.d.ts +8 -0
  75. package/dist/search/model/properties/float.d.ts.map +1 -0
  76. package/dist/search/model/properties/float.js +14 -0
  77. package/dist/search/model/properties/float.js.map +1 -0
  78. package/dist/search/model/properties/geo.d.ts +11 -0
  79. package/dist/search/model/properties/geo.d.ts.map +1 -0
  80. package/dist/search/model/properties/geo.js +14 -0
  81. package/dist/search/model/properties/geo.js.map +1 -0
  82. package/dist/search/model/properties/index.d.ts +11 -0
  83. package/dist/search/model/properties/index.d.ts.map +1 -0
  84. package/dist/search/model/properties/index.js +27 -0
  85. package/dist/search/model/properties/index.js.map +1 -0
  86. package/dist/search/model/properties/integer.d.ts +8 -0
  87. package/dist/search/model/properties/integer.d.ts.map +1 -0
  88. package/dist/search/model/properties/integer.js +14 -0
  89. package/dist/search/model/properties/integer.js.map +1 -0
  90. package/dist/search/model/properties/keyword.d.ts +8 -0
  91. package/dist/search/model/properties/keyword.d.ts.map +1 -0
  92. package/dist/search/model/properties/keyword.js +14 -0
  93. package/dist/search/model/properties/keyword.js.map +1 -0
  94. package/dist/search/model/properties/object.d.ts +12 -0
  95. package/dist/search/model/properties/object.d.ts.map +1 -0
  96. package/dist/search/model/properties/object.js +38 -0
  97. package/dist/search/model/properties/object.js.map +1 -0
  98. package/dist/search/model/properties/text.d.ts +8 -0
  99. package/dist/search/model/properties/text.d.ts.map +1 -0
  100. package/dist/search/model/properties/text.js +14 -0
  101. package/dist/search/model/properties/text.js.map +1 -0
  102. package/dist/search/model/properties/vector.d.ts +18 -0
  103. package/dist/search/model/properties/vector.d.ts.map +1 -0
  104. package/dist/search/model/properties/vector.js +51 -0
  105. package/dist/search/model/properties/vector.js.map +1 -0
  106. package/dist/search/model/search-fields-schema.d.ts +22 -0
  107. package/dist/search/model/search-fields-schema.d.ts.map +1 -0
  108. package/dist/search/model/search-fields-schema.js +70 -0
  109. package/dist/search/model/search-fields-schema.js.map +1 -0
  110. package/dist/search/search-scope.d.ts +44 -0
  111. package/dist/search/search-scope.d.ts.map +1 -0
  112. package/dist/search/search-scope.js +111 -0
  113. package/dist/search/search-scope.js.map +1 -0
  114. package/dist/{search → search-legacy}/abstract-service.d.ts +19 -19
  115. package/dist/search-legacy/abstract-service.d.ts.map +1 -0
  116. package/dist/{search → search-legacy}/abstract-service.js +8 -8
  117. package/dist/search-legacy/abstract-service.js.map +1 -0
  118. package/dist/search-legacy/index-types.d.ts.map +1 -0
  119. package/dist/search-legacy/index-types.js.map +1 -0
  120. package/dist/search-legacy/index.d.ts +6 -0
  121. package/dist/search-legacy/index.d.ts.map +1 -0
  122. package/dist/search-legacy/index.js +22 -0
  123. package/dist/search-legacy/index.js.map +1 -0
  124. package/dist/search-legacy/search-relations.d.ts.map +1 -0
  125. package/dist/search-legacy/search-relations.js.map +1 -0
  126. package/dist/{search → search-legacy}/types.d.ts +29 -29
  127. package/dist/search-legacy/types.d.ts.map +1 -0
  128. package/dist/{search → search-legacy}/types.js +1 -1
  129. package/dist/search-legacy/types.js.map +1 -0
  130. package/dist/search-legacy/variant-keys.d.ts.map +1 -0
  131. package/dist/search-legacy/variant-keys.js.map +1 -0
  132. package/dist/tsconfig.tsbuildinfo +1 -1
  133. package/package.json +2 -2
  134. package/dist/search/abstract-service.d.ts.map +0 -1
  135. package/dist/search/abstract-service.js.map +0 -1
  136. package/dist/search/index-types.d.ts.map +0 -1
  137. package/dist/search/index-types.js.map +0 -1
  138. package/dist/search/search-relations.d.ts.map +0 -1
  139. package/dist/search/search-relations.js.map +0 -1
  140. package/dist/search/types.d.ts.map +0 -1
  141. package/dist/search/types.js.map +0 -1
  142. package/dist/search/variant-keys.d.ts.map +0 -1
  143. package/dist/search/variant-keys.js.map +0 -1
  144. /package/dist/{search → search-legacy}/index-types.d.ts +0 -0
  145. /package/dist/{search → search-legacy}/index-types.js +0 -0
  146. /package/dist/{search → search-legacy}/search-relations.d.ts +0 -0
  147. /package/dist/{search → search-legacy}/search-relations.js +0 -0
  148. /package/dist/{search → search-legacy}/variant-keys.d.ts +0 -0
  149. /package/dist/{search → search-legacy}/variant-keys.js +0 -0
@@ -0,0 +1,345 @@
1
+ import { SearchTypes } from "@etohq/types";
2
+ /**
3
+ * An abstract class for search providers. Extend this class to create a search
4
+ * provider.
5
+ *
6
+ * A search provider translates the Search Module's provider-agnostic input into
7
+ * the calls of a search engine, such as Meilisearch or Typesense: it creates and
8
+ * migrates the physical indexes, writes and deletes documents, and runs queries.
9
+ * The Search Module owns everything around it, including index definitions,
10
+ * batching, task tracking, and reindexing.
11
+ *
12
+ * ### constructor
13
+ *
14
+ * The constructor allows you to access resources from the module's container using the first parameter,
15
+ * and the provider's options using the second parameter.
16
+ *
17
+ * If you're creating a client with a search engine, do it in the constructor.
18
+ * Establishing a connection with the search engine should happen in `onApplicationStart`.
19
+ *
20
+ * #### Example
21
+ *
22
+ * ```ts
23
+ * import { Logger } from "@etohq/framework/types"
24
+ * import { AbstractSearchProviderService } from "@etohq/framework/utils"
25
+ *
26
+ * type InjectedDependencies = {
27
+ * logger: Logger
28
+ * }
29
+ *
30
+ * type Options = {
31
+ * host: string
32
+ * apiKey: string
33
+ * }
34
+ *
35
+ * class MySearchProviderService extends AbstractSearchProviderService {
36
+ * static identifier = "my-search"
37
+ *
38
+ * protected logger_: Logger
39
+ * protected options_: Options
40
+ * // assuming you're initializing a client
41
+ * protected client
42
+ *
43
+ * constructor (
44
+ * { logger }: InjectedDependencies,
45
+ * options: Options
46
+ * ) {
47
+ * super()
48
+ *
49
+ * this.logger_ = logger
50
+ * this.options_ = options
51
+ *
52
+ * // assuming you're initializing a client
53
+ * this.client = new Client(options)
54
+ * }
55
+ * }
56
+ *
57
+ * export default MySearchProviderService
58
+ * ```
59
+ *
60
+ * ### Handling unsupported features
61
+ *
62
+ * There's no list of features to declare. If a query asks for something your engine can't
63
+ * express, throw; if an index definition asks for something it can't hold, throw from
64
+ * `upsertIndex` so the error surfaces at startup. Returning a slightly different result is
65
+ * the one outcome to avoid, since callers can't tell it apart from a correct one.
66
+ *
67
+ * @privateRemarks
68
+ *
69
+ * `waitForTask` is optional and left out of this class on purpose: the Search
70
+ * Module treats its presence as support, so only define it if your engine
71
+ * applies writes asynchronously. `searchMany` has a default that runs `search`
72
+ * concurrently; override it to pack the queries into one engine round-trip.
73
+ * Refer to the `ISearchProvider` interface for their expected parameters and
74
+ * return values.
75
+ */
76
+ export declare class AbstractSearchProviderService implements SearchTypes.ISearchProvider {
77
+ /**
78
+ * Each search provider has a unique identifier used to register it and to bind
79
+ * an index definition to it. An index definition selects a provider by setting
80
+ * its `provider` property to this identifier. You can also use this identifier
81
+ * in `medusa-config.ts` to configure the default provider for the Search Module.
82
+ *
83
+ * @example
84
+ * class MySearchProviderService extends AbstractSearchProviderService {
85
+ * static identifier = "my-search"
86
+ * // ...
87
+ * }
88
+ */
89
+ static identifier: string;
90
+ /**
91
+ * @ignore
92
+ */
93
+ get identifier(): string;
94
+ /**
95
+ * @ignore
96
+ */
97
+ getIdentifier(): string;
98
+ /**
99
+ * This method runs a search against an index. The Search Module will use this method in
100
+ * its `search` and `searchMany` methods.
101
+ *
102
+ * The free-text query arrives as `q`, already lifted out of `filters`, and
103
+ * `attributes_to_retrieve` is already narrowed to the fields the index can return.
104
+ *
105
+ * Compile `input.filters` to your engine's filter syntax, and reject the
106
+ * operators it can't express rather than approximating them. Also, use
107
+ * `input.index.physical_name` as the index to query, not `input.index.name`,
108
+ * since the two differ under an index prefix or between versions.
109
+ *
110
+ * @param {SearchTypes.ProviderSearchQuery} _input - The query, the resolved index
111
+ * definition, and the attributes to return.
112
+ * @returns {Promise<SearchTypes.SearchResult>} The hits, any facets, and the metadata.
113
+ *
114
+ * @example
115
+ * class MySearchProviderService extends AbstractSearchProviderService {
116
+ * // ...
117
+ * async search(
118
+ * input: SearchTypes.ProviderSearchQuery
119
+ * ): Promise<SearchTypes.SearchResult> {
120
+ * const response = await this.client.search(input.index.physical_name, {
121
+ * query: input.q,
122
+ * limit: input.pagination?.take,
123
+ * })
124
+ *
125
+ * return {
126
+ * hits: response.hits.map((hit) => ({ id: hit.id, document: hit })),
127
+ * metadata: {
128
+ * skip: input.pagination?.skip ?? 0,
129
+ * take: input.pagination?.take ?? 20,
130
+ * count: response.total,
131
+ * },
132
+ * }
133
+ * }
134
+ * }
135
+ */
136
+ search(_input: SearchTypes.ProviderSearchQuery): Promise<SearchTypes.SearchResult>;
137
+ /**
138
+ * This method runs multiple queries in a single request to the search engine.
139
+ * The Search Module uses it for its `searchMany` method, including the extra
140
+ * queries produced by disjunctive faceting.
141
+ *
142
+ * The default runs `search` concurrently. Override it to pack the queries into
143
+ * one engine round-trip.
144
+ *
145
+ * @param {SearchTypes.ProviderSearchQuery[]} inputs - The queries to run.
146
+ * @returns {Promise<SearchTypes.SearchResult[]>} A result for each query, in
147
+ * the same order as the queries.
148
+ *
149
+ * @example
150
+ * class MySearchProviderService extends AbstractSearchProviderService {
151
+ * // ...
152
+ * async searchMany(
153
+ * inputs: SearchTypes.ProviderSearchQuery[]
154
+ * ): Promise<SearchTypes.SearchResult[]> {
155
+ * const { results } = await this.client.multiSearch(
156
+ * inputs.map((input) => ({
157
+ * indexUid: input.index.physical_name,
158
+ * query: input.q,
159
+ * }))
160
+ * )
161
+ *
162
+ * return results.map((result, i) => this.buildResult(result, inputs[i]))
163
+ * }
164
+ * }
165
+ */
166
+ searchMany(inputs: SearchTypes.ProviderSearchQuery[]): Promise<SearchTypes.SearchResult[]>;
167
+ /**
168
+ * This method brings an index in line with its definition, creating it if it doesn't
169
+ * exist. The Search Module calls it for every definition when migrations run.
170
+ *
171
+ * You may recreate the index if your engine can't alter a schema in place. That's safe:
172
+ * the module only points this at an index it's about to seed, never at one that has to
173
+ * keep serving reads, and never during a partial rebuild.
174
+ *
175
+ * Throw if the definition asks for something your engine can't hold, such as a
176
+ * facet type it doesn't support. Since migrations run before the application
177
+ * serves requests, the error surfaces at startup rather than as wrong results
178
+ * later.
179
+ *
180
+ * @param {object} _input - The index to create or update.
181
+ * @param {SearchTypes.ResolvedSearchIndexDefinition} _input.index - The definition,
182
+ * including the `physical_name` to create it under, the `primary_key` its
183
+ * documents are keyed by, the `fields` it holds, and its `settings`.
184
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
185
+ *
186
+ * @example
187
+ * class MySearchProviderService extends AbstractSearchProviderService {
188
+ * // ...
189
+ * async upsertIndex({
190
+ * index,
191
+ * }: {
192
+ * index: SearchTypes.ResolvedSearchIndexDefinition
193
+ * }): Promise<SearchTypes.SearchTask> {
194
+ * await this.client.createIndex(index.physical_name, {
195
+ * primaryKey: index.primary_key,
196
+ * })
197
+ *
198
+ * return { index: index.physical_name, status: "succeeded" }
199
+ * }
200
+ * }
201
+ */
202
+ upsertIndex(_input: {
203
+ index: SearchTypes.ResolvedSearchIndexDefinition;
204
+ }): Promise<SearchTypes.SearchTask>;
205
+ /**
206
+ * This method deletes an index and everything in it. The Search Module calls it
207
+ * to clean up an old version of an index once a newer one has taken over.
208
+ *
209
+ * @param {object} _input - The index to delete.
210
+ * @param {string} _input.index - The index's physical name.
211
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
212
+ *
213
+ * @example
214
+ * class MySearchProviderService extends AbstractSearchProviderService {
215
+ * // ...
216
+ * async deleteIndex({
217
+ * index,
218
+ * }: {
219
+ * index: string
220
+ * }): Promise<SearchTypes.SearchTask> {
221
+ * await this.client.deleteIndex(index)
222
+ * return { index, status: "succeeded" }
223
+ * }
224
+ * }
225
+ */
226
+ deleteIndex(_input: {
227
+ index: string;
228
+ }): Promise<SearchTypes.SearchTask>;
229
+ /**
230
+ * This method lists the indexes you hold. The Search Module reads the document counts to
231
+ * spot an index that lost its data and needs reseeding.
232
+ *
233
+ * @returns {Promise<SearchTypes.SearchIndexInfo[]>} The indexes and their document counts.
234
+ *
235
+ * @example
236
+ * class MySearchProviderService extends AbstractSearchProviderService {
237
+ * // ...
238
+ * async listIndexes(): Promise<SearchTypes.SearchIndexInfo[]> {
239
+ * const indexes = await this.client.listIndexes()
240
+ *
241
+ * return indexes.map((index) => ({
242
+ * name: index.uid,
243
+ * provider: MySearchProviderService.identifier,
244
+ * document_count: index.numberOfDocuments,
245
+ * }))
246
+ * }
247
+ * }
248
+ */
249
+ listIndexes(): Promise<SearchTypes.SearchIndexInfo[]>;
250
+ /**
251
+ * This method adds documents to an index, replacing any that already exist under the same
252
+ * ID. The Search Module uses it both for direct writes and for seeding, where it's called
253
+ * once per batch.
254
+ *
255
+ * If your engine applies writes later rather than inline, return a task with an `id` and
256
+ * implement `waitForTask`, so the module can wait before making a new version active.
257
+ *
258
+ * Write to `input.index` but read schema information from `input.definition`:
259
+ * while a new version is being seeded, `input.index` is that version's
260
+ * physical index, whereas the definition is that of the logical index.
261
+ *
262
+ * @param {object} _input - The documents to write.
263
+ * @param {string} _input.index - The index's physical name. This is the index to
264
+ * write to.
265
+ * @param {SearchTypes.ResolvedSearchIndexDefinition} _input.definition - The
266
+ * definition of the logical index the documents belong to. Use it for schema
267
+ * information, such as the index's `fields` or `primary_key`.
268
+ * @param {SearchTypes.SearchDocument[]} _input.documents - The documents, each with an `id`.
269
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
270
+ *
271
+ * @example
272
+ * class MySearchProviderService extends AbstractSearchProviderService {
273
+ * // ...
274
+ * async upsertDocuments({
275
+ * index,
276
+ * definition,
277
+ * documents,
278
+ * }: {
279
+ * index: string
280
+ * definition: SearchTypes.ResolvedSearchIndexDefinition
281
+ * documents: SearchTypes.SearchDocument[]
282
+ * }): Promise<SearchTypes.SearchTask> {
283
+ * const task = await this.client.addDocuments(index, documents, {
284
+ * schema: definition.fields,
285
+ * })
286
+ * return { id: `${task.uid}`, index, status: "enqueued" }
287
+ * }
288
+ * }
289
+ */
290
+ upsertDocuments(_input: {
291
+ index: string;
292
+ definition: SearchTypes.ResolvedSearchIndexDefinition;
293
+ documents: SearchTypes.SearchDocument[];
294
+ }): Promise<SearchTypes.SearchTask>;
295
+ /**
296
+ * This method removes every document matching the given filters.
297
+ *
298
+ * Deleting by ID isn't a special case — it arrives as a filter on the primary key, such
299
+ * as `{ id: ["prod_1", "prod_2"] }`. Recognize that shape and use your engine's
300
+ * delete-by-ID path, which is usually much faster. If your engine can't delete by
301
+ * arbitrary filters, either search first and delete the matching IDs, or throw.
302
+ *
303
+ * @param {SearchTypes.SearchDeleteDocumentsInput} _input - The index and the filters
304
+ * selecting the documents to remove.
305
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
306
+ *
307
+ * @example
308
+ * class MySearchProviderService extends AbstractSearchProviderService {
309
+ * // ...
310
+ * async deleteDocuments({
311
+ * index,
312
+ * filters,
313
+ * }: SearchTypes.SearchDeleteDocumentsInput): Promise<SearchTypes.SearchTask> {
314
+ * await this.client.deleteDocumentsByFilter(index, filters)
315
+ * return { index, status: "succeeded" }
316
+ * }
317
+ * }
318
+ */
319
+ deleteDocuments(_input: SearchTypes.SearchDeleteDocumentsInput): Promise<SearchTypes.SearchTask>;
320
+ /**
321
+ * This method removes every document from an index without deleting the index itself.
322
+ * The Search Module uses it to empty an index before reseeding it in place.
323
+ *
324
+ * @param {object} _input - The index to empty.
325
+ * @param {string} _input.index - The index's physical name.
326
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
327
+ *
328
+ * @example
329
+ * class MySearchProviderService extends AbstractSearchProviderService {
330
+ * // ...
331
+ * async clearIndex({
332
+ * index,
333
+ * }: {
334
+ * index: string
335
+ * }): Promise<SearchTypes.SearchTask> {
336
+ * await this.client.deleteAllDocuments(index)
337
+ * return { index, status: "succeeded" }
338
+ * }
339
+ * }
340
+ */
341
+ clearIndex(_input: {
342
+ index: string;
343
+ }): Promise<SearchTypes.SearchTask>;
344
+ }
345
+ //# sourceMappingURL=abstract-search-provider.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"abstract-search-provider.d.ts","sourceRoot":"","sources":["../../src/search/abstract-search-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,qBAAa,6BACX,YAAW,WAAW,CAAC,eAAe;IAEtC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAA;IAEzB;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,MAAM,CACV,MAAM,EAAE,WAAW,CAAC,mBAAmB,GACtC,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC;IAIpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,UAAU,CACd,MAAM,EAAE,WAAW,CAAC,mBAAmB,EAAE,GACxC,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC;IAItC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,WAAW,CAAC,MAAM,EAAE;QACxB,KAAK,EAAE,WAAW,CAAC,6BAA6B,CAAA;KACjD,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;IAInC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,WAAW,CAAC,MAAM,EAAE;QACxB,KAAK,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;IAInC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC;IAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,WAAW,CAAC,6BAA6B,CAAA;QACrD,SAAS,EAAE,WAAW,CAAC,cAAc,EAAE,CAAA;KACxC,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;IAInC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CACnB,MAAM,EAAE,WAAW,CAAC,0BAA0B,GAC7C,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;IAIlC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;CAG7E"}
@@ -0,0 +1,345 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AbstractSearchProviderService = void 0;
4
+ /**
5
+ * An abstract class for search providers. Extend this class to create a search
6
+ * provider.
7
+ *
8
+ * A search provider translates the Search Module's provider-agnostic input into
9
+ * the calls of a search engine, such as Meilisearch or Typesense: it creates and
10
+ * migrates the physical indexes, writes and deletes documents, and runs queries.
11
+ * The Search Module owns everything around it, including index definitions,
12
+ * batching, task tracking, and reindexing.
13
+ *
14
+ * ### constructor
15
+ *
16
+ * The constructor allows you to access resources from the module's container using the first parameter,
17
+ * and the provider's options using the second parameter.
18
+ *
19
+ * If you're creating a client with a search engine, do it in the constructor.
20
+ * Establishing a connection with the search engine should happen in `onApplicationStart`.
21
+ *
22
+ * #### Example
23
+ *
24
+ * ```ts
25
+ * import { Logger } from "@etohq/framework/types"
26
+ * import { AbstractSearchProviderService } from "@etohq/framework/utils"
27
+ *
28
+ * type InjectedDependencies = {
29
+ * logger: Logger
30
+ * }
31
+ *
32
+ * type Options = {
33
+ * host: string
34
+ * apiKey: string
35
+ * }
36
+ *
37
+ * class MySearchProviderService extends AbstractSearchProviderService {
38
+ * static identifier = "my-search"
39
+ *
40
+ * protected logger_: Logger
41
+ * protected options_: Options
42
+ * // assuming you're initializing a client
43
+ * protected client
44
+ *
45
+ * constructor (
46
+ * { logger }: InjectedDependencies,
47
+ * options: Options
48
+ * ) {
49
+ * super()
50
+ *
51
+ * this.logger_ = logger
52
+ * this.options_ = options
53
+ *
54
+ * // assuming you're initializing a client
55
+ * this.client = new Client(options)
56
+ * }
57
+ * }
58
+ *
59
+ * export default MySearchProviderService
60
+ * ```
61
+ *
62
+ * ### Handling unsupported features
63
+ *
64
+ * There's no list of features to declare. If a query asks for something your engine can't
65
+ * express, throw; if an index definition asks for something it can't hold, throw from
66
+ * `upsertIndex` so the error surfaces at startup. Returning a slightly different result is
67
+ * the one outcome to avoid, since callers can't tell it apart from a correct one.
68
+ *
69
+ * @privateRemarks
70
+ *
71
+ * `waitForTask` is optional and left out of this class on purpose: the Search
72
+ * Module treats its presence as support, so only define it if your engine
73
+ * applies writes asynchronously. `searchMany` has a default that runs `search`
74
+ * concurrently; override it to pack the queries into one engine round-trip.
75
+ * Refer to the `ISearchProvider` interface for their expected parameters and
76
+ * return values.
77
+ */
78
+ class AbstractSearchProviderService {
79
+ /**
80
+ * @ignore
81
+ */
82
+ get identifier() {
83
+ return this.constructor.identifier;
84
+ }
85
+ /**
86
+ * @ignore
87
+ */
88
+ getIdentifier() {
89
+ return this.constructor.identifier;
90
+ }
91
+ /**
92
+ * This method runs a search against an index. The Search Module will use this method in
93
+ * its `search` and `searchMany` methods.
94
+ *
95
+ * The free-text query arrives as `q`, already lifted out of `filters`, and
96
+ * `attributes_to_retrieve` is already narrowed to the fields the index can return.
97
+ *
98
+ * Compile `input.filters` to your engine's filter syntax, and reject the
99
+ * operators it can't express rather than approximating them. Also, use
100
+ * `input.index.physical_name` as the index to query, not `input.index.name`,
101
+ * since the two differ under an index prefix or between versions.
102
+ *
103
+ * @param {SearchTypes.ProviderSearchQuery} _input - The query, the resolved index
104
+ * definition, and the attributes to return.
105
+ * @returns {Promise<SearchTypes.SearchResult>} The hits, any facets, and the metadata.
106
+ *
107
+ * @example
108
+ * class MySearchProviderService extends AbstractSearchProviderService {
109
+ * // ...
110
+ * async search(
111
+ * input: SearchTypes.ProviderSearchQuery
112
+ * ): Promise<SearchTypes.SearchResult> {
113
+ * const response = await this.client.search(input.index.physical_name, {
114
+ * query: input.q,
115
+ * limit: input.pagination?.take,
116
+ * })
117
+ *
118
+ * return {
119
+ * hits: response.hits.map((hit) => ({ id: hit.id, document: hit })),
120
+ * metadata: {
121
+ * skip: input.pagination?.skip ?? 0,
122
+ * take: input.pagination?.take ?? 20,
123
+ * count: response.total,
124
+ * },
125
+ * }
126
+ * }
127
+ * }
128
+ */
129
+ async search(_input) {
130
+ throw Error("search must be overridden by the child class");
131
+ }
132
+ /**
133
+ * This method runs multiple queries in a single request to the search engine.
134
+ * The Search Module uses it for its `searchMany` method, including the extra
135
+ * queries produced by disjunctive faceting.
136
+ *
137
+ * The default runs `search` concurrently. Override it to pack the queries into
138
+ * one engine round-trip.
139
+ *
140
+ * @param {SearchTypes.ProviderSearchQuery[]} inputs - The queries to run.
141
+ * @returns {Promise<SearchTypes.SearchResult[]>} A result for each query, in
142
+ * the same order as the queries.
143
+ *
144
+ * @example
145
+ * class MySearchProviderService extends AbstractSearchProviderService {
146
+ * // ...
147
+ * async searchMany(
148
+ * inputs: SearchTypes.ProviderSearchQuery[]
149
+ * ): Promise<SearchTypes.SearchResult[]> {
150
+ * const { results } = await this.client.multiSearch(
151
+ * inputs.map((input) => ({
152
+ * indexUid: input.index.physical_name,
153
+ * query: input.q,
154
+ * }))
155
+ * )
156
+ *
157
+ * return results.map((result, i) => this.buildResult(result, inputs[i]))
158
+ * }
159
+ * }
160
+ */
161
+ async searchMany(inputs) {
162
+ return await Promise.all(inputs.map((input) => this.search(input)));
163
+ }
164
+ /**
165
+ * This method brings an index in line with its definition, creating it if it doesn't
166
+ * exist. The Search Module calls it for every definition when migrations run.
167
+ *
168
+ * You may recreate the index if your engine can't alter a schema in place. That's safe:
169
+ * the module only points this at an index it's about to seed, never at one that has to
170
+ * keep serving reads, and never during a partial rebuild.
171
+ *
172
+ * Throw if the definition asks for something your engine can't hold, such as a
173
+ * facet type it doesn't support. Since migrations run before the application
174
+ * serves requests, the error surfaces at startup rather than as wrong results
175
+ * later.
176
+ *
177
+ * @param {object} _input - The index to create or update.
178
+ * @param {SearchTypes.ResolvedSearchIndexDefinition} _input.index - The definition,
179
+ * including the `physical_name` to create it under, the `primary_key` its
180
+ * documents are keyed by, the `fields` it holds, and its `settings`.
181
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
182
+ *
183
+ * @example
184
+ * class MySearchProviderService extends AbstractSearchProviderService {
185
+ * // ...
186
+ * async upsertIndex({
187
+ * index,
188
+ * }: {
189
+ * index: SearchTypes.ResolvedSearchIndexDefinition
190
+ * }): Promise<SearchTypes.SearchTask> {
191
+ * await this.client.createIndex(index.physical_name, {
192
+ * primaryKey: index.primary_key,
193
+ * })
194
+ *
195
+ * return { index: index.physical_name, status: "succeeded" }
196
+ * }
197
+ * }
198
+ */
199
+ async upsertIndex(_input) {
200
+ throw Error("upsertIndex must be overridden by the child class");
201
+ }
202
+ /**
203
+ * This method deletes an index and everything in it. The Search Module calls it
204
+ * to clean up an old version of an index once a newer one has taken over.
205
+ *
206
+ * @param {object} _input - The index to delete.
207
+ * @param {string} _input.index - The index's physical name.
208
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
209
+ *
210
+ * @example
211
+ * class MySearchProviderService extends AbstractSearchProviderService {
212
+ * // ...
213
+ * async deleteIndex({
214
+ * index,
215
+ * }: {
216
+ * index: string
217
+ * }): Promise<SearchTypes.SearchTask> {
218
+ * await this.client.deleteIndex(index)
219
+ * return { index, status: "succeeded" }
220
+ * }
221
+ * }
222
+ */
223
+ async deleteIndex(_input) {
224
+ throw Error("deleteIndex must be overridden by the child class");
225
+ }
226
+ /**
227
+ * This method lists the indexes you hold. The Search Module reads the document counts to
228
+ * spot an index that lost its data and needs reseeding.
229
+ *
230
+ * @returns {Promise<SearchTypes.SearchIndexInfo[]>} The indexes and their document counts.
231
+ *
232
+ * @example
233
+ * class MySearchProviderService extends AbstractSearchProviderService {
234
+ * // ...
235
+ * async listIndexes(): Promise<SearchTypes.SearchIndexInfo[]> {
236
+ * const indexes = await this.client.listIndexes()
237
+ *
238
+ * return indexes.map((index) => ({
239
+ * name: index.uid,
240
+ * provider: MySearchProviderService.identifier,
241
+ * document_count: index.numberOfDocuments,
242
+ * }))
243
+ * }
244
+ * }
245
+ */
246
+ async listIndexes() {
247
+ throw Error("listIndexes must be overridden by the child class");
248
+ }
249
+ /**
250
+ * This method adds documents to an index, replacing any that already exist under the same
251
+ * ID. The Search Module uses it both for direct writes and for seeding, where it's called
252
+ * once per batch.
253
+ *
254
+ * If your engine applies writes later rather than inline, return a task with an `id` and
255
+ * implement `waitForTask`, so the module can wait before making a new version active.
256
+ *
257
+ * Write to `input.index` but read schema information from `input.definition`:
258
+ * while a new version is being seeded, `input.index` is that version's
259
+ * physical index, whereas the definition is that of the logical index.
260
+ *
261
+ * @param {object} _input - The documents to write.
262
+ * @param {string} _input.index - The index's physical name. This is the index to
263
+ * write to.
264
+ * @param {SearchTypes.ResolvedSearchIndexDefinition} _input.definition - The
265
+ * definition of the logical index the documents belong to. Use it for schema
266
+ * information, such as the index's `fields` or `primary_key`.
267
+ * @param {SearchTypes.SearchDocument[]} _input.documents - The documents, each with an `id`.
268
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
269
+ *
270
+ * @example
271
+ * class MySearchProviderService extends AbstractSearchProviderService {
272
+ * // ...
273
+ * async upsertDocuments({
274
+ * index,
275
+ * definition,
276
+ * documents,
277
+ * }: {
278
+ * index: string
279
+ * definition: SearchTypes.ResolvedSearchIndexDefinition
280
+ * documents: SearchTypes.SearchDocument[]
281
+ * }): Promise<SearchTypes.SearchTask> {
282
+ * const task = await this.client.addDocuments(index, documents, {
283
+ * schema: definition.fields,
284
+ * })
285
+ * return { id: `${task.uid}`, index, status: "enqueued" }
286
+ * }
287
+ * }
288
+ */
289
+ async upsertDocuments(_input) {
290
+ throw Error("upsertDocuments must be overridden by the child class");
291
+ }
292
+ /**
293
+ * This method removes every document matching the given filters.
294
+ *
295
+ * Deleting by ID isn't a special case — it arrives as a filter on the primary key, such
296
+ * as `{ id: ["prod_1", "prod_2"] }`. Recognize that shape and use your engine's
297
+ * delete-by-ID path, which is usually much faster. If your engine can't delete by
298
+ * arbitrary filters, either search first and delete the matching IDs, or throw.
299
+ *
300
+ * @param {SearchTypes.SearchDeleteDocumentsInput} _input - The index and the filters
301
+ * selecting the documents to remove.
302
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
303
+ *
304
+ * @example
305
+ * class MySearchProviderService extends AbstractSearchProviderService {
306
+ * // ...
307
+ * async deleteDocuments({
308
+ * index,
309
+ * filters,
310
+ * }: SearchTypes.SearchDeleteDocumentsInput): Promise<SearchTypes.SearchTask> {
311
+ * await this.client.deleteDocumentsByFilter(index, filters)
312
+ * return { index, status: "succeeded" }
313
+ * }
314
+ * }
315
+ */
316
+ async deleteDocuments(_input) {
317
+ throw Error("deleteDocuments must be overridden by the child class");
318
+ }
319
+ /**
320
+ * This method removes every document from an index without deleting the index itself.
321
+ * The Search Module uses it to empty an index before reseeding it in place.
322
+ *
323
+ * @param {object} _input - The index to empty.
324
+ * @param {string} _input.index - The index's physical name.
325
+ * @returns {Promise<SearchTypes.SearchTask>} The write's task.
326
+ *
327
+ * @example
328
+ * class MySearchProviderService extends AbstractSearchProviderService {
329
+ * // ...
330
+ * async clearIndex({
331
+ * index,
332
+ * }: {
333
+ * index: string
334
+ * }): Promise<SearchTypes.SearchTask> {
335
+ * await this.client.deleteAllDocuments(index)
336
+ * return { index, status: "succeeded" }
337
+ * }
338
+ * }
339
+ */
340
+ async clearIndex(_input) {
341
+ throw Error("clearIndex must be overridden by the child class");
342
+ }
343
+ }
344
+ exports.AbstractSearchProviderService = AbstractSearchProviderService;
345
+ //# sourceMappingURL=abstract-search-provider.js.map