From 3bb9ad0d4ae44382d43d7b7a0ccd98282ed2ae62 Mon Sep 17 00:00:00 2001
From: Micha de Vries <micha.de.vries@surrealdb.com>
Date: Wed, 18 Sep 2024 17:15:53 +0100
Subject: [PATCH] update js docs (#867)

---
 .../doc-sdk-javascript/core/data-querying.mdx | 92 ++++++++++++++++---
 .../core/initialization.mdx                   |  4 +-
 .../doc-sdk-javascript/core/utilities.mdx     | 20 +++-
 .../doc-sdk-javascript/engines/node.mdx       |  4 +-
 .../doc-sdk-javascript/engines/wasm.mdx       |  2 +-
 src/content/doc-sdk-javascript/setup.mdx      | 16 ++--
 6 files changed, 111 insertions(+), 27 deletions(-)

diff --git a/src/content/doc-sdk-javascript/core/data-querying.mdx b/src/content/doc-sdk-javascript/core/data-querying.mdx
index 3754fffb1..9c246d170 100644
--- a/src/content/doc-sdk-javascript/core/data-querying.mdx
+++ b/src/content/doc-sdk-javascript/core/data-querying.mdx
@@ -229,7 +229,7 @@ CREATE $thing CONTENT $data;
 Inserts one or multiple records in the database.
 
 ```ts title="Method Syntax"
-async db.insert<T>(thing, data)
+async db.insert<T>(table, data)
 ```
 
 ### Arguments
@@ -243,11 +243,11 @@ async db.insert<T>(thing, data)
     <tbody>
         <tr>
             <td colspan="2" scope="row" data-label="Arguments">
-                <code>thing</code>
-                <Label label="required" />
+                <code>table</code>
+                <Label label="optional" />
             </td>
             <td colspan="2" scope="row" data-label="Description">
-                The table name or [`RecordId`](/docs/sdk/javascript/data-types#recordid) to insert to.
+                Optionally pass along a table to insert into.
             </td>
         </tr>
         <tr>
@@ -282,14 +282,6 @@ const [person] = await db.insert<Person>('person', {
 	},
 });
 
-const person = await db.insert<Person>(new RecordId('person', 'tobie'), {
-	name: 'Tobie',
-	settings: {
-		active: true,
-		marketing: true,
-	},
-});
-
 // Insert multiple records
 const people = await db.insert<Person>('person', [
 	{
@@ -322,7 +314,81 @@ const people = await db.insert<
 This function will run the following query in the database.
 
 ```surql
-INSERT INTO $thing $data;
+INSERT INTO $table $data;
+```
+
+<br />
+
+## `.insert_relation()` {#insert_relation}
+
+Inserts one or multiple relations in the database.
+
+```ts title="Method Syntax"
+async db.insert<T>(table, data)
+```
+
+### Arguments
+<table>
+    <thead>
+        <tr>
+            <th colspan="2" scope="col">Arguments</th>
+            <th colspan="2" scope="col">Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td colspan="2" scope="row" data-label="Arguments">
+                <code>table</code>
+                <Label label="optional" />
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Optionally pass along a table to insert into.
+            </td>
+        </tr>
+        <tr>
+            <td colspan="2" scope="row" data-label="Arguments">
+                <code>data</code>
+               <Label label="optional" />
+            </td>
+            <td colspan="2" scope="row" data-label="Description">
+                Either a single document/record or an array of documents/records to insert
+            </td>
+        </tr>
+    </tbody>
+</table>
+
+### Example usage
+```ts
+type Likes = {
+	id: RecordId<"likes">;
+	in: RecordId<"person">;
+	out: RecordId<"post">;
+};
+
+// Insert a single record
+const [person] = await db.insert_relation<Likes>('likes', {
+	in: new RecordId('person', 'tobie'),
+	out: new RecordId('post', 123),
+});
+
+// Insert multiple records across tables
+const people = await db.insert<Likes>('likes', [
+	{
+    	in: new RecordId('person', 'tobie'),
+    	out: new RecordId('post', 123),
+	},
+	{
+    	in: new RecordId('person', 'jaime'),
+    	out: new RecordId('post', 456),
+	},
+]);
+```
+
+### Translated query
+This function will run the following query in the database.
+
+```surql
+INSERT RELATION INTO $table $data;
 ```
 
 <br />
diff --git a/src/content/doc-sdk-javascript/core/initialization.mdx b/src/content/doc-sdk-javascript/core/initialization.mdx
index a699856d2..6b30753b7 100644
--- a/src/content/doc-sdk-javascript/core/initialization.mdx
+++ b/src/content/doc-sdk-javascript/core/initialization.mdx
@@ -17,7 +17,7 @@ After [installing the SDK](/docs/sdk/javascript/setup) and selecting your import
   <TabItem value="TS" label="TypeScript" default>
 
 ```typescript title="../utils/surreal.ts"
-import { Surreal } from "surrealdb.js";
+import { Surreal } from "surrealdb";
 
 // highlight-start
 let db: Surreal | undefined;
@@ -50,7 +50,7 @@ export function getDb(): Surreal | undefined {
   </TabItem>
   <TabItem value="JS" label="JavaScript">
 ```js title="../utils/surreal.js"
-import { Surreal } from "surrealdb.js";
+import { Surreal } from "surrealdb";
 
 // highlight-start
 let db;
diff --git a/src/content/doc-sdk-javascript/core/utilities.mdx b/src/content/doc-sdk-javascript/core/utilities.mdx
index 9995639e6..1343564c1 100644
--- a/src/content/doc-sdk-javascript/core/utilities.mdx
+++ b/src/content/doc-sdk-javascript/core/utilities.mdx
@@ -168,7 +168,7 @@ A method allowing you to write a tagged template string, automatically escaping
 
 ```ts
 // Optionally, `surrealql` is an alias export of `surql`
-import { surql, surrealql } from 'surrealdb.js';
+import { surql, surrealql } from 'surrealdb';
 
 const content = { name: "Tobie" };
 const query = surql`CREATE person CONTENT ${content}`;
@@ -184,3 +184,21 @@ await surreal.query(
     [name.fill("Jaime")]
 );
 ```
+
+<br />
+
+## String Prefixes
+
+These methods are also based on tagged templates, but they replicate SurrealQLs string prefixes in JS.
+
+### Example
+
+```ts
+// Optionally, `surrealql` is an alias export of `surql`
+import { s, d, r, u } from 'surrealdb';
+
+const string = s`I am a string`;
+const date = d`2024-05-06T17:44:57.085Z`;
+const record = r`person:tobie`;
+const uuid = u`92b84bde-39c8-4b4b-92f7-626096d6c4d9`;
+```
diff --git a/src/content/doc-sdk-javascript/engines/node.mdx b/src/content/doc-sdk-javascript/engines/node.mdx
index 0f1268f86..e37b4e853 100644
--- a/src/content/doc-sdk-javascript/engines/node.mdx
+++ b/src/content/doc-sdk-javascript/engines/node.mdx
@@ -14,7 +14,7 @@ It enables SurrealDB to be run in-memory, or to persist data by running on top o
 ### Example
 
 ```js
-import { Surreal } from 'surrealdb.js';
+import { Surreal } from 'surrealdb';
 import { surrealdbNodeEngines } from 'surrealdb.node';
 
 // Enable the WebAssembly engines
@@ -28,4 +28,4 @@ await db.connect("mem://");
 await db.connect("surrealkv://demo");
 
 // Now use the JavaScript SDK as normal.
-```
\ No newline at end of file
+```
diff --git a/src/content/doc-sdk-javascript/engines/wasm.mdx b/src/content/doc-sdk-javascript/engines/wasm.mdx
index 29aaf51a8..fd570a003 100644
--- a/src/content/doc-sdk-javascript/engines/wasm.mdx
+++ b/src/content/doc-sdk-javascript/engines/wasm.mdx
@@ -16,7 +16,7 @@ This library works with ES modules (import), not CommonJS (require).
 ### Example
 
 ```js
-import { Surreal } from 'surrealdb.js';
+import { Surreal } from 'surrealdb';
 import { surrealdbWasmEngines } from 'surrealdb.wasm';
 
 // Enable the WebAssembly engines
diff --git a/src/content/doc-sdk-javascript/setup.mdx b/src/content/doc-sdk-javascript/setup.mdx
index 50f4fbc4b..3cffc4536 100644
--- a/src/content/doc-sdk-javascript/setup.mdx
+++ b/src/content/doc-sdk-javascript/setup.mdx
@@ -20,28 +20,28 @@ import TabItem from "@components/Tabs/TabItem.astro";
   <TabItem value="npm" label="npm" default>
 
 ```bash
-npm install --save surrealdb.js
+npm install --save surrealdb
 ```
 
   </TabItem>
   <TabItem value="yarn" label="yarn">
 
 ```bash
-yarn add surrealdb.js
+yarn add surrealdb
 ```
 
   </TabItem>
   <TabItem value="pnpm" label="pnpm">
 
 ```bash
-pnpm install surrealdb.js
+pnpm install surrealdb
 ```
 
   </TabItem>
   <TabItem value="bun" label="bun">
 
 ```bash
-bun install surrealdb.js
+bun install surrealdb
 ```
 
   </TabItem>
@@ -57,11 +57,11 @@ After installing, you can then import the SDK into your project. Depending on yo
 > It is recommended to import this in a utility file or a file that is shared across your application.
 
 ```bash title="CommonJS"
-const { Surreal } = require('surrealdb.js');
+const { Surreal } = require('surrealdb');
 ```
 
 ```bash title="ES6"
-import { Surreal } from 'surrealdb.js';
+import { Surreal } from 'surrealdb';
 ```
 
 In a deno runtime, you can import the SDK using the following syntax:
@@ -77,9 +77,9 @@ import Surreal from "https://deno.land/x/surrealdb@1.0.0/mod.ts";
 Importing via a CDN is also supported:
 
 ```bash title="CDN"
-import Surreal from "https://unpkg.com/surrealdb.js";
+import Surreal from "https://unpkg.com/surrealdb";
 // or
-import Surreal from "https://cdn.jsdelivr.net/npm/surrealdb.js";
+import Surreal from "https://cdn.jsdelivr.net/npm/surrealdb";
 ```
 
 ### Initialize the SDK