frogql 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -8,6 +8,35 @@ Released in lock-step with the [PyPI `frogql` package](https://pypi.org/project/
 
 ## [Unreleased]
 
+### Documentation
+
+- README: expanded the "Insert, modify, persist" section into "Incremental writes" with explicit upsert and delete-by-id snippets, and a notes block covering auto-commit, LTJ cache invalidation per mutation, per-statement transaction granularity, no `MERGE`, no multi-DML chains, and `importJson` not being incremental.
+- README: corrected the `EdgeRef.props` paragraph — props is always populated since `0.2.3`, not just on top-level `RETURN e`.
+
+## [0.2.3] — 2026-05-13
+
+### Added
+
+- Parser accepts `elementPropertySpecification` without `isLabelExpression` per ISO/IEC 39075:2024 §16. Now valid: `({k: v})`, `(x {k: v})`, `-[{k: v}]->`, `-[e {k: v}]->`. Previously these were rejected with `expected path pattern, got LBrace`; the colonised forms (`(:Label {k: v})`, `(: {k: v})`) already worked and behave identically.
+
+## [0.2.2] — 2026-05-13
+
+### Fixed
+
+- Edges expose `props` symmetrically with nodes — both via `RETURN e` and inside `_paths`. `EdgeRef.props` in `index.d.ts` is no longer optional. Pre-`0.2.2` versions silently dropped edge properties in both code paths despite the `EdgeRef` doc-comment claiming `RETURN e` would include them.
+
+## [0.2.1] — 2026-05-12
+
+### Changed
+
+- Re-release of `0.2.0` after the lock-step PyPI + npm pipeline reached steady state; no surface or on-disk format changes.
+
+## [0.2.0] — 2026-05-12
+
+### Added
+
+- First stable release. Surface, on-disk format, and the multi-package npm publish flow validated end-to-end through the `-rc.x` series.
+
 ## [0.2.0-rc.3] — 2026-05-12
 
 ### Fixed

package/README.md

@@ -97,7 +97,7 @@ import type {
 | `SHOW INDEXES` | `IndexSummary[]` |
 | `INSERT / SET / REMOVE / DELETE / DETACH DELETE` | `DmCounters` |
 
-Node and edge references inside row values use `NodeRef` / `EdgeRef`. The `props` field on `EdgeRef` is optional: present when returned via `RETURN e` at the top level, omitted in path-internal context to keep payloads small.
+Node and edge references inside row values use `NodeRef` / `EdgeRef`. Both shapes are symmetric — `kind`, `id`, `labels`, and `props` are always populated, whether the element arrives via `RETURN x` at the top level or inside a `_paths` entry. (Pre-`0.2.3` versions omitted `props` on edges in `_paths`; that gap is closed.)
 
 ## Examples
 
@@ -144,21 +144,65 @@ const rows = conn.execute(
 
 Left-outer join with bind-pushdown: per outer row, pin shared variables and pin-execute the inner. SQLite-style nested-loop. ~93× speedup vs the global-evaluate-and-join baseline on LDBC IS5.
 
-### Insert, modify, persist
+### Incremental writes (insert / upsert / delete)
+
+The full ISO §13 DML surface is reachable through `execute()` — there is no dedicated `connection.insert()` / `connection.delete()` method, the same way SQLite doesn't have one. Writes go in as GQL statements.
 
 ```ts
 import type { DmCounters } from "frogql";
 
-const a = conn.execute("INSERT (:Person {name: 'Alice', age: 30})") as DmCounters;
+// Insert.
+const a = conn.execute("INSERT (:Person {id: 'u-42', name: 'Alice', age: 30})") as DmCounters;
 console.log(a.nodesInserted); // 1
 
-conn.execute("MATCH (p:Person {name: 'Alice'}) SET p.age = 31");
-conn.execute("MATCH (p:Person {name: 'Alice'}) REMOVE p.age");
+// Update a property.
+conn.execute("MATCH (p:Person {id: 'u-42'}) SET p.age = 31");
+
+// Remove a property without dropping the node.
+conn.execute("MATCH (p:Person {id: 'u-42'}) REMOVE p.age");
 
-// Until you save(), mutations live in the in-memory overlay only.
+// Delete by id. DETACH first removes incident edges; NODETACH errors out
+// if the node still has neighbours.
+conn.execute("MATCH (p:Person {id: 'u-42'}) DETACH DELETE p");
+
+// Mutations live in an in-memory overlay until you call save().
 conn.save();
 ```
 
+#### Upsert pattern
+
+There is no `MERGE` yet (deferred per the ISO §13 MVP). Upsert is a two-step probe + branch:
+
+```ts
+function upsertPerson(conn: Connection, id: string, name: string) {
+  const hits = conn.execute(
+    `MATCH (p:Person {id: '${id}'}) RETURN p.id AS id LIMIT 1`,
+    1
+  ) as Array<{ id: string }>;
+  if (hits.length === 0) {
+    conn.execute(`INSERT (:Person {id: '${id}', name: '${name}'})`);
+  } else {
+    conn.execute(`MATCH (p:Person {id: '${id}'}) SET p.name = '${name}'`);
+  }
+}
+```
+
+A unique secondary index on `(Person, id)` makes the probe a point lookup:
+
+```ts
+conn.execute("CREATE INDEX ON :Person(id) USING HASH");
+```
+
+`execute()` takes a raw query string — there is no parameter-binding API. **Escape user input yourself** (`String#replace(/'/g, "\\'")` at minimum) or you'll have a query-injection vector.
+
+#### Operational notes for sync / streaming workloads
+
+- **Auto-commit is off.** Mutations stay in the RAM overlay until `conn.save()` writes a fresh `.gdb` atomically. A crashed process loses the unsaved overlay. Batch writes and save on a cadence (every N statements / every T seconds) rather than per-mutation.
+- **LTJ cache invalidation per mutation.** Each successful DML drops the cached six-ordering TripleIndex; the next read rebuilds it (~670 ms on an LDBC SF0.1-shaped graph). Tight write-read loops pay this per mutation. If your workload is write-heavy with occasional reads, that's fine; if it interleaves writes and reads, batch reads after a batch of writes.
+- **Transactions are per-statement.** A failed statement rolls back its own overlay delta. There's no multi-statement transaction boundary yet (deferred until WAL).
+- **No `MERGE`, no multi-DML chains** (`MATCH … INSERT … SET …` in one statement). One DML op per `execute()` call.
+- **`importJson` is not incremental.** It builds a fresh `.gdb` from scratch and overwrites the destination. Use `execute("INSERT …")` against an open `Connection` for incremental ingest.
+
 ### Schema introspection
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frogql",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "froGQL — embedded GQL graph database with ISO GQL path patterns (Rust core, Node.js bindings via napi-rs)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -65,10 +65,10 @@
     "provenance": true
   },
   "optionalDependencies": {
-    "frogql-darwin-x64": "0.2.3",
-    "frogql-darwin-arm64": "0.2.3",
-    "frogql-linux-x64-gnu": "0.2.3",
-    "frogql-linux-arm64-gnu": "0.2.3",
-    "frogql-win32-x64-msvc": "0.2.3"
+    "frogql-darwin-x64": "0.2.5",
+    "frogql-darwin-arm64": "0.2.5",
+    "frogql-linux-x64-gnu": "0.2.5",
+    "frogql-linux-arm64-gnu": "0.2.5",
+    "frogql-win32-x64-msvc": "0.2.5"
   }
 }