@dotdo/do 0.1.0

package/dist/db/storage/index.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Storage Layer
+ *
+ * Three-tier storage architecture for Digital Objects:
+ * - Hot: DO SQLite + Vortex columnar (~4ms)
+ * - Warm: Edge Cache API (~10ms, free)
+ * - Cold: R2 + Iceberg (~69ms, $0.015/GB/mo)
+ *
+ * @module @do/core/storage
+ */
+import type { StorageTier, StorageTierInfo, CDCEvent, SyncState, SyncOptions, SyncResult } from '../../types/storage';
+import { HotStorage } from './hot';
+import { WarmStorage } from './warm';
+import { ColdStorage } from './cold';
+import { SnapshotManager } from './snapshots';
+export { HotStorage } from './hot';
+export { WarmStorage } from './warm';
+export { ColdStorage } from './cold';
+export { VortexEncoder, VortexDecoder } from './vortex';
+export { SnapshotManager } from './snapshots';
+/**
+ * Storage configuration options
+ */
+export interface StorageConfig {
+    /** DO SQLite storage binding */
+    sqlite?: SqlStorage;
+    /** Cloudflare Cache API */
+    cache?: CacheStorage;
+    /** R2 bucket binding */
+    r2?: R2Bucket;
+    /** CDC event emitter */
+    onCDC?: (event: CDCEvent) => void | Promise<void>;
+    /** Hot tier configuration */
+    hot?: HotStorageConfig;
+    /** Warm tier configuration */
+    warm?: WarmStorageConfig;
+    /** Cold tier configuration */
+    cold?: ColdStorageConfig;
+    /** Sync configuration */
+    sync?: SyncConfig;
+}
+/**
+ * Hot storage configuration
+ */
+export interface HotStorageConfig {
+    /** Enable hot storage (default: true) */
+    enabled?: boolean;
+    /** Maximum storage size in bytes */
+    maxSize?: number;
+    /** Row count threshold for Vortex conversion */
+    vortexThreshold?: number;
+}
+/**
+ * Warm storage configuration
+ */
+export interface WarmStorageConfig {
+    /** Enable warm storage (default: true if cache available) */
+    enabled?: boolean;
+    /** Default TTL in seconds */
+    defaultTTL?: number;
+    /** Maximum cached entries */
+    maxEntries?: number;
+}
+/**
+ * Cold storage configuration
+ */
+export interface ColdStorageConfig {
+    /** Enable cold storage (default: true if R2 available) */
+    enabled?: boolean;
+    /** R2 key prefix */
+    prefix?: string;
+    /** Partition fields */
+    partitionBy?: string[];
+    /** Compression codec */
+    compressionCodec?: 'none' | 'zstd' | 'snappy' | 'gzip';
+}
+/**
+ * Sync configuration
+ */
+export interface SyncConfig {
+    /** Batch size for sync operations */
+    batchSize?: number;
+    /** Sync interval in milliseconds */
+    interval?: number;
+    /** Auto-sync enabled */
+    autoSync?: boolean;
+}
+/**
+ * Unified storage interface across all tiers
+ */
+export interface UnifiedStorage {
+    /** Hot tier storage */
+    readonly hot: HotStorage;
+    /** Warm tier storage (optional) */
+    readonly warm?: WarmStorage;
+    /** Cold tier storage (optional) */
+    readonly cold?: ColdStorage;
+    /** Snapshot manager */
+    readonly snapshots: SnapshotManager;
+    /**
+     * Insert a document (writes to hot, invalidates warm)
+     * @param collection - Collection name
+     * @param document - Document to insert
+     */
+    insert<T extends {
+        id: string;
+    }>(collection: string, document: T): Promise<void>;
+    /**
+     * Query documents (checks warm cache first, falls back to hot)
+     * @param collection - Collection name
+     * @param query - Query parameters
+     */
+    query<T>(collection: string, query?: QueryOptions): Promise<T[]>;
+    /**
+     * Update a document
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @param updates - Partial document updates
+     */
+    update<T>(collection: string, id: string, updates: Partial<T>): Promise<void>;
+    /**
+     * Delete a document
+     * @param collection - Collection name
+     * @param id - Document ID
+     */
+    delete(collection: string, id: string): Promise<void>;
+    /**
+     * Archive data to cold storage
+     * @param collection - Collection name
+     * @param options - Archive options
+     */
+    archive(collection: string, options?: ArchiveOptions): Promise<SyncResult>;
+    /**
+     * Get current sync state
+     */
+    getSyncState(): Promise<SyncState>;
+    /**
+     * Sync data between tiers
+     * @param options - Sync options
+     */
+    sync(options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Subscribe to CDC events
+     * @param callback - Event handler
+     */
+    onCDC(callback: (event: CDCEvent) => void | Promise<void>): () => void;
+}
+/**
+ * Query options for storage operations
+ */
+export interface QueryOptions {
+    /** Filter conditions */
+    where?: Record<string, unknown>;
+    /** Sort order */
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Cache TTL override (warm tier) */
+    cacheTTL?: number;
+    /** Skip cache lookup */
+    skipCache?: boolean;
+}
+/**
+ * Archive options for cold storage
+ */
+export interface ArchiveOptions {
+    /** Archive records older than this timestamp */
+    olderThan?: number;
+    /** Delete archived records from hot */
+    deleteAfterArchive?: boolean;
+    /** Partition configuration */
+    partition?: Record<string, string | number>;
+}
+/**
+ * Storage event types
+ */
+export type StorageEventType = 'insert' | 'update' | 'delete' | 'sync' | 'archive';
+/**
+ * Storage event
+ */
+export interface StorageEvent {
+    type: StorageEventType;
+    tier: StorageTier;
+    collection: string;
+    documentId?: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create a unified storage instance
+ *
+ * @param config - Storage configuration
+ * @returns Unified storage interface
+ *
+ * @example
+ * ```typescript
+ * const storage = createStorage({
+ *   sqlite: env.DO_STORAGE,
+ *   cache: caches,
+ *   r2: env.R2_BUCKET,
+ * })
+ *
+ * await storage.insert('users', { id: '1', name: 'Alice' })
+ * const users = await storage.query('users', { where: { name: 'Alice' } })
+ * ```
+ */
+export declare function createStorage(config: StorageConfig): UnifiedStorage;
+/**
+ * Storage error class
+ */
+export declare class StorageError extends Error {
+    readonly tier: StorageTier;
+    readonly operation: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, tier: StorageTier, operation: string, cause?: Error | undefined);
+}
+/**
+ * Check if a tier is available
+ *
+ * @param tier - Storage tier to check
+ * @param config - Storage configuration
+ * @returns Whether the tier is available
+ */
+export declare function isTierAvailable(tier: StorageTier, config: StorageConfig): boolean;
+/**
+ * Get tier info
+ *
+ * @param tier - Storage tier
+ * @returns Tier information
+ */
+export declare function getTierInfo(tier: StorageTier): StorageTierInfo;
+declare global {
+    interface SqlStorage {
+        exec(query: string, params?: unknown[]): Promise<unknown>;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/db/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../db/storage/index.ts"],"names":[],"mappings":"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"}

package/dist/db/storage/index.js

@@ -0,0 +1,109 @@
+/**
+ * Storage Layer
+ *
+ * Three-tier storage architecture for Digital Objects:
+ * - Hot: DO SQLite + Vortex columnar (~4ms)
+ * - Warm: Edge Cache API (~10ms, free)
+ * - Cold: R2 + Iceberg (~69ms, $0.015/GB/mo)
+ *
+ * @module @do/core/storage
+ */
+// Re-export tier implementations
+export { HotStorage } from './hot';
+export { WarmStorage } from './warm';
+export { ColdStorage } from './cold';
+export { VortexEncoder, VortexDecoder } from './vortex';
+export { SnapshotManager } from './snapshots';
+/**
+ * Create a unified storage instance
+ *
+ * @param config - Storage configuration
+ * @returns Unified storage interface
+ *
+ * @example
+ * ```typescript
+ * const storage = createStorage({
+ *   sqlite: env.DO_STORAGE,
+ *   cache: caches,
+ *   r2: env.R2_BUCKET,
+ * })
+ *
+ * await storage.insert('users', { id: '1', name: 'Alice' })
+ * const users = await storage.query('users', { where: { name: 'Alice' } })
+ * ```
+ */
+export function createStorage(config) {
+    // TODO: Implement unified storage factory
+    throw new Error('Not implemented');
+}
+/**
+ * Storage error class
+ */
+export class StorageError extends Error {
+    tier;
+    operation;
+    cause;
+    constructor(message, tier, operation, cause) {
+        super(message);
+        this.tier = tier;
+        this.operation = operation;
+        this.cause = cause;
+        this.name = 'StorageError';
+    }
+}
+/**
+ * Check if a tier is available
+ *
+ * @param tier - Storage tier to check
+ * @param config - Storage configuration
+ * @returns Whether the tier is available
+ */
+export function isTierAvailable(tier, config) {
+    switch (tier) {
+        case 'Hot':
+            return config.sqlite !== undefined;
+        case 'Warm':
+            return config.cache !== undefined;
+        case 'Cold':
+            return config.r2 !== undefined;
+        default:
+            return false;
+    }
+}
+/**
+ * Get tier info
+ *
+ * @param tier - Storage tier
+ * @returns Tier information
+ */
+export function getTierInfo(tier) {
+    // Import from types to avoid duplication
+    const tiers = {
+        Hot: {
+            tier: 'Hot',
+            name: 'Hot Storage',
+            description: 'DO SQLite + Vortex columnar',
+            latency: '~4ms',
+            cost: 'Included in DO pricing',
+            technology: 'SQLite + Vortex',
+        },
+        Warm: {
+            tier: 'Warm',
+            name: 'Warm Storage',
+            description: 'Edge Cache API',
+            latency: '~10ms',
+            cost: 'Free',
+            technology: 'Cloudflare Cache API',
+        },
+        Cold: {
+            tier: 'Cold',
+            name: 'Cold Storage',
+            description: 'R2 + Iceberg/Parquet',
+            latency: '~69ms',
+            cost: '$0.015/GB/month',
+            technology: 'R2 + Apache Iceberg',
+        },
+    };
+    return tiers[tier];
+}
+//# sourceMappingURL=index.js.map

package/dist/db/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../db/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH,iCAAiC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AA4L7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,0CAA0C;IAC1C,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGnB;IACA;IACA;IAJlB,YACE,OAAe,EACC,IAAiB,EACjB,SAAiB,EACjB,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAA;QAJE,SAAI,GAAJ,IAAI,CAAa;QACjB,cAAS,GAAT,SAAS,CAAQ;QACjB,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;IAC5B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB,EAAE,MAAqB;IACtE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS,CAAA;QACpC,KAAK,MAAM;YACT,OAAO,MAAM,CAAC,KAAK,KAAK,SAAS,CAAA;QACnC,KAAK,MAAM;YACT,OAAO,MAAM,CAAC,EAAE,KAAK,SAAS,CAAA;QAChC;YACE,OAAO,KAAK,CAAA;IAChB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,yCAAyC;IACzC,MAAM,KAAK,GAAyC;QAClD,GAAG,EAAE;YACH,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,6BAA6B;YAC1C,OAAO,EAAE,MAAM;YACf,IAAI,EAAE,wBAAwB;YAC9B,UAAU,EAAE,iBAAiB;SAC9B;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,gBAAgB;YAC7B,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,MAAM;YACZ,UAAU,EAAE,sBAAsB;SACnC;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,sBAAsB;YACnC,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,iBAAiB;YACvB,UAAU,EAAE,qBAAqB;SAClC;KACF,CAAA;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAA;AACpB,CAAC"}

package/dist/db/storage/snapshots.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Snapshot Management
+ *
+ * Manages DO state snapshots for persistence, recovery, and archival.
+ * Supports full and incremental snapshots with tier promotion.
+ *
+ * Features:
+ * - Full and incremental snapshot types
+ * - Vortex encoding for efficient storage
+ * - Automatic tier promotion (hot -> cold)
+ * - Retention policy enforcement
+ *
+ * @module @do/core/storage/snapshots
+ */
+import type { Snapshot, CDCEvent } from '../../types/storage';
+import { HotStorage } from './hot';
+import { ColdStorage } from './cold';
+/**
+ * Snapshot manager configuration
+ */
+export interface SnapshotManagerConfig {
+    /** Hot storage instance */
+    hot?: HotStorage;
+    /** Cold storage instance */
+    cold?: ColdStorage;
+    /** Retention policy */
+    retention?: RetentionPolicy;
+    /** Automatic promotion settings */
+    autoPromote?: AutoPromoteConfig;
+}
+/**
+ * Retention policy configuration
+ */
+export interface RetentionPolicy {
+    /** Hot tier retention */
+    hot?: {
+        /** Maximum age in milliseconds */
+        maxAge?: number;
+        /** Maximum snapshot count */
+        maxCount?: number;
+    };
+    /** Cold tier retention */
+    cold?: {
+        /** Maximum age in milliseconds */
+        maxAge?: number;
+        /** Maximum snapshot count (null = unlimited) */
+        maxCount?: number | null;
+    };
+    /** Maximum incremental chain length before forcing full snapshot */
+    incrementalChainLength?: number;
+}
+/**
+ * Auto-promotion configuration
+ */
+export interface AutoPromoteConfig {
+    /** Enable automatic promotion */
+    enabled: boolean;
+    /** Promote snapshots older than this (ms) */
+    olderThan: number;
+    /** Run promotion check interval (ms) */
+    interval?: number;
+}
+/**
+ * Snapshot creation options
+ */
+export interface CreateSnapshotOptions {
+    /** DO ID */
+    doId: string;
+    /** DO type */
+    doType: string;
+    /** Table data to snapshot */
+    tables: Record<string, unknown[]>;
+    /** Parent snapshot ID (for incremental) */
+    parentId?: string;
+    /** CDC events since parent (for incremental) */
+    changes?: CDCEvent[];
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Snapshot list options
+ */
+export interface ListSnapshotsOptions {
+    /** Filter by DO ID */
+    doId?: string;
+    /** Filter by DO type */
+    doType?: string;
+    /** Filter by snapshot type */
+    type?: 'full' | 'incremental';
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort order */
+    orderBy?: 'timestamp' | 'version';
+    /** Sort direction */
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * Snapshot promotion options
+ */
+export interface PromoteOptions {
+    /** Promote snapshots older than this timestamp */
+    olderThan?: number;
+    /** Target tier */
+    targetTier: 'cold';
+    /** Delete from source tier after promotion */
+    deleteAfterPromote?: boolean;
+    /** Maximum snapshots to promote in one batch */
+    batchSize?: number;
+}
+/**
+ * Snapshot restoration options
+ */
+export interface RestoreOptions {
+    /** Target tables to restore (null = all) */
+    tables?: string[];
+    /** Validate checksum before restore */
+    validateChecksum?: boolean;
+}
+/**
+ * Snapshot manager for DO state persistence
+ *
+ * @example
+ * ```typescript
+ * const manager = new SnapshotManager({
+ *   hot: hotStorage,
+ *   cold: coldStorage,
+ *   retention: {
+ *     hot: { maxAge: days(7), maxCount: 100 },
+ *     cold: { maxAge: years(7) },
+ *   },
+ * })
+ *
+ * // Create full snapshot
+ * const snapshot = await manager.create('full', {
+ *   doId: 'do_123',
+ *   doType: 'UserStore',
+ *   tables: { users: [...], orders: [...] },
+ * })
+ *
+ * // Create incremental snapshot
+ * const incremental = await manager.create('incremental', {
+ *   doId: 'do_123',
+ *   doType: 'UserStore',
+ *   tables: { users: [...] },
+ *   parentId: snapshot.id,
+ *   changes: cdcEvents,
+ * })
+ *
+ * // Restore from snapshot
+ * const data = await manager.restore(snapshot.id)
+ *
+ * // Promote old snapshots to cold storage
+ * await manager.promote({ olderThan: days(30), targetTier: 'cold' })
+ *
+ * // Cleanup expired snapshots
+ * await manager.cleanup()
+ * ```
+ */
+export declare class SnapshotManager {
+    private config;
+    /**
+     * Create a new snapshot manager
+     *
+     * @param config - Manager configuration
+     */
+    constructor(config?: SnapshotManagerConfig);
+    /**
+     * Create a new snapshot
+     *
+     * @param type - Snapshot type (full or incremental)
+     * @param options - Snapshot data and options
+     * @returns Created snapshot
+     *
+     * @example
+     * ```typescript
+     * // Full snapshot
+     * const full = await manager.create('full', {
+     *   doId: 'do_123',
+     *   doType: 'Store',
+     *   tables: { items: allItems },
+     * })
+     *
+     * // Incremental snapshot (only changes)
+     * const incr = await manager.create('incremental', {
+     *   doId: 'do_123',
+     *   doType: 'Store',
+     *   tables: { items: changedItems },
+     *   parentId: full.id,
+     *   changes: recentCDCEvents,
+     * })
+     * ```
+     */
+    create(type: 'full' | 'incremental', options: CreateSnapshotOptions): Promise<Snapshot>;
+    /**
+     * Restore data from a snapshot
+     *
+     * @param snapshotId - Snapshot ID to restore
+     * @param options - Restoration options
+     * @returns Restored snapshot data
+     *
+     * @example
+     * ```typescript
+     * const data = await manager.restore(snapshotId)
+     * for (const [table, rows] of Object.entries(data.tables)) {
+     *   await hot.bulkInsert(table, rows)
+     * }
+     * ```
+     */
+    restore(snapshotId: string, options?: RestoreOptions): Promise<Snapshot>;
+    /**
+     * Get a snapshot by ID
+     *
+     * @param snapshotId - Snapshot ID
+     * @returns Snapshot or null if not found
+     */
+    get(snapshotId: string): Promise<Snapshot | null>;
+    /**
+     * List snapshots
+     *
+     * @param options - List options
+     * @returns Array of snapshots
+     */
+    list(options?: ListSnapshotsOptions): Promise<Snapshot[]>;
+    /**
+     * Get the latest snapshot for a DO
+     *
+     * @param doId - DO ID
+     * @param type - Optional type filter
+     * @returns Latest snapshot or null
+     */
+    getLatest(doId: string, type?: 'full' | 'incremental'): Promise<Snapshot | null>;
+    /**
+     * Delete a snapshot
+     *
+     * @param snapshotId - Snapshot ID to delete
+     * @returns True if deleted
+     */
+    delete(snapshotId: string): Promise<boolean>;
+    /**
+     * Promote snapshots to cold storage
+     *
+     * Moves old snapshots from hot to cold tier for cost efficiency.
+     *
+     * @param options - Promotion options
+     * @returns Promotion result
+     *
+     * @example
+     * ```typescript
+     * const result = await manager.promote({
+     *   olderThan: days(30),
+     *   targetTier: 'cold',
+     *   deleteAfterPromote: true,
+     * })
+     * console.log(`Promoted ${result.count} snapshots`)
+     * ```
+     */
+    promote(options: PromoteOptions): Promise<{
+        count: number;
+        bytesPromoted: number;
+        errors: Array<{
+            snapshotId: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * Cleanup expired snapshots according to retention policy
+     *
+     * @returns Cleanup result
+     */
+    cleanup(): Promise<{
+        hotDeleted: number;
+        coldDeleted: number;
+        bytesReclaimed: number;
+    }>;
+    /**
+     * Get the incremental chain for a snapshot
+     *
+     * Returns all snapshots in the chain from the base full snapshot
+     * to the specified snapshot.
+     *
+     * @param snapshotId - Target snapshot ID
+     * @returns Chain of snapshots (oldest first)
+     */
+    getChain(snapshotId: string): Promise<Snapshot[]>;
+    /**
+     * Consolidate incremental chain into a new full snapshot
+     *
+     * Creates a new full snapshot by applying all incrementals,
+     * reducing restore time for long chains.
+     *
+     * @param snapshotId - Latest incremental snapshot ID
+     * @returns New full snapshot
+     */
+    consolidate(snapshotId: string): Promise<Snapshot>;
+    /**
+     * Get next version number for a DO
+     *
+     * @param doId - DO ID
+     * @returns Next version number
+     */
+    private nextVersion;
+    /**
+     * Calculate snapshot size
+     *
+     * @param tables - Table data
+     * @returns Size in bytes
+     */
+    private calculateSize;
+    /**
+     * Count total rows across tables
+     *
+     * @param tables - Table data
+     * @returns Total row count
+     */
+    private countRows;
+    /**
+     * Generate checksum for snapshot data
+     *
+     * @param data - Data to checksum
+     * @returns Checksum string
+     */
+    private generateChecksum;
+}
+/**
+ * Helper: Convert milliseconds to days
+ */
+export declare function days(n: number): number;
+/**
+ * Helper: Convert milliseconds to years
+ */
+export declare function years(n: number): number;
+/**
+ * Helper: Check if snapshot is expired
+ */
+export declare function isExpired(snapshot: Snapshot, maxAge: number): boolean;
+/**
+ * Helper: Get snapshot type from metadata
+ */
+export declare function getSnapshotType(snapshot: Snapshot): 'Full' | 'Incremental';
+//# sourceMappingURL=snapshots.d.ts.map