import { SelectResourcesOptions, SetTransientDataParams } from '../rest-collection.js'; import { Resource, ResourceId } from '../rest-collection-resources.js'; import { QueryClause, QueryOrder } from '../queries.js'; import { StoreRegistry } from '../rest-store-registry.js'; /** A filter that limits the local REST collection to a subset of the remote collection. */ export interface RestCollectionFilter { namedFilter: string | null; query: any | null; resourceIds: ResourceId[] | null; } /** Options that govern the behavior of a REST collection's data store. */ export interface RestCollectionStoreOptions { detail: { allowMultiple: boolean; autoEdit: boolean; autoFromMultipleSelection: boolean; autoFromSingleInsertion: boolean; autoFromSingleSelection: boolean; constrainToSelection: boolean; }; filter: RestCollectionFilter; idProperty: string; limit: number | null; limitTransientDataToLocalCollection: boolean; loading: { firstPageSize?: number; pageSize?: number; }; order?: QueryOrder; propertiesToExclude?: string[]; referencePathsToExpand?: string[]; restCollectionUrl: string; } /** Default options that govern the behavior of a REST collection's data store */ export declare const DEFAULT_REST_COLLECTION_STORE_OPTIONS: Omit; export type RestCollectionStatus = 'Uninitialized' | 'NotLoaded' | 'Loading' | 'LoadingMore' | 'Loaded' | 'Failed'; export type RestCollectionStoreStatus = 'NotLoaded' | 'Loading' | 'LoadingMore' | 'Loaded' | 'Failed'; /** A REST collection's state, including settings and contents. */ export interface RestCollectionStoreState { idProperty: string; filter: RestCollectionFilter; order: QueryOrder | null; propertiesToExclude: string[] | null; referencePathsToExpand: string[] | null; restCollectionUrl: string; resources: Resource[]; remoteCollectionSize: number | null; status: RestCollectionStoreStatus; selection: Resource[]; detailSelection: Resource[]; invalidResources: Resource[]; listNavigators: { [name: string]: any; }; editingDetailSelection: boolean; batchSaveAttempted: boolean; editors: any[]; transientData: { [id: ResourceId]: any; }; _loadId?: string; _loadOffset?: number; } interface RestCollectionLoadOptions { firstPageSize?: number; pageSize?: number; } interface RestCollectionQueryParams { /** Name of a predefined filter. */ namedFilter?: string; /** Deterministically JSON-serialized representation of a QueryClause. */ q?: string; /** Deterministically JSON-serialized representation of a QueryOrder. */ o?: string; /** Deterministically JSON-serialized array of path strings to exclude. */ ex?: string; /** Deterministically JSON-serialized array of path strings to expand. */ r?: string; /** Page offset, the 0-based index of the first resource to return. */ offset?: number; /** Page size, the maximum number of resources to return. */ limit?: number; } declare const makeStore: (storeId: string, options: RestCollectionStoreOptions) => import("pinia").StoreDefinition) => RestCollectionQueryParams; }, { /** * Reset the store to its initial state. * * Configuration is retained, but REST collection contents and contextual state are reset. */ reset(): void; /** * Reset the store to its initial state, but retain transient data if appropriate. * * As with {@link reset}, configuration is retained, but REST collection contents and contextual state are reset. * Transient data are retained if options.limitTransientDataToLocalCollection is false. */ resetRetainingTransientData(): void; /** * Turn editing mode on or off for the current detail selection. * * Components using this store use the editingDetailSelection state property to govern whether to show an editor for * any current detail selection. * * @param editingDetailSelection The new setting: true if an the detail selection should be shown in an editor, * false if not. */ setEditingDetailSelection(editingDetailSelection: boolean): void; /** * Set the filter. * * This function sets the whole filter without triggering a reload of the local collection. More commonly, clients * will call {@link setQuery} or {@link setFilterResourceIds}. * * @param filter The new filter. */ setFilter(filter: RestCollectionFilter): void; /** * Set the filter query. * * If the collection has a state other than NotLoaded, it will be reloaded. * * @param query The new filter query. * @return A promise that resolves when {@link loadResources} completes, or immediately if the collection does not * need to be reloaded. */ setQuery(query: QueryClause | null): Promise; /** * Set the list if resource IDs to filter on. * * If the collection has a state other than NotLoaded, it will be reloaded. * * @param resourceIds The list of resource IDs for the new filter. * @return A promise that resolves when {@link loadResources} completes, or immediately if the collection does not * need to be reloaded. */ setFilterResourceIds(resourceIds: ResourceId[] | null): Promise; /** * Indicate that a batch save has been attempted and failed. * * Setting this flag is a way of communicating with other client code. The flag should be cleared after further * edits or when another validation or save operations is attempted. * * @param batchSaveAttempted A flag indicating whether a batch save has been attempted and failed. */ setBatchSaveAttempted(batchSaveAttempted: boolean): void; /** * Clear the collection's contents. * * Configuration and contextual state are retained, but REST collection contents are reset. */ clear(): void; /** * Clear the collection's contents, but retain transient data if appropriate. * * As with {@link reset}, configuration and contextual state are retained, but REST collection contents are reset. * Transient data are retained if options.limitTransientDataToLocalCollection is false. */ clearRetainingTransientData(): void; /** * Load the collection, if it has not been loaded. * * The collection will be loaded if its current status is not Loaded, Loading, LoadingMore, or Failed. */ ensureCollectionLoaded(): Promise; /** * Load the collection. * * If pagination is enabled, this may result in multiple HTTP requests. The function's Promise is resolved once * the first page is loaded. * * @param loadOptions Pagination options that may override the defaults. */ loadResources(loadOptions?: RestCollectionLoadOptions): Promise; /** * Load the collection, optionally starting at some offset. * * If pagination is enabled, this may result in multiple HTTP requests. The function's Promise is resolved once * the first page is loaded. * * @param offset The offset at which to start loading. When loading a whole collection, this will be 0; but if * there are more pages to load, the function will call itself with the next page offset. * @param loadId A unique identifier for this load operation, which is used to detect whether results should be * discarded because a later load operation has been issued. Before calling this method, this identifier should * be written to the store's state property named loadId. * @param loadOptions Pagination options that may override the defaults. */ _loadResources(offset: number, loadId: string, loadOptions: RestCollectionLoadOptions): Promise; /** * Verify that a resource does not exist in the remote collection. * * After checking the remote collection and verifying that the resource does not exist, this function calls * {@link recordDeletion} to delete it from the local collection. * * @param itemId The ID of the deleted resource to check. * @return true if the record does not exist in the remote collection, false if it does or if an error occurred. */ checkForDeletedResource(itemId: ResourceId): Promise; /** * Record a deletion, removing the deleted resource from the local collection. * * This should be called after deleting a resource from the remote collection. It is called, for instance, by * {@link deleteResource}; but it can also be called when the application is aware of deletions from the remote * collection made by other means. * * @param resourceId The ID of the resource that has been deleted. */ recordDeletion(resourceId: ResourceId): void; /** * Record an insertion, adding the inserted resource to the local collection. * * This should be called after inserting a resource into the remote collection. It is called, for instance, by * {@link saveResource}; but it can also be called when the application is aware of insertions into the remote * collection made by other means. * * It is important that the resources to be added to the local collection have the same object-graph * characteristics as other resources in the local collection. (These characteristics include property inclusions * and exclusions, as well as reference expansions.) To ensure this, you may call {@refreshResource} to fetch the * resource using the collection's settings. * * @param resource The item that has been inserted. * @param TODO */ recordInsertion(resource: Resource, { insertAtBeginning, transientData }?: { insertAtBeginning?: boolean | undefined; transientData?: any; }): void; /** * Record an update, making the same changes in the local collection. * * This should be called after updating a resource in the remote collection. It is called, for instance, by * {@link saveResource} and {@link refreshResource}; but it can also be called when the application is aware of * updates in the remote collection made by other means. * * It is important that the resource have the same object-graph characteristics as other resources in the local * collection. (These characteristics include property inclusions and exclusions, as well as reference * expansions.) To ensure this, you may instead call {@refreshResource} to fetch the resource using the * collection's settings; this will in turn call {@link recordUpdate}. * * @param resource The item that has been updated. */ recordUpdate(resource: Resource): void; /** * Refresh a resource by requesting it from the remote collection. * * If the resource already exists in the local collection, {@link recordUpdate} will be called to update it there. * If not, this method will return the resource but will not add it to the collection. * * This function is called by {@link insertItem} and {@link updateItem} to ensure that the local copy of the added * or updated resource has the same object-graph characteristics as the rest of the local collection. * * @param resourceId The ID of the resource to refresh. * @return The refreshed resource, or null if refreshing failed. */ refreshResource(resourceId: ResourceId): Promise; /** * Insert a new unsaved resource into the local collection and enter editing mode. * * @param resourceDefaults Initial properties of the new resource. */ addResource(resourceDefaults?: Resource): void; /** * Delete one resource. * * A delete request is sent to the REST API. If it succeeds, the resource is removed from the local collection. * * @param resourceId The ID of the resource to delete. */ deleteResource(resourceId: ResourceId): Promise; /** * Write a new or updated resource to the remote collection, then mirror the change in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param resource The new or updated resource. If it has an ID, an update will be attempted; otherwise it will be * created. * @returns The refreshed local resource after the change has been persisted to the remote collection, or null if * the operation failed. */ saveResource(resource: Resource): Promise; /** * Write new and/or updated resources to the remote collection, and mirror the changes in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param resources Resources to create or update. The two operations may be mixed in the list; when a resource * has an ID, an update will be attempted, while otherwise it will be added. * @returns An array of refreshed local resources, one for each remote resource whose save operation succeeded. */ saveResources(resources: Resource[]): Promise; /** * Perform an update of a resource of the remote collection, then mirror the changes in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param partialResource The partial resource to merge. * @returns The refreshed local resource after the change has been persisted to the remote collection, or null if * the operation failed. */ updateResource(partialResource: Resource): Promise; /** * Perform an update of multiple resource of the remote collection, then mirror the changes in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param partialResources The partial resources to merge. * @returns The refreshed local resource after the change has been persisted to the remote collection, or null if * the operation failed. */ updateResources(partialResources: Resource[]): Promise; /** Clear all transient data. */ clearTransientData(): void; /** * Record which local resources currently fail validation. * * This is useful in multi-resource editing contexts. * * @param resourceIds The IDs of all local resources that failed validation. */ setInvalidResourceIds(resourceIds: ResourceId[]): void; /** * Set transient data. * * @param transientData The new transient data. * @param merge If true, combine each resource's transient data with existing transient data; if false, replace * the transient data for each resource ID in the keys of transientData. */ setTransientDataForResources(params: SetTransientDataParams): void; /** * Clear the selection. */ clearSelection(): void; /** * Remove resources from the selection. * * @param resourceIds The IDs of resources to remove from the selection. */ deselectResources(resourceIds: ResourceId[]): void; /** * Add to or replace the selection. * * @param recordIds The record IDs to select. * @param addToSelection true if the existing selection should be expanded, false if it should be replaced. * @param edit If not undefined, sets the editing mode of the new selection. If undefined, the editing mode will * be left as is, or set to true if options.detail.autoEdit is true. */ selectResources(resourceIds: ResourceId[], options?: SelectResourcesOptions): void; /** * Set a new selection. * * @param selectedResourceIds The resource IDs in the new selection. * @param edit If not undefined, sets the editing mode of the new selection. If undefined, the editing mode will * be left as is, or set to true if options.detail.autoEdit is true. */ setSelection(selectedResourceIds: ResourceId[], edit?: boolean): void; /** * Hide the detail view. * * This clears detailSelection and sets the detail editing mode to false. */ hideDetail(): void; /** * Show the current selection in the detail view. * * If options.detail.allowMultiple is false and more than one resource is selected, the detail view will not be * changed. * * @param edit If not undefined, sets the detail editing mode. If undefined, the editing mode will be left as is, * or set to true if options.detail.autoEdit is true. */ showSelectionAsDetail(edit: boolean): void; /** * Deregister an editor. * * @param editor The editor to deregister. */ deregisterEditor(editor: any): void; /** * Register an editor. * * @param editor The editor to register. */ registerEditor(editor: any): void; /** * Deregister a list navigator. * * @param name The name of the list navigator to deregister. * @param listNavigator The list navigator. If defined, the named list navigator will only be deleted if it equals * this parameter. */ deregisterListNavigator({ name, listNavigator }: { name: string; listNavigator: any; }): void; /** * Register a list navigator. * * Registering a component such as a list view as a list navigator can help other components with list navigation. * For instance, code that implements a "next" button in a detail view might use the list navigator to determine * what resource to select next. * * If another list navigator is registered under this name, its registration will be replaced. * * @param name The name under which to register the list navigator. * @param listNavigator The list navigator. */ registerListNavigator({ name, listNavigator }: { name: string; listNavigator: any; }): void; }>; export type RestCollectionStore = ReturnType>; export declare const storeRegistry: StoreRegistry) => RestCollectionQueryParams; }, { /** * Reset the store to its initial state. * * Configuration is retained, but REST collection contents and contextual state are reset. */ reset(): void; /** * Reset the store to its initial state, but retain transient data if appropriate. * * As with {@link reset}, configuration is retained, but REST collection contents and contextual state are reset. * Transient data are retained if options.limitTransientDataToLocalCollection is false. */ resetRetainingTransientData(): void; /** * Turn editing mode on or off for the current detail selection. * * Components using this store use the editingDetailSelection state property to govern whether to show an editor for * any current detail selection. * * @param editingDetailSelection The new setting: true if an the detail selection should be shown in an editor, * false if not. */ setEditingDetailSelection(editingDetailSelection: boolean): void; /** * Set the filter. * * This function sets the whole filter without triggering a reload of the local collection. More commonly, clients * will call {@link setQuery} or {@link setFilterResourceIds}. * * @param filter The new filter. */ setFilter(filter: RestCollectionFilter): void; /** * Set the filter query. * * If the collection has a state other than NotLoaded, it will be reloaded. * * @param query The new filter query. * @return A promise that resolves when {@link loadResources} completes, or immediately if the collection does not * need to be reloaded. */ setQuery(query: QueryClause | null): Promise; /** * Set the list if resource IDs to filter on. * * If the collection has a state other than NotLoaded, it will be reloaded. * * @param resourceIds The list of resource IDs for the new filter. * @return A promise that resolves when {@link loadResources} completes, or immediately if the collection does not * need to be reloaded. */ setFilterResourceIds(resourceIds: ResourceId[] | null): Promise; /** * Indicate that a batch save has been attempted and failed. * * Setting this flag is a way of communicating with other client code. The flag should be cleared after further * edits or when another validation or save operations is attempted. * * @param batchSaveAttempted A flag indicating whether a batch save has been attempted and failed. */ setBatchSaveAttempted(batchSaveAttempted: boolean): void; /** * Clear the collection's contents. * * Configuration and contextual state are retained, but REST collection contents are reset. */ clear(): void; /** * Clear the collection's contents, but retain transient data if appropriate. * * As with {@link reset}, configuration and contextual state are retained, but REST collection contents are reset. * Transient data are retained if options.limitTransientDataToLocalCollection is false. */ clearRetainingTransientData(): void; /** * Load the collection, if it has not been loaded. * * The collection will be loaded if its current status is not Loaded, Loading, LoadingMore, or Failed. */ ensureCollectionLoaded(): Promise; /** * Load the collection. * * If pagination is enabled, this may result in multiple HTTP requests. The function's Promise is resolved once * the first page is loaded. * * @param loadOptions Pagination options that may override the defaults. */ loadResources(loadOptions?: RestCollectionLoadOptions): Promise; /** * Load the collection, optionally starting at some offset. * * If pagination is enabled, this may result in multiple HTTP requests. The function's Promise is resolved once * the first page is loaded. * * @param offset The offset at which to start loading. When loading a whole collection, this will be 0; but if * there are more pages to load, the function will call itself with the next page offset. * @param loadId A unique identifier for this load operation, which is used to detect whether results should be * discarded because a later load operation has been issued. Before calling this method, this identifier should * be written to the store's state property named loadId. * @param loadOptions Pagination options that may override the defaults. */ _loadResources(offset: number, loadId: string, loadOptions: RestCollectionLoadOptions): Promise; /** * Verify that a resource does not exist in the remote collection. * * After checking the remote collection and verifying that the resource does not exist, this function calls * {@link recordDeletion} to delete it from the local collection. * * @param itemId The ID of the deleted resource to check. * @return true if the record does not exist in the remote collection, false if it does or if an error occurred. */ checkForDeletedResource(itemId: ResourceId): Promise; /** * Record a deletion, removing the deleted resource from the local collection. * * This should be called after deleting a resource from the remote collection. It is called, for instance, by * {@link deleteResource}; but it can also be called when the application is aware of deletions from the remote * collection made by other means. * * @param resourceId The ID of the resource that has been deleted. */ recordDeletion(resourceId: ResourceId): void; /** * Record an insertion, adding the inserted resource to the local collection. * * This should be called after inserting a resource into the remote collection. It is called, for instance, by * {@link saveResource}; but it can also be called when the application is aware of insertions into the remote * collection made by other means. * * It is important that the resources to be added to the local collection have the same object-graph * characteristics as other resources in the local collection. (These characteristics include property inclusions * and exclusions, as well as reference expansions.) To ensure this, you may call {@refreshResource} to fetch the * resource using the collection's settings. * * @param resource The item that has been inserted. * @param TODO */ recordInsertion(resource: Resource, { insertAtBeginning, transientData }?: { insertAtBeginning?: boolean | undefined; transientData?: any; }): void; /** * Record an update, making the same changes in the local collection. * * This should be called after updating a resource in the remote collection. It is called, for instance, by * {@link saveResource} and {@link refreshResource}; but it can also be called when the application is aware of * updates in the remote collection made by other means. * * It is important that the resource have the same object-graph characteristics as other resources in the local * collection. (These characteristics include property inclusions and exclusions, as well as reference * expansions.) To ensure this, you may instead call {@refreshResource} to fetch the resource using the * collection's settings; this will in turn call {@link recordUpdate}. * * @param resource The item that has been updated. */ recordUpdate(resource: Resource): void; /** * Refresh a resource by requesting it from the remote collection. * * If the resource already exists in the local collection, {@link recordUpdate} will be called to update it there. * If not, this method will return the resource but will not add it to the collection. * * This function is called by {@link insertItem} and {@link updateItem} to ensure that the local copy of the added * or updated resource has the same object-graph characteristics as the rest of the local collection. * * @param resourceId The ID of the resource to refresh. * @return The refreshed resource, or null if refreshing failed. */ refreshResource(resourceId: ResourceId): Promise; /** * Insert a new unsaved resource into the local collection and enter editing mode. * * @param resourceDefaults Initial properties of the new resource. */ addResource(resourceDefaults?: Resource): void; /** * Delete one resource. * * A delete request is sent to the REST API. If it succeeds, the resource is removed from the local collection. * * @param resourceId The ID of the resource to delete. */ deleteResource(resourceId: ResourceId): Promise; /** * Write a new or updated resource to the remote collection, then mirror the change in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param resource The new or updated resource. If it has an ID, an update will be attempted; otherwise it will be * created. * @returns The refreshed local resource after the change has been persisted to the remote collection, or null if * the operation failed. */ saveResource(resource: Resource): Promise; /** * Write new and/or updated resources to the remote collection, and mirror the changes in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param resources Resources to create or update. The two operations may be mixed in the list; when a resource * has an ID, an update will be attempted, while otherwise it will be added. * @returns An array of refreshed local resources, one for each remote resource whose save operation succeeded. */ saveResources(resources: Resource[]): Promise; /** * Perform an update of a resource of the remote collection, then mirror the changes in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param partialResource The partial resource to merge. * @returns The refreshed local resource after the change has been persisted to the remote collection, or null if * the operation failed. */ updateResource(partialResource: Resource): Promise; /** * Perform an update of multiple resource of the remote collection, then mirror the changes in the local collection. * * After writing changes, {@link refreshResource} is called to ensure that the local resource (which is also the * return value) has the same object-graph characteristics as the rest of the local collection. * * @param partialResources The partial resources to merge. * @returns The refreshed local resource after the change has been persisted to the remote collection, or null if * the operation failed. */ updateResources(partialResources: Resource[]): Promise; /** Clear all transient data. */ clearTransientData(): void; /** * Record which local resources currently fail validation. * * This is useful in multi-resource editing contexts. * * @param resourceIds The IDs of all local resources that failed validation. */ setInvalidResourceIds(resourceIds: ResourceId[]): void; /** * Set transient data. * * @param transientData The new transient data. * @param merge If true, combine each resource's transient data with existing transient data; if false, replace * the transient data for each resource ID in the keys of transientData. */ setTransientDataForResources(params: SetTransientDataParams): void; /** * Clear the selection. */ clearSelection(): void; /** * Remove resources from the selection. * * @param resourceIds The IDs of resources to remove from the selection. */ deselectResources(resourceIds: ResourceId[]): void; /** * Add to or replace the selection. * * @param recordIds The record IDs to select. * @param addToSelection true if the existing selection should be expanded, false if it should be replaced. * @param edit If not undefined, sets the editing mode of the new selection. If undefined, the editing mode will * be left as is, or set to true if options.detail.autoEdit is true. */ selectResources(resourceIds: ResourceId[], options?: SelectResourcesOptions): void; /** * Set a new selection. * * @param selectedResourceIds The resource IDs in the new selection. * @param edit If not undefined, sets the editing mode of the new selection. If undefined, the editing mode will * be left as is, or set to true if options.detail.autoEdit is true. */ setSelection(selectedResourceIds: ResourceId[], edit?: boolean): void; /** * Hide the detail view. * * This clears detailSelection and sets the detail editing mode to false. */ hideDetail(): void; /** * Show the current selection in the detail view. * * If options.detail.allowMultiple is false and more than one resource is selected, the detail view will not be * changed. * * @param edit If not undefined, sets the detail editing mode. If undefined, the editing mode will be left as is, * or set to true if options.detail.autoEdit is true. */ showSelectionAsDetail(edit: boolean): void; /** * Deregister an editor. * * @param editor The editor to deregister. */ deregisterEditor(editor: any): void; /** * Register an editor. * * @param editor The editor to register. */ registerEditor(editor: any): void; /** * Deregister a list navigator. * * @param name The name of the list navigator to deregister. * @param listNavigator The list navigator. If defined, the named list navigator will only be deleted if it equals * this parameter. */ deregisterListNavigator({ name, listNavigator }: { name: string; listNavigator: any; }): void; /** * Register a list navigator. * * Registering a component such as a list view as a list navigator can help other components with list navigation. * For instance, code that implements a "next" button in a detail view might use the list navigator to determine * what resource to select next. * * If another list navigator is registered under this name, its registration will be replaced. * * @param name The name under which to register the list navigator. * @param listNavigator The list navigator. */ registerListNavigator({ name, listNavigator }: { name: string; listNavigator: any; }): void; }>>; export default makeStore; //# sourceMappingURL=rest-collection-store.d.ts.map