@quadnix/octo 0.0.30 → 0.2.0

package/dist/services/state-management/state-provider.interface.d.ts

@@ -1,14 +1,109 @@
 /**
+ * The prefix of the state files the journal writes. A remote state provider uploads them while the
+ * lock is held, and never replaces them when it refreshes.
+ *
+ * @internal
+ */
+export declare const JOURNAL_STATE_FILE_NAME_PREFIX = "journal.";
+/**
+ * The commands that run before a lock. Every other command runs under one, and its journal files
+ * belong to the lock held.
+ *
+ * @internal
+ */
+export declare const JOURNAL_COMMANDS_BEFORE_LOCK: string[];
+/**
+ * Where Octo's state files live.
+ *
+ * Octo has no database - it records what it built in state files, and reads them back on the next run
+ * to work out the diff. A state provider is only asked to put a named blob somewhere and hand it back
+ * later, so implementing this interface is all it takes to keep state in S3, a database, or anywhere
+ * else your team already trusts.
+ *
+ * Pass one to {@link Octo.initialize}.
+ *
  * @group Services/State Management
+ *
+ * @see Techniques for [State Providers](/docs/techniques/state-providers).
  */
 export interface IStateProvider {
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     getAppLock(): Promise<string | undefined>;
+    /**
+     * Reads a state file.
+     *
+     * @throws {@link TransactionError} With the message `No state found!` when the file does not exist.
+     * Octo treats that as a first run rather than an error.
+     */
     getState(stateFileName: string): Promise<Buffer>;
+    /**
+     * Whether `lockId` is the lock currently held.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a *different* lock is
+     * held, so a caller holding a stale id is told it is stale rather than told the app is free.
+     */
     isAppLocked(lockId: string): Promise<boolean>;
-    lockApp(): Promise<{
+    /**
+     * The names of the state files whose name starts with `prefix`, named as
+     * {@link IStateProvider.getState} would be given them.
+     *
+     * Octo reads state by name everywhere else, so this is the only way it can discover a file it was
+     * not told about - a record an interrupted run left behind. Returns an empty list when the store
+     * holds nothing matching, including when it does not exist yet.
+     */
+    listStates(prefix: string): Promise<string[]>;
+    /**
+     * Takes the app lock and returns its id, which `apply` and `commit` must then present.
+     *
+     * The lock is taken atomically, so of two callers racing for it exactly one wins. With `lockId`,
+     * resumes the run already holding that lock instead, which is how a run that died is finished.
+     * `commitId` names the record the run writes into, where the provider keeps one.
+     *
+     * A provider sharing state names where a resume took the state directory from in `resumedFrom`:
+     * `directory`, the directory the lock was taken in, left as it was; `run`, what the run uploaded so
+     * far; `sealed`, the newest sealed state, because the run uploaded nothing.
+     *
+     * @throws {@link AppLockError} When a lock is held, naming the id that holds it. When `lockId` is
+     * given and is not the lock held.
+     */
+    lockApp(lockId?: string): Promise<{
+        commitId?: string;
         lockId: string;
+        resumedFrom?: 'directory' | 'run' | 'sealed';
+    }>;
+    /**
+     * Brings the state up to the newest a run may plan against. `generate` calls it before reading any.
+     *
+     * A provider whose state is always the newest does nothing here, and returns `replaced: false`.
+     * One that replaced the state files names the commit it replaced them with, and the one before.
+     */
+    refreshState(): Promise<{
+        commitId?: string;
+        previousCommitId?: string;
+        replaced: boolean;
     }>;
-    saveState(stateFileName: string, data: Buffer): Promise<void>;
+    /**
+     * Writes state files as one change, overwriting whatever was there. A file comes from `data`, or is
+     * copied from the file at `filePath` without being read into memory; one given `data: undefined` is
+     * deleted. Deleting one that is not there is not an error. A name holding `/` is the machine's own:
+     * a provider sharing state keeps it on the machine.
+     *
+     * A provider that pays per write makes one write of the whole change rather than one per file.
+     */
+    saveStates(stateFiles: ({
+        data: Buffer | undefined;
+        stateFileName: string;
+    } | {
+        filePath: string;
+        stateFileName: string;
+    })[]): Promise<void>;
+    /**
+     * Releases the app lock. Unlocking an app that is not locked is not an error.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is
+     * held, so one run can never release another's.
+     */
     unlockApp(lockId: string): Promise<void>;
-    updateAppLockTransaction(lockId: string): Promise<void>;
 }

package/dist/services/state-management/state-provider.interface.js

@@ -1,2 +1,15 @@
-export {};
+/**
+ * The prefix of the state files the journal writes. A remote state provider uploads them while the
+ * lock is held, and never replaces them when it refreshes.
+ *
+ * @internal
+ */
+export const JOURNAL_STATE_FILE_NAME_PREFIX = 'journal.';
+/**
+ * The commands that run before a lock. Every other command runs under one, and its journal files
+ * belong to the lock held.
+ *
+ * @internal
+ */
+export const JOURNAL_COMMANDS_BEFORE_LOCK = ['generate', 'lock', 'validate'];
 //# sourceMappingURL=state-provider.interface.js.map

package/dist/services/state-management/state-provider.interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-provider.interface.js","sourceRoot":"","sources":["../../../src/services/state-management/state-provider.interface.ts"],"names":[],"mappings":""}
+{"version":3,"file":"state-provider.interface.js","sourceRoot":"","sources":["../../../src/services/state-management/state-provider.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,UAAU,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC"}

package/dist/services/state-management/terraform-state.service.d.ts

@@ -0,0 +1,99 @@
+import { StateManagementService } from './state-management.service.js';
+/**
+ * Moves each module folder's `terraform.tfstate` in and out of Octo's {@link IStateProvider}.
+ *
+ * Terraform's record of what exists is the one thing Octo cannot rebuild, and a local backend leaves
+ * it in the module folder where only the machine that ran the apply can see it. Checking it out
+ * before a terraform command and back in after puts it wherever Octo state already lives, so a team
+ * sharing Octo state shares terraform state with it.
+ *
+ * Check-in is frequent rather than atomic: it runs on every terraform command's return, success or
+ * failure, and on a timer through a long apply. A partial record of what exists beats none.
+ *
+ * {@link TerraformUtility} drives this around every command it runs, so nothing calls it directly.
+ *
+ * @internal
+ */
+export declare class TerraformStateService {
+    private checkInQueue;
+    private isPeriodicCheckInRunning;
+    private periodicCheckIn;
+    private readonly stateManagementService;
+    /**
+     * @param stateManagementService Where terraform state is read from and written to.
+     */
+    constructor(stateManagementService: StateManagementService);
+    /**
+     * Writes every module folder's terraform state to the state provider, as one change.
+     *
+     * A folder holding no state file, or one recording no resources, has its state **deleted** rather
+     * than written - that is a module terraform has destroyed, and a file recording nothing is a file
+     * worth nobody's history. A file that does not parse is left out, keeping the provider's copy:
+     * terraform rewrites the file in place, so a check-in during a command can read it empty or half
+     * written.
+     *
+     * Check-ins are serialized, so the one on a command's return never races the one on the timer.
+     */
+    checkIn(terragruntDir: string, moduleIds: string[]): Promise<void>;
+    /**
+     * Writes the state provider's terraform state into every module folder.
+     *
+     * A module the provider holds nothing for keeps whatever its folder already has, which is what
+     * adopts the state of a stack that ran with a local backend until now. A folder whose state is
+     * ahead of the provider's keeps it too, which is what a run killed before its last check-in
+     * leaves behind. The check-in that follows hands either to the provider.
+     */
+    checkOut(terragruntDir: string, moduleIds: string[]): Promise<void>;
+    /**
+     * The state moves the last generate recorded, each from one module folder into another.
+     */
+    getRecordedMoves(): Promise<{
+        addresses: {
+            from: string;
+            to: string;
+        }[];
+        fromModuleId: string;
+        moduleId: string;
+        outputs: {
+            from: string;
+            to: string;
+        }[];
+    }[]>;
+    /**
+     * Starts checking state in every `intervalInMs`, bounding what a killed runner loses to one interval.
+     */
+    startPeriodicCheckIn(terragruntDir: string, moduleIds: string[], intervalInMs: number): void;
+    /**
+     * Stops the timer {@link TerraformStateService.startPeriodicCheckIn} started.
+     */
+    stopPeriodicCheckIn(): void;
+    /**
+     * Whether the folder's terraform state is a later write of the same state the provider holds: the
+     * same `lineage`, and a higher `serial`. State that cannot be read or parsed is never ahead.
+     */
+    private isFolderStateAhead;
+    /**
+     * A terraform state file's contents, or `undefined` when it does not parse.
+     */
+    private parseState;
+    /**
+     * The name one module's terraform state is stored under, alongside Octo's own state files.
+     */
+    private stateFileName;
+    /**
+     * The body of a check-in, run one at a time through {@link TerraformStateService.checkIn}.
+     */
+    private writeStates;
+}
+/**
+ * @internal
+ */
+export declare class TerraformStateServiceFactory {
+    /**
+     * Never cached: {@link Octo.initialize} builds a new {@link StateManagementService} around the
+     * provider it is given, and a cached instance would go on writing to the previous one.
+     *
+     * @internal
+     */
+    static create(): Promise<TerraformStateService>;
+}

package/dist/services/state-management/terraform-state.service.js

@@ -0,0 +1,197 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Factory } from '../../decorators/factory.decorator.js';
+import { Container } from '../../functions/container/container.js';
+import { StateManagementService } from './state-management.service.js';
+const TERRAFORM_STATE_FILE_NAME = 'terraform.tfstate';
+/**
+ * Moves each module folder's `terraform.tfstate` in and out of Octo's {@link IStateProvider}.
+ *
+ * Terraform's record of what exists is the one thing Octo cannot rebuild, and a local backend leaves
+ * it in the module folder where only the machine that ran the apply can see it. Checking it out
+ * before a terraform command and back in after puts it wherever Octo state already lives, so a team
+ * sharing Octo state shares terraform state with it.
+ *
+ * Check-in is frequent rather than atomic: it runs on every terraform command's return, success or
+ * failure, and on a timer through a long apply. A partial record of what exists beats none.
+ *
+ * {@link TerraformUtility} drives this around every command it runs, so nothing calls it directly.
+ *
+ * @internal
+ */
+export class TerraformStateService {
+    /**
+     * @param stateManagementService Where terraform state is read from and written to.
+     */
+    constructor(stateManagementService) {
+        this.checkInQueue = Promise.resolve();
+        this.isPeriodicCheckInRunning = false;
+        this.stateManagementService = stateManagementService;
+    }
+    /**
+     * Writes every module folder's terraform state to the state provider, as one change.
+     *
+     * A folder holding no state file, or one recording no resources, has its state **deleted** rather
+     * than written - that is a module terraform has destroyed, and a file recording nothing is a file
+     * worth nobody's history. A file that does not parse is left out, keeping the provider's copy:
+     * terraform rewrites the file in place, so a check-in during a command can read it empty or half
+     * written.
+     *
+     * Check-ins are serialized, so the one on a command's return never races the one on the timer.
+     */
+    async checkIn(terragruntDir, moduleIds) {
+        this.checkInQueue = this.checkInQueue.then(() => this.writeStates(terragruntDir, moduleIds), () => this.writeStates(terragruntDir, moduleIds));
+        return this.checkInQueue;
+    }
+    /**
+     * Writes the state provider's terraform state into every module folder.
+     *
+     * A module the provider holds nothing for keeps whatever its folder already has, which is what
+     * adopts the state of a stack that ran with a local backend until now. A folder whose state is
+     * ahead of the provider's keeps it too, which is what a run killed before its last check-in
+     * leaves behind. The check-in that follows hands either to the provider.
+     */
+    async checkOut(terragruntDir, moduleIds) {
+        for (const moduleId of moduleIds) {
+            let data;
+            try {
+                data = await this.stateManagementService.getState(this.stateFileName(moduleId));
+            }
+            catch (error) {
+                if (error.message === 'No state found!') {
+                    continue;
+                }
+                throw error;
+            }
+            const stateFilePath = join(terragruntDir, moduleId, TERRAFORM_STATE_FILE_NAME);
+            if (await this.isFolderStateAhead(stateFilePath, data)) {
+                continue;
+            }
+            await writeFile(stateFilePath, data);
+        }
+    }
+    /**
+     * The state moves the last generate recorded, each from one module folder into another.
+     */
+    async getRecordedMoves() {
+        const { userData } = await this.stateManagementService.getModelState(this.stateManagementService.modelStateFileName);
+        return (userData.terraformFolders ?? []).flatMap(({ moduleId, moves = [] }) => moves.map(({ addresses, fromModuleId, outputs }) => ({ addresses, fromModuleId, moduleId, outputs })));
+    }
+    /**
+     * Starts checking state in every `intervalInMs`, bounding what a killed runner loses to one interval.
+     */
+    startPeriodicCheckIn(terragruntDir, moduleIds, intervalInMs) {
+        if (this.periodicCheckIn) {
+            return;
+        }
+        this.periodicCheckIn = setInterval(() => {
+            // Skip the tick while the last one is still checking in, rather than waiting behind it.
+            if (this.isPeriodicCheckInRunning) {
+                return;
+            }
+            this.isPeriodicCheckInRunning = true;
+            // A tick that fails is not worth aborting the terraform command that is still running - the
+            // check-in on its return reports the failure instead.
+            void this.checkIn(terragruntDir, moduleIds)
+                .catch(() => { })
+                .finally(() => {
+                this.isPeriodicCheckInRunning = false;
+            });
+        }, intervalInMs);
+    }
+    /**
+     * Stops the timer {@link TerraformStateService.startPeriodicCheckIn} started.
+     */
+    stopPeriodicCheckIn() {
+        if (this.periodicCheckIn) {
+            clearInterval(this.periodicCheckIn);
+            this.periodicCheckIn = undefined;
+        }
+    }
+    /**
+     * Whether the folder's terraform state is a later write of the same state the provider holds: the
+     * same `lineage`, and a higher `serial`. State that cannot be read or parsed is never ahead.
+     */
+    async isFolderStateAhead(stateFilePath, providerData) {
+        try {
+            const folderState = JSON.parse(await readFile(stateFilePath, 'utf-8'));
+            const providerState = JSON.parse(providerData.toString());
+            return (typeof folderState.serial === 'number' &&
+                typeof providerState.serial === 'number' &&
+                folderState.lineage === providerState.lineage &&
+                folderState.serial > providerState.serial);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * A terraform state file's contents, or `undefined` when it does not parse.
+     */
+    parseState(data) {
+        try {
+            return JSON.parse(data.toString());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * The name one module's terraform state is stored under, alongside Octo's own state files.
+     */
+    stateFileName(moduleId) {
+        return `${moduleId}.tfstate`;
+    }
+    /**
+     * The body of a check-in, run one at a time through {@link TerraformStateService.checkIn}.
+     */
+    async writeStates(terragruntDir, moduleIds) {
+        const stateFiles = [];
+        for (const moduleId of moduleIds) {
+            const stateFilePath = join(terragruntDir, moduleId, TERRAFORM_STATE_FILE_NAME);
+            const stateFileName = this.stateFileName(moduleId);
+            // Delete the state of a module with no state file.
+            if (!existsSync(stateFilePath)) {
+                stateFiles.push({ data: undefined, stateFileName });
+                continue;
+            }
+            // Skip a file terraform is still writing.
+            const data = await readFile(stateFilePath);
+            const state = this.parseState(data);
+            if (!state) {
+                continue;
+            }
+            // Delete the state of a module recording no resources, and write every other.
+            const holdsNoResources = Array.isArray(state.resources) && state.resources.length === 0;
+            stateFiles.push({ data: holdsNoResources ? undefined : data, stateFileName });
+        }
+        await this.stateManagementService.saveStates(stateFiles);
+    }
+}
+/**
+ * @internal
+ */
+let TerraformStateServiceFactory = class TerraformStateServiceFactory {
+    /**
+     * Never cached: {@link Octo.initialize} builds a new {@link StateManagementService} around the
+     * provider it is given, and a cached instance would go on writing to the previous one.
+     *
+     * @internal
+     */
+    static async create() {
+        const stateManagementService = await Container.getInstance().get(StateManagementService);
+        return new TerraformStateService(stateManagementService);
+    }
+};
+TerraformStateServiceFactory = __decorate([
+    Factory(TerraformStateService)
+], TerraformStateServiceFactory);
+export { TerraformStateServiceFactory };
+//# sourceMappingURL=terraform-state.service.js.map

package/dist/services/state-management/terraform-state.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terraform-state.service.js","sourceRoot":"","sources":["../../../src/services/state-management/terraform-state.service.ts"],"names":[],"mappings":"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"}

package/dist/services/state-management/test.state-provider.d.ts

@@ -1,17 +1,55 @@
 import type { IStateProvider } from './state-provider.interface.js';
 /**
+ * Keeps state in memory, and discards it when the process ends. For tests.
+ *
  * @group Services/State Management
+ *
+ * @see Techniques for [State Providers](/docs/techniques/state-providers).
  */
 export declare class TestStateProvider implements IStateProvider {
     private readonly localState;
     private lockId;
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     getAppLock(): Promise<string | undefined>;
+    /**
+     * Reads a state file.
+     *
+     * @throws {@link TransactionError} With the message `No state found!` when the file does not exist.
+     */
     getState(stateFileName: string): Promise<Buffer>;
+    /**
+     * Whether `lockId` is the lock currently held.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     isAppLocked(lockId: string): Promise<boolean>;
-    lockApp(): Promise<{
-        lockId: string;
+    /**
+     * The names of the state files whose name starts with `prefix`.
+     */
+    listStates(prefix: string): Promise<string[]>;
+    /**
+     * Takes the app lock. With `lockId`, resumes the run already holding it.
+     *
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it. When `lockId`
+     * is given and is not the lock held.
+     */
+    lockApp(lockId?: string): ReturnType<IStateProvider['lockApp']>;
+    /**
+     * Does nothing: the state lives in this process alone, so it is always the newest.
+     */
+    refreshState(): Promise<{
+        replaced: boolean;
     }>;
-    saveState(stateFileName: string, data: Buffer): Promise<void>;
+    /**
+     * Writes state files, overwriting whatever was there and deleting each one given no `data`.
+     */
+    saveStates(stateFiles: Parameters<IStateProvider['saveStates']>[0]): Promise<void>;
+    /**
+     * Releases the app lock.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     unlockApp(lockId: string): Promise<void>;
-    updateAppLockTransaction(lockId: string): Promise<void>;
 }

package/dist/services/state-management/test.state-provider.js

@@ -1,60 +1,112 @@
-import { TransactionError } from '../../errors/index.js';
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { AppLockError, TransactionError } from '../../errors/index.js';
 /**
+ * Keeps state in memory, and discards it when the process ends. For tests.
+ *
  * @group Services/State Management
+ *
+ * @see Techniques for [State Providers](/docs/techniques/state-providers).
  */
 export class TestStateProvider {
     constructor() {
         this.localState = {};
         this.lockId = undefined;
     }
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     async getAppLock() {
         return this.lockId;
     }
+    /**
+     * Reads a state file.
+     *
+     * @throws {@link TransactionError} With the message `No state found!` when the file does not exist.
+     */
     async getState(stateFileName) {
         if (!(stateFileName in this.localState)) {
             throw new TransactionError('No state found!');
         }
         return this.localState[stateFileName];
     }
+    /**
+     * Whether `lockId` is the lock currently held.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     async isAppLocked(lockId) {
-        const existingLockId = await this.getAppLock();
-        if (!existingLockId) {
+        if (!this.lockId) {
             return false;
         }
-        if (lockId !== existingLockId) {
+        if (this.lockId !== lockId) {
             throw new TransactionError('Invalid lock ID!');
         }
-        else {
-            return true;
-        }
+        return true;
+    }
+    /**
+     * The names of the state files whose name starts with `prefix`.
+     */
+    async listStates(prefix) {
+        return Object.keys(this.localState).filter((stateFileName) => stateFileName.startsWith(prefix));
     }
-    async lockApp() {
-        const existingLockId = await this.getAppLock();
-        if (existingLockId) {
-            throw new TransactionError('App already locked!');
+    /**
+     * Takes the app lock. With `lockId`, resumes the run already holding it.
+     *
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it. When `lockId`
+     * is given and is not the lock held.
+     */
+    async lockApp(lockId) {
+        if (lockId) {
+            if (this.lockId !== lockId) {
+                throw new AppLockError(`App is not locked with lock ID "${lockId}"!`, { reason: 'not-held' });
+            }
+            return { lockId };
         }
-        const lockId = crypto.randomUUID();
-        this.lockId = lockId;
-        return { lockId };
+        if (this.lockId) {
+            throw new AppLockError(`App already locked with lock ID "${this.lockId}"!`, {
+                holder: { lockId: this.lockId },
+                reason: 'held',
+            });
+        }
+        this.lockId = randomUUID();
+        return { lockId: this.lockId };
     }
-    async saveState(stateFileName, data) {
-        this.localState[stateFileName] = data;
+    /**
+     * Does nothing: the state lives in this process alone, so it is always the newest.
+     */
+    async refreshState() {
+        return { replaced: false };
     }
+    /**
+     * Writes state files, overwriting whatever was there and deleting each one given no `data`.
+     */
+    async saveStates(stateFiles) {
+        for (const stateFile of stateFiles) {
+            if ('filePath' in stateFile) {
+                this.localState[stateFile.stateFileName] = await readFile(stateFile.filePath);
+            }
+            else if (stateFile.data === undefined) {
+                delete this.localState[stateFile.stateFileName];
+            }
+            else {
+                this.localState[stateFile.stateFileName] = stateFile.data;
+            }
+        }
+    }
+    /**
+     * Releases the app lock.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     async unlockApp(lockId) {
-        const existingLockId = await this.getAppLock();
-        if (!existingLockId) {
+        if (!this.lockId) {
             return;
         }
-        if (lockId !== existingLockId) {
+        if (this.lockId !== lockId) {
             throw new TransactionError('Invalid lock ID!');
         }
         this.lockId = undefined;
     }
-    async updateAppLockTransaction(lockId) {
-        const isAppLocked = await this.isAppLocked(lockId);
-        if (!isAppLocked) {
-            throw new TransactionError('App is unlocked!');
-        }
-    }
 }
 //# sourceMappingURL=test.state-provider.js.map

package/dist/services/state-management/test.state-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"test.state-provider.js","sourceRoot":"","sources":["../../../src/services/state-management/test.state-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAA9B;QACmB,eAAU,GAA8B,EAAE,CAAC;QACpD,WAAM,GAAuB,SAAS,CAAC;IA8DjD,CAAC;IA5DC,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,aAAqB;QAClC,IAAI,CAAC,CAAC,aAAa,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,MAAc;QAC9B,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAE/C,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;YAC9B,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAE/C,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,IAAI,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,aAAqB,EAAE,IAAY;QACjD,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAE/C,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;YAC9B,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,wBAAwB,CAAC,MAAc;QAC3C,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"test.state-provider.js","sourceRoot":"","sources":["../../../src/services/state-management/test.state-provider.ts"],"names":[],"mappings":"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"}