nebula_api_studio 0.1.0

A professional Dart/Flutter package combining a Compiler + Runtime SDK. Convert OpenAPI 3.x / Swagger 2.0 specs into fully type-safe Dart SDKs with smart caching, retry policies, a plugin system, offl [...]

Changelog

All notable changes to Nebula API Studio are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

Unreleased

Planned

• WebSocket endpoint support in the compiler and runtime
• File-upload helpers (multipart/form-data) in NebulaClient
• nebula_offline companion package with persistent SQLite queue
• GraphQL spec parser
• Freezed integration option for generated models
• dart pub publish CI workflow

---

1.0.0 — 2024-01-15

Added

Compiler

• OpenApiParser — full OpenAPI 3.0 / 3.1 spec parser producing a typed AST
• SwaggerParser — Swagger 2.0 / 2.x spec parser
• ParserInterface — extensible base for custom spec formats
• ApiAst — root intermediate representation node
• ApiEndpoint — endpoint node with method, path, parameters, request body and response type
• ApiModel — model/schema node with typed fields
• ApiType — primitive, object, array and enum type nodes with nullable flag
• NameNormalizer — snake_case / kebab-case / PascalCase / camelCase conversions with Dart reserved-keyword escaping
• NullSafetyInferrer — promotes required fields to non-nullable, optional fields to nullable
• SchemaDeduplicator — removes exact duplicate schemas; renames structural conflicts
• CodeEmitter — low-level string buffer with indentation helpers
• ModelGenerator — emits null-safe Dart model classes with fromJson / toJson, copyWith, == and hashCode
• EnumGenerator — emits Dart enums with fromJson / toJson helpers
• ServiceGenerator — emits typed service classes backed by NebulaClient
• NebulaCompiler façade — orchestrates parse → optimize → generate pipeline

Runtime

• Result<T> — typed success/failure monad with map, flatMap, when, getOrElse
• ApiError — structured error with code, message, statusCode, details, isClientError, isServerError
• ApiRequest — immutable request value object with copyWith and fullUrl helpers
• ApiResponse — immutable response with isSuccess and typed body
• NebulaClient — single HTTP execution entry point with plugin chain, cache and retry
• HttpAdapter — interface for swapping HTTP implementations
• DefaultAdapter — production dart:io HTTP adapter
• MemoryCache — in-memory LRU cache with per-entry TTL
• CacheProvider — abstract cache interface
• CachePolicy — per-client cache configuration with configurable cacheable methods
• InvalidationGraph — tag-based dependency graph with cascading invalidation
• RetryPolicy — declarative retry configuration with per-status-code control
• ExponentialBackoff — exponential delay calculator with optional ±25 % jitter
• RetryEngine — transparent retry orchestration wrapping any Future<ApiResponse>
• ApiPlugin — interceptor interface (beforeRequest, afterResponse, onError)
• PluginChain — ordered plugin pipeline with correct request/response ordering
• AuthPlugin — Bearer / API-key / custom-scheme authentication header injector
• LoggingPlugin — structured request/response logger with debug / info / warn / error levels
• AnalyticsPlugin — fires analytics events on every request/response cycle
• RequestQueue — offline request queue with priority and persistence hooks
• SyncEngine — connectivity-aware queue flusher

CLI

• bin/nebula.dart — CLI entry point powered by package:args
• generate command — one-shot code generation from spec file
• watch command — incremental regeneration using package:watcher
• init command — project scaffolding with nebula.config.json template
• doctor command — environment health check (Dart SDK, wrangler, config validity)
• ConfigLoader — JSON config reader with CLI override merging and schema validation
• Watcher — file-system watcher abstraction over package:watcher

Public API

• lib/nebula_api_studio.dart — single barrel export for all public symbols

Example

• example/swagger.yaml — complete Pet Store OpenAPI 3.0 spec (pets, owners, orders, enums, nested models)
• example/nebula.config.json — annotated configuration example
• example/main.dart — end-to-end demo: mock adapter, plugin chain, CRUD operations, Result chaining, cache stats

Tests

• test/compiler/ast_test.dart — AST construction and ApiType primitives
• test/compiler/parser_test.dart — OpenAPI 3.x and Swagger 2.0 parsing (12 test cases)
• test/compiler/optimizer_test.dart — NameNormalizer, NullSafetyInferrer, SchemaDeduplicator
• test/runtime/result_test.dart — Result<T>, ApiError, ApiRequest, ApiResponse
• test/runtime/client_test.dart — NebulaClient execution, plugins, retry and cache
• test/runtime/cache_test.dart — MemoryCache, CachePolicy, InvalidationGraph
• test/runtime/retry_plugin_test.dart — RetryPolicy, ExponentialBackoff, RetryEngine, PluginChain, AuthPlugin
• test/cli/config_loader_test.dart — ConfigLoader, NebulaConfig, all exception types

Documentation

• README.md — full documentation with architecture diagram, quick-start, API reference and contribution guide
• CHANGELOG.md — this file
• LICENSE — MIT license
• analysis_options.yaml — strict lint rules

---

0.9.0-beta — 2024-01-01

Added

• Initial beta release with compiler skeleton and basic runtime
• Proof-of-concept OpenAPI parser
• Result<T> monad prototype

Changed

• Restructured package layout to compiler / runtime / shared / cli

Removed

• Legacy api_client.dart monolithic file replaced by NebulaClient

---