oxidized 3.1.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 58

oxidized #

A Dart package with types similar to those found in Rust, such as the Result which represents either a value or an error, and Option which either contains Some value or None.

Motivation #

The Option and Result types are akin to the "sum types" found in languages such as OCaml and Rust. They encourage safer code by making errors and possible "null" values (i.e. None) a necessary part of the code flow, requiring you to deal with these cases appropriately. For an illustration of how this style of coding can prove to be helpful, see the excellent tutorial series by Matt Rešetá Flutter TDD Clean Architecture Course – Entities & Use Cases in which he uses the Either type from the dartz package to represent either a success or a failure. The Result type in this package is specifically designed for this purpose, making it easy to remember which part is the "success" and which is the "failure" (imagine trying to remember "Is the right side the failure? Or was it the left?").

Usage #

A simple example using synchronous I/O to avoid nested futures is shown below. For additional examples, see the Dart code in the example directory.

import 'dart:io';
import 'package:oxidized/oxidized.dart';

Result<String, Exception> readFileSync(String name) {
  return Result.of(() {
    return File(name).readAsStringSync();
  });
}

void main() {
  var result = readFileSync('README.md');
  result.match((text) {
    print('first 80 characters of file:\n');
    print(text.substring(0, 80));
  }, (err) => print(err));
}

Prior Art #

The dartz package offers many functional programming helpers, including the Either type, which is similar to Result, with the difference being that it represents any two types of values.

The either_option package has both Either and Option and supports all of the typical functional operations.

The result package offers a few basic operations and may be adequate for simple cases.

The rust_like_result offers a simple Result type similar to the one in Rust.

The simple_result package provides a similar Result type based on the type of the same name in Swift.

Change Log #

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning. This file follows the convention described at Keep a Changelog.

[3.1.0] - 2020-03-22 #

Added #

  • Add fold() function on Result that combines map() and mapErr().

[3.0.1] - 2020-03-18 #

Changed #

  • Fix the package description and code formatting.

[3.0.0] - 2020-03-18 #

Changed #

  • BREAKING CHANGES: see below for the details.
  • The Result "ok" and "error" values are full-fledged classes now.
  • The Option "some" and "none" values are full-fledged classes now.
  • Option.isSome() and Option.isNone() are gone, use is Some and is None.
  • Result.isOk() and Result.isErr() are gone, use is Ok and is Err.
  • The default Result constructor has been renamed to of() instead.
  • Passing null to the Option.some() factory constructor will yield a None.
  • Both the Ok and Err subclasses of Result allow for null arguments.

[2.0.0] - 2020-03-14 #

Added #

  • Borrowing from simple_result, added when() as an alternative to match().

Changed #

  • BREAKING CHANGE: the various is methods are now getters.
  • Extend Equatable in both Option and Result.
  • Override the equals operator (==) in both Option and Result.

[1.0.0] - 2020-03-09 #

Added #

  • Initial version

example/oxidized_example.dart

import 'dart:io';
import 'package:oxidized/oxidized.dart';

Result<String, Exception> readFileSync(String name) {
  return Result.of(() {
    return File(name).readAsStringSync();
  });
}

Future<Result<Future<String>, Exception>> readFile(String name) async {
  return Result.of(() async {
    return await File(name).readAsString();
  });
}

void main() async {
  var result = readFileSync('README.md');

  // you can use `is` like so
  if (result is Err) {
    print('oh no, unable to read the file!');
  } else {
    print('read the file successfully');
    // it is safe to call .unwrap() here
  }

  // or you can use the match function
  result.match((text) {
    print('first 80 characters of file:\n');
    print(text.substring(0, 80));
  }, (err) => print(err));

  // using the "catching" constructor with futures is also feasible
  var futureResult = await readFile('LICENSE');
  futureResult.when(
    ok: (text) async {
      var text = await futureResult.unwrap();
      print('\nlength of LICENSE file: ${text.length}');
    },
    err: (err) => print(err),
  );
}

Use this package as a library

1. Depend on it

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


dependencies:
  oxidized: ^3.1.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

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

3. Import it

Now in your Dart code, you can use:


import 'package:oxidized/oxidized.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
16
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]
58
Learn more about scoring.

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

  • Dart: 2.8.4
  • pana: 0.13.15

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
equatable ^1.1.1 1.2.2
Transitive dependencies
collection 1.14.13 1.15.0-nullsafety
meta 1.2.2 1.3.0-nullsafety
Dev dependencies
pedantic ^1.8.0
test ^1.6.0