minigraf 1.2.2 → 1.2.3

package/Cargo.lock

@@ -280,9 +280,9 @@ checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "minigraf"
-version = "1.2.2"
+version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e62df0c250d941359d9610c25cdde804e4ade914694089e8b6e1c46b25251b0"
+checksum = "ee16db19bf63c1bc6c66fc75993a6e4b8cf7e253d4e5643b44923a939745a913"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -10,7 +10,7 @@ crate-type = ["cdylib"]
 [dependencies]
 napi = { version = "3.8", features = ["napi6"] }
 napi-derive = "3"
-minigraf = { version = "=1.2.2" }
+minigraf = { version = "=1.2.3" }
 serde_json = "1.0"
 
 [build-dependencies]

package/README.md

@@ -34,8 +34,33 @@ console.log(result.results[0][0])  // "Alice"
 const db2 = new MiniGrafDb('path/to/mydb.graph')
 db2.execute('(transact [[:bob :name "Bob"]])')
 db2.checkpoint()
+db2.close()
 ```
 
+## Closing a file-backed database
+
+Only one handle per `.graph` file may be open in a process at a time — two
+would each cache their own page table and corrupt the file — so call `close()`
+when you are done with one:
+
+```js
+const db = new MiniGrafDb('mydb.graph')
+db.execute('(transact [[:bob :name "Bob"]])')
+db.checkpoint()
+db.close()
+
+const again = new MiniGrafDb('mydb.graph') // fine: the first handle is gone
+```
+
+Letting the variable go out of scope is **not** enough. JavaScript has no
+deterministic destructor: the object becomes unreachable, but the underlying
+handle survives until V8 garbage-collects it, which may be arbitrarily later or
+not at all before the process exits. Reopening before then throws
+`Database is already open in this process`.
+
+`close()` is idempotent; every other method throws once it has run. In-memory
+databases hold no file lock, so closing them is optional.
+
 ## Building from source
 
 Requires Rust stable toolchain and `@napi-rs/cli`.

package/index.d.ts

@@ -1,7 +1,12 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 export declare class MiniGrafDb {
-  /** Open a file-backed database. Throws on error. */
+  /**
+   * Open a file-backed database. Throws on error.
+   *
+   * Only one handle per file may be open in a process at a time. Call
+   * `close()` before reopening the same path — see `close()`.
+   */
   constructor(path: string)
   /** Open an in-memory database. Throws on error. */
   static inMemory(): MiniGrafDb
@@ -9,4 +14,35 @@ export declare class MiniGrafDb {
   execute(datalog: string): string
   /** Flush the WAL to disk. Throws on error. */
   checkpoint(): void
+  /**
+   * Close the database, releasing its file lock immediately.
+   *
+   * Letting a `MiniGrafDb` go out of scope is **not** enough to release the
+   * file. JavaScript has no deterministic destructor: the object merely
+   * becomes unreachable, and the underlying handle lives until V8 garbage
+   * collects it — arbitrarily later, or never before the process exits.
+   *
+   * That matters because minigraf permits only one live handle per file per
+   * process (two would each cache their own page table and corrupt each
+   * other), so opening the same path again throws until the first handle is
+   * really gone. `close()` is the only way to make that happen on demand.
+   * Every other binding has the same escape hatch: UniFFI (Python, Java,
+   * Swift) exposes `destroy()`, and the C API exposes `minigraf_close`.
+   *
+   * Call `checkpoint()` first if you need to know the WAL was compacted;
+   * closing does that too, but cannot report a failure.
+   *
+   * Idempotent — closing an already-closed database is a no-op. Every other
+   * method throws afterwards.
+   *
+   * ```js
+   * const db = new MiniGrafDb(path)
+   * db.execute('(transact [[:bob :name "Bob"]])')
+   * db.checkpoint()
+   * db.close()
+   *
+   * const db2 = new MiniGrafDb(path) // fine: the first handle is gone
+   * ```
+   */
+  close(): void
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minigraf",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries",
   "main": "index.js",
   "types": "index.d.ts",

package/packages/@minigraf/darwin-universal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minigraf/darwin-universal",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries (macOS universal)",
   "os": [
     "darwin"

package/packages/@minigraf/linux-arm64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minigraf/linux-arm64-gnu",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries (Linux arm64 GNU)",
   "os": [
     "linux"

package/packages/@minigraf/linux-x64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minigraf/linux-x64-gnu",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries (Linux x64 GNU)",
   "os": [
     "linux"

package/packages/@minigraf/win32-x64-msvc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minigraf/win32-x64-msvc",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries (Windows x64 MSVC)",
   "os": [
     "win32"

package/src/lib.rs

@@ -42,20 +42,29 @@ fn query_result_to_json(result: QueryResult) -> String {
 
 // ─── MiniGrafDb ───────────────────────────────────────────────────────────────
 
+/// Thrown by every method once `close()` has run.
+const CLOSED_MSG: &str = "database is closed";
+
 #[napi]
 pub struct MiniGrafDb {
-    inner: Arc<Mutex<minigraf::Minigraf>>,
+    /// `None` once `close()` has run. JavaScript has no deterministic
+    /// destructor, so the handle needs an explicit way to be dropped — see
+    /// `close()`.
+    inner: Arc<Mutex<Option<minigraf::Minigraf>>>,
 }
 
 #[napi]
 impl MiniGrafDb {
     /// Open a file-backed database. Throws on error.
+    ///
+    /// Only one handle per file may be open in a process at a time. Call
+    /// `close()` before reopening the same path — see `close()`.
     #[napi(constructor)]
     pub fn new(path: String) -> Result<Self> {
         let db = minigraf::Minigraf::open(&path)
             .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))?;
         Ok(Self {
-            inner: Arc::new(Mutex::new(db)),
+            inner: Arc::new(Mutex::new(Some(db))),
         })
     }
 
@@ -65,17 +74,20 @@ impl MiniGrafDb {
         let db = minigraf::Minigraf::in_memory()
             .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))?;
         Ok(Self {
-            inner: Arc::new(Mutex::new(db)),
+            inner: Arc::new(Mutex::new(Some(db))),
         })
     }
 
     /// Execute a Datalog string. Returns a JSON string. Throws on error.
     #[napi]
     pub fn execute(&self, datalog: String) -> Result<String> {
-        let result = self
+        let guard = self
             .inner
             .lock()
-            .map_err(|_| Error::new(Status::GenericFailure, "mutex poisoned"))?
+            .map_err(|_| Error::new(Status::GenericFailure, "mutex poisoned"))?;
+        let result = guard
+            .as_ref()
+            .ok_or_else(|| Error::new(Status::GenericFailure, CLOSED_MSG))?
             .execute(&datalog)
             .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))?;
         Ok(query_result_to_json(result))
@@ -84,10 +96,54 @@ impl MiniGrafDb {
     /// Flush the WAL to disk. Throws on error.
     #[napi]
     pub fn checkpoint(&self) -> Result<()> {
-        self.inner
+        let guard = self
+            .inner
             .lock()
-            .map_err(|_| Error::new(Status::GenericFailure, "mutex poisoned"))?
+            .map_err(|_| Error::new(Status::GenericFailure, "mutex poisoned"))?;
+        guard
+            .as_ref()
+            .ok_or_else(|| Error::new(Status::GenericFailure, CLOSED_MSG))?
             .checkpoint()
             .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))
     }
+
+    /// Close the database, releasing its file lock immediately.
+    ///
+    /// Letting a `MiniGrafDb` go out of scope is **not** enough to release the
+    /// file. JavaScript has no deterministic destructor: the object merely
+    /// becomes unreachable, and the underlying handle lives until V8 garbage
+    /// collects it — arbitrarily later, or never before the process exits.
+    ///
+    /// That matters because minigraf permits only one live handle per file per
+    /// process (two would each cache their own page table and corrupt each
+    /// other), so opening the same path again throws until the first handle is
+    /// really gone. `close()` is the only way to make that happen on demand.
+    /// Every other binding has the same escape hatch: UniFFI (Python, Java,
+    /// Swift) exposes `destroy()`, and the C API exposes `minigraf_close`.
+    ///
+    /// Call `checkpoint()` first if you need to know the WAL was compacted;
+    /// closing does that too, but cannot report a failure.
+    ///
+    /// Idempotent — closing an already-closed database is a no-op. Every other
+    /// method throws afterwards.
+    ///
+    /// ```js
+    /// const db = new MiniGrafDb(path)
+    /// db.execute('(transact [[:bob :name "Bob"]])')
+    /// db.checkpoint()
+    /// db.close()
+    ///
+    /// const db2 = new MiniGrafDb(path) // fine: the first handle is gone
+    /// ```
+    #[napi]
+    pub fn close(&self) -> Result<()> {
+        let mut guard = self
+            .inner
+            .lock()
+            .map_err(|_| Error::new(Status::GenericFailure, "mutex poisoned"))?;
+        // Dropping the last Minigraf clone runs its Drop impl: a best-effort
+        // checkpoint, then release of the sidecar `.graph.lock`.
+        *guard = None;
+        Ok(())
+    }
 }

package/test/basic.test.mjs

@@ -41,9 +41,64 @@ test('file-backed roundtrip', async (t) => {
     const db = new MiniGrafDb(dbPath)
     db.execute('(transact [[:bob :name "Bob"]])')
     db.checkpoint()
+    // Required, not tidiness: leaving the block makes `db` unreachable but does
+    // not free the handle — V8 frees it whenever it next collects. minigraf
+    // allows one live handle per file per process, so without this the reopen
+    // below throws "Database is already open in this process".
+    db.close()
   }
 
   const db2 = new MiniGrafDb(dbPath)
   const qr = JSON.parse(db2.execute('(query [:find ?n :where [?e :name ?n]])'))
   assert.equal(qr.results[0][0], 'Bob')
+  db2.close()
+})
+
+test('reopening without close throws', async (t) => {
+  const os = await import('node:os')
+  const path = await import('node:path')
+  const fs = await import('node:fs')
+
+  const dbPath = path.default.join(
+    os.default.tmpdir(),
+    `minigraf_node_noclose_${Date.now()}.graph`,
+  )
+
+  const db = new MiniGrafDb(dbPath)
+  t.after(() => {
+    try { db.close() } catch {}
+    try { fs.default.unlinkSync(dbPath) } catch {}
+    try { fs.default.unlinkSync(dbPath + '.wal') } catch {}
+    try { fs.default.unlinkSync(dbPath + '.lock') } catch {}
+  })
+
+  // Two live handles would each cache their own page table and corrupt the
+  // file, so this must fail loudly rather than succeed.
+  assert.throws(
+    () => new MiniGrafDb(dbPath),
+    /already open in this process/,
+  )
+})
+
+test('close is idempotent and use-after-close throws', async (t) => {
+  const os = await import('node:os')
+  const path = await import('node:path')
+  const fs = await import('node:fs')
+
+  const dbPath = path.default.join(
+    os.default.tmpdir(),
+    `minigraf_node_closed_${Date.now()}.graph`,
+  )
+  t.after(() => {
+    try { fs.default.unlinkSync(dbPath) } catch {}
+    try { fs.default.unlinkSync(dbPath + '.wal') } catch {}
+  })
+
+  const db = new MiniGrafDb(dbPath)
+  db.execute('(transact [[:bob :name "Bob"]])')
+  db.close()
+  db.close() // idempotent
+
+  assert.throws(() => db.execute('(query [:find ?n :where [?e :name ?n]])'), /closed/)
+  assert.throws(() => db.checkpoint(), /closed/)
 })