catalyst 2.0.2

GitHub license Travis Pub Coverage Status

Catalyst #

Catalyst is a dependency injection container for the dart language. It's fast, reliable and easy to understand.

📦 Installation #

Add the following to your pubspec.yaml:

dependencies:
  catalyst: ^2.0.2

Then run pub get

💡 Usage #

Importing #

import 'package:catalyst/catalyst.dart';

Register Services #

To register a service you have to call the register-method.

Container.register(String id, dynamic service, [List<dynamic> arguments])
ParameterDescriptionExample
idThe unique id of the serviceapp.my_service
serviceThe service target(int a) => a * 2
argumentsThe arguments for the service. Entries with @-prefix are service references[1, 'foo', bar]

Register a service with static arguments #

Since not all services need an service injection, the arguments array also supports static entries.

Container container = new Container();

container.register('app.my_service', (String name) {
  return 'Hello $name';
}, ['Your Name']);

var knownServices = container.registeredServices; // Contains the registered Service 

Register a service with a service dependency #

In most cases you need another registered service in your service. In that case you can pass the service name with a @-prefix to reference to it. The (sub-) dependencies are solved recursively.

Container container = new Container();

container.register('app.another_service', () {
  return {'name': 'Jane', 'age': '24'};
});

container.register('app.my_service', (dynamic anotherService) {
return "Name: ${anotherService['name']}, Age: ${anotherService['age']}";
}, ['@app.another_service']);

print(container.get('app.my_service')); // Outputs "Name: Jane, Age: 24"

Register a class as a service #

You can also register a class as a service. If the service is loaded, the constructor gets called with the dependencies.

main() {
  Container container = new Container();

  // Register the first service
  container.register('namer', () => 'John Doe');

  // Register the second service. The constructor will be called with the passed arguments
  container.register('greeter', Greeter, ['@namer']);

  // Retrieve the greeter
  var greeter = container.get('greeter');

  // Greet
  print(greeter.greet()); // Outputs "Hello, my Name is John Doe!"
}

class Greeter {
  String name;

  Greeter(this.name) {}

  String greet() {
    return "Hello, my Name is $name!";
  }
}

Load a service #

To load a service you have to call the get-method.
Once a service is loaded, it remains in memory at runtime. When the same service is loaded again, the first instance is returned.

Container.get(String id)
ParameterDescriptionExample
idThe unique id of the service.app.my_service
Container container = new Container();

// Register the first service
container.register('namer', () => 'Catalyst');

container.get('namer'); // returns "Catalyst"

Add Parameters #

The service container also supports static parameters.
You can add a parameter using the addParameter-method

Container.addParameter(String name, dynamic value)
ParameterDescriptionExample
nameThe unique name of the parameter.database.host
valueThe parameter valuelocalhost

To pass a parameter to a service, add before and after the name a '%': %name.of.the.parameter%

Container container = new Container();
container.addParameter('database.host', 'localhost');

container.register('db.context', (String hostname) {
return 'Connecting to $hostname';
}, ['%database.host%']);

print(container.get('db.context')); // Outputs "Connecting to localhost"

🔌 Service auto wiring #

Catalyst supports auto wiring of services. That means, that you only need to register the service without passing depending service names as arguments. (Strong typing is required).

For example:

main() {
  Container container = new Container();
  container.register('greeter', SimpleGreeter);
  container.register('greeting_printer', (SimpleGreeter greeter) {
    print(greeter.greet('Catalyst'));
  });

  container.get('greeting_printer'); // Outputs "Hello from Catalyst!"
}

class SimpleGreeter {

  String greet(String name) {
    return "Hello from $name!";
  }
}

You can disable this behaviour with setting Container.autoWire = false;

🔬 Testing #

$ pub run test

🤝 Contribute #

Feel free to fork and add pull-requests 🤓

2.0.2 #

  • Copyright updated
  • Travis fixed
  • Fix lib/container.dart. (-0.50 points): line 132 col 13: Don't explicitly initialize variables to null.
  • Fix lib/service.dart. (-0.50 points): line 50 col 13: Use isNotEmpty instead of length
  • isInstanceOf<T> replaced by TypeMatcher<T>
  • analysis_options.yaml added

2.0.0 / 2.0.1 #

  • SDK version constraint updated
  • Test version updated

1.1.1 #

Tests fixed

  • Using Exception.toString() instead of accessing the message property

1.1.0 #

Code refactored

  • Container.get() method splitted into multiple methods
    • _loadAndRetrieveService() loads the service and stores it in the _loadedServices property
    • _injectServicesAndParameters() fetches the @foobar services and %foo_bar% parameters and inject them
    • _doAutoWire() auto wires the injections
  • Service.getMetadata() and Service.targetMirror added

1.0.0 #

  • First Release
  • Example code in /example added

0.0.2 #

  • Auto wiring implemented (See "Service auto wiring" in the README)

0.0.1 #

  • Initial release

example/main.dart

/*
 * This file is part of the Catalyst package.
 *
 * Copyright 2018-2019 by Julian Finkler <julian@mintware.de>
 *
 * For the full copyright and license information, please read the LICENSE
 * file that was distributed with this source code.
 */

import 'package:catalyst/catalyst.dart';

main() {
  Container container = new Container();

  // Register the StackAsAService in the container
  container.register('shared_stack', StackAsAService);

  // Get the registered service from the container
  StackAsAService stack = container.get('shared_stack');

  // Modify the stack
  print(stack.length); // Outputs 0

  stack.add("Hello");
  stack.add("World");

  print(stack.length); // Outputs 2

  print(stack.entries); // Outputs [Hello, World]

  // Retrieve the  same service again from the container
  StackAsAService anotherStack = container.get('shared_stack');

  print(anotherStack.length); // Outputs 2

  print(anotherStack.entries); // Outputs [Hello, World]

  // Modify it...
  anotherStack.remove('World');

  // And the first variable is also modified
  print(stack.length); // Outputs 2

  print(stack.entries); // Outputs [Hello]
}

class StackAsAService {
  List<String> _entries = new List<String>();

  void add(String entry) {
    _entries.add(entry);
  }

  void remove(String entry) {
    _entries.removeWhere((e) => e == entry);
  }

  List<String> get entries => _entries;

  int get length => _entries.length;
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  catalyst: ^2.0.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:catalyst/catalyst.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
50
Learn more about scoring.

We analyzed this package on Jul 17, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: web, other

Primary library: package:catalyst/catalyst.dart with components: mirrors.

Health suggestions

Fix lib/catalyst.dart. (-0.50 points)

Analysis of lib/catalyst.dart reported 1 hint:

line 10 col 9: Name libraries using lowercase_with_underscores.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.54.0 <3.0.0
Dev dependencies
test 1.3.0

Admin