@typed/async-data 0.2.0 → 0.3.1

package/src/AsyncData.ts

@@ -6,12 +6,22 @@
  */
 
 import type { Effect } from "effect"
-import { Cause, Data, Equal, Equivalence, Exit, Option, Unify } from "effect"
+import * as Cause from "effect/Cause"
+import * as Data from "effect/Data"
+import * as Duration from "effect/Duration"
+import * as Either from "effect/Either"
+import * as Equal from "effect/Equal"
+import * as Equivalence from "effect/Equivalence"
+import * as Exit from "effect/Exit"
 import { dual } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Unify from "effect/Unify"
 import * as internal from "./internal/async-data.js"
 import { FAILURE_TAG, LOADING_TAG, NO_DATA_TAG, SUCCESS_TAG } from "./internal/tag.js"
 import * as Progress from "./Progress.js"
 
+const getCurrentTimestamp = () => Date.now()
+
 /**
  * AsyncData represents a piece of data which is acquired asynchronously with loading, failure, and progress states
  * in addition to Option-like states of NoData and Success.
@@ -107,15 +117,18 @@ export class Loading extends Data.TaggedError(LOADING_TAG)<LoadingOptions> {
  * @since 1.0.0
  */
 export type LoadingOptions = {
+  readonly timestamp: number // Date.now()
   readonly progress: Option.Option<Progress.Progress>
 }
 
 /**
  * @since 1.0.0
  */
-export type OptionalPartial<A> = {
-  [K in keyof A]+?: [A[K]] extends [Option.Option<infer R>] ? R | undefined : A[K]
-}
+export type OptionalPartial<A> = [
+  {
+    [K in keyof A]+?: [A[K]] extends [Option.Option<infer R>] ? R | undefined : A[K]
+  }
+] extends [infer R] ? { readonly [K in keyof R]: R[K] } : never
 
 /**
  * @since 1.0.0
@@ -125,13 +138,14 @@ export const loading: {
   <E, A>(options?: OptionalPartial<LoadingOptions>): AsyncData<E, A>
 } = (options?: OptionalPartial<LoadingOptions>): Loading =>
   new Loading({
+    timestamp: options?.timestamp ?? getCurrentTimestamp(),
     progress: Option.fromNullable(options?.progress)
   })
 
 /**
  * @since 1.0.0
  */
-export interface Failure<E> extends Effect.Effect<never, E, never> {
+export interface Failure<out E> extends Effect.Effect<never, E, never> {
   /**
    * @since 1.18.0
    */
@@ -142,6 +156,11 @@ export interface Failure<E> extends Effect.Effect<never, E, never> {
    */
   readonly cause: Cause.Cause<E>
 
+  /**
+   * @since 1.20.0
+   */
+  readonly timestamp: number // Date.now()
+
   /**
    * @since 1.18.0
    */
@@ -167,6 +186,7 @@ export interface Failure<E> extends Effect.Effect<never, E, never> {
  * @since 1.0.0
  */
 export type FailureOptions = {
+  readonly timestamp: number // Date.now()
   readonly refreshing: Option.Option<Loading>
 }
 
@@ -179,6 +199,7 @@ export const failCause: {
 } = <E>(cause: Cause.Cause<E>, options?: OptionalPartial<FailureOptions>): Failure<E> =>
   new internal.FailureImpl(
     cause,
+    options?.timestamp ?? getCurrentTimestamp(),
     Option.fromNullable(options?.refreshing)
   )
 
@@ -193,9 +214,13 @@ export const fail: {
 /**
  * @since 1.0.0
  */
-export interface Success<A> extends Effect.Effect<never, never, A> {
+export interface Success<out A> extends Effect.Effect<never, never, A> {
   readonly _tag: typeof SUCCESS_TAG
   readonly value: A
+  /**
+   * @since 1.20.0
+   */
+  readonly timestamp: number // Date.now()
   readonly refreshing: Option.Option<Loading>
 
   readonly [Unify.typeSymbol]: unknown
@@ -207,6 +232,7 @@ export interface Success<A> extends Effect.Effect<never, never, A> {
  * @since 1.0.0
  */
 export type SuccessOptions = {
+  readonly timestamp: number // Date.now()
   readonly refreshing: Option.Option<Loading>
 }
 
@@ -219,6 +245,7 @@ export const success: {
 } = <A>(value: A, options?: OptionalPartial<SuccessOptions>): Success<A> =>
   new internal.SuccessImpl(
     value,
+    options?.timestamp ?? getCurrentTimestamp(),
     Option.fromNullable(options?.refreshing)
   )
 
@@ -400,6 +427,7 @@ const optionProgressEq = Option.getEquivalence(Progress.equals)
 
 const loadingEquivalence: Equivalence.Equivalence<Loading> = Equivalence.struct({
   _tag: Equivalence.string,
+  timestamp: Equivalence.number,
   progress: optionProgressEq
 })
 
@@ -408,6 +436,7 @@ const optionLoadingEq = Option.getEquivalence(loadingEquivalence)
 const failureEquivalence: Equivalence.Equivalence<Failure<any>> = Equivalence.struct({
   _tag: Equivalence.string,
   cause: Equal.equals,
+  timestamp: Equivalence.number,
   refreshing: optionLoadingEq
 })
 
@@ -415,6 +444,7 @@ const successEquivalence = <A>(valueEq: Equivalence.Equivalence<A>): Equivalence
   Equivalence.struct({
     _tag: Equivalence.string,
     value: valueEq,
+    timestamp: Equivalence.number,
     refreshing: optionLoadingEq
   })
 
@@ -432,3 +462,73 @@ export const getEquivalence =
       Success: (_, s1) => isSuccess(b) ? successEquivalence(valueEq)(s1, b) : false
     })
   }
+
+/**
+ * @since 1.0.0
+ */
+export function fromExit<E, A>(exit: Exit.Exit<E, A>): AsyncData<E, A> {
+  return Exit.match(exit, {
+    onFailure: (cause) => failCause(cause),
+    onSuccess: (value) => success(value)
+  })
+}
+
+/**
+ * @since 1.0.0
+ */
+export function fromEither<E, A>(either: Either.Either<E, A>): AsyncData<E, A> {
+  return Either.match(either, {
+    onLeft: (e) => fail(e),
+    onRight: (a) => success(a)
+  })
+}
+
+const isAsyncDataFirst = (args: IArguments) => args.length === 3 || isAsyncData(args[0])
+
+/**
+ * @since 1.0.0
+ */
+export const isExpired: {
+  (ttl: Duration.DurationInput, now?: number): <E, A>(data: AsyncData<E, A>) => boolean
+  <E, A>(data: AsyncData<E, A>, ttl: Duration.DurationInput, now?: number): boolean
+} = dual(isAsyncDataFirst, function isExpired<E, A>(
+  data: AsyncData<E, A>,
+  ttl: Duration.DurationInput,
+  now: number = getCurrentTimestamp()
+): boolean {
+  return match(data, {
+    NoData: () => true,
+    Loading: () => false,
+    Failure: (_, f) =>
+      Option.isNone(f.refreshing)
+        ? isPastTTL(f.timestamp, ttl, now)
+        : isPastTTL(f.refreshing.value.timestamp, ttl, now),
+    Success: (_, s) =>
+      Option.isNone(s.refreshing)
+        ? isPastTTL(s.timestamp, ttl, now) :
+        isPastTTL(s.refreshing.value.timestamp, ttl, now)
+  })
+})
+
+function isPastTTL(timestamp: number, ttl: Duration.DurationInput, now: number): boolean {
+  const millis = Duration.toMillis(ttl)
+
+  return now - timestamp > millis
+}
+
+/**
+ * Checks if two AsyncData are equal, disregarding the timestamps associated with them. Useful for testing
+ * without needing to manage timestamps.
+ *
+ * @since 1.0.0
+ */
+export function dataEqual<E, A>(first: AsyncData<E, A>, second: AsyncData<E, A>): boolean {
+  return match(first, {
+    NoData: () => isNoData(second),
+    Loading: (l) => isLoading(second) && Equal.equals(l.progress, second.progress),
+    Failure: (_, f1) =>
+      isFailure(second) && Equal.equals(f1.cause, second.cause) && Equal.equals(f1.refreshing, second.refreshing),
+    Success: (_, s1) =>
+      isSuccess(second) && Equal.equals(s1.value, second.value) && Equal.equals(s1.refreshing, second.refreshing)
+  })
+}

package/src/Progress.ts

@@ -2,25 +2,30 @@
  * @since 1.0.0
  */
 
-import { Equivalence, Option } from "effect"
+import { Data } from "effect"
+import * as Equivalence from "effect/Equivalence"
 import { dual } from "effect/Function"
+import * as Option from "effect/Option"
 
 /**
  * @since 1.0.0
  */
-export interface Progress {
-  readonly loaded: bigint
-  readonly total: Option.Option<bigint>
+export interface Progress extends
+  Data.Data<{
+    readonly loaded: bigint
+    readonly total: Option.Option<bigint>
+  }>
+{
 }
 
 /**
  * @since 1.0.0
  */
 export function Progress(loaded: bigint, total: Option.Option<bigint> = Option.none()): Progress {
-  return {
+  return Data.struct({
     loaded,
     total
-  }
+  })
 }
 
 /**
@@ -58,8 +63,23 @@ export const setTotal: {
  * @since 1.0.0
  */
 export const equals: Equivalence.Equivalence<Progress> = Equivalence.struct<
-  { readonly [K in keyof Progress]: Equivalence.Equivalence<Progress[K]> }
+  { readonly [K in Exclude<keyof Progress, keyof Data.Data<any>>]: Equivalence.Equivalence<Progress[K]> }
 >({
   loaded: Equivalence.bigint,
   total: Option.getEquivalence(Equivalence.bigint)
 })
+
+/**
+ * @since 1.0.0
+ */
+export function pretty(progress: Progress): string {
+  return `${progress.loaded}${
+    Option.match(
+      progress.total,
+      {
+        onNone: () => "",
+        onSome: (total) => `/${total}`
+      }
+    )
+  }`
+}