@typed/fx 0.0.8 → 0.0.10

package/perf/_internal.ts

@@ -0,0 +1,153 @@
+import process from 'node:process'
+
+import * as EffectStream from '@effect/core/Stream/Stream'
+import * as Effect from '@effect/core/io/Effect'
+import * as M from '@most/core'
+import * as MS from '@most/scheduler'
+import * as MT from '@most/types'
+import benchmark, { Suite } from 'benchmark'
+import * as RxJS from 'rxjs'
+
+import * as Fx from '@/index.js'
+
+export function parseIterations() {
+  const i = parseInt(process.argv[2], 10)
+
+  return Number.isNaN(i) ? 10000 : i
+}
+
+export const iterations = parseIterations()
+export const array = Array.from({ length: iterations }, (_, i) => i)
+
+export function runSuite(suite: Suite, cb: () => void) {
+  suite
+    .on('start', logStart)
+    .on('cycle', logResults)
+    .on('complete', () => {
+      logComplete()
+      cb()
+    })
+    .run({ defer: false })
+}
+
+const longestLibrary = 13
+const longestOps = 10
+
+function logResults(e: any) {
+  const t = e.target
+
+  if (t.failure) {
+    console.log(`| ${t.name} | FAILED | ${e.target.failure} |`)
+
+    console.error(padl(10, t.name) + 'FAILED: ' + e.target.failure)
+  } else {
+    console.log(
+      `| ${padl(longestLibrary, t.name)} | ${padl(longestOps, t.hz.toFixed(2))} | ${padl(
+        6,
+        t.stats.rme.toFixed(2) + '%',
+      )} | ${padl(3, t.stats.sample.length)}      |`,
+    )
+  }
+}
+
+function logStart(this: any) {
+  console.log('### ' + this.name)
+  console.log(`| Library       | Ops/sec    | ±      | Samples |
+| --------------|------------|--------|---------|`)
+}
+
+function logComplete() {
+  console.log('-------------------------------------------------------\n')
+}
+
+function padl(n: number, s: string) {
+  while (s.length < n) {
+    s += ' '
+  }
+  return s
+}
+
+// function padr(n: number, s: string) {
+//   while (s.length < n) {
+//     s = ' ' + s
+//   }
+//   return s
+// }
+
+export interface PerformanceTest {
+  readonly name: string
+  readonly cases: readonly PerformanceTestCase<any>[]
+}
+
+export interface PerformanceTestCase<A> {
+  name: string
+  init: () => A
+  run: (a: A, deferred: benchmark.Deferred) => void
+}
+
+export function PerformanceTestCase<A>(
+  name: string,
+  init: () => A,
+  run: (a: A, deferred: benchmark.Deferred) => void,
+): PerformanceTestCase<A> {
+  return { name, init, run }
+}
+
+export function runPerformanceTest(test: PerformanceTest, cb: () => void) {
+  // eslint-disable-next-line import/no-named-as-default-member
+  let suite = new benchmark.Suite(test.name)
+
+  for (const testCase of test.cases) {
+    const constructed = testCase.init()
+
+    suite = suite.add(testCase.name, (deferred: benchmark.Deferred) =>
+      testCase.run(constructed, deferred),
+    )
+  }
+
+  runSuite(suite, cb)
+}
+
+export function fxTest<E, A>(init: () => Fx.Fx<never, E, A>) {
+  return PerformanceTestCase(
+    'Fx',
+    () => {
+      const push = init()
+
+      return Fx.runDrain(push)
+    },
+    (fx, deferred) => Effect.unsafeRunAsyncWith(fx, () => deferred.resolve()),
+  )
+}
+
+export function fxEffectTest<E, A>(init: () => Effect.Effect<never, E, A>) {
+  return PerformanceTestCase('Fx', init, (e, deferred) => {
+    Effect.unsafeRunPromise(e).then(() => deferred.resolve())
+  })
+}
+
+export function mostStreamTest<A>(init: () => MT.Stream<A>) {
+  const mostScheduler = MS.newDefaultScheduler()
+
+  return PerformanceTestCase('@most/core', init, (mostStream, deferred) =>
+    M.runEffects(mostStream, mostScheduler).then(() => deferred.resolve()),
+  )
+}
+
+export function rxjsObservableTest<A>(init: () => RxJS.Observable<A>) {
+  return PerformanceTestCase('RxJS @7', init, (observable, deferred) => {
+    observable.subscribe({
+      complete: () => deferred.resolve(),
+    })
+  })
+}
+
+export function effectTsStreamTest<E, A>(init: () => EffectStream.Stream<never, E, A>) {
+  return PerformanceTestCase(
+    'Effect/Stream',
+    () => EffectStream.runDrain(init()),
+    (e, deferred) => {
+      Effect.unsafeRunPromise(e).then(() => deferred.resolve())
+    },
+  )
+}

package/perf/cases/filter-map-reduce.ts

@@ -0,0 +1,48 @@
+import * as EffectStream from '@effect/core/Stream/Stream'
+import { pipe } from '@fp-ts/data/Function'
+import * as M from '@most/core'
+import * as Chunk from '@tsplus/stdlib/collections/Chunk'
+import * as rxjs from 'rxjs'
+
+import {
+  array,
+  effectTsStreamTest,
+  fxEffectTest,
+  iterations,
+  mostStreamTest,
+  rxjsObservableTest,
+} from '../_internal.js'
+
+import * as Stream from '@/index.js'
+
+const filterEvens = (x: number) => x % 2 === 0
+const addOne = (x: number) => x + 1
+const add = (x: number, y: number): number => x + y
+
+export const name = 'filter -> map -> scan ' + iterations + ' integers'
+
+export const cases = [
+  fxEffectTest(() =>
+    pipe(
+      Stream.fromIterable(array),
+      Stream.filter(filterEvens),
+      Stream.map(addOne),
+      Stream.runReduce(0, add),
+    ),
+  ),
+  mostStreamTest(() =>
+    pipe(M.periodic(0), M.withItems(array), M.filter(filterEvens), M.map(addOne), M.scan(add, 0)),
+  ),
+  rxjsObservableTest(() =>
+    pipe(rxjs.from(array), rxjs.filter(filterEvens), rxjs.map(addOne), rxjs.scan(add, 0)),
+  ),
+
+  effectTsStreamTest(() =>
+    pipe(
+      EffectStream.fromChunk(Chunk.from(array)),
+      EffectStream.filter(filterEvens),
+      EffectStream.map(addOne),
+      EffectStream.scan(0, add),
+    ),
+  ),
+]

package/perf/cases/flatMap.ts

@@ -0,0 +1,49 @@
+import * as EffectStream from '@effect/core/Stream/Stream'
+import { pipe } from '@fp-ts/data/Function'
+import * as M from '@most/core'
+import * as Chunk from '@tsplus/stdlib/collections/Chunk'
+import * as rxjs from 'rxjs'
+
+import {
+  array,
+  effectTsStreamTest,
+  fxTest,
+  iterations,
+  mostStreamTest,
+  rxjsObservableTest,
+} from '../_internal.js'
+
+import * as Stream from '@/index.js'
+
+const nestedArray = array.map((x) => Array.from({ length: x }, (_, i) => x * 1000 + i))
+
+const add = (x: number, y: number): number => x + y
+
+export const name = 'flatMap ' + iterations + ' x ' + iterations + ' integers'
+export const cases = [
+  fxTest(() =>
+    pipe(
+      Stream.fromIterable(nestedArray),
+      Stream.flatMap(Stream.fromIterable),
+      Stream.scan(0, add),
+    ),
+  ),
+  mostStreamTest(() =>
+    pipe(
+      M.periodic(0),
+      M.withItems(nestedArray),
+      M.chain((ns) => pipe(M.periodic(0), M.withItems(ns))),
+      M.scan(add, 0),
+    ),
+  ),
+  rxjsObservableTest(() =>
+    pipe(rxjs.from(nestedArray), rxjs.flatMap(rxjs.from), rxjs.scan(add, 0)),
+  ),
+  effectTsStreamTest(() =>
+    pipe(
+      EffectStream.fromChunk(Chunk.from(nestedArray)),
+      EffectStream.flatMap((ns) => EffectStream.fromChunk(Chunk.from(ns))),
+      EffectStream.scan(0, add),
+    ),
+  ),
+]

package/perf/cases/switchMap.ts

@@ -0,0 +1,36 @@
+import { pipe } from '@fp-ts/data/Function'
+import * as M from '@most/core'
+import * as rxjs from 'rxjs'
+
+import { array, fxTest, iterations, mostStreamTest, rxjsObservableTest } from '../_internal.js'
+
+import * as Stream from '@/index.js'
+
+const nestedArray = array.map((x) => Array.from({ length: x }, (_, i) => x * 1000 + i))
+
+const add = (x: number, y: number): number => x + y
+
+export const name = 'switchMap ' + iterations + ' x ' + iterations + ' integers'
+
+export const cases = [
+  fxTest(() =>
+    pipe(
+      Stream.fromIterable(nestedArray),
+      Stream.switchMap(Stream.fromIterable),
+      Stream.scan(0, add),
+    ),
+  ),
+  mostStreamTest(() =>
+    pipe(
+      M.periodic(0),
+      M.withItems(nestedArray),
+      M.map((ns) => pipe(M.periodic(0), M.withItems(ns))),
+      M.switchLatest,
+      M.scan(add, 0),
+    ),
+  ),
+  rxjsObservableTest(() =>
+    pipe(rxjs.from(nestedArray), rxjs.switchMap(rxjs.from), rxjs.scan(add, 0)),
+  ),
+  // Effect Stream is pull-based and does not offer switchMap
+]

package/perf/readme-base.md

@@ -0,0 +1,14 @@
+# Performance Tests
+
+Here is the latest output of the perf test suite run on a 2020 13" macbook pro.
+It is worth noting that all the tests utilize entirely synchronous workflows, and thus
+have a great favoring towards Most.js/RxJS in terms of raw performance overhead. 
+
+If you need strict performance over push-based streams, definitely use Most.js, but if you are
+interested in the superpowers of `Effect`, and are interested in using push-based streams as a means
+of orchestration `Fx` is still a great bet as it won't often be your bottleneck.
+
+If you need strict performance no matter what, none of these abstractions should be utilized at all.
+
+## Test Results
+

package/perf/readme.md

@@ -0,0 +1,40 @@
+# Performance Tests
+
+Here is the latest output of the perf test suite run on a 2020 13" macbook pro.
+It is worth noting that all the tests utilize entirely synchronous workflows, and thus
+have a great favoring towards Most.js/RxJS in terms of raw performance overhead. 
+
+If you need strict performance over push-based streams, definitely use Most.js, but if you are
+interested in the superpowers of `Effect`, and are interested in using push-based streams as a means
+of orchestration `Fx` is still a great bet as it won't often be your bottleneck.
+
+If you need strict performance no matter what, none of these abstractions should be utilized at all.
+
+## Test Results
+
+### filter -> map -> scan 10000 integers
+| Library       | Ops/sec    | ±      | Samples |
+| --------------|------------|--------|---------|
+| Fx            | 3801.43    | 5.81%  | 82      |
+| @most/core    | 384094.58  | 12.96% | 64      |
+| RxJS @7       | 2255.04    | 12.60% | 87      |
+| Effect/Stream | 91.50      | 29.12% | 41      |
+-------------------------------------------------------
+
+### flatMap 10000 x 10000 integers
+| Library       | Ops/sec    | ±      | Samples |
+| --------------|------------|--------|---------|
+| Fx            | 6474.91    | 11.85% | 76      |
+| @most/core    | 276654.02  | 19.33% | 46      |
+| RxJS @7       | 10322.11   | 52.99% | 77      |
+| Effect/Stream | 2.29       | 124.34% | 9      |
+-------------------------------------------------------
+
+### switchMap 10000 x 10000 integers
+| Library       | Ops/sec    | ±      | Samples |
+| --------------|------------|--------|---------|
+| Fx            | 4759.84    | 13.52% | 63      |
+| @most/core    | 300663.64  | 14.57% | 55      |
+| RxJS @7       | 16469.83   | 2.63%  | 75      |
+-------------------------------------------------------
+

package/perf/runFullSuite.ts

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const currentDir = dirname(fileURLToPath(import.meta.url))
+const casesDir = join(currentDir, '/cases')
+
+export const runPerfTestPath = join(currentDir, 'runPerfTest.ts')
+export const readmeBasePath = join(currentDir, 'readme-base.md')
+export const readmePath = join(currentDir, 'readme.md')
+export const fileNames = fs.readdirSync(casesDir).map((x) => basename(x))
+
+let readmeContent = fs.readFileSync(readmeBasePath, 'utf-8').toString()
+
+for (const fileName of fileNames) {
+  console.log('Running', 'cases/' + basename(fileName), '\n')
+
+  const { stdout } = spawnSync(`node`, [
+    `--loader`,
+    `@esbuild-kit/esm-loader`,
+    `${runPerfTestPath}`,
+    `${fileName}`,
+  ])
+
+  const output = stdout.toString()
+
+  console.log(output)
+
+  readmeContent += output
+}
+
+if (fs.existsSync(readmePath)) {
+  fs.unlinkSync(readmePath)
+}
+
+fs.writeFileSync(readmePath, readmeContent)

package/perf/runPerfTest.ts

@@ -0,0 +1,18 @@
+import process from 'node:process'
+
+import { runPerformanceTest } from './_internal.js'
+
+const fileName = process.argv.slice(2).filter((x) => x.trim() !== '--')[0]
+
+async function main() {
+  const { name, cases } = await import(
+    `./cases/${fileName}${fileName.endsWith('.ts') ? '' : '.ts'}`
+  )
+
+  runPerformanceTest({ name, cases }, () => process.exit(0))
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/perf/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../tsconfig.base.json",
+  "include": [
+    "."
+  ]
+}

package/readme.md

@@ -1,34 +1,7 @@
 # @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. 
+`Fx` is a toolkit for composing synchronous, asynchronous, and event-based programs using reactive programming.
 
+It is built directly atop of [Effect-ts](https://github.com/Effect-TS/core) an inherits all of its capabilities
+while being able to be bi-directionally converted `Effect <-> Fx`. `Fx` is intended to be the shorthand for plural form of `Effect` "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
-- 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 30kb 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/Fx.ts

@@ -0,0 +1,50 @@
+import { Cause } from '@effect/core/io/Cause'
+import * as Effect from '@effect/core/io/Effect'
+import { Scope } from '@effect/core/io/Scope'
+
+/**
+ * TODOS:
+ * until
+ * since
+ * during
+ */
+
+export interface Fx<R, E, A> {
+  run<R2>(emitter: Emitter<R2, E, A>): Effect.Effect<R | R2 | Scope, never, unknown>
+}
+
+export function Fx<R, E, A>(run: Fx<R, E, A>['run']): Fx<R, E, A> {
+  return {
+    run,
+  }
+}
+
+export namespace Fx {
+  export type ResourcesOf<T> = T extends Fx<infer R, any, any> ? R : never
+  export type ErrorsOf<T> = T extends Fx<any, infer E, any> ? E : never
+  export type OutputOf<T> = T extends Fx<any, any, infer A> ? A : never
+}
+
+export interface Emitter<R, E, A> {
+  readonly emit: (a: A) => Effect.Effect<R, never, unknown>
+  readonly failCause: (e: Cause<E>) => Effect.Effect<R, never, unknown>
+  readonly end: Effect.Effect<R, never, unknown>
+}
+
+export function Emitter<R, E, A>(
+  emit: Emitter<R, E, A>['emit'],
+  failCause: Emitter<R, E, A>['failCause'],
+  end: Emitter<R, E, A>['end'],
+): Emitter<R, E, A> {
+  return {
+    emit,
+    failCause,
+    end,
+  }
+}
+
+export namespace Emitter {
+  export type ResourcesOf<T> = T extends Emitter<infer R, any, any> ? R : never
+  export type ErrorsOf<T> = T extends Emitter<any, infer E, any> ? E : never
+  export type OutputOf<T> = T extends Emitter<any, any, infer A> ? A : never
+}

package/src/_internal.ts

@@ -0,0 +1,74 @@
+import {
+  CountdownLatch,
+  CountdownLatchInternal,
+} from '@effect/core/concurrent/CountdownLatch/definition'
+import * as Cause from '@effect/core/io/Cause'
+import * as Deferred from '@effect/core/io/Deferred'
+import * as Effect from '@effect/core/io/Effect'
+import * as Ref from '@effect/core/io/Ref'
+import { pipe } from '@fp-ts/data/Function'
+import * as Maybe from '@tsplus/stdlib/data/Maybe'
+
+export const EARLY_EXIT_FAILURE = Symbol('EarlyExitFailure')
+export interface EarlyExitFailure {
+  readonly sym: typeof EARLY_EXIT_FAILURE
+}
+export const EarlyExitFailure: EarlyExitFailure = { sym: EARLY_EXIT_FAILURE }
+
+export function isEarlyExitFailure(u: unknown): u is EarlyExitFailure {
+  return typeof u === 'object' && u !== null && (u as any).sym === EARLY_EXIT_FAILURE
+}
+
+export const exitEarly = Effect.die(EarlyExitFailure)
+
+export const onEarlyExitFailure =
+  <R2, E2, B>(handler: Effect.Effect<R2, E2, B>) =>
+  <R, E, A>(effect: Effect.Effect<R, E, A>): Effect.Effect<R | R2, E | E2, A | B> =>
+    pipe(
+      effect,
+      Effect.foldCauseEffect<E, A, R | R2, E | E2, A | B, R | R2, E | E2, A | B>(
+        (e) =>
+          pipe(
+            e,
+            Cause.dieMaybe,
+            Maybe.fold(
+              () => Effect.failCause(e),
+              (d) => (isEarlyExitFailure(d) ? handler : Effect.failCause(e)),
+            ),
+          ),
+        Effect.succeed,
+      ),
+    )
+
+/**
+ * A small wrapper around CountdownLatch which enables incrementing
+ * the latch count dynamically
+ */
+export type DynamicCountdownLatch = {
+  readonly increment: Effect.Effect<never, never, void>
+  readonly latch: CountdownLatch
+}
+
+export function makeDynamicCountdownLatch(
+  initialCount: number,
+): Effect.Effect<never, never, DynamicCountdownLatch> {
+  return pipe(
+    Ref.makeRef<number>(() => initialCount),
+    Effect.zipWith(Deferred.make<never, void>(), (ref, deferred) => ({
+      increment: ref.update((x) => x + 1),
+      latch: new CountdownLatchInternal(ref, deferred),
+    })),
+  )
+}
+
+export function withDynamicCountdownLatch<R, E, A, R2, E2, B>(
+  initialCount: number,
+  f: (latch: DynamicCountdownLatch) => Effect.Effect<R, E, A>,
+  onEnd: Effect.Effect<R2, E2, B>,
+): Effect.Effect<R | R2, E | E2, B> {
+  return pipe(
+    makeDynamicCountdownLatch(initialCount),
+    Effect.tap(f),
+    Effect.flatMap(({ latch }) => pipe(latch.await, Effect.zipRight(onEnd))),
+  )
+}

package/src/combine.test.ts

@@ -0,0 +1,34 @@
+import { deepStrictEqual } from 'assert'
+
+import * as Effect from '@effect/core/io/Effect'
+import { pipe } from '@fp-ts/data/Function'
+import * as Duration from '@tsplus/stdlib/data/Duration'
+
+import * as Fx from './index.js'
+
+describe(import.meta.url, () => {
+  describe('combine', () => {
+    it('combines 2 fx together', async () => {
+      const values = [1, 2, 3]
+      const test = pipe(
+        Fx.fromIterable(values),
+        Fx.flatMap((a) =>
+          pipe(
+            Fx.fromIterable([a, a + 1]),
+            Fx.combine(pipe(Fx.fromIterable([a * a, a ** a]), Fx.delay(Duration.millis(10)))),
+          ),
+        ),
+      )
+      const events = await pipe(test, Fx.runCollect, Effect.unsafeRunPromise)
+
+      deepStrictEqual(events, [
+        [1 + 1, 1 * 1],
+        [2 + 1, 2 * 2],
+        [3 + 1, 3 * 3],
+        [1 + 1, 1 ** 1],
+        [2 + 1, 2 ** 2],
+        [3 + 1, 3 ** 3],
+      ])
+    })
+  })
+})

package/src/combine.ts

@@ -0,0 +1,62 @@
+import * as Effect from '@effect/core/io/Effect'
+import { pipe } from '@fp-ts/data/Function'
+import * as Maybe from '@tsplus/stdlib/data/Maybe'
+
+import { Emitter, Fx } from './Fx.js'
+import { withDynamicCountdownLatch } from './_internal.js'
+
+export function combine<R2, E2, B>(second: Fx<R2, E2, B>) {
+  return <R, E, A>(first: Fx<R, E, A>): Fx<R | R2, E | E2, readonly [A, B]> =>
+    combineAll([first, second])
+}
+
+export function combineAll<FX extends ReadonlyArray<Fx<any, any, any>>>(
+  fx: readonly [...FX],
+): Fx<
+  Fx.ResourcesOf<FX[number]>,
+  Fx.ErrorsOf<FX[number]>,
+  { readonly [K in keyof FX]: Fx.OutputOf<FX[K]> }
+>
+
+export function combineAll<R, E, A>(iterable: Iterable<Fx<R, E, A>>): Fx<R, E, ReadonlyArray<A>>
+
+export function combineAll<R, E, A>(iterable: Iterable<Fx<R, E, A>>): Fx<R, E, ReadonlyArray<A>> {
+  return Fx((emitter) =>
+    Effect.suspendSucceed(() => {
+      const array = Array.from(iterable)
+
+      return pipe(
+        Effect.sync<Maybe.Maybe<A>[]>(() => Array(array.length)),
+        Effect.flatMap((ref) =>
+          Effect.suspendSucceed(() => {
+            const emitIfReady = pipe(
+              Effect.sync(() => ref.filter(Maybe.isSome).map((x) => x.value)),
+              Effect.flatMap((bs) => (bs.length === array.length ? emitter.emit(bs) : Effect.unit)),
+            )
+
+            return withDynamicCountdownLatch(
+              array.length,
+              ({ latch }) =>
+                Effect.forEachWithIndex(array, (fx, i) =>
+                  Effect.forkScoped(
+                    fx.run(
+                      Emitter(
+                        (a) =>
+                          pipe(
+                            Effect.sync(() => (ref[i] = Maybe.some(a))),
+                            Effect.zipRight(emitIfReady),
+                          ),
+                        emitter.failCause,
+                        latch.countDown,
+                      ),
+                    ),
+                  ),
+                ),
+              emitter.end,
+            )
+          }),
+        ),
+      )
+    }),
+  )
+}