Add demos into queryjson

Author: davesnx

Makefile

@@ -106,14 +106,75 @@ npm-install: ## Install npm dependencies
 .PHONY: init
 init: setup-githooks create-switch pin install npm-install ## Create a local dev enviroment
 
+DEMO_FILES = \
+	repl-demo \
+	cli-basic \
+	cli-advanced \
+	comparison \
+	jq-compat-demos/00-error-messages \
+	jq-compat-demos/01-stricter-null-handling \
+	jq-compat-demos/02-fn-vs-def \
+	jq-compat-demos/03-snake-case-naming \
+	jq-compat-demos/04-clearer-naming \
+	jq-compat-demos/05-group-by-behavior \
+	jq-compat-demos/06-keys-insertion-order \
+	jq-compat-demos/07-unique-insertion-order \
+	jq-compat-demos/08-infinite-generator \
+	jq-compat-demos/09-optional-access-functions \
+	jq-compat-demos/10-additional-features \
+	jq-compat-demos/all-demos
+
+
 .PHONY: demo
-demo: ## Generate demo from tape file (usage: make demo FILE=cli-basic)
+demo: demo-cast demo-gif ## Generate cast+gif demo (usage: make demo FILE=cli-basic)
+
+.PHONY: demo-cast
+demo-cast: ## Record demo cast (usage: make demo-cast FILE=cli-basic)
 	@if [ -z "$(FILE)" ]; then \
-		echo "Error: FILE is required. Usage: make demo FILE=cli-basic"; \
+		echo "Error: FILE is required. Usage: make demo FILE=repl-demo"; \
 		exit 1; \
 	fi
 	$(DUNE) install
-	vhs "docs/$(FILE).tape"
+	@if [ "$(FILE)" = "repl-demo" ]; then \
+		asciinema rec --overwrite --cols 140 --rows 48 -c "python3 docs/record-repl-demo.py" docs/repl-demo.cast; \
+	elif [ -f "docs/demo-scripts/$(FILE).sh" ]; then \
+		asciinema rec --overwrite --cols 140 --rows 48 -c "bash docs/demo-scripts/$(FILE).sh" "docs/$(FILE).cast"; \
+	else \
+		echo "Error: unknown demo '$(FILE)'. Expected docs/demo-scripts/$(FILE).sh"; \
+		exit 1; \
+	fi
+
+.PHONY: demo-gif
+demo-gif: ## Render demo gif from cast (usage: make demo-gif FILE=cli-basic)
+	@if [ -z "$(FILE)" ]; then \
+		echo "Error: FILE is required. Usage: make demo-gif FILE=repl-demo"; \
+		exit 1; \
+	fi
+	@if [ ! -f "docs/$(FILE).cast" ]; then \
+		echo "Error: docs/$(FILE).cast not found. Run: make demo-cast FILE=$(FILE)"; \
+		exit 1; \
+	fi
+	@if ! command -v agg >/dev/null 2>&1; then \
+		echo "Error: agg is required to render GIFs."; \
+		echo "Install it from: https://github.com/asciinema/agg"; \
+		exit 1; \
+	fi
+	agg "docs/$(FILE).cast" "docs/$(FILE).gif"
+
+.PHONY: demo-all-cast
+demo-all-cast: ## Record all demos as .cast files
+	@for demo in $(DEMO_FILES); do \
+		$(MAKE) demo-cast FILE=$$demo || exit 1; \
+	done
+
+.PHONY: demo-all-gif
+demo-all-gif: ## Render all demos as .gif files
+	@for demo in $(DEMO_FILES); do \
+		$(MAKE) demo-gif FILE=$$demo || exit 1; \
+	done
+
+.PHONY: demo-all
+demo-all: demo-all-cast demo-all-gif ## Record and render all demos
 
 .PHONY: bench
 bench: ## Run benchmarks

README.md

@@ -50,7 +50,14 @@ $ jq ".naem" <<< '{"name": "Alice", "age": 30}'
 null
 ```
 
-<video src="docs/repl-demo.mp4" autoplay loop muted playsinline></video>
+<img src="docs/repl-demo.gif" alt="query-json interactive REPL demo" />
+
+More demos:
+
+- [Basic CLI demo](./docs/cli-basic.gif)
+- [Advanced CLI demo](./docs/cli-advanced.gif)
+- [query-json vs jq demo](./docs/comparison.gif)
+- [jq compatibility demo bundle](./docs/jq-compat-demos/all-demos.gif)
 
 ### Portable
 

docs/JQ_COMPATIBILITY.md

@@ -461,37 +461,35 @@ query-json includes some functions not found in jq:
 
 ## Video Demos
 
-All the examples in this guide have corresponding VHS tape demos. You can find them in [`docs/jq-compat-demos/`](./jq-compat-demos/) and generate the videos using [VHS](https://github.com/charmbracelet/vhs).
+All the examples in this guide have corresponding asciinema demos. Cast recordings and GIFs are generated from scripts in [`docs/demo-scripts/jq-compat-demos/`](./demo-scripts/jq-compat-demos/).
 
 ### Available Demos
 
-| Demo | Description | Tape File |
-|------|-------------|-----------|
-| **Error Messages** | Helpful error messages with context and hints | [`00-error-messages.tape`](./jq-compat-demos/00-error-messages.tape) |
-| **Null Handling** | Stricter null handling catches bugs early | [`01-stricter-null-handling.tape`](./jq-compat-demos/01-stricter-null-handling.tape) |
-| **fn vs def** | `fn` keyword for user-defined functions | [`02-fn-vs-def.tape`](./jq-compat-demos/02-fn-vs-def.tape) |
-| **Snake_case** | Readable `snake_case` function names | [`03-snake-case-naming.tape`](./jq-compat-demos/03-snake-case-naming.tape) |
-| **Clearer Naming** | Self-explanatory function names | [`04-clearer-naming.tape`](./jq-compat-demos/04-clearer-naming.tape) |
-| **group_by** | Returns object instead of array of arrays | [`05-group-by-behavior.tape`](./jq-compat-demos/05-group-by-behavior.tape) |
-| **keys** | Preserves insertion order | [`06-keys-insertion-order.tape`](./jq-compat-demos/06-keys-insertion-order.tape) |
-| **unique** | Preserves insertion order | [`07-unique-insertion-order.tape`](./jq-compat-demos/07-unique-insertion-order.tape) |
-| **infinite** | Generator producing 0, 1, 2, ... | [`08-infinite-generator.tape`](./jq-compat-demos/08-infinite-generator.tape) |
-| **Optional Functions** | `?` works on function calls | [`09-optional-access-functions.tape`](./jq-compat-demos/09-optional-access-functions.tape) |
-| **Additional Features** | Features unique to query-json | [`10-additional-features.tape`](./jq-compat-demos/10-additional-features.tape) |
-| **All Demos** | Complete overview of all differences | [`all-demos.tape`](./jq-compat-demos/all-demos.tape) |
+| Demo | Description | Make `FILE` | Script | GIF | Cast |
+|------|-------------|-------------|--------|-----|------|
+| **Error Messages** | Helpful error messages with context and hints | `jq-compat-demos/00-error-messages` | [`00-error-messages.sh`](./demo-scripts/jq-compat-demos/00-error-messages.sh) | [`00-error-messages.gif`](./jq-compat-demos/00-error-messages.gif) | [`00-error-messages.cast`](./jq-compat-demos/00-error-messages.cast) |
+| **Null Handling** | Stricter null handling catches bugs early | `jq-compat-demos/01-stricter-null-handling` | [`01-stricter-null-handling.sh`](./demo-scripts/jq-compat-demos/01-stricter-null-handling.sh) | [`01-stricter-null-handling.gif`](./jq-compat-demos/01-stricter-null-handling.gif) | [`01-stricter-null-handling.cast`](./jq-compat-demos/01-stricter-null-handling.cast) |
+| **fn vs def** | `fn` keyword for user-defined functions | `jq-compat-demos/02-fn-vs-def` | [`02-fn-vs-def.sh`](./demo-scripts/jq-compat-demos/02-fn-vs-def.sh) | [`02-fn-vs-def.gif`](./jq-compat-demos/02-fn-vs-def.gif) | [`02-fn-vs-def.cast`](./jq-compat-demos/02-fn-vs-def.cast) |
+| **Snake_case** | Readable `snake_case` function names | `jq-compat-demos/03-snake-case-naming` | [`03-snake-case-naming.sh`](./demo-scripts/jq-compat-demos/03-snake-case-naming.sh) | [`03-snake-case-naming.gif`](./jq-compat-demos/03-snake-case-naming.gif) | [`03-snake-case-naming.cast`](./jq-compat-demos/03-snake-case-naming.cast) |
+| **Clearer Naming** | Self-explanatory function names | `jq-compat-demos/04-clearer-naming` | [`04-clearer-naming.sh`](./demo-scripts/jq-compat-demos/04-clearer-naming.sh) | [`04-clearer-naming.gif`](./jq-compat-demos/04-clearer-naming.gif) | [`04-clearer-naming.cast`](./jq-compat-demos/04-clearer-naming.cast) |
+| **group_by** | Returns object instead of array of arrays | `jq-compat-demos/05-group-by-behavior` | [`05-group-by-behavior.sh`](./demo-scripts/jq-compat-demos/05-group-by-behavior.sh) | [`05-group-by-behavior.gif`](./jq-compat-demos/05-group-by-behavior.gif) | [`05-group-by-behavior.cast`](./jq-compat-demos/05-group-by-behavior.cast) |
+| **keys** | Preserves insertion order | `jq-compat-demos/06-keys-insertion-order` | [`06-keys-insertion-order.sh`](./demo-scripts/jq-compat-demos/06-keys-insertion-order.sh) | [`06-keys-insertion-order.gif`](./jq-compat-demos/06-keys-insertion-order.gif) | [`06-keys-insertion-order.cast`](./jq-compat-demos/06-keys-insertion-order.cast) |
+| **unique** | Preserves insertion order | `jq-compat-demos/07-unique-insertion-order` | [`07-unique-insertion-order.sh`](./demo-scripts/jq-compat-demos/07-unique-insertion-order.sh) | [`07-unique-insertion-order.gif`](./jq-compat-demos/07-unique-insertion-order.gif) | [`07-unique-insertion-order.cast`](./jq-compat-demos/07-unique-insertion-order.cast) |
+| **infinite** | Generator producing 0, 1, 2, ... | `jq-compat-demos/08-infinite-generator` | [`08-infinite-generator.sh`](./demo-scripts/jq-compat-demos/08-infinite-generator.sh) | [`08-infinite-generator.gif`](./jq-compat-demos/08-infinite-generator.gif) | [`08-infinite-generator.cast`](./jq-compat-demos/08-infinite-generator.cast) |
+| **Optional Functions** | `?` works on function calls | `jq-compat-demos/09-optional-access-functions` | [`09-optional-access-functions.sh`](./demo-scripts/jq-compat-demos/09-optional-access-functions.sh) | [`09-optional-access-functions.gif`](./jq-compat-demos/09-optional-access-functions.gif) | [`09-optional-access-functions.cast`](./jq-compat-demos/09-optional-access-functions.cast) |
+| **Additional Features** | Features unique to query-json | `jq-compat-demos/10-additional-features` | [`10-additional-features.sh`](./demo-scripts/jq-compat-demos/10-additional-features.sh) | [`10-additional-features.gif`](./jq-compat-demos/10-additional-features.gif) | [`10-additional-features.cast`](./jq-compat-demos/10-additional-features.cast) |
+| **All Demos** | Complete overview of all differences | `jq-compat-demos/all-demos` | [`all-demos.sh`](./demo-scripts/jq-compat-demos/all-demos.sh) | [`all-demos.gif`](./jq-compat-demos/all-demos.gif) | [`all-demos.cast`](./jq-compat-demos/all-demos.cast) |
 
 ### Generating Videos
 
-To generate all demo videos:
+To generate all demo casts and GIFs:
 
 ```bash
 # Generate all demos
-for tape in docs/jq-compat-demos/*.tape; do
-  vhs "$tape"
-done
+make demo-all
 
 # Or generate a specific demo
-vhs docs/jq-compat-demos/all-demos.tape
+make demo FILE=jq-compat-demos/all-demos
 ```
 
-The generated `.mp4` files will be placed in `docs/jq-compat-demos/`.
+The generated `.cast` and `.gif` files are placed in `docs/jq-compat-demos/`.

docs/cli-advanced.cast

@@ -0,0 +1,10 @@
+{"version": 2, "width": 140, "height": 48, "timestamp": 1773233359, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}}
+[0.005387, "o", "\r\n# query-json advanced filters\r\n"]
+[0.806459, "o", "\r\n$ _opam/bin/query-json '.second.store.books | map(.price) | add' test/mock.json\r\n"]
+[0.811853, "o", "\r\nJSON parse error: Line 1, bytes 0-14:\r\nInvalid token 'test/mock.json'\r\n\r\n"]
+[1.813727, "o", "\r\n$ _opam/bin/query-json 'fn expensive: .price > 20; .second.store.books | filter(expensive)' test/mock.json\r\n"]
+[1.819203, "o", "\r\nJSON parse error: Line 1, bytes 0-14:\r\nInvalid token 'test/mock.json'\r\n\r\n"]
+[2.820971, "o", "\r\n$ _opam/bin/query-json '.second.store.books | group_by(.category) | map_values(length)' test/mock.json\r\n"]
+[2.826431, "o", "\r\nJSON parse error: Line 1, bytes 0-14:\r\nInvalid token 'test/mock.json'\r\n\r\n"]
+[3.828399, "o", "\r\n$ _opam/bin/query-json '.second.store.books | map({title, price_with_tax: (.price * 1.21)})' test/mock.json\r\n"]
+[3.833888, "o", "\r\nJSON parse error: Line 1, bytes 0-14:\r\nInvalid token 'test/mock.json'\r\n\r\n"]

docs/cli-advanced.gif

@@ -0,0 +1,10 @@
+{"version": 2, "width": 140, "height": 48, "timestamp": 1773233356, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}}
+[0.005209, "o", "\r\n# query-json basic CLI\r\n"]
+[0.80653, "o", "\r\n$ _opam/bin/query-json --version\r\n"]
+[0.812294, "o", "1.0.0~beta-1\r\n"]
+[1.814421, "o", "\r\n$ _opam/bin/query-json '.second.store.books[0].title' test/mock.json\r\n"]
+[1.819899, "o", "\r\nJSON parse error: Line 1, bytes 0-14:\r\nInvalid token 'test/mock.json'\r\n\r\n"]
+[2.821833, "o", "\r\n$ cat test/mock.json | _opam/bin/query-json '.second.store.books | length'\r\n"]
+[2.822937, "o", "cat: test/mock.json"]
+[2.823025, "o", ": No such file or directory\r\n"]
+[2.827757, "o", "\r\nJSON parse error: Blank input data\r\n\r\n"]

docs/cli-basic.cast

@@ -0,0 +1,14 @@
+{"version": 2, "width": 140, "height": 48, "timestamp": 1773233364, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}}
+[0.006008, "o", "\r\n# jq vs query-json\r\n"]
+[0.807216, "o", "\r\n$ echo '\"hello\"' | jq 'ascii_upcase'\r\n"]
+[0.81008, "o", "\u001b[0;32m\"HELLO\"\u001b[0m\r\n"]
+[1.81237, "o", "\r\n$ echo '\"hello\"' | _opam/bin/query-json 'to_uppercase'\r\n"]
+[1.819039, "o", "\u001b[32m\"HELLO\"\u001b[39m\u001b[0m\r\n"]
+[2.821299, "o", "\r\n$ echo '42' | jq 'tostring'\r\n"]
+[2.823731, "o", "\u001b[0;32m\"42\"\u001b[0m\r\n"]
+[3.825361, "o", "\r\n$ echo '42' | _opam/bin/query-json 'to_string'\r\n"]
+[3.831415, "o", "\u001b[32m\"42\"\u001b[39m\u001b[0m\r\n"]
+[4.833678, "o", "\r\n$ echo '[1,2,3]' | jq 'def double: . * 2; map(double)'\r\n"]
+[4.835936, "o", "\u001b[1;39m[\r\n  \u001b[0;39m2\u001b[0m\u001b[1;39m,\r\n  \u001b[0;39m4\u001b[0m\u001b[1;39m,\r\n  \u001b[0;39m6\u001b[0m\u001b[1;39m\r\n\u001b[1;39m]\u001b[0m\r\n"]
+[5.837576, "o", "\r\n$ echo '[1,2,3]' | _opam/bin/query-json 'fn double: . * 2; map(double)'\r\n"]
+[5.843697, "o", "[ \u001b[32m2\u001b[39m\u001b[0m, \u001b[32m4\u001b[39m\u001b[0m, \u001b[32m6\u001b[39m\u001b[0m ]\r\n"]

docs/cli-basic.gif

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/common.sh"
+
+section "query-json advanced filters"
+run_cmd "${QUERY_JSON_BIN} '.second.store.books | map(.price) | add' test/mock.json"
+run_cmd "${QUERY_JSON_BIN} 'fn expensive: .price > 20; .second.store.books | filter(expensive)' test/mock.json"
+run_cmd "${QUERY_JSON_BIN} '.second.store.books | group_by(.category) | map_values(length)' test/mock.json"
+run_cmd "${QUERY_JSON_BIN} '.second.store.books | map({title, price_with_tax: (.price * 1.21)})' test/mock.json"