global: MASSIVE snapshot

crates/brk_bindgen/src/generators/javascript/api.rs

@@ -0,0 +1,112 @@
+//! JavaScript API method generation.
+
+use std::fmt::Write;
+
+use crate::{Endpoint, Parameter, to_camel_case};
+
+/// Generate API methods for the BrkClient class.
+pub fn generate_api_methods(output: &mut String, endpoints: &[Endpoint]) {
+    for endpoint in endpoints {
+        if !endpoint.should_generate() {
+            continue;
+        }
+
+        let method_name = endpoint_to_method_name(endpoint);
+        let return_type = endpoint.response_type.as_deref().unwrap_or("*");
+
+        writeln!(output, "  /**").unwrap();
+        if let Some(summary) = &endpoint.summary {
+            writeln!(output, "   * {}", summary).unwrap();
+        }
+        if let Some(desc) = &endpoint.description
+            && endpoint.summary.as_ref() != Some(desc)
+        {
+            writeln!(output, "   * @description {}", desc).unwrap();
+        }
+
+        for param in &endpoint.path_params {
+            let desc = param.description.as_deref().unwrap_or("");
+            writeln!(
+                output,
+                "   * @param {{{}}} {} {}",
+                param.param_type, param.name, desc
+            )
+            .unwrap();
+        }
+        for param in &endpoint.query_params {
+            let optional = if param.required { "" } else { "=" };
+            let desc = param.description.as_deref().unwrap_or("");
+            writeln!(
+                output,
+                "   * @param {{{}{}}} [{}] {}",
+                param.param_type, optional, param.name, desc
+            )
+            .unwrap();
+        }
+
+        writeln!(output, "   * @returns {{Promise<{}>}}", return_type).unwrap();
+        writeln!(output, "   */").unwrap();
+
+        let params = build_method_params(endpoint);
+        writeln!(output, "  async {}({}) {{", method_name, params).unwrap();
+
+        let path = build_path_template(&endpoint.path, &endpoint.path_params);
+
+        if endpoint.query_params.is_empty() {
+            writeln!(output, "    return this.get(`{}`);", path).unwrap();
+        } else {
+            writeln!(output, "    const params = new URLSearchParams();").unwrap();
+            for param in &endpoint.query_params {
+                if param.required {
+                    writeln!(
+                        output,
+                        "    params.set('{}', String({}));",
+                        param.name, param.name
+                    )
+                    .unwrap();
+                } else {
+                    writeln!(
+                        output,
+                        "    if ({} !== undefined) params.set('{}', String({}));",
+                        param.name, param.name, param.name
+                    )
+                    .unwrap();
+                }
+            }
+            writeln!(output, "    const query = params.toString();").unwrap();
+            writeln!(
+                output,
+                "    return this.get(`{}${{query ? '?' + query : ''}}`);",
+                path
+            )
+            .unwrap();
+        }
+
+        writeln!(output, "  }}\n").unwrap();
+    }
+}
+
+fn endpoint_to_method_name(endpoint: &Endpoint) -> String {
+    to_camel_case(&endpoint.operation_name())
+}
+
+fn build_method_params(endpoint: &Endpoint) -> String {
+    let mut params = Vec::new();
+    for param in &endpoint.path_params {
+        params.push(param.name.clone());
+    }
+    for param in &endpoint.query_params {
+        params.push(param.name.clone());
+    }
+    params.join(", ")
+}
+
+fn build_path_template(path: &str, path_params: &[Parameter]) -> String {
+    let mut result = path.to_string();
+    for param in path_params {
+        let placeholder = format!("{{{}}}", param.name);
+        let interpolation = format!("${{{}}}", param.name);
+        result = result.replace(&placeholder, &interpolation);
+    }
+    result
+}

crates/brk_bindgen/src/generators/javascript/client.rs

@@ -0,0 +1,374 @@
+//! JavaScript base client and pattern factory generation.
+
+use std::fmt::Write;
+
+use brk_cohort::{
+    AGE_RANGE_NAMES, AMOUNT_RANGE_NAMES, EPOCH_NAMES, GE_AMOUNT_NAMES, LT_AMOUNT_NAMES,
+    MAX_AGE_NAMES, MIN_AGE_NAMES, SPENDABLE_TYPE_NAMES, TERM_NAMES, YEAR_NAMES,
+};
+use brk_types::{Index, PoolSlug, pools};
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::{
+    ClientMetadata, GenericSyntax, IndexSetPattern, JavaScriptSyntax, PatternField,
+    StructuralPattern, VERSION, generate_parameterized_field, generate_tree_path_field,
+    to_camel_case,
+};
+
+/// Generate the base BrkClient class with HTTP functionality.
+pub fn generate_base_client(output: &mut String) {
+    writeln!(
+        output,
+        r#"/**
+ * @typedef {{Object}} BrkClientOptions
+ * @property {{string}} baseUrl - Base URL for the API
+ * @property {{number}} [timeout] - Request timeout in milliseconds
+ */
+
+const _isBrowser = typeof window !== 'undefined' && 'caches' in window;
+const _runIdle = (/** @type {{VoidFunction}} */ fn) => (globalThis.requestIdleCallback ?? setTimeout)(fn);
+
+/** @type {{Promise<Cache | null>}} */
+const _cachePromise = _isBrowser
+  ? caches.open('__BRK_CLIENT__').catch(() => null)
+  : Promise.resolve(null);
+
+/**
+ * Custom error class for BRK client errors
+ */
+class BrkError extends Error {{
+  /**
+   * @param {{string}} message
+   * @param {{number}} [status]
+   */
+  constructor(message, status) {{
+    super(message);
+    this.name = 'BrkError';
+    this.status = status;
+  }}
+}}
+
+/**
+ * @template T
+ * @typedef {{Object}} Endpoint
+ * @property {{(onUpdate?: (value: T[]) => void) => Promise<T[]>}} get - Fetch all data points
+ * @property {{(from?: number, to?: number, onUpdate?: (value: T[]) => void) => Promise<T[]>}} range - Fetch data in range
+ * @property {{string}} path - The endpoint path
+ */
+
+/**
+ * @template T
+ * @typedef {{Object}} MetricPattern
+ * @property {{string}} name - The metric name
+ * @property {{Partial<Record<Index, Endpoint<T>>>}} by - Index endpoints (lazy getters)
+ * @property {{() => Index[]}} indexes - Get the list of available indexes
+ * @property {{(index: Index) => Endpoint<T>|undefined}} get - Get an endpoint for a specific index
+ */
+
+/**
+ * Create an endpoint for a metric index.
+ * @template T
+ * @param {{BrkClientBase}} client
+ * @param {{string}} name - The metric vec name
+ * @param {{Index}} index - The index name
+ * @returns {{Endpoint<T>}}
+ */
+function _endpoint(client, name, index) {{
+  const p = `/api/metric/${{name}}/${{index}}`;
+  return {{
+    get: (onUpdate) => client.get(p, onUpdate),
+    range: (from, to, onUpdate) => {{
+      const params = new URLSearchParams();
+      if (from !== undefined) params.set('from', String(from));
+      if (to !== undefined) params.set('to', String(to));
+      const query = params.toString();
+      return client.get(query ? `${{p}}?${{query}}` : p, onUpdate);
+    }},
+    get path() {{ return p; }},
+  }};
+}}
+
+/**
+ * Base HTTP client for making requests with caching support
+ */
+class BrkClientBase {{
+  /**
+   * @param {{BrkClientOptions|string}} options
+   */
+  constructor(options) {{
+    const isString = typeof options === 'string';
+    this.baseUrl = isString ? options : options.baseUrl;
+    this.timeout = isString ? 5000 : (options.timeout ?? 5000);
+  }}
+
+  /**
+   * Make a GET request with stale-while-revalidate caching
+   * @template T
+   * @param {{string}} path
+   * @param {{(value: T) => void}} [onUpdate] - Called when data is available
+   * @returns {{Promise<T>}}
+   */
+  async get(path, onUpdate) {{
+    const base = this.baseUrl.endsWith('/') ? this.baseUrl.slice(0, -1) : this.baseUrl;
+    const url = `${{base}}${{path}}`;
+    const cache = await _cachePromise;
+    const cachedRes = await cache?.match(url);
+    const cachedJson = cachedRes ? await cachedRes.json() : null;
+
+    if (cachedJson) onUpdate?.(cachedJson);
+    if (!globalThis.navigator?.onLine) {{
+      if (cachedJson) return cachedJson;
+      throw new BrkError('Offline and no cached data available');
+    }}
+
+    try {{
+      const res = await fetch(url, {{ signal: AbortSignal.timeout(this.timeout) }});
+      if (!res.ok) throw new BrkError(`HTTP ${{res.status}}`, res.status);
+      if (cachedRes?.headers.get('ETag') === res.headers.get('ETag')) return cachedJson;
+
+      const cloned = res.clone();
+      const json = await res.json();
+      onUpdate?.(json);
+      if (cache) _runIdle(() => cache.put(url, cloned));
+      return json;
+    }} catch (e) {{
+      if (cachedJson) return cachedJson;
+      throw e;
+    }}
+  }}
+}}
+
+/**
+ * Build metric name with optional prefix.
+ * @param {{string}} acc - Accumulated prefix
+ * @param {{string}} s - Metric suffix
+ * @returns {{string}}
+ */
+const _m = (acc, s) => acc ? `${{acc}}_${{s}}` : s;
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate static constants for the BrkClient class.
+pub fn generate_static_constants(output: &mut String) {
+    fn instance_const<T: Serialize>(output: &mut String, name: &str, value: &T) {
+        write_static_const(output, name, &serde_json::to_string_pretty(value).unwrap());
+    }
+
+    fn instance_const_raw(output: &mut String, name: &str, value: &str) {
+        writeln!(output, "  {} = {};\n", name, value).unwrap();
+    }
+
+    instance_const_raw(output, "VERSION", &format!("\"v{}\"", VERSION));
+
+    let indexes = Index::all();
+    let indexes_json: Vec<&'static str> = indexes.iter().map(|i| i.serialize_long()).collect();
+    instance_const(output, "INDEXES", &indexes_json);
+
+    let pools = pools();
+    let mut sorted_pools: Vec<_> = pools.iter().collect();
+    sorted_pools.sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase()));
+    let pool_map: std::collections::BTreeMap<PoolSlug, &'static str> =
+        sorted_pools.iter().map(|p| (p.slug(), p.name)).collect();
+    instance_const(output, "POOL_ID_TO_POOL_NAME", &pool_map);
+
+    fn instance_const_camel<T: Serialize>(output: &mut String, name: &str, value: &T) {
+        let json_value: Value = serde_json::to_value(value).unwrap();
+        let camel_value = camel_case_top_level_keys(json_value);
+        write_static_const(output, name, &serde_json::to_string_pretty(&camel_value).unwrap());
+    }
+
+    instance_const_camel(output, "TERM_NAMES", &TERM_NAMES);
+    instance_const_camel(output, "EPOCH_NAMES", &EPOCH_NAMES);
+    instance_const_camel(output, "YEAR_NAMES", &YEAR_NAMES);
+    instance_const_camel(output, "SPENDABLE_TYPE_NAMES", &SPENDABLE_TYPE_NAMES);
+    instance_const_camel(output, "AGE_RANGE_NAMES", &AGE_RANGE_NAMES);
+    instance_const_camel(output, "MAX_AGE_NAMES", &MAX_AGE_NAMES);
+    instance_const_camel(output, "MIN_AGE_NAMES", &MIN_AGE_NAMES);
+    instance_const_camel(output, "AMOUNT_RANGE_NAMES", &AMOUNT_RANGE_NAMES);
+    instance_const_camel(output, "GE_AMOUNT_NAMES", &GE_AMOUNT_NAMES);
+    instance_const_camel(output, "LT_AMOUNT_NAMES", &LT_AMOUNT_NAMES);
+}
+
+fn camel_case_top_level_keys(value: Value) -> Value {
+    match value {
+        Value::Object(map) => {
+            let new_map: serde_json::Map<String, Value> = map
+                .into_iter()
+                .map(|(k, v)| (to_camel_case(&k), v))
+                .collect();
+            Value::Object(new_map)
+        }
+        other => other,
+    }
+}
+
+fn indent_json_const(json: &str) -> String {
+    json.lines()
+        .enumerate()
+        .map(|(i, line)| if i == 0 { line.to_string() } else { format!("  {}", line) })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn write_static_const(output: &mut String, name: &str, json: &str) {
+    writeln!(output, "  {} = /** @type {{const}} */ ({});\n", name, indent_json_const(json)).unwrap();
+}
+
+/// Generate index accessor factory functions.
+pub fn generate_index_accessors(output: &mut String, patterns: &[IndexSetPattern]) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Index accessor factory functions\n").unwrap();
+
+    for pattern in patterns {
+        let by_fields: Vec<String> = pattern
+            .indexes
+            .iter()
+            .map(|idx| format!("{}: Endpoint<T>", idx.serialize_long()))
+            .collect();
+        let by_type = format!("{{ {} }}", by_fields.join(", "));
+
+        writeln!(output, "/**").unwrap();
+        writeln!(output, " * @template T").unwrap();
+        writeln!(
+            output,
+            " * @typedef {{{{ name: string, by: {}, indexes: () => Index[], get: (index: Index) => Endpoint<T>|undefined }}}} {}",
+            by_type, pattern.name
+        )
+        .unwrap();
+        writeln!(output, " */\n").unwrap();
+
+        writeln!(output, "/**").unwrap();
+        writeln!(output, " * Create a {} accessor", pattern.name).unwrap();
+        writeln!(output, " * @template T").unwrap();
+        writeln!(output, " * @param {{BrkClientBase}} client").unwrap();
+        writeln!(output, " * @param {{string}} name - The metric vec name").unwrap();
+        writeln!(output, " * @returns {{{}<T>}}", pattern.name).unwrap();
+        writeln!(output, " */").unwrap();
+        writeln!(output, "function create{}(client, name) {{", pattern.name).unwrap();
+        writeln!(output, "  return {{").unwrap();
+        writeln!(output, "    name,").unwrap();
+        writeln!(output, "    by: {{").unwrap();
+
+        for (i, index) in pattern.indexes.iter().enumerate() {
+            let index_name = index.serialize_long();
+            let comma = if i < pattern.indexes.len() - 1 { "," } else { "" };
+            writeln!(
+                output,
+                "      get {}() {{ return _endpoint(client, name, '{}'); }}{}",
+                index_name, index_name, comma
+            )
+            .unwrap();
+        }
+
+        writeln!(output, "    }},").unwrap();
+        writeln!(output, "    indexes() {{").unwrap();
+
+        write!(output, "      return [").unwrap();
+        for (i, index) in pattern.indexes.iter().enumerate() {
+            if i > 0 {
+                write!(output, ", ").unwrap();
+            }
+            write!(output, "'{}'", index.serialize_long()).unwrap();
+        }
+        writeln!(output, "];").unwrap();
+
+        writeln!(output, "    }},").unwrap();
+        writeln!(output, "    get(index) {{").unwrap();
+        writeln!(output, "      if (this.indexes().includes(index)) {{").unwrap();
+        writeln!(output, "        return _endpoint(client, name, index);").unwrap();
+        writeln!(output, "      }}").unwrap();
+        writeln!(output, "    }}").unwrap();
+        writeln!(output, "  }};").unwrap();
+        writeln!(output, "}}\n").unwrap();
+    }
+}
+
+/// Generate structural pattern factory functions.
+pub fn generate_structural_patterns(
+    output: &mut String,
+    patterns: &[StructuralPattern],
+    metadata: &ClientMetadata,
+) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Reusable structural pattern factories\n").unwrap();
+
+    for pattern in patterns {
+        let is_parameterizable = pattern.is_parameterizable();
+
+        writeln!(output, "/**").unwrap();
+        if pattern.is_generic {
+            writeln!(output, " * @template T").unwrap();
+        }
+        writeln!(output, " * @typedef {{Object}} {}", pattern.name).unwrap();
+        for field in &pattern.fields {
+            let js_type = field_type_annotation(field, metadata, pattern.is_generic);
+            writeln!(
+                output,
+                " * @property {{{}}} {}",
+                js_type,
+                to_camel_case(&field.name)
+            )
+            .unwrap();
+        }
+        writeln!(output, " */\n").unwrap();
+
+        writeln!(output, "/**").unwrap();
+        writeln!(output, " * Create a {} pattern node", pattern.name).unwrap();
+        if pattern.is_generic {
+            writeln!(output, " * @template T").unwrap();
+        }
+        writeln!(output, " * @param {{BrkClientBase}} client").unwrap();
+        if is_parameterizable {
+            writeln!(output, " * @param {{string}} acc - Accumulated metric name").unwrap();
+        } else {
+            writeln!(output, " * @param {{string}} basePath").unwrap();
+        }
+        let return_type = if pattern.is_generic {
+            format!("{}<T>", pattern.name)
+        } else {
+            pattern.name.clone()
+        };
+        writeln!(output, " * @returns {{{}}}", return_type).unwrap();
+        writeln!(output, " */").unwrap();
+
+        let param_name = if is_parameterizable { "acc" } else { "basePath" };
+        writeln!(output, "function create{}(client, {}) {{", pattern.name, param_name).unwrap();
+        writeln!(output, "  return {{").unwrap();
+
+        let syntax = JavaScriptSyntax;
+        for field in &pattern.fields {
+            if is_parameterizable {
+                generate_parameterized_field(output, &syntax, field, pattern, metadata, "    ");
+            } else {
+                generate_tree_path_field(output, &syntax, field, metadata, "    ");
+            }
+        }
+
+        writeln!(output, "  }};").unwrap();
+        writeln!(output, "}}\n").unwrap();
+    }
+}
+
+fn field_type_annotation(field: &PatternField, metadata: &ClientMetadata, is_generic: bool) -> String {
+    metadata.field_type_annotation(field, is_generic, None, GenericSyntax::JAVASCRIPT)
+}
+
+/// Get field type with specific generic value type.
+pub fn field_type_with_generic(
+    field: &PatternField,
+    metadata: &ClientMetadata,
+    is_generic: bool,
+    generic_value_type: Option<&str>,
+) -> String {
+    metadata.field_type_annotation(field, is_generic, generic_value_type, GenericSyntax::JAVASCRIPT)
+}

crates/brk_bindgen/src/generators/javascript/mod.rs

@@ -0,0 +1,65 @@
+//! JavaScript client generation.
+//!
+//! This module generates a JavaScript + JSDoc client for the BRK API.
+
+mod api;
+mod client;
+mod tree;
+mod types;
+
+use std::{fmt::Write, fs, io, path::Path};
+
+use serde_json::json;
+
+use crate::{ClientMetadata, Endpoint, TypeSchemas, VERSION};
+
+/// Generate JavaScript + JSDoc client from metadata and OpenAPI endpoints.
+///
+/// `output_path` is the full path to the output file (e.g., "modules/brk-client/index.js").
+pub fn generate_javascript_client(
+    metadata: &ClientMetadata,
+    endpoints: &[Endpoint],
+    schemas: &TypeSchemas,
+    output_path: &Path,
+) -> io::Result<()> {
+    let mut output = String::new();
+
+    writeln!(output, "// Auto-generated BRK JavaScript client").unwrap();
+    writeln!(output, "// Do not edit manually\n").unwrap();
+
+    types::generate_type_definitions(&mut output, schemas);
+    client::generate_base_client(&mut output);
+    client::generate_index_accessors(&mut output, &metadata.index_set_patterns);
+    client::generate_structural_patterns(&mut output, &metadata.structural_patterns, metadata);
+    tree::generate_tree_typedefs(&mut output, &metadata.catalog, metadata);
+    tree::generate_main_client(&mut output, &metadata.catalog, metadata, endpoints);
+
+    fs::write(output_path, output)?;
+
+    // Update package.json version if it exists in the same directory
+    if let Some(parent) = output_path.parent() {
+        let package_json_path = parent.join("package.json");
+        if package_json_path.exists() {
+            update_package_json_version(&package_json_path)?;
+        }
+    }
+
+    Ok(())
+}
+
+fn update_package_json_version(package_json_path: &Path) -> io::Result<()> {
+    let content = fs::read_to_string(package_json_path)?;
+    let mut package: serde_json::Value = serde_json::from_str(&content)
+        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+
+    if let Some(obj) = package.as_object_mut() {
+        obj.insert("version".to_string(), json!(VERSION));
+    }
+
+    let updated = serde_json::to_string_pretty(&package)
+        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+
+    fs::write(package_json_path, updated + "\n")?;
+
+    Ok(())
+}

crates/brk_bindgen/src/generators/javascript/tree.rs

@@ -0,0 +1,223 @@
+//! JavaScript tree structure generation.
+
+use std::collections::HashSet;
+use std::fmt::Write;
+
+use brk_types::TreeNode;
+
+use crate::{
+    ClientMetadata, Endpoint, PatternField, child_type_name, get_fields_with_child_info,
+    get_first_leaf_name, get_node_fields, get_pattern_instance_base, infer_accumulated_name,
+    to_camel_case,
+};
+
+use super::api::generate_api_methods;
+use super::client::{field_type_with_generic, generate_static_constants};
+
+/// Generate JSDoc typedefs for the catalog tree.
+pub fn generate_tree_typedefs(output: &mut String, catalog: &TreeNode, metadata: &ClientMetadata) {
+    writeln!(output, "// Catalog tree typedefs\n").unwrap();
+
+    let pattern_lookup = metadata.pattern_lookup();
+    let mut generated = HashSet::new();
+    generate_tree_typedef(
+        output,
+        "CatalogTree",
+        catalog,
+        &pattern_lookup,
+        metadata,
+        &mut generated,
+    );
+}
+
+fn generate_tree_typedef(
+    output: &mut String,
+    name: &str,
+    node: &TreeNode,
+    pattern_lookup: &std::collections::HashMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+    generated: &mut HashSet<String>,
+) {
+    let TreeNode::Branch(children) = node else {
+        return;
+    };
+
+    let fields_with_child_info = get_fields_with_child_info(children, name, pattern_lookup);
+    let fields: Vec<PatternField> = fields_with_child_info
+        .iter()
+        .map(|(f, _)| f.clone())
+        .collect();
+
+    if pattern_lookup.contains_key(&fields)
+        && pattern_lookup.get(&fields) != Some(&name.to_string())
+    {
+        return;
+    }
+
+    if generated.contains(name) {
+        return;
+    }
+    generated.insert(name.to_string());
+
+    writeln!(output, "/**").unwrap();
+    writeln!(output, " * @typedef {{Object}} {}", name).unwrap();
+
+    for (field, child_fields) in &fields_with_child_info {
+        let generic_value_type = child_fields
+            .as_ref()
+            .and_then(|cf| metadata.get_type_param(cf))
+            .map(String::as_str);
+        let js_type = field_type_with_generic(field, metadata, false, generic_value_type);
+        writeln!(
+            output,
+            " * @property {{{}}} {}",
+            js_type,
+            to_camel_case(&field.name)
+        )
+        .unwrap();
+    }
+
+    writeln!(output, " */\n").unwrap();
+
+    for (child_name, child_node) in children {
+        if let TreeNode::Branch(grandchildren) = child_node {
+            let child_fields = get_node_fields(grandchildren, pattern_lookup);
+            if !pattern_lookup.contains_key(&child_fields) {
+                let child_type = child_type_name(name, child_name);
+                generate_tree_typedef(
+                    output,
+                    &child_type,
+                    child_node,
+                    pattern_lookup,
+                    metadata,
+                    generated,
+                );
+            }
+        }
+    }
+}
+
+/// Generate the main BrkClient class.
+pub fn generate_main_client(
+    output: &mut String,
+    catalog: &TreeNode,
+    metadata: &ClientMetadata,
+    endpoints: &[Endpoint],
+) {
+    let pattern_lookup = metadata.pattern_lookup();
+
+    writeln!(output, "/**").unwrap();
+    writeln!(output, " * Main BRK client with catalog tree and API methods").unwrap();
+    writeln!(output, " * @extends BrkClientBase").unwrap();
+    writeln!(output, " */").unwrap();
+    writeln!(output, "class BrkClient extends BrkClientBase {{").unwrap();
+
+    generate_static_constants(output);
+
+    writeln!(output, "  /**").unwrap();
+    writeln!(output, "   * @param {{BrkClientOptions|string}} options").unwrap();
+    writeln!(output, "   */").unwrap();
+    writeln!(output, "  constructor(options) {{").unwrap();
+    writeln!(output, "    super(options);").unwrap();
+    writeln!(output, "    /** @type {{CatalogTree}} */").unwrap();
+    writeln!(output, "    this.tree = this._buildTree('');").unwrap();
+    writeln!(output, "  }}\n").unwrap();
+
+    writeln!(output, "  /**").unwrap();
+    writeln!(output, "   * @private").unwrap();
+    writeln!(output, "   * @param {{string}} basePath").unwrap();
+    writeln!(output, "   * @returns {{CatalogTree}}").unwrap();
+    writeln!(output, "   */").unwrap();
+    writeln!(output, "  _buildTree(basePath) {{").unwrap();
+    writeln!(output, "    return {{").unwrap();
+    generate_tree_initializer(output, catalog, "", 3, &pattern_lookup, metadata);
+    writeln!(output, "    }};").unwrap();
+    writeln!(output, "  }}\n").unwrap();
+
+    generate_api_methods(output, endpoints);
+
+    writeln!(output, "}}\n").unwrap();
+
+    writeln!(output, "export {{ BrkClient, BrkClientBase, BrkError }};").unwrap();
+}
+
+fn generate_tree_initializer(
+    output: &mut String,
+    node: &TreeNode,
+    accumulated_name: &str,
+    indent: usize,
+    pattern_lookup: &std::collections::HashMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+) {
+    let indent_str = "  ".repeat(indent);
+
+    if let TreeNode::Branch(children) = node {
+        for (i, (child_name, child_node)) in children.iter().enumerate() {
+            let field_name = to_camel_case(child_name);
+            let comma = if i < children.len() - 1 { "," } else { "" };
+
+            match child_node {
+                TreeNode::Leaf(leaf) => {
+                    let accessor = metadata
+                        .find_index_set_pattern(leaf.indexes())
+                        .unwrap_or_else(|| {
+                            panic!(
+                                "Metric '{}' has no matching index pattern. All metrics must be indexed.",
+                                leaf.name()
+                            )
+                        });
+                    writeln!(
+                        output,
+                        "{}{}: create{}(this, '{}'){}",
+                        indent_str, field_name, accessor.name, leaf.name(), comma
+                    )
+                    .unwrap();
+                }
+                TreeNode::Branch(grandchildren) => {
+                    let child_fields = get_node_fields(grandchildren, pattern_lookup);
+                    if let Some(pattern_name) = pattern_lookup.get(&child_fields) {
+                        let pattern = metadata
+                            .structural_patterns
+                            .iter()
+                            .find(|p| &p.name == pattern_name);
+                        let is_parameterizable =
+                            pattern.map(|p| p.is_parameterizable()).unwrap_or(false);
+
+                        let arg = if is_parameterizable {
+                            get_pattern_instance_base(child_node)
+                        } else if accumulated_name.is_empty() {
+                            format!("/{}", child_name)
+                        } else {
+                            format!("{}/{}", accumulated_name, child_name)
+                        };
+
+                        writeln!(
+                            output,
+                            "{}{}: create{}(this, '{}'){}",
+                            indent_str, field_name, pattern_name, arg, comma
+                        )
+                        .unwrap();
+                    } else {
+                        let child_acc =
+                            infer_child_accumulated_name(child_node, accumulated_name, child_name);
+                        writeln!(output, "{}{}: {{", indent_str, field_name).unwrap();
+                        generate_tree_initializer(
+                            output,
+                            child_node,
+                            &child_acc,
+                            indent + 1,
+                            pattern_lookup,
+                            metadata,
+                        );
+                        writeln!(output, "{}}}{}", indent_str, comma).unwrap();
+                    }
+                }
+            }
+        }
+    }
+}
+
+fn infer_child_accumulated_name(node: &TreeNode, parent_acc: &str, field_name: &str) -> String {
+    let leaf_name = get_first_leaf_name(node).unwrap_or_default();
+    infer_accumulated_name(parent_acc, field_name, &leaf_name)
+}

crates/brk_bindgen/src/generators/javascript/types.rs

@@ -0,0 +1,172 @@
+//! JavaScript type definitions generation.
+
+use std::fmt::Write;
+
+use serde_json::Value;
+
+use crate::{TypeSchemas, ref_to_type_name, to_camel_case};
+
+/// Generate JSDoc type definitions from OpenAPI schemas.
+pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
+    if schemas.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Type definitions\n").unwrap();
+
+    for (name, schema) in schemas {
+        let js_type = schema_to_js_type(schema, Some(name));
+
+        if is_primitive_alias(schema) {
+            writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
+        } else if let Some(props) = schema.get("properties").and_then(|p| p.as_object()) {
+            writeln!(output, "/**").unwrap();
+            writeln!(output, " * @typedef {{Object}} {}", name).unwrap();
+            for (prop_name, prop_schema) in props {
+                let prop_type = schema_to_js_type(prop_schema, Some(name));
+                let required = schema
+                    .get("required")
+                    .and_then(|r| r.as_array())
+                    .map(|arr| arr.iter().any(|v| v.as_str() == Some(prop_name)))
+                    .unwrap_or(false);
+                let optional = if required { "" } else { "=" };
+                let safe_name = to_camel_case(prop_name);
+                writeln!(
+                    output,
+                    " * @property {{{}{}}} {}",
+                    prop_type, optional, safe_name
+                )
+                .unwrap();
+            }
+            writeln!(output, " */").unwrap();
+        } else {
+            writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
+        }
+    }
+    writeln!(output).unwrap();
+}
+
+fn is_primitive_alias(schema: &Value) -> bool {
+    schema.get("properties").is_none()
+        && schema.get("items").is_none()
+        && schema.get("anyOf").is_none()
+        && schema.get("oneOf").is_none()
+        && schema.get("enum").is_none()
+}
+
+fn json_type_to_js(ty: &str, schema: &Value, current_type: Option<&str>) -> String {
+    match ty {
+        "integer" | "number" => "number".to_string(),
+        "boolean" => "boolean".to_string(),
+        "string" => "string".to_string(),
+        "null" => "null".to_string(),
+        "array" => {
+            let item_type = schema
+                .get("items")
+                .map(|s| schema_to_js_type(s, current_type))
+                .unwrap_or_else(|| "*".to_string());
+            format!("{}[]", item_type)
+        }
+        "object" => {
+            if let Some(add_props) = schema.get("additionalProperties") {
+                let value_type = schema_to_js_type(add_props, current_type);
+                return format!("{{ [key: string]: {} }}", value_type);
+            }
+            "Object".to_string()
+        }
+        _ => "*".to_string(),
+    }
+}
+
+/// Convert a JSON schema to a JavaScript type string.
+pub fn schema_to_js_type(schema: &Value, current_type: Option<&str>) -> String {
+    if let Some(all_of) = schema.get("allOf").and_then(|v| v.as_array()) {
+        for item in all_of {
+            let resolved = schema_to_js_type(item, current_type);
+            if resolved != "*" {
+                return resolved;
+            }
+        }
+    }
+
+    if let Some(ref_path) = schema.get("$ref").and_then(|r| r.as_str()) {
+        return ref_to_type_name(ref_path).unwrap_or("*").to_string();
+    }
+
+    if let Some(enum_values) = schema.get("enum").and_then(|e| e.as_array()) {
+        let literals: Vec<String> = enum_values
+            .iter()
+            .filter_map(|v| v.as_str())
+            .map(|s| format!("\"{}\"", s))
+            .collect();
+        if !literals.is_empty() {
+            return format!("({})", literals.join("|"));
+        }
+    }
+
+    if let Some(ty) = schema.get("type") {
+        if let Some(type_array) = ty.as_array() {
+            let types: Vec<String> = type_array
+                .iter()
+                .filter_map(|t| t.as_str())
+                .filter(|t| *t != "null")
+                .map(|t| json_type_to_js(t, schema, current_type))
+                .collect();
+            let has_null = type_array.iter().any(|t| t.as_str() == Some("null"));
+
+            if types.len() == 1 {
+                let base_type = &types[0];
+                return if has_null {
+                    format!("?{}", base_type)
+                } else {
+                    base_type.clone()
+                };
+            } else if !types.is_empty() {
+                let union = format!("({})", types.join("|"));
+                return if has_null {
+                    format!("?{}", union)
+                } else {
+                    union
+                };
+            }
+        }
+
+        if let Some(ty_str) = ty.as_str() {
+            return json_type_to_js(ty_str, schema, current_type);
+        }
+    }
+
+    if let Some(variants) = schema
+        .get("anyOf")
+        .or_else(|| schema.get("oneOf"))
+        .and_then(|v| v.as_array())
+    {
+        let types: Vec<String> = variants
+            .iter()
+            .map(|v| schema_to_js_type(v, current_type))
+            .collect();
+        let filtered: Vec<_> = types.iter().filter(|t| *t != "*").collect();
+        if !filtered.is_empty() {
+            return format!(
+                "({})",
+                filtered
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join("|")
+            );
+        }
+        return format!("({})", types.join("|"));
+    }
+
+    if let Some(format) = schema.get("format").and_then(|f| f.as_str()) {
+        return match format {
+            "int32" | "int64" => "number".to_string(),
+            "float" | "double" => "number".to_string(),
+            "date" | "date-time" => "string".to_string(),
+            _ => "*".to_string(),
+        };
+    }
+
+    "*".to_string()
+}