feat: initial stab at parser idea

Added a very basic recursive descent parser in ideas. It's pretty
straightforward and reuses the DecodeError from Decoder for tracking
errors. In the long run, when I learn a bit more about parsers, lexers,
and grammars, I'll likely completely change the implementation to
something like an LR(1) parser generator. For now, this works ok for the
minimal places I need some basic string parsing and don't want to deal
with regex.

Removed that silly bimap function from bimappable.ts. I think the idea
was that once could create a Bimappable instance from map and
mapSecond.. But that is easier with plain types. Anyway, that's gone
now, just write your own bimap function.

Also, cleaned up a bunch of the example code that was erroring during
deno test --doc. It's not 100% yet and it seems the newest deno versions
broke my coverage script.. but that's work for another day.

Author: baetheus

async_either.ts

@@ -513,11 +513,11 @@ export function getInitializableAsyncEither<A, B>(
   CA: Initializable<A>,
   CB: Initializable<B>,
 ): Initializable<AsyncEither<B, A>> {
-  const { init, combine } = E.getInitializableEither(CA, CB);
+  const ie = E.getInitializableEither(CA, CB);
   return {
-    init: () => () => resolve(init()),
+    init: () => () => resolve(ie.init()),
     combine: (second) => (first) => async () =>
-      combine(await second())(await first()),
+      ie.combine(await second())(await first()),
   };
 }
 

bimappable.ts

@@ -10,8 +10,6 @@
 import type { $, Hold, Kind } from "./kind.ts";
 import type { Mappable } from "./mappable.ts";
 
-import { pipe } from "./fn.ts";
-
 /**
  * The Bimappable interface. Bimapple includes the methods map and mapSecond.
  *
@@ -24,35 +22,3 @@ export interface Bimappable<U extends Kind> extends Mappable<U>, Hold<U> {
     ta: $<U, [A, B, C], [D], [E]>,
   ) => $<U, [A, J, C], [D], [E]>;
 }
-
-/**
- * Apply two functions simultaneously to the first and second values in a Bimappable structure.
- *
- * @example
- * ```ts
- * import * as B from "./bimappable.ts";
- * import * as E from "./either.ts";
- * import { pipe } from "./fn.ts";
- *
- * const bimap = B.bimap(E.BimappableEither);
- * const transform = bimap(
- *   (n: number) => n * 2,
- *   (s: string) => s.toUpperCase()
- * );
- *
- * const result1 = pipe(E.right("hello"), transform); // Right("HELLO")
- * const result2 = pipe(E.left(5), transform); // Left(10)
- * ```
- *
- * @since 2.0.0
- */
-export function bimap<U extends Kind>(
-  { map, mapSecond }: Bimappable<U>,
-): <A, B, I, J>(
-  fai: (a: A) => I,
-  fbj: (b: B) => J,
-) => <C = never, D = unknown, E = unknown>(
-  ua: $<U, [A, B, C], [D], [E]>,
-) => $<U, [I, J, C], [D], [E]> {
-  return (fai, fbj) => (ua) => pipe(ua, map(fai), mapSecond(fbj));
-}

datum.ts

@@ -512,8 +512,8 @@ export function map<A, I>(fai: (a: A) => I): (ta: Datum<A>) => Datum<I> {
  * const datumFn = replete((n: number) => n * 2);
  * const datumValue = replete(5);
  * const result = pipe(
- *   datumValue,
- *   apply(datumFn)
+ *   datumFn,
+ *   apply(datumValue)
  * );
  * console.log(result); // { tag: "Replete", value: 10 }
  * ```

deno.json

@@ -1,8 +1,9 @@
 {
   "name": "@baetheus/fun",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "exports": {
     "./ideas/dux": "./ideas/dux.ts",
+    "./ideas/parser": "./ideas/parser.ts",
     "./applicable": "./applicable.ts",
     "./array": "./array.ts",
     "./async": "./async.ts",

fn.ts

@@ -255,7 +255,11 @@ export function memoize<D, A>(ua: Fn<D, A>): Fn<D, A> {
  *   write: (s: string) => Promise<unknown>,
  * }
  *
- * const mockInOut: InOut = todo(); // InOut !!THROWS!!
+ * try {
+ *   const mockInOut: InOut = todo(); // InOut !!THROWS!!
+ * } catch (e) {
+ *   // todo() throws so this block would run
+ * }
  * ```
  *
  * @since 2.0.0

free.ts

@@ -275,8 +275,8 @@ export function flatmap<A, I>(
  * const freeFn = node((n: number) => n * 2);
  * const freeValue = node(5);
  * const result = pipe(
- *   freeValue,
- *   apply(freeFn)
+ *   freeFn,
+ *   apply(freeValue)
  * );
  *
  * console.log(result); // { tag: "Node", value: 10 }