@dotdo/postgres 0.1.0

package/dist/config/memory.js

@@ -0,0 +1,157 @@
+/**
+ * Memory Configuration Constants
+ *
+ * Centralized memory-related constants for Cloudflare Workers environment.
+ * These constants define the memory limits, pressure thresholds, and WASM
+ * characteristics used throughout the postgres package.
+ *
+ * ## Cloudflare Workers Memory Budget
+ *
+ * ```
+ * 128 MB (Worker limit)
+ * - 15 MB (static: WASM + data + JS)
+ * - 16 MB (shared_buffers)
+ * - 16 MB (WAL + buffers)
+ * - 10 MB (PostgreSQL catalog/metadata)
+ * = ~71 MB available for queries, results, and runtime
+ * ```
+ *
+ * @module config/memory
+ */
+// =============================================================================
+// Worker Memory Limits
+// =============================================================================
+/**
+ * Cloudflare Worker memory limit in bytes (128MB).
+ *
+ * This is the hard limit enforced by the Workers runtime. Exceeding this
+ * causes the isolate to be terminated with an OOM error.
+ *
+ * @see https://developers.cloudflare.com/workers/platform/limits/
+ */
+export const WORKER_MEMORY_LIMIT_BYTES = 128 * 1024 * 1024;
+/**
+ * WASM memory page size in bytes (64KB).
+ *
+ * WebAssembly allocates memory in 64KB pages. Used for heap size calculations.
+ *
+ * @see https://webassembly.github.io/spec/core/exec/runtime.html#page-size
+ */
+export const WASM_PAGE_SIZE_BYTES = 64 * 1024;
+/**
+ * Estimated PGLite baseline memory footprint (55MB).
+ *
+ * Typical memory usage after PGLite initialization:
+ * - ~15MB static (WASM binary + data bundle + JS runtime)
+ * - ~40MB PostgreSQL runtime (shared_buffers, WAL, catalog)
+ */
+export const PGLITE_BASELINE_BYTES = (15 + 40) * 1024 * 1024;
+// =============================================================================
+// Memory Pressure Thresholds (Percentages)
+// =============================================================================
+/**
+ * Default warning threshold as percentage of memory limit (70%).
+ *
+ * At this level, the system begins taking protective actions:
+ * - Suggests cache reduction
+ * - May trigger GC hints
+ * - Logs warnings
+ */
+export const DEFAULT_WARNING_THRESHOLD_PERCENT = 70;
+/**
+ * Default critical threshold as percentage of memory limit (85%).
+ *
+ * At this level, aggressive protective actions are taken:
+ * - Pauses new queries
+ * - Triggers aggressive GC
+ * - May unload extensions
+ * - Disables non-essential features
+ */
+export const DEFAULT_CRITICAL_THRESHOLD_PERCENT = 85;
+/**
+ * Default OOM threshold as percentage of memory limit (95%).
+ *
+ * At this level, emergency actions are taken:
+ * - Rejects new queries
+ * - Clears all caches
+ * - May trigger DO restart recommendation
+ */
+export const DEFAULT_OOM_THRESHOLD_PERCENT = 95;
+// =============================================================================
+// Memory Pressure Thresholds (Ratios for observability/memory-metrics.ts)
+// =============================================================================
+/**
+ * Default warning threshold as ratio (0.7 = 70%).
+ *
+ * Used by MemoryMetricsCollector for compatibility with ratio-based APIs.
+ */
+export const DEFAULT_WARNING_THRESHOLD_RATIO = 0.7;
+/**
+ * Default critical threshold as ratio (0.9 = 90%).
+ *
+ * Note: This is higher than the percentage-based threshold because
+ * the observability module uses a more conservative definition.
+ */
+export const DEFAULT_CRITICAL_THRESHOLD_RATIO = 0.9;
+// =============================================================================
+// Memory Spike Detection
+// =============================================================================
+/**
+ * Threshold for detecting memory spikes (10MB).
+ *
+ * A sudden increase of this magnitude between samples triggers a spike event.
+ * Used to detect potential memory leaks or unexpectedly large allocations.
+ */
+export const MEMORY_SPIKE_THRESHOLD_BYTES = 10 * 1024 * 1024;
+// =============================================================================
+// Index Memory Management
+// =============================================================================
+/**
+ * Estimated bytes per storage index entry (120 bytes).
+ *
+ * Breakdown:
+ * - Map entry overhead: ~40 bytes
+ * - StorageIndexEntry object: ~80 bytes (8 fields x 8-10 bytes each)
+ *
+ * Used for memory budgeting of the tiered storage index.
+ */
+export const INDEX_ENTRY_MEMORY_OVERHEAD_BYTES = 120;
+/**
+ * Map internal structure overhead estimate (10%).
+ *
+ * JavaScript Maps have additional overhead for internal hash tables
+ * and bucket structures beyond the per-entry cost.
+ */
+export const MAP_OVERHEAD_ESTIMATE_PERCENT = 0.1;
+/**
+ * Default memory warning threshold for storage index (80%).
+ *
+ * Warns when index memory usage reaches this percentage of the configured
+ * maximum to allow proactive eviction before hitting hard limits.
+ */
+export const DEFAULT_INDEX_MEMORY_WARNING_THRESHOLD = 0.8;
+/**
+ * Target percentage of max memory when evicting due to memory pressure (80%).
+ *
+ * Eviction continues until usage drops to this percentage of the limit
+ * to prevent immediate re-eviction on the next write.
+ */
+export const INDEX_MEMORY_EVICTION_TARGET = 0.8;
+// =============================================================================
+// Memory History Tracking
+// =============================================================================
+/**
+ * Default number of metrics samples to retain in history.
+ *
+ * Used for trend analysis, growth rate calculation, and OOM prediction.
+ * Higher values provide better trend data but use more memory.
+ */
+export const DEFAULT_METRICS_HISTORY_SIZE = 100;
+/**
+ * Average key length assumption for memory estimation (20 characters).
+ *
+ * Used when calculating memory requirements for index capacity planning
+ * when actual key lengths are unknown.
+ */
+export const DEFAULT_AVG_KEY_LENGTH_CHARS = 20;
+//# sourceMappingURL=memory.js.map

package/dist/config/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/config/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,CAAA;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AAE5D,gFAAgF;AAChF,2CAA2C;AAC3C,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAA;AAEnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,EAAE,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAA;AAE/C,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAA;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,GAAG,CAAA;AAEnD,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAE5D,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,GAAG,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAA;AAE/C,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAA"}

package/dist/config/storage.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Storage Configuration Constants
+ *
+ * Centralized constants for the tiered storage system (HOT/WARM/COLD).
+ * These values control promotion/demotion thresholds, TTLs, page sizes,
+ * and circuit breaker behavior.
+ *
+ * ## Storage Tier Architecture
+ *
+ * ```
+ * +-----------+     +-----------+     +-----------+
+ * |    HOT    | --> |   WARM    | --> |   COLD    |
+ * | (Cache)   |     | (DO/SQLite)|    |   (R2)    |
+ * +-----------+     +-----------+     +-----------+
+ *  - FREE           - Persistent     - Durable
+ *  - Ephemeral      - Sync access    - Async
+ *  - Fastest        - Limited size   - Unlimited
+ * ```
+ *
+ * @module config/storage
+ */
+/**
+ * Default page size for storage operations (8KB).
+ *
+ * Matches the standard PostgreSQL page size and PGLite default.
+ * All tiered storage operations work with pages of this size.
+ */
+export declare const DEFAULT_PAGE_SIZE = 8192;
+/**
+ * Default chunk size for DOVFS blob storage (2MB).
+ *
+ * Durable Object storage blobs are chunked at this size.
+ * Balances between:
+ * - Too small: Many chunks, high metadata overhead
+ * - Too large: Slow reads, memory pressure
+ */
+export declare const DEFAULT_CHUNK_SIZE: number;
+/**
+ * Default access count before promoting from COLD to WARM tier (3).
+ *
+ * Prevents unnecessary promotion of rarely accessed data.
+ * Three accesses within the promotion window indicates the data
+ * is likely to be accessed again.
+ */
+export declare const DEFAULT_COLD_TO_WARM_THRESHOLD = 3;
+/**
+ * Default access count before promoting from WARM to HOT tier (5).
+ *
+ * Higher than cold-to-warm to ensure only frequently accessed data
+ * gets cached in the ephemeral HOT tier. This prevents cache churn.
+ */
+export declare const DEFAULT_WARM_TO_HOT_THRESHOLD = 5;
+/**
+ * Default promotion threshold used by tiered-vfs.ts (3).
+ *
+ * Generic promotion threshold for tier upgrades.
+ */
+export declare const DEFAULT_PROMOTION_THRESHOLD = 3;
+/**
+ * Default time window for promotion consideration (60 seconds).
+ *
+ * Accesses must occur within this window to count toward promotion.
+ * Prevents old access patterns from triggering promotion.
+ */
+export declare const DEFAULT_PROMOTION_WINDOW_MS = 60000;
+/**
+ * Default TTL for HOT tier entries (5 minutes).
+ *
+ * Cache entries not accessed within this time are demoted to WARM.
+ * Shorter TTL keeps the cache fresh and prevents stale data.
+ */
+export declare const DEFAULT_HOT_TTL_MS = 300000;
+/**
+ * Default TTL for WARM tier entries (1 hour).
+ *
+ * DO storage entries not accessed within this time are demoted to COLD.
+ * Longer TTL because WARM storage is persistent and cheaper than HOT.
+ */
+export declare const DEFAULT_WARM_TTL_MS = 3600000;
+/**
+ * Default maximum number of pages in HOT tier (1000).
+ *
+ * Limits cache memory usage in Workers environment.
+ * At 8KB per page, this allows ~8MB of cached data.
+ */
+export declare const DEFAULT_MAX_HOT_PAGES = 1000;
+/**
+ * Default prefix for DO storage keys.
+ *
+ * Namespaces page data to avoid collisions with other DO data
+ * like metadata, migration state, etc.
+ */
+export declare const DEFAULT_DO_PREFIX = "page:";
+/**
+ * Default number of entries to evict when index bounds are exceeded (10).
+ *
+ * Batch eviction amortizes overhead across multiple entries.
+ * Larger batches are more efficient but may cause latency spikes.
+ */
+export declare const DEFAULT_INDEX_EVICTION_BATCH_SIZE = 10;
+/**
+ * Default number of consecutive failures before opening circuit (3).
+ *
+ * Prevents cascading failures by temporarily disabling failing tiers.
+ * Three failures provides confidence that the issue is persistent.
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_FAILURE_THRESHOLD = 3;
+/**
+ * Default time before attempting to close an open circuit (30 seconds).
+ *
+ * Allows the failing tier to recover before retrying operations.
+ * After this timeout, the circuit enters half-open state.
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS = 30000;
+/**
+ * Default failure threshold for tiered-vfs.ts circuit breaker (3).
+ */
+export declare const DEFAULT_FAILURE_THRESHOLD = 3;
+/**
+ * Default recovery time before tier is considered healthy again (30 seconds).
+ */
+export declare const DEFAULT_RECOVERY_TIME_MS = 30000;
+/**
+ * Maximum number of failures to track in history (100).
+ *
+ * Limits memory usage for failure tracking while providing
+ * enough history for trend analysis.
+ */
+export declare const DEFAULT_MAX_FAILURE_HISTORY = 100;
+/**
+ * Minimum chunk size for R2 multi-part uploads (1MB).
+ *
+ * R2 requires chunks to be at least 5MB for multi-part uploads,
+ * but for overflow operations we use 1MB as the minimum.
+ */
+export declare const R2_MIN_CHUNK_SIZE: number;
+/**
+ * Maximum chunk size for R2 multi-part uploads (10MB).
+ *
+ * Larger chunks reduce the number of API calls but increase
+ * memory pressure during uploads.
+ */
+export declare const R2_MAX_CHUNK_SIZE: number;
+/**
+ * Target number of chunks for R2 uploads (6).
+ *
+ * Used to calculate optimal chunk size based on file size.
+ */
+export declare const R2_TARGET_CHUNK_COUNT = 6;
+/**
+ * Maximum parallel R2 operations (4).
+ *
+ * Limits concurrent uploads/downloads to prevent overwhelming
+ * the R2 API and memory pressure.
+ */
+export declare const R2_MAX_PARALLEL_OPERATIONS = 4;
+//# sourceMappingURL=storage.d.ts.map

package/dist/config/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/config/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAkB,CAAA;AAMjD;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAAQ,CAAA;AAMhD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAS,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAA;AAM1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAA;AAMxC;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAA;AAMnD;;;;;GAKG;AACH,eAAO,MAAM,yCAAyC,IAAI,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,QAAQ,CAAA;AAE7D;;GAEG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAM9C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAkB,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAmB,CAAA;AAEjD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA"}

package/dist/config/storage.js

@@ -0,0 +1,178 @@
+/**
+ * Storage Configuration Constants
+ *
+ * Centralized constants for the tiered storage system (HOT/WARM/COLD).
+ * These values control promotion/demotion thresholds, TTLs, page sizes,
+ * and circuit breaker behavior.
+ *
+ * ## Storage Tier Architecture
+ *
+ * ```
+ * +-----------+     +-----------+     +-----------+
+ * |    HOT    | --> |   WARM    | --> |   COLD    |
+ * | (Cache)   |     | (DO/SQLite)|    |   (R2)    |
+ * +-----------+     +-----------+     +-----------+
+ *  - FREE           - Persistent     - Durable
+ *  - Ephemeral      - Sync access    - Async
+ *  - Fastest        - Limited size   - Unlimited
+ * ```
+ *
+ * @module config/storage
+ */
+// =============================================================================
+// Page Size Configuration
+// =============================================================================
+/**
+ * Default page size for storage operations (8KB).
+ *
+ * Matches the standard PostgreSQL page size and PGLite default.
+ * All tiered storage operations work with pages of this size.
+ */
+export const DEFAULT_PAGE_SIZE = 8192;
+/**
+ * Default chunk size for DOVFS blob storage (2MB).
+ *
+ * Durable Object storage blobs are chunked at this size.
+ * Balances between:
+ * - Too small: Many chunks, high metadata overhead
+ * - Too large: Slow reads, memory pressure
+ */
+export const DEFAULT_CHUNK_SIZE = 2 * 1024 * 1024;
+// =============================================================================
+// Promotion Thresholds
+// =============================================================================
+/**
+ * Default access count before promoting from COLD to WARM tier (3).
+ *
+ * Prevents unnecessary promotion of rarely accessed data.
+ * Three accesses within the promotion window indicates the data
+ * is likely to be accessed again.
+ */
+export const DEFAULT_COLD_TO_WARM_THRESHOLD = 3;
+/**
+ * Default access count before promoting from WARM to HOT tier (5).
+ *
+ * Higher than cold-to-warm to ensure only frequently accessed data
+ * gets cached in the ephemeral HOT tier. This prevents cache churn.
+ */
+export const DEFAULT_WARM_TO_HOT_THRESHOLD = 5;
+/**
+ * Default promotion threshold used by tiered-vfs.ts (3).
+ *
+ * Generic promotion threshold for tier upgrades.
+ */
+export const DEFAULT_PROMOTION_THRESHOLD = 3;
+/**
+ * Default time window for promotion consideration (60 seconds).
+ *
+ * Accesses must occur within this window to count toward promotion.
+ * Prevents old access patterns from triggering promotion.
+ */
+export const DEFAULT_PROMOTION_WINDOW_MS = 60000;
+// =============================================================================
+// Tier TTLs (Time to Live)
+// =============================================================================
+/**
+ * Default TTL for HOT tier entries (5 minutes).
+ *
+ * Cache entries not accessed within this time are demoted to WARM.
+ * Shorter TTL keeps the cache fresh and prevents stale data.
+ */
+export const DEFAULT_HOT_TTL_MS = 300000;
+/**
+ * Default TTL for WARM tier entries (1 hour).
+ *
+ * DO storage entries not accessed within this time are demoted to COLD.
+ * Longer TTL because WARM storage is persistent and cheaper than HOT.
+ */
+export const DEFAULT_WARM_TTL_MS = 3600000;
+// =============================================================================
+// Tier Capacity Limits
+// =============================================================================
+/**
+ * Default maximum number of pages in HOT tier (1000).
+ *
+ * Limits cache memory usage in Workers environment.
+ * At 8KB per page, this allows ~8MB of cached data.
+ */
+export const DEFAULT_MAX_HOT_PAGES = 1000;
+/**
+ * Default prefix for DO storage keys.
+ *
+ * Namespaces page data to avoid collisions with other DO data
+ * like metadata, migration state, etc.
+ */
+export const DEFAULT_DO_PREFIX = 'page:';
+// =============================================================================
+// Index Eviction Configuration
+// =============================================================================
+/**
+ * Default number of entries to evict when index bounds are exceeded (10).
+ *
+ * Batch eviction amortizes overhead across multiple entries.
+ * Larger batches are more efficient but may cause latency spikes.
+ */
+export const DEFAULT_INDEX_EVICTION_BATCH_SIZE = 10;
+// =============================================================================
+// Circuit Breaker Configuration
+// =============================================================================
+/**
+ * Default number of consecutive failures before opening circuit (3).
+ *
+ * Prevents cascading failures by temporarily disabling failing tiers.
+ * Three failures provides confidence that the issue is persistent.
+ */
+export const DEFAULT_CIRCUIT_BREAKER_FAILURE_THRESHOLD = 3;
+/**
+ * Default time before attempting to close an open circuit (30 seconds).
+ *
+ * Allows the failing tier to recover before retrying operations.
+ * After this timeout, the circuit enters half-open state.
+ */
+export const DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS = 30000;
+/**
+ * Default failure threshold for tiered-vfs.ts circuit breaker (3).
+ */
+export const DEFAULT_FAILURE_THRESHOLD = 3;
+/**
+ * Default recovery time before tier is considered healthy again (30 seconds).
+ */
+export const DEFAULT_RECOVERY_TIME_MS = 30000;
+/**
+ * Maximum number of failures to track in history (100).
+ *
+ * Limits memory usage for failure tracking while providing
+ * enough history for trend analysis.
+ */
+export const DEFAULT_MAX_FAILURE_HISTORY = 100;
+// =============================================================================
+// R2 Overflow Configuration
+// =============================================================================
+/**
+ * Minimum chunk size for R2 multi-part uploads (1MB).
+ *
+ * R2 requires chunks to be at least 5MB for multi-part uploads,
+ * but for overflow operations we use 1MB as the minimum.
+ */
+export const R2_MIN_CHUNK_SIZE = 1 * 1024 * 1024;
+/**
+ * Maximum chunk size for R2 multi-part uploads (10MB).
+ *
+ * Larger chunks reduce the number of API calls but increase
+ * memory pressure during uploads.
+ */
+export const R2_MAX_CHUNK_SIZE = 10 * 1024 * 1024;
+/**
+ * Target number of chunks for R2 uploads (6).
+ *
+ * Used to calculate optimal chunk size based on file size.
+ */
+export const R2_TARGET_CHUNK_COUNT = 6;
+/**
+ * Maximum parallel R2 operations (4).
+ *
+ * Limits concurrent uploads/downloads to prevent overwhelming
+ * the R2 API and memory pressure.
+ */
+export const R2_MAX_PARALLEL_OPERATIONS = 4;
+//# sourceMappingURL=storage.js.map

package/dist/config/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/config/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAA;AAErC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AAEjD,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAA;AAEhD,gFAAgF;AAChF,2BAA2B;AAC3B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAA;AAE1C,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAA;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAA;AAExC,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAA;AAEnD,gFAAgF;AAChF,gCAAgC;AAChC,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAAG,CAAC,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,KAAK,CAAA;AAE7D;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAA;AAE1C;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAA;AAE9C,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAA"}

package/dist/config/streaming.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Streaming Configuration Constants
+ *
+ * Centralized constants for query streaming and memory-bounded streams.
+ * These values control buffer sizes, water marks for backpressure, and
+ * batch sizes for cursor-based query streaming.
+ *
+ * ## Water Mark System
+ *
+ * The streaming system uses a dual water mark approach to prevent thrashing:
+ *
+ * ```
+ * Memory
+ *   ^
+ *   |  memoryLimit -------- Hard limit (throws OOM)
+ *   |
+ *   |  highWaterMark ------ Pause point
+ *   |       |
+ *   |       v  (paused zone)
+ *   |  lowWaterMark ------- Resume point
+ *   |       |
+ *   |       v  (normal zone)
+ *   +-------------------------> Time
+ * ```
+ *
+ * @module config/streaming
+ */
+/**
+ * Default memory limit for streaming operations (50MB).
+ *
+ * This is the hard limit that triggers StreamingOOMError when exceeded.
+ * Set lower than Worker limit to leave room for other operations.
+ *
+ * Calculation:
+ * - 128MB Worker limit
+ * - ~55MB PGLite baseline
+ * - ~23MB buffer for other operations
+ * = ~50MB available for streaming
+ */
+export declare const DEFAULT_STREAMING_MEMORY_LIMIT: number;
+/**
+ * Default high water mark for streaming backpressure (10MB).
+ *
+ * When buffered data exceeds this threshold, the stream pauses the producer
+ * and waits for the consumer to catch up. This prevents unbounded memory growth.
+ *
+ * Set at 20% of memory limit to provide early warning without being too aggressive.
+ */
+export declare const DEFAULT_HIGH_WATER_MARK: number;
+/**
+ * Default low water mark for streaming resume (5MB).
+ *
+ * When buffered data drops below this threshold after being paused,
+ * the stream resumes producing. The gap between high and low marks
+ * prevents rapid pause/resume oscillation (thrashing).
+ *
+ * Set at 10% of memory limit (50% of high water mark).
+ */
+export declare const DEFAULT_LOW_WATER_MARK: number;
+/**
+ * Default number of rows per cursor fetch batch (100).
+ *
+ * Balance between:
+ * - Too small: High overhead from many FETCH calls
+ * - Too large: Memory spikes, poor backpressure responsiveness
+ *
+ * 100 rows is a good default for typical row sizes (1-10KB).
+ * Adjust based on actual row sizes in your workload.
+ */
+export declare const DEFAULT_BATCH_SIZE = 100;
+/**
+ * Default cursor name prefix for streaming queries.
+ *
+ * Combined with a unique suffix (timestamp or counter) to create
+ * cursor names like 'pglite_cursor_1234567890'.
+ */
+export declare const DEFAULT_CURSOR_PREFIX = "pglite_cursor";
+/**
+ * Fallback row size estimate when serialization fails (1KB).
+ *
+ * Used by estimateRowsMemory() when JSON.stringify() fails due to
+ * circular references or other issues.
+ */
+export declare const FALLBACK_ROW_SIZE_BYTES = 1024;
+/**
+ * Base memory overhead per JavaScript object (64 bytes).
+ *
+ * Includes object header, hidden class pointer, and other V8 internals.
+ * Used for accurate memory tracking in buffer pools.
+ */
+export declare const OBJECT_BASE_OVERHEAD = 64;
+/**
+ * Bytes per character in JavaScript strings (2 bytes).
+ *
+ * JavaScript uses UTF-16 encoding, so each character takes 2 bytes.
+ * Used for string memory estimation.
+ */
+export declare const BYTES_PER_CHAR = 2;
+/**
+ * String header overhead in bytes (24 bytes).
+ *
+ * V8 string objects have a header with length, hash, and encoding info.
+ */
+export declare const STRING_HEADER_OVERHEAD = 24;
+/**
+ * Base overhead for JavaScript arrays (24 bytes).
+ *
+ * Includes array length and pointer to backing store.
+ */
+export declare const ARRAY_BASE_OVERHEAD = 24;
+/**
+ * Per-element overhead in JavaScript arrays (8 bytes).
+ *
+ * Each array element is a tagged pointer (8 bytes on 64-bit).
+ */
+export declare const ARRAY_ELEMENT_OVERHEAD = 8;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/config/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/config/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,QAAmB,CAAA;AAM9D;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,QAAmB,CAAA;AAEvD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAAkB,CAAA;AAMrD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAA;AAMpD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAM3C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAA;AAExC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA"}