@dotdo/do 0.1.0

package/dist/db/storage/vortex.js

@@ -0,0 +1,365 @@
+/**
+ * Vortex Blob Format
+ *
+ * Columnar blob encoding optimized for DO SQLite storage.
+ * Provides efficient storage and column-selective reads for analytical queries.
+ *
+ * Format structure:
+ * - Header: magic, version, column count, row count
+ * - Column data: per-column compressed data
+ * - Column index: column metadata and offsets
+ * - Footer: checksum, index offset
+ *
+ * @module @do/core/storage/vortex
+ */
+/**
+ * Vortex format magic bytes ("VRTX")
+ */
+export const VORTEX_MAGIC = new Uint8Array([0x56, 0x52, 0x54, 0x58]);
+/**
+ * Current Vortex format version
+ */
+export const VORTEX_VERSION = 1;
+/**
+ * Vortex encoder for creating columnar blobs
+ *
+ * @example
+ * ```typescript
+ * const schema: VortexSchema = {
+ *   columns: [
+ *     { name: 'id', type: 'string', nullable: false },
+ *     { name: 'name', type: 'string', nullable: false },
+ *     { name: 'age', type: 'int32', nullable: true },
+ *   ],
+ * }
+ *
+ * const encoder = new VortexEncoder(schema)
+ *
+ * // Add rows
+ * encoder.addRow({ id: '1', name: 'Alice', age: 30 })
+ * encoder.addRow({ id: '2', name: 'Bob', age: null })
+ *
+ * // Or add many at once
+ * encoder.addRows(moreUsers)
+ *
+ * // Finish and get blob
+ * const blob = encoder.finish()
+ *
+ * // Store in SQLite
+ * await db.exec('INSERT INTO vortex (data) VALUES (?)', [blob])
+ * ```
+ */
+export class VortexEncoder {
+    schema;
+    options;
+    rows = [];
+    finished = false;
+    /**
+     * Create a new Vortex encoder
+     *
+     * @param schema - Column schema
+     * @param options - Encoder options
+     */
+    constructor(schema, options) {
+        this.schema = schema;
+        this.options = options;
+    }
+    /**
+     * Add a single row
+     *
+     * @param row - Row data (must match schema)
+     * @throws {Error} If encoder is already finished
+     */
+    addRow(row) {
+        if (this.finished) {
+            throw new Error('Encoder is already finished');
+        }
+        this.rows.push(row);
+    }
+    /**
+     * Add multiple rows
+     *
+     * @param rows - Array of row data
+     * @throws {Error} If encoder is already finished
+     */
+    addRows(rows) {
+        if (this.finished) {
+            throw new Error('Encoder is already finished');
+        }
+        this.rows.push(...rows);
+    }
+    /**
+     * Get current row count
+     */
+    get rowCount() {
+        return this.rows.length;
+    }
+    /**
+     * Finish encoding and return the blob
+     *
+     * @returns Vortex blob as ArrayBuffer
+     */
+    finish() {
+        if (this.finished) {
+            throw new Error('Encoder is already finished');
+        }
+        this.finished = true;
+        // TODO: Implement Vortex encoding
+        // 1. Transpose rows to columns
+        // 2. Choose optimal encoding per column
+        // 3. Encode and compress each column
+        // 4. Build column index
+        // 5. Assemble blob with header and footer
+        throw new Error('Not implemented');
+    }
+    /**
+     * Reset encoder for reuse
+     */
+    reset() {
+        this.rows = [];
+        this.finished = false;
+    }
+    /**
+     * Get estimated blob size
+     *
+     * @returns Estimated size in bytes
+     */
+    estimateSize() {
+        // TODO: Implement size estimation
+        throw new Error('Not implemented');
+    }
+}
+/**
+ * Vortex decoder for reading columnar blobs
+ *
+ * @example
+ * ```typescript
+ * // Read blob from SQLite
+ * const blob = await db.query('SELECT data FROM vortex WHERE id = ?', [id])
+ *
+ * // Create decoder
+ * const decoder = new VortexDecoder(blob)
+ *
+ * // Read metadata
+ * const meta = decoder.getMetadata()
+ * console.log(`Rows: ${meta.rowCount}, Columns: ${meta.columnCount}`)
+ *
+ * // Read specific columns only (efficient)
+ * const names = decoder.readColumn<string>('name')
+ * const ages = decoder.readColumn<number>('age')
+ *
+ * // Or read all data
+ * const rows = decoder.readAll()
+ * ```
+ */
+export class VortexDecoder {
+    blob;
+    options;
+    metadata = null;
+    /**
+     * Create a new Vortex decoder
+     *
+     * @param blob - Vortex blob data
+     * @param options - Decoder options
+     */
+    constructor(blob, options) {
+        this.blob = blob;
+        this.options = options;
+    }
+    /**
+     * Get blob metadata
+     *
+     * @returns Vortex metadata
+     */
+    getMetadata() {
+        if (!this.metadata) {
+            this.metadata = this.parseMetadata();
+        }
+        return this.metadata;
+    }
+    /**
+     * Get schema from blob
+     *
+     * @returns Column schema
+     */
+    getSchema() {
+        // TODO: Implement schema extraction
+        throw new Error('Not implemented');
+    }
+    /**
+     * Read a single column
+     *
+     * Efficiently reads only the requested column without
+     * decoding the entire blob.
+     *
+     * @param name - Column name
+     * @returns Column data
+     *
+     * @example
+     * ```typescript
+     * const emails = decoder.readColumn<string>('email')
+     * console.log(emails.values) // ['alice@example.com', ...]
+     * console.log(emails.stats.nullCount)
+     * ```
+     */
+    readColumn(name) {
+        // TODO: Implement column-selective read
+        throw new Error('Not implemented');
+    }
+    /**
+     * Read multiple columns
+     *
+     * @param names - Column names to read
+     * @returns Map of column name to column data
+     */
+    readColumns(names) {
+        // TODO: Implement multi-column read
+        throw new Error('Not implemented');
+    }
+    /**
+     * Read all data as rows
+     *
+     * @returns Array of row objects
+     */
+    readAll() {
+        // TODO: Implement full blob read
+        throw new Error('Not implemented');
+    }
+    /**
+     * Read rows in a range
+     *
+     * @param start - Start row index
+     * @param count - Number of rows to read
+     * @returns Array of row objects
+     */
+    readRange(start, count) {
+        // TODO: Implement range read
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get column statistics without reading data
+     *
+     * @param name - Column name
+     * @returns Column statistics
+     */
+    getColumnStats(name) {
+        // TODO: Implement stats extraction
+        throw new Error('Not implemented');
+    }
+    /**
+     * Validate blob checksum
+     *
+     * @returns True if checksum is valid
+     */
+    validate() {
+        // TODO: Implement checksum validation
+        throw new Error('Not implemented');
+    }
+    /**
+     * Parse metadata from blob header
+     */
+    parseMetadata() {
+        // TODO: Implement metadata parsing
+        throw new Error('Not implemented');
+    }
+}
+/**
+ * Infer schema from sample rows
+ *
+ * @param rows - Sample row data
+ * @returns Inferred schema
+ *
+ * @example
+ * ```typescript
+ * const schema = inferVortexSchema([
+ *   { id: '1', name: 'Alice', age: 30 },
+ *   { id: '2', name: 'Bob', age: null },
+ * ])
+ * // { columns: [
+ * //   { name: 'id', type: 'string', nullable: false },
+ * //   { name: 'name', type: 'string', nullable: false },
+ * //   { name: 'age', type: 'int32', nullable: true },
+ * // ]}
+ * ```
+ */
+export function inferVortexSchema(rows) {
+    if (rows.length === 0) {
+        return { columns: [] };
+    }
+    const columnInfo = new Map();
+    for (const row of rows) {
+        for (const [key, value] of Object.entries(row)) {
+            let info = columnInfo.get(key);
+            if (!info) {
+                info = { types: new Set(), hasNull: false };
+                columnInfo.set(key, info);
+            }
+            if (value === null || value === undefined) {
+                info.hasNull = true;
+            }
+            else {
+                info.types.add(inferVortexType(value));
+            }
+        }
+    }
+    const columns = [];
+    for (const [name, info] of columnInfo) {
+        const types = Array.from(info.types);
+        const type = types.length > 0 ? types[0] : 'string';
+        columns.push({
+            name,
+            type,
+            nullable: info.hasNull,
+            encoding: chooseEncoding(type),
+        });
+    }
+    return { columns };
+}
+/**
+ * Infer Vortex type from JavaScript value
+ */
+function inferVortexType(value) {
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number') {
+        if (Number.isInteger(value)) {
+            return value >= -2147483648 && value <= 2147483647 ? 'int32' : 'int64';
+        }
+        return 'float64';
+    }
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (value instanceof Date)
+        return 'timestamp';
+    if (value instanceof ArrayBuffer || value instanceof Uint8Array)
+        return 'binary';
+    return 'json';
+}
+/**
+ * Choose optimal encoding for a column type
+ */
+function chooseEncoding(type) {
+    switch (type) {
+        case 'string':
+            return 'dictionary';
+        case 'int32':
+        case 'int64':
+        case 'timestamp':
+            return 'delta';
+        case 'boolean':
+            return 'boolean';
+        default:
+            return 'plain';
+    }
+}
+/**
+ * Calculate compression ratio
+ *
+ * @param original - Original size in bytes
+ * @param compressed - Compressed size in bytes
+ * @returns Compression ratio (e.g., 5.0 means 5x smaller)
+ */
+export function compressionRatio(original, compressed) {
+    return compressed > 0 ? original / compressed : 0;
+}
+//# sourceMappingURL=vortex.js.map

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

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

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

@@ -0,0 +1,306 @@
+/**
+ * Warm Storage - Edge Cache API
+ *
+ * Caching tier using Cloudflare's Cache API for frequently accessed data.
+ * Provides ~10ms latency with zero additional cost.
+ *
+ * Features:
+ * - Automatic cache key generation
+ * - TTL management
+ * - Pattern-based invalidation
+ * - Cache-aside pattern support
+ *
+ * @module @do/core/storage/warm
+ */
+/**
+ * Warm storage configuration
+ */
+export interface WarmStorageConfig {
+    /** Default TTL in seconds */
+    defaultTTL?: number;
+    /** Cache key prefix */
+    keyPrefix?: string;
+    /** Maximum serialized value size in bytes */
+    maxValueSize?: number;
+    /** Enable compression for large values */
+    compression?: boolean;
+}
+/**
+ * Cache options for individual operations
+ */
+export interface CacheOptions {
+    /** TTL in seconds (overrides default) */
+    ttl?: number;
+    /** Cache tags for invalidation */
+    tags?: string[];
+    /** Skip compression even if enabled globally */
+    skipCompression?: boolean;
+}
+/**
+ * Cache entry metadata
+ */
+export interface CacheEntry<T> {
+    /** Cached value */
+    value: T;
+    /** When the entry was cached */
+    cachedAt: number;
+    /** When the entry expires */
+    expiresAt: number;
+    /** Cache tags */
+    tags: string[];
+    /** Size in bytes */
+    sizeBytes: number;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Hit rate percentage */
+    hitRate: number;
+    /** Number of invalidations */
+    invalidations: number;
+    /** Total cached entries (estimated) */
+    entries: number;
+}
+/**
+ * Warm storage implementation using Edge Cache API
+ *
+ * @example
+ * ```typescript
+ * const warm = new WarmStorage(caches.default)
+ *
+ * // Cache a value
+ * await warm.set('users:123', user, { ttl: 300 })
+ *
+ * // Get cached value
+ * const cached = await warm.get<User>('users:123')
+ *
+ * // Cache-aside pattern
+ * const user = await warm.getOrSet('users:123', async () => {
+ *   return await hot.get('users', '123')
+ * }, { ttl: 300 })
+ *
+ * // Invalidate by pattern
+ * await warm.invalidate('users:*')
+ * ```
+ */
+export declare class WarmStorage {
+    private readonly cache;
+    private config;
+    private stats;
+    /**
+     * Create a new warm storage instance
+     *
+     * @param cache - Cloudflare Cache API instance
+     * @param config - Cache configuration
+     */
+    constructor(cache: Cache, config?: WarmStorageConfig);
+    /**
+     * Get a value from cache
+     *
+     * @param key - Cache key
+     * @returns Cached value or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const user = await warm.get<User>('users:123')
+     * if (user) {
+     *   console.log('Cache hit:', user.name)
+     * } else {
+     *   console.log('Cache miss')
+     * }
+     * ```
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Get a value with metadata
+     *
+     * @param key - Cache key
+     * @returns Cache entry with metadata or null
+     */
+    getEntry<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Set a value in cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options
+     *
+     * @example
+     * ```typescript
+     * await warm.set('users:123', user, {
+     *   ttl: 600, // 10 minutes
+     *   tags: ['users', 'user:123'],
+     * })
+     * ```
+     */
+    set<T>(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /**
+     * Get or set a cached value (cache-aside pattern)
+     *
+     * If the key exists in cache, returns cached value.
+     * Otherwise, calls the factory function, caches the result, and returns it.
+     *
+     * @param key - Cache key
+     * @param factory - Function to generate value on cache miss
+     * @param options - Cache options
+     * @returns Cached or generated value
+     *
+     * @example
+     * ```typescript
+     * const user = await warm.getOrSet('users:123', async () => {
+     *   return await db.query('SELECT * FROM users WHERE id = ?', [123])
+     * }, { ttl: 300 })
+     * ```
+     */
+    getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Delete a specific key from cache
+     *
+     * @param key - Cache key
+     * @returns True if key was deleted
+     *
+     * @example
+     * ```typescript
+     * await warm.delete('users:123')
+     * ```
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Invalidate cache entries by pattern
+     *
+     * Supports glob-style patterns:
+     * - `users:*` - All keys starting with "users:"
+     * - `*:123` - All keys ending with ":123"
+     * - `users:*:orders` - Keys matching pattern
+     *
+     * @param pattern - Glob pattern for keys to invalidate
+     * @returns Number of entries invalidated
+     *
+     * @example
+     * ```typescript
+     * // Invalidate all user cache entries
+     * await warm.invalidate('users:*')
+     *
+     * // Invalidate specific user's related caches
+     * await warm.invalidate('*:user:123:*')
+     * ```
+     */
+    invalidate(pattern: string): Promise<number>;
+    /**
+     * Invalidate cache entries by tag
+     *
+     * @param tag - Tag to invalidate
+     * @returns Number of entries invalidated
+     *
+     * @example
+     * ```typescript
+     * // Invalidate all entries tagged with 'user:123'
+     * await warm.invalidateByTag('user:123')
+     * ```
+     */
+    invalidateByTag(tag: string): Promise<number>;
+    /**
+     * Check if a key exists in cache
+     *
+     * @param key - Cache key
+     * @returns True if key exists and is not expired
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get multiple values from cache
+     *
+     * @param keys - Array of cache keys
+     * @returns Map of key to value (missing keys omitted)
+     *
+     * @example
+     * ```typescript
+     * const users = await warm.getMany(['users:1', 'users:2', 'users:3'])
+     * for (const [key, user] of users) {
+     *   console.log(key, user.name)
+     * }
+     * ```
+     */
+    getMany<T>(keys: string[]): Promise<Map<string, T>>;
+    /**
+     * Set multiple values in cache
+     *
+     * @param entries - Map of key to value
+     * @param options - Cache options (applied to all entries)
+     *
+     * @example
+     * ```typescript
+     * await warm.setMany(new Map([
+     *   ['users:1', user1],
+     *   ['users:2', user2],
+     * ]), { ttl: 300 })
+     * ```
+     */
+    setMany<T>(entries: Map<string, T>, options?: CacheOptions): Promise<void>;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset cache statistics
+     */
+    resetStats(): void;
+    /**
+     * Build full cache key with prefix
+     *
+     * @param key - User-provided key
+     * @returns Full cache key
+     */
+    private buildKey;
+    /**
+     * Convert cache key to Request object
+     *
+     * Cache API requires Request objects as keys.
+     *
+     * @param key - Cache key
+     * @returns Request object for cache operations
+     */
+    private toRequest;
+    /**
+     * Create Response object for caching
+     *
+     * @param value - Value to cache
+     * @param options - Cache options
+     * @returns Response object with proper headers
+     */
+    private toResponse;
+}
+/**
+ * Cache key builder utility
+ *
+ * Builds consistent cache keys from components.
+ *
+ * @example
+ * ```typescript
+ * const key = cacheKey('users', userId, 'orders')
+ * // Returns: 'users:abc123:orders'
+ * ```
+ */
+export declare function cacheKey(...parts: (string | number)[]): string;
+/**
+ * Parse cache key into components
+ *
+ * @param key - Cache key
+ * @returns Array of key components
+ */
+export declare function parseCacheKey(key: string): string[];
+/**
+ * Check if a key matches a glob pattern
+ *
+ * @param key - Cache key to check
+ * @param pattern - Glob pattern
+ * @returns True if key matches pattern
+ */
+export declare function matchesCachePattern(key: string, pattern: string): boolean;
+//# sourceMappingURL=warm.d.ts.map

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

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