nebula_api_studio 0.1.1

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 [...]

🌌 Nebula API Studio

A complete Dart/Flutter toolkit for consuming REST APIs — from OpenAPI/Swagger spec to production-ready client code, with a powerful runtime layer.

---

Table of Contents

• Overview
• Features
• Architecture
• Installation
• Quick Start
• CLI Usage
• Runtime Configuration
• Plugins
• Caching
• Retry & Resilience
• Offline Support
• Code Generation
• Configuration Reference
• Testing
• Contributing
• Changelog
• License

---

Overview

Nebula API Studio is a monolithic Dart package that covers the entire API lifecycle:

Layer	What it does
Compiler	Parses OpenAPI 3.x / Swagger 2.0 specs → builds an AST → optimizes → emits null-safe Dart code
Runtime	NebulaClient with plugin chain, caching, retry, offline queue and a typed Result<T> monad
CLI	nebula generate, nebula watch, nebula init, nebula doctor commands

---

Features

Compiler

• ✅ OpenAPI 3.0 / 3.1 parser
• ✅ Swagger 2.0 parser
• ✅ AST-based intermediate representation
• ✅ Name normalizer (snake_case → PascalCase / camelCase, reserved-keyword escaping)
• ✅ Null-safety inferrer (required fields → non-nullable, optional → nullable)
• ✅ Schema deduplicator (removes exact duplicates, renames structural conflicts)
• ✅ Code emitter (models, enums, services)
• ✅ Pluggable parser interface for custom spec formats

Runtime

• ✅ NebulaClient — single entry point for all HTTP calls
• ✅ Result<T> monad — no more uncaught exceptions
• ✅ Typed ApiError with status code, machine-readable code and details map
• ✅ HttpAdapter interface — swap real HTTP for mocks in tests
• ✅ Plugin chain — AuthPlugin, LoggingPlugin, AnalyticsPlugin + custom
• ✅ MemoryCache with TTL and LRU eviction
• ✅ CachePolicy — configurable per-method caching
• ✅ InvalidationGraph — tag-based cascading cache invalidation
• ✅ RetryPolicy + ExponentialBackoff (with optional jitter)
• ✅ RetryEngine — transparent retry orchestration
• ✅ Offline RequestQueue + SyncEngine for mobile resilience

CLI

• ✅ nebula generate — one-shot code generation
• ✅ nebula watch — incremental regeneration on file change
• ✅ nebula init — scaffold a new project with nebula.config.json
• ✅ nebula doctor — environment health check
• ✅ ConfigLoader — JSON config with CLI overrides

---

Architecture

nebula_api_studio/
├── lib/
│   ├── nebula_api_studio.dart        ← Public API barrel
│   ├── cli/
│   │   ├── commands/
│   │   │   ├── generate_command.dart
│   │   │   ├── watch_command.dart
│   │   │   ├── init_command.dart
│   │   │   └── doctor_command.dart
│   │   ├── config_loader.dart
│   │   └── watcher.dart
│   └── src/
│       ├── compiler/
│       │   ├── ast/                  ← ApiAst, ApiEndpoint, ApiModel, ApiType
│       │   ├── parser/               ← ParserInterface, OpenApiParser, SwaggerParser
│       │   ├── optimizer/            ← NameNormalizer, NullSafetyInferrer, SchemaDeduplicator
│       │   ├── generator/            ← CodeEmitter, ModelGenerator, EnumGenerator, ServiceGenerator
│       │   └── nebula_compiler.dart  ← Compiler façade
│       ├── runtime/
│       │   ├── core/                 ← Result, ApiError, ApiRequest, ApiResponse
│       │   ├── client/               ← NebulaClient, HttpAdapter, DefaultAdapter
│       │   ├── cache/                ← CacheProvider, MemoryCache, CachePolicy, InvalidationGraph
│       │   ├── retry/                ← RetryPolicy, ExponentialBackoff, RetryEngine
│       │   ├── plugins/              ← ApiPlugin, PluginChain, AuthPlugin, LoggingPlugin, AnalyticsPlugin
│       │   └── offline/              ← RequestQueue, SyncEngine
│       └── shared/
│           ├── nebula_config.dart
│           └── exceptions.dart
├── bin/
│   └── nebula.dart                   ← CLI entry point
├── example/
│   ├── main.dart                     ← Full usage demo
│   ├── swagger.yaml                  ← Pet Store OpenAPI spec
│   └── nebula.config.json            ← Example config
└── test/
    ├── compiler/                     ← ast_test, parser_test, optimizer_test
    ├── runtime/                      ← result_test, client_test, cache_test, retry_plugin_test
    └── cli/                          ← config_loader_test

---

Installation

Add to your pubspec.yaml:

dependencies:
  nebula_api_studio: ^1.0.0

Or for CLI usage, activate globally:

dart pub global activate nebula_api_studio

---

Quick Start

1 — Generate code from a spec

# Create nebula.config.json in your project root
nebula init

# Edit nebula.config.json to point to your spec
# Then generate
nebula generate

2 — Use the runtime client

import 'package:nebula_api_studio/nebula_api_studio.dart';

final client = NebulaClient(
  adapter: DefaultAdapter(),
  config: NebulaConfig(
    baseUrl: 'https://api.example.com/v1',
    timeout: const Duration(seconds: 30),
    defaultHeaders: {'Accept': 'application/json'},
  ),
  plugins: [
    AuthPlugin(
      tokenProvider: () async => await getAccessToken(),
      headerName: 'Authorization',
      scheme: 'Bearer',
    ),
    LoggingPlugin(logRequests: true, logResponses: true),
  ],
  retryPolicy: RetryPolicy(
    maxAttempts: 3,
    retryOn: {408, 429, 500, 502, 503, 504},
    backoff: ExponentialBackoff(
      initialDelay: const Duration(milliseconds: 200),
      multiplier: 2.0,
      maxDelay: const Duration(seconds: 10),
      jitter: true,
    ),
  ),
  cachePolicy: CachePolicy(
    enabled: true,
    ttl: const Duration(minutes: 5),
    maxEntries: 500,
  ),
);

// Execute a request
final result = await client.execute(
  ApiRequest(method: 'GET', path: '/pets/pet-001'),
);

result.when(
  success: (response) {
    final pet = Pet.fromJson(response.body as Map<String, dynamic>);
    print('Got pet: ${pet.name}');
  },
  failure: (error) {
    print('Error ${error.statusCode}: ${error.message}');
  },
);

// Always close when done
client.close();

3 — Result monad chaining

final names = (await petsService.listPets())
    .map((pets) => pets.map((p) => p.name).toList())
    .getOrElse([]);

print(names); // ['Buddy', 'Rio', 'Nemo']

---

CLI Usage

# Initialize a new project
nebula init [--output-dir lib/generated]

# Generate code (uses nebula.config.json in current directory)
nebula generate [--config path/to/nebula.config.json] [--verbose]

# Watch for spec changes and regenerate automatically
nebula watch [--config path/to/nebula.config.json]

# Check environment health
nebula doctor

---

Runtime Configuration

final config = NebulaConfig(
  baseUrl: 'https://api.example.com/v1',  // Required
  timeout: const Duration(seconds: 30),    // Default: 30s
  defaultHeaders: {                        // Merged into every request
    'Accept': 'application/json',
    'X-App-Version': '2.0.0',
  },
  connectTimeout: const Duration(seconds: 10),
  receiveTimeout: const Duration(seconds: 30),
);

---

Plugins

Plugins intercept the request/response lifecycle. Implement ApiPlugin:

class TimingPlugin implements ApiPlugin {
  final _stopwatches = <String, Stopwatch>{};

  @override
  Future<ApiRequest> beforeRequest(ApiRequest request) async {
    _stopwatches[request.path] = Stopwatch()..start();
    return request;
  }

  @override
  Future<ApiResponse> afterResponse(ApiRequest req, ApiResponse res) async {
    final elapsed = _stopwatches.remove(req.path)?.elapsedMilliseconds;
    print('${req.method} ${req.path} → ${res.statusCode} (${elapsed}ms)');
    return res;
  }

  @override
  Future<ApiError?> onError(ApiRequest req, ApiError error) async => error;
}

Built-in Plugins

Plugin	Purpose
AuthPlugin	Adds Bearer / API-key / custom auth headers
LoggingPlugin	Structured request/response logging with log-level control
AnalyticsPlugin	Fires events on every request for analytics backends

---

Caching

// Client-level policy
final client = NebulaClient(
  ...
  cachePolicy: CachePolicy(
    enabled: true,
    ttl: const Duration(minutes: 10),
    maxEntries: 1000,
    cacheableMethods: {'GET', 'HEAD'},
  ),
);

// Tag-based invalidation
final graph = InvalidationGraph();
graph.addDependency(tag: 'pets', invalidates: ['pet-list', 'pet-search']);
// Invalidating 'pets' automatically clears 'pet-list' and 'pet-search'

---

Retry & Resilience

final policy = RetryPolicy(
  maxAttempts: 4,
  retryOn: {408, 429, 500, 502, 503, 504},
  backoff: ExponentialBackoff(
    initialDelay: const Duration(milliseconds: 100),
    multiplier: 2.0,
    maxDelay: const Duration(seconds: 30),
    jitter: true,   // ±25% random jitter to avoid thundering herd
  ),
);

---

Offline Support

// The SyncEngine replays queued requests when connectivity is restored
final syncEngine = SyncEngine(
  queue: RequestQueue(),
  client: client,
  onSync: (result) => print('Synced: $result'),
);

// Register connectivity listener
connectivityStream.listen((isOnline) {
  if (isOnline) syncEngine.flush();
});

---

Code Generation

nebula.config.json

{
  "input": "swagger.yaml",
  "output": "lib/generated",
  "packageName": "my_api",
  "options": {
    "nullSafety": true,
    "generateModels": true,
    "generateServices": true,
    "generateEnums": true,
    "useJsonSerializable": true,
    "addCopyWith": true,
    "addEquality": true,
    "addToString": true,
    "dateTimeType": "DateTime",
    "enumSuffix": "Type",
    "serviceSuffix": "Service"
  },
  "runtime": {
    "baseUrl": "https://api.example.com/v1",
    "timeout": 30000,
    "retries": 3,
    "cacheEnabled": true,
    "defaultCacheDuration": 300,
    "offlineEnabled": true
  },
  "plugins": ["auth", "logging", "analytics"]
}

Generated file structure

lib/generated/
├── models/
│   ├── pet.dart
│   ├── owner.dart
│   ├── order.dart
│   └── address.dart
├── enums/
│   ├── pet_status_type.dart
│   ├── pet_category_type.dart
│   └── order_status_type.dart
└── services/
    ├── pets_service.dart
    ├── owners_service.dart
    └── orders_service.dart

---

Configuration Reference

Key	Type	Default	Description
input	string	—	Path to the OpenAPI/Swagger spec file (required)
output	string	lib/generated	Output directory for generated code
packageName	string	generated_api	Dart package name prefix for generated files
options.nullSafety	bool	true	Enable Dart null-safety annotations
options.generateModels	bool	true	Generate model classes
options.generateServices	bool	true	Generate service classes
options.generateEnums	bool	true	Generate enum types
options.useJsonSerializable	bool	true	Use json_serializable annotations
options.addCopyWith	bool	true	Add copyWith() to models
options.addEquality	bool	true	Add == / hashCode to models
options.enumSuffix	string	Type	Suffix appended to generated enum names
options.serviceSuffix	string	Service	Suffix appended to generated service names
runtime.baseUrl	string	—	Base URL injected into generated service constructors
runtime.timeout	int	30000	Default request timeout in milliseconds
runtime.retries	int	3	Default maximum retry attempts
runtime.cacheEnabled	bool	true	Enable response caching
runtime.defaultCacheDuration	int	300	Default cache TTL in seconds
runtime.offlineEnabled	bool	false	Enable offline request queue

---

Testing

# Run all tests
dart test

# Run with coverage
dart test --coverage=coverage
dart pub global run coverage:format_coverage \
  --lcov --in=coverage --out=coverage/lcov.info \
  --report-on=lib

# Run specific test file
dart test test/runtime/result_test.dart

# Run tests matching a pattern
dart test --name "RetryEngine"

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push to the branch: git push origin feat/my-feature
5. Open a Pull Request

Please run dart analyze and dart test before submitting.

---

Changelog

See CHANGELOG.md for the full history.

---

License

MIT © 2026 Nebula API Studio contributors. See LICENSE.