sekejap 0.13.3 → 0.14.0

package/README.md

@@ -1,62 +1,86 @@
-# sekejap for Node.js
+# sekejap
 
-**Status: working** (tested). Native Node.js binding via [napi-rs](https://napi.rs/) —
-`#[napi]` over `sekejap::CoreDB`, compiled to a native N-API addon.
+Embedded **graph-first, multi-model database** for Node.js — SQL + graph + vector +
+spatial in one native library. No server, no external process; the whole engine runs
+in-process on a Rust core.
 
-## Run it
+- **PostgreSQL-like SQL** — `CREATE TABLE`, `INSERT`, `SELECT … WHERE`, parameters (`$1`).
+- **Graph** — link records and traverse relationships.
+- **Prepared statements** — compile once, run many with varying parameters.
+- **No native build** — the prebuilt binaries for every platform ship inside the
+  package. No Rust toolchain, no `node-gyp`, no compile step.
 
-```bash
-cd wrappers/node
-cargo build --release                        # builds the addon
-cp target/release/libsekejap_node.dylib sekejap.node   # (.so on Linux, .dll on Windows)
-node test.cjs                                # → OK — sekejap-node 0.13.0 …
+## Install
+
+```sh
+npm install sekejap
 ```
 
-For real packaging use `npx @napi-rs/cli build --release`, which names the addon
-per-platform and generates `index.js` + `index.d.ts` (TypeScript types). JS API:
-`Db.open(path)`, `execute`, `query`/`queryParams` (→ JSON string, `JSON.parse` it),
-`put`, `link`, `nodeCount`/`edgeCount`, `compact`, `version()`.
+Works on macOS (arm64/x64), Linux (x64/arm64), and Windows (x64), Node ≥ 16.
 
-## Approach
+## Quick start
 
-napi-rs is Node's equivalent of PyO3: you annotate Rust with `#[napi]` and it
-builds a native Node addon (`.node`) that speaks Node's stable **N-API** directly —
-idiomatic JS types, no manual C ABI. (An alternative is `koffi`/`ffi-napi` calling
-the C ABI in `../c`, but napi-rs gives better perf and TypeScript types.)
+```js
+const { Db, version } = require('sekejap');
 
+const db = Db.open('/tmp/notes');           // open (or create) a database directory
+
+// Define a table and insert rows with SQL.
+db.execute('CREATE TABLE note (_key TEXT PRIMARY KEY, title TEXT, pinned INTEGER)');
+db.execute("INSERT INTO note (_key, title, pinned) VALUES ('n1', 'Buy milk', 1)");
+
+// Insert a record directly (no SQL) as a JSON payload.
+db.put('note/n2', JSON.stringify({ _collection: 'note', _key: 'n2', title: 'Call Sam', pinned: 0 }));
+
+// Query. Results come back as a JSON string — JSON.parse it.
+const notes = JSON.parse(db.query('SELECT * FROM note'));
+console.log(notes);
+// [ { _key: 'n1', title: 'Buy milk', pinned: 1, ... }, { _key: 'n2', ... } ]
+
+// Parameterized query ($1, $2, …) — injection-safe. Params are a JSON array string.
+const pinned = JSON.parse(db.queryParams('SELECT title FROM note WHERE pinned = $1', JSON.stringify([1])));
+
+// Prepared statement — compile once, run many.
+const byPin = db.prepare('SELECT _key FROM note WHERE pinned = $1');
+for (const p of [0, 1]) {
+  console.log(JSON.parse(db.queryPrepared(byPin, JSON.stringify([p]))));
+}
+
+// Graph: link two records.
+db.link('note/n1', 'note/n2', 'related');
+console.log('nodes:', db.nodeCount(), 'edges:', db.edgeCount());
+
+// Flush + compact to disk after heavy writes.
+db.compact();
 ```
-wrappers/node/
-├── Cargo.toml        # crate-type = ["cdylib"], deps: napi, napi-derive; depends on the sekejap crate
-├── package.json      # name "sekejap", @napi-rs/cli build/publish scripts
-├── src/lib.rs        # #[napi] wrappers over sekejap::CoreDB / Engine
-├── index.d.ts        # generated TypeScript types
-└── examples/         # .js / .ts usage
-```
 
-Minimal `Cargo.toml` to add (then add `wrappers/node` to the workspace members):
+## API
+
+| Method | Purpose |
+|---|---|
+| `Db.open(path)` | Open (or create) a database at a directory path |
+| `db.execute(sql)` | Run DDL/DML (`CREATE`/`INSERT`/`UPDATE`/`DELETE`) → rows affected |
+| `db.query(sql)` | Run a `SELECT`/graph query → **JSON string** |
+| `db.queryParams(sql, paramsJson)` | Parameterized query; `paramsJson` is a JSON array string |
+| `db.prepare(sql)` / `db.queryPrepared(stmt, paramsJson)` | Prepared statements |
+| `db.put(slug, payloadJson)` | Insert/replace one record by slug with a JSON payload |
+| `db.link(from, to, edgeType)` | Create a graph edge |
+| `db.nodeCount()` / `db.edgeCount()` | Counts |
+| `db.compact()` | Flush WAL, rewrite payloads, reclaim RAM |
+| `version()` | Library version |
 
-```toml
-[package]
-name = "sekejap-node"
-version.workspace = true
-edition.workspace = true
+`query` / `queryParams` / `queryPrepared` return a **JSON string** — decode with
+`JSON.parse(...)`. It's an array of row objects.
 
-[lib]
-crate-type = ["cdylib"]
+### TypeScript
 
-[dependencies]
-sekejap = { path = "../.." }
-napi = { version = "2", features = ["napi8"] }
-napi-derive = "2"
+Types ship with the package (`index.d.ts`) — no `@types` needed.
 
-[build-dependencies]
-napi-build = "2"
+```ts
+import { Db } from 'sekejap';
+const db = Db.open('/tmp/notes');
 ```
 
-## Distribution
+## License
 
-- **Registry:** [npm](https://npmjs.com) → `npm install sekejap`
-- **Publish:** `npm publish`. Build prebuilt binaries per platform in CI with
-  `@napi-rs/cli` (`napi build --release`) and ship them as platform packages under
-  `optionalDependencies`, so users don't need a Rust toolchain.
-- Reserve the name `sekejap` on npm now.
+Dual-licensed under **MIT OR Apache-2.0**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sekejap",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "description": "Embedded graph-first multi-model database — Node.js binding",
   "license": "MIT OR Apache-2.0",
   "repository": "github:sekejapdb/sekejap",