version 0.1.0

.changeset/modern-tomatoes-promise.md

@@ -0,0 +1,5 @@
+---
+"@fp-ts/core": minor
+---
+
+add modules from @fp-ts/data

.changeset/red-moons-hope.md

@@ -0,0 +1,5 @@
+---
+"@fp-ts/core": patch
+---
+
+Add tracking code for Option

CHANGELOG.md

@@ -1,5 +1,55 @@
 # @fp-ts/core
 
+## next
+
+**Breaking changes**
+
+- remove `NonEmptyTraversable` module
+- `Semigroup`
+  - make `combine` binary
+  - make `combineMany` binary
+- `SemiCoproduct`
+  - make `coproduct` binary
+  - make `coproductMany` binary
+- `SemiProduct`
+  - make `product` binary
+  - make `productMany` binary
+  - rename `productFlatten` to `element`
+- `Order`
+  - make `compare` binary
+
+**New Features**
+
+- `Boolean`
+  - add `not` combinator
+- `Order`
+  - add `array` combinator
+  - add `bigint` instance
+- `Monoid`
+  - add `array`, `readonlyArray` combinators
+- `Semigroup`
+  - add `array`, `readonlyArray` combinators
+- new modules
+  - `typeclass/Equivalence`
+  - `typeclass/Filterable`
+  - `typeclass/TraversableFilterable`
+  - `Bigint`
+  - `Boolean`
+  - `Either`
+  - `Function`
+  - `Identity`
+  - `Number`
+  - `Option`
+  - `Ordering`
+  - `Predicate`
+  - `ReadonlyArray`
+  - `ReadonyRecord`
+  - `String`
+  - `Struct`
+  - `Symbol`
+  - `These`
+  - `Tuple`
+
 ## 0.0.11
 
 ### Patch Changes

Either.md

@@ -0,0 +1,141 @@
+# The `Either` data type
+
+The `Either` data type is a powerful and flexible tool for handling potentially failed computations in functional programming. It can be found in the `@fp-ts/core/Either` module, and it has two variants, `Left` and `Right`, which can be used to represent different outcomes.
+
+The `Left` variant is used to represent a failure, and it can contain useful information such as an error message or a failure code. The `Right` variant, on the other hand, is used to represent a successful outcome, and it can contain the result of the computation.
+
+Unlike the `Option` type, `Either` allows you to attach additional information to the failure case, making it more informative.
+In this usage, `None` is replaced with a `Left` which can contain useful information. `Right` takes the place of `Some`.
+
+# Definition
+
+The `Either` data type is the union of two members: `Left` and `Right`. The way chosen by the `@fp-ts/core` library to model this union in TypeScript is to use a feature of the language called [Discriminating Unions](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#discriminating-unions):
+
+> A common technique for working with unions is to have a single field which uses literal types which you can use to let TypeScript narrow down the possible current type
+
+Here's the complete definition of the `Either` type:
+
+```ts
+export type Left<E> = {
+  readonly _tag: "Left";
+  readonly left: E;
+};
+
+export type Right<A> = {
+  readonly _tag: "Right";
+  readonly right: A;
+};
+
+export type Either<E, A> = Left<E> | Right<A>;
+```
+
+# Using `Either`
+
+To create an instance of `Either`, you can use the `right` and `left` constructors, which construct a new `Either` holding a `Right` or `Left` value respectively.
+
+```ts
+import { left, right } from "@fp-ts/core/Either";
+
+const success: Either<string, number> = right(1);
+const failure: Either<string, number> = left("error message");
+```
+
+You can also use the `fromOption` function to convert an `Option` to an `Either`.
+
+```ts
+import { pipe } from "@fp-ts/core/Function";
+import { fromOption } from "@fp-ts/core/Either";
+import { none, some } from "@fp-ts/core/Option";
+
+const success: Either<string, number> = pipe(
+  some(1),
+  fromOption("error message")
+);
+const failure: Either<string, number> = pipe(
+  none(),
+  fromOption("error message")
+);
+```
+
+The `fromOption` function requires an argument because it needs to know what value to use for the `Left` variant of the `Either` type when given a `None`. In the example, the argument "error message" is used as the value for the `Left` variant when `None` is encountered. This allows `Either` to provide more information about why a failure occurred.
+
+# Working with `Either`
+
+Once you have an instance of `Either`, you can use the various functions provided in the `@fp-ts/core/Either` module to work with it.
+
+The `map` and `mapLeft` functions can be used to transform the `Right` and `Left` values respectively.
+
+```ts
+import { pipe } from "@fp-ts/core/Function";
+import { left, right, map, mapLeft } from "@fp-ts/core/Either";
+
+const success: Either<string, number> = pipe(
+  right(1),
+  map((x) => x + 1)
+); // right(2)
+
+const failure: Either<string, number> = pipe(
+  left("error message"),
+  mapLeft((x) => x + "!")
+); // left("error message!")
+```
+
+# Handling failing computations
+
+Let's see how to use the `Either` data type to model a computation that can fail, such as a function that can throw an exception based on certain conditions. Let's take the case of the following function:
+
+```ts
+function parseNumber(s: string): number {
+  const n = parseFloat(s);
+  if (isNaN(n)) {
+    throw new Error(`Cannot parse '${s}' as a number`);
+  }
+  return n;
+}
+```
+
+An alternative to throwing an exception is to always return a value, but this value will be of type `Either<string, number>` instead of `number`, with the following interpretation:
+
+- if `parseNumber` returns a `Left<string>` value, it means that the computation failed, and the `Left` contains an error message or other information about the failure
+- if the result is instead a `Right<number>` value, it means that the computation succeeded and the computed value is wrapped inside the `Right`
+
+Let's see how we can rewrite the `parseNumber` function without throwing exceptions and using the `Either` data type instead:
+
+```ts
+import { Either, left, right } from "@fp-ts/core/Either";
+
+function parseNumber(s: string): Either<string, number> {
+  const n = parseFloat(s);
+  return isNaN(n) ? left(`Cannot parse '${s}' as a number`) : right(n);
+}
+
+console.log(parseNumber("2")); // right(2)
+console.log(parseNumber("Not a number")); // left("Cannot parse 'Not a number' as a number")
+```
+
+# Pattern matching
+
+The `match` function allows us to match on the `Left` and `Right` cases of an `Either` value and provide different actions for each.
+
+We can use the `match` function to handle the `Either` value returned by `parseNumber` and decide what to do based on whether it's a `Left` or a `Right`.
+
+```ts
+import { pipe } from "@fp-ts/core/Function";
+import { match } from "@fp-ts/core/Either";
+
+// parseNumber returns an Either<string, number>
+const result = parseNumber("Not a number");
+
+// Using pipe and match to pattern match on the result
+const output = pipe(
+  result,
+  match(
+    // If the result is a Left, return an error string
+    (error) => `Error: ${error}`,
+    // If the result is a Right, return a string with the number
+    (n) => `The number is ${n}`
+  )
+);
+
+console.log(output); // Output: Error: Cannot parse 'Not a number' as a number
+```

Option.md

@@ -0,0 +1,120 @@
+# The `Option` data type
+
+The `Option` data type is a powerful and flexible tool for handling potentially failed computations in functional programming. It can be found in the `@fp-ts/core/Option` module, and it has two variants, `None` and `Some`, which can be used to represent different outcomes.
+
+There are two possible interpretations of the `Option` data type:
+
+1. as a representation of the result of a computation that can fail or return a value of type `A`
+2. as a representation of an optional value of type `A`
+
+In the first of these two interpretations, the `None` union member represents the result of a computation that has failed and therefore was not able to return any value, while the `Some<A>` union member represents the result of a computation that has succeeded and was able to return a value of type `A`.
+
+In the second of these two interpretations, the `None` union member represents the absence of the value, while the `Some<A>` union member represents the presence of the value of type `A`
+
+# Definition
+
+The `Option` data type is the union of two members: `None` and `Some`. The way chosen by the `@fp-ts/core` library to model this union in TypeScript is to use a feature of the language called [Discriminating Unions](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#discriminating-unions):
+
+> A common technique for working with unions is to have a single field which uses literal types which you can use to let TypeScript narrow down the possible current type
+
+Here's the complete definition of the `Option` type:
+
+```ts
+export type None = {
+  readonly _tag: "None";
+};
+
+export type Some<A> = {
+  readonly _tag: "Some";
+  readonly value: A;
+};
+
+export type Option<A> = None | Some<A>;
+```
+
+# Using `Option`
+
+To create an instance of `Option`, you can use the `some` and `none` constructors, which construct a new `Option` holding a `Some` or `None` value respectively.
+
+```ts
+import { none, some } from "@fp-ts/core/Either";
+
+const success: Option<number> = some(1);
+const failure: Option<number> = none();
+```
+
+# Working with `Option`
+
+Once you have an instance of `Option`, you can use the various functions provided in the `@fp-ts/core/Option` module to work with it.
+
+The `map` function can be used to transform the `Some` values.
+
+```ts
+import { pipe } from "@fp-ts/core/Function";
+import { some, map } from "@fp-ts/core/Option";
+
+const success: Option<number> = pipe(
+  some(1),
+  map((x) => x + 1)
+); // some(2)
+```
+
+# Handling failing computations
+
+Let's see how to use the `Option` data type to model a computation that can fail, such as a function that can throw an exception based on certain conditions. Let's take the case of the following function:
+
+```ts
+function parseNumber(s: string): number {
+  const n = parseFloat(s);
+  if (isNaN(n)) {
+    throw new Error();
+  }
+  return n;
+}
+```
+
+An alternative to throwing an exception is to always return a value, but this value will be of type `Option<number>` instead of `number`, with the following interpretation:
+
+- if `parseNumber` returns a `None` value, it means that the computation failed
+- if the result is instead a `Some<number>` value, it means that the computation succeeded and the computed value is wrapped inside the `Some`
+
+Let's see how we can rewrite the `parseNumber` function without throwing exceptions and using the `Option` data type instead:
+
+```ts
+import { Option, none, some } from "@fp-ts/core/Option";
+
+function parseNumber(s: string): Option<number> {
+  const n = parseFloat(s);
+  return isNaN(n) ? none() : some(n);
+}
+
+console.log(parseNumber("2")); // some(2)
+console.log(parseNumber("Not a number")); // none()
+```
+
+# Pattern matching
+
+The `match` function allows us to match on the `None` and `Some` cases of an `Option` value and provide different actions for each.
+
+We can use the `match` function to handle the `Option` value returned by `parseNumber` and decide what to do based on whether it's a `None` or a `Some`.
+
+```ts
+import { pipe } from "@fp-ts/core/Function";
+import { match } from "@fp-ts/core/Option";
+
+// parseNumber returns an Option<number>
+const result = parseNumber("Not a number");
+
+// Using pipe and match to pattern match on the result
+const output = pipe(
+  result,
+  match(
+    // If the result is a None, return an error string
+    () => `Error: ${error}`,
+    // If the result is a Some, return a string with the number
+    (n) => `The number is ${n}`
+  )
+);
+
+console.log(output); // Output: Error: Cannot parse 'Not a number' as a number
+```

README.md

@@ -16,38 +16,40 @@ Functional programming in TypeScript
 
 # Typed functional programming in TypeScript
 
-This project represents the next major iteration of [`fp-ts`](https://github.com/gcanti/fp-ts) and it's objective is a reconciliation with [`Effect`](https://github.com/Effect-TS) in order to unify the ecosystems.
+This project represents the next major iteration of [`fp-ts`](https://github.com/gcanti/fp-ts) and it's objective is a reconciliation with [`@effect`](https://github.com/Effect-TS) in order to unify the ecosystems.
 
-The [`Effect`](https://github.com/Effect-TS) project will reduce it's scope to simply being an effect system and will delegate to `fp-ts org` all the lower level abstractions such as typeclasses and common data structures.
+The [`@effect`](https://github.com/Effect-TS) project will reduce it's scope to simply being an effect system and will delegate to `fp-ts org` all the lower level abstractions such as typeclasses and common data structures.
 
 The objective of the `fp-ts org` in github and in npm (`@fp-ts`) is to simplify structure and management of the project, have smaller and better scoped packages.
 
 Our "current" idea (that is well open for changes) is for `fp-ts org` to have:
 
-- `@fp-ts/core` with the new `HKT` implementation and the most common typeclasses such as `Monad`
-- `@fp-ts/data` with `Option`, `Either`, `ReadonlyArray`, `List` and the most common data structures together with data related typeclasses (i.e. `Compactable`, etc)
-- `@fp-ts/optics` with an optic implementation that will provide also optics for structures in `@fp-ts/data`
-- `@fp-ts/schema` with a concrete codec such as `io-ts` again for all the structures in `@fp-ts/data`
+- The [`@fp-ts/core`](https://github.com/fp-ts/core) library features a new implementation of the Higher Kinded Type (HKT) pattern, including common typeclasses such as `Monad` and widely-used data types like `Option`, `Either`, and `ReadonlyArray`
+- [`@fp-ts/schema`](https://github.com/fp-ts/schema) offers schema validation with static type inference, including decoders for data structures in `@fp-ts/core` and `@effect/data`
+- [`@fp-ts/optic`](https://github.com/fp-ts/optic) provides optics for structures in both `@fp-ts/core` and `@effect/data`
 
-And for [`Effect`](https://github.com/Effect-TS) to have:
+For those using [`fp-ts`](https://github.com/gcanti/fp-ts) v2 and its ecosystem, roughly these are the equivalents:
 
-- `@effect/core` with the effect system
-- `@effect/query` with the query impl
-- `@effect/*` every other effect based impl
+- [`fp-ts`](https://github.com/gcanti/fp-ts) -> [`@fp-ts/core`](https://github.com/fp-ts/core) + [`@effect/*` packages](https://github.com/Effect-TS)
+- [`io-ts`](https://github.com/gcanti/io-ts) -> [`@fp-ts/schema`](https://github.com/fp-ts/schema)
+- [`monocle-ts`](https://github.com/gcanti/monocle-ts) -> [`@fp-ts/optic`](https://github.com/fp-ts/optic)
 
-Note that [`Effect`](https://github.com/Effect-TS) will not have base structures like `Option` / `Either` / `List` and typeclasses like `Monad` / `Functor` and [`fp-ts`](https://github.com/fp-ts) will not have effect execution modules like `Task` / `IO` as both projects are made to be the same ecosystem and each answer a specific set of needs in the best way possible.
+Note that `@fp-ts/core` will not contain any effect system (e.g. `Task`, `TaskEither`, `ReaderTaskEither`) since the handling of effects is entirely delegated to the packages contained in [`@effect/*`](https://github.com/Effect-TS).
 
 # Installation
 
-To install the **pre-alpha** version:
+To install the **alpha** version:
 
 ```
 npm install @fp-ts/core
 ```
 
 # Documentation
 
-- [Overview](./Overview.md)
+- [Typeclass overview](./typeclass.md)
+- [Data overview](./data.md)
+- [The `Option` data type](./Option.md)
+- [The `Either` data type](./Either.md)
 - [API Reference](https://fp-ts.github.io/core/)
 
 # License