Fix StartOS 0.4 TypeScript packaging to match SDK API

2026-04-09 15:10:44 -05:00
parent 68ec875ee7
commit 8298c083c7
3436 changed files with 867051 additions and 92 deletions
@@ -0,0 +1,96 @@
+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"[];