@t1mmen/srtd
Version:
Supabase Repeatable Template Definitions (srtd): 🪄 Live-reloading SQL templates for Supabase DX. Make your database changes reviewable and migrations maintainable! 🚀
205 lines (204 loc) • 6.01 kB
TypeScript
/**
* StateService - Centralized state management for template status
* Single source of truth for all template states and transitions
*/
import { EventEmitter } from 'node:events';
import type { BuildLog, TemplateBuildState } from '../types.js';
import { type ValidationWarning } from '../utils/schemas.js';
/**
* Template states in the state machine
*/
export declare enum TemplateState {
UNSEEN = "unseen",
SYNCED = "synced",
CHANGED = "changed",
APPLIED = "applied",
BUILT = "built",
ERROR = "error"
}
/**
* Template state information
*/
export interface TemplateStateInfo {
state: TemplateState;
templatePath: string;
currentHash?: string;
lastAppliedHash?: string;
lastBuiltHash?: string;
lastAppliedDate?: string;
lastBuiltDate?: string;
lastError?: string;
metadata?: TemplateBuildState;
}
/**
* State transition event
*/
export interface StateTransitionEvent {
templatePath: string;
fromState: TemplateState;
toState: TemplateState;
timestamp: string;
}
/**
* Configuration for StateService
*/
export interface StateServiceConfig {
baseDir: string;
buildLogPath?: string;
localBuildLogPath?: string;
autoSave?: boolean;
}
export declare class StateService extends EventEmitter {
private config;
private templateStates;
private buildLog;
private localBuildLog;
private saveTimer;
private validationWarnings;
constructor(config: StateServiceConfig);
/**
* Initialize the service by loading existing build logs
*/
initialize(): Promise<void>;
/**
* Create an empty build log
*/
private createEmptyBuildLog;
/**
* Load build logs from disk
*/
private loadBuildLogs;
/**
* Save build logs to disk
*/
saveBuildLogs(): Promise<void>;
/**
* Schedule auto-save if enabled
*/
private scheduleAutoSave;
/**
* Sync build log states to in-memory map
*/
private syncStatesToMemory;
/**
* Determine template state from metadata
*/
private determineStateFromMetadata;
/**
* Validate if a state transition is allowed
*/
private validateTransition;
/**
* Perform a state transition
*/
private transitionState;
/**
* Get the current state of a template
*/
getTemplateStatus(templatePath: string): TemplateStateInfo | undefined;
/**
* Get all template statuses
*/
getAllTemplateStatuses(): Map<string, TemplateStateInfo>;
/**
* Get validation warnings from initialization
* Returns any warnings about corrupted or invalid build log files
*/
getValidationWarnings(): ValidationWarning[];
/**
* Get recently applied templates sorted by date (most recent first)
* Returns templates from local build log that have lastAppliedDate
*/
getRecentlyApplied(limit?: number): Array<{
template: string;
appliedDate: string;
}>;
/**
* Get recent activity for watch mode history display.
* Returns the most recent builds and applies sorted by date.
*/
getRecentActivity(limit?: number): Array<{
template: string;
action: 'built' | 'applied';
timestamp: Date;
target?: string;
}>;
/**
* Get template info including migration file and last date
* Used for displaying arrow format: template.sql → migration_file.sql
* Accepts either a full path, relative path, or just the template name
*/
getTemplateInfo(templatePath: string): {
template: string;
migrationFile?: string;
lastDate?: string;
};
/**
* Check if template has changed based on hash comparison
*/
hasTemplateChanged(templatePath: string, currentHash: string): boolean;
/**
* Mark template as unseen (new template)
*/
markAsUnseen(templatePath: string, currentHash?: string): Promise<void>;
/**
* Mark template as synced
*/
markAsSynced(templatePath: string, currentHash: string): Promise<void>;
/**
* Mark template as changed
*/
markAsChanged(templatePath: string, currentHash: string): Promise<void>;
/**
* Mark template as applied
*/
markAsApplied(templatePath: string, hash: string): Promise<void>;
/**
* Mark template as built
*/
markAsBuilt(templatePath: string, hash: string, migrationFile?: string): Promise<void>;
/**
* Mark template as having an error
*/
markAsError(templatePath: string, error: string, type?: 'apply' | 'build'): Promise<void>;
/**
* Clear all states (reset)
*/
clearAllStates(): Promise<void>;
/**
* Clear build logs selectively
* @param type - 'local' clears local only, 'shared' clears shared only, 'both' clears all
*/
clearBuildLogs(type: 'local' | 'shared' | 'both'): Promise<void>;
/**
* Update template timestamp
*/
updateTimestamp(timestamp: string): void;
/**
* Get the last timestamp for generating migration filenames
*/
getLastTimestamp(): string;
/**
* Get combined build state for a template (merges common and local logs)
* @see Orchestrator.getTemplateStatus - primary consumer
*/
getTemplateBuildState(templatePath: string): TemplateBuildState | undefined;
/**
* Get build log reference for MigrationBuilder (read-only access)
* @see MigrationBuilder.generateAndWriteBundledMigration
*/
getBuildLogForMigration(): Readonly<BuildLog>;
/**
* Rename template entry in build logs (used when promoting WIP templates)
* Moves the build state from old path to new path in both common and local logs
*/
renameTemplate(oldPath: string, newPath: string): Promise<void>;
/**
* Convert template path to relative path for build log keys
*/
private toRelativePath;
/**
* Dispose of the service
*/
dispose(): Promise<void>;
}