@salesforce/lds-drafts 0.131.0

package/dist/types/actionHandlers/ActionHandler.d.ts

@@ -0,0 +1,148 @@
+import type { CompletedDraftAction, DraftAction, DraftActionMetadata, EnqueueResult, 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<EnqueueResult<Data, Type>>;
+    /**
+     * 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 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
+     */
+    handleActionCompleted(action: CompletedDraftAction<Data, Type>, queueOperations: QueueOperation[], allHandlers: ActionHandler<unknown, unknown, unknown>[]): Promise<void>;
+    /**
+     * Replace the targetAction's data with the sourceAction's data and return
+     * the targetAction.  Also sets the targetAction's status to Pending.
+     *
+     * NOTE: this method mutates the targetAction.
+     *
+     * Implementations can assume the caller has already ensured the given draft
+     * actions have the same targetId, same tag, same version, and are not currently
+     * being uploaded.
+     *
+     * Replacing draft actions with different targetIds or different tags will result
+     * in an error.
+     */
+    handleReplaceAction(targetAction: DraftAction<Data, Type>, sourceAction: DraftAction<Data, Type>): DraftAction<Data, Type>;
+    /**
+     * 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).
+     *
+     * Implementations can assume the caller has already ensured the given draft
+     * actions have the same targetId, same tag, same version, and are not currently
+     * being uploaded.
+     *
+     * 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/types/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 {};

package/dist/types/main.d.ts

@@ -0,0 +1,15 @@
+export { DraftQueue, DraftQueueState, DraftAction, ErrorDraftAction, PendingDraftAction, CompletedDraftAction, DraftActionStatus, ProcessActionResult, DraftQueueChangeListener, DraftActionMetadata, DraftQueueEventType, QueueOperation, } from './DraftQueue';
+export { AdapterBuildNetworkSnapshot, buildLuvioOverrideForDraftAdapters, } from './DraftAwareAdapter';
+export { DRAFT_ID_MAPPINGS_SEGMENT, DraftKeyMapping } from './DraftIdMapping';
+export { DurableDraftQueue, DRAFT_SEGMENT } from './DurableDraftQueue';
+export { generateUniqueDraftActionId } from './utils/id';
+export { DurableDraftStore } from './DurableDraftStore';
+export { DraftStore } from './DraftStore';
+export { DraftManager, DraftManagerState, DraftActionOperationType, DraftQueueItem, DraftQueueItemMetadata, } from './DraftManager';
+export { ActionHandler, ReplacingActions, DraftIdAndKeyMapping, } from './actionHandlers/ActionHandler';
+export type { CustomActionResult } from './actionHandlers/CustomActionHandler';
+export { CustomActionResultType, CustomActionExecutor } from './actionHandlers/CustomActionHandler';
+export { AbstractResourceRequestActionHandler, ResponseIngestionEntry, } from './actionHandlers/AbstractResourceRequestActionHandler';
+export { makeEnvironmentDraftAware } from './makeEnvironmentDraftAware';
+export * from './DraftFetchResponse';
+export { DraftSynthesisErrorType, DraftSynthesisError, isDraftSynthesisError, } from './DraftSynthesisError';

package/dist/types/makeEnvironmentDraftAware.d.ts

@@ -0,0 +1,4 @@
+import type { Luvio, ResourceRequest } from '@luvio/engine';
+import type { DurableEnvironment, DurableStore } from '@luvio/environments';
+import type { ActionHandler, DraftQueue } from './main';
+export declare function makeEnvironmentDraftAware(luvio: Luvio, env: DurableEnvironment, durableStore: DurableStore, handlers: ActionHandler<ResourceRequest, any, any>[], draftQueue: DraftQueue): DurableEnvironment;

package/dist/types/utils/adapter.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from '@luvio/engine';
+export declare function getAdapterData<Config, Data>(adapter: Adapter<Config, Data>, config: Config): Promise<Data | undefined>;

package/dist/types/utils/clone.d.ts

@@ -0,0 +1 @@
+export declare function clone<T>(obj: T): T;

package/dist/types/utils/id.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a time-ordered, unique id to associate with a DraftAction. Ensures
+ * no collisions with existing draft action IDs.
+ */
+export declare function generateUniqueDraftActionId(existingIds: string[]): string;

package/dist/types/utils/language.d.ts

@@ -0,0 +1,24 @@
+declare const keys: {
+    (o: object): string[];
+    (o: {}): string[];
+}, create: {
+    (o: object | null): any;
+    (o: object | null, properties: PropertyDescriptorMap & ThisType<any>): any;
+}, assign: {
+    <T extends {}, U>(target: T, source: U): T & U;
+    <T_1 extends {}, U_1, V>(target: T_1, source1: U_1, source2: V): T_1 & U_1 & V;
+    <T_2 extends {}, U_2, V_1, W>(target: T_2, source1: U_2, source2: V_1, source3: W): T_2 & U_2 & V_1 & W;
+    (target: object, ...sources: any[]): any;
+}, values: {
+    <T>(o: {
+        [s: string]: T;
+    } | ArrayLike<T>): T[];
+    (o: {}): any[];
+};
+declare const stringify: {
+    (value: any, replacer?: ((this: any, key: string, value: any) => any) | undefined, space?: string | number | undefined): string;
+    (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string;
+}, parse: (text: string, reviver?: ((this: any, key: string, value: any) => any) | undefined) => any;
+declare const shift: () => any;
+declare const isArray: (arg: any) => arg is any[];
+export { keys as ObjectKeys, create as ObjectCreate, assign as ObjectAssign, values as ObjectValues, stringify as JSONStringify, parse as JSONParse, shift as ArrayPrototypeShift, isArray as ArrayIsArray, };

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@salesforce/lds-drafts",
+    "version": "0.131.0",
+    "license": "SEE LICENSE IN LICENSE.txt",
+    "description": "LDS Drafts",
+    "main": "dist/ldsDrafts.js",
+    "module": "dist/ldsDrafts.js",
+    "types": "dist/types/main.d.ts",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "import": "./dist/ldsDrafts.js",
+            "types": "./dist/types/main.d.ts",
+            "default": "./dist/ldsDrafts.js"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn build",
+        "build": "rollup --config rollup.config.js",
+        "clean": "rm -rf dist",
+        "test:unit": "NODE_ENV=production jest",
+        "release:corejar": "yarn build && ../core-build/scripts/core.js --adapter=lds-drafts"
+    },
+    "dependencies": {
+        "@luvio/engine": "0.138.8-244.1",
+        "@luvio/environments": "0.138.8-244.1",
+        "@salesforce/lds-utils-adapters": "1.131.0-244.6"
+    }
+}