server_contracts 0.1.1

Framework-agnostic contracts for auth, data, config, and translation server packages.

server_contracts

Framework-agnostic contracts for server ecosystem packages.

server_contracts is the dependency boundary package for the server ecosystem. It defines shared interfaces and value contracts used by runtime packages such as server_data, server_auth, and framework adapters (for example, Routed or Shelf integrations).

Scope

This package intentionally contains only contract artifacts:

• abstract interfaces
• typedefs and callback signatures
• value contracts
• contract-level exceptions

This package must not contain concrete runtime implementations.

It never initializes a Routed engine or service provider. Use the relevant Routed adapter, such as routed_cache, routed_sessions, or routed_storage, when these contracts need to participate in a Routed application.

Installation

dependencies:
  server_contracts: ^0.1.0

Exports

• package:server_contracts/cache.dart
  • Store, Repository, Factory, Lock, LockProvider
• package:server_contracts/config.dart
  • Config
• package:server_contracts/translation.dart
  • TranslationLoader, TranslatorContract

Typical usage

Use server_contracts for framework-agnostic signatures and extension points. Concrete runtime behavior should be implemented by other packages.

import 'package:server_contracts/server_contracts.dart';

Future<String> readHealth(Repository repository) async {
  final value = await repository.get('health');
  return value?.toString() ?? 'unknown';
}

Package Selection

• Use server_contracts when you need interfaces only.
• Use server_data when you need concrete cache/storage/session/rate-limit implementations.
• Use server_auth when you need auth providers, JWT, callbacks, and authorization primitives.

Migration Notes

If older code imported these contracts from package:routed_core/routed_core.dart, switch to direct imports from server_contracts to avoid framework coupling.

Contract implementation example

Runnable example:

dart run example/main.dart

See example/main.dart for:

• a minimal Config implementation
• an in-memory Store and Repository
• a lightweight TranslatorContract implementation

See example/README.md for run instructions and expected output.

Design rules

• Keep contracts small and stable.
• Do not import framework runtimes here.
• Move concrete behavior to dedicated runtime packages.

Adapter checklist

When creating a framework adapter package (for Routed, Shelf, Serinus, etc.):

• Define framework-facing bridge types in the adapter package, not here.
• Depend on server_contracts for interfaces and typed boundaries.
• Keep framework runtime imports out of contract models and exceptions.
• Place concrete runtime behavior in server_data or server_auth.

Validation

dart analyze
dart test
dart run example/main.dart

License

MIT