From b67ef8a7ebdb0a94baf1ec7bacdf1bbd3775c75f Mon Sep 17 00:00:00 2001
From: Nikita Sivukhin <sivukhin@turso.tech>
Date: Fri, 3 Oct 2025 13:20:13 +0400
Subject: [PATCH] add basic examples for database-wasm package

---
 .../examples/database-node/README.md          | 12 +++
 .../examples/database-node/index.mjs          | 21 ++++
 .../examples/database-node/package.json       | 14 +++
 .../examples/database-wasm-vite/.gitignore    |  1 +
 .../examples/database-wasm-vite/README.md     | 63 ++++++++++++
 .../examples/database-wasm-vite/index.html    | 95 +++++++++++++++++++
 .../examples/database-wasm-vite/package.json  | 19 ++++
 .../examples/database-wasm-vite/server.mjs    | 34 +++++++
 .../examples/database-wasm-vite/vercel.json   | 11 +++
 .../database-wasm-vite/vite.config.ts         | 10 ++
 bindings/javascript/package-lock.json         | 35 ++++++-
 bindings/javascript/package.json              |  4 +-
 bindings/javascript/yarn.lock                 | 29 ++++--
 13 files changed, 337 insertions(+), 11 deletions(-)
 create mode 100644 bindings/javascript/examples/database-node/README.md
 create mode 100644 bindings/javascript/examples/database-node/index.mjs
 create mode 100644 bindings/javascript/examples/database-node/package.json
 create mode 100644 bindings/javascript/examples/database-wasm-vite/.gitignore
 create mode 100644 bindings/javascript/examples/database-wasm-vite/README.md
 create mode 100644 bindings/javascript/examples/database-wasm-vite/index.html
 create mode 100644 bindings/javascript/examples/database-wasm-vite/package.json
 create mode 100644 bindings/javascript/examples/database-wasm-vite/server.mjs
 create mode 100644 bindings/javascript/examples/database-wasm-vite/vercel.json
 create mode 100644 bindings/javascript/examples/database-wasm-vite/vite.config.ts

diff --git a/bindings/javascript/examples/database-node/README.md b/bindings/javascript/examples/database-node/README.md
new file mode 100644
index 000000000..492ae652d
--- /dev/null
+++ b/bindings/javascript/examples/database-node/README.md
@@ -0,0 +1,12 @@
+# database-node
+
+This is a minimal example showing how to use [`@tursodatabase/database`](https://www.npmjs.com/package/@tursodatabase/database) in the node.js
+
+---
+
+## Usage
+
+```bash
+npm install
+node index.mjs
+```
\ No newline at end of file
diff --git a/bindings/javascript/examples/database-node/index.mjs b/bindings/javascript/examples/database-node/index.mjs
new file mode 100644
index 000000000..33e46081d
--- /dev/null
+++ b/bindings/javascript/examples/database-node/index.mjs
@@ -0,0 +1,21 @@
+import { connect } from "@tursodatabase/database";
+
+const db = await connect("local.db", {
+    timeout: 1000, // busy timeout for handling high-concurrency write cases
+});
+
+// execute multiple SQL statements with exec(...)
+await db.exec(`
+    CREATE TABLE IF NOT EXISTS guestbook (comment TEXT, created_at DEFAULT (unixepoch()));
+    CREATE INDEX IF NOT EXISTS guestbook_idx ON guestbook (created_at);
+`);
+
+// use prepared statements and bind args to placeholders later
+const insert = db.prepare(`INSERT INTO guestbook(comment) VALUES (?)`);
+
+// use run(...) method if query only need to be executed till completion
+await insert.run([`hello, turso at ${Math.floor(Date.now() / 1000)}`]);
+
+const select = db.prepare(`SELECT * FROM guestbook ORDER BY created_at DESC LIMIT ?`);
+// use all(...) or get(...) methods to get all or one row from the query
+console.info(await select.all([5]))
diff --git a/bindings/javascript/examples/database-node/package.json b/bindings/javascript/examples/database-node/package.json
new file mode 100644
index 000000000..43bca7eaa
--- /dev/null
+++ b/bindings/javascript/examples/database-node/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "database-node",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@tursodatabase/database": "^0.2.0"
+  }
+}
diff --git a/bindings/javascript/examples/database-wasm-vite/.gitignore b/bindings/javascript/examples/database-wasm-vite/.gitignore
new file mode 100644
index 000000000..e985853ed
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/.gitignore
@@ -0,0 +1 @@
+.vercel
diff --git a/bindings/javascript/examples/database-wasm-vite/README.md b/bindings/javascript/examples/database-wasm-vite/README.md
new file mode 100644
index 000000000..fcbc230c6
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/README.md
@@ -0,0 +1,63 @@
+# database-wasm-vite
+
+This is a minimal example showing how to use [`@tursodatabase/database-wasm`](https://www.npmjs.com/package/@tursodatabase/database-wasm) in the browser with [Vite](https://vite.dev/).  
+
+---
+
+## Usage
+
+```bash
+npm install
+npm run dev
+# or build assets and serve them with simple node.js server
+npm run build
+npm run serve
+```
+
+---
+
+## Important: COOP / COEP Headers
+
+Because `@tursodatabase/database-wasm` relies on **SharedArrayBuffer**, you need Cross-Origin headers in development and production:
+
+### Vite dev server config (`vite.config.js`)
+
+```js
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    }
+  }
+})
+```
+
+### Static production server (`server.mjs`)
+
+When serving the `dist/` build, also make sure your server sets these headers:
+
+```js
+res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+```
+
+### Vercel deployment
+
+If you deploy to [**Vercel**](https://vercel.com/), add a `vercel.json` file to ensure COOP / COEP headers are set:
+
+```json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
+        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
+      ]
+    }
+  ]
+}
+```
\ No newline at end of file
diff --git a/bindings/javascript/examples/database-wasm-vite/index.html b/bindings/javascript/examples/database-wasm-vite/index.html
new file mode 100644
index 000000000..dfa3a4c6b
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/index.html
@@ -0,0 +1,95 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <title>Guestbook</title>
+  <style>
+    body {
+      font-family: sans-serif;
+      max-width: 600px;
+      margin: 2rem auto;
+    }
+
+    #comments {
+      border: 1px solid #ddd;
+      border-radius: 6px;
+      padding: 0;
+      list-style: none;
+    }
+
+    #comments li {
+      padding: 8px;
+      border-top: 1px solid #eee;
+    }
+
+    #comments li:first-child {
+      border-top: none;
+    }
+
+    .time {
+      font-size: 0.8em;
+      color: gray;
+    }
+  </style>
+</head>
+
+<body>
+  <h1>Guestbook</h1>
+  <form id="form">
+    <input id="comment" placeholder="Write a comment..." style="width:70%; padding:6px;" />
+    <button type="submit">Add</button>
+  </form>
+  <ul id="comments"></ul>
+
+  <script type="module">
+    import { connect } from "@tursodatabase/database-wasm/vite";
+
+    let db = await connect("local.db", {
+      timeout: 1000 // busy timeout for handling high-concurrency write cases
+    });
+    // execute multiple SQL statements with exec(...)
+    await db.exec(`
+      CREATE TABLE IF NOT EXISTS guestbook ( comment TEXT, created_at DEFAULT (unixepoch()) );
+      CREATE INDEX IF NOT EXISTS guestbook_idx ON guestbook (created_at);
+    `);
+    await refresh();
+
+    async function addComment() {
+      // use prepared statements and bind args to placeholders later
+      const insert = db.prepare(`INSERT INTO guestbook(comment) VALUES (?)`);
+
+      const input = document.getElementById("comment");
+      const text = input.value.trim();
+      input.value = "";
+
+      // use run(...) method if query only need to be executed till completion
+      await insert.run([text]);
+
+      await refresh();
+    }
+    document.getElementById("form").addEventListener("submit", (e) => {
+      e.preventDefault();
+      addComment();
+    });
+
+    async function refresh() {
+      const select = db.prepare(`SELECT comment, created_at FROM guestbook ORDER BY created_at DESC LIMIT ?`);
+      // use all(...) or get(...) methods to get all or one row from the query
+      const rows = await select.all([5]);
+
+      const ul = document.getElementById("comments");
+      ul.innerHTML = "";
+      rows.forEach((row) => {
+        const li = document.createElement("li");
+        li.innerHTML = `
+              <div>${row.comment}</div>
+              <div class="time">${new Date(row.created_at * 1000).toLocaleString()}</div>
+            `;
+        ul.appendChild(li);
+      });
+    }
+  </script>
+</body>
+
+</html>
\ No newline at end of file
diff --git a/bindings/javascript/examples/database-wasm-vite/package.json b/bindings/javascript/examples/database-wasm-vite/package.json
new file mode 100644
index 000000000..88ec402bf
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "database-wasm-vite",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "serve": "node server.mjs"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "vite": "^7.1.9"
+  },
+  "dependencies": {
+    "@tursodatabase/database-wasm": "^0.2.0"
+  }
+}
diff --git a/bindings/javascript/examples/database-wasm-vite/server.mjs b/bindings/javascript/examples/database-wasm-vite/server.mjs
new file mode 100644
index 000000000..9daa24d39
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/server.mjs
@@ -0,0 +1,34 @@
+import http from "http";
+import { readFile } from "fs/promises";
+import { extname, join } from "path";
+import { fileURLToPath } from "url";
+
+const root = fileURLToPath(new URL("./dist", import.meta.url));
+const port = 8080;
+
+const mimeTypes = { ".html": "text/html", ".js": "application/javascript" };
+
+const server = http.createServer(async (req, res) => {
+  // COOP / COEP headers necessary for shared WASM memory
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+
+  try {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+    const filePath = pathname === "/" ? "index.html" : pathname;
+    const fullPath = join(root, filePath);
+
+    const data = await readFile(fullPath);
+    const ext = extname(fullPath).toLowerCase();
+    const contentType = mimeTypes[ext] || "application/octet-stream";
+
+    res.writeHead(200, { "Content-Type": contentType });
+    res.end(data);
+  } catch (err) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  }
+});
+
+server.listen(port, "0.0.0.0", () => console.log(`Serving on http://localhost:${port}`));
diff --git a/bindings/javascript/examples/database-wasm-vite/vercel.json b/bindings/javascript/examples/database-wasm-vite/vercel.json
new file mode 100644
index 000000000..3de04dda1
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/vercel.json
@@ -0,0 +1,11 @@
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
+        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
+      ]
+    }
+  ]
+}
diff --git a/bindings/javascript/examples/database-wasm-vite/vite.config.ts b/bindings/javascript/examples/database-wasm-vite/vite.config.ts
new file mode 100644
index 000000000..48bdbef5f
--- /dev/null
+++ b/bindings/javascript/examples/database-wasm-vite/vite.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    }
+  }
+})
diff --git a/bindings/javascript/package-lock.json b/bindings/javascript/package-lock.json
index 30522cec1..ee09edf43 100644
--- a/bindings/javascript/package-lock.json
+++ b/bindings/javascript/package-lock.json
@@ -13,9 +13,28 @@
         "packages/wasm",
         "sync/packages/common",
         "sync/packages/native",
-        "sync/packages/wasm"
+        "sync/packages/wasm",
+        "examples/database-node",
+        "examples/database-wasm-vite"
       ]
     },
+    "examples/database-node": {
+      "version": "1.0.0",
+      "license": "ISC",
+      "dependencies": {
+        "@tursodatabase/database": "^0.2.0"
+      }
+    },
+    "examples/database-wasm-vite": {
+      "version": "1.0.0",
+      "license": "ISC",
+      "dependencies": {
+        "@tursodatabase/database-wasm": "^0.2.0"
+      },
+      "devDependencies": {
+        "vite": "^7.1.9"
+      }
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.27.1",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz",
@@ -1656,6 +1675,14 @@
         "node": ">= 12"
       }
     },
+    "node_modules/database-node": {
+      "resolved": "examples/database-node",
+      "link": true
+    },
+    "node_modules/database-wasm-vite": {
+      "resolved": "examples/database-wasm-vite",
+      "link": true
+    },
     "node_modules/debug": {
       "version": "4.4.1",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz",
@@ -3248,9 +3275,9 @@
       "license": "MIT"
     },
     "node_modules/vite": {
-      "version": "7.1.5",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-7.1.5.tgz",
-      "integrity": "sha512-4cKBO9wR75r0BeIWWWId9XK9Lj6La5X846Zw9dFfzMRw38IlTk2iCcUt6hsyiDRcPidc55ZParFYDXi0nXOeLQ==",
+      "version": "7.1.9",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.1.9.tgz",
+      "integrity": "sha512-4nVGliEpxmhCL8DslSAUdxlB6+SMrhB0a1v5ijlh1xB1nEPuy1mxaHxysVucLHuWryAxLWg6a5ei+U4TLn/rFg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
diff --git a/bindings/javascript/package.json b/bindings/javascript/package.json
index 7625d4ca2..bcfcbf00b 100644
--- a/bindings/javascript/package.json
+++ b/bindings/javascript/package.json
@@ -12,7 +12,9 @@
     "packages/wasm",
     "sync/packages/common",
     "sync/packages/native",
-    "sync/packages/wasm"
+    "sync/packages/wasm",
+    "examples/database-node",
+    "examples/database-wasm-vite"
   ],
   "version": "0.2.0"
 }
diff --git a/bindings/javascript/yarn.lock b/bindings/javascript/yarn.lock
index 0d06fc233..a514aa9c7 100644
--- a/bindings/javascript/yarn.lock
+++ b/bindings/javascript/yarn.lock
@@ -1593,7 +1593,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@tursodatabase/database-wasm@workspace:packages/wasm":
+"@tursodatabase/database-wasm@npm:^0.2.0, @tursodatabase/database-wasm@workspace:packages/wasm":
   version: 0.0.0-use.local
   resolution: "@tursodatabase/database-wasm@workspace:packages/wasm"
   dependencies:
@@ -1608,7 +1608,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@tursodatabase/database@workspace:packages/native":
+"@tursodatabase/database@npm:^0.2.0, @tursodatabase/database@workspace:packages/native":
   version: 0.0.0-use.local
   resolution: "@tursodatabase/database@workspace:packages/native"
   dependencies:
@@ -2100,6 +2100,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"database-node@workspace:examples/database-node":
+  version: 0.0.0-use.local
+  resolution: "database-node@workspace:examples/database-node"
+  dependencies:
+    "@tursodatabase/database": "npm:^0.2.0"
+  languageName: unknown
+  linkType: soft
+
+"database-wasm-vite@workspace:examples/database-wasm-vite":
+  version: 0.0.0-use.local
+  resolution: "database-wasm-vite@workspace:examples/database-wasm-vite"
+  dependencies:
+    "@tursodatabase/database-wasm": "npm:^0.2.0"
+    vite: "npm:^7.1.9"
+  languageName: unknown
+  linkType: soft
+
 "debug@npm:4":
   version: 4.4.3
   resolution: "debug@npm:4.4.3"
@@ -3865,9 +3882,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"vite@npm:^5.0.0 || ^6.0.0 || ^7.0.0-0, vite@npm:^7.1.5":
-  version: 7.1.5
-  resolution: "vite@npm:7.1.5"
+"vite@npm:^5.0.0 || ^6.0.0 || ^7.0.0-0, vite@npm:^7.1.5, vite@npm:^7.1.9":
+  version: 7.1.9
+  resolution: "vite@npm:7.1.9"
   dependencies:
     esbuild: "npm:^0.25.0"
     fdir: "npm:^6.5.0"
@@ -3916,7 +3933,7 @@ __metadata:
       optional: true
   bin:
     vite: bin/vite.js
-  checksum: 10c0/782d2f20c25541b26d1fb39bef5f194149caff39dc25b7836e25f049ca919f2e2ce186bddb21f3f20f6195354b3579ec637a8ca08d65b117f8b6f81e3e730a9c
+  checksum: 10c0/f628f903a137c1410232558bde99c223ea00a090bda6af77752c61f912955f0050aac12d3cfe024d08a0f150ff6fab61b3d0be75d634a59b94d49f525392e1f7
   languageName: node
   linkType: hard