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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xy-planning-network/trees",
-  "version": "0.6.1",
+  "version": "0.6.2-rc-2",
   "description": "",
   "license": "MIT",
   "repository": "github:xy-planning-network/trees",
@@ -28,7 +28,9 @@
     "lint": "eslint --ext .js,.ts,.vue src",
     "lint:fix": "eslint --fix --ext .js,.ts,.vue src dev && prettier -w -u src dev",
     "preview": "vite preview --config vite.docs.config.ts",
-    "typecheck": "vue-tsc -p src --noEmit"
+    "typecheck": "npm run typecheck:src && npm run typecheck:docs",
+    "typecheck:src": "vue-tsc -p src --noEmit",
+    "typecheck:docs": "vue-tsc -p dev --noEmit"
   },
   "devDependencies": {
     "@tailwindcss/forms": "^0.5.3",

package/src/lib-components/lists/Table.vue

@@ -1,5 +1,4 @@
 <script setup lang="ts">
-import { AxiosResponse } from "axios"
 import {
   ComponentPublicInstance,
   computed,
@@ -12,6 +11,7 @@ import Paginator from "../navigation/Paginator.vue"
 import BaseAPI from "../../api/base"
 import * as TableTypes from "@/composables/table"
 import { useAppFlasher } from "@/composables/useFlashes"
+import { TrailsResponsePaged } from "@/api/client"
 
 const props = withDefaults(
   defineProps<{
@@ -96,8 +96,12 @@ const loadAndRender = (): void => {
     q: query.value,
   }
 
-  BaseAPI.get(props.tableData.url, { skipLoader: !props.loader }, params).then(
-    (success: AxiosResponse) => {
+  BaseAPI.get<TrailsResponsePaged<unknown>>(
+    props.tableData.url,
+    { skipLoader: !props.loader },
+    params
+  ).then(
+    (success) => {
       pagination.value = {
         page: success.data.page,
         perPage: success.data.perPage,

package/types/api/base.d.ts

@@ -1,24 +1,5 @@
 import { AxiosRequestConfig } from "axios";
-export declare type RequestMethod = "GET" | "get" | "PUT" | "put" | "POST" | "post" | "DELETE" | "delete";
-export interface RequestOptions {
-    /**
-     * returns the nested data key inside the AxiosResponse data when true
-     */
-    dataIntercept?: boolean;
-    /**
-     * 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): Promise<T>;
-    get<T_1 = any>(path: string, opts: RequestOptions, params?: Record<string, unknown> | undefined): Promise<T_1>;
-    delete<T_2 = any>(path: string, opts: RequestOptions): Promise<T_2>;
-    post<T_3 = any>(path: string, data: Record<string, unknown> | FormData, opts: RequestOptions): Promise<T_3>;
-    put<T_4 = any>(path: string, data: Record<string, unknown> | FormData, opts: RequestOptions): Promise<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/api/url.d.ts

@@ -0,0 +1 @@
+export declare function getBaseUrl(): string;

package/types/composables/useBaseAPI.d.ts

@@ -1,6 +1,5 @@
-import { AxiosError } from "axios";
 import { Ref, ShallowRef } from "vue";
-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
@@ -25,7 +24,7 @@ export interface UseBaseAPI<T> {
     /**
      * Any errors that may have occurred
      */
-    error: ShallowRef<Error | AxiosError<T> | undefined>;
+    error: ShallowRef<Error | HttpError<T> | undefined>;
     /**
      * Indicates if the request has finished
      */
@@ -51,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) => Promise<T>;
+    execute: (data?: RequestPayload, opts?: RequestOptions) => HttpPromise<T>;
 }
 /**
  * useBaseAPI is a composable wrapper of BaseAPI
@@ -61,16 +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>;
-    error: ShallowRef<Error | AxiosError<T, any> | undefined>;
-    isFinished: Ref<boolean>;
-    isLoading: Ref<boolean>;
-    isAborted: Ref<boolean>;
-    hasFetched: Ref<boolean>;
-    abort: () => void;
-    execute: (data?: Record<string, unknown> | FormData, opts?: RequestOptions) => Promise<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
@@ -87,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/composables/usePopper.d.ts

@@ -0,0 +1,19 @@
+import { VNode } from "vue";
+import { Options, Placement } from "@popperjs/core";
+export declare type PopperPosition = Placement;
+export declare const offsetModifier: (skidding: number, distance: number) => {
+    options: {
+        offset: () => number[];
+    };
+    name: "offset";
+    enabled: boolean;
+    phase: import("@popperjs/core").ModifierPhases;
+    requires?: string[] | undefined;
+    requiresIfExists?: string[] | undefined;
+    fn: (arg0: import("@popperjs/core").ModifierArguments<import("@popperjs/core/lib/modifiers/offset").Options>) => void | import("@popperjs/core").State;
+    effect?: ((arg0: import("@popperjs/core").ModifierArguments<import("@popperjs/core/lib/modifiers/offset").Options>) => void | (() => void)) | undefined;
+    data?: import("@popperjs/core").Obj | undefined;
+};
+export declare function usePopper(opts: Partial<Options>): import("vue").Ref<VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | HTMLElement | undefined>[];

package/types/entry.d.ts

@@ -1,9 +1,9 @@
 import { Plugin } from "vue";
 import BaseAPI from "./api/base";
-import type { RequestOptions } from "./api/base";
+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 { RequestOptions };
+export type { HttpPromise, HttpError, RequestOptions, TrailsResponse, TrailsResponsePaged, };

package/types/types/lists.d.ts

@@ -0,0 +1,12 @@
+export interface Pagination {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+}
+export interface PaginationItems<T = any> {
+    items: T[];
+}
+export interface PaginationData<T = any> {
+    data: Pagination & PaginationItems<T>;
+}