@sphereon/ssi-sdk.xstate-machine-persistence 0.33.1-next.3 → 0.33.1-next.73

package/dist/index.d.ts

@@ -1,6 +1,426 @@
+import { IAbstractMachineStateStore, StoreMachineStatesFindActiveArgs, StoreMachineStateInfo, StoreMachineStateDeleteExpiredArgs } from '@sphereon/ssi-sdk.data-store';
+import { IAgentPlugin, IAgentContext, IPluginMethodMap } from '@veramo/core';
+import { EventObject, StateValue, SCXML, HistoryValue, AnyEventObject, DefaultContext, StateSchema, Typestate, TypegenDisabled, Interpreter, State } from 'xstate';
+import { EventObject as EventObject$1 } from 'xstate/lib/types';
+
+/**
+ * This class implements the IMachineStatePersistence interface using a datastore.
+ *
+ * This allows you to store and retrieve the State of a state machine/application by their types.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
+declare class MachineStatePersistence implements IAgentPlugin {
+    readonly schema: any;
+    readonly methods: IMachineStatePersistence | {};
+    readonly eventTypes: Array<string>;
+    private readonly _store?;
+    get store(): IAbstractMachineStateStore;
+    constructor(opts: MachineStatePersistOpts);
+    onEvent(event: MachineStatePersistEvent, context: RequiredContext): Promise<void>;
+    private machineStateInit;
+    private machineStatePersist;
+    private machineStatesFindActive;
+    private machineStatesDeleteExpired;
+    private machineStateGet;
+    private machineStateDelete;
+}
+
+/**
+ * Represents the options for persisting machine state.
+ *
+ * @typedef {Object} MachineStatePersistOpts
+ * @property {IAbstractMachineStateStore} store - The store used to persist the machine state.
+ * @property {Array<string>} eventTypes - The types of events to be persisted.
+ */
+type MachineStatePersistOpts = {
+    store?: IAbstractMachineStateStore;
+    eventTypes: Array<string>;
+    isRESTClient?: boolean;
+};
+/**
+ * Enum representing the types of machine state persist events.
+ * @enum {string}
+ */
+declare enum MachineStatePersistEventType {
+    INIT = "INIT",
+    EVERY = "EVERY"
+}
+/**
+ * Represents the arguments for deleting expired states from a machine.
+ */
+type DeleteExpiredStatesArgs = Pick<StoreMachineStateDeleteExpiredArgs, 'deleteDoneStates' | 'machineName' | 'tenantId'>;
+/**
+ * Represents the arguments for finding active states of a store machine.
+ */
+type FindActiveStatesArgs = StoreMachineStatesFindActiveArgs;
+/**
+ * Represents the result of a state deletion operation.
+ *
+ * @typedef {number} DeleteStateResult
+ */
+type DeleteStateResult = number;
+/**
+ * Represents a machine state persist event.
+ *
+ * @typedef {Object} MachineStatePersistEvent
+ * @property {MachineStatePersistEventType} type - The type of the persist event.
+ * @property {MachineStatePersistArgs} data - The data associated with the persist event, along with additional properties `_eventCounter` and `_eventDate`.
+ * @property {number} data._eventCounter - The counter for the persist event.
+ * @property {Date} data._eventDate - The date and time the persist event occurred.
+ */
+type MachineStatePersistEvent = {
+    type: MachineStatePersistEventType;
+    data: Omit<MachineStatePersistArgs, 'machineState'> & {
+        _eventCounter: number;
+        _eventDate: Date;
+        _cleanupOnFinalState: boolean;
+    };
+};
+/**
+ * Represents a RequiredContext class, which is a type definition for the context required by an agent.
+ * It is used to enforce that the agent context implements the necessary interfaces.
+ *
+ * @typeparam T - The type of the machine state persistence.
+ */
+type RequiredContext = IAgentContext<IMachineStatePersistence>;
+/**
+ * Represents the information about the current state of a machine.
+ * @typedef {Object} MachineStateInfo
+ * @property {string} id - The ID of the machine.
+ * @property {SerializableState} state - The serializable state of the machine.
+ * @property {string} description - The description of the machine state.
+ */
+type MachineStateInfo = Omit<StoreMachineStateInfo, 'state'> & {
+    state: SerializableState;
+};
+type MachineStatePersistenceOpts = {
+    disablePersistence?: boolean;
+    customInstanceId?: string;
+    existingInstanceId?: string;
+    expireInMS?: number;
+    expiresAt?: Date;
+};
+type MachineStateInitType = 'new' | 'existing';
+/**
+ * Represents the initial state for a machine.
+ *
+ * @typedef {Object} MachineStateInit
+ * @property {string} existingInstanceId - The unique identifier for the machine instance.
+ * @property {string} machineName - The name of the machine.
+ * @property {string} tenantId - The identifier for the tenant associated with the machine.
+ * @property {Date} createdAt - The date and time when the machine was created.
+ * @property {Date} expiresAt - The date and time when the machine's state expires.
+ */
+type MachineStateInit = Pick<MachineStateInfo, 'instanceId' | 'machineName' | 'tenantId' | 'createdAt' | 'expiresAt'> & {
+    stateType: MachineStateInitType;
+    machineState?: MachineStateInfo;
+};
+/**
+ * Represents the arguments required to initialize the machine state.
+ * @typedef {Object} InitMachineStateArgs
+ * @property {string} machineName - The name of the machine.
+ * @property {Partial<MachineStateInit>} [additionalArgs] - Additional initialization arguments for the machine state.
+ */
+type InitMachineStateArgs = Omit<Partial<MachineStateInit>, 'instanceId'> & Pick<MachineStateInfo, 'machineName'> & Pick<MachineStatePersistenceOpts, 'customInstanceId' | 'existingInstanceId'> & {
+    cleanupAllOtherInstances?: boolean;
+};
+/**
+ * Represents the arguments required to persist the machine state.
+ */
+type MachineStatePersistArgs = Omit<MachineStateInit, 'createdAt'> & Pick<MachineStateInfo, 'state' | 'instanceId'> & Partial<Pick<MachineStateInfo, 'updatedCount'>> & {
+    cleanupOnFinalState?: boolean;
+};
+/**
+ * Represents the arguments required to get machine state.
+ * @typedef {Object} MachineStateGetArgs
+ * @property {string} existingInstanceId - The ID of the machine instance.
+ * @property {string} tenantId - The ID of the tenant the machine belongs to.
+ */
+type MachineStateGetArgs = Pick<StoreMachineStateInfo, 'instanceId' | 'tenantId'>;
+/**
+ * Represents the arguments required for deleting a machine state.
+ *
+ * @typedef {object} MachineStateDeleteArgs
+ * @property {string} existingInstanceId - The ID of the machine instance to delete the state for.
+ * @property {string} tenantId - The ID of the tenant owning the machine instance.
+ */
+type MachineStateDeleteArgs = Pick<StoreMachineStateInfo, 'instanceId' | 'tenantId'>;
+/**
+ * Represents the information for a started interpreter.
+ *
+ * @template TContext The type of the context object.
+ * @template TStateSchema The type of the state schema.
+ * @template TEvent The type of the event object.
+ * @template TTypestate The type of the typestate object.
+ * @template TResolvedTypesMeta The type of the resolved types meta object.
+ */
+type StartedInterpreterInfo<TContext = DefaultContext, TStateSchema extends StateSchema = any, TEvent extends EventObject = EventObject, TTypestate extends Typestate<TContext> = {
+    value: any;
+    context: TContext;
+}, TResolvedTypesMeta = TypegenDisabled> = {
+    interpreter: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>;
+    machineState?: MachineStateInfo;
+    init: MachineStateInit;
+};
+/**
+ * Represents the serializable state of a machine.
+ *
+ * @typedef {Object} SerializableState
+ * @property {XStateConfig<any, AnyEventObject>} config - The machine configuration.
+ */
+type SerializableState = XStateConfig<any, AnyEventObject>;
+/**
+ * The configuration for the XState machine state. Simplified StateConfig object from XState so we have a minimal typed structure
+ *
+ * @template TContext - The context type for the state.
+ * @template TEvent - The event type for the state.
+ */
+interface XStateConfig<TContext, TEvent extends EventObject> {
+    value: StateValue;
+    context: TContext;
+    _event: SCXML.Event<TEvent>;
+    _sessionid: string | null;
+    historyValue?: HistoryValue | undefined;
+    history?: any;
+    actions?: Array<any>;
+    activities?: any;
+    meta?: any;
+    events?: TEvent[];
+    configuration: Array<any>;
+    transitions: Array<any>;
+    children: Record<string, any>;
+    done?: boolean;
+    tags?: Set<string>;
+    machine?: any;
+}
+
+/**
+ * The interface definition for a plugin that can issue and verify Verifiable Credentials and Presentations
+ * that use JSON-LD format.
+ *
+ * @remarks Please see {@link https://www.w3.org/TR/vc-data-model | W3C Verifiable Credentials data model}
+ *
+ * @beta This API is likely to change without a BREAKING CHANGE notice
+ */
+interface IMachineStatePersistence extends IPluginMethodMap {
+    /**
+     * Loads the states of active xstate machines from the database.
+     *
+     * @param args FindActiveStatesArgs
+     * type of the event
+     *
+     * @returns state or null
+     *
+     * @beta This API is likely to change without a BREAKING CHANGE notice
+     */
+    machineStatesFindActive(args: FindActiveStatesArgs): Promise<Array<MachineStateInfo>>;
+    /**
+     * Deletes the state of an xstate machine in the database.
+     *
+     * @param args DeleteExpiredStatesArgs
+     * type: optional type of the machine
+     *
+     * @beta This API is likely to change without a BREAKING CHANGE notice
+     */
+    machineStatesDeleteExpired(args: DeleteExpiredStatesArgs): Promise<DeleteStateResult>;
+    /**
+     * Initializes a state object for a new machine. Does not persist anything
+     * @param args Requires a machineName, instanceId and tenantId are optional
+     */
+    machineStateInit(args: InitMachineStateArgs): Promise<MachineStateInit>;
+    /**
+     * Persists the state
+     * @param args MachineStatePersistArgs
+     *
+     * @param context
+     * @beta This API is likely to change without a BREAKING CHANGE notice
+     */
+    machineStatePersist(args: MachineStatePersistArgs, context: RequiredContext): Promise<MachineStateInfo>;
+    /**
+     * Get a particular machine state by instance id and tenant id
+     * @param args instance id and tenant id
+     *
+     * @param context
+     * @beta This API is likely to change without a BREAKING CHANGE notice
+     */
+    machineStateGet(args: MachineStateGetArgs, context: RequiredContext): Promise<MachineStateInfo>;
+    /**
+     * Delete a particular machine state by instance id and tenant id
+     * @param args instance id and tenant id
+     *
+     * @param context
+     * @beta This API is likely to change without a BREAKING CHANGE notice
+     */
+    machineStateDelete(args: MachineStateDeleteArgs, context: RequiredContext): Promise<boolean>;
+}
+
+/**
+ * Initialize the machine state persistence. Returns a unique instanceId and the machine name amongst others
+ *
+ * @param {Object} opts - The options for initializing the machine state persistence.
+ * @param {InitMachineStateArgs} opts - The arguments for initializing the machine state.
+ * @param {IAgentContext<any>} opts.context - The agent context.
+ * @returns {Promise<MachineStateInit | undefined>} - A promise that resolves to the initialized machine state, or undefined if the agent isn't using the Xstate plugin.
+ */
+declare const machineStatePersistInit: (opts: InitMachineStateArgs & Pick<MachineStatePersistenceOpts, "existingInstanceId" | "customInstanceId"> & {
+    context: IAgentContext<any>;
+}) => Promise<MachineStateInit | undefined>;
+/**
+ * This function allows for the persistence of machine state on every xstate transition. It emits an event with the new state
+ * and other relevant data to be handled by the persistence plugin when enabled.
+ *
+ * @param {Object} opts - The options object.
+ * @param {Interpreter} opts.instance - The XState machine interpreter instance.
+ * @param {IAgentContext<any>} opts.context - The agent context.
+ * @param {MachineStateInit} opts.init - The initial persistence options, containing the unique instanceId.
+ * @returns {Promise<void>} - A promise that resolves when the persistence event is emitted.
+ */
+declare const machineStatePersistOnTransition: <TContext = DefaultContext, TStateSchema extends StateSchema = any, TEvent extends EventObject = EventObject, TTypestate extends Typestate<TContext> = {
+    value: any;
+    context: TContext;
+}, TResolvedTypesMeta = TypegenDisabled>(opts: {
+    interpreter: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>;
+    context: IAgentContext<any>;
+    init: MachineStateInit;
+    cleanupOnFinalState?: boolean;
+}) => Promise<void>;
+/**
+ * Persist the initial state of a machine and register it with the given machine instance.
+ *
+ * @param {InitMachineStateArgs & {instance: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>, context: IAgentContext<any>}} args - The options for initializing
+ * machine state and registering it.
+ * @returns {Promise<MachineStateInit | undefined>} - A promise that resolves to the initial state of the machine, or undefined if the agent isn't using the Xstate plugin.
+ */
+declare const machineStatePersistRegistration: <TContext = DefaultContext, TStateSchema extends StateSchema = any, TEvent extends EventObject = EventObject, TTypestate extends Typestate<TContext> = {
+    value: any;
+    context: TContext;
+}, TResolvedTypesMeta = TypegenDisabled>(args: Omit<InitMachineStateArgs, "machineName"> & Partial<Pick<InitMachineStateArgs, "machineName">> & MachineStatePersistenceOpts & {
+    cleanupOnFinalState?: boolean;
+    cleanupAllOtherInstances?: boolean;
+    interpreter: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>;
+    context: IAgentContext<any>;
+}) => Promise<MachineStateInit | undefined>;
+/**
+ * Resumes the interpreter from a given state.
+ *
+ * @param {Object} args - The arguments for resuming the interpreter.
+ * @param {MachineStateInfo} args.machineState - The machine state information.
+ * @param {boolean} [args.noRegistration] - If true, no registration will be performed.
+ * @param {Interpreter} args.interpreter - The interpreter instance.
+ * @param {IAgentContext<IMachineStatePersistence>} args.context - The context for machine state persistence.
+ *
+ * @returns {Promise<Interpreter>} - A promise that resolves to the resumed interpreter.
+ */
+declare const interpreterResumeFromState: <TContext = DefaultContext, TStateSchema extends StateSchema = any, TEvent extends EventObject = EventObject, TTypestate extends Typestate<TContext> = {
+    value: any;
+    context: TContext;
+}, TResolvedTypesMeta = TypegenDisabled>(args: {
+    machineState: MachineStateInfo;
+    noRegistration?: boolean;
+    cleanupAllOtherInstances?: boolean;
+    cleanupOnFinalState?: boolean;
+    interpreter: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>;
+    context: IAgentContext<IMachineStatePersistence>;
+}) => Promise<StartedInterpreterInfo<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>>;
+/**
+ * Resumes or starts the interpreter from the initial machine state.
+ *
+ * @async
+ * @param {Object} args - The arguments for the function.
+ * @param {MachineStateInit & {stateType?: MachineStateInitType}} args.init - The initialization state of the machine.
+ * @param {boolean} args.noRegistration - Whether registration is required, defaults to false.
+ * @param {Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>} args.interpreter - The interpreter object.
+ * @param {IAgentContext<IMachineStatePersistence>} args.context - The context object.
+ * @returns {Promise} - A promise that resolves to the interpreter instance.
+ * @throws {Error} - If the machine name from init does not match the interpreter id.
+ */
+declare const interpreterStartOrResumeFromInit: <TContext = DefaultContext, TStateSchema extends StateSchema = any, TEvent extends EventObject = EventObject, TTypestate extends Typestate<TContext> = {
+    value: any;
+    context: TContext;
+}, TResolvedTypesMeta = TypegenDisabled>(args: {
+    init: MachineStateInit & {
+        stateType?: MachineStateInitType;
+    };
+    cleanupAllOtherInstances?: boolean;
+    cleanupOnFinalState?: boolean;
+    noRegistration?: boolean;
+    interpreter: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>;
+    context: IAgentContext<IMachineStatePersistence>;
+}) => Promise<StartedInterpreterInfo<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>>;
+/**
+ * Starts or resumes the given state machine interpreter.
+ *
+ * @async
+ * @param {Object} args - The arguments for starting or resuming the interpreter.
+ * @param {MachineStateInitType | 'auto'} [args.stateType] - The state type. Defaults to 'auto'.
+ * @param {string} [args.instanceId] - The instance ID.
+ * @param {string} [args.machineName] - The machine name.
+ * @param {string} [args.tenantId] - The tenant ID.
+ * @param {boolean} args.singletonCheck - Whether to perform a singleton check or not. If more than one machine instance is found an error will be thrown
+ * @param {boolean} [args.noRegistration] - Whether to skip state change event registration or not.
+ * @param {Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>} args.interpreter - The interpreter to start or resume.
+ * @param {IAgentContext<IMachineStatePersistence>} args.context - The agent context.
+ * @returns {Promise} A promise that resolves when the interpreter is started or resumed.
+ * @throws {Error} If there are multiple active instances of the machine and singletonCheck is true.
+ * @throws {Error} If a new instance was requested with the same ID as an existing active instance.
+ * @throws {Error} If the existing state machine with the given machine name and instance ID cannot be found.
+ */
+declare const interpreterStartOrResume: <TContext = DefaultContext, TStateSchema extends StateSchema = any, TEvent extends EventObject = EventObject, TTypestate extends Typestate<TContext> = {
+    value: any;
+    context: TContext;
+}, TResolvedTypesMeta = TypegenDisabled>(args: {
+    stateType?: MachineStateInitType | "auto";
+    instanceId?: string;
+    machineName?: string;
+    tenantId?: string;
+    singletonCheck: boolean;
+    noRegistration?: boolean;
+    cleanupAllOtherInstances?: boolean;
+    cleanupOnFinalState?: boolean;
+    interpreter: Interpreter<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>;
+    context: IAgentContext<IMachineStatePersistence>;
+}) => Promise<StartedInterpreterInfo<TContext, TStateSchema, TEvent, TTypestate, TResolvedTypesMeta>>;
+
+/**
+ * Create a machine state info object useful for the store, based on the provided machine info and existing state.
+ *
+ * @param {MachineStatePersistArgs} machineInfo - The machine info object.
+ * @param {Partial<StoreMachineStateInfo>} [existingState] - The optional existing state object.
+ * @returns {StoreMachineStateInfo} - The store machine state info object.
+ */
+declare const machineStateToStoreInfo: (machineInfo: MachineStatePersistArgs, existingState?: Partial<StoreMachineStateInfo>) => StoreMachineStateInfo;
+declare const storeInfoToMachineInit: (args: StoreMachineStateInfo & {
+    stateType: MachineStateInitType;
+    machineState?: MachineStateInfo;
+}) => MachineStateInit;
+declare const machineStateToMachineInit: (machineInfo: MachineStatePersistArgs, existingState: Partial<StoreMachineStateInfo>) => MachineStateInit;
+/**
+ * Serializes a machine state to a string representation.
+ *
+ * @param {State<T, TEvent> | SerializableState | string} state - The machine state to serialize.
+ * @returns {string} - The serialized machine state.
+ */
+declare const serializeMachineState: <T, TEvent extends EventObject$1>(state: State<T, TEvent> | SerializableState | string) => string;
+/**
+ * Deserializes a serialized machine state.
+ *
+ * @template T - The type of the machine's context.
+ * @template TEvent - The type of the events that the machine handles.
+ * @param {string} state - The serialized machine state.
+ * @returns {State<T, TEvent>} - The deserialized machine state.
+ */
+declare const deserializeMachineState: <T, TEvent extends EventObject$1>(state: string) => State<T, TEvent>;
+
+/**
+ * Emits a machine state persistence event.
+ *
+ * @param {MachineStatePersistEvent} event - The event to be emitted.
+ * @param {RequiredContext} context - The required agent context for the event emission.
+ * @returns {void}
+ */
+declare const emitMachineStatePersistEvent: (event: MachineStatePersistEvent, context: RequiredContext) => void;
+
 declare const schema: any;
-export { schema };
-export * from './agent/MachineStatePersistence';
-export * from './types';
-export * from './functions';
-//# sourceMappingURL=index.d.ts.map
+
+export { type DeleteExpiredStatesArgs, type DeleteStateResult, type FindActiveStatesArgs, type IMachineStatePersistence, type InitMachineStateArgs, type MachineStateDeleteArgs, type MachineStateGetArgs, type MachineStateInfo, type MachineStateInit, type MachineStateInitType, type MachineStatePersistArgs, type MachineStatePersistEvent, MachineStatePersistEventType, type MachineStatePersistOpts, MachineStatePersistence, type MachineStatePersistenceOpts, type RequiredContext, type SerializableState, type StartedInterpreterInfo, type XStateConfig, deserializeMachineState, emitMachineStatePersistEvent, interpreterResumeFromState, interpreterStartOrResume, interpreterStartOrResumeFromInit, machineStatePersistInit, machineStatePersistOnTransition, machineStatePersistRegistration, machineStateToMachineInit, machineStateToStoreInfo, schema, serializeMachineState, storeInfoToMachineInit };