@xy-planning-network/trees 0.6.2-rc-1 → 0.6.2-rc-2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xy-planning-network/trees",
-  "version": "0.6.2-rc-1",
+  "version": "0.6.2-rc-2",
   "description": "",
   "license": "MIT",
   "repository": "github:xy-planning-network/trees",

package/types/api/base.d.ts

@@ -1,36 +1,5 @@
-import { Pagination } from "../composables/nav";
 import { AxiosRequestConfig } from "axios";
-export interface Paginated<T> extends Pagination {
-    items: T[];
-}
-export interface TreesResponse<T = any> {
-    /**
-     * response data as T
-     */
-    data: T;
-    /**
-     * http status code
-     */
-    status: number;
-}
-export interface TreesPromise<T = any> extends Promise<TreesResponse<T>> {
-}
-export declare type RequestMethod = "GET" | "get" | "PUT" | "put" | "POST" | "post" | "DELETE" | "delete";
-export interface RequestOptions {
-    /**
-     * disables the full screen loading interface during the request when true
-     */
-    skipLoader?: boolean;
-    /**
-     * artificially delay's the request by the time specified when set
-     */
-    withDelay?: number;
-}
-declare const BaseAPI: {
-    makeRequest<T = any>(config: AxiosRequestConfig, opts: RequestOptions): TreesPromise<T>;
-    get<T_1 = any>(path: string, opts: RequestOptions, params?: Record<string, unknown> | undefined): TreesPromise<T_1>;
-    delete<T_2 = any>(path: string, opts: RequestOptions): TreesPromise<T_2>;
-    post<T_3 = any>(path: string, data: Record<string, unknown> | FormData, opts: RequestOptions): TreesPromise<T_3>;
-    put<T_4 = any>(path: string, data: Record<string, unknown> | FormData, opts: RequestOptions): TreesPromise<T_4>;
-};
+import { HttpClient, HttpPromise, RequestOptions } from "./client";
+export declare const httpRequest: <T = any>(config: AxiosRequestConfig, opts: RequestOptions) => HttpPromise<T>;
+declare const BaseAPI: HttpClient;
 export default BaseAPI;

package/types/api/client.d.ts

@@ -0,0 +1,163 @@
+/**
+ * RequestMethod
+ * The HTTP request methods that our http client supports.
+ */
+export declare type RequestMethod = "GET" | "get" | "PATCH" | "patch" | "PUT" | "put" | "POST" | "post" | "DELETE" | "delete";
+/**
+ * RequestOptions
+ * The set of options available for any http client request.
+ */
+export interface RequestOptions {
+    /**
+     * Disable the full screen loading interface during the request when true.
+     */
+    skipLoader?: boolean;
+    /**
+     * Artificially delay a request by the time specified when set.
+     */
+    withDelay?: number;
+}
+export declare const HTTP_ERROR = "HttpError";
+export declare const HTTP_CANCELLED_ERROR = "HttpCanceledError";
+/**
+ * HttpError
+ * An http client error when the request is rejected.
+ */
+export declare class HttpError<T = unknown> extends Error {
+    /**
+     * The http response status code.
+     */
+    status: number;
+    /**
+     * The http response body.
+     */
+    response?: T;
+    constructor(message?: string, status?: number, response?: T, name?: string);
+}
+/**
+ * HttpPromise
+ * The successfully resolved interface of an http client request.
+ */
+export interface HttpPromise<T = any> extends Promise<T> {
+}
+/**
+ * TrailsResponse
+ * A convenience interface to represent the shape of a Trails delivered API response.
+ *
+ * Example Usage:
+ * interface User {
+ *     id: number
+ *     email: string
+ * }
+ *
+ * BaseAPI.get<TrailsResponse<User>>(`/user/${id}`)
+ *     .then(result => {
+ *         const id = result.data.id
+ *         const email = result.data.email
+ *         const user = { ...result.data }
+ *     })
+ */
+export interface TrailsResponse<T = any> {
+    data: T;
+}
+/**
+ * TrailsResponsePaged
+ * A convenience interface to represent the shape of a paginated Trails delivered API response.
+ *
+ * Example Usage:
+ * interface User {
+ *     id: number
+ *     email: string
+ * }
+ *
+ * BaseAPI.get<TrailsResponsePaged<User>>(`/users`)
+ *     .then(result => {
+ *         const currentPage = result.data.page
+ *         const users = { ...result.data.items }
+ *
+ *         result.data.items.forEach(u => {
+ *             console.log(u.id)
+ *         })
+ *     })
+ */
+export interface TrailsResponsePaged<T = any> {
+    data: {
+        items: T[];
+        page: number;
+        perPage: number;
+        totalItems: number;
+        totalPages: number;
+    };
+}
+/**
+ * QueryParams
+ * Http GET request query params.
+ */
+export declare type QueryParams = Record<string, any>;
+/**
+ * RequestPayload
+ * Http POST and PUT payloads.
+ */
+export declare type RequestPayload = Record<string, any> | FormData;
+/**
+ * HttpClient
+ * The http client interface the BaseAPI implements.
+ */
+export interface HttpClient {
+    /**
+     * The method to make an http GET request.
+     * @param path string
+     * @param opts RequestOptions
+     * @param params QueryParams
+     * @returns HttpPromise<T>
+     */
+    get<T>(path: string, opts?: RequestOptions, params?: QueryParams): HttpPromise<T>;
+    /**
+     * The method to make an http DELETE request.
+     * @param path string
+     * @param opts RequestOptions
+     * @returns HttpPromise<T>
+     */
+    delete<T>(path: string, opts?: RequestOptions): HttpPromise<T>;
+    /**
+     * A convenience method for checking if a variable in a failed request has an http status code.
+     * This is most useful for checking for specific http status codes in error callbacks.
+     * @param err unknown
+     * @param codes number | number[]
+     * @returns boolean
+     */
+    hasErrStatus(err: unknown, codes: number | number[]): boolean;
+    /**
+     * A type guard for checking if a variable is in the shape of a HttpError
+     * @param err unknown
+     * @returns payload is HttpError
+     */
+    isHttpError(err: unknown): err is HttpError;
+    /**
+     * A convenience method for checking if a variable is a cancelled http request error.
+     * @param err unknown
+     * @returns boolean
+     */
+    isHttpCancel(err: unknown): boolean;
+    /**
+     * The method to make an http PATCH request.
+     * @param path string
+     * @param data RequestPayload
+     * @param opts RequestOptions
+     */
+    patch<T>(path: string, data?: RequestPayload, opts?: RequestOptions): HttpPromise<T>;
+    /**
+     * The method to make an http POST request.
+     * @param path string
+     * @param data RequestPayload
+     * @param opts RequestOptions
+     */
+    post<T>(path: string, data?: RequestPayload, opts?: RequestOptions): HttpPromise<T>;
+    /**
+     * The method to make an http PUT request.
+     * @param path string
+     * @param data RequestPayload
+     * @param opts RequestOptions
+     */
+    put<T>(path: string, data?: RequestPayload, opts?: RequestOptions): HttpPromise<T>;
+}

package/types/composables/useBaseAPI.d.ts

@@ -1,7 +1,5 @@
-import { AxiosError } from "axios";
 import { Ref, ShallowRef } from "vue";
-import { TreesPromise } from "../api/base";
-import type { RequestMethod, RequestOptions } from "../api/base";
+import type { HttpPromise, HttpError, RequestMethod, RequestOptions, RequestPayload } from "../api/client";
 /**
  * UseBaseAPIOptions extends Trees/RequestOptions
  * these options are used only in the instantiation
@@ -20,17 +18,13 @@ export interface UseBaseAPIOptions extends RequestOptions {
  */
 export interface UseBaseAPI<T> {
     /**
-     * Promise response data
+     * Axios response data
      */
     result: Ref<T | undefined>;
     /**
-     * Promise response http status code
+     * Any errors that may have occurred
      */
-    status: Ref<number | undefined>;
-    /**
-     * Any errors or rejections that may have occurred
-     */
-    error: ShallowRef<AxiosError | Error | undefined>;
+    error: ShallowRef<Error | HttpError<T> | undefined>;
     /**
      * Indicates if the request has finished
      */
@@ -56,7 +50,7 @@ export interface UseBaseAPI<T> {
      * Manually call the axios request
      * can be used multiple times
      */
-    execute: (data?: Record<string, unknown> | FormData, opts?: RequestOptions) => TreesPromise<T>;
+    execute: (data?: RequestPayload, opts?: RequestOptions) => HttpPromise<T>;
 }
 /**
  * useBaseAPI is a composable wrapper of BaseAPI
@@ -66,17 +60,7 @@ export interface UseBaseAPI<T> {
  * @param initConfig {AxiosRequestConfig}
  * @returns {UseBaseAPI<T>}
  */
-export default function useBaseAPI<T = any>(path: string, method?: RequestMethod, initOpts?: UseBaseAPIOptions): {
-    result: Ref<T | undefined>;
-    status: Ref<number | undefined>;
-    error: ShallowRef<AxiosError<unknown, any> | Error | undefined>;
-    isFinished: Ref<boolean>;
-    isLoading: Ref<boolean>;
-    isAborted: Ref<boolean>;
-    hasFetched: Ref<boolean>;
-    abort: () => void;
-    execute: (data?: Record<string, unknown> | FormData, opts?: RequestOptions) => TreesPromise<T>;
-};
+export default function useBaseAPI<T = any>(path: string, method?: RequestMethod, initOpts?: UseBaseAPIOptions): UseBaseAPI<T>;
 /**
  * useBaseAPIGet is a convenience function for useBaseAPI
  * @param path {string} the api path or full url for the
@@ -93,6 +77,14 @@ export declare function useBaseAPIGet<T = any>(url: string, opts?: UseBaseAPIOpt
  * @returns {UseBaseAPI<T>}
  */
 export declare function useBaseAPIDelete<T = any>(url: string, opts?: UseBaseAPIOptions): UseBaseAPI<T>;
+/**
+ * useBaseAPIPatch is a convenience function for useBaseAPI
+ * @param path {string} the api path or full url for the
+ * @param initOpts {UseBaseAPIOptions}
+ * @param initConfig {AxiosRequestConfig}
+ * @returns {UseBaseAPI<T>}
+ */
+export declare function useBaseAPIPatch<T = any>(url: string, opts?: UseBaseAPIOptions): UseBaseAPI<T>;
 /**
  * useBaseAPIPost is a convenience function for useBaseAPI
  * @param path {string} the api path or full url for the

package/types/entry.d.ts

@@ -1,10 +1,9 @@
 import { Plugin } from "vue";
 import BaseAPI from "./api/base";
-import type { Paginated, RequestOptions, TreesPromise, TreesResponse } from "./api/base";
-import type { Pagination } from "./composables/nav";
+import type { HttpPromise, HttpError, RequestOptions, TrailsResponse, TrailsResponsePaged } from "./api/client";
 declare const install: Exclude<Plugin["install"], undefined>;
 export default install;
 export * from "./composables/index";
 export * from "./lib-components/index";
 export { BaseAPI };
-export type { Paginated, Pagination, RequestOptions, TreesPromise, TreesResponse, };
+export type { HttpPromise, HttpError, RequestOptions, TrailsResponse, TrailsResponsePaged, };