gitx.do 0.0.1 → 0.0.3

package/dist/types/storage.d.ts

@@ -1,117 +1,489 @@
 /**
- * Storage Interface Types
+ * @fileoverview Storage Interface Types
  *
- * Canonical interfaces for object storage and commit providers.
- * These are the single source of truth - all modules should import from here.
+ * This module defines the canonical interfaces for object storage and commit providers.
+ * All storage-related interfaces are defined here as the single source of truth.
+ *
+ * The interfaces follow a layered design:
+ * - {@link BasicObjectStore} - Core object CRUD operations
+ * - {@link RefObjectStore} - Adds ref management capabilities
+ * - {@link TreeDiffObjectStore} - Specialized for tree diff operations
+ * - {@link ObjectStore} - Full-featured store combining all capabilities
+ *
+ * Similarly for commit providers:
+ * - {@link BasicCommitProvider} - Core commit retrieval
+ * - {@link CommitProvider} - Extended with path filtering and tree access
+ *
+ * @module types/storage
+ *
+ * @example
+ * ```typescript
+ * import type { ObjectStore, CommitProvider } from './types/storage'
+ *
+ * // Implement a storage backend
+ * class MyObjectStore implements ObjectStore {
+ *   async getObject(sha: string) { ... }
+ *   async storeObject(type: string, data: Uint8Array) { ... }
+ *   // ... other methods
+ * }
+ * ```
  */
 import type { CommitObject, TreeObject } from './objects';
 /**
- * Interface for Git object storage operations.
+ * Full-featured interface for Git object storage operations.
  *
+ * @description
  * This is the canonical ObjectStore interface that combines all required
  * methods from various modules. Implementations should provide all methods.
  *
- * Used by: commit.ts, tag.ts, tree-builder.ts, tree-diff.ts
+ * The interface is organized into three groups:
+ * 1. **Core object operations**: Basic CRUD for Git objects
+ * 2. **Ref operations**: Managing references (branches, tags, HEAD)
+ * 3. **Typed accessors**: Convenient methods for specific object types
+ *
+ * @example
+ * ```typescript
+ * const store: ObjectStore = new DurableObjectStore(storage)
+ *
+ * // Store a blob
+ * const sha = await store.storeObject('blob', content)
+ *
+ * // Retrieve it
+ * const obj = await store.getObject(sha)
+ *
+ * // Work with refs
+ * await store.setRef('refs/heads/main', sha)
+ * const mainSha = await store.getRef('refs/heads/main')
+ * ```
  */
 export interface ObjectStore {
-    /** Get an object by SHA */
+    /**
+     * Retrieve a Git object by its SHA-1 hash.
+     *
+     * @description
+     * Fetches the raw object data and type for the given SHA.
+     * Returns null if the object does not exist.
+     *
+     * @param sha - 40-character hexadecimal SHA-1 hash
+     * @returns The object with type and data, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const obj = await store.getObject('abc123...')
+     * if (obj) {
+     *   console.log(`Type: ${obj.type}, Size: ${obj.data.length}`)
+     * }
+     * ```
+     */
     getObject(sha: string): Promise<{
         type: string;
         data: Uint8Array;
     } | null>;
-    /** Store an object and return its SHA */
+    /**
+     * Store a Git object and return its SHA-1 hash.
+     *
+     * @description
+     * Computes the SHA-1 hash of the object in Git format (type + size + content)
+     * and stores it. If an object with the same SHA already exists, this is a no-op.
+     *
+     * @param type - Object type ('blob', 'tree', 'commit', 'tag')
+     * @param data - Raw object content (without Git header)
+     * @returns The 40-character SHA-1 hash of the stored object
+     *
+     * @example
+     * ```typescript
+     * const content = new TextEncoder().encode('Hello, World!')
+     * const sha = await store.storeObject('blob', content)
+     * console.log(`Stored blob: ${sha}`)
+     * ```
+     */
     storeObject(type: string, data: Uint8Array): Promise<string>;
-    /** Check if an object exists */
+    /**
+     * Check if an object exists in the store.
+     *
+     * @description
+     * Efficiently checks for object existence without fetching the full content.
+     *
+     * @param sha - 40-character hexadecimal SHA-1 hash
+     * @returns True if the object exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (await store.hasObject(sha)) {
+     *   console.log('Object exists')
+     * }
+     * ```
+     */
     hasObject(sha: string): Promise<boolean>;
-    /** Get a ref by name */
+    /**
+     * Get a reference by its name.
+     *
+     * @description
+     * Retrieves the SHA-1 that a ref points to. For symbolic refs,
+     * this returns the resolved SHA (following the chain).
+     *
+     * @param refName - Full ref name (e.g., 'refs/heads/main', 'HEAD')
+     * @returns The SHA-1 hash the ref points to, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const mainSha = await store.getRef('refs/heads/main')
+     * const headSha = await store.getRef('HEAD')
+     * ```
+     */
     getRef(refName: string): Promise<string | null>;
-    /** Set a ref to point to a SHA */
+    /**
+     * Set a reference to point to a SHA.
+     *
+     * @description
+     * Creates or updates a ref to point to the given SHA.
+     * For atomic operations, consider using compare-and-swap patterns.
+     *
+     * @param refName - Full ref name (e.g., 'refs/heads/main')
+     * @param sha - 40-character SHA-1 hash to point to
+     *
+     * @example
+     * ```typescript
+     * await store.setRef('refs/heads/feature', commitSha)
+     * ```
+     */
     setRef(refName: string, sha: string): Promise<void>;
-    /** Delete a ref */
+    /**
+     * Delete a reference.
+     *
+     * @description
+     * Removes a ref from storage. Returns true if the ref existed
+     * and was deleted, false if it didn't exist.
+     *
+     * @param refName - Full ref name to delete
+     * @returns True if deleted, false if ref didn't exist
+     *
+     * @example
+     * ```typescript
+     * const deleted = await store.deleteRef('refs/heads/old-branch')
+     * ```
+     */
     deleteRef(refName: string): Promise<boolean>;
-    /** List refs with a given prefix */
+    /**
+     * List references with a given prefix.
+     *
+     * @description
+     * Returns all refs that start with the given prefix.
+     * Commonly used to list branches or tags.
+     *
+     * @param prefix - Prefix to filter refs (e.g., 'refs/heads/', 'refs/tags/')
+     * @returns Array of ref names and their SHA targets
+     *
+     * @example
+     * ```typescript
+     * // List all branches
+     * const branches = await store.listRefs('refs/heads/')
+     * for (const { name, sha } of branches) {
+     *   console.log(`${name} -> ${sha}`)
+     * }
+     *
+     * // List all tags
+     * const tags = await store.listRefs('refs/tags/')
+     * ```
+     */
     listRefs(prefix: string): Promise<Array<{
         name: string;
         sha: string;
     }>>;
-    /** Get a tree object by SHA */
+    /**
+     * Get a tree object by SHA.
+     *
+     * @description
+     * Retrieves and parses a tree object, returning it with parsed entries.
+     * Returns null if the object doesn't exist or isn't a tree.
+     *
+     * @param sha - 40-character SHA-1 of the tree
+     * @returns Parsed TreeObject or null
+     *
+     * @example
+     * ```typescript
+     * const tree = await store.getTree(treeSha)
+     * if (tree) {
+     *   for (const entry of tree.entries) {
+     *     console.log(`${entry.mode} ${entry.name}`)
+     *   }
+     * }
+     * ```
+     */
     getTree(sha: string): Promise<TreeObject | null>;
-    /** Get blob content by SHA */
+    /**
+     * Get blob content by SHA.
+     *
+     * @description
+     * Retrieves the raw content of a blob object.
+     * Returns null if the object doesn't exist or isn't a blob.
+     *
+     * @param sha - 40-character SHA-1 of the blob
+     * @returns Raw blob content or null
+     *
+     * @example
+     * ```typescript
+     * const content = await store.getBlob(blobSha)
+     * if (content) {
+     *   const text = new TextDecoder().decode(content)
+     * }
+     * ```
+     */
     getBlob(sha: string): Promise<Uint8Array | null>;
-    /** Check if an object exists (alias for hasObject) */
+    /**
+     * Check if an object exists (alias for hasObject).
+     *
+     * @description
+     * Convenience alias for hasObject, commonly used in tree diff operations.
+     *
+     * @param sha - 40-character SHA-1 hash
+     * @returns True if the object exists
+     */
     exists(sha: string): Promise<boolean>;
 }
 /**
  * Minimal ObjectStore interface for basic operations.
  *
- * Use this when only core object operations are needed,
- * without ref management or typed accessors.
+ * @description
+ * Use this interface when only core object operations are needed,
+ * without ref management or typed accessors. This is useful for
+ * modules that only need to read/write raw objects.
+ *
+ * @example
+ * ```typescript
+ * function processObjects(store: BasicObjectStore) {
+ *   const obj = await store.getObject(sha)
+ *   if (obj) {
+ *     // Process the object
+ *     await store.storeObject('blob', processedData)
+ *   }
+ * }
+ * ```
  */
 export interface BasicObjectStore {
-    /** Get an object by SHA */
+    /**
+     * Get an object by SHA.
+     *
+     * @param sha - 40-character SHA-1 hash
+     * @returns Object with type and data, or null if not found
+     */
     getObject(sha: string): Promise<{
         type: string;
         data: Uint8Array;
     } | null>;
-    /** Store an object and return its SHA */
+    /**
+     * Store an object and return its SHA.
+     *
+     * @param type - Object type ('blob', 'tree', 'commit', 'tag')
+     * @param data - Raw object content
+     * @returns 40-character SHA-1 hash of the stored object
+     */
     storeObject(type: string, data: Uint8Array): Promise<string>;
-    /** Check if an object exists */
+    /**
+     * Check if an object exists.
+     *
+     * @param sha - 40-character SHA-1 hash
+     * @returns True if the object exists
+     */
     hasObject(sha: string): Promise<boolean>;
 }
 /**
  * ObjectStore with ref management capabilities.
  *
- * Extends BasicObjectStore with ref operations needed for tag management.
+ * @description
+ * Extends BasicObjectStore with ref operations needed for tag management
+ * and branch operations. Use this when you need both object storage
+ * and reference management.
+ *
+ * @example
+ * ```typescript
+ * async function createTag(store: RefObjectStore, name: string, target: string) {
+ *   // Store the tag object
+ *   const tagSha = await store.storeObject('tag', tagData)
+ *   // Create the ref
+ *   await store.setRef(`refs/tags/${name}`, tagSha)
+ * }
+ * ```
  */
 export interface RefObjectStore extends BasicObjectStore {
-    /** Get a ref by name */
+    /**
+     * Get a ref by name.
+     *
+     * @param refName - Full ref name (e.g., 'refs/heads/main')
+     * @returns SHA-1 hash or null if not found
+     */
     getRef(refName: string): Promise<string | null>;
-    /** Set a ref to point to a SHA */
+    /**
+     * Set a ref to point to a SHA.
+     *
+     * @param refName - Full ref name
+     * @param sha - Target SHA-1 hash
+     */
     setRef(refName: string, sha: string): Promise<void>;
-    /** Delete a ref */
+    /**
+     * Delete a ref.
+     *
+     * @param refName - Full ref name to delete
+     * @returns True if deleted, false if not found
+     */
     deleteRef(refName: string): Promise<boolean>;
-    /** List refs with a given prefix */
+    /**
+     * List refs with a given prefix.
+     *
+     * @param prefix - Prefix to filter (e.g., 'refs/heads/')
+     * @returns Array of ref names and their targets
+     */
     listRefs(prefix: string): Promise<Array<{
         name: string;
         sha: string;
     }>>;
 }
 /**
- * ObjectStore for tree diff operations.
+ * ObjectStore specialized for tree diff operations.
+ *
+ * @description
+ * Provides typed accessors for tree and blob objects, optimized for
+ * operations that need to traverse and compare directory trees.
  *
- * Provides typed accessors for tree and blob objects.
+ * @example
+ * ```typescript
+ * async function compareFiles(store: TreeDiffObjectStore, sha1: string, sha2: string) {
+ *   const blob1 = await store.getBlob(sha1)
+ *   const blob2 = await store.getBlob(sha2)
+ *   // Compare contents...
+ * }
+ * ```
  */
 export interface TreeDiffObjectStore {
-    /** Get a tree object by SHA */
+    /**
+     * Get a tree object by SHA.
+     *
+     * @param sha - 40-character SHA-1 of the tree
+     * @returns Parsed TreeObject or null
+     */
     getTree(sha: string): Promise<TreeObject | null>;
-    /** Get blob content by SHA */
+    /**
+     * Get blob content by SHA.
+     *
+     * @param sha - 40-character SHA-1 of the blob
+     * @returns Raw content or null
+     */
     getBlob(sha: string): Promise<Uint8Array | null>;
-    /** Check if an object exists */
+    /**
+     * Check if an object exists.
+     *
+     * @param sha - 40-character SHA-1 hash
+     * @returns True if the object exists
+     */
     exists(sha: string): Promise<boolean>;
 }
 /**
  * Interface for retrieving commits from storage.
  *
+ * @description
  * This is the canonical CommitProvider interface that combines all required
- * methods from various modules. The base method is required; others are optional.
+ * methods for commit traversal and history operations. The base getCommit
+ * method is required; path filtering and tree access are optional extensions.
  *
  * Used by: commit-traversal.ts, merge-base.ts
+ *
+ * @example
+ * ```typescript
+ * async function walkHistory(provider: CommitProvider, startSha: string) {
+ *   const commit = await provider.getCommit(startSha)
+ *   if (!commit) return
+ *
+ *   console.log(commit.message)
+ *
+ *   for (const parentSha of commit.parents) {
+ *     await walkHistory(provider, parentSha)
+ *   }
+ * }
+ * ```
  */
 export interface CommitProvider {
-    /** Get a commit by SHA */
+    /**
+     * Get a commit by SHA.
+     *
+     * @description
+     * Retrieves and parses a commit object. This is the core method
+     * required for all commit traversal operations.
+     *
+     * @param sha - 40-character SHA-1 of the commit
+     * @returns Parsed CommitObject or null if not found
+     *
+     * @example
+     * ```typescript
+     * const commit = await provider.getCommit(sha)
+     * if (commit) {
+     *   console.log(`${commit.author.name}: ${commit.message}`)
+     * }
+     * ```
+     */
     getCommit(sha: string): Promise<CommitObject | null>;
-    /** Get commits that modify a path (optional, for path filtering) */
+    /**
+     * Get commits that modify a specific path.
+     *
+     * @description
+     * Optional method for efficient path-filtered history traversal.
+     * Returns commit SHAs that touched the given file or directory path.
+     *
+     * @param path - File or directory path (relative to repo root)
+     * @returns Array of commit SHAs that modified the path
+     *
+     * @example
+     * ```typescript
+     * if (provider.getCommitsForPath) {
+     *   const commits = await provider.getCommitsForPath('src/index.ts')
+     *   console.log(`File modified in ${commits.length} commits`)
+     * }
+     * ```
+     */
     getCommitsForPath?(path: string): Promise<string[]>;
-    /** Get the tree for a commit (optional, for tree operations) */
+    /**
+     * Get the tree for a commit.
+     *
+     * @description
+     * Optional method for accessing the tree associated with a commit.
+     * Useful for operations that need to examine file contents.
+     *
+     * @param commitSha - 40-character SHA-1 of the commit
+     * @returns The tree structure (implementation-defined format)
+     *
+     * @example
+     * ```typescript
+     * if (provider.getTree) {
+     *   const tree = await provider.getTree(commitSha)
+     *   // Examine tree contents...
+     * }
+     * ```
+     */
     getTree?(commitSha: string): Promise<unknown>;
 }
 /**
  * Minimal CommitProvider interface for basic operations.
  *
+ * @description
  * Use this when only the core getCommit method is needed.
+ * Suitable for simple commit lookups without path filtering or tree access.
+ *
+ * @example
+ * ```typescript
+ * function findMergeBase(provider: BasicCommitProvider, sha1: string, sha2: string) {
+ *   // Only needs getCommit for ancestor traversal
+ *   const commit1 = await provider.getCommit(sha1)
+ *   const commit2 = await provider.getCommit(sha2)
+ *   // ... traverse parents
+ * }
+ * ```
  */
 export interface BasicCommitProvider {
-    /** Get a commit by SHA */
+    /**
+     * Get a commit by SHA.
+     *
+     * @param sha - 40-character SHA-1 of the commit
+     * @returns Parsed CommitObject or null if not found
+     */
     getCommit(sha: string): Promise<CommitObject | null>;
 }
 //# sourceMappingURL=storage.d.ts.map

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

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

package/dist/types/storage.js

@@ -1,8 +1,32 @@
 /**
- * Storage Interface Types
+ * @fileoverview Storage Interface Types
  *
- * Canonical interfaces for object storage and commit providers.
- * These are the single source of truth - all modules should import from here.
+ * This module defines the canonical interfaces for object storage and commit providers.
+ * All storage-related interfaces are defined here as the single source of truth.
+ *
+ * The interfaces follow a layered design:
+ * - {@link BasicObjectStore} - Core object CRUD operations
+ * - {@link RefObjectStore} - Adds ref management capabilities
+ * - {@link TreeDiffObjectStore} - Specialized for tree diff operations
+ * - {@link ObjectStore} - Full-featured store combining all capabilities
+ *
+ * Similarly for commit providers:
+ * - {@link BasicCommitProvider} - Core commit retrieval
+ * - {@link CommitProvider} - Extended with path filtering and tree access
+ *
+ * @module types/storage
+ *
+ * @example
+ * ```typescript
+ * import type { ObjectStore, CommitProvider } from './types/storage'
+ *
+ * // Implement a storage backend
+ * class MyObjectStore implements ObjectStore {
+ *   async getObject(sha: string) { ... }
+ *   async storeObject(type: string, data: Uint8Array) { ... }
+ *   // ... other methods
+ * }
+ * ```
  */
 export {};
 //# sourceMappingURL=storage.js.map

package/dist/types/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/types/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/types/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG"}