Add JSON optimization plan for webhooks/objects data files

Author: ericsciple

json-optimization-plan.md

@@ -0,0 +1,147 @@
+# JSON Optimization Plan for webhooks.json and objects.json
+
+## Current State
+
+| File | Source Size | Minified Size |
+|------|-------------|---------------|
+| webhooks.json | 828 KB | 265 KB |
+| objects.json | 476 KB | 199 KB |
+| **Total** | **1,304 KB** | **464 KB** |
+
+---
+
+## Optimization Approaches
+
+### 1. Short Property Names (~80 KB savings, ~17% reduction)
+
+Replace verbose property names with single-character keys in the minified output.
+
+| Property | Current | Short | Occurrences | Savings |
+|----------|---------|-------|-------------|---------|
+| `name` | 4 chars | `n` | 15,507 | 46 KB |
+| `description` | 11 chars | `d` | 1,716 | 17 KB |
+| `childParamsGroups` | 17 chars | `c` | 949 | 15 KB |
+| `bodyParameters` | 14 chars | `b` | 141 | 2 KB |
+| | | | **Total** | **~80 KB** |
+
+**Result: 464 KB → ~384 KB**
+
+**Complexity:** Low - just rename keys when generating minified version
+
+---
+
+### 2. Array-Based Structure (~79 KB savings, ~17% reduction)
+
+Replace objects with positional arrays to eliminate all property name overhead.
+
+**Current format:**
+```json
+{"name":"url","description":"The URL"}
+```
+
+**Array format:**
+```json
+["url","The URL"]
+```
+
+Position: `[0]=name, [1]=description, [2]=childParamsGroups`
+
+| Object Type | Count | Savings per Object | Total Savings |
+|-------------|-------|-------------------|---------------|
+| name only | 5,459 | 10 bytes | 53 KB |
+| name + description | 603 | 24 bytes | 14 KB |
+| name + children | 303 | 25 bytes | 7 KB |
+| name + desc + children | 98 | 40 bytes | 4 KB |
+| | | **Total** | **~79 KB** |
+
+**Result: 464 KB → ~385 KB** (or ~305 KB combined with approach 1)
+
+**Complexity:** Medium - requires updating reader code to handle array format
+
+---
+
+### 3. String Interning for Values (~40 KB savings, ~9% reduction)
+
+Create a string table for frequently repeated values and reference by index.
+
+**Top repeated values in objects.json:**
+
+| Value | Occurrences | Bytes per occurrence | Total overhead |
+|-------|-------------|---------------------|----------------|
+| `url` | 256 | 3 → 1-2 | 0.5 KB |
+| `id` | 250 | 2 → 1-2 | minimal |
+| `node_id` | 244 | 7 → 1-2 | 1.2 KB |
+| `html_url` | 210 | 8 → 1-2 | 1.3 KB |
+| `name` | 208 | 4 → 1-2 | 0.4 KB |
+| ... and 418 more unique values | | | |
+
+**Format:**
+```json
+{
+  "strings": ["url", "id", "node_id", "html_url", ...],
+  "data": [[0], [1, "Unique ID"], ...]  // reference by index
+}
+```
+
+**Estimated savings:** ~40 KB
+
+**Complexity:** High - requires string table lookup at runtime
+
+---
+
+### 4. Deduplicate Identical Subtrees (~30-50 KB savings, ~7-11% reduction)
+
+Many objects have identical `childParamsGroups` structures. Reference them once.
+
+Example: The "user" object structure appears ~122 times with identical fields.
+
+**Complexity:** Medium-High - requires structural hashing and reference resolution
+
+---
+
+## Recommended Implementation Order
+
+| Phase | Approach | Savings | Cumulative Size | Complexity |
+|-------|----------|---------|-----------------|------------|
+| 1 | Short property names | 80 KB | 384 KB | Low |
+| 2 | Array-based structure | 79 KB | 305 KB | Medium |
+| 3 | String interning | 40 KB | 265 KB | High |
+| 4 | Subtree deduplication | 30-50 KB | 220-235 KB | High |
+
+**Phase 1 alone gets you 17% reduction with minimal code changes.**
+
+**Phases 1+2 combined get you ~34% reduction (464 KB → 305 KB).**
+
+---
+
+## Implementation Notes
+
+### Phase 1: Short Property Names
+
+Update `minify-json.js` or create a transform in `update-webhooks` script:
+
+```javascript
+function shortenKeys(obj) {
+  return {
+    n: obj.name,
+    d: obj.description,
+    c: obj.childParamsGroups?.map(shortenKeys),
+    b: obj.bodyParameters,
+    a: obj.action
+  };
+}
+```
+
+Update consumers to use short keys when reading `.min.json` files.
+
+### Phase 2: Array Format
+
+```javascript
+// [name, description, children] - omit trailing nulls
+function toArray(obj) {
+  const children = obj.childParamsGroups?.map(toArray);
+  if (children) return [obj.name, obj.description || null, children];
+  if (obj.description) return [obj.name, obj.description];
+  return [obj.name];
+}
+```