@gl-life/gl-life-database 1.0.0

package/dist/types/cloudforge.d.ts

@@ -0,0 +1,753 @@
+import { Result } from '@gl-life/gl-life-core';
+import type { DatabaseConnectionError } from './connection.js';
+/**
+ * Cloudflare D1 database binding interface
+ *
+ * This represents the D1 database binding available in Cloudflare Workers
+ */
+export interface D1Database {
+    /**
+     * Execute a query and return results
+     */
+    prepare(query: string): D1PreparedStatement;
+    /**
+     * Execute multiple queries in a batch
+     */
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    /**
+     * Execute SQL directly (for migrations)
+     */
+    exec(sql: string): Promise<D1ExecResult>;
+    /**
+     * Dump database schema and data
+     */
+    dump(): Promise<ArrayBuffer>;
+}
+/**
+ * D1 prepared statement interface
+ */
+export interface D1PreparedStatement {
+    /**
+     * Bind parameters to the statement
+     */
+    bind(...params: unknown[]): D1PreparedStatement;
+    /**
+     * Execute and return first row
+     */
+    first<T = unknown>(colName?: string): Promise<T | null>;
+    /**
+     * Execute and return all rows
+     */
+    all<T = unknown>(): Promise<D1Result<T>>;
+    /**
+     * Execute and return raw results
+     */
+    raw<T = unknown[]>(): Promise<T[]>;
+    /**
+     * Execute without returning results
+     */
+    run(): Promise<D1Result>;
+}
+/**
+ * D1 query result interface
+ */
+export interface D1Result<T = unknown> {
+    /**
+     * Query results
+     */
+    results?: T[];
+    /**
+     * Whether the query was successful
+     */
+    success: boolean;
+    /**
+     * Query execution metadata
+     */
+    meta?: {
+        /**
+         * Number of rows changed
+         */
+        changes?: number;
+        /**
+         * Last inserted row ID
+         */
+        last_row_id?: number;
+        /**
+         * Query duration in milliseconds
+         */
+        duration?: number;
+        /**
+         * Number of rows returned
+         */
+        rows_read?: number;
+        /**
+         * Number of rows written
+         */
+        rows_written?: number;
+    };
+    /**
+     * Error information (if success is false)
+     */
+    error?: string;
+}
+/**
+ * D1 exec result interface (for raw SQL execution)
+ */
+export interface D1ExecResult {
+    /**
+     * Number of statements executed
+     */
+    count: number;
+    /**
+     * Query duration in milliseconds
+     */
+    duration: number;
+}
+/**
+ * D1 adapter configuration
+ */
+export interface D1AdapterConfig {
+    /**
+     * D1 database binding
+     */
+    database: D1Database;
+    /**
+     * Database name for logging
+     */
+    name: string;
+    /**
+     * Enable query logging
+     */
+    enableQueryLogging?: boolean;
+    /**
+     * Maximum batch size for batch operations
+     */
+    maxBatchSize?: number;
+    /**
+     * Query timeout in milliseconds
+     */
+    timeout?: number;
+}
+/**
+ * D1 adapter error types
+ */
+export type D1AdapterError = DatabaseConnectionError | {
+    type: 'QUERY_FAILED';
+    message: string;
+    sql: string;
+    cause?: unknown;
+} | {
+    type: 'BATCH_FAILED';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'INVALID_QUERY';
+    message: string;
+    sql: string;
+} | {
+    type: 'PARAMETER_ERROR';
+    message: string;
+} | {
+    type: 'EXEC_FAILED';
+    message: string;
+    cause?: unknown;
+};
+/**
+ * D1 database adapter interface
+ *
+ * Provides a standardized interface for interacting with Cloudflare D1 databases
+ */
+export interface D1Adapter {
+    /**
+     * Adapter configuration
+     */
+    readonly config: D1AdapterConfig;
+    /**
+     * Execute a SQL query
+     *
+     * @param sql - SQL query string
+     * @param params - Query parameters
+     * @returns Result with query results or D1AdapterError
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<Result<T[], D1AdapterError>>;
+    /**
+     * Execute a SQL query and return first result
+     *
+     * @param sql - SQL query string
+     * @param params - Query parameters
+     * @returns Result with first result or D1AdapterError
+     */
+    queryFirst<T = unknown>(sql: string, params?: unknown[]): Promise<Result<T | null, D1AdapterError>>;
+    /**
+     * Execute a SQL statement (INSERT, UPDATE, DELETE)
+     *
+     * @param sql - SQL statement string
+     * @param params - Statement parameters
+     * @returns Result with execution metadata or D1AdapterError
+     */
+    execute(sql: string, params?: unknown[]): Promise<Result<D1Result, D1AdapterError>>;
+    /**
+     * Execute multiple SQL statements in a batch
+     *
+     * @param statements - Array of SQL statements with parameters
+     * @returns Result with array of execution results or D1AdapterError
+     */
+    batch(statements: Array<{
+        sql: string;
+        params?: unknown[];
+    }>): Promise<Result<D1Result[], D1AdapterError>>;
+    /**
+     * Execute raw SQL (for migrations and schema changes)
+     *
+     * @param sql - Raw SQL to execute
+     * @returns Result with execution result or D1AdapterError
+     */
+    exec(sql: string): Promise<Result<D1ExecResult, D1AdapterError>>;
+    /**
+     * Begin a transaction
+     *
+     * @param callback - Transaction callback function
+     * @returns Result with callback result or D1AdapterError
+     */
+    transaction<T>(callback: (adapter: D1Adapter) => Promise<Result<T, D1AdapterError>>): Promise<Result<T, D1AdapterError>>;
+}
+/**
+ * Cloudflare Durable Objects Storage interface
+ *
+ * This represents the storage API available in Durable Objects
+ */
+export interface DurableObjectStorage {
+    /**
+     * Get a single value or multiple values by key
+     */
+    get(key: string): Promise<any>;
+    get(keys: string[]): Promise<Map<string, any>>;
+    get(key: string | string[]): Promise<any | Map<string, any>>;
+    /**
+     * Put a single key-value pair or multiple pairs
+     */
+    put(key: string, value: any): Promise<void>;
+    put(entries: Record<string, any>): Promise<void>;
+    put(key: string | Record<string, any>, value?: any): Promise<void>;
+    /**
+     * Delete a single key or multiple keys
+     */
+    delete(key: string): Promise<boolean>;
+    delete(keys: string[]): Promise<number>;
+    delete(key: string | string[]): Promise<boolean | number>;
+    /**
+     * List keys in storage
+     */
+    list(options?: StorageListOptions): Promise<Map<string, any>>;
+    /**
+     * Delete all keys in storage
+     */
+    deleteAll(options?: StorageListOptions): Promise<void>;
+    /**
+     * Execute a transaction
+     */
+    transaction<T>(callback: (txn: DurableObjectStorage) => Promise<T>): Promise<T>;
+    /**
+     * Get the current alarm timestamp
+     */
+    getAlarm(): Promise<number | null>;
+    /**
+     * Set an alarm to trigger at a specific time
+     */
+    setAlarm(scheduledTime: number | Date): Promise<void>;
+    /**
+     * Delete the current alarm
+     */
+    deleteAlarm(): Promise<void>;
+    /**
+     * Synchronize storage to disk
+     */
+    sync(): Promise<void>;
+}
+/**
+ * Storage list options
+ */
+export interface StorageListOptions {
+    /**
+     * Start key (inclusive)
+     */
+    start?: string;
+    /**
+     * End key (exclusive)
+     */
+    end?: string;
+    /**
+     * Key prefix filter
+     */
+    prefix?: string;
+    /**
+     * Reverse the order of results
+     */
+    reverse?: boolean;
+    /**
+     * Maximum number of keys to return
+     */
+    limit?: number;
+}
+/**
+ * Durable Objects storage adapter configuration
+ */
+export interface DurableObjectStorageConfig {
+    /**
+     * Storage name for logging
+     */
+    name: string;
+    /**
+     * Enable operation logging
+     */
+    enableLogging?: boolean;
+    /**
+     * Allow concurrent operations (default: false for consistency)
+     */
+    allowConcurrency?: boolean;
+    /**
+     * Cache options
+     */
+    cacheOptions?: {
+        /**
+         * Enable in-memory caching
+         */
+        enableMemoryCache?: boolean;
+        /**
+         * Cache TTL in milliseconds
+         */
+        ttl?: number;
+    };
+}
+/**
+ * Durable Objects storage error types
+ */
+export type DurableObjectStorageError = {
+    type: 'STORAGE_FAILED';
+    message: string;
+    key?: string;
+    cause?: unknown;
+} | {
+    type: 'SERIALIZATION_ERROR';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'TRANSACTION_FAILED';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'QUOTA_EXCEEDED';
+    message: string;
+} | {
+    type: 'INVALID_KEY';
+    message: string;
+    key?: string;
+} | {
+    type: 'UNKNOWN';
+    message: string;
+    cause?: unknown;
+};
+/**
+ * Storage transaction interface for callback operations
+ */
+export interface StorageTransaction {
+    get<T>(key: string): Promise<Result<T | null, DurableObjectStorageError>>;
+    getMultiple<T>(keys: string[]): Promise<Result<Map<string, T>, DurableObjectStorageError>>;
+    put<T>(key: string, value: T): Promise<Result<void, DurableObjectStorageError>>;
+    putMultiple<T>(entries: [string, T][]): Promise<Result<void, DurableObjectStorageError>>;
+    delete(key: string): Promise<Result<boolean, DurableObjectStorageError>>;
+    deleteMultiple(keys: string[]): Promise<Result<number, DurableObjectStorageError>>;
+    list(options?: StorageListOptions): Promise<Result<Map<string, any>, DurableObjectStorageError>>;
+}
+/**
+ * Durable Objects storage adapter interface
+ *
+ * Provides a standardized interface for interacting with Durable Objects storage
+ */
+export interface DurableObjectStorageAdapter {
+    /**
+     * Adapter configuration
+     */
+    readonly config: DurableObjectStorageConfig;
+    /**
+     * Get a single value by key
+     *
+     * @param key - Storage key
+     * @returns Result with value or null if not found
+     */
+    get<T>(key: string): Promise<Result<T | null, DurableObjectStorageError>>;
+    /**
+     * Get multiple values by keys
+     *
+     * @param keys - Array of storage keys
+     * @returns Result with Map of key-value pairs
+     */
+    getMultiple<T>(keys: string[]): Promise<Result<Map<string, T>, DurableObjectStorageError>>;
+    /**
+     * Put a single key-value pair
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     * @returns Result with void or error
+     */
+    put<T>(key: string, value: T): Promise<Result<void, DurableObjectStorageError>>;
+    /**
+     * Put multiple key-value pairs
+     *
+     * @param entries - Array of [key, value] tuples
+     * @returns Result with void or error
+     */
+    putMultiple<T>(entries: [string, T][]): Promise<Result<void, DurableObjectStorageError>>;
+    /**
+     * Delete a single key
+     *
+     * @param key - Storage key to delete
+     * @returns Result with boolean indicating if key existed
+     */
+    delete(key: string): Promise<Result<boolean, DurableObjectStorageError>>;
+    /**
+     * Delete multiple keys
+     *
+     * @param keys - Array of storage keys to delete
+     * @returns Result with count of deleted keys
+     */
+    deleteMultiple(keys: string[]): Promise<Result<number, DurableObjectStorageError>>;
+    /**
+     * Delete all keys in storage
+     *
+     * @returns Result with void or error
+     */
+    deleteAll(): Promise<Result<void, DurableObjectStorageError>>;
+    /**
+     * List keys in storage
+     *
+     * @param options - List options (prefix, start, end, limit, reverse)
+     * @returns Result with Map of key-value pairs
+     */
+    list(options?: StorageListOptions): Promise<Result<Map<string, any>, DurableObjectStorageError>>;
+    /**
+     * Execute operations in a transaction
+     *
+     * @param callback - Transaction callback function
+     * @returns Result with callback result or error
+     */
+    transaction<T>(callback: (txn: StorageTransaction) => Promise<Result<T, DurableObjectStorageError>>): Promise<Result<T, DurableObjectStorageError>>;
+}
+/**
+ * Cloudflare R2 bucket binding interface
+ *
+ * This represents the R2 bucket binding available in Cloudflare Workers
+ */
+export interface R2Bucket {
+    /**
+     * Get object metadata only
+     */
+    head(key: string): Promise<R2Object | null>;
+    /**
+     * Get object with body
+     */
+    get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
+    /**
+     * Put object
+     */
+    put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob, options?: R2PutOptions): Promise<R2Object>;
+    /**
+     * Delete single or multiple objects
+     */
+    delete(key: string | string[]): Promise<void>;
+    /**
+     * List objects in bucket
+     */
+    list(options?: R2ListOptions): Promise<R2Objects>;
+    /**
+     * Create multipart upload
+     */
+    createMultipartUpload(key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>;
+    /**
+     * Resume multipart upload
+     */
+    resumeMultipartUpload(key: string, uploadId: string): R2MultipartUpload;
+}
+/**
+ * R2 object metadata
+ */
+export interface R2Object {
+    key: string;
+    version: string;
+    size: number;
+    etag: string;
+    httpEtag: string;
+    uploaded: Date;
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+    storageClass?: 'Standard' | 'InfrequentAccess';
+    checksums?: R2Checksums;
+}
+/**
+ * R2 object with body
+ */
+export interface R2ObjectBody extends R2Object {
+    body: ReadableStream;
+    bodyUsed: boolean;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    blob(): Promise<Blob>;
+}
+/**
+ * R2 HTTP metadata
+ */
+export interface R2HttpMetadata {
+    contentType?: string;
+    contentLanguage?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    cacheControl?: string;
+    expires?: Date;
+}
+/**
+ * R2 checksums
+ */
+export interface R2Checksums {
+    md5?: ArrayBuffer;
+    sha1?: ArrayBuffer;
+    sha256?: ArrayBuffer;
+    sha384?: ArrayBuffer;
+    sha512?: ArrayBuffer;
+}
+/**
+ * R2 get options
+ */
+export interface R2GetOptions {
+    onlyIf?: R2Conditional;
+    range?: {
+        offset?: number;
+        length?: number;
+        suffix?: number;
+    };
+}
+/**
+ * R2 conditional request
+ */
+export interface R2Conditional {
+    etagMatches?: string;
+    etagDoesNotMatch?: string;
+    uploadedBefore?: Date;
+    uploadedAfter?: Date;
+}
+/**
+ * R2 put options
+ */
+export interface R2PutOptions {
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+    md5?: string | ArrayBuffer;
+    sha256?: string | ArrayBuffer;
+    storageClass?: 'Standard' | 'InfrequentAccess';
+}
+/**
+ * R2 list options
+ */
+export interface R2ListOptions {
+    limit?: number;
+    prefix?: string;
+    cursor?: string;
+    delimiter?: string;
+    include?: ('httpMetadata' | 'customMetadata')[];
+}
+/**
+ * R2 list result
+ */
+export interface R2Objects {
+    objects: R2Object[];
+    truncated: boolean;
+    cursor?: string;
+    delimitedPrefixes: string[];
+}
+/**
+ * R2 multipart upload
+ */
+export interface R2MultipartUpload {
+    uploadPart(partNumber: number, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob): Promise<R2UploadedPart>;
+    completeMultipartUpload(parts: R2UploadedPart[]): Promise<R2Object>;
+    abort(): Promise<void>;
+}
+/**
+ * R2 multipart options
+ */
+export interface R2MultipartOptions {
+    httpMetadata?: R2HttpMetadata;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * R2 uploaded part
+ */
+export interface R2UploadedPart {
+    partNumber: number;
+    etag: string;
+}
+/**
+ * Backup information
+ */
+export interface BackupInfo {
+    key: string;
+    size: number;
+    compressedSize: number;
+    compressionRatio: number;
+    uploadedAt: Date;
+    etag: string;
+    metadata?: {
+        databaseVersion?: string;
+        backupType?: string;
+        originalChecksum?: string;
+    };
+}
+/**
+ * Backup options
+ */
+export interface BackupOptions {
+    /**
+     * Compression level (0-9, default: 6)
+     */
+    compressionLevel?: number;
+    /**
+     * Custom metadata to attach
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Storage class
+     */
+    storageClass?: 'Standard' | 'InfrequentAccess';
+    /**
+     * Use multipart upload threshold (bytes, default: 100MB)
+     */
+    multipartThreshold?: number;
+}
+/**
+ * Restore options
+ */
+export interface RestoreOptions {
+    /**
+     * Verify checksum after restore
+     */
+    verifyChecksum?: boolean;
+}
+/**
+ * R2 backup adapter configuration
+ */
+export interface R2BackupConfig {
+    /**
+     * R2 bucket binding
+     */
+    bucket: R2Bucket;
+    /**
+     * Backup name prefix
+     */
+    name: string;
+    /**
+     * Enable operation logging
+     */
+    enableLogging?: boolean;
+    /**
+     * Default compression level (0-9)
+     */
+    defaultCompressionLevel?: number;
+    /**
+     * Multipart upload threshold in bytes
+     */
+    multipartThreshold?: number;
+}
+/**
+ * R2 backup error types
+ */
+export type R2BackupError = {
+    type: 'UPLOAD_FAILED';
+    message: string;
+    key?: string;
+    cause?: unknown;
+} | {
+    type: 'DOWNLOAD_FAILED';
+    message: string;
+    key?: string;
+    cause?: unknown;
+} | {
+    type: 'RESTORE_FAILED';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'COMPRESSION_FAILED';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'DECOMPRESSION_FAILED';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'BACKUP_NOT_FOUND';
+    message: string;
+    key: string;
+} | {
+    type: 'INVALID_BACKUP';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'SCHEDULE_FAILED';
+    message: string;
+    cause?: unknown;
+} | {
+    type: 'UNKNOWN';
+    message: string;
+    cause?: unknown;
+};
+/**
+ * R2 backup adapter interface
+ *
+ * Provides database backup and restore functionality using Cloudflare R2
+ */
+export interface R2BackupAdapter {
+    /**
+     * Adapter configuration
+     */
+    readonly config: R2BackupConfig;
+    /**
+     * Create a backup
+     *
+     * @param data - Data to backup
+     * @param options - Backup options
+     * @returns Result with backup information
+     */
+    backup(data: ArrayBuffer | Buffer, options?: BackupOptions): Promise<Result<BackupInfo, R2BackupError>>;
+    /**
+     * Restore from a backup
+     *
+     * @param key - Backup key
+     * @param options - Restore options
+     * @returns Result with restored data
+     */
+    restore(key: string, options?: RestoreOptions): Promise<Result<ArrayBuffer, R2BackupError>>;
+    /**
+     * List all backups
+     *
+     * @param options - List options
+     * @returns Result with array of backup information
+     */
+    listBackups(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Result<BackupInfo[], R2BackupError>>;
+    /**
+     * Delete a backup
+     *
+     * @param key - Backup key to delete
+     * @returns Result with void or error
+     */
+    deleteBackup(key: string): Promise<Result<void, R2BackupError>>;
+    /**
+     * Delete multiple backups
+     *
+     * @param keys - Backup keys to delete
+     * @returns Result with void or error
+     */
+    deleteMultipleBackups(keys: string[]): Promise<Result<void, R2BackupError>>;
+}
+//# sourceMappingURL=cloudforge.d.ts.map