TS +の場合

A fluent API in TypeScript might look something like:

export class IO<A> {
  static succeed = <A>(a: A) => new IO(() => a);
  static succeedWith = <A>(a: () => A) => new IO(a);

  private constructor(readonly io: () => A) {}

  map<A, B>(this: IO<A>, f: (a: A) => B): IO<B> {
    return new IO(() => f(this.io()));
  }

  flatMap<A, B>(this: IO<A>, f: (a: A) => IO<B>): IO<B> {
    return new IO(() => f(this.io()).io());
  }

  zip<A, B>(this: IO<A>, b: IO<B>): IO<[A, B]> {
    return new IO(() => [this.io(), b.io()]);
  }

  run<A>(this: IO<A>) {
    return this.io();
  }
}

which can be used like:

export const program = IO.succeed(0)
  .map((n) => n + 1)
  .flatMap((r) =>
    IO.succeedWith(() => {
      console.log(`result: ${r}`);
    })
  );

program.run();

In this approach we have a data-type IO<A> together with a "companion object" IO . This approach lends itself to a certain organization of code:

• Constructors like succeed and succeedWith are placed in the "companion object" as static members
• Methods like map , flatMap , and zip are placed in the class instance as members of the type IO<A>

This approach is very common in object-oriented languages and its advantages lie in the ease of use. In fact, for the user of such a module, the editor experience is beautiful - if you want to construct an IO you type IO. and get a full list of suggestions on ways you can construct an IO . In addition, when you want to do something with a value of type IO<A> , you type value. and you are again prompted with a nice list of options.

This fluent type of API is "a dream", but also has a few drawbacks that have led the biggest part of the FP community away from it.

The limitations are staggering:

• All methods have to be inside the class (or inside a common abstract class for ADTs)
• Once a class is defined adding methods to it from the outside requires module augmentation and unsafe mutation of object prototypes
• Worst of all, none of it can be optimized from a tree shaking perspective, so you'll end up with a huge bundle size that becomes prohibitive at a certain point

The current "solution" that the FP community has adopted is the use of pipeable APIs.

In a pipeable API we would rewrite the prior example to:

// file: IO.ts
export class IO<A> {
  constructor(readonly io: () => A) {}
}

export const succeed = <A>(a: A) => new IO(() => a);

export const succeedWith = <A>(a: () => A) => new IO(a);

export function map<A, B>(f: (a: A) => B): (self: IO<A>) => IO<B> {
  return (self: IO<A>) => new IO(() => f(self.io()));
}

export function flatMap<A, B>(f: (a: A) => IO<B>): (self: IO<A>) => IO<B> {
  return (self) => new IO(() => f(self.io()).io());
}

export function zip<A, B>(b: IO<B>): (self: IO<A>) => IO<[A, B]> {
  return (self) => new IO(() => [self.io(), b.io()]);
}

export function run<A>(self: IO<A>) {
  return self.io();
}

// file: Function.ts

// omitted definition of pipe due to its length
// For the curious, take a look at https://github.com/Effect-TS/core/blob/master/packages/system/src/Function/pipe.ts

// file: Program.ts
import * as IO from "./IO";
import { pipe } from "./Function";

export const program = pipe(
  IO.succeed(0),
  IO.map((n) => n + 1),
  IO.flatMap((r) =>
    IO.succeedWith(() => {
      console.log(`result: ${r}`);
    })
  )
);

IO.run(program);

What we have essentially done is extracted all the constructors and methods outside of the class, and moved the this parameter to be a normal curried function parameter that the pipe function will carry through each function call.

The resulting API is still quite nice visually, but it does have a few drawbacks.

First of all, auto-imports do not work well with namespaced imports (recently folks at Unsplash have been ). Even if you do get auto-imports to work, you'll end up with tons of imports.

Additionally, we have lost the meaning and categorization of IO - namely we no longer have a data-type IO<A> and a "companion object" IO . We now only have a data-type IO<A> and a module of functions that include both constructors, such as IO.succeed , and pipeable functions (which are also called aspects), such as IO.flatMap . So when programming a user needs to know exactly which module to import, exactly which functions are constructors of the datatype and which are methods for the datatype, and exactly how to use them.

Finally, having had the experience of teaching those concepts to other developers, it seems fairly common that folks sometimes have issues reading pipeable function signatures.

TS+ is a new language developed as a super-set of TypeScript and maintained as a fork of the original TypeScript compiler that is rebased daily.

In order to guarantee full support with the TypeScript ecosystem, we limit what can be extended. TS+ emits standard declaration files consumable from plain TypeScript and consumes plain definition files. TS+ also does not add any new syntax.

TS+ diverges from TypeScript in that we do not limit ourselves from emitting code using type information. Instead, we leverage the type information as much as possible to produce both highly optimized code and improve the developer experience.

With those decisions comes a set of trade-offs. TS+ can be compiled only with the TS+ compiler (a fork of tsc ) and cannot be compiled by tools like babel which "simply" remove the types.

We suggest using a compilation pipeline where tsc emits ES2022 modules, followed by another tool such as esbuild / swc / babel that takes over from there leveraging the powerful infrastructure of project references to optimize compilation.

To install TS+, you must first add it as a dev dependency with:

yarn add -D @tsplus/installer
# or
npm i -D @tsplus/installer

Then, you can add a postinstall script to your package.json . For example:

{
  "scripts": {
    "postinstall": "tsplus-install"
  }
}

This will replace the TypeScript that is installed in your node_modules with the TS+ version.

Note: this install process is temporary until a better mechanism for installation is determined.

After installing, you will want to also ensure that your IDE uses the TypeScript language service from the workspace and not the default one.

Using our initial example, we will start by extracting all methods from the main IO class:

/**
 * @tsplus type article.IO
 */
export class IO<A> {
  static succeed = <A>(a: A) => new IO(() => a);
  static succeedWith = <A>(a: () => A) => new IO(a);

  constructor(readonly io: () => A) {}
}

/**
 * @tsplus fluent article.IO map
 */
export function map<A, B>(self: IO<A>, f: (a: A) => B): IO<B> {
  return new IO(() => f(self.io()));
}

/**
 * @tsplus fluent article.IO flatMap
 */
export function flatMap<A, B>(self: IO<A>, f: (a: A) => IO<B>): IO<B> {
  return new IO(() => f(self.io()).io());
}

/**
 * @tsplus fluent article.IO zip
 */
export function zip<A, B>(self: IO<A>, b: IO<B>): IO<[A, B]> {
  return new IO(() => [self.io(), b.io()]);
}

/**
 * @tsplus fluent article.IO run
 */
export function run<A>(self: IO<A>) {
  return self.io();
}

There are cases where we would like to add a call signature to something that isn't a function, for example we could refactor the above constructor like:

/**
 * @tsplus type article.IO/Ops
 */
export interface IOOps {}
export const IO: IOOps = {};

/**
 * @tsplus static article.IO/Ops __call
 */
export function make<A>(io: () => A): IO<A> {
  return { io };
}

This allows us to construct values for a datatype using the __call expression that we define. For example, we can create an IO<string> using the __call expression for the IO datatype above:

const io: IO<string> = IO(() => "Hello, World!")

The name __call is a special name that basically says "use the function as the call signature for a type". In the example above, TS+ will resolve the __call expression for the IO datatype to the make function that we defined for IO .

In some extreme cases you may want access to the "this" and for that you can use a "fluent" variant of a __call expression instead of a "static" one.

/**
 * @tsplus fluent article.IO/Ops __call
 */
export function make<A>(self: IOOps, io: () => A): IO<A> {
  return { io };
}

You may think the set of features we have described thus far is enticing enough... ohh but we have only just started.

There are many binary operators in JS - it's a shame there isn't a way of extending those (and the proposal to do so is inefficient in terms of tree shaking, limited, and may never gonna come to fruition)... Yeah, we can do that too :)

Looking at the IO type that we defined above, the zip combinator that we defined for IO looks quite a bit like a binary operator. Given that the "+" symbol doesn't make any sense when used between two IO types in plain JavaScript/TypeScript, we can override it in TS+:

/**
 * @tsplus fluent article.IO zip
 * @tsplus operator article.IO +
 */
export function zip<A, B>(self: IO<A>, b: IO<B>): IO<[A, B]> {
  return IO(() => [self.io(), b.io()]);
}

With just that additional JSDoc annotation we can now call zip on two IO types using the + operator:

const zipped = IO.succeed(0) + IO.succeed(1);

And looking at the quick info from VSCode:

In JavaScript/TypeScript, lazy evaluation of a computation is generally implemented via a thunk (i.e. () => A ). Deferring evaluation of computations can be quite beneficial in a variety of circumstances, particularly when we want to avoid eager computation of a value. This paradigm of "lazy" programming becomes even more powerful when combined with effect systems.

However, if you attempt to write a truly lazy program in JavaScript/TypeScript, you'll quickly find yourself writing a lot of annoying arrow functions like T.succeed(() => console.log("A")) . This is because we want the effect system to assume control over whether or not the console.log is actually called.

To avoid this, TS+ allows us to define function parameters as "lazy":

/**
* @tsplus type LazyArgument
*/
interface LazyArg<A> {
  (): A
}

/**
 * @tsplus static Effect/Ops succeed
 */
function succeed<A>(f: LazyArg<A>) {
  f()
}

When calling Effect.succeed(x) , if x is not already evaluated lazily (i.e. if x is not already a thunk), the compiler will transform it to Effect.succeed(() => x) making it possible to trim annoying boilerplate.

So something like:

Effect.succeed(() => console.log("Hello, world!"))

becomes

Effect.succeed(console.log("Hello, world!"))

Note that the behavior is only added to function arguments of a type that has a type tag of value LazyArgument and not generally to any function arguments.

Ever ended up with something like Left<0> | Left<1> | Right<string> in something that should have been Either<number, string> ?

That's because TypeScript assumes that the right-most type is always the strictest (which is a good assumption, if you manually type it, it compiles).

We can be explicit about type unification in TS+ though:

/**
 * @tsplus type Option
 */
export type Option<A> = None | Some<A>;

/**
 * @tsplus unify Option
 * @tsplus unify Option/Some
 * @tsplus unify Option/None
 */
export function unifyOption<X extends Option<any>>(
  self: X
): Option<[X] extends [Option<infer A>] ? A : never> {
  return self;
}

or

/**
 * @tsplus type Eval
 */
export interface Eval<A> {
  readonly _A: () => A;
  readonly _TypeId: unique symbol;
}

/**
 * @tsplus unify Eval
 */
export function unifyEval<X extends Eval<any>>(self: X): Eval<[X] extends [Eval<infer AX>] ? AX : never> {
  return self;
}

and TS+ will use the result of the unify function to unify any time a union is generated.

So that for example:

As mentioned before, having a lot of imports can be quite painful. To avoid this, we have found that many users of Effect, for example, define their own "prelude" or "utils" files that re-export commonly used modules. Unfortunately, this often leads to edge cases in tree-shaking algorithms used by bundlers that have only recently begin to improve shaking of deeply nested dependency trees.

With TS+, we solve this problem using the concept of global imports.

A global import is an import defined in a declaration file ( .d.ts ) using the following syntax:

/**
 * @tsplus global
 */
import { Chunk } from "@tsplus/stdlib/collections/Chunk/definition";

When defining a type as "global", TS+ will make the type and its associated constructors/methods available globally in the project. However, during compilation TS+ will resolve usage of the constructors/methods associated with a datatype and add relevant imports to each file using the datatype. However, note that imports will only be added to a file during compilation if the global datatype is actually used in that file.

It is a common practice to define a prelude.d.ts in your root and add it to the "files" portion of the "tsconfig.json". For example:

// tsconfig.json
{
  "files": [
    "./prelude.d.ts"
  ]
}

Thought it couldn't get any better? close.

We've been going trough a list of example and by now you probably noticed we tend to use fully qualified imports like "@tsplus/stdlib/collections/Chunk/definition" even for local references.

So how does it compile in practice? When an exported value has a tag like static/fluent/implicit/derivation etc when we emit definition files .d.ts per each function we add a further jsdoc annotation called "location" like:

/**
 * @tsplus fluent Decoder decode
 * @tsplus location "@tsplus/stdlib/runtime/Decoder"
 */
export declare function decode<A>(decoder: Decoder<A>, value: unknown): import("../data/Either").Either<string, A>;

This is how we know how to import things and from where, in a JS file when something like that is used an import is introduced accordingly.

This design ensures modules are always imported as close to the declaration as possible and it helps preventing circular references, it may lead to a big number of imports in the compiled js files but tree-shaking can inline very well.

We think we are pretty much feature ready for the first decent release, we have to write tons of tests and finish extracting out the standard library from the effect codebase before this is considered usable at a decent level externally (internally effect is already written in TS+) but we feel very confident and the TS folks have been amazing in offering valuable advise.