fixes @gnata -> @gnata-sqlite

rbbydotdev · rbbydotdev · commit 2e2a32d71fd3 · 2026-03-31T13:38:36.000+07:00
updates markdown
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,23 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+**What happened?**
+
+**Expected behavior**
+
+**Reproduction**
+
+Minimal JSONata expression and input that triggers the bug:
+
+```
+Expression:
+Input:
+```
+
+**Environment**
+- OS:
+- Go version:
+- gnata-sqlite version/commit:
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest a feature
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+**Proposed solution**
+
+**Alternatives considered**
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,15 @@
+## What
+
+Brief description.
+
+## Why
+
+Context and motivation.
+
+## How
+
+Implementation approach.
+
+## Test plan
+
+How this was tested.
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,5 @@ skills-lock.json
 .DS_Store
 node_modules/
 editor/codemirror/dist/
+lsp-wasm_exec.js
+wasm_exec.js
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,61 @@
+# Contributing
+
+## Development Setup
+
+```bash
+git clone git@github.com:rbbydotdev/gnata-sqlite.git
+cd gnata-sqlite
+go build ./...
+go test -race ./...
+```
+
+### Optional: SQLite Extension
+
+Requires CGo:
+
+```bash
+go build -buildmode=c-shared -o gnata_jsonata.dylib ./sqlite
+```
+
+### Optional: WASM LSP
+
+Requires [TinyGo](https://tinygo.org):
+
+```bash
+tinygo build -o gnata-lsp.wasm -target wasm ./editor
+```
+
+### Optional: CodeMirror Package
+
+```bash
+cd editor/codemirror && npm install && npm run build
+```
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| Root `.go` files | Core JSONata 2.x engine (parser, evaluator, streaming) |
+| `functions/` | 50+ stdlib function implementations |
+| `internal/` | Lexer, parser, evaluator, query planner internals |
+| `sqlite/` | Loadable SQLite extension (CGo) |
+| `editor/` | CodeMirror 6 language support + WASM LSP |
+| `wasm/` | WASM build entry point |
+| `testdata/` | JSONata conformance test suite (1,778 cases) |
+
+## Making Changes
+
+1. Fork the repo
+2. Create a branch (`git checkout -b feat/my-feature`)
+3. Make changes and add tests
+4. Run `go test -race ./...`
+5. Run `golangci-lint run` if you have it installed
+6. Commit with a descriptive message
+7. Open a PR
+
+## Code Style
+
+- Follow standard Go conventions (`gofmt`, `go vet`)
+- Linting config is in `.golangci.yaml`
+- Tests live alongside the code they test (`*_test.go`)
+- Conformance tests use JSON datasets in `testdata/`
diff --git a/README.md b/README.md
@@ -1,27 +1,21 @@
 # gnata-sqlite
 
-A full [JSONata 2.x](https://jsonata.org) implementation in Go with SQLite integration, editor tooling, and query optimization.
+Full [JSONata 2.x](https://jsonata.org) implementation in Go — with a loadable SQLite extension, streaming query optimizer, and 85KB WASM LSP.
 
-## Fork Notice
-
-Forked from [RecoLabs/gnata](https://github.com/RecoLabs/gnata), which provides a production-grade JSONata 2.x engine in pure Go. This project extends the core engine with a loadable SQLite extension, a CodeMirror 6 editor with TinyGo WASM LSP, and a query planner that decomposes JSONata into streaming SQL-friendly operations.
-
-## Packages
+[![CI](https://github.com/rbbydotdev/gnata-sqlite/actions/workflows/ci.yml/badge.svg)](https://github.com/rbbydotdev/gnata-sqlite/actions/workflows/ci.yml)
+[![Go Reference](https://pkg.go.dev/badge/github.com/rbbydotdev/gnata-sqlite.svg)](https://pkg.go.dev/github.com/rbbydotdev/gnata-sqlite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Go 1.25](https://img.shields.io/badge/Go-1.25-00ADD8.svg)](https://go.dev)
 
-| Package | Description | Docs |
-|---------|-------------|------|
-| `gnata` (root) | Core JSONata 2.x engine -- full spec, two-tier eval, streaming | [Core features below](#core-engine) |
-| `sqlite/` | SQLite extension -- `jsonata()`, `jsonata_query()`, `jsonata_each()`, mutations | [sqlite/README.md](sqlite/README.md) |
-| `editor/` | CodeMirror 6 language support + TinyGo WASM LSP | [editor/README.md](editor/README.md) |
+## Highlights
 
-## Core Engine
+- **5M+ eval ops/sec** — two-tier evaluator with GJSON fast path hitting 10M+ ops/sec for simple paths
+- **Full JSONata 2.x spec** — paths, wildcards, lambdas, closures, higher-order functions, 50+ stdlib functions. 1,778 conformance tests, 0 failures
+- **SQLite extension** — `jsonata()`, `jsonata_query()`, `jsonata_each()` as loadable functions with a built-in query planner
+- **85KB WASM LSP** — TinyGo-compiled language server for in-browser diagnostics and autocomplete
+- **Lock-free streaming** — `StreamEvaluator` with schema-keyed plan caching for high-throughput batch workloads
 
-The root package implements the full JSONata 2.x specification in pure Go:
-
-- **Full JSONata 2.x** -- paths, wildcards, lambdas, closures, higher-order functions, 50+ stdlib functions
-- **Two-tier evaluation** -- GJSON fast path for simple expressions, full AST interpreter for complex ones
-- **Lock-free `StreamEvaluator`** -- batch evaluation with schema-keyed plan caching for high-throughput workloads
-- **1,778 test cases** from the official jsonata-js conformance suite (0 failures, 0 skips)
+## Quick Start
 
 ```go
 import "github.com/rbbydotdev/gnata-sqlite"
@@ -33,8 +27,6 @@ fmt.Println(result) // [34.45 21.67]
 
 ## SQLite Extension
 
-A loadable SQLite extension that brings JSONata expressions into SQL queries. Query, transform, and aggregate JSON data directly from SQLite.
-
 ```sql
 .load ./gnata_jsonata sqlite3_jsonata_init
 
@@ -45,27 +37,43 @@ SELECT jsonata_query('$sum(amount)', data) FROM orders;
 -- 4250
 ```
 
-Key functions:
+| Function | Description |
+|----------|-------------|
+| `jsonata(json, expr)` | Evaluate expression against JSON |
+| `jsonata_query(expr, json)` | Expression-first argument order |
+| `jsonata_each(expr, json)` | Expand results into rows (table-valued) |
+| `jsonata_set(json, path, val)` | Set a value at a path |
+| `jsonata_delete(json, path)` | Delete a value at a path |
+
+See [sqlite/README.md](sqlite/README.md) for full docs. Query optimization details in [sqlite/OPTIMIZATION.md](sqlite/OPTIMIZATION.md).
 
-- `jsonata(json, expr)` -- evaluate a JSONata expression against a JSON value
-- `jsonata_query(expr, json)` -- same operation, expression-first argument order
-- `jsonata_each(expr, json)` -- expand results into rows (table-valued function)
-- `jsonata_set(json, path, value)` -- set a value at a path
-- `jsonata_delete(json, path)` -- delete a value at a path
+## Benchmarks
 
-The built-in query planner decomposes JSONata expressions into streaming SQL-friendly operations for better performance on large datasets. See [sqlite/OPTIMIZATION.md](sqlite/OPTIMIZATION.md) and [sqlite/BLOGPOST.md](sqlite/BLOGPOST.md) for details.
+![Eval Performance](assets/benchmark-eval.png)
 
-See [sqlite/README.md](sqlite/README.md) for full documentation.
+![GJSON Fast Path](assets/benchmark-fastpath.png)
 
-## Editor / LSP
+<details>
+<summary>Raw numbers (Apple M1)</summary>
 
-CodeMirror 6 language support and LSP server for JSONata, powered by gnata's parser.
+| Benchmark | ops/sec | ns/op | allocs/op |
+|-----------|---------|-------|-----------|
+| Eval `Account.Name` | **5,037,783** | 198 | 4 |
+| Eval `Order.Product.SKU` | 2,160,554 | 463 | 10 |
+| Eval `Product[Price>50].SKU` | 895,255 | 1,117 | 26 |
+| Eval `$sum(Product.*)` | 654,006 | 1,529 | 44 |
+| EvalBytes `Account.Name` | **10,280,965** | 97 | 2 |
+| Compile `Account.Name` | 1,757,469 | 569 | 13 |
 
-- **TinyGo WASM LSP** -- 182 KB module (85 KB gzipped) for in-browser diagnostics and autocomplete
-- **CodeMirror 6 npm package** -- `@gnata/codemirror` with syntax highlighting, error diagnostics, context-aware autocomplete, and hover documentation
-- **Native LSP server** -- stdio JSON-RPC for VS Code, Neovim, and other editors
+</details>
 
-See [editor/README.md](editor/README.md) for full documentation.
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `gnata` (root) | Core JSONata 2.x engine — full spec, two-tier eval, streaming |
+| [`sqlite/`](sqlite/README.md) | SQLite extension — loadable functions, query planner, mutations |
+| [`editor/`](editor/README.md) | CodeMirror 6 language support + TinyGo WASM LSP |
 
 ## Building
 
@@ -85,8 +93,16 @@ cd editor/codemirror && npm install && npm run build
 
 ## Playground
 
-Open `playground.html` for interactive testing of JSONata expressions and the SQLite extension in the browser.
+Open `playground.html` or visit the [live playground](https://rbbydotdev.github.io/gnata-sqlite/) for interactive testing of JSONata expressions and the SQLite extension.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## Fork Notice
+
+Forked from [RecoLabs/gnata](https://github.com/RecoLabs/gnata), which provides a production-grade JSONata 2.x engine in pure Go. This project extends the core engine with a SQLite extension, editor tooling, and query optimizer.
 
 ## License
 
-MIT. Based on [RecoLabs/gnata](https://github.com/RecoLabs/gnata).
+[MIT](LICENSE)
diff --git a/assets/benchmark-eval.png b/assets/benchmark-eval.png
diff --git a/assets/benchmark-fastpath.png b/assets/benchmark-fastpath.png
diff --git a/editor/README.md b/editor/README.md
@@ -13,7 +13,7 @@ Two delivery modes from the same codebase:
 
 ```typescript
 import { EditorView, basicSetup } from "codemirror"
-import { jsonataFull, initWasm } from "@gnata/codemirror"
+import { jsonataFull, initWasm } from "@gnata-sqlite/codemirror"
 
 // Load the WASM module (182 KB, 85 KB gzipped).
 await initWasm("/gnata-lsp.wasm", "/lsp-wasm_exec.js")
@@ -169,7 +169,7 @@ Pass the schema when the LSP client initializes:
 Syntax highlighting only. No WASM required.
 
 ```typescript
-import { jsonata } from "@gnata/codemirror"
+import { jsonata } from "@gnata-sqlite/codemirror"
 // extensions: [basicSetup, jsonata()]
 ```
 
@@ -178,7 +178,7 @@ import { jsonata } from "@gnata/codemirror"
 Full support: syntax highlighting + WASM linter + autocomplete.
 
 ```typescript
-import { jsonataFull } from "@gnata/codemirror"
+import { jsonataFull } from "@gnata-sqlite/codemirror"
 // extensions: [basicSetup, jsonataFull({ schema: '...' })]
 ```
 
@@ -254,7 +254,7 @@ npm run build
 ```tsx
 import { useEffect, useRef } from "react"
 import { EditorView, basicSetup } from "codemirror"
-import { jsonataFull, initWasm } from "@gnata/codemirror"
+import { jsonataFull, initWasm } from "@gnata-sqlite/codemirror"
 
 export function JsonataEditor({ schema }: { schema: string }) {
   const ref = useRef<HTMLDivElement>(null)
@@ -278,7 +278,7 @@ export function JsonataEditor({ schema }: { schema: string }) {
 <div id="editor"></div>
 <script type="module">
   import { EditorView, basicSetup } from "codemirror"
-  import { jsonata, initWasm, jsonataLint } from "@gnata/codemirror"
+  import { jsonata, initWasm, jsonataLint } from "@gnata-sqlite/codemirror"
 
   // Syntax highlighting works immediately.
   const view = new EditorView({
@@ -303,7 +303,7 @@ editor/
   funcinfo.go            # Built-in function catalog (70+ functions)
   schema.go              # Schema JSON parser (no encoding/json)
   marshal.go             # Reflect-free AST → JSON serializer
-  codemirror/            # npm package (@gnata/codemirror)
+  codemirror/            # npm package (@gnata-sqlite/codemirror)
     src/
       jsonata.grammar    # Lezer grammar for syntax highlighting
       highlight.js       # CodeMirror style tag mappings
diff --git a/editor/codemirror/README.md b/editor/codemirror/README.md
@@ -1,4 +1,4 @@
-# @gnata/codemirror
+# @gnata-sqlite/codemirror
 
 CodeMirror 6 language support for [JSONata](https://jsonata.org) expressions — syntax highlighting, error diagnostics, autocomplete, and hover documentation, powered by a 85KB WASM module.
 
@@ -12,7 +12,7 @@ CodeMirror 6 language support for [JSONata](https://jsonata.org) expressions —
 ## Install
 
 ```bash
-npm install @gnata/codemirror
+npm install @gnata-sqlite/codemirror
 ```
 
 You also need the WASM files served from your app:
@@ -23,7 +23,7 @@ You also need the WASM files served from your app:
 
 ```ts
 import { EditorView, basicSetup } from "codemirror"
-import { initWasm, jsonataFull } from "@gnata/codemirror"
+import { initWasm, jsonataFull } from "@gnata-sqlite/codemirror"
 
 // 1. Load WASM (once, at startup)
 await initWasm("/gnata-lsp.wasm", "/lsp-wasm_exec.js")
@@ -73,7 +73,7 @@ import {
   jsonataLint,       // error diagnostics
   jsonataCompletion, // autocomplete
   jsonataHover,      // hover tooltips
-} from "@gnata/codemirror"
+} from "@gnata-sqlite/codemirror"
 
 extensions: [
   jsonata(),
@@ -357,7 +357,7 @@ A complete working example using ESM imports (no build step):
 │   Your App (browser)    │     │    gnata-lsp.wasm (85KB)  │
 │                         │     │    TinyGo WASM module     │
 │  CodeMirror Editor      │────▶│                          │
-│  + @gnata/codemirror    │     │  _gnataDiagnostics(expr) │
+│  + @gnata-sqlite/codemirror    │     │  _gnataDiagnostics(expr) │
 │                         │◀────│  _gnataCompletions(...)   │
 │                         │     │  _gnataHover(expr, pos)   │
 └─────────────────────────┘     └──────────────────────────┘
diff --git a/editor/codemirror/package-lock.json b/editor/codemirror/package-lock.json
diff --git a/editor/codemirror/package.json b/editor/codemirror/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@gnata/codemirror",
+  "name": "@gnata-sqlite/codemirror",
   "version": "0.1.0",
   "description": "CodeMirror 6 language support for JSONata — syntax highlighting, linting, and autocomplete",
   "type": "module",
