Dart — Libraries, Visibility & Package Architecture

// ── `as`: namespace prefix (avoid name clashes) ──
import 'package:http/http.dart' as http;
// http.get(...), http.post(...) — all http members are prefixed.

// ── `show`: import only specific names ──
import 'package:shelf/shelf.dart' show Request, Response, Pipeline;
// Only Request, Response, Pipeline are available — no Router, no logRequests.

// ── `hide`: import everything except specific names ──
import 'package:shelf/shelf.dart' hide logRequests;
// Everything except logRequests.

// ── Combining: prefix + show/hide ──
import 'package:shelf/shelf.dart' as shelf show Request, Response;

// ❌ Anti-pattern: name clash from two libraries exporting the same name.
import 'package:app_a/config.dart';  // exports Config
import 'package:app_b/config.dart';  // also exports Config
// Error: 'Config' is defined in both libraries.

// ✓ Correct: prefix one or both.
import 'package:app_a/config.dart';
import 'package:app_b/config.dart' as app_b;

void main() {
  var a = Config();       // app_a's Config
  var b = app_b.Config();  // app_b's Config
}

// A barrel file re-exports multiple libraries as a single import surface.
// Users import one file instead of many — clean API boundary.

// lib/models.dart — barrel file
export 'src/models/user.dart';
export 'src/models/post.dart';
export 'src/models/comment.dart';
export 'src/models/event.dart' show Event, ClickEvent;  // selective export

// User code:
import 'package:my_app/models.dart';  // gets User, Post, Comment, Event, ClickEvent

// ── Package public API barrel ──
// lib/my_package.dart — the single entry point for consumers
library my_package;

export 'src/core.dart';
export 'src/utils.dart' show StringUtils, DateUtils;
export 'src/types.dart';
// src/ is convention-private — users shouldn't import src/ directly.

// Conditional imports select an implementation at COMPILE TIME based on
// which dart: libraries are available. Zero runtime cost — the compiler
// includes only the matching file and dead-code-eliminates the other.

// platform.dart — public API (both implementations must export the same API)
export 'platform_io.dart'     // native: dart:io is available
    if (dart.library.html) 'platform_web.dart';  // web: dart:html is available

// platform_io.dart
import 'dart:io';
String get platformName => Platform.operatingSystem;
Future<List<int>> readFile(String path) => File(path).readAsBytes();

// platform_web.dart — same API, web implementation
import 'dart:html';
String get platformName => 'web';
Future<List<int>> readFile(String url) async {
  final response = await HttpRequest.request(url, responseType: 'arraybuffer');
  return (response.response as ByteBuffer).asUint8List();
}

// ── Using the conditional import ──
import 'platform.dart';  // resolves to io or web at compile time

void main() async {
  print(platformName);  // 'macos' on native, 'web' on web
  final bytes = await readFile('data.bin');
}

// ❌ Anti-pattern: importing dart:io directly in cross-platform code.
// import 'dart:io';  // ✗ fails on web — compile error

// `deferred as` loads a library on DEMAND (via loadLibrary()).
// Useful on web for code-splitting — smaller initial bundle.
// The library is downloaded only when loadLibrary() is called.

import 'heavy_editor.dart' deferred as editor;

void main() async {
  // The editor library is NOT loaded yet — smaller initial bundle.
  print('App started');

  // Load on demand (e.g., when user opens the editor):
  await editor.loadLibrary();  // downloads + compiles the library
  editor.openEditor();  // now available
}

// ── Flutter deferred components ──
// On Flutter mobile, deferred loading enables dynamic feature delivery
// (download features on demand). Configure in build.gradle / Info.plist.

// Limitations:
// - Can't use deferred types at compile time before loadLibrary().
// - `editor.Editor` is available as a type, but instantiating before
//   loadLibrary() throws.

# In a monorepo, packages depend on each other via path: dependencies.
# pubspec.yaml for my_service/
dependencies:
  shared_models:
    path: ../shared_models  # relative path to the sibling package
  my_lib:
    path: ../../packages/my_lib

# ── Melos for monorepo management ──
# For large monorepos, use `melos` to manage multiple packages:
# melos bootstrap — run `pub get` for all packages
# melos exec -- dart test — run tests in all packages
# melos publish — publish all packages

# Bootstrap a monorepo (install deps for all packages):
dart pub global activate melos
melos bootstrap

# Run a command in all packages:
melos exec -- dart analyze
melos exec -- dart test

# The root melos.yaml configures the workspace:
# packages:
#   - 'packages/*'
#   - 'apps/*'