@salesforce/lds-drafts 1.100.1

package/dist/actionHandlers/AbstractResourceRequestActionHandler.d.ts

@@ -0,0 +1,50 @@
+import type { NetworkAdapter, ResourceRequest, Luvio, DurableStoreKeyMetadataMap } from '@luvio/engine';
+import type { DraftAction, CompletedDraftAction, QueueOperation, PendingDraftAction, DraftActionMetadata, DraftQueue } from '../DraftQueue';
+import { ProcessActionResult } from '../DraftQueue';
+import type { ActionHandler, DraftIdAndKeyMapping, ReplacingActions } from './ActionHandler';
+export type ResponseIngestionEntry<T = unknown> = {
+    response: T;
+    synchronousIngest: AbstractResourceRequestActionHandler<T, unknown>['synchronousIngest'];
+    buildCacheKeysForResponse: AbstractResourceRequestActionHandler<T, unknown>['buildCacheKeysFromResponse'];
+};
+export declare abstract class AbstractResourceRequestActionHandler<ResponseType, DraftMetadata> implements ActionHandler<ResourceRequest, DraftMetadata, ResponseType> {
+    protected readonly draftQueue: DraftQueue;
+    protected readonly networkAdapter: NetworkAdapter;
+    protected readonly getLuvio: () => Luvio;
+    constructor(draftQueue: DraftQueue, networkAdapter: NetworkAdapter, getLuvio: () => Luvio);
+    enqueue(data: ResourceRequest): Promise<PendingDraftAction<ResourceRequest>>;
+    handleAction(action: DraftAction<ResourceRequest, ResponseType>, actionCompleted: (action: CompletedDraftAction<ResourceRequest, ResponseType>) => Promise<void>, actionErrored: (action: DraftAction<ResourceRequest, ResponseType>, retry: boolean) => Promise<void>): Promise<ProcessActionResult>;
+    buildPendingAction(request: ResourceRequest, queue: DraftAction<unknown, unknown>[]): Promise<PendingDraftAction<ResourceRequest>>;
+    handleActionEnqueued(action: PendingDraftAction<ResourceRequest>): Promise<void>;
+    handleActionRemoved(action: DraftAction<ResourceRequest, ResponseType>): Promise<void>;
+    getQueueOperationsForCompletingDrafts(queue: DraftAction<unknown, unknown>[], action: CompletedDraftAction<ResourceRequest, ResponseType>): QueueOperation[];
+    getRedirectMappings(action: CompletedDraftAction<ResourceRequest, ResponseType>): DraftIdAndKeyMapping[] | undefined;
+    handleActionCompleted(action: CompletedDraftAction<ResourceRequest, ResponseType>, queueOperations: QueueOperation[], _queue: DraftAction<unknown, unknown>[], allHandlers: ActionHandler<unknown, unknown, unknown>[]): Promise<void>;
+    handleReplaceAction<Response>(actionId: string, withActionId: string, uploadingActionId: String | undefined, actions: DraftAction<unknown, unknown>[]): ReplacingActions<ResourceRequest, Response>;
+    shouldDeleteActionByTagOnRemoval(action: DraftAction<ResourceRequest, ResponseType>): boolean;
+    updateMetadata(_existingMetadata: DraftActionMetadata, incomingMetadata: DraftActionMetadata): DraftActionMetadata;
+    private isActionOfType;
+    protected reingestRecord(action: DraftAction<ResourceRequest, ResponseType>): Promise<void>;
+    getDraftIdsFromAction(action: DraftAction<ResourceRequest, ResponseType>): string[];
+    ingestResponses(responses: ResponseIngestionEntry[], action: DraftAction<ResourceRequest, ResponseType>): Promise<void>;
+    evictKey(key: string): Promise<void>;
+    abstract handlerId: string;
+    abstract canHandlePublish(key: string): boolean;
+    abstract canRepresentationContainDraftMetadata(representationName: string): boolean;
+    abstract getIdFromRequest(request: ResourceRequest): Promise<string | undefined>;
+    abstract getIdFromResponseBody(responseBody: ResponseType): string;
+    abstract buildTagForTargetId(id: string): string;
+    abstract buildCacheKeysFromResponse(response: ResponseType): DurableStoreKeyMetadataMap;
+    abstract synchronousIngest(response: ResponseType, action: DraftAction<ResourceRequest, ResponseType>): void;
+    abstract getDataForAction(action: DraftAction<ResourceRequest, ResponseType>): Promise<ResponseType | undefined>;
+    abstract getDraftMetadata(key: string): Promise<DraftMetadata | undefined>;
+    abstract applyDraftsToIncomingData(key: string, data: unknown, draftMetadata: DraftMetadata | undefined, publishFn: (key: string, data: any) => void): void;
+    /**
+     * Returns true if the given targetId is a for a draft-created record
+     *
+     * @param targetId the targetId to check
+     */
+    abstract isDraftId(targetId: string): boolean;
+    abstract mergeActions(targetAction: DraftAction<ResourceRequest, ResponseType>, sourceAction: DraftAction<ResourceRequest, ResponseType>): DraftAction<ResourceRequest, ResponseType>;
+}
+export declare function isResourceRequestAction(action: DraftAction<unknown, unknown>): action is DraftAction<ResourceRequest, unknown>;

package/dist/actionHandlers/ActionHandler.d.ts

@@ -0,0 +1,149 @@
+import type { CompletedDraftAction, DraftAction, DraftActionMetadata, PendingDraftAction, ProcessActionResult, QueueOperation } from '../DraftQueue';
+import type { DraftKeyMapping } from '../DraftIdMapping';
+export interface ReplacingActions<Response, Data> {
+    original: DraftAction<Response, Data>;
+    actionToReplace: DraftAction<Response, Data>;
+    replacingAction: DraftAction<Response, Data>;
+}
+export interface DraftIdAndKeyMapping extends DraftKeyMapping {
+    draftId: string;
+    canonicalId: string;
+}
+/**
+ * A Handler that knows what the Data and Response type expected are in a DraftAction.
+ * It knows how to process and set them up.
+ *
+ * The action handler is registered both with the DraftQueue and the Draft environment to handle
+ * all draft application logic to a particular type
+ */
+export interface ActionHandler<Data, DraftMetadata, Type> {
+    /**
+     * The id for this handler. Every action in the queue will have a handlerId property
+     * associated with it which specifies which handler knows how to handle that draft action
+     */
+    handlerId: string;
+    /**
+     * Invoked by the draft environment while ingesting incoming data to determine if the handler knows how to apply drafts to the incoming key
+     * @param key
+     */
+    canHandlePublish(key: string): boolean;
+    /**
+     * Invoked by the draft environment prior to ingesting to determine if the representation type can potentially have draft metadata
+     * @param representationName
+     */
+    canRepresentationContainDraftMetadata(representationName: string): boolean;
+    /**
+     * Enqueues an action to the draft queue
+     * @param data the data that will get added to the draft action
+     */
+    enqueue(data: Data): Promise<PendingDraftAction<Data>>;
+    /**
+     * Used to build a PendingDraftAction that is specific to the type of Data and Response.
+     * @param data
+     * @param queue
+     *
+     * @throws {Error} if any preconditions to building the draft action are not satisfied
+     */
+    buildPendingAction(data: unknown, queue: DraftAction<unknown, unknown>[]): Promise<PendingDraftAction<Data>>;
+    /**
+     * Invoked after an action is enqueued into the draft queue
+     * @param action The action that was just enqueued
+     * @param queue The queue with the new action now inserted
+     */
+    handleActionEnqueued(action: PendingDraftAction<Data>, queue: DraftAction<unknown, unknown>[]): Promise<void>;
+    /**
+     * Invoked by the draft queue when it is this actions turn to execute.
+     * @param action: the action that is executing
+     * @param actionCompleted callback function when the action completes successfully
+     * @param actionErrored callback function invoked when the action errors
+     */
+    handleAction(action: DraftAction<Data, Type>, actionCompleted: (action: CompletedDraftAction<Data, Type>) => Promise<void>, actionErrored: (action: DraftAction<Data, Type>, retry: boolean) => Promise<void>): Promise<ProcessActionResult>;
+    /**
+     * Invoked by the draft queue after an action for this handler is removed from the queue
+     * @param action: the removed action
+     * @param queue: the queue with the action removed
+     */
+    handleActionRemoved(action: DraftAction<Data, Type>, queue: DraftAction<unknown, unknown>[]): Promise<void>;
+    /**
+     * Invoked by the draft queue while an action is completing successfully and returns
+     * a set of queue modification operations that should be performed as a result of the
+     * action completing
+     * @param queue
+     * @param action
+     */
+    getQueueOperationsForCompletingDrafts(queue: DraftAction<unknown, unknown>[], action: CompletedDraftAction<Data, Type>): QueueOperation[];
+    /**
+     * Invoked by the draft queue when an action is completing. Sometimes after an action completes we
+     * need to perform a key redirect (i.e. an object that used to have a draft id now has a real id and it needs to redirect the old id)
+     * This function returns an array of mappings if necessary or undefined if no redirect is necessary as a result of the completed operation
+     * @param action
+     */
+    getRedirectMappings(action: CompletedDraftAction<Data, Type>): DraftIdAndKeyMapping[] | undefined;
+    /**
+     * Invoked by the draft queue after an action completes and is removed from the queue
+     * @param action The completed action
+     * @param queueOperations The queue modification operations that were executes with the completed action
+     * @param queue The updated queue with the completed action removed
+     */
+    handleActionCompleted(action: CompletedDraftAction<Data, Type>, queueOperations: QueueOperation[], queue: DraftAction<unknown, unknown>[], allHandlers: ActionHandler<unknown, unknown, unknown>[]): Promise<void>;
+    /**
+     * Replace an item in the queue with another to take its place (if supported by handler)
+     * @param actionId
+     * @param withActionId
+     * @param uploadingActionId
+     * @param actions
+     */
+    handleReplaceAction<Response>(actionId: string, withActionId: string, uploadingActionId: string | undefined, actions: DraftAction<unknown, unknown>[]): ReplacingActions<Data, Response>;
+    /**
+     * Invoked by the durable store and the draft environment to get the data that is associated with this draft action
+     * The data should include all drafts applied to it (if any)
+     * @param action The action to get data for
+     * @param queue The draft queue
+     *
+     * @returns the data with the up to date draft changes applied. returns undefined if after replaying drafts there is no
+     * data to return (i.e. a draft-created record had it's post action removed)
+     */
+    getDataForAction(action: DraftAction<Data, Type>): Promise<Type | undefined>;
+    /**
+     * Asynchronous function to fetch any necessary metadata required to apply drafts during ingest
+     * Note that since ingest is synchronous any necessary metadata that requires asynchronicity must be fetch prior to ingest commencing
+     * @param key
+     * @returns the metadata or undefined if there's no drafts associated or no metadata for this key
+     */
+    getDraftMetadata(key: string): Promise<DraftMetadata | undefined>;
+    /**
+     * Invoked by the draft environment while ingesting normalized data that may contain drafts.
+     * Note that this function is synchronous since ingestion is synchronous (see note in getDraftMetadata)
+     * @param key The key being ingested
+     * @param data The normalized data being ingested
+     * @param draftMetadata The metadata that was previously fetched using getDraftMetadata
+     * @param publishFn The environment's publish method to publish the data once drafts have been applied
+     */
+    applyDraftsToIncomingData(key: string, data: unknown, draftMetadata: DraftMetadata | undefined, publishFn: (key: string, data: any) => void): void;
+    /**
+     * Invoked by the draft queue when a request to remove an action is made. This tells the queue whether it should just
+     * delete the requested action or any action with the same tag. This is helpful in examples where other related queue items no longer
+     * make sense with this action removed.
+     * @param action The action being removed
+     */
+    shouldDeleteActionByTagOnRemoval(action: DraftAction<Data, Type>): boolean;
+    /**
+     * Invoked by the draft queue when a request to update an actions metadata is made. This allows the handler to mutate the incoming
+     * metadata if necessary
+     * @param existingMetadata
+     * @param incomingMetadata
+     * @returns the metadata that will be persisted
+     */
+    updateMetadata(existingMetadata: DraftActionMetadata, incomingMetadata: DraftActionMetadata): DraftActionMetadata;
+    /**
+     * Merges two actions, overlaying the source over the target (ie: the data from
+     * both actions will be combined, if there are conflicts the source's data will
+     * be used).
+     *
+     * Merging draft actions with different targetIds or different tags will result
+     * in an error.
+     *
+     * NOTE: the resulting merged action will use the target's timestamp and id.
+     */
+    mergeActions(targetAction: DraftAction<Data, Type>, sourceAction: DraftAction<Data, Type>): DraftAction<Data, Type>;
+}

package/dist/actionHandlers/CustomActionHandler.d.ts

@@ -0,0 +1,33 @@
+import type { DraftAction, DraftQueue } from '../DraftQueue';
+import type { ActionHandler } from './ActionHandler';
+export declare enum CustomActionResultType {
+    SUCCESS = "SUCCESS",
+    FAILURE = "FAILURE"
+}
+export declare enum CustomActionErrorType {
+    NETWORK_ERROR = "NETWORK_ERROR",
+    CLIENT_ERROR = "CLIENT_ERROR"
+}
+export interface CustomActionError {
+    type: CustomActionErrorType;
+    message: string;
+}
+interface BaseCustomActionResult {
+    id: string;
+    type: CustomActionResultType;
+}
+export interface CustomActionSuccess extends BaseCustomActionResult {
+    type: CustomActionResultType.SUCCESS;
+}
+export interface CustomActionFailed extends BaseCustomActionResult {
+    type: CustomActionResultType.FAILURE;
+    error: CustomActionError;
+}
+export type CustomActionResult = CustomActionSuccess | CustomActionFailed;
+export type CustomActionExecutor = (action: DraftAction<unknown, unknown>, completed: (result: CustomActionResult) => void) => void;
+export type CustomActionCompletionResponse = (result: CustomActionResult) => void;
+export interface CustomActionData {
+    [key: string]: string;
+}
+export declare function customActionHandler(executor: CustomActionExecutor, id: string, draftQueue: DraftQueue): ActionHandler<CustomActionData, unknown, unknown>;
+export {};