@sebspark/opensearch 0.3.3 → 1.0.0

package/README.md

@@ -2,94 +2,141 @@
 
 A wrapper for OpenSearch Client to assist with typed queries, indices etc
 
-## Usage
+## Add
 
 ```zsh
 yarn add @sebspark/opensearch @opensearch-project/opensearch
 ```
 
-**Note:** Data types require a property called `id` of type `string`
+## Usage
+
+Everything starts with an index definition. This must be declared as a const which **satisfies** `OpenSearchIndexMapping`. From this you can then derive your documents and search queries.
+
+```typescript
+import type {
+  IndexDefinition,
+  DocumentFor,
+  SearchRequest,
+} from '@sebspark/opensearch'
+
+export const personIndex = {
+  index: 'person',
+  body: {
+    mappings: {
+      properties: {
+        name: { type: 'keyword' },
+        age: { type: 'integer' },
+      },
+    },
+  },
+} as const satisfies IndexDefinition
+
+export type PersonIndex = typeof personIndex
+export type PersonDocument = DocumentFor<PersonIndex>
+export type PersonSearch = SearchRequest<PersonIndex>
+```
+
+Using the index definition and your types, you can now start interacting with OpenSearch with typeahead:
 
 ```typescript
-import { Client } from '@opensearch-project/opensearch'
-import { helper } from '@sebspark/opensearch'
+import { OpenSearchClient } from '@sebspark/opensearch'
+import {
+  personIndex,
+  type PersonIndex,
+  type PersonDocument,
+  type PersonSearch,
+} from './personIndex'
+
+async function run () {
+  const client = new OpenSearchClient()
 
-const client = new Client({})
-const typedClient = helper(client)
+  // Check if the index exists
+  const { body: exists } = await client.indices.exists<PersonIndex>({ index: 'person' })
 
-type Data = {
-  id: string
-  user: {
-    name: string
-    age: number
+  // If not: create it
+  if (!exists) {
+    await client.indices.create(personIndex)
   }
-  blog: {
-    posts: Array<{
-      title: string
-      text: string
-    }>
+
+  // Create a document
+  const doc: PersonDocument = { // <- This will auto complete on fields and types
+    name: 'John Wick',
+    age: 52,
   }
-}
 
-type UserOnly = Pick<Data, 'id' | 'user'>
+  // Store it
+  await client.index<PersonIndex>({ // <- This will auto complete on index name
+    index: 'person',
+    body: doc,
+  })
 
-// Typed index creation
-async function createIndex() {
-  await helper(client as Client).typedIndexCreate<Data>('data', {
-    mappings: {
-      properties: {
-        user: {
-          age: {
-            type: 'integer'
-          },
-        },
-        isTrue: {
-          type: 'boolean'
+  // Find it
+  const searchQuery: PersonSearch = { // <- This will auto complete on fields and types
+    index: personIndexName,
+    body: {
+      query: {
+        match: {
+          name: 'John Wick'
         }
       }
     }
-  })
+  }
+  const result = await client.search(searchQuery)
+  
+  // result.body.hits.hits <- This has type PersonDocument[]
 }
+```
 
-// Typed insert
-async function indexDocument() {
-  await helper(client as Client).typedIndex<Data>('data', {
-    id: 'foo',
-    isTrue: true,
-    user: {
-      age: 42,
-      name: 'Arthur Dent',
-    }
-  })
-}
+## Helpers
 
-// Typed search
-async function loadData() {
-  // result: Data[]
-  const { result } = await typedClient.typedSearch<Data>({
-    index: 'data',
-    body: {
-      query: {
-        term: {
-          'user.name': {
-            value: 'Arthur Dent',
-          },
-        },
-      },
-    },
-  })
-  return result
-}
-async function loadPartialData() {
-  // result: UserOnly[]
-  const { result } = await typedClient.typedSearch<Data, UserOnly>({
-    index: 'data',
-    body: {
-      query: {
-        fields: ['user.age', 'user.name'],
-      },
-    },
-  })
-  return result
-}
+### Bulk operations
+
+Since bulk operations are a bit tricky to call, this library offers a few utility functions to simplify:
+
+```typescript
+import {
+  bulkIndex,
+  bulkCreate,
+  bulkUpdate,
+  bulkDelete,
+} from '@sebspark/opensearch'
+
+// create a bunch of documents with automatic id:s
+const indexWithAutoId = bulkIndex<PersonIndex>('persons', [
+  { name: 'John Wick', age: 52 },
+  { name: 'Jason Bourne', age: 50 },
+])
+await opensearchClient.bulk(indexWithAutoId)
+
+// Name to lower case without spaces
+const idGen = (doc: PersonDocument) =>
+  doc.name.replace(/\s/g, '').toLowerCase()
+
+// create a bunch of documents with id generator function
+const indexWithIdGen = bulkIndex<PersonIndex>('persons', [
+  { name: 'John Wick', age: 52 },
+  { name: 'Jason Bourne', age: 50 },
+], idGen)
+await opensearchClient.bulk(indexWithIdGen)
+
+// create a bunch of documents and fail if id exists
+const createDocs = bulkCreate<PersonIndex>('persons', [
+  { name: 'John Wick', age: 52 },
+  { name: 'Jason Bourne', age: 50 },
+], idGen)
+await opensearchClient.bulk(createDocs)
+
+// update a bunch of documents
+const updateDocs = bulkUpdate<PersonIndex>('persons', [
+  { doc: { name: 'John Wick', age: 53 } },
+  { doc: { name: 'Jason Bourne', age: 51 } },
+], idGen)
+await opensearchClient.bulk(updateDocs)
+
+// delete a bunch of documents
+const deleteDocs = bulkDelete<PersonIndex>('persons', [
+  'johnwick',
+  'jasonbourne',
+])
+await opensearchClient.bulk(deleteDocs)
 ```