feat: Integrate libseekdb to support embedded mode

.github/workflows/build-js-bindings.yml

@@ -0,0 +1,183 @@
+# Build, pack and upload seekdb JS bindings for multiple platforms to S3
+#
+# Platforms: linux-x64, linux-arm64, darwin-arm64 (macOS x64 not supported)
+# S3: s3://oceanbase-seekdb-builds/js-bindings/all_commits/<sha>/seekdb-js-bindings-<platform>.zip
+#
+name: Build JS bindings
+run-name: Build JS bindings for ${{ github.sha }}
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - develop
+      - "*.*.x"
+      - "integration/*"
+    paths-ignore:
+      - "!.github/workflows/build-js-bindings*"
+      - ".github/**"
+      - "*.md"
+      - "LICENSE"
+      - "CODEOWNERS"
+      - "docs/**"
+      - "packages/seekdb/**"
+      - "packages/embeddings/**"
+      - "examples/**"
+  workflow_dispatch:
+  pull_request:
+    paths-ignore:
+      - ".github/**"
+      - "!.github/workflows/build-js-bindings*"
+      - "*.md"
+      - "LICENSE"
+      - "CODEOWNERS"
+      - "docs/**"
+      - "packages/seekdb/**"
+      - "packages/embeddings/**"
+      - "examples/**"
+
+env:
+  AWS_REGION: ${{ vars.AWS_REGION || 'ap-southeast-1' }}
+  BUCKET_NAME: ${{ vars.AWS_S3_BUCKET || 'oceanbase-seekdb-builds' }}
+  DESTINATION_TARGET_PATH: ${{ vars.SEEKDB_JS_BINDINGS_S3_PATH || format('s3://oceanbase-seekdb-builds/js-bindings/all_commits/{0}', github.sha) }}
+  S3_BUCKET: ${{ vars.AWS_S3_BUCKET || 'oceanbase-seekdb-builds' }}
+  S3_PREFIX: js-bindings/all_commits/${{ github.sha }}
+
+jobs:
+  # ---------- Build JS bindings on Linux ----------
+  build-linux:
+    name: Build JS bindings (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux-x64
+            runner: ubuntu-22.04
+          - platform: linux-arm64
+            runner: ubuntu-22.04-arm
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Setup Python (Linux)
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build bindings (Linux)
+        working-directory: packages/bindings
+        run: pnpm run build
+
+      - name: Pack artifact (Linux)
+        working-directory: packages/bindings/pkgs/js-bindings
+        run: zip -r ../../../../seekdb-js-bindings-${{ matrix.platform }}.zip . -x "seekdb.js" -x "seekdb.d.ts" -x "package.json"
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: seekdb-js-bindings-${{ matrix.platform }}
+          path: seekdb-js-bindings-${{ matrix.platform }}.zip
+
+  # ---------- Build JS bindings on macOS ----------
+  build-macos:
+    name: Build JS bindings (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: darwin-arm64
+            runner: macos-14
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build bindings (macOS)
+        working-directory: packages/bindings
+        run: pnpm run build
+
+      - name: Pack artifact (macOS)
+        working-directory: packages/bindings/pkgs/js-bindings
+        run: zip -r ../../../../seekdb-js-bindings-${{ matrix.platform }}.zip .
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: seekdb-js-bindings-${{ matrix.platform }}
+          path: seekdb-js-bindings-${{ matrix.platform }}.zip
+
+  # ---------- Collect artifacts and upload to S3 ----------
+  release-artifacts:
+    name: Collect artifacts and upload to S3
+    runs-on: ubuntu-22.04
+    needs:
+      - build-linux
+      - build-macos
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: release-artifacts
+          merge-multiple: true
+
+      - name: List all artifacts
+        run: |
+          echo "=== All artifacts ==="
+          ls -la release-artifacts/
+
+      - name: Configure AWS credentials
+        if: env.DESTINATION_TARGET_PATH != '' || env.S3_BUCKET != ''
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Upload to S3
+        if: env.DESTINATION_TARGET_PATH != '' || env.S3_BUCKET != ''
+        run: |
+          set -e
+          if [ -n "${{ env.DESTINATION_TARGET_PATH }}" ]; then
+            S3_TARGET="${{ env.DESTINATION_TARGET_PATH }}"
+          else
+            S3_TARGET="s3://${{ env.S3_BUCKET }}/${{ env.S3_PREFIX }}/"
+          fi
+          [ "${S3_TARGET: -1}" != "/" ] && S3_TARGET="${S3_TARGET}/"
+          echo "Uploading to $S3_TARGET"
+          aws s3 cp release-artifacts/ "$S3_TARGET" --recursive --exclude "*" --include "*.zip" --no-progress
+          echo "Uploaded:"
+          aws s3 ls "$S3_TARGET" --recursive
+          echo "Done."
+        continue-on-error: true

.github/workflows/ci.yml

@@ -65,9 +65,10 @@ jobs:
       - name: Build all packages
         run: pnpm run build
 
-  test:
+  # Server-mode tests (exclude embedded/; each job runs on its own runner so seekdb-docker cannot be shared across jobs)
+  test-server:
     if: github.repository == 'oceanbase/seekdb-js'
-    needs: [lint, build]
+    name: Test server
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -95,12 +96,85 @@ jobs:
           sleep 15
           docker logs seekdb-server
 
-      - name: Run tests
+      - name: Run server tests
+        working-directory: packages/seekdb
         env:
           SERVER_HOST: 127.0.0.1
           SERVER_PORT: 2881
           SERVER_USER: root
           SERVER_PASSWORD: ""
           SERVER_DATABASE: test
           SERVER_TENANT: sys
-        run: pnpm run test
+        run: pnpm exec vitest run --exclude 'tests/embedded/**'
+
+  # Embedded-mode tests on multiple platforms (requires native bindings build per OS; Docker per job)
+  test-embedded:
+    if: github.repository == 'oceanbase/seekdb-js'
+    name: Test embedded (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux-x64
+            runner: ubuntu-22.04
+          - platform: linux-arm64
+            runner: ubuntu-22.04-arm
+          - platform: darwin-arm64
+            runner: macos-14
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build bindings
+        working-directory: packages/bindings
+        run: pnpm run build
+
+      - name: Build packages
+        run: pnpm run build
+
+      # macOS has no Docker; skip container and exclude mode-consistency (needs seekdb server)
+      - name: Start seekdb container
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          docker run --name seekdb-server -p 2881:2881 -d oceanbase/seekdb:latest
+          sleep 15
+          docker logs seekdb-server
+
+      - name: Run embedded tests
+        working-directory: packages/seekdb
+        env:
+          SERVER_HOST: 127.0.0.1
+          SERVER_PORT: 2881
+          SERVER_USER: root
+          SERVER_PASSWORD: ""
+          SERVER_DATABASE: test
+          SERVER_TENANT: sys
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            pnpm exec vitest run tests/embedded/ 2>&1 | tee /tmp/vitest.log
+          else
+            pnpm exec vitest run tests/embedded/ --exclude '**/mode-consistency.test.ts' 2>&1 | tee /tmp/vitest.log
+          fi
+          exit_code=$?
+          if [ $exit_code -ne 0 ]; then exit $exit_code; fi
+          grep -qE "[0-9]+ failed" /tmp/vitest.log && exit 1
+          exit 0

.gitignore

@@ -11,5 +11,6 @@ coverage/
 .npmrc
 .pnpm-store
 .cursor
+seekdb.db
 spec/
-.vscode
+.vscode

.husky/pre-commit

@@ -0,0 +1 @@
+npx --no-install lint-staged

DEVELOP.md

@@ -2,6 +2,7 @@
 
 - [Development Guide](#development-guide)
   - [Prerequisites](#prerequisites)
+  - [Running Modes](#running-modes)
   - [Run Examples](#run-examples)
     - [Setup](#setup)
     - [Run Examples](#run-examples-1)
@@ -14,13 +15,16 @@
 
 - **Node.js**: Version >= 20
 - **Package Manager**: pnpm
-- **Database**: A running seekdb or OceanBase instance is required.
-  - Default connection config:
-    - Host: `127.0.0.1`
-    - Port: `2881`
-    - User: `root`
-    - Database: `test`
-    - Tenant: `sys` (Required for OceanBase mode)
+- **Database / running mode**:
+  - **Embedded mode**: No seekdb server required; install and build, then run examples and tests (using local `seekdb.db` or a custom `path`). Depends on the native addon (see `packages/bindings`). All embedded tests live under `packages/seekdb/tests/embedded/` and mirror server-mode scenarios.
+  - **Server mode**: A running seekdb or OceanBase instance (local or remote) is required.
+    - Default connection: Host `127.0.0.1`, Port `2881`, User `root`, Database `test`
+    - OceanBase mode requires Tenant: `sys`
+
+## Running Modes
+
+- **Embedded mode**: `new SeekdbClient({ path: "..." })`. Data is stored under the given path; no server needed. Admin operations use `AdminClient({ path: "..." })`, which returns a `SeekdbClient`. Examples and embedded-only tests run without a database server.
+- **Server mode**: `new SeekdbClient({ host, port, ... })` connects to a deployed seekdb/OceanBase. Start the database and verify connection settings before running server-mode examples.
 
 ## Run Examples
 
@@ -38,29 +42,30 @@ pnpm build
 
 ### Run Examples
 
-This project provides several example in the `packages/examples` directory. You can run them directly from the root directory using the following commands:
+Examples live in the root `examples/` directory. From the project root:
 
-- **Simple Example**:
-  Demonstrates basic connection, collection creation, data addition, and querying.
+- **Simple Example**: Basic connection, collection creation, add, and query.
 
   ```bash
   pnpm --filter seekdb-examples run run:simple
   ```
 
-- **Complete Example**:
-  Demonstrates all SDK features, including DML (CRUD), DQL (Query), Hybrid Search, etc.
+- **Complete Example**: Full feature demo (DML, DQL, Hybrid Search, etc.).
 
   ```bash
   pnpm --filter seekdb-examples run run:complete
   ```
 
-- **Hybrid Search Example**:
-  Focuses on demonstrating hybrid search functionality.
+- **Hybrid Search Example**: Hybrid search usage.
+
   ```bash
   pnpm --filter seekdb-examples run run:hybrid
   ```
 
-> **Note**: The example code connects to a local database (`127.0.0.1:2881`) by default. If your database configuration is different, please modify the `SeekdbClient` configuration in the corresponding `.ts` file under `packages/examples/`.
+**Running mode**:
+
+- Examples use **embedded mode** by default (`path: "./seekdb.db"`); no seekdb server is required.
+- For **server mode**, start seekdb/OceanBase and adjust the `SeekdbClient` config in the example (e.g. `host`, `port`, `user`, `password`); see comments in each example file.
 
 ---
 
@@ -82,16 +87,26 @@ pnpm build
 
 ### Run Tests
 
-The project uses Vitest for testing. Run tests for the core package `seekdb`:
+The project uses Vitest. Run tests for the core `seekdb` package from the project root:
 
 ```bash
 # Run all tests
 pnpm test
 
-# Or run with specific filter
+# Run only seekdb package tests
 pnpm --filter seekdb run test
+
+# Run only embedded-mode tests (no server required)
+pnpm --filter seekdb exec vitest run tests/embedded/
 ```
 
+**Tests and running mode**:
+
+- **Embedded-mode tests** live under `packages/seekdb/tests/embedded/` and use a temporary database path per test file. They do not require a seekdb/OceanBase server. Run them with the command above when no server is available.
+- **Server-mode tests** (under `packages/seekdb/tests/` but outside `embedded/`) connect to `127.0.0.1:2881` and require a local seekdb or OceanBase instance.
+- **Mode consistency** tests (`tests/embedded/mode-consistency.test.ts`) run both embedded and server modes in the same file; they require the native addon and a server for the server part.
+- Embedded test coverage vs server is documented in `packages/seekdb/tests/embedded/COVERAGE_REPORT.md`.
+
 ### Linting & Formatting
 
 ```bash