@synple.dev/core 0.0.0 → 0.2.0

package/README.md

@@ -6,10 +6,14 @@ To install dependencies:
 bun install
 ```
 
-To run:
+To build the application:
 
 ```bash
-bun run index.ts
+bun build
 ```
 
-This project was created using `bun init` in bun v1.3.14. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+To publish the application:
+
+```bash
+bun publish --access public
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synple.dev/core",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "module": "index.ts",
   "type": "module",
   "private": false,
@@ -11,9 +11,11 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "bunup": "^0.16.32"
+    "bunup": "^0.16.32",
+    "vitest": "^4.1.8"
   },
   "scripts": {
-    "build": "bunup"
+    "build": "bunup",
+    "test": "vitest"
   }
 }

package/src/monads/README.md

@@ -0,0 +1,3 @@
+## Monads ?
+
+Monads are a simple concept. TO sum it up with a bit of humour, I could say it's simply a monoid in the category of endofunctors, but without a strong knowledge of the basis of category theory, that would not be easy to understand. TO be more simple, monads are an object that allow you to separate the structure of an algorithm, from the result of each step of the algorithm. It gives you some ways to functionally handle the results and errors arising from computations.

package/src/monads/either.ts

@@ -0,0 +1,112 @@
+export interface Side<T, Err> {
+
+  /**
+   * Returns the inner value of the monad, or a default value if it cannot be computed (in case of error).
+   * @param defaultValue the value to return if the computation cannot come to an end.
+   */
+  or(defaultValue: T): T
+
+  /**
+   * This flat map function takes a callback that can transform the current value in a value of another type
+   * wrapped in a monad, either with it being a success and a failure. It allows an easy chaining of methods
+   * after this call, chaining the different fmap calls until there is an error, or to the full extend of the
+   * computation.
+   * 
+   * @param fct the function transforming the current value into a monad.
+   */
+  fmap<U>(fct: (item: T) => Side<U, Err>): Side<U, Err>
+
+  /**
+   * Applies a function to the inner value of the computation, eventually transforming it into a new type. On
+   * a fundamental level, the function passed here is just a morphism in the category of types, and after it
+   * has been applied to the current value, the result is raised anew in the world of monads to chain further
+   * computations.
+   * 
+   * @param fct the function transforming the current value, eventually changing its type.
+   */
+  map<U>(fct: (item: T) => U): Side<U, Err>
+
+  /**
+   * Applies a function to the current value without waiting for its executation to end. It's only applied if
+   * the current value is a success. To apply a function like this on an error, use the tapError method. This
+   * method, and its sibling method tapError, are usually used to apply side-effect without waiting for them.
+   * A good example of that would be : logging the success of a computation.
+   * 
+   * @param fct 
+   */
+  tap(fct: (item: T) => void | Promise<void>): Side<T, Err>
+
+  /**
+   * The opposite of the tap function, applying a side-effect only if the current computation is a failure. It
+   * can be used, as tap is used, to log an error happening for example.
+   * 
+   * @param fct the function generating the side-effect to execute.
+   */
+  tapError(fct: (error: Err) => void | Promise<void>): Side<T, Err>
+}
+
+class Success<T, Err> implements Side<T, Err> {
+  constructor(protected readonly item: T) { }
+
+  public or(_: T) {
+    return this.item
+  }
+
+  public fmap<U>(fct: (item: T) => Side<U, Err>): Side<U, Err> {
+    return fct(this.item)
+  }
+
+  public map<U>(fct: (item: T) => U): Side<U, Err> {
+    return some(fct(this.item))
+  }
+
+  public tap(fct: (item: T) => void | Promise<void>): Side<T, Err> {
+    fct(this.item)
+    return some(this.item)
+  }
+
+  public tapError(_: (error: Err) => void | Promise<void>): Side<T, Err> {
+    return some(this.item)
+  }
+}
+
+class Failure<T, Err> implements Side<T, Err> {
+  constructor(protected readonly error: Err) { }
+
+  public or(defaultValue: T) {
+    return defaultValue
+  }
+
+  public fmap<U>(_: (item: T) => Side<U, Err>): Side<U, Err> {
+    return fail(this.error)
+  }
+
+  public map<U>(_: (item: T) => U): Side<U, Err> {
+    return fail(this.error)
+  }
+
+  public tap(_: (item: T) => void | Promise<void>): Side<T, Err> {
+    return fail(this.error)
+  }
+
+  public tapError(fct: (error: Err) => void | Promise<void>): Side<T, Err> {
+    fct(this.error)
+    return fail(this.error)
+  }
+}
+
+/**
+ * Creates the first step of a computation, considered a success as nothing has already failed.
+ * @param item the initial value for the computation.
+ */
+export function some<T, Err>(item: T): Success<T, Err> {
+  return new Success<T, Err>(item)
+}
+
+/**
+ * Creates a failing computation, often returned as result of a flat map in another monad.
+ * @param error the error returned by the computation.
+ */
+export function fail<T, Err>(error: Err): Failure<T, Err> {
+  return new Failure<T, Err>(error)
+}

package/test/hello.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import { hello } from "../src";
+
+describe('hello', () => {
+  it("Returns the correct message", () => {
+    expect(hello()).toEqual("Hello world!")
+  })
+})

package/test/monads/either.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { fail, some } from "../../src/monads/either"
+
+describe("some", () => {
+  it("Returns a wrapper containing the original value as a success monad", () => {
+    expect(some<number, number>(42).or(13)).toEqual(42)
+  })
+})
+
+describe("fail", () => {
+  it("Returns a wrapper containing an error monad returning a default value when interrogated", () => {
+    expect(fail<number, number>(42).or(13)).toEqual(13)
+  })
+})
+
+describe("fmap", () => {
+  const init = some<number, string>(42)
+
+  it("Returns a failure if the underlying function returns a failure", () => {
+    const fct = (n: number) => fail<number, string>("42")
+    expect(init.fmap(fct).or(13)).toEqual(13)
+  })
+  it("Returns a success if the underlying function returns a success", () => {
+    const fct = (n: number) => some<string, string>(`${n}`)
+    expect(init.fmap(fct).or("test")).toEqual("42")
+  })
+})
+
+describe("map", () => {
+  const stringify = (n: number) => `${n}`
+
+  it("Returns a failure if the underlying function returns a failure", () => {
+    expect(some<number, number>(42).map(stringify).or("13")).toEqual("42")
+  })
+  it("Returns a success if the underlying function returns a success", () => {
+    expect(fail<number, number>(42).map(stringify).or("13")).toEqual("13")
+  })
+})
+
+describe("Side effects dependant methods", () => {
+  // Used for the side effect built to pass to the tap method.
+  let num: number;
+
+  const affect = (n: number) => {
+    num = n;
+  }
+
+  beforeEach(() => affect(0))
+
+  describe("tap", () => {
+    it("Executes the side-effect when called on a success monad", () => {
+      some<number, number>(42).tap(affect)
+      expect(num).toEqual(42)
+    })
+    it("Does not execute the side-effect when called on a failure monad", () => {
+      fail<number, number>(42).tap(affect)
+      expect(num).toEqual(0)
+    })
+  })
+  describe("tapError", () => {
+    it("Does not execute the side-effect when called on a success monad", () => {
+      some<number, number>(42).tapError(affect)
+      expect(num).toEqual(0)
+    })
+    it("Executes the side-effect when called on a failure monad", () => {
+      fail<number, number>(42).tapError(affect)
+      expect(num).toEqual(42)
+    })
+  })
+})

package/index.ts

@@ -1 +0,0 @@
-console.log("Hello via Bun!");