Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import { type SetupMarker, type SetupTargetScreen } from "@triliumnext/commons";
/**
* Setup asked for by an instance that already has a database.
*
* An instance normally reaches the setup screen because there is nothing to open. Some things the
* user can ask for, restoring a backup among them, need the same screen and the same closed
* database, so a running instance writes a `setup.json` marker and restarts. The start that follows
* reads it, hands it to this module, and from then on the instance answers "not initialized" to
* everything that asks: the database is never migrated, becca is never loaded, the desktop opens its
* setup window, and every guard that exists to protect an uninitialized instance keeps working
* unchanged.
*
* The state lives for the process, not for the file, which is read once and deleted. A page reloaded
* halfway through the wizard therefore comes back to the same screen, while a genuine restart comes
* back to the app.
*
* @module
*/
/** The screens a marker is allowed to name, which is not every screen the wizard has. */
const TARGET_SCREENS: readonly SetupTargetScreen[] = [ "restore-backup", "backup-database" ];
let requested: SetupMarker | null = null;
let dataDiscarded = false;
/**
* Puts the instance into setup for the rest of this process.
*
* Called by the platform at start, before the database is opened, with whatever its marker file
* held. A `null` marker is the ordinary case and leaves everything alone.
*/
export function enterSetupMode(marker: SetupMarker | null): void {
requested = marker;
dataDiscarded = false;
}
/**
* Takes the instance back out, which is what bringing a database up means.
*
* Called by every path that opens one: finishing a restore, creating a document, converging a sync.
* Until it is called, {@link isSetupRequested} keeps the instance answering as uninitialized, and
* the database that was just opened would go unnoticed.
*/
export function leaveSetupMode(): void {
requested = null;
dataDiscarded = false;
}
/**
* Whether the knowledge base the wizard was booted away from is still there.
*
* Not the same question as {@link isInitialSetup}, which answers for how the wizard was reached and
* never changes. This one stops being true the moment the user picks a path that replaces the
* database, which is the point everything offering to back it up, or to go back to it, has to stop.
*/
export function hasExistingData(): boolean {
return requested !== null && !dataDiscarded;
}
/** Records that it is gone. Nothing takes this back: the file it refers to no longer exists. */
export function markExistingDataDiscarded(): void {
dataDiscarded = true;
}
/** Whether this instance was asked to be in setup rather than being there for want of a database. */
export function isSetupRequested(): boolean {
return requested !== null;
}
/**
* Whether the setup screen is the instance's first run.
*
* `false` says there is a database behind the wizard, which is what lets a screen offer to leave
* without doing anything: the instance has somewhere to go back to.
*/
export function isInitialSetup(): boolean {
return requested === null;
}
/** The screen the marker asked for, if it asked for one. */
export function getSetupTargetScreen(): SetupTargetScreen | undefined {
return requested?.targetScreen;
}
/** The language the marker carried, which is the instance's own, from before the database closed. */
export function getSetupLanguage(): string | undefined {
return requested?.lang;
}
/**
* Reads a marker's contents, or answers `null` for anything that is not one.
*
* The file is written by this application and read by the next start of it, but it is also a plain
* file in the data directory that anything could have left behind, and it is read at the one moment
* when a bad answer sends the instance somewhere the user did not ask to go. So it is parsed
* defensively: unknown screens are dropped rather than carried, and a marker without a language is
* not a marker.
*/
export function parseSetupMarker(raw: string): SetupMarker | null {
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return null;
}
if (typeof parsed !== "object" || parsed === null) {
return null;
}
const { lang, targetScreen } = parsed as Record<string, unknown>;
if (typeof lang !== "string" || !lang) {
return null;
}
const screen = asSetupTargetScreen(targetScreen);
return {
lang,
...(screen ? { targetScreen: screen } : {})
};
}
/**
* Narrows a value to a screen the wizard may be sent to, or to nothing.
*
* The list is deliberately not every state the wizard has: two of them create a document the moment
* they are shown, and nothing outside the wizard should be able to name those.
*/
export function asSetupTargetScreen(value: unknown): SetupTargetScreen | undefined {
return TARGET_SCREENS.find((screen) => screen === value);
}
/**
* What setup needs of the platform it is running on.
*
* The marker and the database both live somewhere only the platform knows: a data directory on a
* disk, or the origin's private filesystem in a browser. Reading the marker is the platform's own
* business and happens before any of this exists, so only what a shared route has to reach is here.
*/
export interface SetupPlatform {
/** Leaves the marker that makes the next start the wizard. */
writeMarker(marker: SetupMarker): Promise<void>;
/**
* Whether one is lying there waiting to be read.
*
* Asked by an instance that cannot restart itself, where the marker outlives the page that
* wrote it: a server is restarted by hand, possibly days later, and until then this is the only
* thing that can tell the owner a start-over is pending, or let them call it off.
*/
hasMarker(): Promise<boolean>;
/** Takes it back, for a request that was made and then abandoned. */
removeMarker(): Promise<void>;
/**
* Erases the database this instance was booted away from, and only that: backups, configuration
* and the stored passphrase are what a user who deletes by mistake has left, and they stay.
*/
removeDatabase(): Promise<void>;
}
let platform: SetupPlatform | null = null;
export function initSetupPlatform(instance: SetupPlatform): void {
platform = instance;
}
export function getSetupPlatform(): SetupPlatform {
if (!platform) {
throw new Error("Setup platform not initialized.");
}
return platform;
}