npm - rest-client-vue - Versions diffs - 1.0.0-a1 - Mend

rest-client-vue 1.0.0-a1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/LICENSE +7 -0
package/README.md +15 -0
package/dist/rest-client-vue.js +1254 -0
package/dist/rest-client-vue.umd.cjs +1 -0
package/dist/src/config.d.ts +12 -0
package/dist/src/errors.d.ts +5 -0
package/dist/src/index.d.ts +11 -0
package/dist/src/queries.d.ts +95 -0
package/dist/src/rest-collection-resources.d.ts +30 -0
package/dist/src/rest-collection.d.ts +308 -0
package/dist/src/rest-resource.d.ts +140 -0
package/dist/src/rest-store-registry.d.ts +9 -0
package/dist/src/stores/rest-collection-store.d.ts +775 -0
package/dist/src/stores/rest-resource-store.d.ts +277 -0
package/dist/tsconfig.tsbuildinfo +1 -0
package/package.json +73 -0

package/dist/rest-client-vue.umd.cjs ADDED Viewed

@@ -0,0 +1 @@

package/dist/src/config.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+export interface RestClientConfigInput {
+    apiBaseUrl?: string;
+    useVueLogger?: boolean;
+}
+export interface RestClientConfig extends RestClientConfigInput {
+    apiBaseUrl: string;
+    useVueLogger: boolean;
+}
+export declare const DEFAULT_REST_CLIENT_CONFIG: {
+    apiBaseUrl: string;
+    useVueLogger: boolean;
+};

package/dist/src/errors.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export declare class ApiClientError extends Error {
+    context: object | undefined;
+    innerError: any;
+    constructor(message: any, context?: object | undefined, innerError?: any);
+}

package/dist/src/index.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import { RestClientConfig, RestClientConfigInput } from './config.js';
+export declare const restClient: {
+    config: RestClientConfig;
+};
+export declare function initRestClient(config: RestClientConfigInput): void;
+export * from './errors.js';
+export { default as useRestCollection } from './rest-collection.js';
+export * from './rest-collection.js';
+export { default as useRestResource } from './rest-resource.js';
+export * from './rest-resource.js';
+export * from './rest-collection-resources.js';

package/dist/src/queries.d.ts ADDED Viewed

@@ -0,0 +1,95 @@
+export type PropertyPathStr = string;
+export type PropertyPathArray = (string | number)[];
+export type PropertyPath = PropertyPathStr | PropertyPathArray;
+export type JsonPathStr = string;
+export type JsonPointerStr = string;
+export type QueryConstant = string | number | boolean | null;
+export type QueryFullTextSearchContext = 'default';
+export type QueryPath = string;
+export interface QueryCoalesceExpression {
+    coalesce: (QueryConstantExpression | QueryPathExpression)[];
+}
+export interface QueryConstantExpression {
+    constant: QueryConstant;
+}
+export interface QueryConstantListExpression {
+    constant: QueryConstant[];
+}
+export interface QueryFullTextExpression {
+    text: QueryFullTextSearchContext;
+}
+export interface QueryFunctionExpression {
+    function: string;
+    parameters: (QueryConstantExpression | QueryPathExpression)[];
+}
+export interface QueryOperatorExpression {
+    operator: string;
+    parameters: (QueryConstantExpression | QueryPathExpression)[];
+}
+export interface QueryPathExpression {
+    path: QueryPath;
+    sqlType?: string;
+}
+export interface QueryRangeExpression {
+    range: [QueryConstantExpression, QueryConstantExpression];
+}
+export type QueryExpression = QueryCoalesceExpression | QueryConstantExpression | QueryConstantListExpression | QueryFullTextExpression | QueryFunctionExpression | QueryOperatorExpression | QueryPathExpression | QueryRangeExpression;
+export interface QueryBetweenClause {
+    operator: 'between';
+    l: QueryConstantExpression | QueryPathExpression;
+    r: QueryRangeExpression;
+}
+export interface QueryComparisonClause {
+    operator?: '=' | '<' | '>' | '<=' | '>=' | '!=' | 'like';
+    l: QueryConstantExpression | QueryPathExpression;
+    r: QueryConstantExpression | QueryPathExpression;
+}
+export interface QueryInClause {
+    operator: 'in';
+    l: QueryConstantExpression | QueryPathExpression;
+    r: QueryConstantListExpression;
+}
+export interface QueryFullTextSearchClause {
+    operator: 'contains';
+    l: QueryFullTextExpression;
+    r: QueryConstantExpression | QueryPathExpression;
+}
+export type QuerySimpleClause = QueryBetweenClause | QueryComparisonClause | QueryInClause | QueryFullTextSearchClause;
+export interface QueryAndClause {
+    and: QueryClause[];
+}
+export interface QueryOrClause {
+    or: QueryClause[];
+}
+export interface QueryNotClause {
+    not: QueryClause;
+}
+export type QueryClause = QuerySimpleClause | QueryAndClause | QueryOrClause | QueryNotClause | true | false;
+export type QueryOrderProperty = QueryPathExpression;
+export type QueryOrderDirection = 'asc' | 'desc' | 'ASC' | 'DESC';
+export type QueryOrderElement = QueryOrderProperty | [QueryOrderProperty, QueryOrderDirection];
+export type QueryOrder = QueryOrderElement[];
+export interface SqlExpression {
+    expression: string;
+    parameterValues: any[];
+}
+export interface SqlClause {
+    sqlClause: string | null;
+    parameterValues: any[];
+}
+export declare function queryExpressionIsCoalesce(expression: QueryExpression): expression is QueryCoalesceExpression;
+export declare function queryExpressionIsConstant(expression: QueryExpression): expression is QueryConstantExpression;
+export declare function queryExpressionIsConstantList(expression: QueryExpression): expression is QueryConstantListExpression;
+export declare function queryExpressionIsFunction(expression: QueryExpression): expression is QueryFunctionExpression;
+export declare function queryExpressionIsOperator(expression: QueryExpression): expression is QueryOperatorExpression;
+export declare function queryExpressionIsFullText(expression: QueryExpression): expression is QueryFullTextExpression;
+export declare function queryExpressionIsPath(expression: QueryExpression): expression is QueryPathExpression;
+export declare function queryExpressionIsRange(expression: QueryExpression): expression is QueryRangeExpression;
+export declare function queryClauseIsBetween(clause: QueryClause): clause is QueryBetweenClause;
+export declare function queryClauseIsComparisonn(clause: QueryClause): clause is QueryComparisonClause;
+export declare function queryClauseIsIn(clause: QueryClause): clause is QueryInClause;
+export declare function queryClauseIsFullTextSearch(clause: QueryClause): clause is QueryFullTextSearchClause;
+export declare function queryClauseIsSimple(clause: QueryClause): clause is QuerySimpleClause;
+export declare function queryClauseIsAnd(clause: QueryClause): clause is QueryAndClause;
+export declare function queryClauseIsOr(clause: QueryClause): clause is QueryOrClause;
+export declare function queryClauseIsNot(clause: QueryClause): clause is QueryNotClause;

package/dist/src/rest-collection-resources.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+/** A REST resource type, i.e. a description of items in one REST collection. */
+export interface ResourceType {
+    /** The REST collection name, which is used in constructing its path. */
+    collectionName: string;
+    /** The property path (in dot notation) for each resource's primary key. */
+    idProperty?: string;
+    /** Subcollections of each resource. */
+    subcollections?: ResourceSubcollection[];
+    /** Custom data attached by the client. */
+    custom?: {
+        [key: string]: any;
+    };
+}
+/** A subcollection belonging to each resource of a certain type. */
+export interface ResourceSubcollection {
+    /** The subcollection name, which is used in constructing its path. */
+    name: string;
+    /** The resource type of subcollection members. */
+    type: ResourceType;
+}
+/**
+ * A primary key value identifying a resource within its collection.
+ *
+ * Every resource must have an ID, which is currently assumed to be stored in its _id property.
+ */
+export type ResourceId<T = string | number> = T;
+/** A resource from a REST collection. */
+export type Resource = object;
+export type RestCollectionQuery = any;
+export type RestCollectionOrder = any;

package/dist/src/rest-collection.d.ts ADDED Viewed

@@ -0,0 +1,308 @@
+import { Ref } from 'vue';
+import { Resource, ResourceId, ResourceType } from './rest-collection-resources.js';
+import { RestCollectionStatus } from './stores/rest-collection-store.js';
+/** Options that define a REST collection. */
+export interface RestCollectionOptions {
+    /**
+     * The REST collection's unique identifier, which will be used as the ID of its Pinia store.
+     *
+     * This is normally generated, and the generated ID may be accessed using the collection's {@link collectionId}
+     * property.
+     *
+     * There are two circumstances where you may want to specify a collection ID:
+     * 1. You have already created a collection and want to give another Vue component access to it. In this case, pass
+     *   the value of the collection's {@link collectionId} property in the options to the second component's
+     *   {@link useRestCollection} call.
+     * 2. You want to assign a canonical ID to the collection, so that components can call {@link useRestCollection} to
+     *   create it or to access it if it already exists. In this case, you can assign the ID manually, but you must ensure
+     *   that it does not conflict with any other Pinia store IDs used in the Vue application.
+     *
+     * - If not specified, an unique ID will be generated.
+     * - If specified, the REST collection will check whether a Pinia store with this ID already exists.
+     *   - If one exists, that store will be used, and other options will be ignored. This is a way to have multiple
+     *     components' {@link RestCollection}s share a single data store.
+     *   - If a Pinia store does not exist, then when creating a new collection, the ID will be used instead of generating
+     *     a new unique ID.
+     */
+    collectionId?: string;
+    draftBatchId?: string;
+    enabled?: boolean;
+    /** The resource type. */
+    resourceType?: Ref<ResourceType | undefined> | ResourceType;
+    /** Options that govern the behavior of the REST collections's data store module. */
+    options?: RestCollectionStoreOptionsInput;
+}
+export interface ConcreteRestCollectionStoreOptionsInput {
+    detail?: {
+        allowMultiple?: boolean;
+        autoEdit?: boolean;
+        autoFromMultipleSelection?: boolean;
+        autoFromSingleInsertion?: boolean;
+        autoFromSingleSelection?: boolean;
+        constrainToSelection?: boolean;
+    };
+    filter?: {
+        namedFilter?: string | null;
+        query?: any | null;
+        resourceIds?: ResourceId[] | null;
+    };
+    limit?: number | null;
+    limitTransientDataToLocalCollection?: boolean;
+    loadId?: string | null;
+    loading?: {
+        firstPageSize?: number | null;
+        pageSize?: number | null;
+    };
+    order?: [any, string][];
+    referencePathsToExpand?: string[];
+    restCollectionUrl?: string | null;
+}
+export interface RestCollectionStoreOptionsInput {
+    detail?: {
+        allowMultiple?: boolean;
+        autoEdit?: boolean;
+        autoFromMultipleSelection?: boolean;
+        autoFromSingleInsertion?: boolean;
+        autoFromSingleSelection?: boolean;
+        constrainToSelection?: boolean;
+    };
+    filter?: {
+        namedFilter?: string | null;
+        query?: any | null | ((resourceType: ResourceType) => any | null);
+        resourceIds?: ResourceId[] | null;
+    };
+    limit?: number | null;
+    limitTransientDataToLocalCollection?: boolean;
+    loadId?: string | null;
+    loading?: {
+        firstPageSize?: number | null;
+        pageSize?: number | null;
+    };
+    order?: [any, string][];
+    referencePathsToExpand?: string[] | ((resourceType: ResourceType) => string[]);
+    restCollectionUrl?: string | null;
+}
+export interface LoadResourcesParams {
+    firstPageSize?: number;
+    pageSize?: number;
+}
+export interface SelectResourcesOptions {
+    addToSelection?: boolean;
+    edit?: boolean;
+}
+/** Parameters to {@link RestCollection.setTransientDataForResources} */
+export interface SetTransientDataParams {
+    /** Transient data keyed by resource ID. */
+    transientData: {
+        /** Transient data for one resource. */
+        [resourceId: ResourceId]: object;
+    };
+    /**
+     * Flag indicating whether new transient data should replace existing transient data for each resource or be merged
+     * with it.
+     */
+    merge?: boolean;
+}
+export type RestCollectionStoreReadyCallback = (() => void) | (() => Promise<void>);
+/**
+ * A REST collection.
+ *
+ * This represents a collection of resources (records) fetched from a REST API. Most commonly, it represents all the
+ * resources from one collection endpoint of the REST API; but filters can be added when using a REST API that supports
+ * them.
+ */
+export interface RestCollection {
+    /**
+     * The REST collection's unique ID, which is used as the ID of its Pinia store.
+     *
+     * If you want to share the store with another component, you can pass this ID when creating the second component's
+     * {@link RestCollection}.
+     */
+    collectionId: Ref<string | null>;
+    /** The draft batch ID, if one was passed in {@link RestCollectionOptions.draftBatchId}. */
+    draftBatchId: Ref<string | undefined>;
+    /** A flag indicating whether accessing the local collection will fetch data from the remote collection. */
+    enabled: Ref<boolean>;
+    /**
+     * The resource type for this collection.
+     *
+     * To allow for asynchronous loading of resource types, this may be undefined.
+     */
+    resourceType: Ref<ResourceType | undefined>;
+    /** A status indicating whether resources have been loaded yet from the REST API. */
+    status: Ref<RestCollectionStatus>;
+    batchSaveAttempted: Ref<boolean>;
+    /**
+     * An array of resources that have failed validation. The client must manage this list by calling
+     * {@link setInvalidResourceIds}
+     **/
+    invalidResources: Ref<Resource[]>;
+    /** The array of resources that have been loaded from the REST API into the local collection. */
+    resources: Ref<Resource[]>;
+    /** Transient data that a client has associated with the resources via {@link setTransientDataForResources}. */
+    transientData: Ref<any[]>;
+    /** Resources in the current detail view, a sublist of {@link resources}. */
+    detailSelection: Ref<Resource[]>;
+    /** A flag indicating whether the detail selection is currently being edited or only displayed. */
+    editingDetailSelection: Ref<boolean>;
+    /** The current selection, a sublist of {@link resources}. */
+    selection: Ref<Resource[]>;
+    /**
+     * Apply new configuration options.
+     *
+     * The result is much like creating a new RestCollection, except that the client can continue using the same
+     * properties.
+     *
+     * @param options New options to apply.
+     */
+    reconfigureCollection: (options: RestCollectionOptions) => void;
+    setEditingDetailSelection: (editingDetailSelection: boolean) => void;
+    setEnabled: (enabled: boolean) => void;
+    /**
+     * Set filter consisting of a list of resource IDs to fetch from the collection.
+     *
+     * This relies on a filtering request format that is not a part of the informal REST standard, so use of this method
+     * should be limited to APIs that adhere to our extended REST standard, i.e. TODO.
+     *
+     * If the previous state was anything other than NotLoaded, the collection will be immediately refreshed as if the
+     * client had called {@link loadResources}. Calls made with await will return once the first page of results have
+     * loaded or failed (just as when you call {@link loadResources} with await).
+     *
+     * @param filterResourceIds The list if resource IDs to fetch from the REST collection.
+     * @return A promise that resolves when the first page of resources is loaded, or immediately if the collection does
+     *   not need to be reloaded.
+     */
+    setFilterResourceIds: (filterResourceIds: ResourceId[]) => Promise<void>;
+    /**
+     * Apply a new filter query.
+     *
+     * Since filter queries are not a part of the informal REST standard, use of this method should be limited to APIs
+     * that adhere to our extended REST standard, i.e. TODO.
+     *
+     * If the previous state was anything other than NotLoaded, the collection will be immediately refreshed as if the
+     * client had called {@link loadResources}. Calls made with await will return once the first page of results have
+     * loaded or failed (just as when you call {@link loadResources} with await).
+     *
+     * @param query The query for filtering the REST collection. This will be sent to the REST API as a query parameter.
+     */
+    setQuery: (query: any | null | ((resourceType: ResourceType) => any | null)) => Promise<void>;
+    /**
+     * Ensure that a Pinia store has been created for this REST collection.
+     *
+     * This does not normally need to be called, because it will happen automatically when the {@link RestCollection} is
+     * created and when {@link collectionId}, {@link resourceType}, or options change.
+     *
+     * @return true if the store has been created or replaced. (Note that false does not indicate that the store does not
+     *   exist.)
+     */
+    ensureStore: () => boolean;
+    setBatchSaveAttempted: (batchSaveAttempted: boolean) => void;
+    /** Return the {@link RestCollection} to the NotLoaded state, where no resources have been fetched yet. */
+    clear: () => void;
+    /**
+     * Fetch the collection from the REST API, if this has not happened yet.
+     *
+     * A client that observes changes to the reactive property {@link resources} should never need to call this.
+     *
+     * @return A promise that resolves when the first page of results have loaded or loading has failed.
+     */
+    ensureCollectionLoaded: () => Promise<void>;
+    /**
+     * Fetch the collection from the REST API.
+     *
+     * A client that observes changes to the reactive property {@link resources} should never need to call this.
+     *
+     * If you call this with await, the call will return once the first page of results have loaded or failed.
+     *
+     * @param payload Parameters governing page size.
+     * @return A promise that resolves when the first page of results have loaded or loading has failed.
+     */
+    loadResources: (params: LoadResourcesParams) => Promise<void>;
+    /**
+     * Start editing a new resource, whose properties are all undefined except for any passed in the parameter.
+     *
+     * @param resourceDefaults An object containing initial property values for the new resource.
+     */
+    addResource: (resourceDefaults?: Resource) => void;
+    checkForDeletedResource: (resourceId: ResourceId) => Promise<boolean>;
+    recordDeletion: (resourceId: ResourceId) => void;
+    recordInsertion: (resource: Resource, { insertAtBeginning, transientData }?: {
+        insertAtBeginning?: boolean;
+        transientData?: any;
+    }) => void;
+    recordUpdate: (resource: Resource) => void;
+    /**
+     * Refresh one resource by fetching it again from the REST API.
+     *
+     * If you call this with await, it will return once the API call has completed.
+     *
+     * @param resourceId The ID of the resource to refresh.
+     */
+    refreshResource: (resourceId: ResourceId) => Promise<Resource | null | undefined>;
+    /**
+     * Delete one resource.
+     *
+     * If you call this with await, it will return once the API call has completed.
+     *
+     * @param resourceId The ID of the resource to delete.
+     */
+    deleteResource: (resourceId: ResourceId) => Promise<void>;
+    /**
+     * Save one resource (new or updated).
+     *
+     * The resource will be updated if it has a resource ID, created if not.
+     *
+     * If you call this with await, it will return once the API call has completed, and if the APi call succeeded, it will
+     * return the newly saved item.
+     *
+     * @param resource The resource to create or update.
+     */
+    saveResource: (resource: Resource) => Promise<Resource | null | undefined>;
+    /**
+     * Save multiple resources (new or updated).
+     *
+     * Each resource will be updated if it has a resource ID, created if not.
+     *
+     * If you call this with await, it will return once the API call has completed, and if the APi call succeeded, it will
+     * return the newly saved item.
+     *
+     * @param params TODO
+     */
+    saveResources: (resources: Resource[]) => Promise<Resource[] | undefined>;
+    /**
+     * Record which resources have failed validation.
+     *
+     * The REST collection does not interact directly with any validation code. The ability to record which resources
+     * failed validation is purely a convenience for clients that want to store this information. To store more complex
+     * information about validation, consider setting transient data associated with resources.
+     *
+     * @param resourceIds The IDs of all resources that failed validation.
+     */
+    setInvalidResourceIds: (resourceIds: ResourceId[]) => void;
+    /** Clear all transient data associated with resources. */
+    clearTransientData: () => void;
+    /**
+     * Associate transient data with REST resources that have been fetched from the API.
+     *
+     * @param params Parameters, including transient data for zero or more resources, keyed by resource ID.
+     */
+    setTransientDataForResources: (params: SetTransientDataParams) => void;
+    clearSelection: () => void;
+    deselectResources: (resourceIds: ResourceId[]) => void;
+    selectResources: (resourceIds: ResourceId[], options?: SelectResourcesOptions) => void;
+    hideDetail: () => void;
+    deregisterEditor: (editor: any) => void;
+    registerEditor: (editor: any) => void;
+    deregisterListNavigator: ({ name, listNavigator }: {
+        name: string;
+        listNavigator: any;
+    }) => void;
+    registerListNavigator: ({ name, listNavigator }: {
+        name: string;
+        listNavigator: any;
+    }) => void;
+    onItemsStoreReady: (callback: RestCollectionStoreReadyCallback) => void;
+}
+declare const _default: (params?: RestCollectionOptions) => RestCollection;
+export default _default;
+export declare const clearAllRestCollections: () => void;