@memberjunction/archiving-engine 0.0.1 → 5.29.0

package/dist/ArchiveRecovery.d.ts

@@ -0,0 +1,47 @@
+import { BaseEntity, UserInfo } from '@memberjunction/core';
+import { RestoreRecordResult } from './types.js';
+/**
+ * Provides recovery operations for archived records, including listing
+ * archived versions and restoring specific versions.
+ */
+export declare class ArchiveRecovery {
+    /**
+     * Retrieves all archived versions for a specific entity record.
+     * Queries the ArchiveRunDetail table for matching records.
+     *
+     * @param entityName - The name of the entity
+     * @param recordId - The primary key value of the record
+     * @param contextUser - User context for database access
+     * @returns Array of ArchiveRunDetail records, ordered by most recent first
+     */
+    GetArchivedVersions(entityName: string, recordId: string, contextUser: UserInfo): Promise<BaseEntity[]>;
+    /**
+     * Restores a specific archived version of a record.
+     * Loads the ArchiveRunDetail, initializes the storage driver,
+     * reads the archive document, and applies the values back to the record.
+     *
+     * @param archiveRunDetailId - ID of the ArchiveRunDetail record to restore
+     * @param contextUser - User context for database and storage access
+     * @returns Result indicating success/failure and which fields were restored
+     */
+    RestoreVersion(archiveRunDetailId: string, contextUser: UserInfo): Promise<RestoreRecordResult>;
+    /**
+     * Loads a single ArchiveRunDetail record by ID.
+     */
+    private LoadArchiveRunDetail;
+    /**
+     * Loads a single ArchiveRun record by ID.
+     */
+    private LoadArchiveRun;
+    /**
+     * Initializes a storage driver from the ArchiveRun's associated configuration.
+     */
+    private InitializeStorageDriver;
+    /**
+     * Returns the DefaultArchiveDriver for restore operations.
+     * ArchiveRunDetail does not store the driver class used during archiving;
+     * the default driver handles the standard JSON-based restore path.
+     */
+    private ResolveDriver;
+}
+//# sourceMappingURL=ArchiveRecovery.d.ts.map

package/dist/ArchiveRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArchiveRecovery.d.ts","sourceRoot":"","sources":["../src/ArchiveRecovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAwD,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAKlH,OAAO,EAAwB,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEpE;;;GAGG;AACH,qBAAa,eAAe;IACxB;;;;;;;;OAQG;IACU,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAiBpH;;;;;;;;OAQG;IACU,cAAc,CAAC,kBAAkB,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAmC5G;;OAEG;YACW,oBAAoB;IAOlC;;OAEG;YACW,cAAc;IAO5B;;OAEG;YACW,uBAAuB;IA4BrC;;;;OAIG;IACH,OAAO,CAAC,aAAa;CAGxB"}

package/dist/ArchiveRecovery.js

@@ -0,0 +1,125 @@
+import { CompositeKey, LogError, LogStatus, Metadata, RunView } from '@memberjunction/core';
+import { FileStorageEngineBase } from '@memberjunction/core-entities';
+import { initializeDriverWithAccountCredentials } from '@memberjunction/storage';
+import { DefaultArchiveDriver } from './DefaultArchiveDriver.js';
+/**
+ * Provides recovery operations for archived records, including listing
+ * archived versions and restoring specific versions.
+ */
+export class ArchiveRecovery {
+    /**
+     * Retrieves all archived versions for a specific entity record.
+     * Queries the ArchiveRunDetail table for matching records.
+     *
+     * @param entityName - The name of the entity
+     * @param recordId - The primary key value of the record
+     * @param contextUser - User context for database access
+     * @returns Array of ArchiveRunDetail records, ordered by most recent first
+     */
+    async GetArchivedVersions(entityName, recordId, contextUser) {
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: 'MJ: Archive Run Details',
+            ExtraFilter: `Entity='${entityName}' AND RecordID='${recordId}' AND Status='Success'`,
+            OrderBy: '__mj_CreatedAt DESC',
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (!result.Success) {
+            LogError(`Failed to load archived versions for ${entityName}/${recordId}: ${result.ErrorMessage}`);
+            return [];
+        }
+        return result.Results;
+    }
+    /**
+     * Restores a specific archived version of a record.
+     * Loads the ArchiveRunDetail, initializes the storage driver,
+     * reads the archive document, and applies the values back to the record.
+     *
+     * @param archiveRunDetailId - ID of the ArchiveRunDetail record to restore
+     * @param contextUser - User context for database and storage access
+     * @returns Result indicating success/failure and which fields were restored
+     */
+    async RestoreVersion(archiveRunDetailId, contextUser) {
+        try {
+            const detail = await this.LoadArchiveRunDetail(archiveRunDetailId, contextUser);
+            if (!detail) {
+                return { Success: false, ErrorMessage: `ArchiveRunDetail not found: ${archiveRunDetailId}`, RestoredFields: [] };
+            }
+            const archiveRun = await this.LoadArchiveRun(detail.Get('ArchiveRunID'), contextUser);
+            if (!archiveRun) {
+                return { Success: false, ErrorMessage: 'Failed to load parent ArchiveRun', RestoredFields: [] };
+            }
+            const storageDriver = await this.InitializeStorageDriver(archiveRun, contextUser);
+            const driver = this.ResolveDriver();
+            const restoreContext = {
+                ArchiveRunDetail: detail,
+                StorageDriver: storageDriver,
+                ContextUser: contextUser,
+            };
+            const result = await driver.RestoreRecord(restoreContext);
+            LogStatus(`RestoreVersion completed for detail ${archiveRunDetailId}: success=${result.Success}`);
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`RestoreVersion failed for detail ${archiveRunDetailId}: ${message}`);
+            return { Success: false, ErrorMessage: message, RestoredFields: [] };
+        }
+    }
+    // ========================================
+    // Private Helpers
+    // ========================================
+    /**
+     * Loads a single ArchiveRunDetail record by ID.
+     */
+    async LoadArchiveRunDetail(detailId, contextUser) {
+        const md = new Metadata();
+        const detail = await md.GetEntityObject('MJ: Archive Run Details', contextUser);
+        const loaded = await detail.InnerLoad(CompositeKey.FromKeyValuePair('ID', detailId));
+        return loaded ? detail : null;
+    }
+    /**
+     * Loads a single ArchiveRun record by ID.
+     */
+    async LoadArchiveRun(archiveRunId, contextUser) {
+        const md = new Metadata();
+        const run = await md.GetEntityObject('MJ: Archive Runs', contextUser);
+        const loaded = await run.InnerLoad(CompositeKey.FromKeyValuePair('ID', archiveRunId));
+        return loaded ? run : null;
+    }
+    /**
+     * Initializes a storage driver from the ArchiveRun's associated configuration.
+     */
+    async InitializeStorageDriver(archiveRun, contextUser) {
+        const configId = archiveRun.Get('ArchiveConfigurationID');
+        const md = new Metadata();
+        const config = await md.GetEntityObject('MJ: Archive Configurations', contextUser);
+        const loaded = await config.InnerLoad(CompositeKey.FromKeyValuePair('ID', configId));
+        if (!loaded) {
+            throw new Error(`ArchiveConfiguration not found: ${configId}`);
+        }
+        const storageAccountId = config.Get('StorageAccountID');
+        if (!storageAccountId) {
+            throw new Error(`No StorageAccountID configured on ArchiveConfiguration: ${configId}`);
+        }
+        await FileStorageEngineBase.Instance.Config(false, contextUser);
+        const accountWithProvider = FileStorageEngineBase.Instance.GetAccountWithProvider(storageAccountId);
+        if (!accountWithProvider) {
+            throw new Error(`File storage account not found or provider inactive for ID: ${storageAccountId}`);
+        }
+        return initializeDriverWithAccountCredentials({
+            accountEntity: accountWithProvider.account,
+            providerEntity: accountWithProvider.provider,
+            contextUser,
+        });
+    }
+    /**
+     * Returns the DefaultArchiveDriver for restore operations.
+     * ArchiveRunDetail does not store the driver class used during archiving;
+     * the default driver handles the standard JSON-based restore path.
+     */
+    ResolveDriver() {
+        return new DefaultArchiveDriver();
+    }
+}
+//# sourceMappingURL=ArchiveRecovery.js.map

package/dist/ArchiveRecovery.js.map

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

package/dist/ArchiveStorageManager.d.ts

@@ -0,0 +1,60 @@
+import { UserInfo } from '@memberjunction/core';
+import { FileStorageBase } from '@memberjunction/storage';
+import { ArchiveDocument } from './types.js';
+/**
+ * Manages the lifecycle of a storage driver for archive operations,
+ * including initialization from a FileStorageAccount and read/write
+ * of archive documents.
+ */
+export declare class ArchiveStorageManager {
+    private _driver;
+    private _accountId;
+    /**
+     * Returns the initialized storage driver, or throws if not yet initialized.
+     */
+    get Driver(): FileStorageBase;
+    /**
+     * Initializes the storage driver for the given FileStorageAccount.
+     * Loads the account and provider from the FileStorageEngineBase cache,
+     * then creates and initializes the appropriate driver via ClassFactory.
+     *
+     * @param storageAccountId - ID of the MJ: File Storage Account to use
+     * @param contextUser - User context for credential resolution
+     */
+    Initialize(storageAccountId: string, contextUser: UserInfo): Promise<void>;
+    /**
+     * Serializes and writes an archive document to storage.
+     *
+     * @param basePath - Configured base path prefix
+     * @param entityName - Entity name for path building
+     * @param recordId - Record primary key value for path building
+     * @param versionStamp - Timestamp for this archive version
+     * @param document - The archive document to write
+     * @returns The storage path and bytes written
+     */
+    WriteArchiveDocument(basePath: string, entityName: string, recordId: string, versionStamp: Date, document: ArchiveDocument): Promise<{
+        storagePath: string;
+        bytesWritten: number;
+    }>;
+    /**
+     * Reads and parses an archive document from storage.
+     *
+     * @param storagePath - Full path to the archive document in storage
+     * @returns The parsed archive document
+     */
+    ReadArchiveDocument(storagePath: string): Promise<ArchiveDocument>;
+    /**
+     * Builds a storage path for an archive document.
+     * Format: `{basePath}/{SanitizedEntityName}/{RecordID}/{VersionStamp}.json`
+     */
+    BuildStoragePath(basePath: string, entityName: string, recordId: string, versionStamp: Date): string;
+    /**
+     * Replaces characters that are problematic in storage paths with underscores.
+     */
+    SanitizeEntityName(name: string): string;
+    /**
+     * Formats a Date as an ISO 8601 string safe for use in file paths.
+     */
+    FormatVersionStamp(date: Date): string;
+}
+//# sourceMappingURL=ArchiveStorageManager.d.ts.map

package/dist/ArchiveStorageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArchiveStorageManager.d.ts","sourceRoot":"","sources":["../src/ArchiveStorageManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAA0C,MAAM,yBAAyB,CAAC;AAElG,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,UAAU,CAAuB;IAEzC;;OAEG;IACH,IAAW,MAAM,IAAI,eAAe,CAKnC;IAED;;;;;;;OAOG;IACU,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBvF;;;;;;;;;OASG;IACU,oBAAoB,CAC7B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,IAAI,EAClB,QAAQ,EAAE,eAAe,GAC1B,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAazD;;;;;OAKG;IACU,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAM/E;;;OAGG;IACI,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,MAAM;IAQ3G;;OAEG;IACI,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI/C;;OAEG;IACI,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;CAGhD"}

package/dist/ArchiveStorageManager.js

@@ -0,0 +1,101 @@
+import { LogStatus } from '@memberjunction/core';
+import { initializeDriverWithAccountCredentials } from '@memberjunction/storage';
+import { FileStorageEngineBase } from '@memberjunction/core-entities';
+/**
+ * Manages the lifecycle of a storage driver for archive operations,
+ * including initialization from a FileStorageAccount and read/write
+ * of archive documents.
+ */
+export class ArchiveStorageManager {
+    constructor() {
+        this._driver = null;
+        this._accountId = null;
+    }
+    /**
+     * Returns the initialized storage driver, or throws if not yet initialized.
+     */
+    get Driver() {
+        if (!this._driver) {
+            throw new Error('ArchiveStorageManager has not been initialized. Call Initialize() first.');
+        }
+        return this._driver;
+    }
+    /**
+     * Initializes the storage driver for the given FileStorageAccount.
+     * Loads the account and provider from the FileStorageEngineBase cache,
+     * then creates and initializes the appropriate driver via ClassFactory.
+     *
+     * @param storageAccountId - ID of the MJ: File Storage Account to use
+     * @param contextUser - User context for credential resolution
+     */
+    async Initialize(storageAccountId, contextUser) {
+        this._accountId = storageAccountId;
+        await FileStorageEngineBase.Instance.Config(false, contextUser);
+        const accountWithProvider = FileStorageEngineBase.Instance.GetAccountWithProvider(storageAccountId);
+        if (!accountWithProvider) {
+            throw new Error(`File storage account not found or provider inactive for ID: ${storageAccountId}`);
+        }
+        const { account, provider } = accountWithProvider;
+        LogStatus(`Initializing archive storage driver for account "${account.Name}" (provider: ${provider.Name})`);
+        this._driver = await initializeDriverWithAccountCredentials({
+            accountEntity: account,
+            providerEntity: provider,
+            contextUser,
+        });
+    }
+    /**
+     * Serializes and writes an archive document to storage.
+     *
+     * @param basePath - Configured base path prefix
+     * @param entityName - Entity name for path building
+     * @param recordId - Record primary key value for path building
+     * @param versionStamp - Timestamp for this archive version
+     * @param document - The archive document to write
+     * @returns The storage path and bytes written
+     */
+    async WriteArchiveDocument(basePath, entityName, recordId, versionStamp, document) {
+        const storagePath = this.BuildStoragePath(basePath, entityName, recordId, versionStamp);
+        const jsonContent = JSON.stringify(document, null, 2);
+        const buffer = Buffer.from(jsonContent, 'utf8');
+        const success = await this.Driver.PutObject(storagePath, buffer, 'application/json');
+        if (!success) {
+            throw new Error(`Failed to write archive document to storage: ${storagePath}`);
+        }
+        return { storagePath, bytesWritten: buffer.byteLength };
+    }
+    /**
+     * Reads and parses an archive document from storage.
+     *
+     * @param storagePath - Full path to the archive document in storage
+     * @returns The parsed archive document
+     */
+    async ReadArchiveDocument(storagePath) {
+        const buffer = await this.Driver.GetObject({ fullPath: storagePath });
+        const jsonContent = buffer.toString('utf8');
+        return JSON.parse(jsonContent);
+    }
+    /**
+     * Builds a storage path for an archive document.
+     * Format: `{basePath}/{SanitizedEntityName}/{RecordID}/{VersionStamp}.json`
+     */
+    BuildStoragePath(basePath, entityName, recordId, versionStamp) {
+        const sanitizedEntity = this.SanitizeEntityName(entityName);
+        const sanitizedRecordId = this.SanitizeEntityName(recordId);
+        const formattedStamp = this.FormatVersionStamp(versionStamp);
+        const prefix = basePath ? `${basePath}/` : '';
+        return `${prefix}${sanitizedEntity}/${sanitizedRecordId}/${formattedStamp}.json`;
+    }
+    /**
+     * Replaces characters that are problematic in storage paths with underscores.
+     */
+    SanitizeEntityName(name) {
+        return name.replace(/[\s:\/\\]/g, '_');
+    }
+    /**
+     * Formats a Date as an ISO 8601 string safe for use in file paths.
+     */
+    FormatVersionStamp(date) {
+        return date.toISOString().replace(/:/g, '_');
+    }
+}
+//# sourceMappingURL=ArchiveStorageManager.js.map

package/dist/ArchiveStorageManager.js.map

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

package/dist/BaseArchiveDriver.d.ts

@@ -0,0 +1,71 @@
+import { BaseEntity } from '@memberjunction/core';
+import { ArchiveRecordContext, ArchiveRecordResult, RestoreRecordContext, RestoreRecordResult, ArchiveDocument, ArchivePrimaryKeyField } from './types.js';
+/**
+ * Abstract base class for archive drivers. Concrete implementations handle
+ * the specifics of how records are archived and restored.
+ *
+ * Use `@RegisterClass(BaseArchiveDriver, 'YourDriverName')` on concrete subclasses
+ * to make them discoverable via the MJ ClassFactory.
+ */
+export declare abstract class BaseArchiveDriver {
+    /**
+     * Determines whether a given record should be archived based on its current field values.
+     * @param context - The archive context including record, field config, etc.
+     * @returns True if the record should be archived, false to skip it
+     */
+    abstract ShouldArchiveRecord(context: ArchiveRecordContext): boolean;
+    /**
+     * Archives a single record: writes the archive document to storage and
+     * optionally nullifies the archived fields on the source record.
+     * @param context - The archive context including record, storage driver, etc.
+     * @returns Result indicating success/failure and storage details
+     */
+    abstract ArchiveRecord(context: ArchiveRecordContext): Promise<ArchiveRecordResult>;
+    /**
+     * Restores a previously archived record by reading the archive document
+     * from storage and setting the field values back on the source record.
+     * @param context - The restore context including the ArchiveRunDetail record
+     * @returns Result indicating success/failure and which fields were restored
+     */
+    abstract RestoreRecord(context: RestoreRecordContext): Promise<RestoreRecordResult>;
+    /**
+     * Builds a storage path for an archive document.
+     * Format: `{basePath}/{SanitizedEntityName}/{RecordID}/{VersionStamp}.json`
+     * @param basePath - The configured base path prefix
+     * @param entityName - The entity name (will be sanitized)
+     * @param recordId - The primary key value of the record
+     * @param versionStamp - The timestamp for this archive version
+     * @returns The full storage path string
+     */
+    protected BuildStoragePath(basePath: string, entityName: string, recordId: string, versionStamp: Date): string;
+    /**
+     * Builds the ArchiveDocument JSON structure from a record context.
+     * @param context - The archive context
+     * @param versionStamp - The timestamp for this version
+     * @returns A fully populated ArchiveDocument
+     */
+    protected BuildArchiveDocument(context: ArchiveRecordContext, versionStamp: Date): ArchiveDocument;
+    /**
+     * Extracts the values of fields configured for archiving from the record.
+     */
+    protected ExtractArchivedFields(context: ArchiveRecordContext): Record<string, unknown>;
+    /**
+     * Extracts a full record snapshot if configured, otherwise returns null.
+     */
+    protected ExtractFullRecord(context: ArchiveRecordContext): Record<string, unknown> | null;
+    /**
+     * Extracts the primary key fields and values from a BaseEntity record.
+     */
+    protected ExtractPrimaryKey(record: BaseEntity): ArchivePrimaryKeyField[];
+    /**
+     * Sanitizes a string for use as a storage path segment by replacing
+     * spaces, colons, and other problematic characters with underscores.
+     */
+    protected SanitizePathSegment(value: string): string;
+    /**
+     * Formats a Date as an ISO 8601 string safe for use in file paths.
+     * Colons are replaced with underscores.
+     */
+    protected FormatVersionStamp(date: Date): string;
+}
+//# sourceMappingURL=BaseArchiveDriver.d.ts.map

package/dist/BaseArchiveDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseArchiveDriver.d.ts","sourceRoot":"","sources":["../src/BaseArchiveDriver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACzB,MAAM,SAAS,CAAC;AAEjB;;;;;;GAMG;AACH,8BAAsB,iBAAiB;IACnC;;;;OAIG;aACa,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO;IAE3E;;;;;OAKG;aACa,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAE1F;;;;;OAKG;aACa,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM1F;;;;;;;;OAQG;IACH,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,MAAM;IAQ9G;;;;;OAKG;IACH,SAAS,CAAC,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,IAAI,GAAG,eAAe;IAsBlG;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUvF;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAO1F;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,sBAAsB,EAAE;IAOzE;;;OAGG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIpD;;;OAGG;IACH,SAAS,CAAC,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;CAGnD"}

package/dist/BaseArchiveDriver.js

@@ -0,0 +1,99 @@
+/**
+ * Abstract base class for archive drivers. Concrete implementations handle
+ * the specifics of how records are archived and restored.
+ *
+ * Use `@RegisterClass(BaseArchiveDriver, 'YourDriverName')` on concrete subclasses
+ * to make them discoverable via the MJ ClassFactory.
+ */
+export class BaseArchiveDriver {
+    // ========================================
+    // Protected Helpers
+    // ========================================
+    /**
+     * Builds a storage path for an archive document.
+     * Format: `{basePath}/{SanitizedEntityName}/{RecordID}/{VersionStamp}.json`
+     * @param basePath - The configured base path prefix
+     * @param entityName - The entity name (will be sanitized)
+     * @param recordId - The primary key value of the record
+     * @param versionStamp - The timestamp for this archive version
+     * @returns The full storage path string
+     */
+    BuildStoragePath(basePath, entityName, recordId, versionStamp) {
+        const sanitizedEntity = this.SanitizePathSegment(entityName);
+        const sanitizedRecordId = this.SanitizePathSegment(recordId);
+        const formattedStamp = this.FormatVersionStamp(versionStamp);
+        const prefix = basePath ? `${basePath}/` : '';
+        return `${prefix}${sanitizedEntity}/${sanitizedRecordId}/${formattedStamp}.json`;
+    }
+    /**
+     * Builds the ArchiveDocument JSON structure from a record context.
+     * @param context - The archive context
+     * @param versionStamp - The timestamp for this version
+     * @returns A fully populated ArchiveDocument
+     */
+    BuildArchiveDocument(context, versionStamp) {
+        const record = context.Record;
+        const archivedFields = this.ExtractArchivedFields(context);
+        const fullRecord = this.ExtractFullRecord(context);
+        const primaryKey = this.ExtractPrimaryKey(record);
+        return {
+            archiveVersion: 1,
+            entityName: record.EntityInfo.Name,
+            entityId: record.EntityInfo.ID,
+            recordId: primaryKey.length > 0 ? primaryKey[0].Value : '',
+            primaryKey,
+            versionStamp: versionStamp.toISOString(),
+            archivedAt: new Date().toISOString(),
+            archiveConfigurationEntityId: context.ConfigEntity.Get('ID'),
+            archiveConfigurationId: context.Config.Get('ID'),
+            mode: context.ConfigEntity.Get('Mode') ?? context.Config.Get('DefaultMode') ?? 'StripFields',
+            archivedFields,
+            fullRecord,
+        };
+    }
+    /**
+     * Extracts the values of fields configured for archiving from the record.
+     */
+    ExtractArchivedFields(context) {
+        const fields = {};
+        for (const fieldConfig of context.FieldConfig.Fields) {
+            if (fieldConfig.IsActive !== false) {
+                fields[fieldConfig.FieldName] = context.Record.Get(fieldConfig.FieldName);
+            }
+        }
+        return fields;
+    }
+    /**
+     * Extracts a full record snapshot if configured, otherwise returns null.
+     */
+    ExtractFullRecord(context) {
+        if (!context.FieldConfig.ArchiveFullRecord) {
+            return null;
+        }
+        return context.Record.GetAll();
+    }
+    /**
+     * Extracts the primary key fields and values from a BaseEntity record.
+     */
+    ExtractPrimaryKey(record) {
+        return record.PrimaryKey.KeyValuePairs.map(kvp => ({
+            FieldName: kvp.FieldName,
+            Value: String(kvp.Value),
+        }));
+    }
+    /**
+     * Sanitizes a string for use as a storage path segment by replacing
+     * spaces, colons, and other problematic characters with underscores.
+     */
+    SanitizePathSegment(value) {
+        return value.replace(/[\s:\/\\]/g, '_');
+    }
+    /**
+     * Formats a Date as an ISO 8601 string safe for use in file paths.
+     * Colons are replaced with underscores.
+     */
+    FormatVersionStamp(date) {
+        return date.toISOString().replace(/:/g, '_');
+    }
+}
+//# sourceMappingURL=BaseArchiveDriver.js.map

package/dist/BaseArchiveDriver.js.map

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

package/dist/DefaultArchiveDriver.d.ts

@@ -0,0 +1,98 @@
+import { BaseArchiveDriver } from './BaseArchiveDriver.js';
+import { ArchiveRecordContext, ArchiveRecordResult, RestoreRecordContext, RestoreRecordResult } from './types.js';
+/**
+ * Default archive driver implementation. Archives configured field values to
+ * external storage, applies the appropriate post-archive action based on mode
+ * (StripFields, HardDelete, ArchiveOnly), and supports restoring the original
+ * values from the stored archive document.
+ */
+export declare class DefaultArchiveDriver extends BaseArchiveDriver {
+    /**
+     * Determines whether the record should be archived by checking if at least
+     * one of the configured fields (or SkipIfAllNullFields) has a non-null value.
+     * If no specific fields are configured but ArchiveFullRecord is true,
+     * always archives — the intent is a full record snapshot, not field stripping.
+     */
+    ShouldArchiveRecord(context: ArchiveRecordContext): boolean;
+    /**
+     * Archives a single record:
+     * 1. Builds the archive document with field values
+     * 2. Writes the document to external storage
+     * 3. Applies the post-archive action based on mode:
+     *    - StripFields: nullifies configured fields on the source record
+     *    - HardDelete: cascades to archive+delete dependent records, then deletes the source record
+     *    - ArchiveOnly: no changes to the source record
+     */
+    ArchiveRecord(context: ArchiveRecordContext): Promise<ArchiveRecordResult>;
+    /**
+     * Restores a previously archived record by reading the archive document
+     * from storage and setting the field values back on the source record.
+     */
+    RestoreRecord(context: RestoreRecordContext): Promise<RestoreRecordResult>;
+    /**
+     * Determines which fields to check for the "should archive" decision.
+     * Uses SkipIfAllNullFields if configured, otherwise all active field names.
+     */
+    private GetFieldsToCheck;
+    /**
+     * Serializes the archive document and writes it to storage.
+     */
+    private WriteDocumentToStorage;
+    /**
+     * Resolves the effective archive mode from the entity config or parent config.
+     */
+    private ResolveMode;
+    /**
+     * Applies the appropriate post-archive action based on the resolved mode.
+     */
+    private ApplyPostArchiveAction;
+    /**
+     * Sets all configured archive fields to their empty value on the source record and saves it.
+     * Uses null for nullable columns and empty string for NOT NULL string columns.
+     */
+    private NullifyArchivedFields;
+    /**
+     * Returns the appropriate empty value for a field based on its nullability.
+     * NOT NULL string fields get empty string; nullable fields get null.
+     */
+    private GetEmptyValueForField;
+    /**
+     * Deletes the source record from the database after successful archival.
+     * Automatically cascades to dependent (child) records via FK relationships
+     * discovered from entity metadata, archiving each child to storage before deleting it.
+     */
+    private HardDeleteRecord;
+    /**
+     * Collects all dependent records depth-first, writes one batch archive file
+     * per entity to storage, then deletes all records leaf-first. This batched
+     * approach dramatically reduces storage API calls compared to per-record writes.
+     */
+    private ArchiveAndDeleteDependentRecords;
+    /**
+     * Recursively collects all dependent records depth-first. Leaves (deepest
+     * children) are added to the array first, so deleting in array order
+     * respects FK constraints. Uses a visited set to prevent infinite loops
+     * from circular references.
+     */
+    private CollectDependentsDepthFirst;
+    /**
+     * Groups collected records by entity name and writes one batch archive
+     * document per entity to storage. A batch document contains all records
+     * of that entity type in a single JSON array, dramatically reducing
+     * the number of storage API calls.
+     */
+    private BatchArchiveDependents;
+    /**
+     * Loads all records from a child entity that reference a parent record via a join field.
+     */
+    private LoadChildRecords;
+    /**
+     * Reads and parses an archive document from storage.
+     */
+    private ReadDocumentFromStorage;
+    /**
+     * Applies the archived field values from the document back onto the entity record and saves.
+     */
+    private ApplyArchivedFieldsToRecord;
+}
+//# sourceMappingURL=DefaultArchiveDriver.d.ts.map

package/dist/DefaultArchiveDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultArchiveDriver.d.ts","sourceRoot":"","sources":["../src/DefaultArchiveDriver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EAEtB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,qBACa,oBAAqB,SAAQ,iBAAiB;IACvD;;;;;OAKG;IACI,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO;IAelE;;;;;;;;OAQG;IACU,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsCvF;;;OAGG;IACU,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6BvF;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;YACW,sBAAsB;IA0BpC;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;YACW,sBAAsB;IA0BpC;;;OAGG;YACW,qBAAqB;IAuBnC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;;;OAIG;YACW,gBAAgB;IAqB9B;;;;OAIG;YACW,gCAAgC;IAmC9C;;;;;OAKG;YACW,2BAA2B;IAoCzC;;;;;OAKG;YACW,sBAAsB;IA2DpC;;OAEG;YACW,gBAAgB;IA0B9B;;OAEG;YACW,uBAAuB;IAMrC;;OAEG;YACW,2BAA2B;CA+B5C"}