@eldrin-project/eldrin-app-core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,485 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Core types for @eldrin-project/eldrin-app-core
+ */
+/**
+ * Migration file representation
+ */
+interface MigrationFile {
+    /** Full filename including timestamp and description (e.g., "20250115120000-create-invoices.sql") */
+    name: string;
+    /** Raw SQL content of the migration file */
+    content: string;
+}
+/**
+ * Record of an executed migration stored in _eldrin_migrations table
+ */
+interface MigrationRecord {
+    id: number;
+    filename: string;
+    checksum: string;
+    executed_at: number;
+    execution_time_ms: number | null;
+}
+/**
+ * Result of running migrations
+ */
+interface MigrationResult {
+    /** Whether all migrations succeeded */
+    success: boolean;
+    /** Number of migrations that were executed */
+    executed: number;
+    /** Details about executed migrations */
+    migrations: Array<{
+        name: string;
+        executionTimeMs: number;
+    }>;
+    /** Error if migration failed */
+    error?: {
+        migration: string;
+        message: string;
+        sql?: string;
+    };
+}
+/**
+ * Migration runner options
+ */
+interface MigrationOptions {
+    /** Directory containing migration files (for CLI/build-time) */
+    migrationsDir?: string;
+    /** Pre-loaded migration files (for Workers runtime) */
+    migrations?: MigrationFile[];
+    /** Skip checksum verification (development only) */
+    skipChecksumVerification?: boolean;
+    /** Callback for logging */
+    onLog?: (message: string, level: 'info' | 'warn' | 'error') => void;
+}
+/**
+ * App configuration from eldrin-app.manifest.json
+ */
+interface AppManifest {
+    name: string;
+    version: string;
+    displayName?: string;
+    description?: string;
+    permissions?: string[];
+    hooks?: Record<string, string>;
+    events?: {
+        emits?: string[];
+        subscribes?: string[];
+    };
+}
+/**
+ * Options for createApp factory
+ */
+interface CreateAppOptions {
+    /** Unique app identifier */
+    name: string;
+    /** Root React component */
+    root: React.ComponentType<unknown>;
+    /** App manifest (optional, can be loaded from file) */
+    manifest?: AppManifest;
+    /** Migration files (loaded at build time via Vite plugin) */
+    migrations?: MigrationFile[];
+    /** Called when migrations complete successfully */
+    onMigrationsComplete?: (result: MigrationResult) => void;
+    /** Called when migrations fail */
+    onMigrationError?: (error: Error) => void;
+}
+/**
+ * Database context passed to app components
+ */
+interface DatabaseContext {
+    /** D1 database instance (null if app has no database) */
+    db: D1Database | null;
+    /** Whether migrations have completed */
+    migrationsComplete: boolean;
+    /** Migration result (if migrations were run) */
+    migrationResult?: MigrationResult;
+}
+/**
+ * Eldrin context provided to apps
+ */
+interface EldrinContext {
+    /** App ID */
+    appId: string;
+    /** Database context */
+    database: DatabaseContext;
+    /** Environment variables */
+    env: Record<string, string>;
+}
+
+/**
+ * App factory for creating Eldrin apps
+ *
+ * Returns single-spa compatible lifecycle functions with:
+ * - Automatic migration execution on bootstrap
+ * - Database provider wrapping
+ * - Error boundary integration
+ */
+
+/**
+ * Single-spa lifecycle props passed to lifecycle functions
+ */
+interface LifecycleProps {
+    /** DOM element to mount the app into */
+    domElement?: HTMLElement;
+    /** App name */
+    name?: string;
+    /** D1 Database instance (provided by shell) */
+    db?: D1Database;
+    /** Custom props from shell */
+    customProps?: Record<string, unknown>;
+}
+/**
+ * Single-spa compatible lifecycle object
+ */
+interface AppLifecycle {
+    bootstrap: (props: LifecycleProps) => Promise<void>;
+    mount: (props: LifecycleProps) => Promise<void>;
+    unmount: (props: LifecycleProps) => Promise<void>;
+}
+/**
+ * Create an Eldrin app with single-spa compatible lifecycle
+ *
+ * @param options - App configuration
+ * @returns Object with bootstrap, mount, and unmount lifecycle functions
+ *
+ * @example
+ * ```tsx
+ * // src/index.tsx
+ * import { createApp } from '@eldrin-project/eldrin-app-core';
+ * import App from './App';
+ *
+ * export const { bootstrap, mount, unmount } = createApp({
+ *   name: 'invoicing',
+ *   root: App,
+ *   // Migrations loaded via Vite plugin
+ * });
+ * ```
+ */
+declare function createApp(options: CreateAppOptions): AppLifecycle;
+/**
+ * Type helper for migration files loaded via Vite plugin
+ *
+ * @example
+ * ```tsx
+ * // With Vite plugin
+ * import { createApp, type MigrationFiles } from '@eldrin-project/eldrin-app-core';
+ * import migrations from 'virtual:eldrin/migrations';
+ *
+ * export const { bootstrap, mount, unmount } = createApp({
+ *   name: 'invoicing',
+ *   root: App,
+ *   migrations: migrations as MigrationFiles,
+ * });
+ * ```
+ */
+type MigrationFiles = MigrationFile[];
+
+/**
+ * Props for DatabaseProvider
+ */
+interface DatabaseProviderProps {
+    /** D1 database instance (null if app has no database) */
+    db: D1Database | null;
+    /** Whether migrations have completed */
+    migrationsComplete: boolean;
+    /** Migration result */
+    migrationResult?: MigrationResult;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * Provider component for database context
+ */
+declare function DatabaseProvider({ db, migrationsComplete, migrationResult, children, }: DatabaseProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the app's D1 database
+ *
+ * @returns D1Database instance or null if app has no database
+ * @throws Error if used outside of DatabaseProvider
+ *
+ * @example
+ * ```tsx
+ * function InvoiceList() {
+ *   const db = useDatabase();
+ *
+ *   if (!db) {
+ *     return <div>No database configured</div>;
+ *   }
+ *
+ *   const { results } = await db.prepare(
+ *     'SELECT * FROM invoices ORDER BY created_at DESC'
+ *   ).all();
+ *
+ *   return <div>{results.map(invoice => ...)}</div>;
+ * }
+ * ```
+ */
+declare function useDatabase(): D1Database | null;
+/**
+ * Hook to access full database context including migration status
+ *
+ * @returns DatabaseContext object
+ * @throws Error if used outside of DatabaseProvider
+ */
+declare function useDatabaseContext(): DatabaseContext;
+/**
+ * Hook to check if migrations have completed
+ *
+ * Useful for showing loading states while migrations run
+ *
+ * @returns true if migrations are complete
+ */
+declare function useMigrationsComplete(): boolean;
+
+/**
+ * Migration runner for Eldrin apps
+ *
+ * Executes SQL migrations against a D1 database with:
+ * - Automatic tracking table creation
+ * - Checksum verification for integrity
+ * - Sequential execution (one migration at a time)
+ * - Transaction-based execution per migration
+ */
+
+/**
+ * Run pending migrations against the database
+ *
+ * @param db - D1 Database instance
+ * @param options - Migration options
+ * @returns Result of migration execution
+ */
+declare function runMigrations(db: D1Database, options?: MigrationOptions): Promise<MigrationResult>;
+/**
+ * Get migration status (pending and executed migrations)
+ *
+ * @param db - D1 Database instance
+ * @param migrations - Available migration files
+ * @returns Status information
+ */
+declare function getMigrationStatus(db: D1Database, migrations: MigrationFile[]): Promise<{
+    pending: string[];
+    executed: MigrationRecord[];
+    orphaned: string[];
+    checksumMismatches: string[];
+}>;
+
+/**
+ * Migration rollback functionality
+ *
+ * Rolls back migrations using .rollback.sql files in reverse order
+ */
+
+/**
+ * Result of a rollback operation
+ */
+interface RollbackResult {
+    success: boolean;
+    rolledBack: string[];
+    error?: {
+        migration: string;
+        message: string;
+    };
+}
+/**
+ * Rollback migrations to a specific target (or just the last one)
+ *
+ * @param db - D1 Database instance
+ * @param options - Rollback options
+ * @returns Result of rollback operation
+ */
+declare function rollbackMigrations(db: D1Database, options: {
+    /** Rollback files (.rollback.sql) */
+    rollbackFiles: MigrationFile[];
+    /** Target migration to rollback TO (exclusive - this migration stays) */
+    targetMigration?: string;
+    /** Callback for logging */
+    onLog?: (message: string, level: 'info' | 'warn' | 'error') => void;
+}): Promise<RollbackResult>;
+
+/**
+ * Checksum utilities for migration integrity verification
+ *
+ * Uses SHA-256 for content hashing via Web Crypto API
+ * (compatible with Cloudflare Workers runtime)
+ */
+/** Prefix for SHA-256 checksums in marketplace format */
+declare const CHECKSUM_PREFIX = "sha256:";
+/**
+ * Calculate SHA-256 checksum of content
+ *
+ * @param content - String content to hash
+ * @param options - Options for checksum calculation
+ * @param options.prefixed - If true, returns "sha256:..." format (default: false for backwards compatibility)
+ * @returns Hex-encoded SHA-256 hash, optionally with prefix
+ */
+declare function calculateChecksum(content: string, options?: {
+    prefixed?: boolean;
+}): Promise<string>;
+/**
+ * Calculate SHA-256 checksum with sha256: prefix
+ *
+ * Convenience function for marketplace format
+ *
+ * @param content - String content to hash
+ * @returns Prefixed checksum (e.g., "sha256:abc123...")
+ */
+declare function calculatePrefixedChecksum(content: string): Promise<string>;
+/**
+ * Verify that content matches an expected checksum
+ *
+ * Handles both prefixed ("sha256:...") and unprefixed checksums
+ *
+ * @param content - Content to verify
+ * @param expectedChecksum - Expected SHA-256 hex string (with or without prefix)
+ * @returns true if checksums match
+ */
+declare function verifyChecksum(content: string, expectedChecksum: string): Promise<boolean>;
+
+/**
+ * SQL statement parser for migration files
+ *
+ * Parses SQL content into individual statements for execution via db.batch()
+ */
+/**
+ * Parse SQL content into individual statements
+ *
+ * - Removes SQL comments (-- style)
+ * - Splits by semicolon
+ * - Handles multi-line statements
+ * - Preserves string literals containing semicolons
+ *
+ * @param sql - Raw SQL content
+ * @returns Array of individual SQL statements
+ */
+declare function parseSQLStatements(sql: string): string[];
+/**
+ * Validate that a filename follows the migration naming convention
+ *
+ * Expected format: TIMESTAMP-description.sql
+ * - TIMESTAMP: 14 digits (YYYYMMDDHHmmss)
+ * - description: kebab-case
+ *
+ * @param filename - Filename to validate
+ * @returns true if valid, false otherwise
+ */
+declare function isValidMigrationFilename(filename: string): boolean;
+/**
+ * Validate that a filename follows the rollback naming convention
+ *
+ * Expected format: TIMESTAMP-description.rollback.sql
+ *
+ * @param filename - Filename to validate
+ * @returns true if valid rollback file, false otherwise
+ */
+declare function isValidRollbackFilename(filename: string): boolean;
+/**
+ * Extract timestamp from migration filename
+ *
+ * @param filename - Migration filename
+ * @returns Timestamp string or null if invalid
+ */
+declare function extractTimestamp(filename: string): string | null;
+/**
+ * Get the rollback filename for a migration
+ *
+ * @param migrationFilename - Migration filename (e.g., "20250115120000-create-table.sql")
+ * @returns Rollback filename (e.g., "20250115120000-create-table.rollback.sql")
+ */
+declare function getRollbackFilename(migrationFilename: string): string;
+
+/**
+ * Marketplace utilities for migration packaging
+ *
+ * Provides tools to generate migration manifests for marketplace distribution.
+ * This is used at build time to prepare apps for submission.
+ */
+
+/**
+ * Migration entry in the marketplace manifest
+ */
+interface MigrationManifestEntry {
+    /** Migration ID (timestamp) */
+    id: string;
+    /** Full filename */
+    file: string;
+    /** SHA-256 checksum with prefix */
+    checksum: string;
+}
+/**
+ * Marketplace migration manifest format
+ */
+interface MigrationManifest {
+    /** Logical database name (used for table prefixing) */
+    database: string;
+    /** List of migrations in order */
+    migrations: MigrationManifestEntry[];
+}
+/**
+ * Options for generating migration manifest
+ */
+interface GenerateMigrationManifestOptions {
+    /** Directory containing migration SQL files */
+    migrationsDir: string;
+    /** Logical database name for the app */
+    database: string;
+}
+/**
+ * Result of migration manifest generation
+ */
+interface GenerateMigrationManifestResult {
+    /** The generated manifest */
+    manifest: MigrationManifest;
+    /** Migration files with content (for copying to output) */
+    files: MigrationFile[];
+}
+/**
+ * Generate a marketplace migration manifest from migration files
+ *
+ * Reads migration files from the specified directory and generates
+ * a manifest with checksums suitable for marketplace distribution.
+ *
+ * @param options - Generation options
+ * @returns Manifest and file contents
+ *
+ * @example
+ * ```typescript
+ * import { generateMigrationManifest } from '@eldrin-project/eldrin-app-core';
+ *
+ * const result = await generateMigrationManifest({
+ *   migrationsDir: './migrations',
+ *   database: 'invoicing',
+ * });
+ *
+ * // Write manifest to output directory
+ * await writeFile(
+ *   'dist/migrations/index.json',
+ *   JSON.stringify(result.manifest, null, 2)
+ * );
+ *
+ * // Copy migration files
+ * for (const file of result.files) {
+ *   await writeFile(`dist/migrations/${file.name}`, file.content);
+ * }
+ * ```
+ */
+declare function generateMigrationManifest(options: GenerateMigrationManifestOptions): Promise<GenerateMigrationManifestResult>;
+/**
+ * Validate a migration manifest against actual files
+ *
+ * Useful for CI/CD validation in the marketplace-dist repository.
+ *
+ * @param manifest - The manifest to validate
+ * @param files - The actual migration files
+ * @returns Validation result with any errors
+ */
+declare function validateMigrationManifest(manifest: MigrationManifest, files: MigrationFile[]): Promise<{
+    valid: boolean;
+    errors: string[];
+}>;
+
+export { type AppLifecycle, type AppManifest, CHECKSUM_PREFIX, type CreateAppOptions, type DatabaseContext, DatabaseProvider, type DatabaseProviderProps, type EldrinContext, type GenerateMigrationManifestOptions, type GenerateMigrationManifestResult, type LifecycleProps, type MigrationFile, type MigrationFiles, type MigrationManifest, type MigrationManifestEntry, type MigrationOptions, type MigrationRecord, type MigrationResult, type RollbackResult, calculateChecksum, calculatePrefixedChecksum, createApp, extractTimestamp, generateMigrationManifest, getMigrationStatus, getRollbackFilename, isValidMigrationFilename, isValidRollbackFilename, parseSQLStatements, rollbackMigrations, runMigrations, useDatabase, useDatabaseContext, useMigrationsComplete, validateMigrationManifest, verifyChecksum };