@better-media/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,779 @@
+import { z } from 'zod';
+
+type WhereClause = {
+    field: string;
+    value: unknown;
+    operator?: "=" | "!=" | "<" | "<=" | ">" | ">=" | "like" | "in" | "not_in" | "contains" | "starts_with" | "ends_with";
+    connector?: "AND" | "OR";
+}[];
+interface CreateOptions<T = Record<string, unknown>> {
+    /** Table / collection name */
+    model: string;
+    /** Data to insert */
+    data: T;
+}
+interface FindOptions<T = Record<string, unknown>> {
+    /** Table / collection name */
+    model: string;
+    /** Filter conditions – combined with AND by default */
+    where?: WhereClause;
+    /** Fields to return; omit to return all */
+    select?: (keyof T & string)[];
+    /** Sort order */
+    sortBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    };
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip */
+    offset?: number;
+    /** Include soft-deleted records if true */
+    withDeleted?: boolean;
+    /** Relationships to populate (join/fetch) */
+    populate?: string[];
+}
+interface UpdateOptions<T = Record<string, unknown>> {
+    /** Table / collection name */
+    model: string;
+    /** Filter conditions that identify the record(s) to update */
+    where: WhereClause;
+    /** Partial data to merge into the matched record(s) */
+    update: Partial<T>;
+}
+interface DeleteOptions {
+    /** Table / collection name */
+    model: string;
+    /** Filter conditions that identify the record(s) to delete */
+    where: WhereClause;
+}
+interface CountOptions {
+    /** Table / collection name */
+    model: string;
+    /** Filter conditions */
+    where?: WhereClause;
+}
+/**
+ * Adapter specifically for transaction contexts, omitting the ability to nest transactions.
+ */
+type DatabaseTransactionAdapter = Omit<DatabaseAdapter, "transaction">;
+/**
+ * Engine-agnostic database adapter interface.
+ */
+interface DatabaseAdapter {
+    /**
+     * Insert a new record and return the persisted result (including any
+     * server-side defaults such as `id`, `createdAt`, etc.).
+     */
+    create<T extends Record<string, unknown> = Record<string, unknown>>(options: CreateOptions<T>): Promise<T>;
+    /**
+     * Return the first record matching `where`, or `null` if no match.
+     */
+    findOne<T extends Record<string, unknown> = Record<string, unknown>>(options: FindOptions<T>): Promise<T | null>;
+    /**
+     * Return all records matching `where`. Returns an empty array when there
+     * are no matches.
+     */
+    findMany<T extends Record<string, unknown> = Record<string, unknown>>(options: FindOptions<T>): Promise<T[]>;
+    /**
+     * Apply a partial update to all records matching `where` and return the
+     * first updated record, or `null` if no match was found.
+     */
+    update<T extends Record<string, unknown> = Record<string, unknown>>(options: UpdateOptions<T>): Promise<T | null>;
+    /**
+     * Apply a partial update to all records matching `where` and return the
+     * number of updated records.
+     */
+    updateMany<T extends Record<string, unknown> = Record<string, unknown>>(options: UpdateOptions<T>): Promise<number>;
+    /**
+     * Delete all records matching `where`.
+     */
+    delete(options: DeleteOptions): Promise<void>;
+    /**
+     * Delete all records matching `where` and return the number of deleted records.
+     */
+    deleteMany(options: DeleteOptions): Promise<number>;
+    /**
+     * Return the number of records matching `where`.
+     */
+    count(options: CountOptions): Promise<number>;
+    /**
+     * Execute a raw query. USE WITH CAUTION.
+     * This breaks engine-agnosticism.
+     */
+    raw<T = unknown>(query: string, params?: unknown[]): Promise<T>;
+    /**
+     * Execute multiple operations within an atomic transaction.
+     */
+    transaction<R>(callback: (trx: DatabaseTransactionAdapter) => Promise<R>): Promise<R>;
+}
+
+/**
+ * Job adapter interface for background execution.
+ * Implementations: in-memory (default), Redis, RabbitMQ, Kafka, etc.
+ */
+interface JobAdapter {
+    /** Enqueue a job for background execution */
+    enqueue(name: string, payload: Record<string, unknown>): Promise<void>;
+}
+
+/** Options for generating a URL to access stored media */
+interface GetUrlOptions {
+    /** Expiration time in seconds (for signed URLs). Default depends on adapter. */
+    expiresIn?: number;
+}
+/** HTTP method to use for a presigned upload */
+type PresignedUploadMethod = "PUT" | "POST";
+/**
+ * Options for creating a presigned upload (PUT or POST).
+ * Both methods apply validation as strictly as the S3 protocol allows.
+ */
+interface PresignedUploadOptions {
+    /**
+     * Upload method.
+     * - PUT: binary body, signed headers enforce Content-Type + Content-Length.
+     * - POST: multipart/form-data with an S3 Policy enforcing size range and Content-Type.
+     * Default: "PUT"
+     */
+    method?: PresignedUploadMethod;
+    /** Required MIME type (e.g. "image/jpeg"). Enforced strictly for both methods. */
+    contentType: string;
+    /** Expiration in seconds. Default: 3600 */
+    expiresIn?: number;
+    /**
+     * Maximum allowed file size in bytes.
+     * - POST: enforced by S3 Policy (`content-length-range`). S3 rejects uploads exceeding this.
+     * - PUT: encoded as `Content-Length` in the signed command. S3 rejects body size mismatches.
+     *   For the tightest constraint on PUT, pass the exact expected file size here.
+     */
+    maxSizeBytes?: number;
+    /**
+     * Minimum allowed file size in bytes.
+     * - POST: enforced by S3 Policy (`content-length-range`). Default: 1.
+     * - PUT: not constrainable at the S3 level.
+     */
+    minSizeBytes?: number;
+    /**
+     * Additional user-defined metadata to attach to the object (stored as x-amz-meta-* on S3).
+     * These are signed into the URL/Policy, so any metadata mismatch causes a 403.
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * Unified presigned upload result — same shape for both PUT and POST.
+ *
+ * @example PUT usage (mobile app / API client):
+ * ```ts
+ * fetch(result.url, {
+ *   method: "PUT",
+ *   headers: result.headers,
+ *   body: fileBlob,
+ * });
+ * ```
+ *
+ * @example POST usage (browser form / web app):
+ * ```ts
+ * const form = new FormData();
+ * for (const [key, value] of Object.entries(result.fields ?? {})) {
+ *   form.append(key, value);
+ * }
+ * form.append("file", fileBlob); // file field MUST be last
+ * fetch(result.url, { method: "POST", body: form });
+ * ```
+ */
+interface PresignedUploadResult {
+    method: PresignedUploadMethod;
+    /** The URL to upload to. For POST this is the bucket endpoint; for PUT it is the fully signed URL. */
+    url: string;
+    /**
+     * Required form fields (POST only).
+     * Must be appended to the multipart/form-data body BEFORE the file field, in the order provided.
+     */
+    fields?: Record<string, string>;
+    /**
+     * Required HTTP headers (PUT only).
+     * The client MUST send all of these headers exactly as specified.
+     * Mismatch causes S3 to return 403 Forbidden.
+     */
+    headers?: Record<string, string>;
+}
+interface StorageAdapter {
+    get(key: string): Promise<Buffer | null>;
+    put(key: string, value: Buffer): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists without loading the full content.
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Optional: get file size in bytes without loading the full buffer.
+     * Used with fileHandling.maxBufferBytes to decide buffer vs stream.
+     */
+    getSize?(key: string): Promise<number | null>;
+    /**
+     * Optional: stream file contents. Used when file exceeds maxBufferBytes.
+     */
+    getStream?(key: string): Promise<ReadableStream | null>;
+    /**
+     * Generate a signed or public URL to access the file.
+     * Optional: S3/GCS adapters implement this; memory adapter does not.
+     */
+    getUrl?(key: string, options?: GetUrlOptions): Promise<string>;
+    /**
+     * Create a presigned upload for direct-to-storage upload.
+     * Supports both PUT (binary body) and POST (multipart form) with strict validation.
+     * Optional: S3/GCS adapters implement this; memory adapter does not.
+     */
+    createPresignedUpload?(key: string, options: PresignedUploadOptions): Promise<PresignedUploadResult>;
+    /**
+     * Remove all stored keys. Optional; mainly for testing/dev (e.g. memory adapter).
+     */
+    clear?(): Promise<void>;
+}
+
+/** Core file information. Populated by upload adapter / upload:init. */
+interface FileInfo {
+    /** Logical key in storage. Always present. */
+    key: string;
+    /** File size in bytes */
+    size?: number;
+    /** MIME type (e.g. "image/jpeg"). Use this instead of contentType/mimeType. */
+    mimeType?: string;
+    /** Original filename from upload (e.g. "photo.jpg") */
+    originalName?: string;
+    /** File extension (e.g. ".jpg"). Derived from key or originalName. */
+    extension?: string;
+    /** Checksum for validation (e.g. sha256). Key names are hashing algorithm. */
+    checksums?: Record<string, string>;
+}
+
+/** Where the file lives in storage. Populated by upload adapter or upload:init. */
+interface StorageLocation {
+    /** Logical key (same as file.key). Always present. */
+    key: string;
+    /** Bucket name (S3, GCS). Optional for memory/local adapters. */
+    bucket?: string;
+    /** Region (S3). Optional. */
+    region?: string;
+    /** Public or pre-signed URL. Optional; computed on demand by adapters. */
+    url?: string;
+}
+
+/** A single thumbnail or derived image */
+interface ThumbnailResult {
+    key: string;
+    width?: number;
+    height?: number;
+    format?: string;
+    url?: string;
+}
+/** A transcoded or converted variant */
+interface VariantResult {
+    key: string;
+    format?: string;
+    width?: number;
+    height?: number;
+    bitrate?: number;
+    url?: string;
+}
+/** Image/video dimensions. Set by validation or processing. */
+interface MediaDimensions {
+    width: number;
+    height: number;
+    /** Duration in seconds, for video */
+    duration?: number;
+}
+/** Output from processing plugins. Each plugin writes to a namespaced key to avoid overwrites. */
+interface ProcessingResults {
+    /** Dimensions (from validation or processing) */
+    dimensions?: MediaDimensions;
+    /** Thumbnails. Plugins append; use plugin name as key if multiple sources. */
+    thumbnails?: Record<string, ThumbnailResult[]>;
+    /** Variants (transcodes, conversions) */
+    variants?: Record<string, VariantResult[]>;
+    /** Plugin-specific results. Key by plugin name. */
+    [pluginKey: string]: unknown;
+}
+
+/**
+ * Zod Schema for Trusted Metadata.
+ * Strictly enforced to prevent trust injection from the database.
+ */
+declare const TrustedMetadataSchema: z.ZodObject<{
+    file: z.ZodOptional<z.ZodObject<{
+        mimeType: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+        originalName: z.ZodOptional<z.ZodString>;
+        extension: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        originalName?: string | undefined;
+        extension?: string | undefined;
+    }, {
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        originalName?: string | undefined;
+        extension?: string | undefined;
+    }>>;
+    checksums: z.ZodOptional<z.ZodObject<{
+        sha256: z.ZodOptional<z.ZodString>;
+        md5: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        sha256?: string | undefined;
+        md5?: string | undefined;
+    }, {
+        sha256?: string | undefined;
+        md5?: string | undefined;
+    }>>;
+    media: z.ZodOptional<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        width?: number | undefined;
+        height?: number | undefined;
+        duration?: number | undefined;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+        duration?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    file?: {
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        originalName?: string | undefined;
+        extension?: string | undefined;
+    } | undefined;
+    checksums?: {
+        sha256?: string | undefined;
+        md5?: string | undefined;
+    } | undefined;
+    media?: {
+        width?: number | undefined;
+        height?: number | undefined;
+        duration?: number | undefined;
+    } | undefined;
+}, {
+    file?: {
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        originalName?: string | undefined;
+        extension?: string | undefined;
+    } | undefined;
+    checksums?: {
+        sha256?: string | undefined;
+        md5?: string | undefined;
+    } | undefined;
+    media?: {
+        width?: number | undefined;
+        height?: number | undefined;
+        duration?: number | undefined;
+    } | undefined;
+}>;
+/** Metadata from DB/Trusted Sources (Schema validated) */
+type TrustedMetadata = z.infer<typeof TrustedMetadataSchema>;
+
+/** File content loaded by framework. buffer or tempPath (when streamed to disk). */
+interface FileContent {
+    buffer?: Buffer;
+    tempPath?: string;
+}
+interface PipelineContext {
+    /** The unique database record identifier (typically a generated UUID). */
+    recordId: string;
+    /** Core file information. Mutable. */
+    file: FileInfo;
+    /** Storage location. Mutable but typically set once. */
+    storageLocation: StorageLocation;
+    /** Processing outputs (thumbnails, variants, etc). Mutable. */
+    processing: ProcessingResults;
+    /** Custom app/plugin metadata. Mutable. */
+    metadata: Record<string, unknown>;
+    /**
+     * Plugin-derived metadata. First writer wins.
+     * Prefilled from DB when available. Plugins read when set, compute and write when missing.
+     */
+    trusted: TrustedMetadata;
+    /** Storage adapter – read-only reference */
+    storage: StorageAdapter;
+    /** Database adapter – read-only reference */
+    database: DatabaseAdapter;
+    /** Job adapter – read-only reference */
+    jobs: JobAdapter;
+    /** Plugin scratchpad. Not persisted. Mutable. Includes file content (buffer/tempPath) from framework. */
+    utilities?: Record<string, unknown> & {
+        fileContent?: FileContent;
+    };
+}
+/** Framework-mediated Write API for Plugins */
+interface PluginApi {
+    /** Emit metadata under the plugin's own namespace. Scoped automatically. */
+    emitMetadata(patch: Record<string, unknown>): void;
+    /** Emit processing results (transcription, thumbnails) under plugin's namespace. */
+    emitProcessing(patch: Record<string, unknown>): void;
+    /** Propose updates to global trusted metadata. ONLY for 'trusted' plugins. */
+    proposeTrusted(patch: TrustedMetadata): void;
+}
+
+/** Lifecycle hook names (aligns with AWS/Cloudinary media pipeline stages). Single source of truth. */
+declare const HOOK_NAMES: readonly ["upload:init", "validation:run", "scan:run", "process:run", "upload:complete"];
+type HookName = (typeof HOOK_NAMES)[number];
+
+/**
+ * Result from validation-phase handlers; can abort pipeline.
+ * Persisted to 'validation_results' table.
+ */
+declare const ValidationResultSchema: z.ZodObject<{
+    valid: z.ZodBoolean;
+    pluginId: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    valid: boolean;
+    message?: string | undefined;
+    pluginId?: string | undefined;
+    errors?: string[] | undefined;
+}, {
+    valid: boolean;
+    message?: string | undefined;
+    pluginId?: string | undefined;
+    errors?: string[] | undefined;
+}>;
+type ValidationResult = z.infer<typeof ValidationResultSchema>;
+/**
+ * Result from virus-scan handlers.
+ * Persisted to 'virus_scan_results' table.
+ */
+declare const VirusScanResultSchema: z.ZodObject<{
+    status: z.ZodEnum<["clean", "infected", "error"]>;
+    threats: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    scanner: z.ZodOptional<z.ZodString>;
+    scannedAt: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "clean" | "infected" | "error";
+    threats?: string[] | undefined;
+    scanner?: string | undefined;
+    scannedAt?: string | undefined;
+}, {
+    status: "clean" | "infected" | "error";
+    threats?: string[] | undefined;
+    scanner?: string | undefined;
+    scannedAt?: string | undefined;
+}>;
+/** Hook interface for plugin registration (Tapable-style) */
+interface MediaRuntimeHook {
+    tap(name: string, fn: (ctx: PipelineContext, api: PluginApi) => Promise<void | ValidationResult>, options?: {
+        mode?: "sync" | "background";
+    }): void;
+}
+/** Runtime host passed to plugins via apply(); exposes lifecycle hooks */
+interface MediaRuntime {
+    readonly hooks: {
+        [K in HookName]: MediaRuntimeHook;
+    };
+}
+
+/** Plugin execution mode: sync (inline) or background (queued) */
+type PluginExecutionMode = "sync" | "background";
+/**
+ * Plugin capabilities: what a plugin is allowed to do.
+ */
+type PluginCapability = "file.read" | "metadata.write.own" | "processing.write.own" | "trusted.propose";
+/**
+ * Plugin trust level: untrusted (default) or trusted.
+ */
+type PluginTrustLevel = "untrusted" | "trusted";
+/**
+ * Plugin Manifest: immutable identity and requirements.
+ */
+interface PluginManifest {
+    readonly id: string;
+    readonly version: string;
+    readonly trustLevel: PluginTrustLevel;
+    readonly capabilities: PluginCapability[];
+    readonly namespace: string;
+}
+/**
+ * Pipeline Plugin (apply pattern, Webpack/Babel style)
+ * - apply: receive runtime, tap into hooks (preferred)
+ * - execute: legacy single-phase; mapped to process:run when apply is absent
+ */
+interface PipelinePlugin {
+    readonly name: string;
+    /** Manifest: Required identity and security metadata */
+    readonly runtimeManifest: PluginManifest;
+    /** Apply: receive runtime, tap into hooks. Standard Webpack/Babel pattern. */
+    apply?(runtime: MediaRuntime): void;
+    /** Legacy: single-phase execution. Mapped to process:run when apply is absent. */
+    execute?(context: PipelineContext): Promise<void>;
+    /** Execution mode: sync (default) or background */
+    readonly executionMode?: PluginExecutionMode;
+    /** Intensive plugins run in background by default. Non-intensive default to sync. */
+    readonly intensive?: boolean;
+}
+
+/** Provenance tokens for trusted metadata (e.g. proposeTrusted). */
+type VerifiedSourceId = "file:content";
+interface PipelineContextWithVerified extends PipelineContext {
+    _verifiedSources?: Set<VerifiedSourceId>;
+}
+/**
+ * Mark that this pipeline run has read file bytes from storage (buffer or temp path).
+ * Required before trusted plugins may call proposeTrusted with file/checksums/media patches.
+ */
+declare function markFileContentVerified(context: PipelineContext): void;
+
+/** Plugin lifecycle hooks (extensible) */
+interface PluginHooks {
+    /** Hook names → handlers. Structure for future use. */
+    [key: string]: (...args: unknown[]) => Promise<void>;
+}
+
+/**
+ * Hook-level execution mode constraint.
+ * - sync-only: Handler always runs inline. Passing background is overridden with a warning.
+ * - sync-or-background: Plugin may choose either; both are valid.
+ * - background-only: Handler always runs enqueued. Passing sync is overridden with a warning.
+ */
+type HookModeConstraint = "sync-only" | "sync-or-background" | "background-only";
+/** Per-hook mode constraints. Single source of truth for hook execution rules. */
+declare const HOOK_MODE_CONSTRAINTS: Record<HookName, HookModeConstraint>;
+/**
+ * Resolve effective execution mode given hook constraint and requested mode.
+ * Returns the mode to use and whether it was overridden (for logging).
+ */
+declare function resolveHookMode(hookName: HookName, requested: "sync" | "background"): {
+    effective: "sync" | "background";
+    overridden: boolean;
+};
+
+/**
+ * Handler for a pipeline stage hook.
+ * Can return ValidationResult to abort pipeline (validation phases).
+ */
+type HookHandler$1 = (ctx: PipelineContext) => Promise<void | ValidationResult>;
+/** Options for hook registration (tap) */
+interface HookHandlerOptions {
+    /** Sync (inline) or background (queued via JobAdapter) */
+    mode?: "sync" | "background";
+}
+
+/** Plugin contract alias – plugins register themselves via apply() and tap into hooks */
+type MediaPlugin = PipelinePlugin;
+/** Context passed to hook handlers – pipeline stage execution context */
+type HookContext = PipelineContext;
+
+type FieldType = "string" | "number" | "boolean" | "date" | "json";
+interface FieldDefinition {
+    type: FieldType;
+    /** Whether this field is the primary key */
+    primaryKey?: boolean;
+    /** Whether this field must always have a value */
+    required?: boolean;
+    /** Whether the values in this field must be unique across the table */
+    unique?: boolean;
+    /** Default value for new records */
+    defaultValue?: unknown | (() => unknown);
+    /** Foreign key reference */
+    references?: {
+        model: string;
+        field: string;
+        onDelete?: "cascade" | "set null" | "restrict";
+    };
+}
+interface IndexDefinition {
+    fields: string[];
+    unique?: boolean;
+}
+interface ModelDefinition {
+    fields: Record<string, FieldDefinition>;
+    indexes?: IndexDefinition[];
+    /** Whether to enable soft delete for this model */
+    softDelete?: boolean;
+}
+type BmSchema = Record<string, ModelDefinition>;
+/**
+ * Context passed to database hooks.
+ */
+interface DatabaseHookContext {
+    model: string;
+    adapter: DatabaseAdapter;
+    transaction?: DatabaseTransactionAdapter;
+}
+type HookHandler<T = unknown, R = unknown> = (data: T, context: DatabaseHookContext) => Promise<R>;
+interface DbHooks {
+    before?: {
+        create?: HookHandler<Record<string, unknown>, Record<string, unknown>>[];
+        update?: HookHandler<Record<string, unknown>, Record<string, unknown>>[];
+        delete?: HookHandler<WhereClause, void>[];
+    };
+    after?: {
+        create?: HookHandler<Record<string, unknown>, void>[];
+        update?: HookHandler<Record<string, unknown>, void>[];
+        delete?: HookHandler<WhereClause, void>[];
+    };
+}
+type SqlDialect = "postgres" | "mysql" | "sqlite" | "mssql";
+interface ColumnMetadata {
+    name: string;
+    dataType: string;
+    isNullable: boolean;
+    isUnique?: boolean;
+}
+interface TableMetadata {
+    name: string;
+    columns: ColumnMetadata[];
+}
+type MigrationOperation = {
+    type: "createTable";
+    table: string;
+    definition: ModelDefinition;
+} | {
+    type: "addColumn";
+    table: string;
+    field: string;
+    definition: FieldDefinition;
+} | {
+    type: "createIndex";
+    table: string;
+    name: string;
+    fields: string[];
+    unique?: boolean;
+};
+
+/**
+ * Central schema defining all Better Media tables and relationships.
+ * This is the single source of truth for the database structure.
+ */
+declare const schema: BmSchema;
+
+declare function toSnakeCase(value: string): string;
+declare function toCamelCase(value: string): string;
+declare function toDbFieldName(field: string): string;
+
+interface FieldConverter {
+    serialize(value: unknown): unknown;
+    deserialize(value: unknown): unknown;
+}
+declare const converters: Record<FieldType, FieldConverter>;
+declare function serializeField(type: FieldType, value: unknown): unknown;
+declare function deserializeField(type: FieldType, value: unknown): unknown;
+declare function serializeData(fields: Record<string, {
+    type: FieldType;
+}>, data: Record<string, unknown>): Record<string, unknown>;
+declare function deserializeData(fields: Record<string, {
+    type: FieldType;
+}>, data: Record<string, unknown>): Record<string, unknown>;
+
+declare function getColumnType(field: FieldDefinition, dialect: SqlDialect): string;
+declare function matchType(dbType: string, expectedType: FieldType, dialect: SqlDialect): boolean;
+/**
+ * MigrationPlanner calculates the delta between the desired schema and the actual DB state.
+ */
+declare class MigrationPlanner {
+    private readonly dialect;
+    constructor(dialect: SqlDialect);
+    plan(schema: BmSchema, currentTables: TableMetadata[]): MigrationOperation[];
+}
+/**
+ * Applies a list of migration operations to an existing metadata state to project
+ * what the database will look like after the migration.
+ */
+declare function applyOperationsToMetadata(currentMetadata: TableMetadata[], operations: MigrationOperation[], dialect: SqlDialect): TableMetadata[];
+
+declare function compileMigrationOperationsSql(options: {
+    operations: MigrationOperation[];
+    dialect: SqlDialect;
+}): string;
+declare function generateCreateSchemaSql(options: {
+    schema: BmSchema;
+    dialect: SqlDialect;
+}): string;
+
+interface MigrationOptions {
+    /**
+     * Migration mode:
+     * - 'safe': Only create missing tables/collections and add missing columns/indexes.
+     * - 'diff': Full schema comparison and incremental updates (Recommended).
+     * - 'force': Drop and recreate all tables/collections (destructive).
+     */
+    mode?: "safe" | "diff" | "force";
+    /**
+     * For SQL adapters, the dialect can be manually specified.
+     * If omitted, the adapter will try to detect it.
+     */
+    dialect?: SqlDialect;
+}
+interface PlannedMigrationTable {
+    table: string;
+    fields: string[];
+}
+interface PlannedMigrations {
+    toBeCreated: PlannedMigrationTable[];
+    toBeAdded: PlannedMigrationTable[];
+    operations: MigrationOperation[];
+    compileMigrations: () => string;
+    runMigrations: () => Promise<void>;
+}
+declare function getMigrations(adapter: DatabaseAdapter, options?: MigrationOptions): Promise<PlannedMigrations>;
+/**
+ * Migration engine. It iterates through the central BmSchema and invokes
+ * engine-specific setup commands on the adapter.
+ */
+declare function runMigrations(adapter: DatabaseAdapter, options?: MigrationOptions): Promise<void>;
+
+/**
+ * Utility to run hooks sequentially.
+ * Supports multiple handlers and passes DatabaseHookContext.
+ */
+declare const runHooks: {
+    beforeCreate(hooks: DbHooks | undefined, data: Record<string, unknown>, context: DatabaseHookContext): Promise<Record<string, unknown>>;
+    beforeUpdate(hooks: DbHooks | undefined, data: Record<string, unknown>, context: DatabaseHookContext): Promise<Record<string, unknown>>;
+    beforeDelete(hooks: DbHooks | undefined, where: WhereClause, context: DatabaseHookContext): Promise<void>;
+    afterCreate(hooks: DbHooks | undefined, result: Record<string, unknown>, context: DatabaseHookContext): Promise<void>;
+    afterUpdate(hooks: DbHooks | undefined, result: Record<string, unknown>, context: DatabaseHookContext): Promise<void>;
+    afterDelete(hooks: DbHooks | undefined, where: WhereClause, context: DatabaseHookContext): Promise<void>;
+};
+
+type QueryResultLike<T = unknown> = {
+    rows: T[];
+    rowCount?: number | null;
+};
+type Queryable = {
+    query: (text: string, values?: unknown[]) => Promise<QueryResultLike<Record<string, unknown>>>;
+};
+type PgPoolLike = Queryable & {
+    connect?: () => Promise<PgClientLike>;
+};
+type PgClientLike = Queryable & {
+    release?: () => void;
+};
+declare function isPgPoolLike(value: unknown): value is PgPoolLike;
+/**
+ * Normalizes a database pool or adapter into a standard DatabaseAdapter.
+ * Note: If using the built-in Postgres pool, this requires the actual
+ * implementation to be registered or known.
+ */
+declare function toDatabaseAdapter(database: DatabaseAdapter | PgPoolLike, postgresFactory?: (pool: PgPoolLike) => DatabaseAdapter): DatabaseAdapter;
+
+type GetAdapterOptions = {
+    database?: DatabaseAdapter | PgPoolLike;
+    createDatabase?: () => Promise<DatabaseAdapter | PgPoolLike> | DatabaseAdapter | PgPoolLike;
+    dialect?: string;
+    schemaOutput?: string;
+    migrationsDir?: string;
+};
+declare function getAdapter(options: GetAdapterOptions): Promise<DatabaseAdapter>;
+
+/**
+ * Mapping of common file extensions to their valid MIME types.
+ * Based on MDN Common Media Types: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types
+ */
+declare const EXTENSION_TO_MIME_MAP: Record<string, string[]>;
+
+type MediaStatus = "PENDING_VERIFICATION" | "VALID" | "INVALID" | "PROCESSING" | "COMPLETED";
+declare function sleep(ms: number): Promise<unknown>;
+
+export { type BmSchema, type ColumnMetadata, type CountOptions, type CreateOptions, type DatabaseAdapter, type DatabaseHookContext, type DatabaseTransactionAdapter, type DbHooks, type DeleteOptions, EXTENSION_TO_MIME_MAP, type FieldConverter, type FieldDefinition, type FieldType, type FileContent, type FileInfo, type FindOptions, type GetAdapterOptions, type GetUrlOptions, HOOK_MODE_CONSTRAINTS, HOOK_NAMES, type HookContext, type HookHandler$1 as HookHandler, type HookHandlerOptions, type HookModeConstraint, type HookName, type IndexDefinition, type JobAdapter, type MediaDimensions, type MediaPlugin, type MediaRuntime, type MediaRuntimeHook, type MediaStatus, type MigrationOperation, type MigrationOptions, MigrationPlanner, type ModelDefinition, type PgClientLike, type PgPoolLike, type PipelineContext, type PipelineContextWithVerified, type PipelinePlugin, type PlannedMigrationTable, type PlannedMigrations, type PluginApi, type PluginExecutionMode, type PluginHooks, type PluginManifest, type PresignedUploadMethod, type PresignedUploadOptions, type PresignedUploadResult, type ProcessingResults, type QueryResultLike, type Queryable, type SqlDialect, type StorageAdapter, type StorageLocation, type TableMetadata, type ThumbnailResult, type TrustedMetadata, TrustedMetadataSchema, type UpdateOptions, type ValidationResult, ValidationResultSchema, type VariantResult, type VerifiedSourceId, VirusScanResultSchema, type WhereClause, applyOperationsToMetadata, compileMigrationOperationsSql, converters, deserializeData, deserializeField, generateCreateSchemaSql, getAdapter, getColumnType, getMigrations, isPgPoolLike, markFileContentVerified, matchType, resolveHookMode, runHooks, runMigrations, schema, serializeData, serializeField, sleep, toCamelCase, toDatabaseAdapter, toDbFieldName, toSnakeCase };