[2.x] - Return visit/request promises

[VicGUTT]

Hi there @joetannenbaum 👋

Was looking at the on-going async-requests branch and though I'd chime in with some questions/feedback if you'd indulge me.

Prelude

Prior to #208 Inertia allowed for visit request promises to be consumed by end users:

let loading = true;
let succeeded = false;
let failed = false;

const pendingRequest = router
    .get(url, data, options)
    .then(() => {
        succeeded = true;
    })
    .catch(() => {
        failed = true;
    })
    .finally(() => {
        loading = false;
    });

This allowed straightforward loading/success/failure indication in a standard JavaScript native way and allowed for easy Promise consumption wherever needed.

Currently, when loading/success/failure indications are needed, we can only make use of the provided Inertia hooks:

let loading = false;
let succeeded = false;
let failed = false;

router.get(url, data, {
    onBefore(visit) {
        loading = true;
    },
    onSuccess(page) {
        succeeded = true;
    },
    onError(errors) {
        failed = true;
    },
    onFinishvisit() {
        loading = false;
    },
});

And when a Promise is needed as a result of the request being made, a Promise wrapping the request needs to be constructed manually:

let loading = false;
let succeeded = false;
let failed = false;

const pendingRequest = new Promise((resolve, reject) => {
    router.get(url, data, {
        onBefore(visit) {
            loading = true;
        },
        onSuccess(page) {
            succeeded = true;

            resolve(page);
        },
        onError(errors) {
            failed = true;

            reject(errors);
        },
        onFinishvisit() {
            loading = false;
        },
    });
});

As you can probably tell this approach is very boilerplate-y and quickly gets cumbersome. But also, end users only have access to Inertia specific data in those hooks, nothing about the Axios response which can be useful in many situations.

Suggestion

I would like to propose the comeback of Promises as a result of all Inertia requests and, where possible, provide access to the underlaying Axios/Inertia objects.

As of now, this would include (I think it's an exhaustive list) the following elements:

• requestStream

export type PendingResponse = {
  request: InertiaRequest;
  response: InertiaResponse;
}

export class RequestStream {
  //

+  public async send(request: Request): Promise<PendingResponse> {
    this.requests.push(request)

+   return request.send().then((response) => {
      this.requests = this.requests.filter((r) => r !== request)
+
+     return { request, response }
      })
    }
}

• router

export class Router {
  //

+  public async get(/*...*/): Promise<PendingResponse> {
    return this.visit(/*...*/)
  }

+  public async post(/*...*/): Promise<PendingResponse> {
    return this.visit(/*...*/)
  }

+  public async put(/*...*/): Promise<PendingResponse> {
    return this.visit(/*...*/)
  }

+  public async patch(/*...*/): Promise<PendingResponse> {
    return this.visit(/*...*/)
  }

+  public async delete(/*...*/): Promise<PendingResponse> {
    return this.visit(/*...*/)
  }

+  public async reload(/*...*/): Promise<PendingResponse> {
    return this.visit(/*...*/)
  }

+  public async visit(/*...*/): Promise<PendingResponse> {
    //

    return requestStream.send(request)
  }

+  public async replace(/*...*/): Promise<PendingResponse> {
    //

    return this.visit(/*...*/)
  }
}

• response

import { AxiosResponse } from 'axios'
import { fireErrorEvent, fireInvalidEvent, fireSuccessEvent } from './events'
import { History } from './history'
import modal from './modal'
import { page as currentPage } from './page'
import { poll } from './poll'
import { RequestParams } from './requestParams'
import { SessionStorage } from './sessionStorage'
import { ErrorBag, Errors, LocationVisit, Page } from './types'
import { hrefToUrl, isSameUrlWithoutHash, setHashIfSameUrl } from './url'

export class Response {
  //

  public async handle() {
    //

+    return this.requestParams.params.onSuccess(currentPage.get())
  }
}

But why? What problems/usecases would be solved?

Quality of life elements:

• Access to the request response as a Promise
• Less boilerplate
• Less mental overhead

Usecases

Any scenario where consuming a Promise and/or the Request/Response is needed.

A very contrived example:

router.post(url, data, options)
  .then(({ request, response }) => {
    if (request.redirected) {
      return;
    }

    selectItem(response.response.data.props.item.id)
    updateUrlHash(response.response.data.props.item.id)

    notify({ type: 'succes', message: 'Yay!' })
  })
  .catch(() => {
    notify({ type: 'error', message: 'Oops...' })
  });

Ps.: All code provided should only serve as examples and starting points of course :)

[artygrand]

I vote for this

Another use case

showModal(PromptDialog, {title: 'Why?'})
    .then(v => router.post(route('item.destroy', id), {v}))
    .then(hideModal);

Simple and straightforward, I hope for the future