diff --git a/.gitignore b/.gitignore index 5cc9f52..3ca2719 100644 --- a/.gitignore +++ b/.gitignore @@ -83,3 +83,4 @@ node_modules/ # --- Claude Code local state -------------------------------------------- # Per-project session state — lock files, local settings. Never shipped. .claude/ +coverage/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 02e4bcc..73f12ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,42 @@ # Changelog +## 0.9.0 + +**Final docs + polish before 1.0.0-rc.1.** No runtime API change; the +surface of 0.7.0 stays identical. This release closes the doc-coverage +gap, refreshes the README for the current API, and enables the +`public_member_api_docs` lint so gaps can't re-open. + +### Added + +- **`public_member_api_docs` lint enabled.** Every public exported + symbol now carries at least a one-line dartdoc. Internal FFI + bindings and self-documenting option/enum fields suppress the rule + with targeted `// ignore_for_file` pragmas and a comment + explaining why. +- **`dart doc --dry-run` passes clean** — zero unresolved references. + +### Changed + +- **README rewritten for the 0.9.0 API.** Install snippet now pins + `^0.9.0`; dead references to the `*Args` API (removed in 0.4.0) + are gone; `Config` loader / `Quicktype` constructor examples match + the 0.5.0 shape; transports section leads with "Prefer `auto`"; + bundle-source section documents the 0.4.4 body-read timeout, + atomic writes, and SRI base64 rejection. +- **`GenerateTransport` enum values now carry per-case docstrings** + explaining when each transport is available and when to reach for + it instead of `auto`. +- Various one-line docstrings added to `Config`, `ConfigException`, + `QuicktypeCommand`, `QuicktypeException`, `RendererOptions`, + `DefaultPaths.*` constants. + +### Skipped from plan + +- **Cancellation support** (`CancellationToken`) — deferred. Adding + a new concept to the `generate` surface right before the RC cut + wants consumer feedback first. Track via a post-1.0 RFC. + ## 0.7.0 **Quality gates release.** Locks in the bar for everything that diff --git a/README.md b/README.md index 98b6900..a3f26bc 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,12 @@ build time via `build_runner` or at runtime from in-memory data. Think of it as a **[pigeon](https://pub.dev/packages/pigeon)-analogue with arbitrarily-nested typed data**. Where pigeon gives you one-layer-deep method -channel contracts, `quicktype_dart` gives you typed data classes with -full nesting — on every platform, from a single JSON source of truth. +channel contracts, `quicktype_dart` gives you typed data classes with full +nesting — on every platform, from a single JSON source of truth. -A thin Dart wrapper around the [quicktype](https://quicktype.io) code generator. +A thin Dart wrapper around the [quicktype](https://quicktype.io) code +generator, embedded in a [QuickJS](https://bellard.org/quickjs/) runtime on +native targets and `dart:js_interop` on web. --- @@ -17,14 +19,14 @@ A thin Dart wrapper around the [quicktype](https://quicktype.io) code generator. ```yaml dependencies: - quicktype_dart: ^0.3.0 + quicktype_dart: ^0.9.0 ``` No other tooling required for Flutter apps on macOS, iOS, Linux, Windows, Android, or Web — `quicktype_dart` embeds quicktype-core in a QuickJS runtime (native platforms) or calls through `dart:js_interop` to the browser's JS engine (web), and ships the JS bundle as a Flutter asset. -~2ms per generation after a ~1s first-call warm-up. +~ms per generation after a ~1s first-call warm-up. For dev-time tooling (CI codegen, build_runner flows) on machines that lack the FFI plugin, install the `quicktype` CLI: @@ -55,8 +57,7 @@ final dartSource = await QuicktypeDart.generate( print(dartSource); // → `class User { ... }` with fromJson/toJson ``` -Pass language-specific flags via the typed `options:` parameter — e.g. -Dart with `--use-freezed --null-safety`: +Pass language-specific flags via the typed `options:` parameter: ```dart await QuicktypeDart.generate( @@ -70,13 +71,11 @@ await QuicktypeDart.generate( ); ``` -Every target has a matching `*RendererOptions` class: +Every target has a matching `*RendererOptions` class — `DartRendererOptions`, `KotlinRendererOptions`, `SwiftRendererOptions`, -`TypeScriptRendererOptions`, `CSharpRendererOptions`, `PythonRendererOptions`, -etc. IDE autocomplete gives you every flag the underlying renderer accepts. - -(The older `args: [DartArgs.useFreezed..value = true]` pattern still works -but is `@Deprecated` — removal planned for v0.4.0.) +`TypeScriptRendererOptions`, `CSharpRendererOptions`, +`PythonRendererOptions`, etc. IDE autocomplete gives you every flag the +underlying renderer accepts. Already have the JSON as a string? Skip the re-encode: @@ -129,63 +128,79 @@ dart run build_runner build You'll get `lib/models/user.dart` generated alongside the sample. Builders available: `quicktype_dart:dart`, `quicktype_dart:kotlin`, -`quicktype_dart:swift`, `quicktype_dart:typescript`. Enable any combination — -each produces the matching output extension next to the source. +`quicktype_dart:swift`, `quicktype_dart:typescript`. Enable any +combination — each produces the matching output extension next to the +source. + +See [`example/`](example/) for a minimal working setup. --- -## Transports +## Config-driven batch generation -`QuicktypeDart.generate` and `generateFromString` accept a `transport:` -parameter: +For non-builder flows (CLIs, CI pipelines), configure sources and +targets in `quicktype.json` and drive them through the `Quicktype` +orchestrator: ```dart -await QuicktypeDart.generate( - // ... - transport: GenerateTransport.auto, // default — FFI if available, else Process -); -await QuicktypeDart.generate( - // ... - transport: GenerateTransport.ffi, // force in-process QuickJS -); -await QuicktypeDart.generate( - // ... - transport: GenerateTransport.process, // always shell out to `quicktype` -); +import 'package:quicktype_dart/quicktype_dart.dart'; + +final qt = Quicktype(Config.loadOrDefaults('quicktype.json')); +final commands = await qt.buildCommandsFromConfig(); +final results = await qt.executeAll(commands); ``` -Under `ffi`, the first call warms up the embedded runtime (~1s to parse -the bundled quicktype-core). Subsequent calls in the same process run in -~ms. Each Dart isolate that calls `QuicktypeDart.generate` gets its own -runtime — QuickJS is single-threaded, and `QtFfiRuntime` enforces that -isolation. +`Config` exposes four constructors for different loading flavors: + +- `Config.fromFile(path)` — throws `ConfigException` on missing/malformed. +- `Config.loadOrDefaults(path)` — falls back to built-in defaults. +- `Config.fromMap(map)` — for tests and in-memory configs. +- `Config.defaults()` — the built-in defaults directly. -For long-running workflows or test setups, manage the runtime lifecycle -explicitly: +Multiple `Quicktype` / `Config` instances can coexist in a single +process — there are no singletons. + +--- + +## Transports + +`QuicktypeDart.generate` and `generateFromString` accept a `transport:` +parameter. **Prefer `auto`** — the others are escape hatches for tests, +benchmarks, or environments where the default picks wrong. ```dart -import 'package:quicktype_dart/src/ffi/ffi_runtime.dart'; +// default — FFI if available, else Process +await QuicktypeDart.generate(..., transport: GenerateTransport.auto); -final runtime = await QtFfiRuntime.create(); -try { - await runtime.generate(/* ... */); -} finally { - runtime.dispose(); -} +// force in-process QuickJS +await QuicktypeDart.generate(..., transport: GenerateTransport.ffi); + +// always shell out to `quicktype` +await QuicktypeDart.generate(..., transport: GenerateTransport.process); +``` + +Tune the subprocess timeout via a static: + +```dart +QuicktypeDart.processTimeout = const Duration(minutes: 10); ``` +Under `ffi`, the first call warms up the embedded runtime (~1s to parse +the bundled quicktype-core). Subsequent calls in the same process run in +~ms. Each Dart isolate gets its own runtime — QuickJS is single-threaded. + --- ## Supported target languages -C • C++ • C# • Dart • Elixir • Elm • Flow • Go • Haskell • Java • JavaScript -• Kotlin • Objective-C • PHP • JS PropTypes • Python • Ruby • Rust • Scala 3 -• Smithy • Swift • TypeScript +C • C++ • C# • Dart • Elixir • Elm • Flow • Go • Haskell • Java • +JavaScript • Kotlin • Objective-C • PHP • JS PropTypes • Python • Ruby • +Rust • Scala 3 • Smithy • Swift • TypeScript Each [`TargetType`](https://pub.dev/documentation/quicktype_dart/latest/quicktype_dart/TargetType.html) -value has a corresponding `*Args` class exposing the language-specific CLI -flags as typed getters — `DartArgs.useFreezed`, `SwiftArgs.structOrClass`, -`KotlinArgs.framework`, etc. +value has a matching `*RendererOptions` class exposing the +language-specific flags as named constructor parameters. Null fields are +omitted, so unset options inherit quicktype-core's defaults. --- @@ -193,19 +208,20 @@ flags as typed getters — `DartArgs.useFreezed`, `SwiftArgs.structOrClass`, 1. **"JSON → typed models, everywhere"** — you have JSON samples (API responses, fixtures, schemas) and want typed data classes in whatever - language your app's using. Point the builder at the folder, walk away. + language your app's using. Point the builder at the folder, walk + away. 2. **"One source of truth across platforms"** — you're writing a Flutter/iOS/Android/web app with shared data contracts. Define the shape once (as a JSON sample or JSON Schema), generate Dart for your Flutter code, Kotlin for Android native, Swift for iOS native, - TypeScript for the web client. Unlike pigeon, nesting works the whole - way down. + TypeScript for the web client. Unlike pigeon, nesting works the + whole way down. --- ## Bundle source -The 2.9MB quicktype-core JS bundle ships with the plugin by default — +The ~2.9MB quicktype-core JS bundle ships with the plugin by default — embedded in the C library on native and shipped as a Flutter asset on web. Apps that prefer to load from a CDN (or their own origin) can switch: @@ -220,17 +236,19 @@ QuicktypeDart.setBundleSource(BundleSource.remote( ``` `BundleSource.remote` is honored on both web and native. On native the -bytes are fetched via `HttpClient`, cached under the system temp dir -keyed by a URL hash, and verified against `integrity` before being fed -to QuickJS. SRI tokens support `sha256-…`, `sha384-…`, and `sha512-…`. +bytes are fetched via `HttpClient` with a 60-second body-read timeout, +cached under the system temp dir keyed by a URL hash, written +atomically, and verified against `integrity` before being fed to +QuickJS. SRI tokens support `sha256-…`, `sha384-…`, and `sha512-…`; +malformed base64 is rejected at parse time. ### Shedding the embedded bundle (~2.9MB per binary) -If every call site uses `BundleSource.remote`, the embedded copy is dead -weight. On CMake-driven targets (Linux / Windows / Android), rebuild the -native library with: +If every call site uses `BundleSource.remote`, the embedded copy is +dead weight. On CMake-driven targets (Linux / Windows / Android), +rebuild the native library with: -``` +```bash cmake -S native -B build -DQT_EMBED_BUNDLE=OFF cmake --build build ``` @@ -238,19 +256,19 @@ cmake --build build On macOS / iOS (CocoaPods), define `QT_NO_EMBEDDED_BUNDLE` in the pod's `OTHER_CFLAGS` and remove `Classes/bundle_data.c` from the source set. -Once embedding is off, `QuicktypeDart.setBundleSource(BundleSource.remote(...))` -**must** be called before the first generate — the library will otherwise -return an error that the embedded bundle is unavailable. +Once embedding is off, +`QuicktypeDart.setBundleSource(BundleSource.remote(...))` **must** be +called before the first generate — the library will otherwise return an +error that the embedded bundle is unavailable. --- ## Roadmap -- **v0.3.1** — current. Native remote bundle, `QT_EMBED_BUNDLE=OFF` opt-out. -- **v0.3.0** — typed `*RendererOptions` classes, Flutter Web remote bundle, - legacy process-global FFI API removed. -- **v0.4.0** — remove the deprecated `*Args` classes in favor of - `*RendererOptions`. +- **v0.9.0** — current. Final docs + polish before the RC cut. +- **v1.0.0-rc.1** — next. Tag + pub.dev publish once 0.9.x has baked. + +See [CHANGELOG.md](CHANGELOG.md) for the per-version detail. --- diff --git a/analysis_options.yaml b/analysis_options.yaml index 0df4975..373b912 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -33,6 +33,7 @@ linter: - prefer_final_in_for_each - prefer_final_locals - prefer_single_quotes + - public_member_api_docs - throw_in_finally - unawaited_futures - unnecessary_lambdas diff --git a/android/build.gradle b/android/build.gradle index 04e8242..ce5bc16 100644 --- a/android/build.gradle +++ b/android/build.gradle @@ -4,7 +4,7 @@ // Flutter's plugin system expects this file at `android/build.gradle`. group = "io.simplezen.quicktype_dart" -version = "0.7.0" +version = "0.9.0" buildscript { repositories { diff --git a/ios/quicktype_dart.podspec b/ios/quicktype_dart.podspec index 60f87e4..ff2a33f 100644 --- a/ios/quicktype_dart.podspec +++ b/ios/quicktype_dart.podspec @@ -8,7 +8,7 @@ Pod::Spec.new do |s| s.name = 'quicktype_dart' - s.version = '0.7.0' + s.version = '0.9.0' s.summary = 'Cross-platform type generation from JSON.' s.description = <<-DESC Embeds quicktype-core inside a QuickJS-NG runtime via FFI so Flutter diff --git a/lib/entrypoint_cli.dart b/lib/entrypoint_cli.dart index fccbefa..7bfc126 100644 --- a/lib/entrypoint_cli.dart +++ b/lib/entrypoint_cli.dart @@ -9,7 +9,7 @@ import 'src/version.dart'; /// Entry point for the `quicktype_dart` CLI. /// -/// Wired up from [bin/quicktype_dart.dart] — run it with: +/// Wired up from `bin/quicktype_dart.dart` — run it with: /// /// ```bash /// dart run quicktype_dart # uses ./quicktype.json diff --git a/lib/quicktype_dart.dart b/lib/quicktype_dart.dart index a2839d7..29da9fd 100644 --- a/lib/quicktype_dart.dart +++ b/lib/quicktype_dart.dart @@ -1,7 +1,7 @@ /// Cross-platform type generation from JSON. /// /// Use [QuicktypeDart.generate] for runtime, in-memory JSON → code, or wire -/// up the `build_runner` builders declared in [build.yaml] for build-time +/// up the `build_runner` builders declared in `build.yaml` for build-time /// generation from `*.qt.json` files. /// /// ```dart diff --git a/lib/src/bundle_source.dart b/lib/src/bundle_source.dart index c9206bc..b1360b6 100644 --- a/lib/src/bundle_source.dart +++ b/lib/src/bundle_source.dart @@ -50,11 +50,16 @@ sealed class BundleSource { /// See [BundleSource.embedded]. final class EmbeddedBundleSource extends BundleSource { + /// Creates a [BundleSource] that loads the compiled-in bundle. Use + /// the [BundleSource.embedded] factory for clarity. const EmbeddedBundleSource(); } /// See [BundleSource.remote]. final class RemoteBundleSource extends BundleSource { + /// Creates a [BundleSource] that fetches from [url], optionally + /// verified against a Subresource-Integrity [integrity] token. Use + /// the [BundleSource.remote] factory for clarity. const RemoteBundleSource(this.url, {this.integrity}); /// Absolute URL the browser will `