Type Alias FuturesAPI

The API for Futures.

The Serializable equivalent of a vanilla JavaScript Promise.

type FuturesAPI = {
    create: <T extends Serializable>(
        executor: FutureExecutor<T>,
    ) => Future<T>;
    withResolvers: <T extends Serializable>() => Struct<
        {
            future: Future<T>;
            id: FutureId<T>;
            reject: RejectCallback;
            resolve: ResolveCallback<T>;
        },
    >;
    resolveFutureById: <T extends Serializable>(
        futureId: FutureId<T>,
        ...result: T extends void ? [undefined?] : [ValidResult<T>],
    ) => void;
    rejectFutureById: <T extends Serializable>(
        futureId: FutureId<T>,
        reason?: Serializable,
    ) => void;
    resolve: <T extends Serializable>(
        ...result: T extends void ? [undefined?] : [ValidResult<T>],
    ) => Future<T>;
    reject: <T extends Serializable = Serializable>(
        reason?: Serializable,
    ) => Future<T>;
    try: <Impl extends AnyMethodImpl>(
        method: Method<Impl>,
        ...args: Parameters<Impl>,
    ) => Future<UnwrapFuture<ReturnType<Impl>>>;
    race: {
        <T extends readonly ValidResult<Serializable>[]>(
            values: T,
        ): Future<UnwrapFuture<T[number]>>;
        <T extends ValidResult<Serializable>>(
            values: Iterable<T>,
        ): Future<UnwrapFuture<T>>;
    };
    all: {
        <T extends readonly ValidResult<Serializable>[]>(
            values: T,
        ): Future<
            List<
                { -readonly [I in string
                | number
                | symbol]: UnwrapFuture<T[I]> },
            >,
        >;
        <T extends ValidResult<Serializable>>(
            values: Iterable<T>,
        ): Future<List<UnwrapFuture<T>[]>>;
    };
    any: {
        <T extends readonly ValidResult<Serializable>[]>(
            values: T,
        ): Future<UnwrapFuture<T[number]>>;
        <T extends ValidResult<Serializable>>(
            values: Iterable<T>,
        ): Future<UnwrapFuture<T>>;
    };
    allSettled: {
        <T extends readonly ValidResult<Serializable>[]>(
            values: T,
        ): Future<
            List<
                {
                    -readonly [I in string
                    | number
                    | symbol]: FutureSettledResult<UnwrapFuture<T[I]>>
                },
            >,
        >;
        <T extends ValidResult<Serializable>>(
            values: Iterable<T>,
        ): Future<List<FutureSettledResult<UnwrapFuture<T>>[]>>;
    };
}

Index

Properties

create withResolvers resolveFutureById rejectFutureById resolve reject try race all any allSettled

Properties

create

create: <T extends Serializable>(executor: FutureExecutor<T>) => Future<T>

Creates a Future.

Type Declaration

- <T extends Serializable>(executor: FutureExecutor<T>): Future<T>
- Type Parameters
  - T extends Serializable
  Parameters
  - executor: FutureExecutor<T>
    A callback that receives the Future's FutureId, ResolveCallback, and RejectCallback.
  Returns Future<T>
  A Future.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

// Sends an email and returns a Future that resolves with its response.
function sendEmail(
  to: string,
  subject: string,
  body: string
): Future<string> {
  return futures.create<string>((id, _resolve, _reject) => {
    emailService.send({
      to,
      subject,
      body,
      metadata: JSON.stringify({ id }),
    });
  });
}

// Email may be received on another session.
emailService.onEmail((response: string, metadata: string) => {
  const futureId = JSON.parse(metadata).id as FutureId<string>;
  futures.resolveFutureById(futureId, response);
});

withResolvers

withResolvers: <T extends Serializable>() => Struct<
    {
        future: Future<T>;
        id: FutureId<T>;
        reject: RejectCallback;
        resolve: ResolveCallback<T>;
    },
>

Creates a Future and returns it, its ResolveCallback, its RejectCallback, and its FutureId.

Type Declaration

- <T extends Serializable>(): Struct<
      {
          future: Future<T>;
          id: FutureId<T>;
          reject: RejectCallback;
          resolve: ResolveCallback<T>;
      },
  >
- Type Parameters
  - T extends Serializable
  Returns Struct<
      {
          future: Future<T>;
          id: FutureId<T>;
          reject: RejectCallback;
          resolve: ResolveCallback<T>;
      },
  >
  A Future, its ResolveCallback, its RejectCallback, and its FutureId.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

// Sends an email and returns a Future that resolves with its response.
function sendEmail(
  to: string,
  subject: string,
  body: string
): Future<string> {
  const { future, id } = futures.withResolvers();
  emailService.send({
    to,
    subject,
    body,
    metadata: JSON.stringify({ id }),
  });
  return future;
}

// Email may be received on another session.
emailService.onEmail((response: string, metadata: string) => {
  const futureId = JSON.parse(metadata).id as FutureId<string>;
  futures.resolveFutureById(futureId, response);
});

resolveFutureById

resolveFutureById: <T extends Serializable>(
futureId: FutureId<T>,
...result: T extends void ? [undefined?] : [ValidResult<T>],
) => void

Resolves a Future using its FutureId.

Type Declaration

- <T extends Serializable>(
  futureId: FutureId<T>,
  ...result: T extends void ? [undefined?] : [ValidResult<T>],
  ): void
- Type Parameters
  - T extends Serializable
  Parameters
  - futureId: FutureId<T>
    The FutureId of the Future to resolve.
  - ...result: T extends void ? [undefined?] : [ValidResult<T>]
    The value to resolve the Future with.
  Returns void

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

// Email may be received on another session.
emailService.onEmail((response: string, metadata: string) => {
  const futureId = JSON.parse(metadata).id as FutureId<string>;
  futures.resolveFutureById(futureId, response);
});

// Sends an email and returns a Future that resolves with its response.
function sendEmail(
  to: string,
  subject: string,
  body: string
): Future<string> {
  const { future, id } = futures.withResolvers();
  emailService.send({
    to,
    subject,
    body,
    metadata: JSON.stringify({ id }),
  });
  return future;
}

rejectFutureById

rejectFutureById: <T extends Serializable>(
futureId: FutureId<T>,
reason?: Serializable,
) => void

Rejects a Future using its FutureId.

Type Declaration

- <T extends Serializable>(futureId: FutureId<T>, reason?: Serializable): void
- Type Parameters
  - T extends Serializable
  Parameters
  - futureId: FutureId<T>
    The FutureId of the Future to reject.
  - Optionalreason: Serializable
    The value to reject the Future with.
  Returns void

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

// Email may be received on another session.
emailService.onEmailDropped((metadata: string) => {
  const futureId = JSON.parse(metadata).id as FutureId<string>;
  futures.rejectFutureById(futureId, exceptions.createException('Email dropped.'));
});

// Sends an email and returns a Future that resolves with its response.
function sendEmail(
  to: string,
  subject: string,
  body: string
): Future<string> {
  const { future, id } = futures.withResolvers();
  emailService.send({
    to,
    subject,
    body,
    metadata: JSON.stringify({ id }),
  });
  return future;
}

resolve

resolve: <T extends Serializable>(
...result: T extends void ? [undefined?] : [ValidResult<T>],
) => Future<T>

Creates a Future resolved with result.

Type Declaration

- <T extends Serializable>(
  ...result: T extends void ? [undefined?] : [ValidResult<T>],
  ): Future<T>
- Type Parameters
  - T extends Serializable
  Parameters
  - ...result: T extends void ? [undefined?] : [ValidResult<T>]
    The value to resolve the Future with.
  Returns Future<T>
  A Future resolved with result.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

const future: Future<string> = futures.resolve("Hello");

reject

reject: <T extends Serializable = Serializable>(
reason?: Serializable,
) => Future<T>

Creates a Future rejected with reason.

Type Declaration

- <T extends Serializable = Serializable>(reason?: Serializable): Future<T>
- Type Parameters
  - T extends Serializable = Serializable
  Parameters
  - Optionalreason: Serializable
    The value to reject the Future with.
  Returns Future<T>
  A Future rejected with reason.

Example

const { methods, exceptions } = createFutureMachine(futureDatabase);
const futures = methods.build();

const future: Future<string> = futures.reject<string>(
  exceptions.createException('MyError')
);

try

try: <Impl extends AnyMethodImpl>(
method: Method<Impl>,
...args: Parameters<Impl>,
) => Future<UnwrapFuture<ReturnType<Impl>>>

Creates a Future that's resolved with method's return value or rejected with the value it throws.

Type Declaration

- <Impl extends AnyMethodImpl>(
  method: Method<Impl>,
  ...args: Parameters<Impl>,
  ): Future<UnwrapFuture<ReturnType<Impl>>>
- Type Parameters
  - Impl extends AnyMethodImpl
  Parameters
  - method: Method<Impl>
    The Method which either resolves or rejects the Future.
  - ...args: Parameters<Impl>
    The arguments to pass to Method.
  Returns Future<UnwrapFuture<ReturnType<Impl>>>
  A Future either resolved with the value returned by method or rejected with the value thrown by method.

Example

const { methods, exceptions } = createFutureMachine(futureDatabase);

const divideMethod = methods.create(
  'divideMethod',
  (numerator: number, denominator: number) => {
    if (denominator === 0) {
      throw exceptions.createException('Divide by zero');
    }
    return numerator / denominator;
  }
);

const futures = methods.build();

const resolvedFuture = futures.try(divideMethod, 10, 5);
const rejectedFuture = futures.try(divideMethod, 7, 0);

race

race: {
    <T extends readonly ValidResult<Serializable>[]>(
        values: T,
    ): Future<UnwrapFuture<T[number]>>;
    <T extends ValidResult<Serializable>>(
        values: Iterable<T>,
    ): Future<UnwrapFuture<T>>;
}

Creates a Future that settles when the first Future in values settles.

Param: values

An iterable of Serializables.

Returns

A Future which settles with the same outcome as the first settled value in values.

The returned Future will either be:

Pending if all values in values are unsettled Futures
Otherwise, settled with the first non-Future Serializable or settled Future.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

const { future: f1, resolve: r1 } = futures.withResolvers<string>();
const { future: f2, resolve: r2 } = futures.withResolvers<number>();

const raceFuture: Future<string | number> = futures.race([f1, f2]);

r2(4312);
r1('Hello');
// raceFuture will be resolved with 4312.

all

all: {
    <T extends readonly ValidResult<Serializable>[]>(
        values: T,
    ): Future<
        List<{ -readonly [I in string | number | symbol]: UnwrapFuture<T[I]> }>,
    >;
    <T extends ValidResult<Serializable>>(
        values: Iterable<T>,
    ): Future<List<UnwrapFuture<T>[]>>;
}

Creates a Future that resolves when all values are resolved, or rejects as soon as any Future in values rejects.

Param: values

An iterable of Serializables.

Returns

A Future which resolves with a List of the results of values or rejects with the first Future in values to reject.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

const { future: f1, resolve: r1 } = futures.withResolvers<string>();
const { future: f2, resolve: r2 } = futures.withResolvers<number>();

const allFuture: Future<List<[string, number]>> = futures.all([f1, f2]);

r2(1234);
r1('Hello');
// allFuture resolves with List<['Hello', 1234]>.

any

any: {
    <T extends readonly ValidResult<Serializable>[]>(
        values: T,
    ): Future<UnwrapFuture<T[number]>>;
    <T extends ValidResult<Serializable>>(
        values: Iterable<T>,
    ): Future<UnwrapFuture<T>>;
}

Creates a Future that resolves with the first successfully resolved value.

Param: values

An iterable of Serializables.

Returns

A Future that resolves when any value in values is resolved or rejects with an AggregateException when all values are rejected.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

const { future: f1, reject: reject1 } = futures.withResolvers<string>();
const { future: f2, resolve: resolve2 } =
  futures.withResolvers<number>();

const anyFuture: Future<string | number> = futures.any([f1, f2]);

reject1('Hello');
resolve2(4312);
// anyFuture is resolved with 4312.

allSettled

allSettled: {
    <T extends readonly ValidResult<Serializable>[]>(
        values: T,
    ): Future<
        List<
            {
                -readonly [I in string
                | number
                | symbol]: FutureSettledResult<UnwrapFuture<T[I]>>
            },
        >,
    >;
    <T extends ValidResult<Serializable>>(
        values: Iterable<T>,
    ): Future<List<FutureSettledResult<UnwrapFuture<T>>[]>>;
}

Creates a Future that resolves when all values are settled.

Param: values

An iterable of Serializables.

Returns

A Future that resolves to a List of FutureSettledResults containing the resolution information of each value in values.

Example

const { methods } = createFutureMachine(futureDatabase);
const futures = methods.build();

const { future: f1, resolve: resolve1 } =
  futures.withResolvers<string>();
const { future: f2, reject: reject2 } = futures.withResolvers<number>();

const allSettledFuture: Future<
  List<[FutureSettledResult<string>, FutureSettledResult<number>]>
> = futures.allSettled([f1, f2]);

reject2(1234);
resolve1('Hello');
// `allSettledFuture` is resolved with a List containing
// FutureSettledResults with these values:
// * [0]: { status: 'fulfilled', value: 'Hello' }
// * [1]: { status: 'rejected', reason: 1234 }

Type Alias FuturesAPI

Index

Properties

Properties

create

Type Declaration

Type Parameters

Parameters

Returns Future<T>

Example

withResolvers

Type Declaration

Type Parameters

Returns Struct< { future: Future<T>; id: FutureId<T>; reject: RejectCallback; resolve: ResolveCallback<T>; },>

Example

resolveFutureById

Type Declaration

Type Parameters

Parameters

Returns void

Example

rejectFutureById

Type Declaration

Type Parameters

Parameters

Returns void

Example

resolve

Type Declaration

Type Parameters

Parameters

Returns Future<T>

Example

reject

Type Declaration

Type Parameters

Parameters

Returns Future<T>

Example

try

Type Declaration

Type Parameters

Parameters

Returns Future<UnwrapFuture<ReturnType<Impl>>>

Example

race

Param: values

Returns

Example

all

Param: values

Returns

Example

any

Param: values

Returns

Example

allSettled

Param: values

Returns

Example

Settings

On This Page

Returns Struct<
{
future: Future<T>;
id: FutureId<T>;
reject: RejectCallback;
resolve: ResolveCallback<T>;
},
>