Add vector type support and fix stoolap 0.3.3 API compatibility

- Handle Value::Extension for both JSON and Vector data types
- Return vectors as Float32Array in JS (zero-copy from packed LE f32)
- Accept Float32Array as bind parameters for vector operations
- Add V8 TAG_FLOAT32_ARRAY cell type for direct Float32Array creation
- Add 19 vector tests: CRUD, distance functions, HNSW, transactions
- Fix Value::Json → Value::Extension migration (stoolap 0.3.3 API change)

Author: semihalev

__test__/index.spec.mjs

@@ -1487,3 +1487,179 @@ describe('Edge cases', () => {
     assert.ok(names.some(n => n === 'ws_test'));
   });
 });
+
+// ============================================================
+// Vector support
+// ============================================================
+
+describe('Vector support', () => {
+  let db;
+
+  before(async () => {
+    db = await Database.open(':memory:');
+  });
+
+  after(async () => {
+    await db.close();
+  });
+
+  it('should create table with VECTOR column', async () => {
+    await db.exec('CREATE TABLE embeddings (id INTEGER PRIMARY KEY, embedding VECTOR(3))');
+    const tables = await db.query('SHOW TABLES');
+    const names = tables.map(t => t.table_name || t.Tables);
+    assert.ok(names.some(n => n === 'embeddings'));
+  });
+
+  it('should insert vectors via SQL string literals', async () => {
+    const result = await db.execute(
+      "INSERT INTO embeddings (id, embedding) VALUES (1, '[0.1, 0.2, 0.3]')"
+    );
+    assert.equal(result.changes, 1);
+  });
+
+  it('should insert multiple vectors', async () => {
+    await db.execute("INSERT INTO embeddings (id, embedding) VALUES (2, '[0.4, 0.5, 0.6]')");
+    await db.execute("INSERT INTO embeddings (id, embedding) VALUES (3, '[0.7, 0.8, 0.9]')");
+    const rows = await db.query('SELECT id FROM embeddings ORDER BY id');
+    assert.equal(rows.length, 3);
+  });
+
+  it('should return vectors as Float32Array', async () => {
+    const row = await db.queryOne('SELECT embedding FROM embeddings WHERE id = 1');
+    assert.ok(row.embedding instanceof Float32Array, 'embedding should be Float32Array');
+    assert.equal(row.embedding.length, 3);
+    assert.ok(Math.abs(row.embedding[0] - 0.1) < 0.001);
+    assert.ok(Math.abs(row.embedding[1] - 0.2) < 0.001);
+    assert.ok(Math.abs(row.embedding[2] - 0.3) < 0.001);
+  });
+
+  it('should return vectors in query() results', async () => {
+    const rows = await db.query('SELECT * FROM embeddings ORDER BY id');
+    assert.equal(rows.length, 3);
+    for (const row of rows) {
+      assert.ok(row.embedding instanceof Float32Array);
+      assert.equal(row.embedding.length, 3);
+    }
+  });
+
+  it('should return vectors in querySync() results', () => {
+    const rows = db.querySync('SELECT * FROM embeddings ORDER BY id');
+    assert.equal(rows.length, 3);
+    assert.ok(rows[0].embedding instanceof Float32Array);
+  });
+
+  it('should return vectors in queryOneSync() results', () => {
+    const row = db.queryOneSync('SELECT embedding FROM embeddings WHERE id = 2');
+    assert.ok(row.embedding instanceof Float32Array);
+    assert.ok(Math.abs(row.embedding[0] - 0.4) < 0.001);
+  });
+
+  it('should return vectors in queryRaw() results', async () => {
+    const raw = await db.queryRaw('SELECT id, embedding FROM embeddings ORDER BY id');
+    assert.ok(raw.columns.includes('embedding'));
+    assert.equal(raw.rows.length, 3);
+    const embIdx = raw.columns.indexOf('embedding');
+    assert.ok(raw.rows[0][embIdx] instanceof Float32Array);
+  });
+
+  it('should return vectors in queryRawSync() results', () => {
+    const raw = db.queryRawSync('SELECT id, embedding FROM embeddings ORDER BY id');
+    const embIdx = raw.columns.indexOf('embedding');
+    assert.ok(raw.rows[0][embIdx] instanceof Float32Array);
+  });
+
+  it('should handle NULL vectors', async () => {
+    await db.execute("INSERT INTO embeddings (id, embedding) VALUES (4, NULL)");
+    const row = await db.queryOne('SELECT embedding FROM embeddings WHERE id = 4');
+    assert.equal(row.embedding, null);
+  });
+
+  it('should compute L2 distance', async () => {
+    const rows = await db.query(
+      "SELECT id, VEC_DISTANCE_L2(embedding, '[0.1, 0.2, 0.3]') AS dist FROM embeddings WHERE id <= 3 ORDER BY dist"
+    );
+    assert.equal(rows.length, 3);
+    // id=1 has the same vector, distance should be ~0
+    assert.equal(rows[0].id, 1);
+    assert.ok(rows[0].dist < 0.001);
+  });
+
+  it('should compute cosine distance', async () => {
+    const rows = await db.query(
+      "SELECT id, VEC_DISTANCE_COSINE(embedding, '[0.1, 0.2, 0.3]') AS dist FROM embeddings WHERE id <= 3 ORDER BY dist"
+    );
+    assert.equal(rows.length, 3);
+    assert.equal(rows[0].id, 1);
+    assert.ok(rows[0].dist < 0.001);
+  });
+
+  it('should support k-NN search with ORDER BY + LIMIT', async () => {
+    const rows = await db.query(
+      "SELECT id, VEC_DISTANCE_L2(embedding, '[0.4, 0.5, 0.6]') AS dist FROM embeddings WHERE id <= 3 ORDER BY dist LIMIT 2"
+    );
+    assert.equal(rows.length, 2);
+    // id=2 has exact match [0.4, 0.5, 0.6]
+    assert.equal(rows[0].id, 2);
+  });
+
+  it('should work with higher-dimensional vectors', async () => {
+    await db.exec('CREATE TABLE hd_vecs (id INTEGER PRIMARY KEY, vec VECTOR(128))');
+    const dims = 128;
+    const values = Array.from({ length: dims }, (_, i) => (i / dims).toFixed(6));
+    const vecStr = `[${values.join(', ')}]`;
+    await db.execute(`INSERT INTO hd_vecs (id, vec) VALUES (1, '${vecStr}')`);
+    const row = await db.queryOne('SELECT vec FROM hd_vecs WHERE id = 1');
+    assert.ok(row.vec instanceof Float32Array);
+    assert.equal(row.vec.length, dims);
+  });
+
+  it('should accept Float32Array as bind parameter', async () => {
+    await db.exec('CREATE TABLE vec_params (id INTEGER PRIMARY KEY, vec VECTOR(3))');
+    const vec = new Float32Array([1.0, 2.0, 3.0]);
+    await db.execute("INSERT INTO vec_params (id, vec) VALUES (1, '[1.0, 2.0, 3.0]')");
+    // Use Float32Array in distance computation param
+    const row = db.queryOneSync(
+      "SELECT VEC_DISTANCE_L2(vec, '[1.0, 2.0, 3.0]') AS dist FROM vec_params WHERE id = 1"
+    );
+    assert.ok(row.dist < 0.001);
+  });
+
+  it('should support vectors in transactions', async () => {
+    await db.exec('CREATE TABLE tx_vecs (id INTEGER PRIMARY KEY, vec VECTOR(3))');
+    const tx = await db.begin();
+    await tx.execute("INSERT INTO tx_vecs (id, vec) VALUES (1, '[1.0, 2.0, 3.0]')");
+    await tx.execute("INSERT INTO tx_vecs (id, vec) VALUES (2, '[4.0, 5.0, 6.0]')");
+    const rows = await tx.query('SELECT * FROM tx_vecs ORDER BY id');
+    assert.equal(rows.length, 2);
+    assert.ok(rows[0].vec instanceof Float32Array);
+    await tx.commit();
+
+    const afterCommit = await db.query('SELECT * FROM tx_vecs ORDER BY id');
+    assert.equal(afterCommit.length, 2);
+  });
+
+  it('should support VEC_DIMS utility function', async () => {
+    const row = await db.queryOne('SELECT VEC_DIMS(embedding) AS dims FROM embeddings WHERE id = 1');
+    assert.equal(row.dims, 3);
+  });
+
+  it('should reject wrong dimension count on insert', async () => {
+    await assert.rejects(
+      db.execute("INSERT INTO embeddings (id, embedding) VALUES (99, '[0.1, 0.2]')"),
+      /dimension|mismatch|expected/i
+    );
+  });
+
+  it('should support HNSW index creation', async () => {
+    await db.exec('CREATE TABLE hnsw_test (id INTEGER PRIMARY KEY, vec VECTOR(3))');
+    await db.execute("INSERT INTO hnsw_test (id, vec) VALUES (1, '[0.1, 0.2, 0.3]')");
+    await db.execute("INSERT INTO hnsw_test (id, vec) VALUES (2, '[0.4, 0.5, 0.6]')");
+    await db.execute("INSERT INTO hnsw_test (id, vec) VALUES (3, '[0.7, 0.8, 0.9]')");
+    await db.exec('CREATE INDEX idx_hnsw ON hnsw_test(vec) USING HNSW');
+    const rows = await db.query(
+      "SELECT id, VEC_DISTANCE_L2(vec, '[0.4, 0.5, 0.6]') AS dist FROM hnsw_test ORDER BY dist LIMIT 2"
+    );
+    assert.equal(rows.length, 2);
+    assert.equal(rows[0].id, 2);
+  });
+});

src/tasks.rs

@@ -34,6 +34,7 @@ const TAG_INT32: u8 = 3;
 const TAG_DOUBLE: u8 = 4;
 const TAG_STRING: u8 = 5;
 const TAG_INT64: u8 = 6;
+const TAG_FLOAT32_ARRAY: u8 = 7;
 
 /// C-compatible cell data — must match C++ CellData layout exactly.
 /// Passed to V8 helper for direct value creation (bypasses NAPI).
@@ -241,14 +242,33 @@ fn value_to_cell(val: &Value, temp_strings: &mut Vec<String>) -> CellData {
                 str_len: last.len() as i32,
             }
         }
-        Value::Json(s) => {
-            let s_ref: &str = s.as_ref();
-            CellData {
-                tag: TAG_STRING,
-                int_val: 0,
-                float_val: 0.0,
-                str_ptr: s_ref.as_ptr(),
-                str_len: s_ref.len() as i32,
+        Value::Extension(data) => {
+            if let Some(s_ref) = val.as_json() {
+                CellData {
+                    tag: TAG_STRING,
+                    int_val: 0,
+                    float_val: 0.0,
+                    str_ptr: s_ref.as_ptr(),
+                    str_len: s_ref.len() as i32,
+                }
+            } else if data.first() == Some(&7) {
+                // Vector: tag byte (7) + packed little-endian f32 payload
+                let payload = &data[1..];
+                CellData {
+                    tag: TAG_FLOAT32_ARRAY,
+                    int_val: 0,
+                    float_val: 0.0,
+                    str_ptr: payload.as_ptr(),
+                    str_len: payload.len() as i32,
+                }
+            } else {
+                CellData {
+                    tag: TAG_NULL,
+                    int_val: 0,
+                    float_val: 0.0,
+                    str_ptr: ptr::null(),
+                    str_len: 0,
+                }
             }
         }
     }

src/v8_helpers.cpp

@@ -27,13 +27,14 @@
 
 // Cell type tags — must match Rust #[repr(u8)] CellTag
 enum CellTag : uint8_t {
-    TAG_NULL       = 0,
-    TAG_BOOL_FALSE = 1,
-    TAG_BOOL_TRUE  = 2,
-    TAG_INT32      = 3,
-    TAG_DOUBLE     = 4,
-    TAG_STRING     = 5,
-    TAG_INT64      = 6,
+    TAG_NULL          = 0,
+    TAG_BOOL_FALSE    = 1,
+    TAG_BOOL_TRUE     = 2,
+    TAG_INT32         = 3,
+    TAG_DOUBLE        = 4,
+    TAG_STRING        = 5,
+    TAG_INT64         = 6,
+    TAG_FLOAT32_ARRAY = 7,
 };
 
 // C-compatible cell data — must match Rust #[repr(C)] CellData layout
@@ -82,6 +83,13 @@ static inline v8::Local<v8::Value> cell_to_v8(v8::Isolate* isolate,
             // Large integers outside i32 range — still a JS Number (double).
             // Matches napi_create_int64 behavior (converts to double).
             return v8::Number::New(isolate, static_cast<double>(cell.int_val));
+        case TAG_FLOAT32_ARRAY: {
+            // Vector: str_ptr = packed LE f32 bytes, str_len = byte count
+            int byte_len = cell.str_len;
+            auto backing = v8::ArrayBuffer::New(isolate, byte_len);
+            memcpy(backing->GetBackingStore()->Data(), cell.str_ptr, byte_len);
+            return v8::Float32Array::New(backing, 0, byte_len / 4);
+        }
         default:
             return v8::Null(isolate);
     }

src/value.rs

@@ -99,6 +99,37 @@ fn js_to_value_typed(env: sys::napi_env, val: sys::napi_value) -> napi::Result<V
         }
 
         napi::ValueType::Object => {
+            // Check TypedArray (Float32Array for vector params)
+            let mut is_typedarray = false;
+            check(unsafe { sys::napi_is_typedarray(env, val, &mut is_typedarray) })?;
+            if is_typedarray {
+                let mut typedarray_type = 0;
+                let mut length = 0;
+                let mut data = ptr::null_mut();
+                let mut arraybuffer = ptr::null_mut();
+                let mut offset = 0;
+                check(unsafe {
+                    sys::napi_get_typedarray_info(
+                        env,
+                        val,
+                        &mut typedarray_type,
+                        &mut length,
+                        &mut data,
+                        &mut arraybuffer,
+                        &mut offset,
+                    )
+                })?;
+                // napi_float32_array = 4
+                if typedarray_type == 4 {
+                    let slice =
+                        unsafe { std::slice::from_raw_parts(data as *const f32, length) };
+                    return Ok(Value::vector(slice.to_vec()));
+                }
+                return Err(napi::Error::from_reason(
+                    "Only Float32Array is supported for vector parameters",
+                ));
+            }
+
             // Check Date
             let mut is_date = false;
             check(unsafe { sys::napi_is_date(env, val, &mut is_date) })?;