Public entry points
index.ts registers all Node.js engines and exports AVA plus public types. index.browser.ts registers only JavaScript. ava.ts coordinates source state, data model, events, and engine lifecycle.
Source directory map
| Source | Responsibility |
|---|---|
ava.ts | Public API, source state, and lifecycle |
types.ts | Public type definitions and schema-derived types |
contracts/ | API contracts for source, schema, profile, semantic, query, analyze, suggest and visualization |
engines.ts | Engine selection and registry |
analysis/ | Direct and loop strategies |
duckdb/ | SQL engine, source loaders, and profiling |
interpreter/javascript/ | In-memory data and JavaScript execution |
interpreter/python/ | pandas execution and source validation |
remote/supabase/ | Management API, schema, and profiling |
remote/clickhouse/ | Remote SQL, schema, and profiling |
remote/snowflake/ | Snowflake driver session, schema, and profiling |
query/ | Query generation and dialect validation |
visualization/ | Chart advice, GPT-Vis config, and HTML generation |
suggest/ | Suggested analysis questions |
event/ | Event types and payloads |
cli/ | Commands and local dataset sessions |
util/ | Catalog assembly, model formatting, metric execution rules and result bounds |
Contracts follow the public API. source/ keeps each source type's runtime schema in its own file, including CSV/JSON/Excel reader options; source/index.ts assembles the source union and source/shared.ts holds common file and connection fields. schema.ts, profile.ts, semantic.ts, query.ts, analyze.ts, translate.ts and suggest.ts define each API's runtime input and output schemas. visualize.ts holds the chart specification shared by recommend(), viz() and visualize(). Cross-API JSON values and data-model building blocks live in shared/.
types.ts defines public configuration, engine, strategy and data types; data types are inferred from the runtime schemas. The data-model builder owns its stricter assembly input validation, derived from the public metadata fields. Modules import API schemas through contracts/index.ts, internal schemas from their owning modules and types from types.ts; contract definitions reference each other directly to avoid circular dependencies. index.ts and index.browser.ts export API input/output schemas and types with their existing names. CLI wire messages, AI-stage response formats and interpreter-specific restrictions remain local to their modules.
Method to module
| Public method | Responsibility / implementation |
|---|---|
source() / schema() / dispose() | Source state and engine lifecycle in ava.ts |
profile() | Per-engine profiling; shared metric contracts in util/profile.ts |
analyze() | Dispatch to analysis/direct.ts or analysis/loop.ts |
translate() / query() | Engine getDSL() / execute() |
suggest() | suggest/index.ts |
recommend() | visualization/advisor.ts and config generation |
viz() | HTML wrapping in visualization/generator.ts |
visualize() | Compose recommend() and viz() |
Context and state
An AVA instance owns one active engine and its schema/profile cache. source() loads data; schema() discovers structure on first use. profile() computes and retains fresh observations; the data model is assembled from cached metadata when needed. Reloading or disposal clears both caches.
Engines retain data and connections. Their load() returns no metadata; schema() discovers it, profile(schema, options?) computes observations, and getDSL(query, dataModel) consumes AVA's data model. Shared data validators live in contracts/; catalog assembly and metric execution helpers stay in util/.
Analysis strategies share a runtime containing the engine, model configuration, data model, and event emitter. Query result limits are normalized through shared utilities.
Documentation organization
Each topic is a separate MDX file under site/content/docs/, grouped into data/, analysis/, visualization/, engines/, and reference/. This mirrors the public capabilities without exposing every internal helper as a separate user-facing page.