isomorphic-jj 1.0.0

package/src/backend/lazy-git-backend.js

@@ -0,0 +1,180 @@
+/**
+ * LazyGitBackend - Git backend with lazy object loading (v0.4)
+ *
+ * Extends IsomorphicGitBackend to support on-demand object fetching.
+ * Perfect for shallow clones and browser environments with limited storage.
+ */
+
+import { IsomorphicGitBackend } from './isomorphic-git-backend.js';
+import { JJError } from '../utils/errors.js';
+import git from 'isomorphic-git';
+
+/**
+ * Git backend with lazy object loading
+ *
+ * @class LazyGitBackend
+ * @extends IsomorphicGitBackend
+ */
+export class LazyGitBackend extends IsomorphicGitBackend {
+  /**
+   * Create lazy Git backend
+   *
+   * @param {Object} options - Backend options
+   * @param {Object} options.fs - Filesystem implementation
+   * @param {Object} [options.http] - HTTP client for network operations
+   * @param {string} options.dir - Repository directory path
+   * @param {boolean} [options.lazyLoad=false] - Enable lazy object loading
+   * @param {string} [options.remote='origin'] - Remote to fetch from
+   */
+  constructor({ fs, http, dir, lazyLoad = false, remote = 'origin' }) {
+    super({ fs, http, dir });
+
+    this.lazyLoad = lazyLoad;
+    this.remote = remote;
+    this.missingObjects = new Set();
+    this.fetchedObjects = new Set();
+  }
+
+  /**
+   * Read blob with lazy loading support
+   *
+   * @param {string} oid - Object ID (SHA-1)
+   * @returns {Promise<Object>} Blob object with { blob: Buffer }
+   */
+  async readBlob(oid) {
+    // Validate OID format
+    if (!/^[0-9a-f]{40}$/.test(oid)) {
+      throw new JJError(
+        'INVALID_OID',
+        `Invalid object ID format: ${oid}`,
+        { oid }
+      );
+    }
+
+    try {
+      // Try local read first
+      return await this._gitReadBlob(oid);
+    } catch (error) {
+      // If not found and lazy loading enabled, fetch from remote
+      if (error.code === 'NotFoundError' && this.lazyLoad) {
+        // Track as missing BEFORE attempting fetch
+        this.missingObjects.add(oid);
+
+        // Only fetch if we haven't already tried
+        if (!this.fetchedObjects.has(oid)) {
+          try {
+            await this._fetchObject(oid);
+            this.fetchedObjects.add(oid);
+
+            // Try reading again after fetch
+            return await this._gitReadBlob(oid);
+          } catch (fetchError) {
+            // Fetch failed, but we still track as missing
+            // Re-throw the fetch error
+            throw fetchError;
+          }
+        }
+      }
+
+      // Re-throw if lazy loading disabled or already tried fetching
+      throw error;
+    }
+  }
+
+  /**
+   * Internal git.readBlob wrapper (for testing/mocking)
+   *
+   * @private
+   * @param {string} oid - Object ID
+   * @returns {Promise<Object>} Blob object
+   */
+  async _gitReadBlob(oid) {
+    return await git.readBlob({
+      fs: this.fs,
+      dir: this.dir,
+      oid,
+    });
+  }
+
+  /**
+   * Fetch a single object from remote
+   *
+   * Note: isomorphic-git doesn't support fetching individual objects.
+   * This is a placeholder for the fetch logic. In practice, you may need to:
+   * 1. Fetch entire packfile containing the object
+   * 2. Use depth-based fetch to get more history
+   * 3. Implement custom Git protocol for single-object fetch
+   *
+   * @private
+   * @param {string} oid - Object ID to fetch
+   * @returns {Promise<void>}
+   */
+  async _fetchObject(oid) {
+    if (!this.http) {
+      throw new JJError(
+        'NETWORK_NOT_AVAILABLE',
+        'Lazy object loading requires http client for fetching missing objects',
+        {
+          suggestion: 'Provide http option when creating backend',
+          oid,
+        }
+      );
+    }
+
+    // Implementation note: isomorphic-git doesn't support fetching single objects.
+    // In a real implementation, you would:
+    //
+    // Option 1: Fetch with increased depth
+    // await git.fetch({
+    //   fs: this.fs,
+    //   http: this.http,
+    //   dir: this.dir,
+    //   remote: this.remote,
+    //   depth: 10,  // Fetch more history
+    //   relative: true
+    // });
+    //
+    // Option 2: Custom Git protocol implementation
+    // - Send want/have negotiation
+    // - Receive packfile containing requested object
+    // - Unpack into .git/objects
+    //
+    // Option 3: Use Git HTTP API directly
+    // - GET /info/refs
+    // - POST /git-upload-pack with want list
+    //
+    // For now, throw an error indicating this needs implementation
+    throw new JJError(
+      'NOT_IMPLEMENTED',
+      'Single object fetch not yet implemented. Consider using shallow fetch with increased depth instead.',
+      {
+        oid,
+        suggestion: 'Use git.fetch({ depth: N, relative: true }) to fetch more history',
+      }
+    );
+  }
+
+  /**
+   * Get statistics about lazy loading
+   *
+   * @returns {Object} Statistics object
+   */
+  getStats() {
+    return {
+      lazyLoad: this.lazyLoad,
+      missingObjects: this.missingObjects.size,
+      fetchedObjects: this.fetchedObjects.size,
+      hitRate: this.fetchedObjects.size > 0
+        ? (this.fetchedObjects.size - this.missingObjects.size) / this.fetchedObjects.size
+        : 0,
+    };
+  }
+
+  /**
+   * Clear lazy loading caches
+   */
+  clearCaches() {
+    this.missingObjects.clear();
+    this.fetchedObjects.clear();
+  }
+}

package/src/browser/helpers.js

@@ -0,0 +1,189 @@
+/**
+ * Browser helpers for isomorphic-jj
+ *
+ * Utilities for setting up isomorphic-jj in browser environments.
+ */
+
+/**
+ * Create a browser-compatible filesystem using LightningFS
+ *
+ * Requires: @isomorphic-git/lightning-fs
+ *
+ * @param {Object} opts - Options
+ * @param {string} [opts.backend='idb'] - Storage backend ('idb' or 'memory')
+ * @param {string} [opts.name='jj'] - Database name for IndexedDB
+ * @param {boolean} [opts.wipe=false] - Wipe existing data
+ * @returns {Object} LightningFS instance
+ *
+ * @example
+ * ```javascript
+ * import { createBrowserFS } from 'isomorphic-jj/browser';
+ * import { createJJ } from 'isomorphic-jj';
+ * import git from 'isomorphic-git';
+ * import http from 'isomorphic-git/http/web';
+ *
+ * const fs = createBrowserFS({ backend: 'idb', name: 'my-repo' });
+ * const jj = await createJJ({
+ *   fs,
+ *   dir: '/repo',
+ *   git,
+ *   http
+ * });
+ * ```
+ */
+export function createBrowserFS(opts = {}) {
+  // Check if we're in a browser environment
+  if (typeof window === 'undefined') {
+    throw new Error('createBrowserFS() should only be used in browser environments');
+  }
+
+  // Dynamic import to avoid issues in Node.js
+  // Users must install @isomorphic-git/lightning-fs separately
+  try {
+    // This will be resolved by the bundler
+    const LightningFS = require('@isomorphic-git/lightning-fs');
+
+    const fs = new LightningFS(opts.name || 'jj', {
+      wipe: opts.wipe || false,
+    });
+
+    return fs;
+  } catch (error) {
+    throw new Error(
+      'LightningFS not found. Install it with: npm install @isomorphic-git/lightning-fs\n' +
+      'Original error: ' + error.message
+    );
+  }
+}
+
+/**
+ * Get storage quota information (browser only)
+ *
+ * @returns {Promise<Object|null>} Quota information or null if not supported
+ *
+ * @example
+ * ```javascript
+ * const quota = await getStorageQuota();
+ * console.log(`Using ${quota.usage} of ${quota.quota} bytes (${quota.percentage}%)`);
+ * ```
+ */
+export async function getStorageQuota() {
+  if (typeof navigator === 'undefined' || !navigator.storage || !navigator.storage.estimate) {
+    return null;
+  }
+
+  const estimate = await navigator.storage.estimate();
+  return {
+    usage: estimate.usage || 0,
+    quota: estimate.quota || 0,
+    available: (estimate.quota || 0) - (estimate.usage || 0),
+    percentage: estimate.quota ? ((estimate.usage || 0) / estimate.quota) * 100 : 0,
+  };
+}
+
+/**
+ * Request persistent storage (browser only)
+ *
+ * Prevents the browser from evicting the storage.
+ *
+ * @returns {Promise<boolean>} Whether persistent storage was granted
+ *
+ * @example
+ * ```javascript
+ * const persistent = await requestPersistentStorage();
+ * if (persistent) {
+ *   console.log('Storage will not be evicted');
+ * }
+ * ```
+ */
+export async function requestPersistentStorage() {
+  if (typeof navigator === 'undefined' || !navigator.storage || !navigator.storage.persist) {
+    return false;
+  }
+
+  return await navigator.storage.persist();
+}
+
+/**
+ * Check if persistent storage is already granted
+ *
+ * @returns {Promise<boolean>} Whether persistent storage is granted
+ */
+export async function isPersistentStorage() {
+  if (typeof navigator === 'undefined' || !navigator.storage || !navigator.storage.persisted) {
+    return false;
+  }
+
+  return await navigator.storage.persisted();
+}
+
+/**
+ * ServiceWorker utilities for offline support
+ */
+export const serviceWorker = {
+  /**
+   * Register a service worker for offline support
+   *
+   * @param {string} scriptURL - Service worker script URL
+   * @param {Object} [options] - Registration options
+   * @returns {Promise<ServiceWorkerRegistration>}
+   */
+  async register(scriptURL, options = {}) {
+    if (typeof navigator === 'undefined' || !navigator.serviceWorker) {
+      throw new Error('Service Workers not supported in this browser');
+    }
+
+    return await navigator.serviceWorker.register(scriptURL, options);
+  },
+
+  /**
+   * Unregister service worker
+   */
+  async unregister() {
+    if (typeof navigator === 'undefined' || !navigator.serviceWorker) {
+      return false;
+    }
+
+    const registration = await navigator.serviceWorker.ready;
+    return await registration.unregister();
+  },
+
+  /**
+   * Check if service worker is registered
+   */
+  async isRegistered() {
+    if (typeof navigator === 'undefined' || !navigator.serviceWorker) {
+      return false;
+    }
+
+    const registration = await navigator.serviceWorker.getRegistration();
+    return !!registration;
+  },
+};
+
+/**
+ * Detect browser capabilities
+ *
+ * @returns {Object} Capability detection results
+ */
+export function detectCapabilities() {
+  if (typeof window === 'undefined') {
+    return {
+      environment: 'node',
+      indexedDB: false,
+      serviceWorker: false,
+      persistentStorage: false,
+      sharedArrayBuffer: false,
+      webWorker: false,
+    };
+  }
+
+  return {
+    environment: 'browser',
+    indexedDB: typeof indexedDB !== 'undefined',
+    serviceWorker: typeof navigator !== 'undefined' && 'serviceWorker' in navigator,
+    persistentStorage: typeof navigator !== 'undefined' && navigator.storage && typeof navigator.storage.persist === 'function',
+    sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
+    webWorker: typeof Worker !== 'undefined',
+  };
+}

package/src/browser/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * TypeScript type definitions for isomorphic-jj/browser
+ *
+ * Browser-specific utilities for isomorphic-jj
+ */
+
+/**
+ * Browser filesystem creation options
+ */
+export interface BrowserFSOptions {
+  /** Storage backend ('idb' for IndexedDB or 'memory') */
+  backend?: 'idb' | 'memory';
+  /** Database name for IndexedDB */
+  name?: string;
+  /** Wipe existing data on initialization */
+  wipe?: boolean;
+}
+
+/**
+ * Storage quota information
+ */
+export interface StorageQuota {
+  /** Bytes currently used */
+  usage: number;
+  /** Total quota in bytes */
+  quota: number;
+  /** Available bytes remaining */
+  available: number;
+  /** Percentage of quota used (0-100) */
+  percentage: number;
+}
+
+/**
+ * Browser capabilities detection result
+ */
+export interface BrowserCapabilities {
+  /** IndexedDB is available */
+  indexedDB: boolean;
+  /** Storage Manager API is available */
+  storageManager: boolean;
+  /** Persistent storage is available */
+  persistentStorage: boolean;
+  /** Service Workers are supported */
+  serviceWorker: boolean;
+  /** Origin Private File System (OPFS) is available */
+  opfs: boolean;
+  /** SharedArrayBuffer is available */
+  sharedArrayBuffer: boolean;
+  /** Web Workers are supported */
+  webWorker: boolean;
+}
+
+/**
+ * Service Worker utilities
+ */
+export interface ServiceWorkerUtils {
+  /**
+   * Register a service worker
+   * @param scriptURL - URL to service worker script
+   * @param options - Registration options
+   */
+  register(scriptURL: string, options?: RegistrationOptions): Promise<ServiceWorkerRegistration>;
+
+  /**
+   * Unregister the active service worker
+   */
+  unregister(): Promise<boolean>;
+
+  /**
+   * Get the active service worker registration
+   */
+  getRegistration(): Promise<ServiceWorkerRegistration | undefined>;
+
+  /**
+   * Post a message to the service worker
+   * @param message - Message to send
+   */
+  postMessage(message: any): void;
+
+  /**
+   * Listen for messages from the service worker
+   * @param handler - Message handler function
+   */
+  onMessage(handler: (event: MessageEvent) => void): void;
+}
+
+/**
+ * Create a browser-compatible filesystem using LightningFS
+ *
+ * Requires: @isomorphic-git/lightning-fs
+ *
+ * @param opts - Filesystem options
+ * @returns LightningFS instance compatible with isomorphic-jj
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserFS } from 'isomorphic-jj/browser';
+ * import { createJJ } from 'isomorphic-jj';
+ * import git from 'isomorphic-git';
+ * import http from 'isomorphic-git/http/web';
+ *
+ * const fs = createBrowserFS({ backend: 'idb', name: 'my-repo' });
+ * const jj = await createJJ({ fs, dir: '/repo', git, http });
+ * ```
+ */
+export function createBrowserFS(opts?: BrowserFSOptions): any;
+
+/**
+ * Get storage quota information (browser only)
+ *
+ * @returns Quota information or null if not supported
+ *
+ * @example
+ * ```typescript
+ * const quota = await getStorageQuota();
+ * if (quota) {
+ *   console.log(`Using ${quota.usage} of ${quota.quota} bytes`);
+ * }
+ * ```
+ */
+export function getStorageQuota(): Promise<StorageQuota | null>;
+
+/**
+ * Request persistent storage to prevent browser eviction
+ *
+ * @returns true if persistent storage was granted, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const persistent = await requestPersistentStorage();
+ * if (persistent) {
+ *   console.log('Storage will not be evicted by the browser');
+ * }
+ * ```
+ */
+export function requestPersistentStorage(): Promise<boolean>;
+
+/**
+ * Check if persistent storage is currently enabled
+ *
+ * @returns true if storage is persistent, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isPersistent = await isPersistentStorage();
+ * if (!isPersistent) {
+ *   await requestPersistentStorage();
+ * }
+ * ```
+ */
+export function isPersistentStorage(): Promise<boolean>;
+
+/**
+ * Service worker utilities for offline support
+ */
+export const serviceWorker: ServiceWorkerUtils;
+
+/**
+ * Detect browser capabilities
+ *
+ * @returns Object indicating which features are available
+ *
+ * @example
+ * ```typescript
+ * const caps = detectCapabilities();
+ * if (!caps.indexedDB) {
+ *   console.warn('IndexedDB not available, using memory backend');
+ * }
+ * if (caps.serviceWorker) {
+ *   // Enable offline support
+ * }
+ * ```
+ */
+export function detectCapabilities(): BrowserCapabilities;

package/src/browser/index.js

@@ -0,0 +1,12 @@
+/**
+ * Browser-specific exports for isomorphic-jj
+ */
+
+export {
+  createBrowserFS,
+  getStorageQuota,
+  requestPersistentStorage,
+  isPersistentStorage,
+  serviceWorker,
+  detectCapabilities,
+} from './helpers.js';