Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,4 @@ node_modules/
# --- Claude Code local state --------------------------------------------
# Per-project session state — lock files, local settings. Never shipped.
.claude/
coverage/
37 changes: 37 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
156 changes: 87 additions & 69 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,27 @@ 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.

---

## Install

```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:
Expand Down Expand Up @@ -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(
Expand All @@ -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:

Expand Down Expand Up @@ -129,83 +128,100 @@ 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.

---

## Two ways to think about this package

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:
Expand All @@ -220,37 +236,39 @@ 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
```

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.

---

Expand Down
1 change: 1 addition & 0 deletions analysis_options.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion android/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion ios/quicktype_dart.podspec
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion lib/entrypoint_cli.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion lib/quicktype_dart.dart
Original file line number Diff line number Diff line change
@@ -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
Expand Down
5 changes: 5 additions & 0 deletions lib/src/bundle_source.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<script src="…">` load from.
Expand Down
2 changes: 2 additions & 0 deletions lib/src/config.dart
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ import 'utils/logging.dart';
/// Thrown when a `quicktype.json` can't be parsed or is semantically invalid.
@immutable
class ConfigException implements Exception {
/// Creates a config-load failure with a human-readable [message] and
/// an optional underlying [cause].
const ConfigException(this.message, [this.cause]);

/// Human-readable description of the failure.
Expand Down
14 changes: 13 additions & 1 deletion lib/src/facade.dart
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,19 @@ import 'models/type.dart';
/// * [process] — require shelling out to the `quicktype` Node CLI.
/// Throws on Flutter Web (`dart:io` unavailable). Useful for native
/// dev tooling or environments where the FFI plugin isn't built.
enum GenerateTransport { auto, ffi, process }
enum GenerateTransport {
/// Default. Picks the best-available transport per platform (FFI on
/// native, web on browser, Process as the last-resort fallback).
auto,

/// Force the in-process QuickJS FFI runtime. Fastest after warm-up;
/// unavailable on web.
ffi,

/// Force the `quicktype` Node CLI subprocess. Unavailable on web;
/// requires `npm install -g quicktype` or the bundled tool/ setup.
process,
}

/// Entry point for ad-hoc, runtime JSON → typed-code conversion.
///
Expand Down
Loading
Loading