@neutron-build/nucleus 0.1.0

package/dist/vector/index.js

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/vector — Vector similarity search plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus, assertIdentifier } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class VectorModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'Vector');
+    }
+    async createCollection(name, dimension, metric = 'cosine') {
+        this.require();
+        assertIdentifier(name, 'collection name');
+        if (!Number.isInteger(dimension) || dimension <= 0 || dimension > 65535) {
+            throw new Error(`Invalid vector dimension: ${dimension}. Must be a positive integer <= 65535`);
+        }
+        const VALID_METRICS = ['cosine', 'l2', 'inner'];
+        if (!VALID_METRICS.includes(metric)) {
+            throw new Error(`Invalid distance metric: ${metric}. Must be one of: ${VALID_METRICS.join(', ')}`);
+        }
+        await this.transport.execute(`CREATE TABLE IF NOT EXISTS ${name} (id TEXT PRIMARY KEY, embedding VECTOR(${dimension}), metadata JSONB DEFAULT '{}')`);
+        await this.transport.execute(`CREATE INDEX IF NOT EXISTS idx_${name}_embedding ON ${name} USING VECTOR (embedding) WITH (metric = '${metric}')`);
+    }
+    async insert(collection, id, vector, metadata = {}) {
+        this.require();
+        assertIdentifier(collection, 'collection name');
+        const vecJson = JSON.stringify(vector);
+        const metaJson = JSON.stringify(metadata);
+        await this.transport.execute(`INSERT INTO ${collection} (id, embedding, metadata) VALUES ($1, VECTOR($2), $3)`, [id, vecJson, metaJson]);
+    }
+    async delete(collection, id) {
+        this.require();
+        assertIdentifier(collection, 'collection name');
+        await this.transport.execute(`DELETE FROM ${collection} WHERE id = $1`, [id]);
+    }
+    async search(collection, query, opts = {}) {
+        this.require();
+        assertIdentifier(collection, 'collection name');
+        const limit = opts.limit ?? 10;
+        const metric = opts.metric ?? 'cosine';
+        const vecJson = JSON.stringify(query);
+        // Build optional WHERE clause from filter
+        let filterClause = '';
+        const params = [vecJson, metric, limit];
+        if (opts.filter) {
+            const clauses = [];
+            for (const [k, v] of Object.entries(opts.filter)) {
+                const ki = params.length + 1;
+                const vi = params.length + 2;
+                clauses.push(`metadata->>$${ki} = $${vi}`);
+                params.push(k, String(v));
+            }
+            filterClause = ' WHERE ' + clauses.join(' AND ');
+        }
+        const sql = `SELECT id, metadata, VECTOR_DISTANCE(embedding, VECTOR($1), $2) AS distance ` +
+            `FROM ${collection}${filterClause} ORDER BY distance LIMIT $3`;
+        const result = await this.transport.query(sql, params);
+        return result.rows.map((row) => {
+            const meta = typeof row.metadata === 'string'
+                ? JSON.parse(row.metadata)
+                : (row.metadata ?? {});
+            meta.id = row.id;
+            const dist = Number(row.distance);
+            return {
+                item: meta,
+                score: dist > 0 ? 1 / dist : 0,
+                distance: dist,
+            };
+        });
+    }
+    async dims(vector) {
+        this.require();
+        const vecJson = JSON.stringify(vector);
+        return (await this.transport.fetchval('SELECT VECTOR_DIMS(VECTOR($1))', [vecJson])) ?? 0;
+    }
+    async distance(a, b, metric = 'cosine') {
+        this.require();
+        const aJson = JSON.stringify(a);
+        const bJson = JSON.stringify(b);
+        return ((await this.transport.fetchval('SELECT VECTOR_DISTANCE(VECTOR($1), VECTOR($2), $3)', [
+            aJson,
+            bJson,
+            metric,
+        ])) ?? 0);
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.vector` to the client. */
+export const withVector = {
+    name: 'vector',
+    init(transport, features) {
+        return { vector: new VectorModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/vector/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vector/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@neutron-build/nucleus",
+  "version": "0.1.0",
+  "description": "TypeScript client for Nucleus multi-model database engine.",
+  "author": "Tyler",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://neutron.build",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neutron-build/neutron",
+    "directory": "typescript/packages/neutron-nucleus"
+  },
+  "keywords": [
+    "neutron",
+    "nucleus",
+    "database",
+    "multi-model",
+    "sql",
+    "kv",
+    "vector",
+    "graph",
+    "timeseries"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sql": {
+      "types": "./dist/sql/index.d.ts",
+      "import": "./dist/sql/index.js"
+    },
+    "./kv": {
+      "types": "./dist/kv/index.d.ts",
+      "import": "./dist/kv/index.js"
+    },
+    "./vector": {
+      "types": "./dist/vector/index.d.ts",
+      "import": "./dist/vector/index.js"
+    },
+    "./document": {
+      "types": "./dist/document/index.d.ts",
+      "import": "./dist/document/index.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "import": "./dist/graph/index.js"
+    },
+    "./fts": {
+      "types": "./dist/fts/index.d.ts",
+      "import": "./dist/fts/index.js"
+    },
+    "./geo": {
+      "types": "./dist/geo/index.d.ts",
+      "import": "./dist/geo/index.js"
+    },
+    "./blob": {
+      "types": "./dist/blob/index.d.ts",
+      "import": "./dist/blob/index.js"
+    },
+    "./timeseries": {
+      "types": "./dist/timeseries/index.d.ts",
+      "import": "./dist/timeseries/index.js"
+    },
+    "./streams": {
+      "types": "./dist/streams/index.d.ts",
+      "import": "./dist/streams/index.js"
+    },
+    "./columnar": {
+      "types": "./dist/columnar/index.d.ts",
+      "import": "./dist/columnar/index.js"
+    },
+    "./datalog": {
+      "types": "./dist/datalog/index.d.ts",
+      "import": "./dist/datalog/index.js"
+    },
+    "./cdc": {
+      "types": "./dist/cdc/index.d.ts",
+      "import": "./dist/cdc/index.js"
+    },
+    "./pubsub": {
+      "types": "./dist/pubsub/index.d.ts",
+      "import": "./dist/pubsub/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "pnpm run build && node --test --experimental-test-isolation=none dist/index.test.js dist/integration.test.js dist/transport.test.js",
+    "typecheck": "tsc --noEmit"
+  }
+}