web-sqlite-js 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wuchuheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+ <h1 align="center">web-sqlite-js</h1>
+<p align="center"> <img src="docs/public/web-sqlite-js.gif" width="400px" />
+</p>
+
+`web-sqlite-js` gives web developers an out-of-the-box way to run SQLite directly in the browser and keep data persisted on the client via OPFS (Origin Private File System).
+
+Developers only need to install and configure the http request header to use it directly, which is quite friendly.
+
+## Features
+
+- **Persistent Storage**: Uses OPFS for high-performance, persistent file storage.
+- **Non-Blocking**: Runs in a Web Worker, keeping your UI responsive.
+- **Concurrency Safe**: Built-in mutex ensures safe, sequential execution of commands.
+- **Type-Safe**: Written in TypeScript with full type definitions.
+- **Transactions**: Supports atomic transactions with automatic rollback on error.
+
+## Installation
+
+```bash
+npm install web-sqlite-js
+```
+
+## Setup http headers
+
+This library high-performance dependencies `SharedArrayBuffer`, which requires your server to send the following HTTP headers:
+
+```http
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+<details>
+<summary><strong>Vite</strong></summary>
+
+Update your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    server: {
+        headers: {
+            "Cross-Origin-Opener-Policy": "same-origin",
+            "Cross-Origin-Embedder-Policy": "require-corp",
+        },
+    },
+    preview: {
+        headers: {
+            "Cross-Origin-Opener-Policy": "same-origin",
+            "Cross-Origin-Embedder-Policy": "require-corp",
+        },
+    },
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Next.js</strong></summary>
+
+Update your `next.config.js`:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    async headers() {
+        return [
+            {
+                source: "/(.*)",
+                headers: [
+                    {
+                        key: "Cross-Origin-Opener-Policy",
+                        value: "same-origin",
+                    },
+                    {
+                        key: "Cross-Origin-Embedder-Policy",
+                        value: "require-corp",
+                    },
+                ],
+            },
+        ];
+    },
+};
+
+module.exports = nextConfig;
+```
+
+</details>
+
+<details>
+<summary><strong>Webpack (Dev Server)</strong></summary>
+
+Update your `webpack.config.js`:
+
+```javascript
+module.exports = {
+    // ...
+    devServer: {
+        headers: {
+            "Cross-Origin-Opener-Policy": "same-origin",
+            "Cross-Origin-Embedder-Policy": "require-corp",
+        },
+    },
+};
+```
+
+</details>
+
+<details>
+<summary><strong>Nginx</strong></summary>
+
+Add the headers to your server block:
+
+```nginx
+server {
+    # ...
+    add_header Cross-Origin-Opener-Policy "same-origin";
+    add_header Cross-Origin-Embedder-Policy "require-corp";
+    # ...
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Express.js</strong></summary>
+
+Use a middleware:
+
+```javascript
+const express = require("express");
+const app = express();
+
+app.use((req, res, next) => {
+    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+    res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+    next();
+});
+
+// ...
+```
+
+</details>
+
+<details>
+<summary><strong>React / Vue (Create React App / Vue CLI)</strong></summary>
+
+Most modern React/Vue setups use **Vite**. Please refer to the **Vite** section above.
+
+If you are using an older webpack-based setup (like CRA `react-scripts`), you technically need to configure the underlying `webpack-dev-server`, but CRA doesn't expose this easily without ejecting or using tools like `craco` or `react-app-rewired` to modify the dev server configuration as shown in the **Webpack** section.
+
+</details>
+
+## Usage
+
+#### Basic Usage
+
+```typescript
+import openDB from "web-sqlite-js";
+
+// 1. Open the database (creates 'my-database.sqlite3' in OPFS)
+const db = await openDB("my-database");
+
+// 2. Initialize schema
+await db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT,
+    email TEXT
+  );
+`);
+
+// 3. Insert data (Parameterized)
+await db.exec("INSERT INTO users (name, email) VALUES (?, ?)", [
+    "Alice",
+    "alice@example.com",
+]);
+await db.exec("INSERT INTO users (name, email) VALUES ($name, $email)", {
+    $name: "Bob",
+    $email: "bob@example.com",
+});
+
+// 4. Query data
+interface User {
+    id: number;
+    name: string;
+    email: string;
+}
+
+const users = await db.query<User>("SELECT * FROM users");
+console.log(users);
+// Output: [{ id: 1, name: 'Alice', ... }, { id: 2, name: 'Bob', ... }]
+
+// 5. Close when done
+await db.close();
+```
+
+#### Transactions
+
+Transactions are atomic. If any command inside the callback fails, the entire transaction is rolled back.
+
+```typescript
+await db.transaction(async (tx) => {
+    await tx.exec("INSERT INTO users (name) VALUES (?)", ["Charlie"]);
+
+    // You can perform multiple operations safely
+    await tx.exec("INSERT INTO logs (action) VALUES (?)", ["User Created"]);
+
+    // If you throw an error here, both INSERTs will be rolled back!
+    // throw new Error('Something went wrong');
+});
+```

package/dist/index.js

@@ -12743,7 +12743,6 @@ if(!globalThis.SharedArrayBuffer){
     return sIM;
   })();
   sqlite3InitModule = toExportForESM;
-  var sqlite3InitModule$1 = sqlite3InitModule;
   var SqliteEvent = /* @__PURE__ */ ((SqliteEvent2) => {
     SqliteEvent2["OPEN"] = "open";
     SqliteEvent2["CLOSE"] = "close";
@@ -12865,7 +12864,7 @@ if(!globalThis.SharedArrayBuffer){
     if (typeof payload.filename !== "string") {
       throw new Error("Invalid payload for OPEN event: expected filename string");
     }
-    sqlite3 = await sqlite3InitModule$1();
+    sqlite3 = await sqlite3InitModule();
     console.debug(\`Initialized sqlite3 module in worker.\`);
     let { filename } = payload;
     if (!filename.endsWith(".sqlite3")) {

package/package.json

@@ -1,10 +1,24 @@
 {
     "name": "web-sqlite-js",
-    "version": "0.0.1",
-    "description": "",
+    "version": "0.0.3",
+    "description": "web-sqlite-js gives web developers an out-of-the-box way to run SQLite directly in the browser and keep data persisted on the client via OPFS (Origin Private File System).",
+    "workspaces": [
+        "docs"
+    ],
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
+    "author": "wuchuheng <root@wuchuheng.com>",
+    "keywords": [
+        "sqlite",
+        "wasm",
+        "opfs",
+        "web-worker",
+        "database",
+        "typescript",
+        "web-sqlite"
+    ],
+    "sideEffects": false,
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
@@ -14,7 +28,7 @@
     "scripts": {
         "test": "npm run build && npm run lint && npm run test:unit && npm run test:e2e ",
         "test:unit": "vitest run --config vitest.unit.config.ts --coverage",
-        "http": "tsx scripts/http-service.ts ./ --port 8399",
+        "http": "tsx scripts/http-service.ts ./docs/.vitepress/dist --port 8399",
         "test:e2e": "vitest run --config vitest.e2e.config.ts",
         "test:debug": "vitest run --config vitest.e2e.config.ts --no-file-parallelism",
         "build": "vite build",
@@ -24,7 +38,12 @@
         "typecheck": "tsc --noEmit",
         "format": "prettier --ignore-path .gitignore --write .",
         "package:compress": "npm pack",
-        "package:publish": "npm run test && npm run build && npm publish --access public"
+        "package:publish": "npm run test && npm run build && npm publish --access public",
+        "docs:dev": "npm run dev --workspace=@web-sqlite-js/docs",
+        "docs:build": "npm run build --workspace=@web-sqlite-js/docs",
+        "docs:preview": "npm run preview --workspace=@web-sqlite-js/docs",
+        "docs:icons": "npm run icons --workspace=@web-sqlite-js/docs",
+        "docs:deploy": "cd docs && ./deploy.sh"
     },
     "files": [
         "dist"
@@ -53,12 +72,11 @@
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/wuchuheng/web-sqlite-v2.git"
+        "url": "git+https://github.com/wuchuheng/web-sqlite-js.git"
     },
-    "author": "",
-    "license": "ISC",
+    "license": "MIT",
     "bugs": {
-        "url": "https://github.com/wuchuheng/web-sqlite-v2/issues"
+        "url": "https://github.com/wuchuheng/web-sqlite-js/issues"
     },
-    "homepage": "https://github.com/wuchuheng/web-sqlite-v2#readme"
-}
+    "homepage": "https://github.com/wuchuheng/web-sqlite-js#readme"
+}