chore: add json vs jsonb demo scripts

[RogerHYang]

PostgreSQL JSON vs JSONB Demonstration

Overview

This PR adds a comprehensive demonstration project that showcases the key differences between PostgreSQL's JSON and JSONB data types. The demo includes practical examples, performance benchmarks, and best practices for choosing between JSON and JSONB in different scenarios.

Key Comparison Example

Here's a concrete example demonstrating the key ordering difference:

Original input order: ['QVZZCJFR', 'DAUFW', 'DXRMYF', 'SEETRJBUU', ...]

JSON output: {                | JSONB output: {
  "QVZZCJFR": 8,              |   "B": 1,
  "DAUFW": 5,                 |   "XT": 2,
  "DXRMYF": 6,                |   "RHD": 3,
  "SEETRJBUU": 9,             |   "YPSE": 4,
  "YPSE": 4,                  |   "DAUFW": 5,
  "DEGAZFI": 7,               |   "DXRMYF": 6,
  "XT": 2,                    |   "DEGAZFI": 7,
  "RHD": 3,                   |   "QVZZCJFR": 8,
  "B": 1,                     |   "SEETRJBUU": 9,
  "JCXSRJOEXE": 10            |   "JCXSRJOEXE": 10
}                             | }

This difference is crucial for applications that:

• Need to maintain exact document structure
• Rely on key order for processing
• Store configuration files
• Handle legacy systems with order-dependent JSON

Key Findings

1. Key Ordering

• JSON: Preserves exact key order as provided in input
• JSONB: Stores keys sorted by length
• Impact: Critical for applications requiring exact document format preservation

2. Performance Characteristics

• Insert Performance:
  • JSON is faster for inserts (no preprocessing required)
  • JSONB requires additional processing (validation and binary conversion)
• Query Performance:
  • JSONB is significantly faster for queries
  • GIN indexes on JSONB can improve query performance by 10x or more
  • JSON does not support indexing

3. Storage Efficiency

• JSONB typically uses less storage space
• JSONB's binary format is more efficient for processing
• Storage savings vary based on data structure and content

4. Query Capabilities

• JSONB-exclusive Operators:
  • Containment (@>)
  • Existence (?)
  • Path exists (?|)
• Error Prevention: Attempting to use JSONB operators with JSON raises clear errors

When to Use Each Type

Use JSON when:

• Exact document format preservation is required
• Insert performance is critical
• Data is write-heavy with minimal querying
• Input validation is more important than query performance

Use JSONB when:

• Query performance is critical
• Indexing capabilities are needed
• Storage space is a concern
• Complex JSON operations are required
• Key order preservation is not required

Technical Details

Key Ordering Demo

• Demonstrates how JSON preserves exact key order while JSONB sorts keys lexicographically
• Shows practical implications for data storage and retrieval

Performance Comparison

• Benchmarks insert performance
• Measures query performance with and without indexes
• Demonstrates JSONB-specific operator performance
• Shows storage size differences

Query Capabilities

• Showcases JSONB-specific operators (@>, ?, ?|)
• Demonstrates error cases when using JSONB operators with JSON
• Provides practical examples of complex JSON queries

Implementation Notes

• Uses TypeScript for type safety and better developer experience
• Implements a flexible database service that works with both PGlite and PostgreSQL
• Includes comprehensive type definitions for database models
• Follows modern ES modules and TypeScript best practices

Usage

The demo can be run using the following commands:

pnpm run compare      # Key order comparison
pnpm run performance  # Performance benchmarks
pnpm run query        # Query capabilities examples

Benefits

• Helps developers understand when to use JSON vs JSONB
• Provides practical examples for common use cases
• Demonstrates performance implications of data type choices
• Serves as a reference for PostgreSQL JSON operations

Testing

• All examples are self-contained and can be run independently
• Works with both PGlite (in-memory) and PostgreSQL
• Includes error handling and edge cases

Documentation

The code includes extensive inline documentation explaining:

• Key differences between JSON and JSONB
• Performance implications
• Best practices for choosing between data types
• Common use cases and recommendations