@genesislcap/foundation-state-machine 14.70.0

package/dist/esm/core/machine.js

@@ -0,0 +1,180 @@
+import { __decorate } from "tslib";
+import { createErrorMap } from '@genesislcap/foundation-utils';
+import { defaultExecutionContext, observable, Observable, } from '@microsoft/fast-element';
+import { Container } from '@microsoft/fast-foundation';
+import { interpret, InterpreterStatus } from 'xstate';
+import { logger } from '../utils';
+import { getBindArgs } from './binding';
+/**
+ * AbstractMachine base class.
+ * @public
+ */
+export class AbstractMachine {
+    constructor() {
+        /** {@inheritDoc Machine.onSendEvent} */
+        this.onSendEvent = (event) => {
+            this.send(event.detail);
+        };
+    }
+    /** {@inheritDoc Machine.start} */
+    start(options) {
+        this.interpret(options);
+        this.subscribe();
+        this.startActor();
+    }
+    /** {@inheritDoc Machine.stop} */
+    stop() {
+        this.stopActor();
+        this.unsubscribe();
+    }
+    /**
+     * @internal
+     */
+    interpret(options = {}) {
+        if (!this.machine) {
+            throw new Error('Create this.machine before calling interpret()');
+        }
+        const contextWithErrors = {
+            errors: createErrorMap(logger.error),
+            error: undefined,
+        };
+        this.startingState = options === null || options === void 0 ? void 0 : options.state;
+        this.startingContext = (options.input
+            ? Object.assign(Object.assign({}, contextWithErrors), options.input) : contextWithErrors);
+        this.actor = interpret(this.machine, Object.assign(Object.assign({}, options), { input: this.startingContext, state: this.startingState }));
+        const { value: currentValue, context: currentContext } = this.actor.getSnapshot();
+        this.state = currentValue;
+        this.context = currentContext;
+        this.complete = false;
+        this.output = undefined;
+        this.errors = currentContext.errors;
+        this.error = undefined;
+    }
+    /**
+     * @internal
+     */
+    subscribe() {
+        if (!this.actor) {
+            throw new Error('Call interpret() before calling subscribe()');
+        }
+        this.subscription = this.actor.subscribe({
+            next: (snapshot) => {
+                var _a;
+                this.state = snapshot.value;
+                this.context = snapshot.context;
+                this.errors = this.context.errors;
+                this.error = (_a = this.context.error) !== null && _a !== void 0 ? _a : this.errors.lastError;
+                logger.debug(`${this.machine.id} changed, state:`, this.state, `context:`, this.context);
+            },
+            error: (err) => {
+                this.error = err;
+                logger.error(`${this.machine.id} error:`, err);
+            },
+            complete: () => {
+                this.complete = true;
+                this.output = this.actor.getSnapshot().output;
+                logger.debug(`${this.machine.id} complete:`, this.output);
+            },
+        });
+    }
+    /**
+     * @internal
+     */
+    unsubscribe() {
+        this.subscription && this.subscription.unsubscribe();
+    }
+    /**
+     * @internal
+     */
+    startActor() {
+        var _a;
+        if (((_a = this.actor) === null || _a === void 0 ? void 0 : _a.status) !== InterpreterStatus.Running) {
+            this.actor.start();
+        }
+    }
+    /**
+     * @internal
+     */
+    stopActor() {
+        var _a;
+        if (((_a = this.actor) === null || _a === void 0 ? void 0 : _a.status) === InterpreterStatus.Running) {
+            this.actor.stop();
+        }
+    }
+    /** {@inheritDoc Machine.provide} */
+    provide(implementations) {
+        if (!this.machine) {
+            throw new Error('Create this.machine before calling provide()');
+        }
+        this.machine = this.machine.provide(implementations);
+        if (this.actor) {
+            this.stop();
+            logger.debug('You will need to recall start() after calling provide() on a running machine.');
+        }
+    }
+    /** {@inheritDoc Machine.matches} */
+    matches(value) {
+        if (!this.actor) {
+            throw new Error('Call interpret() before calling matches()');
+        }
+        return this.actor.getSnapshot().matches(value);
+    }
+    /** {@inheritDoc Machine.hasTag} */
+    hasTag(tag) {
+        if (!this.actor) {
+            throw new Error('Call interpret() before calling hasTag()');
+        }
+        return this.actor.getSnapshot().hasTag(tag);
+    }
+    /** {@inheritDoc Machine.send} */
+    send(event) {
+        this.actor.send(event);
+    }
+    /** {@inheritDoc Machine.binding} */
+    binding(token, subscriberChangeCallback, isVolatileBinding = false, context = defaultExecutionContext) {
+        const valueGetter = getBindArgs(token);
+        const initialSubscriber = {
+            handleChange: (binding, args) => {
+                if (subscriberChangeCallback) {
+                    subscriberChangeCallback(binding(this, context), args);
+                }
+            },
+        };
+        const bindingObserver = Observable.binding(valueGetter, initialSubscriber, isVolatileBinding);
+        bindingObserver.observe(this, context);
+        return bindingObserver;
+    }
+}
+__decorate([
+    Container
+], AbstractMachine.prototype, "container", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "machine", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "actor", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "state", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "startingState", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "context", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "startingContext", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "complete", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "output", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "errors", void 0);
+__decorate([
+    observable
+], AbstractMachine.prototype, "error", void 0);

package/dist/esm/core/state.js

@@ -0,0 +1,26 @@
+import { setErrorByKey } from './actions';
+/**
+ * Creates an error state node.
+ *
+ * @param key - An error state key.
+ * @param metaContent - An optional meta content value.
+ * @param final - An optional flag which adds final with output functionality.
+ * @public
+ */
+export const createErrorStateNode = (key, metaContent, final = true) => {
+    return {
+        tags: ['error', key],
+        meta: {
+            content: metaContent ? metaContent : `${key} error.`,
+        },
+        entry: [setErrorByKey(`${key}-error`)],
+        /**
+         * Provide final output to parent machines.
+         */
+        type: final ? 'final' : 'atomic',
+        output: ({ context }) => ({
+            error: context.error,
+            data: context.error,
+        }),
+    };
+};

package/dist/esm/index.federated.js

@@ -0,0 +1 @@
+import('./index');

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './machines';
+export * from './utils';

package/dist/esm/machines/fetch/errors.js

@@ -0,0 +1,46 @@
+import { StatusCodes } from 'http-status-codes';
+/**
+ * NetworkError.
+ * @remarks
+ * Failed to reach server.
+ * @public
+ */
+export class NetworkError extends Error {
+    constructor(url, message = 'Network Error Occurred') {
+        super(message);
+        this.url = url;
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+/**
+ * APIError.
+ * @remarks
+ * Bad server `Response`.
+ * @public
+ */
+export class APIError extends Error {
+    constructor(status, data, message = 'API Error Occurred') {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = 'APIError';
+        Object.setPrototypeOf(this, APIError.prototype);
+    }
+}
+/**
+ * @param error - An error.
+ * @public
+ */
+export const isAPIError = (error) => error instanceof APIError;
+/**
+ * @param error - An error.
+ * @public
+ */
+export const isNetworkError = (error) => error instanceof NetworkError ||
+    (error instanceof TypeError && error.message === 'Failed to fetch');
+/**
+ * @param error - An error.
+ * @public
+ */
+export const isNotFoundError = (error) => isAPIError(error) && error.status === StatusCodes.NOT_FOUND;

package/dist/esm/machines/fetch/index.js

@@ -0,0 +1,4 @@
+export * from './errors';
+export * from './policies';
+export * from './types';
+export * from './machine';

package/dist/esm/machines/fetch/machine.js

@@ -0,0 +1,216 @@
+import { __awaiter, __decorate, __param } from "tslib";
+import { DI, optional } from '@microsoft/fast-foundation';
+import { assign, createMachine, fromPromise } from 'xstate';
+import { AbstractMachine, createErrorStateNode, isAbortError, isDoneInvokeEvent, isErrorEvent, isSyntaxError, isTypeError, setError, } from '../../core';
+import { logger } from '../../utils';
+import { APIError, isAPIError, isNetworkError, isNotFoundError, NetworkError } from './errors';
+import { defaultFetchConfig, defaultFetchMachineContext } from './types';
+/**
+ * FetchConfig DI key.
+ * @internal
+ */
+export const FetchConfig = DI.createInterface();
+/**
+ * Default FetchMachine.
+ * @public
+ */
+let DefaultFetchMachine = class DefaultFetchMachine extends AbstractMachine {
+    constructor(config = defaultFetchConfig) {
+        super();
+        this.config = config;
+        this.machine = createMachine({
+            id: 'fetchMachine',
+            context: ({ input }) => (Object.assign({}, input)),
+            initial: 'idle',
+            states: {
+                idle: {
+                    tags: ['idle'],
+                    meta: {
+                        content: 'Idle.',
+                    },
+                },
+                pending: {
+                    tags: ['pending'],
+                    meta: {
+                        content: 'Fetching, please wait.',
+                    },
+                    invoke: {
+                        src: 'fetch',
+                        input: ({ context }) => (Object.assign(Object.assign({}, context.params), { controller: context.controller })),
+                        onDone: 'success',
+                        onError: [
+                            {
+                                guard: 'isNetworkError',
+                                target: 'error.network',
+                            },
+                            {
+                                guard: 'isNotFoundError',
+                                target: 'error.notFound',
+                            },
+                            {
+                                guard: 'isAPIError',
+                                target: 'error.api',
+                            },
+                            {
+                                guard: 'isAbortError',
+                                target: 'error.abort',
+                            },
+                            {
+                                guard: 'isSyntaxError',
+                                target: 'error.syntax',
+                            },
+                            {
+                                target: 'error.unknown',
+                            },
+                        ],
+                    },
+                },
+                success: {
+                    tags: ['success'],
+                    meta: {
+                        content: 'Success.',
+                    },
+                    entry: ['setResponse', 'setData', 'successCallback'],
+                    /**
+                     * Provide final output to parent machines.
+                     */
+                    type: 'final',
+                    output: ({ context }) => ({
+                        response: context.response,
+                        data: context.data,
+                    }),
+                },
+                error: {
+                    tags: ['error'],
+                    initial: 'unknown',
+                    entry: ['setError', 'errorCallback'],
+                    states: {
+                        unknown: createErrorStateNode('unknown', 'Unknown error.'),
+                        network: createErrorStateNode('network', 'Network error.'),
+                        notFound: createErrorStateNode('notFound', 'Not found error.'),
+                        api: createErrorStateNode('api', 'API error.'),
+                        abort: createErrorStateNode('abort', 'Abort error.'),
+                        syntax: createErrorStateNode('syntax', 'Syntax error.'),
+                    },
+                },
+            },
+            on: {
+                fetch: {
+                    actions: ['abortInFlight', 'resetContext', 'setParams'],
+                    target: '#fetchMachine.pending',
+                },
+                cancel: {
+                    actions: ['abortInFlight', 'resetContext'],
+                    target: '#fetchMachine.idle',
+                },
+            },
+        }, {
+            actors: {
+                fetch: fromPromise(({ input }) => __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b, _c, _d, _e;
+                    const { controller, fetchConfig, requestInit, url } = input;
+                    const fetcher = (_b = (_a = fetchConfig === null || fetchConfig === void 0 ? void 0 : fetchConfig.fetcher) !== null && _a !== void 0 ? _a : this.config.fetcher) !== null && _b !== void 0 ? _b : fetch;
+                    const fetchPolicy = (_c = fetchConfig === null || fetchConfig === void 0 ? void 0 : fetchConfig.fetchPolicy) !== null && _c !== void 0 ? _c : this.config.fetchPolicy;
+                    const init = requestInit !== null && requestInit !== void 0 ? requestInit : { method: 'GET' };
+                    const okChecker = (_d = fetchConfig === null || fetchConfig === void 0 ? void 0 : fetchConfig.responseOkChecker) !== null && _d !== void 0 ? _d : this.config.responseOkChecker;
+                    const dataExtractor = (_e = fetchConfig === null || fetchConfig === void 0 ? void 0 : fetchConfig.responseDataExtractor) !== null && _e !== void 0 ? _e : this.config.responseDataExtractor;
+                    return fetchPolicy.execute(() => __awaiter(this, void 0, void 0, function* () {
+                        try {
+                            const response = yield fetcher(url, Object.assign(Object.assign({}, init), { signal: controller.signal }));
+                            const data = yield dataExtractor(response);
+                            if (!okChecker(response)) {
+                                throw new APIError(response.status, data);
+                            }
+                            return [data, response];
+                        }
+                        catch (error) {
+                            if (isNetworkError(error)) {
+                                throw new NetworkError(url);
+                            }
+                            throw error; // < API, Syntax / JS Error
+                        }
+                    }));
+                })),
+            },
+            actions: {
+                setParams: assign(({ event }) => {
+                    if (event.type === 'fetch') {
+                        return {
+                            params: event.params,
+                            controller: new AbortController(),
+                        };
+                    }
+                }),
+                setResponse: assign(({ event }) => {
+                    if (isDoneInvokeEvent(event)) {
+                        const [_, response] = event.output;
+                        return {
+                            response,
+                        };
+                    }
+                }),
+                setData: assign(({ event }) => {
+                    if (isDoneInvokeEvent(event)) {
+                        const [data] = event.output;
+                        return {
+                            data,
+                        };
+                    }
+                }),
+                setError,
+                abortInFlight: ({ context }) => {
+                    if (context.controller) {
+                        context.controller.abort();
+                    }
+                },
+                resetContext: assign(() => this.startingContext),
+                /**
+                 * successCallback.
+                 * @remarks
+                 * Can be overridden by the caller. Alternatively callers can observe context or successful output.
+                 * @public
+                 */
+                successCallback: () => {
+                    logger.debug('FetchMachine.successCallback invoked.');
+                },
+                /**
+                 * errorCallback.
+                 * @remarks
+                 * Can be overridden by the caller. Alternatively callers can observe context or successful output.
+                 * @public
+                 */
+                errorCallback: () => {
+                    logger.debug('FetchMachine.errorCallback invoked.');
+                },
+            },
+            guards: {
+                isNetworkError: ({ event }) => (isErrorEvent(event) ? isNetworkError(event.data) : false),
+                isAPIError: ({ event }) => (isErrorEvent(event) ? isAPIError(event.data) : false),
+                isNotFoundError: ({ event }) => isErrorEvent(event) ? isNotFoundError(event.data) : false,
+                isAbortError,
+                isSyntaxError,
+                isTypeError,
+            },
+        });
+        this.start();
+    }
+    /** {@inheritDoc Machine.start} */
+    start(options = {
+        input: defaultFetchMachineContext,
+    }) {
+        super.start(options);
+    }
+    /** {@inheritDoc Machine.getFromContainer} */
+    getFromContainer() {
+        return this.container.get(FetchMachine);
+    }
+};
+DefaultFetchMachine = __decorate([
+    __param(0, optional(FetchConfig))
+], DefaultFetchMachine);
+export { DefaultFetchMachine };
+/**
+ * FetchMachine DI key.
+ * @internal
+ */
+export const FetchMachine = DI.createInterface((x) => x.transient(DefaultFetchMachine));

package/dist/esm/machines/fetch/policies.js

@@ -0,0 +1,48 @@
+import { ExponentialBackoff, TimeoutStrategy, handleType, retry, timeout, wrap } from 'cockatiel';
+import { StatusCodes } from 'http-status-codes';
+import { logger } from '../../utils';
+import { APIError, NetworkError } from './errors';
+/**
+ * Default retry stats codes.
+ * @public
+ */
+export const defaultRetryStatsCodes = [
+    StatusCodes.REQUEST_TIMEOUT,
+    StatusCodes.TOO_MANY_REQUESTS,
+    StatusCodes.INTERNAL_SERVER_ERROR,
+    StatusCodes.BAD_GATEWAY,
+    StatusCodes.SERVICE_UNAVAILABLE,
+    StatusCodes.GATEWAY_TIMEOUT,
+];
+/**
+ * A fetch policy factory.
+ * @remarks
+ * Will retry network errors and responses with certain status codes up to the specified max attempts.
+ * @param maxAttempts - Max attempts. Defaults to `2`.
+ * @param retryCodes - Status code array to retry. Defaults to {@link defaultRetryStatsCodes}.
+ * @param backoff - Backoff algo. Defaults to {@link cockatiel#ExponentialBackoff}.
+ * @param timeoutDuration - Timeout duration. Defaults to 3 seconds.
+ * @param logEvents - Log events to the console. Defaults to `true`.
+ * @public
+ */
+export const createFetchPolicy = (maxAttempts = 2, retryCodes = defaultRetryStatsCodes, backoff = new ExponentialBackoff(), timeoutDuration = 3000, logEvents = true) => {
+    const retryPolicy = retry(handleType(NetworkError).orType(APIError, (error) => retryCodes.includes(error.status)), {
+        maxAttempts,
+        backoff,
+    });
+    const timeoutPolicy = timeout(timeoutDuration, TimeoutStrategy.Aggressive);
+    const policy = wrap(retryPolicy, timeoutPolicy);
+    if (logEvents) {
+        retryPolicy.onRetry((data) => logger.info('Fetch retrying...', data));
+        retryPolicy.onFailure((data) => logger.info('Fetch failed:', data));
+        retryPolicy.onSuccess((data) => logger.info('Fetch success:', data));
+        retryPolicy.onGiveUp((data) => logger.info('Fetch gave up:', data));
+        timeoutPolicy.onTimeout(() => logger.info('Fetch timed out'));
+    }
+    return policy;
+};
+/**
+ * The default fetch policy.
+ * @public
+ */
+export const defaultFetchPolicy = createFetchPolicy();

package/dist/esm/machines/fetch/types.js

@@ -0,0 +1,48 @@
+import { __awaiter } from "tslib";
+import { JSONReviver } from '@genesislcap/foundation-utils';
+import { defaultFetchPolicy } from './policies';
+/**
+ * {@inheritDoc ResponseOkChecker}
+ * @public
+ */
+export const defaultResponseOkChecker = (response) => response.ok;
+/**
+ * {@inheritDoc ResponseDataExtractor}
+ * @public
+ */
+export const defaultResponseDataExtractor = (response) => __awaiter(void 0, void 0, void 0, function* () {
+    const text = yield response.text();
+    const contentType = response.headers.get('content-type');
+    const expectingJson = contentType === null || contentType === void 0 ? void 0 : contentType.includes('application/json');
+    return expectingJson ? JSON.parse(text, JSONReviver) : text;
+});
+/**
+ * Creates an extractor that applies a deserializer to the extracted response data.
+ * @param deserializer - The deserializer to apply.
+ * @param extractor - An optional data extractor. Defaults to {@link defaultResponseDataExtractor}.
+ * @public
+ */
+export const createResponseDataExtractorWithDeserializer = (deserializer, extractor = defaultResponseDataExtractor) => (response) => __awaiter(void 0, void 0, void 0, function* () {
+    const json = yield extractor(response);
+    return deserializer(json);
+});
+/**
+ * The default fetch config.
+ * @public
+ */
+export const defaultFetchConfig = {
+    fetcher: fetch,
+    fetchPolicy: defaultFetchPolicy,
+    responseOkChecker: defaultResponseOkChecker,
+    responseDataExtractor: defaultResponseDataExtractor,
+};
+/**
+ * Default FetchMachineContext.
+ * @public
+ */
+export const defaultFetchMachineContext = {
+    params: undefined,
+    controller: undefined,
+    response: undefined,
+    data: undefined,
+};

package/dist/esm/machines/index.js

@@ -0,0 +1 @@
+export * from './fetch';

package/dist/esm/utils/index.js

@@ -0,0 +1 @@
+export * from './logger';

package/dist/esm/utils/logger.js

@@ -0,0 +1,5 @@
+import { createLogger } from '@genesislcap/foundation-utils';
+/**
+ * @public
+ */
+export const logger = createLogger('foundation-state-machine');