Result Class API and Some Implementation Details

[DScheglov]

Instantiation

Minimize Direct Instantiation API Surface

The proposal currently offers four ways to instantiate results: two direct and two indirect.

1. Static factory methods (direct):

   const okResult = Result.ok(value);
   const errResult = Result.error(error);

2. Constructor (direct):

   const okResult = new Result(true, undefined, value);
   const errResult = new Result(false, error);

3. Static try method on a non-function/non-promise (indirect):

   const okResult = Result.try(value);

4. try operator on a non-function/non-promise (indirect):

   const okResult = try value;

Indirect ways can be flagged by linters as suboptimal. The preferred approach is the static factory methods (Result.ok, Result.error), which are concise and less error-prone.

The constructor approach introduces problems, especially for JS (non-TS) developers:

• value and error can be swapped, creating incorrect results.

• Using two arguments for errors encourages incorrect use for success cases.

• Ambiguity in specifying ok, error, and value:

  • ok: true/false, 1/0, "success"/"" etc.
  • error in ok-results: null, undefined, any ignored value.
  • value in error-results: same ambiguity.

• Non-intuitive behavior when both error and value are set.

Explicit new Result(...) must throw an error:

const result = new Result(...); // throws
const result = new (Result.ok()).constructor(...); // throws

Void Results

Factory methods must allow creating results without values:

const voidOk = Result.ok();
const voidErr = Result.error();

Useful when details don’t matter.

Instance Check

Both checks must return true:

Result.ok(..) instanceof Result
Result.error(..) instanceof Result

Properties

Result instances have three properties:

1. ok
2. error (only if ok is false)
3. value (only if ok is true)

Properties must be readonly. This prevents inconsistent states, e.g., ok true but with an error, or vice versa. Instances should also be sealed to prevent adding error to ok-results or value to error-results. This is especially important if discriminating with 'error' in result or 'value' in result is supported.

Instance Methods

Algebraic Data Types

Result models success/failure flows similar to other languages, supporting:

• Functor
• Monad
• Bi-Functor
• Bi-Monad

Required methods (like in Array):

class Result {
  map(mapValueFn, mapErrorFn?) {}
  mapError(mapErrorFn) {}

  flatMap(chainValueFn, chainErrorFn?) {}
  flatMapError(chainErrorFn) {}

  flat() {}
}

Optional combined naming (like in Promise):

class Result {
  andThen(handleValue, handleError?) {}
  orElse(handleError) {}
}

Unwrapping Methods

Direct field access is preferred, but unwrapping is useful, especially for TS developers:

const value = result.unwrap(); // returns value or throws TypeError with cause=result

Unwrap methods:

class Result {
  unwrap(options?) {}
  unwrapError(options?) {}
}

options can:

• Provide a default:

  result.unwrap({ default: 'fallback' });

• Provide an expected error message:

  result.unwrap({ expect: 'Error Message' });

• Handle error explicitly:

  result.unwrap({ onError(error) {
    console.error(error);
    return 'fallback';
  }});

A match method is also recommended:

class Result {
  match(onOk, onError) {}
}

Example:

app.post('/some-resource', (req, res) => {
  res.json(
    someService.doSomething().match(
      value => ({ status: 'success', data: value }),
      error => ({ status: 'error', error: error.message }),
    ),
  );
});

Static Methods

Currently proposed static methods:

• ok
• error
• try

Additional methods for arrays/tuples of results:

• collect – returns an ok result with an array of values if all are ok, or the first non-ok result.
• collectRight – same as collect, but returns the last non-ok result instead of the first.

Implementation

It is recommended to implement two separate classes instead of one generic Result:

• OkResult – represents a successful result.
• ErrorResult – represents an error result.

This simplifies method implementations by removing the need for branching logic inside every method. Each subclass can implement its own version of map, flatMap, unwrap, etc., without runtime checks. Factory methods (Result.ok, Result.error) return instances of these classes, but they share a common base class Result to ensure instanceof Result works consistently.

[arthurfiorette]

I'm not sure about the idea of throwing when new Result().

Imagine code that converts any result-like into a native result:

declare let download: { data: any; error: null } | { data: null, error: any }

const nativeResult = new Result(!!download.data, download.error, download.data)

which has a higher readability in this case.

Anyways, thousand of possibilities showing that restricting the constructor does not serves any purpose.

[arthurfiorette]

About algebraic functions, I like it but don't think it fits in the proposal that introduces Result, but instead a later proposal like "ECMAScript Result Algebraic Methods". Less stuff for now = higher chance of it being accepted

[arthurfiorette]

I like the idea of it being readonly, I'd love a PR pushing this change to both this proposal and https://github.com/arthurfiorette/try.

I'm also ok for "sacrificing" 'error' in result-like checks to ensure there will always be a error and value as readonly properties. Both defined, only one with actual value.

[ljharb]

Result.try would take a function to invoke (like Promise.try), not a value.

and, there's absolutely nothing suboptimal about it, just like there's not for Promise.try.

[ljharb]

Also, if new Result throws, it basically means it's not subclassable, so I don't think that's a viable path.

[DScheglov]

Also, if new Result throws, it basically means it's not subclassable, so I don't think that's a viable path.

common ... it is the JS )

class ResultOk {
  construct() {
     throw new Error('ResultOk is not constructor');
  }
}
Object.defineProperty(ResultOk, 'name', { value: 'Result.ok' });

const Result = class {
  static ok(value) {
    return Object.freeze(Object.setPrototypeOf({ ok: true, value }, ResultOk.prototype))
  }
}
Object.setPrototypeOf(ResultOk.prototype, Result.prototype);

[ljharb]

you would definitely never want to do that - Object.create is very bad and should be avoided anywhere, and Object.setPrototypeOf is a performance cliff in most engines. You'd want:

class MyResult extends Result {}

to Just Work, without having to define a constructor.

[DScheglov]

@arthurfiorette

declare let download: { data: any; error: null } | { data: null, error: any }
const nativeResult = new Result(!!download.data, download.error, download.data)

Common pattern. Perfectly covered with:

declare let download: { data: any; error: null } | { data: null, error: any }

const nativeResult = !!download.data
  ? Result.ok(download.data)
  : Resul.error(download.error)

It is a little bit more verbose, but it is definitely more readable.

[DScheglov]

you would definitely never want to do that - Object.create is very bad and should be avoided anywhere, and Object.setPrototypeOf is a performance cliff in most engines. You'd want:

class MyResult extends Result {}
to Just Work, without having to define a constructor.

What does it mean??
For both classes the empty constructors are defined.

There is another way to make the constructor private:

const $private = Symbol('private');

class Result {
  static ok(value) {
    return new ResultOk($private, value);
  }
  constructor(private) {
     if (private !== $private) {
       throw Error('Result is not a constructor');
     }
  }
}

class ResultOk extends Result {
  constructor(private, value) {
     if (private !== $private) {
       throw Error('ResultOk is not a constructor');
     }
    super(private);
    Object.defineProperties(this, {
      ok: { value: true, writable: false, configurabe: false, enumarable: false },
      value: { value, writable: false, configurabe: false, enumarable: true },
    });
  }
}

[DScheglov]

...
Object.setPrototypeOf is a performance cliff in most engines. ...
...

About the implementation and performance:
https://github.com/DScheglov/try-to-result/tree/main/benchmark

I'm not sure that it is absolutelly correct benchmark -- i.e. it is just a draft for that.
But it looks like setPrototypeOf doesn't cause performance penalties.

[ljharb]

The language doesn't have "private constructors" for objects, and we shouldn't be proposing one. There's nothing wrong with new Result, and if the boolean arguments aren't clear, then we can use a different argument style.

[DScheglov]

The language doesn't have "private constructors" for objects, and we shouldn't be proposing one. There's nothing wrong with new Result, and if the boolean arguments aren't clear, then we can use a different argument style.

Common ...

• BigInt
• Symbol

And the language allows to emulate the private constructors with the approach shown above.

Also JS has constructors that everyone dreams to have as private:

• String
• Number
• Boolean

We never use new String(), new Number() and so on...

So, actually it is absolutely normal for new features to have "private" constructors.