gitx.do 0.0.1 → 0.0.3

package/dist/durable-object/schema.d.ts

@@ -1,17 +1,205 @@
+/**
+ * @fileoverview Database Schema for Git Object Storage
+ *
+ * This module defines the SQLite schema used for storing Git objects and related
+ * data in Cloudflare Durable Objects. It provides schema initialization, version
+ * management, and validation.
+ *
+ * **Tables**:
+ * - `objects`: Main Git object storage (blobs, trees, commits, tags)
+ * - `object_index`: Tiered storage location index
+ * - `hot_objects`: Frequently accessed objects cache
+ * - `wal`: Write-ahead log for durability
+ * - `refs`: Git references (branches, tags, HEAD)
+ *
+ * @module durable-object/schema
+ *
+ * @example
+ * ```typescript
+ * import { SchemaManager, DurableObjectStorage } from './durable-object/schema'
+ *
+ * // Initialize schema on first access
+ * const schemaManager = new SchemaManager(storage)
+ * await schemaManager.initializeSchema()
+ *
+ * // Verify schema is valid
+ * if (await schemaManager.validateSchema()) {
+ *   console.log('Schema is ready')
+ * }
+ * ```
+ */
+/**
+ * Interface representing Durable Object storage with SQL capabilities.
+ *
+ * @description
+ * Abstraction over Cloudflare's Durable Object storage that provides
+ * SQLite access. This interface allows for easy mocking in tests.
+ *
+ * @example
+ * ```typescript
+ * const storage: DurableObjectStorage = {
+ *   sql: {
+ *     exec(query: string, ...params: unknown[]) {
+ *       // Execute SQL and return results
+ *       return { toArray: () => [] }
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export interface DurableObjectStorage {
+    /**
+     * SQL execution interface.
+     *
+     * @description
+     * Provides access to SQLite query execution within the Durable Object.
+     */
     sql: {
+        /**
+         * Execute a SQL query with optional parameters.
+         *
+         * @param query - SQL query string (can use ? placeholders)
+         * @param params - Parameter values for placeholders
+         * @returns Result object with toArray() method for reading rows
+         *
+         * @example
+         * ```typescript
+         * const result = storage.sql.exec(
+         *   'SELECT * FROM objects WHERE sha = ?',
+         *   'abc123...'
+         * )
+         * const rows = result.toArray()
+         * ```
+         */
         exec(query: string, ...params: unknown[]): {
             toArray(): unknown[];
         };
     };
 }
+/**
+ * Current schema version number.
+ *
+ * @description
+ * Increment this when making schema changes that require migration.
+ * Used for schema validation and upgrade detection.
+ *
+ * @example
+ * ```typescript
+ * const version = await schemaManager.getSchemaVersion()
+ * if (version < SCHEMA_VERSION) {
+ *   // Perform migration
+ * }
+ * ```
+ */
 export declare const SCHEMA_VERSION = 1;
+/**
+ * Complete SQL schema definition.
+ *
+ * @description
+ * Contains all CREATE TABLE and CREATE INDEX statements for the
+ * Git object storage database. Uses IF NOT EXISTS for idempotency.
+ *
+ * **Tables**:
+ * - `objects`: Primary object storage with SHA as primary key
+ * - `object_index`: Tracks object locations across storage tiers
+ * - `hot_objects`: Cache for frequently accessed objects
+ * - `wal`: Write-ahead log for crash recovery
+ * - `refs`: Git references (branches, tags, symbolic refs)
+ *
+ * **Indexes**:
+ * - `idx_objects_type`: Fast lookup by object type
+ * - `idx_wal_flushed`: Find unflushed WAL entries
+ * - `idx_hot_objects_accessed`: LRU eviction ordering
+ */
 export declare const SCHEMA_SQL = "\n-- Git objects (blobs, trees, commits, tags)\nCREATE TABLE IF NOT EXISTS objects (sha TEXT PRIMARY KEY, type TEXT NOT NULL, size INTEGER NOT NULL, data BLOB NOT NULL, created_at INTEGER);\n\n-- Object location index for tiered storage\nCREATE TABLE IF NOT EXISTS object_index (sha TEXT PRIMARY KEY, tier TEXT NOT NULL DEFAULT 'hot', location TEXT NOT NULL DEFAULT 'local', size INTEGER, type TEXT);\n\n-- Hot objects cache\nCREATE TABLE IF NOT EXISTS hot_objects (sha TEXT PRIMARY KEY, type TEXT NOT NULL, data BLOB NOT NULL, accessed_at INTEGER, created_at INTEGER);\n\n-- Write-ahead log\nCREATE TABLE IF NOT EXISTS wal (id INTEGER PRIMARY KEY AUTOINCREMENT, operation TEXT NOT NULL, payload BLOB NOT NULL, created_at INTEGER, flushed INTEGER DEFAULT 0);\n\n-- Refs table\nCREATE TABLE IF NOT EXISTS refs (name TEXT PRIMARY KEY, target TEXT NOT NULL, type TEXT DEFAULT 'sha', updated_at INTEGER);\n\n-- Indexes\nCREATE INDEX IF NOT EXISTS idx_objects_type ON objects(type);\nCREATE INDEX IF NOT EXISTS idx_wal_flushed ON wal(flushed);\nCREATE INDEX IF NOT EXISTS idx_hot_objects_accessed ON hot_objects(accessed_at);\n";
+/**
+ * Manager for database schema initialization and validation.
+ *
+ * @description
+ * Handles schema lifecycle including initialization, version checking,
+ * and validation. Should be used when first accessing a Durable Object
+ * to ensure the schema is properly set up.
+ *
+ * @example
+ * ```typescript
+ * class GitDurableObject implements DurableObject {
+ *   private schemaManager: SchemaManager
+ *   private initialized = false
+ *
+ *   constructor(state: DurableObjectState) {
+ *     this.schemaManager = new SchemaManager(state.storage)
+ *   }
+ *
+ *   private async ensureInitialized() {
+ *     if (!this.initialized) {
+ *       await this.schemaManager.initializeSchema()
+ *       this.initialized = true
+ *     }
+ *   }
+ *
+ *   async fetch(request: Request) {
+ *     await this.ensureInitialized()
+ *     // ... handle request
+ *   }
+ * }
+ * ```
+ */
 export declare class SchemaManager {
     private storage;
+    /**
+     * Create a new SchemaManager.
+     *
+     * @param storage - Durable Object storage interface
+     */
     constructor(storage: DurableObjectStorage);
+    /**
+     * Initialize the database schema.
+     *
+     * @description
+     * Creates all required tables and indexes if they don't exist.
+     * This operation is idempotent - safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * await schemaManager.initializeSchema()
+     * ```
+     */
     initializeSchema(): Promise<void>;
+    /**
+     * Get the current schema version.
+     *
+     * @description
+     * Returns the schema version if valid, or 0 if schema is missing/invalid.
+     * Use this to detect when schema migration is needed.
+     *
+     * @returns Schema version number (0 if invalid/missing)
+     *
+     * @example
+     * ```typescript
+     * const version = await schemaManager.getSchemaVersion()
+     * console.log(`Schema version: ${version}`)
+     * ```
+     */
     getSchemaVersion(): Promise<number>;
+    /**
+     * Validate that all required tables exist.
+     *
+     * @description
+     * Checks the sqlite_master table to verify all required tables
+     * are present. Returns false if any tables are missing.
+     *
+     * @returns True if schema is valid and complete
+     *
+     * @example
+     * ```typescript
+     * if (await schemaManager.validateSchema()) {
+     *   console.log('Schema is valid')
+     * } else {
+     *   console.log('Schema needs initialization')
+     *   await schemaManager.initializeSchema()
+     * }
+     * ```
+     */
     validateSchema(): Promise<boolean>;
 }
 //# sourceMappingURL=schema.d.ts.map

package/dist/durable-object/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/durable-object/schema.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE;QACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;YAAE,OAAO,IAAI,OAAO,EAAE,CAAA;SAAE,CAAA;KACpE,CAAA;CACF;AAED,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B,eAAO,MAAM,UAAU,umCAoBtB,CAAA;AAID,qBAAa,aAAa;IACZ,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAE3C,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAKnC,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CASzC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/durable-object/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,GAAG,EAAE;QACH;;;;;;;;;;;;;;;WAeG;QACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;YAAE,OAAO,IAAI,OAAO,EAAE,CAAA;SAAE,CAAA;KACpE,CAAA;CACF;AAMD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU,umCAoBtB,CAAA;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,aAAa;IAMZ,OAAO,CAAC,OAAO;IAL3B;;;;OAIG;gBACiB,OAAO,EAAE,oBAAoB;IAEjD;;;;;;;;;;;OAWG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAKzC;;;;;;;;;;;;;;;;;;OAkBG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CASzC"}

package/dist/durable-object/schema.js

@@ -1,4 +1,71 @@
+/**
+ * @fileoverview Database Schema for Git Object Storage
+ *
+ * This module defines the SQLite schema used for storing Git objects and related
+ * data in Cloudflare Durable Objects. It provides schema initialization, version
+ * management, and validation.
+ *
+ * **Tables**:
+ * - `objects`: Main Git object storage (blobs, trees, commits, tags)
+ * - `object_index`: Tiered storage location index
+ * - `hot_objects`: Frequently accessed objects cache
+ * - `wal`: Write-ahead log for durability
+ * - `refs`: Git references (branches, tags, HEAD)
+ *
+ * @module durable-object/schema
+ *
+ * @example
+ * ```typescript
+ * import { SchemaManager, DurableObjectStorage } from './durable-object/schema'
+ *
+ * // Initialize schema on first access
+ * const schemaManager = new SchemaManager(storage)
+ * await schemaManager.initializeSchema()
+ *
+ * // Verify schema is valid
+ * if (await schemaManager.validateSchema()) {
+ *   console.log('Schema is ready')
+ * }
+ * ```
+ */
+// ============================================================================
+// Schema Constants
+// ============================================================================
+/**
+ * Current schema version number.
+ *
+ * @description
+ * Increment this when making schema changes that require migration.
+ * Used for schema validation and upgrade detection.
+ *
+ * @example
+ * ```typescript
+ * const version = await schemaManager.getSchemaVersion()
+ * if (version < SCHEMA_VERSION) {
+ *   // Perform migration
+ * }
+ * ```
+ */
 export const SCHEMA_VERSION = 1;
+/**
+ * Complete SQL schema definition.
+ *
+ * @description
+ * Contains all CREATE TABLE and CREATE INDEX statements for the
+ * Git object storage database. Uses IF NOT EXISTS for idempotency.
+ *
+ * **Tables**:
+ * - `objects`: Primary object storage with SHA as primary key
+ * - `object_index`: Tracks object locations across storage tiers
+ * - `hot_objects`: Cache for frequently accessed objects
+ * - `wal`: Write-ahead log for crash recovery
+ * - `refs`: Git references (branches, tags, symbolic refs)
+ *
+ * **Indexes**:
+ * - `idx_objects_type`: Fast lookup by object type
+ * - `idx_wal_flushed`: Find unflushed WAL entries
+ * - `idx_hot_objects_accessed`: LRU eviction ordering
+ */
 export const SCHEMA_SQL = `
 -- Git objects (blobs, trees, commits, tags)
 CREATE TABLE IF NOT EXISTS objects (sha TEXT PRIMARY KEY, type TEXT NOT NULL, size INTEGER NOT NULL, data BLOB NOT NULL, created_at INTEGER);
@@ -20,19 +87,112 @@ CREATE INDEX IF NOT EXISTS idx_objects_type ON objects(type);
 CREATE INDEX IF NOT EXISTS idx_wal_flushed ON wal(flushed);
 CREATE INDEX IF NOT EXISTS idx_hot_objects_accessed ON hot_objects(accessed_at);
 `;
+/**
+ * List of required tables for schema validation.
+ *
+ * @description
+ * Used by validateSchema() to verify all required tables exist.
+ * @internal
+ */
 const REQUIRED_TABLES = ['objects', 'object_index', 'hot_objects', 'wal', 'refs'];
+// ============================================================================
+// SchemaManager Class
+// ============================================================================
+/**
+ * Manager for database schema initialization and validation.
+ *
+ * @description
+ * Handles schema lifecycle including initialization, version checking,
+ * and validation. Should be used when first accessing a Durable Object
+ * to ensure the schema is properly set up.
+ *
+ * @example
+ * ```typescript
+ * class GitDurableObject implements DurableObject {
+ *   private schemaManager: SchemaManager
+ *   private initialized = false
+ *
+ *   constructor(state: DurableObjectState) {
+ *     this.schemaManager = new SchemaManager(state.storage)
+ *   }
+ *
+ *   private async ensureInitialized() {
+ *     if (!this.initialized) {
+ *       await this.schemaManager.initializeSchema()
+ *       this.initialized = true
+ *     }
+ *   }
+ *
+ *   async fetch(request: Request) {
+ *     await this.ensureInitialized()
+ *     // ... handle request
+ *   }
+ * }
+ * ```
+ */
 export class SchemaManager {
     storage;
+    /**
+     * Create a new SchemaManager.
+     *
+     * @param storage - Durable Object storage interface
+     */
     constructor(storage) {
         this.storage = storage;
     }
+    /**
+     * Initialize the database schema.
+     *
+     * @description
+     * Creates all required tables and indexes if they don't exist.
+     * This operation is idempotent - safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * await schemaManager.initializeSchema()
+     * ```
+     */
     async initializeSchema() {
         this.storage.sql.exec(SCHEMA_SQL);
     }
+    /**
+     * Get the current schema version.
+     *
+     * @description
+     * Returns the schema version if valid, or 0 if schema is missing/invalid.
+     * Use this to detect when schema migration is needed.
+     *
+     * @returns Schema version number (0 if invalid/missing)
+     *
+     * @example
+     * ```typescript
+     * const version = await schemaManager.getSchemaVersion()
+     * console.log(`Schema version: ${version}`)
+     * ```
+     */
     async getSchemaVersion() {
         const isValid = await this.validateSchema();
         return isValid ? SCHEMA_VERSION : 0;
     }
+    /**
+     * Validate that all required tables exist.
+     *
+     * @description
+     * Checks the sqlite_master table to verify all required tables
+     * are present. Returns false if any tables are missing.
+     *
+     * @returns True if schema is valid and complete
+     *
+     * @example
+     * ```typescript
+     * if (await schemaManager.validateSchema()) {
+     *   console.log('Schema is valid')
+     * } else {
+     *   console.log('Schema needs initialization')
+     *   await schemaManager.initializeSchema()
+     * }
+     * ```
+     */
     async validateSchema() {
         const result = this.storage.sql.exec("SELECT name FROM sqlite_master WHERE type='table'");
         const tables = result.toArray();

package/dist/durable-object/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/durable-object/schema.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAA;AAE/B,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;CAoBzB,CAAA;AAED,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AAEjF,MAAM,OAAO,aAAa;IACJ;IAApB,YAAoB,OAA6B;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAErD,KAAK,CAAC,gBAAgB;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACnC,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAA;QAC3C,OAAO,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAA;IACrC,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAClC,mDAAmD,CACpD,CAAA;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAwB,CAAA;QACrD,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAE1C,OAAO,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;IACnE,CAAC;CACF"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/durable-object/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAqDH,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAA;AAE/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;CAoBzB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AAEjF,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,aAAa;IAMJ;IALpB;;;;OAIG;IACH,YAAoB,OAA6B;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAErD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,gBAAgB;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACnC,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,gBAAgB;QACpB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAA;QAC3C,OAAO,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAA;IACrC,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,cAAc;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAClC,mDAAmD,CACpD,CAAA;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAwB,CAAA;QACrD,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAE1C,OAAO,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;IACnE,CAAC;CACF"}