gitx.do 0.0.1 → 0.0.3

package/dist/tiered/read-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-path.d.ts","sourceRoot":"","sources":["../../src/tiered/read-path.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"read-path.d.ts","sourceRoot":"","sources":["../../src/tiered/read-path.ts"],"names":[],"mappings":"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"}

package/dist/tiered/read-path.js

@@ -1,20 +1,76 @@
 /**
- * Tiered Read Path
+ * @fileoverview Tiered Read Path Module
  *
- * Implements reading objects from the multi-tier storage system:
- * - Hot tier: Durable Object SQLite (fastest, local)
- * - Warm tier: R2 object storage (medium latency, packed objects)
- * - Cold tier: Analytics/Parquet (highest latency, cold storage)
+ * @description
+ * Implements reading objects from a multi-tier storage system designed for
+ * Git object storage. The tiered approach optimizes for both performance and
+ * cost by organizing data across multiple storage layers with different
+ * characteristics:
  *
- * Features:
- * - Tier fallback on miss
- * - Cache promotion (read-through caching)
- * - Configurable promotion policies
+ * **Storage Tiers:**
+ * - **Hot tier**: Durable Object SQLite (fastest, local, highest cost)
+ * - **Warm tier**: R2 object storage (medium latency, packed objects)
+ * - **Cold tier**: Analytics/Parquet (highest latency, lowest cost)
  *
- * gitdo-aaw: Tiered read path implementation
+ * **Features:**
+ * - Automatic tier fallback on cache miss
+ * - Read-through caching with promotion to hotter tiers
+ * - Configurable promotion policies (aggressive, conservative, none)
+ * - Latency tracking for performance monitoring
+ *
+ * **Architecture:**
+ * The TieredReader orchestrates reads across all tiers, attempting to serve
+ * data from the fastest available tier while optionally promoting frequently
+ * accessed objects to faster tiers.
+ *
+ * @example
+ * ```typescript
+ * // Create a tiered reader with all backends
+ * const reader = new TieredReader(
+ *   hotBackend,
+ *   warmBackend,
+ *   coldBackend,
+ *   {
+ *     hot: { enabled: true, maxSize: 1024 * 1024 },
+ *     warm: { enabled: true },
+ *     cold: { enabled: true },
+ *     promotionPolicy: 'aggressive'
+ *   }
+ * )
+ *
+ * // Read an object - will try hot -> warm -> cold
+ * const result = await reader.read('abc123...')
+ * if (result.object) {
+ *   console.log(`Found in ${result.tier} tier`)
+ *   console.log(`Latency: ${result.latencyMs}ms`)
+ *   if (result.promoted) {
+ *     console.log('Object was promoted to hot tier')
+ *   }
+ * }
+ * ```
+ *
+ * @module tiered/read-path
+ * @see {@link TieredReader} - Main implementation class
+ * @see {@link TieredStorageConfig} - Configuration options
  */
 /**
- * Validates a SHA-1 hash
+ * Validates a SHA-1 hash string.
+ *
+ * @description
+ * Checks that the provided string is a valid 40-character hexadecimal
+ * SHA-1 hash. Used internally to validate input before querying storage.
+ *
+ * @param sha - The string to validate
+ * @returns true if the string is a valid SHA-1 hash, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidSha('abc123')  // false - too short
+ * isValidSha('a1b2c3d4e5f678901234567890abcdef12345678')  // true
+ * isValidSha('xyz123...')  // false - invalid characters
+ * ```
+ *
+ * @internal
  */
 function isValidSha(sha) {
     if (!sha || sha.length !== 40) {
@@ -23,16 +79,122 @@ function isValidSha(sha) {
     return /^[0-9a-f]{40}$/i.test(sha);
 }
 /**
- * TieredReader - Main implementation of the tiered read path
+ * TieredReader - Main implementation of the tiered read path.
+ *
+ * @description
+ * TieredReader orchestrates reads across multiple storage tiers (hot, warm, cold),
+ * implementing automatic fallback and optional promotion to hotter tiers. It provides
+ * a unified interface for reading Git objects regardless of which tier they reside in.
+ *
+ * **Read Algorithm:**
+ * 1. Validate the SHA-1 hash
+ * 2. If hot tier enabled, attempt to read from hot tier
+ * 3. If not found and warm tier enabled, attempt warm tier
+ * 4. If not found and cold tier enabled, attempt cold tier
+ * 5. If found in warm/cold, optionally promote to hot tier
+ * 6. Return result with object, source tier, and metrics
+ *
+ * **Promotion Policies:**
+ * - `aggressive`: Immediately promote any object read from warm/cold to hot
+ * - `conservative`: Reserved for future implementation (repeated access tracking)
+ * - `none`: Never automatically promote objects
+ *
+ * **Error Handling:**
+ * Individual tier failures are silently caught and the next tier is tried.
+ * This ensures graceful degradation when a tier is temporarily unavailable.
+ *
+ * @example
+ * ```typescript
+ * // Create backends for each tier
+ * const hotBackend = new SqliteHotBackend(db)
+ * const warmBackend = new R2WarmBackend(r2)
+ * const coldBackend = new ParquetColdBackend(parquet)
+ *
+ * // Configure the tiered storage
+ * const config: TieredStorageConfig = {
+ *   hot: { enabled: true, maxSize: 1024 * 1024 },
+ *   warm: { enabled: true },
+ *   cold: { enabled: true },
+ *   promotionPolicy: 'aggressive'
+ * }
  *
- * Reads objects from multiple storage tiers with fallback logic
- * and optional promotion to hotter tiers.
+ * // Create the reader
+ * const reader = new TieredReader(hotBackend, warmBackend, coldBackend, config)
+ *
+ * // Read an object
+ * const result = await reader.read('a1b2c3d4e5f678901234567890abcdef12345678')
+ *
+ * if (result.object) {
+ *   console.log(`Object type: ${result.object.type}`)
+ *   console.log(`Size: ${result.object.size} bytes`)
+ *   console.log(`Served from: ${result.tier} tier`)
+ *   console.log(`Latency: ${result.latencyMs}ms`)
+ *
+ *   if (result.promoted) {
+ *     console.log('Object was promoted to hot tier')
+ *   }
+ * } else {
+ *   console.log('Object not found in any tier')
+ * }
+ *
+ * // Direct tier access
+ * const hotOnly = await reader.readFromHot(sha)
+ * const warmOnly = await reader.readFromWarm(sha)
+ * const coldOnly = await reader.readFromCold(sha)
+ *
+ * // Manual promotion
+ * if (warmOnly) {
+ *   await reader.promoteToHot(sha, warmOnly)
+ * }
+ * ```
+ *
+ * @class TieredReader
+ * @implements {TieredObjectStore}
  */
 export class TieredReader {
+    /**
+     * Backend for the hot storage tier (Durable Object SQLite).
+     * @private
+     */
     hotBackend;
+    /**
+     * Backend for the warm storage tier (R2 object storage).
+     * @private
+     */
     warmBackend;
+    /**
+     * Backend for the cold storage tier (Analytics/Parquet).
+     * @private
+     */
     coldBackend;
+    /**
+     * Configuration for all tiers and promotion policy.
+     * @private
+     */
     config;
+    /**
+     * Creates a new TieredReader instance.
+     *
+     * @param hotBackend - Backend for the hot tier (Durable Object SQLite)
+     * @param warmBackend - Backend for the warm tier (R2)
+     * @param coldBackend - Backend for the cold tier (Parquet)
+     * @param config - Configuration for all tiers and promotion policy
+     *
+     * @example
+     * ```typescript
+     * const reader = new TieredReader(
+     *   hotBackend,
+     *   warmBackend,
+     *   coldBackend,
+     *   {
+     *     hot: { enabled: true, maxSize: 1024 * 1024 },
+     *     warm: { enabled: true },
+     *     cold: { enabled: true },
+     *     promotionPolicy: 'aggressive'
+     *   }
+     * )
+     * ```
+     */
     constructor(hotBackend, warmBackend, coldBackend, config) {
         this.hotBackend = hotBackend;
         this.warmBackend = warmBackend;
@@ -40,10 +202,39 @@ export class TieredReader {
         this.config = config;
     }
     /**
-     * Read an object from the tiered storage system
+     * Reads an object from the tiered storage system.
+     *
+     * @description
+     * Attempts to read the object from each enabled tier in order
+     * (hot -> warm -> cold), returning as soon as the object is found.
+     * Objects found in warm or cold tiers may be promoted to hot tier
+     * based on the configured promotion policy.
+     *
+     * **Invalid SHA Handling:**
+     * If the SHA is invalid (not 40 hex characters), returns immediately
+     * with null object and no tier lookup is performed.
      *
-     * Tries each enabled tier in order: hot -> warm -> cold
-     * Promotes objects to hot tier based on promotion policy
+     * **Error Handling:**
+     * If a tier fails (throws an error), the error is caught silently
+     * and the next tier is attempted. This provides graceful degradation.
+     *
+     * @param sha - The 40-character SHA-1 hash of the object to read
+     * @returns Promise resolving to the read result with object, tier, and metrics
+     *
+     * @example
+     * ```typescript
+     * const result = await reader.read('a1b2c3d4e5f678901234567890abcdef12345678')
+     *
+     * if (result.object) {
+     *   // Object found
+     *   console.log(`Type: ${result.object.type}`)
+     *   console.log(`Tier: ${result.tier}`)
+     *   console.log(`Promoted: ${result.promoted}`)
+     * } else {
+     *   // Object not found
+     *   console.log(`Search took ${result.latencyMs}ms`)
+     * }
+     * ```
      */
     async read(sha) {
         const startTime = performance.now();
@@ -118,7 +309,25 @@ export class TieredReader {
         };
     }
     /**
-     * Read an object directly from the hot tier
+     * Reads an object directly from the hot tier only.
+     *
+     * @description
+     * Bypasses the tier fallback logic to read directly from the hot tier.
+     * Useful for checking if an object is already in the hot cache.
+     * Errors are caught and null is returned.
+     *
+     * @param sha - The 40-character SHA-1 hash of the object
+     * @returns Promise resolving to the object or null if not in hot tier
+     *
+     * @example
+     * ```typescript
+     * const cached = await reader.readFromHot(sha)
+     * if (cached) {
+     *   console.log('Object is in hot cache')
+     * } else {
+     *   console.log('Object not in hot cache')
+     * }
+     * ```
      */
     async readFromHot(sha) {
         try {
@@ -129,7 +338,24 @@ export class TieredReader {
         }
     }
     /**
-     * Read an object directly from the warm tier
+     * Reads an object directly from the warm tier only.
+     *
+     * @description
+     * Bypasses the tier fallback logic to read directly from the warm tier.
+     * Does not trigger automatic promotion to hot tier.
+     * Errors are caught and null is returned.
+     *
+     * @param sha - The 40-character SHA-1 hash of the object
+     * @returns Promise resolving to the object or null if not in warm tier
+     *
+     * @example
+     * ```typescript
+     * const warm = await reader.readFromWarm(sha)
+     * if (warm) {
+     *   // Manually promote if desired
+     *   await reader.promoteToHot(sha, warm)
+     * }
+     * ```
      */
     async readFromWarm(sha) {
         try {
@@ -140,7 +366,23 @@ export class TieredReader {
         }
     }
     /**
-     * Read an object directly from the cold tier
+     * Reads an object directly from the cold tier only.
+     *
+     * @description
+     * Bypasses the tier fallback logic to read directly from the cold tier.
+     * Does not trigger automatic promotion to hotter tiers.
+     * Errors are caught and null is returned.
+     *
+     * @param sha - The 40-character SHA-1 hash of the object
+     * @returns Promise resolving to the object or null if not in cold tier
+     *
+     * @example
+     * ```typescript
+     * const cold = await reader.readFromCold(sha)
+     * if (cold) {
+     *   console.log(`Found in cold storage, created at: ${cold.createdAt}`)
+     * }
+     * ```
      */
     async readFromCold(sha) {
         try {
@@ -151,24 +393,65 @@ export class TieredReader {
         }
     }
     /**
-     * Manually promote an object to the hot tier
+     * Manually promotes an object to the hot tier.
+     *
+     * @description
+     * Copies the provided object to the hot tier storage. This is useful for
+     * pre-warming the cache or manually controlling tier placement. No size
+     * or policy checks are performed - the object is always written.
+     *
+     * @param sha - The 40-character SHA-1 hash of the object
+     * @param object - The complete stored object to promote
+     * @returns Promise that resolves when promotion is complete
+     * @throws Error if the hot tier write fails
+     *
+     * @example
+     * ```typescript
+     * // Pre-warm the hot cache
+     * const objects = await reader.query({ type: 'commit' })
+     * for (const obj of objects) {
+     *   await reader.promoteToHot(obj.sha, obj)
+     * }
+     * ```
      */
     async promoteToHot(sha, object) {
         await this.hotBackend.put(sha, object);
     }
     /**
-     * Get the current configuration
+     * Returns the current storage configuration.
+     *
+     * @description
+     * Returns the configuration object passed to the constructor.
+     * Useful for inspecting current settings or debugging.
+     *
+     * @returns The tiered storage configuration
+     *
+     * @example
+     * ```typescript
+     * const config = reader.getConfig()
+     * console.log(`Promotion policy: ${config.promotionPolicy}`)
+     * console.log(`Hot tier enabled: ${config.hot.enabled}`)
+     * ```
      */
     getConfig() {
         return this.config;
     }
     /**
-     * Try to promote an object to the hot tier based on policy
+     * Attempts to promote an object to the hot tier based on policy.
+     *
+     * @description
+     * Called internally when an object is found in warm or cold tier.
+     * Decides whether to promote based on:
+     * 1. Hot tier being enabled
+     * 2. Promotion policy (aggressive promotes, conservative/none don't)
+     * 3. Object size being within hot tier's maxSize limit
+     *
+     * @param sha - The object's SHA-1 hash
+     * @param object - The object to potentially promote
+     * @param _sourceTier - The tier the object was read from (for future use)
+     * @returns true if promotion was successful, false otherwise
      *
-     * @param sha - The object's SHA
-     * @param object - The object to promote
-     * @param sourceTier - The tier the object was read from
-     * @returns true if promotion was successful
+     * @private
      */
     async tryPromote(sha, object, _sourceTier) {
         // Check if hot tier is enabled

package/dist/tiered/read-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-path.js","sourceRoot":"","sources":["../../src/tiered/read-path.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"read-path.js","sourceRoot":"","sources":["../../src/tiered/read-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAmhBH;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,MAAM,OAAO,YAAY;IACvB;;;OAGG;IACK,UAAU,CAAgB;IAElC;;;OAGG;IACK,WAAW,CAAiB;IAEpC;;;OAGG;IACK,WAAW,CAAiB;IAEpC;;;OAGG;IACK,MAAM,CAAqB;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YACE,UAA0B,EAC1B,WAA4B,EAC5B,WAA4B,EAC5B,MAA2B;QAE3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;QAEnC,eAAe;QACf,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,IAAI,EAAE,IAAI;gBACV,QAAQ,EAAE,KAAK;gBACf,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;aACzC,CAAA;QACH,CAAC;QAED,qBAAqB;QACrB,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;gBAC1C,IAAI,GAAG,EAAE,CAAC;oBACR,OAAO;wBACL,MAAM,EAAE,GAAG;wBACX,IAAI,EAAE,KAAK;wBACX,QAAQ,EAAE,KAAK;wBACf,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;qBACzC,CAAA;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,yCAAyC;YAC3C,CAAC;QACH,CAAC;QAED,gBAAgB;QAChB,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;gBAC3C,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;oBACxD,OAAO;wBACL,MAAM,EAAE,GAAG;wBACX,IAAI,EAAE,MAAM;wBACZ,QAAQ;wBACR,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;qBACzC,CAAA;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,0CAA0C;YAC5C,CAAC;QACH,CAAC;QAED,gBAAgB;QAChB,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;gBAC3C,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;oBACxD,OAAO;wBACL,MAAM,EAAE,GAAG;wBACX,IAAI,EAAE,MAAM;wBACZ,QAAQ;wBACR,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;qBACzC,CAAA;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,mBAAmB;YACrB,CAAC;QACH,CAAC;QAED,+BAA+B;QAC/B,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,KAAK;YACf,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;SACzC,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,WAAW,CAAC,GAAW;QAC3B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,YAAY,CAAC,GAAW;QAC5B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,YAAY,CAAC,GAAW;QAC5B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,YAAY,CAAC,GAAW,EAAE,MAAoB;QAClD,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACxC,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACK,KAAK,CAAC,UAAU,CACtB,GAAW,EACX,MAAoB,EACpB,WAA4B;QAE5B,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,yBAAyB;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,KAAK,MAAM,EAAE,CAAC;YAC3C,OAAO,KAAK,CAAA;QACd,CAAC;QAED,sEAAsE;QACtE,mEAAmE;QACnE,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,KAAK,cAAc,EAAE,CAAC;YACnD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,gCAAgC;QAChC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACnF,OAAO,KAAK,CAAA;QACd,CAAC;QAED,iBAAiB;QACjB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;YACtC,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;YACjD,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;CACF;AAED,2EAA2E;AAC3E,OAAO,EAAE,YAAY,IAAI,qBAAqB,EAAE,CAAA"}