analytics_gen 2.3.0
analytics_gen: ^2.3.0 copied to clipboard
Type-safe analytics event tracking with code generation from YAML configuration. Supports multiple providers, testing utilities, and export formats.
Changelog #
All notable changes to this project will be documented in this file.
2.3.0 #
Behaviour changes #
Most of these turn a silent mistake into an error. Check them before upgrading:
- An unknown
naming.casingvalue, such astitleCase, now stops generation and lists the accepted values. Before, it silently fell back tosnake_case. - A parameter written as
name:with no shared parameter of that name now fails to parse. Before, it generatedrequired null name, which did not compile. - A
regexthat does not compile, a length rule (min_length,max_length,regex) on a non-string type, and a range rule (min,max) on a non-numeric type now fail to parse. Before, they produced code that did not compile or threw in the app. auditandstudio_exportreject generation flags such as--watchor--docs. Before, they accepted and ignored them.- When
sqlite3is installed but cannot build the database, generation fails with its error. Before, it reported success and left an empty database. - The SQL and SQLite exports store
source_pathrelative to the project root (events/auth.yaml) instead of an absolute path. BatchingAnalyticsandMultiProviderAnalyticswrite failures that have no callback to the console through aConsoleLogger. Passloggerto send them elsewhere. In debug builds, a failed flush no longer throws anAssertionErrorin place of the delegate's error.- Generated context files with a
regexswitch fromr'...'tor'''...''', the form events already use.
Features #
- Unknown fields in events, parameters and shared parameter files, such as a misspelled
paramters:orallowed_value:, log a warning with the file, line and column. Generation continues. BatchingAnalyticstakes an optionalmaxQueueSizethat drops the oldest events while the provider is unreachable, and alogger. Every dropped event, including one logged afterdispose(), goes toonEventDropped.- A shared parameter that sets
param_namecan be referenced by its key in the shared file as well as by that name, matching the Studio. auditandstudio_exporthave their own--helpand options.
Fixes #
Generated code
- Quotes,
$, backslashes and line breaks in YAML values no longer break the generated Dart: enum values, wire names fromparam_name, context names,replacement, multi-line descriptions and regex patterns are escaped. - Allowed values that differ only in case or separators (
Email,email) report a collision instead of generating two identical enum constants. - Dual-write calls compile when both parameters are generated enums, convert the value by name, and fall back to logging the target event when the types cannot match, for example a nullable value feeding a required parameter. Arguments are passed by identifier, not by wire name.
- Interpolated event names use the parameter's identifier, so
identifier:overrides no longer produce undefined variables. - Nullable enum and
dart_typeparameters no longer generate a?.that the analyzer reports as a warning.
Parsing and errors
- A field with the wrong type (
description: 42,min: "1") is reported by name at the value, in event, context and shared parameter files alike. In context and shared files it used to crash with a rawTypeError. - Every located error names its file (
line 3, column 18 of events/auth.yaml), and a YAML syntax error is reported once instead of twice. - Mistyped
namingfields, anamingvalue that is not a map, a config file with only comments, and a config file whose root is a list are reported clearly. - With
--verbose, a stack trace is printed only for unexpected failures, not for mistakes in the tracking plan, config or command line. - The generated YAML templates load again:
event_name_templateis quoted and the regex example no longer uses an invalid escape.
CLI and exports
- Watch mode keeps running when a regeneration fails.
auditand the Studio export read the tracking plan the same way generation does, including shared parameters, contexts and glob event paths.- The dead event report runs
git blamein the events file's repository, so it shows last-modified details regardless of the current directory. - The SQLite export quotes the script path, so it works in directories with spaces.
- The schema evolution check treats type aliases (
bool,boolean) as the same type, reportsdart_typechanges and narrowedallowed_valuesas breaking, and reports widenedallowed_valuesas non-breaking. - The Markdown docs link their table of contents to the real heading anchors.
- The Studio export warns about each malformed YAML file it skips and no longer rewrites an unchanged project file.
Runtime services
BatchingAnalytics.dispose()delivers events that a failed automatic flush put back in the queue, instead of throwing and losing them.- A provider filter that throws in
MultiProviderAnalytics, or a provider that throws before returning a future, is reported throughonProviderFailureand no longer stops delivery to the other providers.
Studio
- The three parameter editors share one form: changing the type keeps the other fields, and switching selections no longer crashes with "Rendered fewer hooks than expected".
- Renames onto an existing name are rejected, new names follow the configured naming rules, and ZIP export is blocked while validation errors remain.
- Navigation no longer enters undo history or marks the project as unsaved, keyboard shortcuts work with Caps Lock or Shift, settings missing from stored projects are filled with their defaults, YAML import reports every failure, and tree controls have accessible names.
Deprecations #
ensureAnalyticsInitializedis deprecated: the generatedAnalytics.instanceperforms the check. It will be removed in the next major release.BatchingAnalytics.startFlushForTestis deprecated in favour offlush().
Internals #
- The format check in CI resolves dependencies first; it had failed on every pull request. The Studio ESLint check runs in CI and
sync.sh, andsync.shnow fails when the type check or Studio tests fail. - Tests use
fake_asyncinstead of real waits, and the CLI commands run in process. Line coverage oflib/rose from 93.6% to 95.8%. - Field lists, type aliases, config defaults and the generated-enum rule each live in one place, and a test keeps them in step with
schema/*.json. - Unused internal code was removed.
2.2.2 #
Fixes #
- Widened the
analyzerconstraint to>=7.7.1 <15.0.0. Projects on Dart 3.10+ need a neweranalyzerforbuild_runner,freezed, anddrift_dev, and the previous^7.7.1pin blocked their resolution. Projects that stay onanalyzer7 resolve as before.
2.2.1 #
Features #
- Added the
analytics-gen-yaml-schemapackage skill for AI agents creating, updating, and validating YAML tracking plans. Install it from an application that depends onanalytics_genwithdart run skills@ get -p analytics_gen -s analytics-gen-yaml-schema.
2.2.0 #
Features #
- Studio remembers your project file — after a reload the Studio reconnects to the last opened
analytics-studio.json(Chrome/Edge, via the File System Access API) and remembers the file name on every browser, so you no longer re-open it each session.Savewrites straight back to the same file; data is auto-saved locally regardless. - Project identity & content revision for CI/CD — saved and generated
analytics-studio.jsonnow carries ametablock with a stableprojectId, an optionalname, and a contentrevisionhash. The revision is deterministic and timestamp-free, so CI can compare project files across commits to detect analytics changes. The Dartstudiotarget emits the samemetaand preservesprojectIdacross regenerations. - Customizable / unique export names — set a project name (drives both the
.jsonand ZIP file names) and optionally append the content-revision hash for unique CI-artifact names, via the new "Project…" dialog (which also shows the project ID and revision). - External-change detection — when
analytics-studio.jsonchanges on disk (an external edit, agit pull, a CI regeneration), the Studio offers to reload it instead of silently diverging (Chrome/Edge).
Internals #
- Shared cross-language
revisionhash (cyrb53 over canonical, key-sorted JSON) implemented in both the Studio (project-meta.ts) and the Dart generator (project_revision.dart), locked by a parity test so a studio-saved and a CI-generated file agree for identical content.
2.1.0 #
Features #
- Studio export as a first-class generation target — added
targets.studio(withoutputs.studiopath) toanalytics_gen.yaml. The Studio project file is now produced by the main pipeline alongside Dart code, docs, and exports. --studioCLI flag fordart run analytics_gen:generate. CLI flags follow the same precedence as--docs/--exports: explicit flag wins over config, with--no-studioto disable.- Flat aliases
generate_studioandstudio_pathare accepted at the root of the config for parity with other targets.
Fixes #
- Studio now normalizes events when loading a project file — events without a
parametersblock (allowed by schema) no longer crash the import. YAML and JSON import paths share the same normalization logic.
Internals #
- Extracted studio export logic into
StudioGeneratorso the standaloneanalytics_gen:studio_exportbinary and the main pipeline use the same zero-knowledge YAML reader.
2.0.0 #
Features #
- Analytics Gen Studio — web-based visual editor for analytics configuration, events, shared parameters, and contexts with real-time YAML preview.
- Schema as Single Source of Truth — JSON schemas in
schema/now drive everything: Studio UI, TypeScript types, YAML templates, and documentation. - Schema-driven generation — YAML templates, schema reference docs, and Studio TypeScript types are all auto-generated from JSON schemas.
- Studio features: search/filter in event tree, keyboard shortcuts (Ctrl+S/O), notifications, compact array inputs, validation error badges on tabs, confirm dialogs for all deletions, auto-fill context name from filename.
Architecture #
- Studio renders all forms dynamically from JSON schemas — no hardcoded data.
- TypeScript types auto-generated from schemas.
- YAML templates and schema reference docs auto-generated from schemas.
- All YAML field names centralized via constants — no raw string literals in parsers.
1.1.0 #
Features #
- Added
booleanas an alias forbooltype across type mapping, parsing, and documentation generation. - Added automatic tracking creation date injection via a new ledger file and
meta.auto_tracking_creation_dateconfig option.- When enabled, the generator maintains a
.analytics_tracking.jsonledger file that records an ISO 8601 timestamp (yyyy-MM-ddTHH:mm:ss) when each event is first seen. - The
tracking_creation_datevalue is automatically injected into each event'smetafield during generation. - Existing entries are never overwritten — the ledger preserves the original creation timestamp.
- The ledger file is placed next to
analytics_gen.yamland should be committed to version control.
- When enabled, the generator maintains a
- Added
meta.include_meta_in_parametersconfig option to include event meta fields in the generatedeventParametersmap sent to analytics providers (e.g. Amplitude, Mixpanel). Default:false.
1.0.8 #
Features #
- Added
dartReservedWordstoStringUtilto prevent enum member name collisions with Dart keywords.
1.0.6 #
Bug Fixes #
- Fixed
NamingStrategy._toTitleCasestripping structural punctuation (e.g.:) fromevent_name_template. Previously, usingcasing: title_casewith a template like"{domain}: {event}"produced"Chat Under Dev Sheet Shown"instead of"Chat: Under Dev Sheet Shown". Only_and-are now treated as word boundaries.
1.0.5 #
- Added
templates/analytics_gen.yamlas a reference for all configuration options. - Added
templates/events.yamldemonstrating event and parameter definitions. - Update README to enhance clarity and structure of
analytics_gendocumentation. - Add onboarding and AI prompt guides to documentation; enhance README with new links.
1.0.4 #
Improvements #
- Introduced
CapabilityProviderBaseto replaceCapabilityProviderMixin(deprecated). - Added
--metricsflag to track generation performance. - Added "Dead Event" Audit Enhancement with git commit info.
- Glob Pattern Support:
EventLoadernow supports glob patterns (e.g.,events/**/*.yaml). - Improved Fingerprint Sensitivity: covers all event/parameter fields.
- Cross-Platform Robustness: Normalized path handling for Windows/macOS/Linux.
- Added
doc/PERFORMANCE.md,doc/TROUBLESHOOTING.md,doc/TESTING.md.
Bug Fixes #
- Fixed data loss bug in
BatchingAnalyticswhere queue would stall after failed auto-flush. - Fixed
ConfigParsercrash when optional fields are explicitlynull. CapabilityRegistrynow throwsStateErroron duplicate capability keys.- Added default error logging to
BatchingAnalyticsandMultiProviderAnalytics.
1.0.3 #
Features #
- Added "Dead Event" Audit Command (
dart run analytics_gen:audit). - Added
test_matcherstarget to generate typedpackage:testmatchers. - Added
dart_typeparameter option to map parameters to existing Dart types. - Added
importsconfiguration for including external types. - Added configurable event naming strategy (
casing:snake_case,title_case,original).
Improvements #
- Generated code now uses
constmaps for constant event parameters. - Removed auto-generated tests in favor of
test_matchers.
1.0.2 #
- Enhanced SQL/CSV/JSON export formats with additional metadata.
- Formalized analytics data representation with
AnalyticsParameterandAnalyticsDomainmodels. - Conditionally generate Flutter or Dart test imports based on project type.
1.0.0 #
- Stable release with full documentation and API reference.
0.2.1 #
Breaking Changes #
- Configuration restructured into logical groups (
inputs,outputs,targets,rules).# Old → New events_path → inputs.events output_path → outputs.dart docs_path → outputs.docs event_parameters_path → inputs.shared_parameters
Features #
- Shared Event Parameters via
shared_parametersconfig. - Parameter validation DSL:
regex,min_length,max_length,min,max. - Enum generation for parameters with
allowed_values. - Enhanced CSV export with multiple files and better escaping.
Analytics.reset()for testing and hot-restart scenarios.
0.2.0 #
Features #
- Extensible Metadata: Support for
metakey-value pairs in YAML. - Batching & Async: Added
BatchingAnalyticsandAsyncAnalyticsAdapter. - Flexible Naming: Configurable naming strategies.
- Strict Mode:
strict_event_namesto prevent high-cardinality.
Improvements #
- Optimized generator with parallel processing.
- Full test coverage (100%).
0.1.6 #
- Added
include_event_descriptionconfig option. - Support interpolated placeholders in
event_name(e.g.,"Screen: {screen_name}").
0.1.5 #
- Full test coverage.
- Added GitHub Actions CI.
0.1.4 #
Features #
- Added CLI flags:
--validate-only,--watch,--verbose,--plan. MultiProviderAnalyticswith error isolation andonProviderFailurehook.- Event deprecation lifecycle with
deprecated+replacement. allowed_valuesfor parameters with runtime validation.- Deterministic fingerprints in exports (no timestamps).
Improvements #
- Stricter YAML parser with better error messages.
RecordedAnalyticsEventfor typed mock assertions.
0.1.3 #
- Fix badge issues.
0.1.2 #
- Refactor string interpolation in code generation.
0.1.1 #
- Minor updates and fixes.
0.1.0 #
- Minor updates and fixes.
0.0.1 #
- Initial release.