@typed/fx 0.0.1

package/readme.md

@@ -0,0 +1,35 @@
+# @typed/fx
+
+Fx is a generator-based abstraction for describing applications that run within Fibers. 
+The Fiber runtime interprets these generators into running applications that process side-effects. 
+
+
+## Features
+
+- Concurrency - never encounter a race condition, control the level of concurrency at any level.
+- Resources Safety - release unused resources at just the right time, even in the event of failures.
+- Resilient - type-safe errors that will never be swallowed.
+- Interruptable - Cancel Fx you're no longer interested in, or mark regions as uninterruptible to avoid errors.
+- Dependency injection - Use the type-checker to ensure your programs are properly constructed.
+- Streams - Push-based streams, modeled after [@most/core](https://github.com/mostjs/core), with full Fx integration.
+- Tracing - Use our TypeScript/Vite plugin to use the TypeScript compiler to augment your stack traces with more useful information.
+- Logging - Built-in Loggers w/ configurable backends
+- Metrics - Track metrics occurring throughout your application.
+- State Management - Manage and synchronize state effortlessly across all your running processes.
+
+## Target 
+
+This library is primarily designed for front-end applications (including server-side rendering), that is to say,
+bundle size, parse time, memory constraints, etc. are of great concern. There will always be a balancing act between
+these metrics, ergonomics, and feature-set. We'll attempt to tread these lines as best we can, but Fx is highly feature-rich
+as it is, and can be used to build many many more abstractions that are not yet available as 3rd party plugins.
+
+The full library, and its dependencies, are about 50kb minified + gzipped. 
+However, it is provided as ES modules and is highly tree-shakeable. Take only what you need.
+
+## Come Back Soon
+
+There's not a lot else to see here yet, this library is under very active development and will continue to be updated with more docs and 
+information on how to use it. Check back soon! 
+
+If you're interested in chatting about the project come on over and join us on [Discord](https://discord.com/invite/kpPHEvkaAv)!

package/src/Atomic/Atomic.ts

@@ -0,0 +1,122 @@
+import { identity, pipe } from 'hkt-ts'
+import { Endomorphism } from 'hkt-ts/Endomorphism'
+import { Just, Maybe, Nothing } from 'hkt-ts/Maybe'
+import { Associative, First } from 'hkt-ts/Typeclass/Associative'
+import { Eq } from 'hkt-ts/Typeclass/Eq'
+import { Identity } from 'hkt-ts/Typeclass/Identity'
+
+/**
+ * Atomic represents an a mutable reference to immutable data
+ * that can be modified and joined back together.
+ */
+export interface Atomic<A> extends Identity<A> {
+  readonly get: () => A
+  readonly modify: <B>(f: (a: A) => readonly [B, A]) => B
+  readonly set: (a: A) => A
+}
+
+/**
+ * Construct an Atomic with an initial value, and optionally an Associative instance.
+ */
+export function Atomic<A>(initial: A, A: Associative<A> = First): Atomic<A> {
+  let current = initial
+
+  return {
+    id: initial,
+    concat: A.concat,
+    get: () => current,
+    modify: (f) => {
+      const [b, a] = f(current)
+      current = a
+      return b
+    },
+    set: (a) => (current = a),
+  }
+}
+
+/**
+ * Get the current value of an Atomic
+ */
+export function get<A>(atomic: Atomic<A>): A {
+  return atomic.get()
+}
+
+/**
+ * Atomically view and update the state of an Atomic.
+ */
+export function modify<A, B>(f: (a: A) => readonly [B, A]) {
+  return (atomic: Atomic<A>): B => atomic.modify(f)
+}
+
+/**
+ * Set the value of Atomic but return the previous state.
+ */
+export const getAndSet =
+  <A, B extends A>(updated: B) =>
+  (atomic: Atomic<A>): A =>
+    atomic.modify((a) => [a, updated])
+
+/**
+ * Set the state of an Atomic and return that value.
+ */
+export const set =
+  <A, B extends A>(updated: B) =>
+  (atomic: Atomic<A>): A =>
+    atomic.modify(() => [updated, updated])
+
+/**
+ * Apply an Endomorphism to update the current state of an Atomic.
+ */
+export const update =
+  <A>(f: Endomorphism<A>) =>
+  (atomic: Atomic<A>): A =>
+    atomic.modify((a) => {
+      const updated = f(a)
+
+      return [updated, updated]
+    })
+
+/**
+ * Apply an Endomorphism to update the current state of an Atomic, but
+ * return the previous state.
+ */
+export const getAndUpdate =
+  <A>(f: Endomorphism<A>) =>
+  (atomic: Atomic<A>): A =>
+    atomic.modify((a) => {
+      const updated = f(a)
+
+      return [a, updated]
+    })
+
+/**
+ * Join together the values contained within 2 Atomics.
+ */
+export function join<A>(second: Atomic<A>) {
+  return (first: Atomic<A>): A =>
+    pipe(
+      first,
+      update((a) => first.concat(a, second.get())),
+    )
+}
+
+export function fork<A>(f: Endomorphism<A> = identity) {
+  return (first: Atomic<A>): Atomic<A> => Atomic<A>(f(first.get()), first)
+}
+
+/**
+ * Using an Eq instance, compare the expected current value with
+ * the actual value contained within an Atomic and update the Atomic
+ * with the updated value. If the expected current value does not match
+ * the existing value, a `Maybe.Nothing` is returned.
+ */
+export function compareAndSwap<A>(E: Eq<A>) {
+  return (current: A, updated: A) =>
+    (atomic: Atomic<A>): Maybe<A> => {
+      if (E.equals(atomic.get(), current)) {
+        return Just(atomic.set(updated))
+      }
+
+      return Nothing
+    }
+}

package/src/Atomic/AtomicCounter.ts

@@ -0,0 +1,23 @@
+import { NonNegativeInteger, NonNegativeIntegerAssociativeSum } from 'hkt-ts/number'
+
+import { Atomic, getAndUpdate, update } from './Atomic.js'
+
+export interface AtomicCounter extends Atomic<NonNegativeInteger> {}
+
+export function AtomicCounter(initial: NonNegativeInteger = NonNegativeInteger(0)): AtomicCounter {
+  return Atomic(initial, NonNegativeIntegerAssociativeSum)
+}
+
+export const increment: (counter: AtomicCounter) => NonNegativeInteger = update(
+  (n: NonNegativeInteger) => NonNegativeInteger(n + 1),
+)
+export const decrement: (counter: AtomicCounter) => NonNegativeInteger = update(
+  (n: NonNegativeInteger) => NonNegativeInteger(Math.max(0, n - 1)),
+)
+
+export const getAndIncrement: (counter: AtomicCounter) => NonNegativeInteger = getAndUpdate(
+  (n: NonNegativeInteger) => NonNegativeInteger(n + 1),
+)
+export const getAndDecrement: (counter: AtomicCounter) => NonNegativeInteger = getAndUpdate(
+  (n: NonNegativeInteger) => NonNegativeInteger(Math.max(0, n - 1)),
+)

package/src/Atomic/index.ts

@@ -0,0 +1,2 @@
+export * from './Atomic.js'
+export * from './AtomicCounter.js'

package/src/Cause/Cause.ts

@@ -0,0 +1,425 @@
+import { HKT, Kind, Maybe, Params, identity, pipe } from 'hkt-ts'
+import { Associative } from 'hkt-ts/Typeclass'
+import * as AB from 'hkt-ts/Typeclass/AssociativeBoth'
+import * as AF from 'hkt-ts/Typeclass/AssociativeFlatten'
+import { Bottom1 } from 'hkt-ts/Typeclass/Bottom'
+import { Compact1 } from 'hkt-ts/Typeclass/Compact'
+import * as C from 'hkt-ts/Typeclass/Covariant'
+import * as D from 'hkt-ts/Typeclass/Debug'
+import * as EQ from 'hkt-ts/Typeclass/Eq'
+import * as FIM from 'hkt-ts/Typeclass/FilterMap'
+import * as FM from 'hkt-ts/Typeclass/FoldMap'
+import * as FE from 'hkt-ts/Typeclass/ForEach'
+import { Identity } from 'hkt-ts/Typeclass/Identity'
+import * as IB from 'hkt-ts/Typeclass/IdentityBoth'
+import { IdentityFlatten1 } from 'hkt-ts/Typeclass/IdentityFlatten'
+import * as ORD from 'hkt-ts/Typeclass/Ord'
+import * as T from 'hkt-ts/Typeclass/Top'
+import * as N from 'hkt-ts/number'
+
+import { Renderer, defaultRenderer, prettyPrint } from './Renderer.js'
+
+import * as FiberId from '@/FiberId/index.js'
+import * as Trace from '@/Trace/Trace.js'
+
+export type Cause<E> =
+  | Empty
+  | Interrupted
+  | Unexpected
+  | Expected<E>
+  | Sequential<E, E>
+  | Parallel<E, E>
+  | Traced<E>
+
+export type AnyCause = Cause<any> | Cause<never>
+
+export interface Empty {
+  readonly tag: 'Empty'
+}
+export const Empty: Empty = { tag: 'Empty' }
+
+export class Interrupted {
+  readonly tag = 'Interrupted'
+  constructor(readonly fiberId: FiberId.FiberId) {}
+}
+
+export const interrupted = (fiberId: FiberId.FiberId): Cause<never> => new Interrupted(fiberId)
+
+export class Unexpected {
+  readonly tag = 'Unexpected'
+  constructor(readonly error: unknown) {}
+}
+
+export const unexpected = (error: unknown): Cause<never> => new Unexpected(error)
+
+export class Expected<E> {
+  readonly tag = 'Expected'
+  constructor(readonly error: E) {}
+}
+
+export const expected = <E>(error: E) => new Expected(error)
+
+export class Sequential<E1, E2> {
+  readonly tag = 'Sequential'
+  constructor(readonly left: Cause<E1>, readonly right: Cause<E2>) {}
+}
+
+export const sequential = <E1, E2>(left: Cause<E1>, right: Cause<E2>): Cause<E1 | E2> =>
+  new Sequential(left, right)
+
+export class Parallel<E1, E2> {
+  readonly tag = 'Parallel'
+  constructor(readonly left: Cause<E1>, readonly right: Cause<E2>) {}
+}
+
+export const parallel = <E1, E2>(left: Cause<E1>, right: Cause<E2>): Cause<E1 | E2> =>
+  new Parallel(left, right)
+
+export class Traced<E> {
+  readonly tag = 'Traced'
+  constructor(readonly cause: Cause<E>, readonly trace: Trace.Trace) {}
+}
+
+export const traced =
+  (trace: Trace.Trace) =>
+  <E>(cause: Cause<E>): Cause<E> =>
+    new Traced(cause, trace)
+
+export const makeParallelAssociative = <E>(): Associative.Associative<Cause<E>> => ({
+  concat: (left, right) =>
+    left.tag === Empty.tag ? right : right.tag === Empty.tag ? left : new Parallel(left, right),
+})
+
+export const makeParallelIdentity = <E>(): Identity<Cause<E>> => ({
+  ...makeParallelAssociative<E>(),
+  id: Empty,
+})
+
+export const makeSequentialAssociative = <E>(): Associative.Associative<Cause<E>> => ({
+  concat: (left, right) =>
+    left.tag === Empty.tag ? right : right.tag === Empty.tag ? left : new Sequential(left, right),
+})
+
+export const makeSequentialIdentity = <E>(): Identity<Cause<E>> => ({
+  ...makeSequentialAssociative<E>(),
+  id: Empty,
+})
+
+export const makeEq = <E>(Eq: EQ.Eq<E>): EQ.Eq<Cause<E>> => {
+  const eq = EQ.sum<Cause<E>>()('tag')({
+    Empty: EQ.AlwaysEqual,
+    Interrupted: EQ.struct({
+      tag: EQ.AlwaysEqual,
+      fiberId: FiberId.Eq,
+    }),
+    Unexpected: EQ.struct({
+      tag: EQ.AlwaysEqual,
+      error: EQ.DeepEquals,
+    }),
+    Expected: EQ.struct({
+      tag: EQ.AlwaysEqual,
+      error: Eq,
+    }),
+    Sequential: EQ.struct({
+      tag: EQ.AlwaysEqual,
+      left: EQ.lazy(() => eq),
+      right: EQ.lazy(() => eq),
+    }),
+    Parallel: EQ.struct({
+      tag: EQ.AlwaysEqual,
+      left: EQ.lazy(() => eq),
+      right: EQ.lazy(() => eq),
+    }),
+    Traced: EQ.struct({
+      tag: EQ.AlwaysEqual,
+      cause: EQ.lazy(() => eq),
+      trace: Trace.Eq,
+    }),
+  })
+
+  return eq
+}
+
+const tagOrd = pipe(
+  N.Ord,
+  ORD.contramap((x: Cause<any>['tag']) => {
+    switch (x) {
+      case 'Empty':
+        return 0
+      case 'Unexpected':
+        return 1
+      case 'Expected':
+        return 2
+      case 'Interrupted':
+        return 3
+      case 'Parallel':
+        return 4
+      case 'Sequential':
+        return 5
+      case 'Traced':
+        return 6
+    }
+  }),
+)
+
+export const makeOrd = <E>(Eq: ORD.Ord<E>): ORD.Ord<Cause<E>> => {
+  const ord = ORD.sum<Cause<E>>()('tag')(tagOrd)({
+    Empty: ORD.Static,
+    Interrupted: ORD.struct({
+      fiberId: FiberId.Ord,
+      tag: ORD.Static,
+    })(ORD.Static),
+    Unexpected: ORD.struct({
+      error: ORD.Static,
+      tag: ORD.Static,
+    })(ORD.Static),
+    Expected: ORD.struct({
+      error: Eq,
+      tag: ORD.Static,
+    })(ORD.Static),
+    Sequential: ORD.struct({
+      left: ORD.lazy(() => ord),
+      right: ORD.lazy(() => ord),
+      tag: ORD.Static,
+    })(ORD.Static),
+    Parallel: ORD.struct({
+      left: ORD.lazy(() => ord),
+      right: ORD.lazy(() => ord),
+      tag: ORD.Static,
+    })(ORD.Static),
+    Traced: ORD.struct({
+      cause: ORD.lazy(() => ord),
+      trace: Trace.Ord,
+      tag: ORD.Static,
+    })(ORD.Static),
+  })
+
+  return ord
+}
+
+export function shouldRethrow(error: Cause<any>): boolean {
+  return error.tag === 'Unexpected' || (error.tag === 'Traced' && shouldRethrow(error.cause))
+}
+
+export const match =
+  <A, B, C, E, D, F, G, H>(
+    onEmpty: () => A,
+    onInterrupted: (fiberId: FiberId.FiberId) => B,
+    onUnexpected: (error: unknown) => C,
+    onExpected: (e: E) => D,
+    onSequential: (left: Cause<E>, right: Cause<E>) => F,
+    onParallel: (left: Cause<E>, right: Cause<E>) => G,
+    onTraced: (cause: Cause<E>, trace: Trace.Trace) => H,
+  ) =>
+  (cause: Cause<E>): A | B | C | D | F | G | H => {
+    switch (cause.tag) {
+      case 'Empty':
+        return onEmpty()
+      case 'Interrupted':
+        return onInterrupted(cause.fiberId)
+      case 'Unexpected':
+        return onUnexpected(cause.error)
+      case 'Expected':
+        return onExpected(cause.error)
+      case 'Sequential':
+        return onSequential(cause.left, cause.right)
+      case 'Parallel':
+        return onParallel(cause.left, cause.right)
+      case 'Traced':
+        return onTraced(cause.cause, cause.trace)
+    }
+  }
+
+export interface CauseHKT extends HKT {
+  readonly type: Cause<this[Params.A]>
+}
+
+export const Covariant: C.Covariant1<CauseHKT> = {
+  map: function map<A, B>(f: (a: A) => B): (cause: Cause<A>) => Cause<B> {
+    return match(
+      () => Empty,
+      (id) => new Interrupted(id),
+      (error) => new Unexpected(error),
+      (e) => new Expected(f(e)),
+      (left, right) => new Sequential(map(f)(left), map(f)(right)),
+      (left, right) => new Parallel(map(f)(left), map(f)(right)),
+      (cause, trace) => new Traced(map(f)(cause), trace),
+    )
+  },
+}
+
+export const map = Covariant.map
+export const bindTo = C.bindTo(Covariant)
+export const flap = C.flap(Covariant)
+export const mapTo = C.mapTo(Covariant)
+export const tupled = C.tupled(Covariant)
+
+export const Top: T.Top1<CauseHKT> = {
+  get top() {
+    return expected([])
+  },
+}
+
+export const top = Top.top
+export const fromValue = T.makeFromValue<CauseHKT>({ ...Top, ...Covariant })
+export const fromLazy = T.makeFromLazy<CauseHKT>({ ...Top, ...Covariant })
+
+export const Bottom: Bottom1<CauseHKT> = {
+  bottom: Empty,
+}
+
+export const bottom = Bottom.bottom
+
+export const Flatten: AF.AssociativeFlatten1<CauseHKT> = {
+  flatten: match(
+    () => Empty,
+    (id) => new Interrupted(id),
+    (error) => new Unexpected(error),
+    identity,
+    (left, right) => new Sequential(flatten(left), flatten(right)),
+    (left, right) => new Parallel(flatten(left), flatten(right)),
+    (cause, trace) => new Traced(flatten(cause), trace),
+  ),
+}
+
+export const flatten = Flatten.flatten
+export const flatMap = AF.flatMap<CauseHKT>({ ...Flatten, ...Covariant })
+export const bind = AF.bind<CauseHKT>({ ...Flatten, ...Covariant })
+
+export const IdentityFlatten: IdentityFlatten1<CauseHKT> = {
+  ...Flatten,
+  ...Top,
+}
+
+export const AssociativeBoth: AB.AssociativeBoth1<CauseHKT> = AF.makeAssociativeBoth<CauseHKT>({
+  ...Flatten,
+  ...Covariant,
+})
+
+export const zipLeft = AB.zipLeft<CauseHKT>({ ...AssociativeBoth, ...Covariant })
+export const zipRight = AB.zipRight<CauseHKT>({ ...AssociativeBoth, ...Covariant })
+
+export const IdentityBoth: IB.IdentityBoth1<CauseHKT> = {
+  ...AssociativeBoth,
+  ...Top,
+}
+
+export const tuple = IB.tuple<CauseHKT>({ ...IdentityBoth, ...Covariant })
+export const struct = IB.struct<CauseHKT>({ ...IdentityBoth, ...Covariant })
+
+export const ForEach: FE.ForEach1<CauseHKT> = {
+  map,
+  forEach: <T2 extends HKT>(IBC: IB.IdentityBoth<T2> & C.Covariant<T2>) => {
+    const tuple_ = IB.tuple(IBC)
+    const fromValue_ = T.makeFromValue(IBC)
+
+    const forEach_ =
+      <A, B>(f: (a: A) => Kind<T2, B>) =>
+      (cause: Cause<A>): Kind<T2, Cause<B>> => {
+        if (cause.tag === 'Expected') {
+          return IBC.map(expected)(f(cause.error))
+        }
+
+        if (cause.tag === 'Sequential') {
+          return pipe(
+            tuple_(forEach_(f)(cause.left), forEach_(f)(cause.right)),
+            IBC.map(([a, b]) => sequential(a, b)),
+          )
+        }
+
+        if (cause.tag === 'Parallel') {
+          return pipe(
+            tuple_(forEach_(f)(cause.left), forEach_(f)(cause.right)),
+            IBC.map(([a, b]) => parallel(a, b)),
+          )
+        }
+
+        if (cause.tag === 'Traced') {
+          return pipe(
+            forEach_(f)(cause.cause),
+            IBC.map((c) => new Traced(c, cause.trace)),
+          )
+        }
+
+        return fromValue_(cause)
+      }
+
+    return forEach_
+  },
+}
+
+export const forEach = FE.forEach
+export const mapAccum = FE.mapAccum(ForEach)
+export const sequence = FE.sequence(ForEach)
+
+export const FoldMap: FM.FoldMap1<CauseHKT> = {
+  foldMap:
+    <B>(I: Identity<B>) =>
+    <A>(f: (a: A) => B) =>
+      function fold(cause: Cause<A>): B {
+        return pipe(
+          cause,
+          match(
+            () => I.id,
+            () => I.id,
+            () => I.id,
+            f,
+            (left, right) => I.concat(fold(left), fold(right)),
+            (left, right) => I.concat(fold(left), fold(right)),
+            fold,
+          ),
+        )
+      },
+}
+
+export const foldMap = FoldMap.foldMap
+export const foldLeft = FM.foldLeft(FoldMap)
+export const contains = FM.contains(FoldMap)
+export const count = FM.count(FoldMap)
+export const every = FM.every(FoldMap)
+export const some = FM.some(FoldMap)
+export const exists = FM.exists(FoldMap)
+export const find = FM.find(FoldMap)
+export const groupBy = FM.groupBy(FoldMap)
+export const intercalate = FM.intercalate(FoldMap)
+export const reduce = FM.reduce(FoldMap)
+export const reduceAssociative = FM.reduceAssociative(FoldMap)
+export const reduceCommutative = FM.reduceCommutative(FoldMap)
+export const reduceIdentity = FM.reduceIdentity(FoldMap)
+export const reduceRight = FM.reduceRight<CauseHKT>({ ...FoldMap, ...ForEach })
+export const reverse = FM.reverse<CauseHKT>({ ...FoldMap, ...ForEach })
+export const size = FM.size(FoldMap)
+export const toArray = FM.toArray(FoldMap)
+
+export const FilterMap: FIM.FilterMap1<CauseHKT> = {
+  filterMap: (f) =>
+    match(
+      () => Empty,
+      (id) => new Interrupted(id),
+      (e) => new Unexpected(e),
+      (a) =>
+        pipe(
+          a,
+          f,
+          Maybe.match(() => Empty, expected),
+        ),
+      (left, right) => new Sequential(FilterMap.filterMap(f)(left), FilterMap.filterMap(f)(right)),
+      (left, right) => new Parallel(FilterMap.filterMap(f)(left), FilterMap.filterMap(f)(right)),
+      (cause, trace) => new Traced(FilterMap.filterMap(f)(cause), trace),
+    ),
+}
+
+export const filterMap = FilterMap.filterMap
+export const compact = FIM.compact(FilterMap)
+export const filter = FIM.filter(FilterMap)
+
+export const Compact: Compact1<CauseHKT> = {
+  compact,
+}
+
+export const compacted = FE.compacted<CauseHKT>({ ...ForEach, ...Compact })
+
+export const makeDebug = <E>(renderer: Renderer<E> = defaultRenderer): D.Debug<Cause<E>> =>
+  D.Debug((cause) => prettyPrint(cause, renderer))
+
+export const Debug = makeDebug()

package/src/Cause/CauseError.ts

@@ -0,0 +1,55 @@
+import type { Cause } from './Cause.js'
+import { Renderer, defaultRenderer, prettyPrint } from './Renderer.js'
+
+import * as Trace from '@/Trace/Trace.js'
+
+export class CauseError<E> extends Error {
+  constructor(readonly causedBy: Cause<E>, renderer: Renderer<E> = defaultRenderer) {
+    // Separate any taces from the message to use the Error.stack with the Traces
+    const [cause, trace] = causeAndTrace(causedBy)
+
+    // Print the message
+    super(prettyPrint(cause, renderer))
+
+    this.name = 'CauseError'
+
+    // If there is a Trace, add it to the Error
+    if (trace.tag !== 'EmptyTrace') {
+      this.stack = renderer.renderTrace(trace).replace(/\n/g, '\n    ')
+    }
+
+    // Ammend the Error that caused everything
+    if (cause.tag === 'Unexpected' && cause.error instanceof Error) {
+      this.cause = cause.error
+    }
+
+    this.toString = () => prettyPrint(causedBy, renderer)
+  }
+}
+
+/**
+ * Splits any top-level Trace nodes from the rest of the Cause
+ */
+export function causeAndTrace<E>(cause: Cause<E>): readonly [Cause<E>, Trace.Trace] {
+  let trace: Trace.Trace = Trace.EmptyTrace
+  let causeToPrint = cause
+
+  while (causeToPrint.tag === 'Traced') {
+    trace = Trace.Associative.concat(trace, causeToPrint.trace)
+    causeToPrint = causeToPrint.cause
+  }
+
+  return [causeToPrint, trace] as const
+}
+
+export function getCauseError<E>(cause: Cause<E>): Error {
+  if (cause.tag === 'Traced') {
+    return getCauseError(cause.cause)
+  }
+
+  if ((cause.tag === 'Unexpected' || cause.tag === 'Expected') && cause.error instanceof Error) {
+    return cause.error
+  }
+
+  return new CauseError(cause)
+}