From 5f392b25f5d07022c1a5da8ab3ec9c7da22a6019 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Tue, 18 Nov 2025 19:18:34 +0200
Subject: [PATCH 1/2] fix(document): don't accept write actions  on dedicated
 functions

- don't let users define actions on create, update and upsert
---
 src/Typesense/Documents.ts | 11 +++++++----
 src/Typesense/Types.ts     | 15 ++++++++++++---
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/src/Typesense/Documents.ts b/src/Typesense/Documents.ts
index 77ed9c57..df705cbd 100644
--- a/src/Typesense/Documents.ts
+++ b/src/Typesense/Documents.ts
@@ -214,12 +214,15 @@ export default class Documents<T extends DocumentSchema = object>
     super(collectionName, apiCall, configuration);
   }
 
-  async create(document: T, options: DocumentWriteParameters = {}): Promise<T> {
+  async create(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action"> = {},
+  ): Promise<T> {
     if (!document) throw new Error("No document provided");
     return this.apiCall.post<T>(this.endpointPath(), document, options);
   }
 
-  async upsert(document: T, options: DocumentWriteParameters = {}): Promise<T> {
+  async upsert(document: T, options: Omit<DocumentWriteParameters, "action"> = {}): Promise<T> {
     if (!document) throw new Error("No document provided");
     return this.apiCall.post<T>(
       this.endpointPath(),
@@ -232,10 +235,10 @@ export default class Documents<T extends DocumentSchema = object>
     document: T,
     options: UpdateByFilterParameters,
   ): Promise<UpdateByFilterResponse>;
-  async update(document: T, options: DocumentWriteParameters): Promise<T>;
+  async update(document: T, options: Omit<DocumentWriteParameters, "action">): Promise<T>;
   async update(
     document: T,
-    options: DocumentWriteParameters | UpdateByFilterParameters = {},
+    options: Omit<DocumentWriteParameters, "action"> | UpdateByFilterParameters = {},
   ): Promise<UpdateByFilterResponse | T> {
     if (!document) throw new Error("No document provided");
 
diff --git a/src/Typesense/Types.ts b/src/Typesense/Types.ts
index 5270c1f9..366e832c 100644
--- a/src/Typesense/Types.ts
+++ b/src/Typesense/Types.ts
@@ -202,9 +202,18 @@ export interface SearchableDocuments<
 }
 
 export interface WriteableDocuments<T> {
-  create(document: T, options: DocumentWriteParameters): Promise<T>;
-  upsert(document: T, options: DocumentWriteParameters): Promise<T>;
-  update(document: T, options: DocumentWriteParameters): Promise<T>;
+  create(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action">,
+  ): Promise<T>;
+  upsert(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action">,
+  ): Promise<T>;
+  update(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action">,
+  ): Promise<T>;
   delete(query: DeleteQuery): Promise<DeleteResponse>;
   import(
     documents: T[] | string,

From 76f3ce685d1796ffa11d70b61e9b4ed91cde35d1 Mon Sep 17 00:00:00 2001
From: Fanis Tharropoulos <ftharropoulos@gmail.com>
Date: Tue, 18 Nov 2025 19:18:51 +0200
Subject: [PATCH 2/2] feat(documents): add dedicated `emplace` function

---
 src/Typesense/Documents.ts | 29 +++++++++++++++++++++++++++++
 src/Typesense/Types.ts     |  4 ++++
 2 files changed, 33 insertions(+)

diff --git a/src/Typesense/Documents.ts b/src/Typesense/Documents.ts
index df705cbd..683ddb37 100644
--- a/src/Typesense/Documents.ts
+++ b/src/Typesense/Documents.ts
@@ -257,6 +257,35 @@ export default class Documents<T extends DocumentSchema = object>
     }
   }
 
+  async emplace(
+    document: T,
+    options: UpdateByFilterParameters,
+  ): Promise<UpdateByFilterResponse>;
+  async emplace(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action">,
+  ): Promise<T>;
+  async emplace(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action"> | UpdateByFilterParameters = {},
+  ): Promise<UpdateByFilterResponse | T> {
+    if (!document) throw new Error("No document provided");
+
+    if (options["filter_by"] != null) {
+      return this.apiCall.patch<T>(
+        this.endpointPath(),
+        document,
+        Object.assign({}, options),
+      );
+    } else {
+      return this.apiCall.post<T>(
+        this.endpointPath(),
+        document,
+        Object.assign({}, options, { action: "emplace" }),
+      );
+    }
+  }
+
   async delete(
     query: DeleteQuery = {} as DeleteQuery,
   ): Promise<DeleteResponse<T>> {
diff --git a/src/Typesense/Types.ts b/src/Typesense/Types.ts
index 366e832c..8c358f76 100644
--- a/src/Typesense/Types.ts
+++ b/src/Typesense/Types.ts
@@ -214,6 +214,10 @@ export interface WriteableDocuments<T> {
     document: T,
     options: Omit<DocumentWriteParameters, "action">,
   ): Promise<T>;
+  emplace(
+    document: T,
+    options: Omit<DocumentWriteParameters, "action">,
+  ): Promise<T>;
   delete(query: DeleteQuery): Promise<DeleteResponse>;
   import(
     documents: T[] | string,