MacPro
97 lines
4.7 KiB
TypeScript
97 lines
4.7 KiB
TypeScript
import { ExtendedVersion, VersionRange } from '../../../base/lib/exver';
|
|
import * as T from '../../../base/lib/types';
|
|
import { InitScript, UninitScript } from '../../../base/lib/inits';
|
|
import { VersionInfo } from './VersionInfo';
|
|
/**
|
|
* Read the current data version from the effects system.
|
|
* @param effects - The effects context
|
|
* @returns The parsed ExtendedVersion or VersionRange, or null if no version is set
|
|
*/
|
|
export declare function getDataVersion(effects: T.Effects): Promise<ExtendedVersion | VersionRange | null>;
|
|
/**
|
|
* Persist a data version to the effects system.
|
|
* @param effects - The effects context
|
|
* @param version - The version to set, or null to clear it
|
|
*/
|
|
export declare function setDataVersion(effects: T.Effects, version: ExtendedVersion | VersionRange | null): Promise<null>;
|
|
/**
|
|
* Check whether two version specifiers overlap (i.e. share at least one common version).
|
|
* Works with any combination of ExtendedVersion and VersionRange.
|
|
*
|
|
* @param a - First version or range
|
|
* @param b - Second version or range
|
|
* @returns True if the two specifiers overlap
|
|
*/
|
|
export declare function overlaps(a: ExtendedVersion | VersionRange, b: ExtendedVersion | VersionRange): boolean;
|
|
/**
|
|
* A directed graph of service versions and their migration paths.
|
|
*
|
|
* Builds a graph from {@link VersionInfo} definitions, then uses shortest-path
|
|
* search to find and execute migration sequences between any two versions.
|
|
* Implements both {@link InitScript} (for install/update migrations) and
|
|
* {@link UninitScript} (for uninstall/downgrade migrations).
|
|
*
|
|
* @typeParam CurrentVersion - The string literal type of the current service version
|
|
*/
|
|
export declare class VersionGraph<CurrentVersion extends string> implements InitScript, UninitScript {
|
|
readonly current: VersionInfo<CurrentVersion>;
|
|
protected initFn: (effects: T.Effects) => Promise<void>;
|
|
protected uninitFn: (effects: T.Effects, target: VersionRange | ExtendedVersion | null) => Promise<void>;
|
|
private readonly graph;
|
|
/** Dump the version graph as a human-readable string for debugging */
|
|
dump(): string;
|
|
private constructor();
|
|
currentVersion: () => ExtendedVersion;
|
|
/**
|
|
* Each exported `VersionInfo.of()` should be imported and provided as an argument to this function.
|
|
*
|
|
* ** The current version must be the FIRST argument. **
|
|
*/
|
|
static of<CurrentVersion extends string, OtherVersions extends Array<VersionInfo<any>>>(options: {
|
|
current: VersionInfo<CurrentVersion>;
|
|
other: OtherVersions;
|
|
}): VersionGraph<CurrentVersion>;
|
|
/**
|
|
* Execute the shortest migration path between two versions.
|
|
*
|
|
* Finds the shortest path in the version graph from `from` to `to`,
|
|
* executes each migration step in order, and updates the data version after each step.
|
|
*
|
|
* @param options.effects - The effects context
|
|
* @param options.from - The source version or range
|
|
* @param options.to - The target version or range
|
|
* @returns The final data version after migration
|
|
* @throws If no migration path exists between the two versions
|
|
*/
|
|
migrate({ effects, from, to, }: {
|
|
effects: T.Effects;
|
|
from: ExtendedVersion | VersionRange;
|
|
to: ExtendedVersion | VersionRange;
|
|
}): Promise<ExtendedVersion | VersionRange>;
|
|
/**
|
|
* Compute the version range from which the current version can be reached via migration.
|
|
* Uses reverse breadth-first search from the current version vertex.
|
|
*/
|
|
canMigrateFrom: () => VersionRange;
|
|
/**
|
|
* Compute the version range that the current version can migrate to.
|
|
* Uses forward breadth-first search from the current version vertex.
|
|
*/
|
|
canMigrateTo: () => VersionRange;
|
|
/**
|
|
* InitScript implementation: migrate from the stored data version to the current version.
|
|
* If no data version exists (fresh install), sets it to the current version.
|
|
* @param effects - The effects context
|
|
*/
|
|
init(effects: T.Effects): Promise<void>;
|
|
/**
|
|
* UninitScript implementation: migrate from the current data version to the target version.
|
|
* Used during uninstall or downgrade to prepare data for the target version.
|
|
*
|
|
* @param effects - The effects context
|
|
* @param target - The target version to migrate to, or null to clear the data version
|
|
*/
|
|
uninit(effects: T.Effects, target: VersionRange | ExtendedVersion | null): Promise<void>;
|
|
}
|
|
export type EnsureUniqueId<A, B = A, OtherVersions = never> = B extends [] ? A : B extends [VersionInfo<infer Version>, ...infer Rest] ? (Version extends OtherVersions ? "One or more versions are not unique"[] : EnsureUniqueId<A, Rest, Version | OtherVersions>) : "There exists a migration that is not a Migration"[];
|