grant/recap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix StartOS 0.4 TypeScript packaging to match SDK API

Browse Source
This commit is contained in:
MacPro
2026-04-09 15:10:44 -05:00
parent 68ec875ee7
commit 8298c083c7
3436 changed files with 867051 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
node_modules/@start9labs/start-sdk/package/lib/version/VersionGraph.d.ts
Generated Vendored
+96
View File
@@ -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"[];
node_modules/@start9labs/start-sdk/package/lib/version/VersionGraph.js
Generated Vendored
+247
View File
@@ -0,0 +1,247 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.VersionGraph = void 0;
exports.getDataVersion = getDataVersion;
exports.setDataVersion = setDataVersion;
exports.overlaps = overlaps;
const exver_1 = require("../../../base/lib/exver");
const util_1 = require("../util");
const VersionInfo_1 = require("./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
*/
async function getDataVersion(effects) {
const versionStr = await effects.getDataVersion();
if (!versionStr)
return null;
try {
return exver_1.ExtendedVersion.parse(versionStr);
}
catch (_) {
return exver_1.VersionRange.parse(versionStr);
}
}
/**
* Persist a data version to the effects system.
* @param effects - The effects context
* @param version - The version to set, or null to clear it
*/
async function setDataVersion(effects, version) {
return effects.setDataVersion({ version: version?.toString() || null });
}
function isExver(v) {
return 'satisfies' in v;
}
function isRange(v) {
return 'satisfiedBy' in v;
}
/**
* 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
*/
function overlaps(a, b) {
return ((isRange(a) && isRange(b) && a.intersects(b)) ||
(isRange(a) && isExver(b) && a.satisfiedBy(b)) ||
(isExver(a) && isRange(b) && a.satisfies(b)) ||
(isExver(a) && isExver(b) && a.equals(b)));
}
/**
* 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
*/
class VersionGraph {
/** Dump the version graph as a human-readable string for debugging */
dump() {
return this.graph().dump((metadata) => metadata?.toString());
}
constructor(current, versions) {
this.current = current;
this.initFn = this.init.bind(this);
this.uninitFn = this.uninit.bind(this);
this.currentVersion = (0, util_1.once)(() => exver_1.ExtendedVersion.parse(this.current.options.version));
/**
* Compute the version range from which the current version can be reached via migration.
* Uses reverse breadth-first search from the current version vertex.
*/
this.canMigrateFrom = (0, util_1.once)(() => Array.from(this.graph().reverseBreadthFirstSearch((v) => overlaps(v.metadata, this.currentVersion())))
.reduce((acc, x) => acc.or(isRange(x.metadata)
? x.metadata
: exver_1.VersionRange.anchor('=', x.metadata)), exver_1.VersionRange.none())
.normalize());
/**
* Compute the version range that the current version can migrate to.
* Uses forward breadth-first search from the current version vertex.
*/
this.canMigrateTo = (0, util_1.once)(() => Array.from(this.graph().breadthFirstSearch((v) => overlaps(v.metadata, this.currentVersion())))
.reduce((acc, x) => acc.or(isRange(x.metadata)
? x.metadata
: exver_1.VersionRange.anchor('=', x.metadata)), exver_1.VersionRange.none())
.normalize());
this.graph = (0, util_1.once)(() => {
const graph = new util_1.Graph();
const flavorMap = {};
for (let version of [current, ...versions]) {
const v = exver_1.ExtendedVersion.parse(version.options.version);
const vertex = graph.addVertex(v, [], []);
const flavor = v.flavor || '';
if (!flavorMap[flavor]) {
flavorMap[flavor] = [];
}
flavorMap[flavor].push([v, version, vertex]);
}
for (let flavor in flavorMap) {
flavorMap[flavor].sort((a, b) => a[0].compareForSort(b[0]));
let prev = undefined;
for (let [v, version, vertex] of flavorMap[flavor]) {
if (version.options.migrations.up !== VersionInfo_1.IMPOSSIBLE) {
let range;
if (prev) {
graph.addEdge(version.options.migrations.up, prev[2], vertex);
range = exver_1.VersionRange.anchor('>=', prev[0]).and(exver_1.VersionRange.anchor('<', v));
}
else {
range = exver_1.VersionRange.anchor('<', v);
}
const vRange = graph.addVertex(range, [], []);
graph.addEdge(version.options.migrations.up, vRange, vertex);
}
if (version.options.migrations.down !== VersionInfo_1.IMPOSSIBLE) {
let range;
if (prev) {
graph.addEdge(version.options.migrations.down, vertex, prev[2]);
range = exver_1.VersionRange.anchor('>=', prev[0]).and(exver_1.VersionRange.anchor('<', v));
}
else {
range = exver_1.VersionRange.anchor('<', v);
}
const vRange = graph.addVertex(range, [], []);
graph.addEdge(version.options.migrations.down, vertex, vRange);
}
if (version.options.migrations.other) {
for (let rangeStr in version.options.migrations.other) {
const range = exver_1.VersionRange.parse(rangeStr);
const vRange = graph.addVertex(range, [], []);
const migration = version.options.migrations.other[rangeStr];
if (migration.up)
graph.addEdge(migration.up, vRange, vertex);
if (migration.down)
graph.addEdge(migration.down, vertex, vRange);
for (let matching of graph.findVertex((v) => isExver(v.metadata) && v.metadata.satisfies(range))) {
if (migration.up)
graph.addEdge(migration.up, matching, vertex);
if (migration.down)
graph.addEdge(migration.down, vertex, matching);
}
}
}
prev = [v, version, vertex];
}
}
return graph;
});
}
/**
* 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(options) {
return new VersionGraph(options.current, options.other);
}
/**
* 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
*/
async migrate({ effects, from, to, }) {
if (overlaps(from, to))
return from;
const graph = this.graph();
if (from && to) {
const path = graph.shortestPath((v) => overlaps(v.metadata, from), (v) => overlaps(v.metadata, to));
if (path) {
console.log(`Migrating ${path.reduce(({ acc, prev }, x) => ({
acc: acc +
(prev && prev != x.from.metadata.toString()
? ` (as ${prev})`
: '') +
' -> ' +
x.to.metadata.toString(),
prev: x.to.metadata.toString(),
}), { acc: from.toString(), prev: null }).acc}`);
let dataVersion = from;
for (let edge of path) {
if (edge.metadata) {
await edge.metadata({ effects });
}
dataVersion = edge.to.metadata;
await setDataVersion(effects, edge.to.metadata);
}
return dataVersion;
}
}
throw new Error(`cannot migrate from ${from.toString()} to ${to.toString()}`);
}
/**
* 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
*/
async init(effects) {
const from = await getDataVersion(effects);
if (from) {
await this.migrate({
effects,
from,
to: this.currentVersion(),
});
}
else {
await effects.setDataVersion({ version: this.current.options.version });
}
}
/**
* 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
*/
async uninit(effects, target) {
if (target) {
if (isRange(target) && !target.satisfiable()) {
return;
}
const from = await getDataVersion(effects);
if (from) {
target = await this.migrate({
effects,
from,
to: target,
});
}
}
await setDataVersion(effects, target);
}
}
exports.VersionGraph = VersionGraph;
//# sourceMappingURL=VersionGraph.js.map
node_modules/@start9labs/start-sdk/package/lib/version/VersionGraph.js.map
Generated Vendored
+1
View File
File diff suppressed because one or more lines are too long
node_modules/@start9labs/start-sdk/package/lib/version/VersionInfo.d.ts
Generated Vendored
+71
View File
@@ -0,0 +1,71 @@
import { ValidateExVer } from '../../../base/lib/exver';
import * as T from '../../../base/lib/types';
/**
* Sentinel value indicating that a migration in a given direction is not possible.
* Use this for `migrations.up` or `migrations.down` to prevent migration.
*/
export declare const IMPOSSIBLE: unique symbol;
/**
* Configuration options for a single service version definition.
*
* @typeParam Version - The string literal exver version number
*/
export type VersionOptions<Version extends string> = {
/** The exver-compliant version number */
version: Version & ValidateExVer<Version>;
/** The release notes for this version */
releaseNotes: T.LocaleString;
/** Data migrations for this version */
migrations: {
/**
* A migration from the previous version. Leave empty to indicate no migration is necessary.
* Set to `IMPOSSIBLE` to indicate migrating from the previous version is not possible.
*/
up?: ((opts: {
effects: T.Effects;
}) => Promise<void>) | typeof IMPOSSIBLE;
/**
* A migration to the previous version. Leave blank to indicate no migration is necessary.
* Set to `IMPOSSIBLE` to indicate downgrades are prohibited
*/
down?: ((opts: {
effects: T.Effects;
}) => Promise<void>) | typeof IMPOSSIBLE;
/**
* Additional migrations, such as fast-forward migrations, or migrations from other flavors.
*/
other?: Record<string, {
up?: (opts: {
effects: T.Effects;
}) => Promise<void>;
down?: (opts: {
effects: T.Effects;
}) => Promise<void>;
}>;
};
};
/**
* Represents a single version of the service, including its release notes,
* migration scripts, and backwards-compatibility declarations.
*
* By convention, each version gets its own file (e.g. `versions/v1_0_0.ts`).
*
* @typeParam Version - The string literal exver version number
*/
export declare class VersionInfo<Version extends string> {
readonly options: VersionOptions<Version> & {
satisfies: string[];
};
private _version;
private constructor();
/**
* @description Use this function to define a new version of the service. By convention, each version should receive its own file.
* @property {string} version
* @property {string} releaseNotes
* @property {object} migrations
* @returns A VersionInfo class instance that is exported, then imported into versions/index.ts.
*/
static of<Version extends string>(options: VersionOptions<Version>): VersionInfo<Version>;
/** Specify a version that this version is 100% backwards compatible to */
satisfies<V extends string>(version: V & ValidateExVer<V>): VersionInfo<Version>;
}
node_modules/@start9labs/start-sdk/package/lib/version/VersionInfo.js
Generated Vendored
+67
View File
@@ -0,0 +1,67 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.VersionInfo = exports.IMPOSSIBLE = void 0;
/**
* Sentinel value indicating that a migration in a given direction is not possible.
* Use this for `migrations.up` or `migrations.down` to prevent migration.
*/
exports.IMPOSSIBLE = Symbol('IMPOSSIBLE');
/**
* Represents a single version of the service, including its release notes,
* migration scripts, and backwards-compatibility declarations.
*
* By convention, each version gets its own file (e.g. `versions/v1_0_0.ts`).
*
* @typeParam Version - The string literal exver version number
*/
class VersionInfo {
constructor(options) {
this.options = options;
this._version = null;
}
/**
* @description Use this function to define a new version of the service. By convention, each version should receive its own file.
* @property {string} version
* @property {string} releaseNotes
* @property {object} migrations
* @returns A VersionInfo class instance that is exported, then imported into versions/index.ts.
*/
static of(options) {
return new VersionInfo({ ...options, satisfies: [] });
}
/** Specify a version that this version is 100% backwards compatible to */
satisfies(version) {
return new VersionInfo({
...this.options,
satisfies: [...this.options.satisfies, version],
});
}
}
exports.VersionInfo = VersionInfo;
function __type_tests() {
const version = VersionInfo.of({
version: '1.0.0:0',
releaseNotes: '',
migrations: {},
})
.satisfies('#other:1.0.0:0')
.satisfies('#other:2.0.0:0')
// @ts-expect-error
.satisfies('#other:2.f.0:0');
let a = version;
// @ts-expect-error
let b = version;
VersionInfo.of({
// @ts-expect-error
version: 'test',
releaseNotes: '',
migrations: {},
});
VersionInfo.of({
// @ts-expect-error
version: 'test',
releaseNotes: '',
migrations: {},
});
}
//# sourceMappingURL=VersionInfo.js.map
node_modules/@start9labs/start-sdk/package/lib/version/VersionInfo.js.map
Generated Vendored
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"VersionInfo.js","sourceRoot":"","sources":["../../../../package/lib/version/VersionInfo.ts"],"names":[],"mappings":";;;AAGA;;;GAGG;AACU,QAAA,UAAU,GAAkB,MAAM,CAAC,YAAY,CAAC,CAAA;AAqC7D;;;;;;;GAOG;AACH,MAAa,WAAW;IAEtB,YACW,OAA0D;QAA1D,YAAO,GAAP,OAAO,CAAmD;QAF7D,aAAQ,GAAmB,IAAI,CAAA;IAGpC,CAAC;IACJ;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAyB,OAAgC;QAChE,OAAO,IAAI,WAAW,CAAU,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAA;IAChE,CAAC;IACD,0EAA0E;IAC1E,SAAS,CACP,OAA6B;QAE7B,OAAO,IAAI,WAAW,CAAC;YACrB,GAAG,IAAI,CAAC,OAAO;YACf,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC;SAChD,CAAC,CAAA;IACJ,CAAC;CACF;AAxBD,kCAwBC;AAED,SAAS,YAAY;IACnB,MAAM,OAAO,GAA2B,WAAW,CAAC,EAAE,CAAC;QACrD,OAAO,EAAE,SAAS;QAClB,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,EAAE;KACf,CAAC;SACC,SAAS,CAAC,gBAAgB,CAAC;SAC3B,SAAS,CAAC,gBAAgB,CAAC;QAC5B,mBAAmB;SAClB,SAAS,CAAC,gBAAgB,CAAC,CAAA;IAE9B,IAAI,CAAC,GAA2B,OAAO,CAAA;IACvC,mBAAmB;IACnB,IAAI,CAAC,GAA2B,OAAO,CAAA;IAEvC,WAAW,CAAC,EAAE,CAAC;QACb,mBAAmB;QACnB,OAAO,EAAE,MAAM;QACf,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,EAAE;KACf,CAAC,CAAA;IACF,WAAW,CAAC,EAAE,CAAC;QACb,mBAAmB;QACnB,OAAO,EAAE,MAAgB;QACzB,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,EAAE;KACf,CAAC,CAAA;AACJ,CAAC"}
node_modules/@start9labs/start-sdk/package/lib/version/index.d.ts
Generated Vendored
+2
View File
@@ -0,0 +1,2 @@
export * from './VersionGraph';
export * from './VersionInfo';
node_modules/@start9labs/start-sdk/package/lib/version/index.js
Generated Vendored
+19
View File
@@ -0,0 +1,19 @@
"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __exportStar = (this && this.__exportStar) || function(m, exports) {
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
};
Object.defineProperty(exports, "__esModule", { value: true });
__exportStar(require("./VersionGraph"), exports);
__exportStar(require("./VersionInfo"), exports);
//# sourceMappingURL=index.js.map
node_modules/@start9labs/start-sdk/package/lib/version/index.js.map
Generated Vendored
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../package/lib/version/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA8B;AAC9B,gDAA6B"}