👨‍💻 Developer Guide

// Classes: PascalCase
class RaindropClient { }

// Interfaces: PascalCase, with I prefix (optional)
interface IRaindrop { }
interface FetchOptions { }

// Functions: camelCase
function processRaindrop() { }

// Constants: UPPER_SNAKE_CASE
const MAX_RETRIES = 3;
const API_BASE_URL = "https://api.raindrop.io";

// Variables: camelCase
let currentProgress = 0;
const apiToken = "xxx";

// Private members: _leadingUnderscore
class MyClass {
  private _internalState = 0;
}

// Booleans: is/has prefix
const isLoading = false;
const hasError = true;

// ✅ Good
function fetchRaindrops(token: string, limit: number): Promise<Raindrop[]> {
  // ...
}

const config: FetchConfig = {
  token: "xxx",
  limit: 50,
};

// ❌ Avoid
function fetchRaindrops(token, limit) {
  // ...
}

const config = {
  token: "xxx",
  limit: 50,
};

/**
 * Fetches raindrops from Raindrop.io API
 * @param token - API authentication token
 * @param options - Fetch configuration options
 * @returns Promise resolving to array of raindrops
 * @throws {ApiError} If API request fails
 */
function fetchRaindrops(token: string, options: FetchOptions): Promise<Raindrop[]> {
  // Implementation
}

// Use comments for "why", not "what"
// ✅ Good
// Retry with exponential backoff to handle rate limiting
const delay = Math.pow(2, retryCount) * 1000;

// ❌ Avoid
// Add delay
const delay = Math.pow(2, retryCount) * 1000;

// imports
import { Obsidian } from "obsidian";
import { RaindropClient } from "./api/raindropClient";

// types/interfaces
interface ProcessorOptions {
  token: string;
  limit: number;
}

// constants
const DEFAULT_LIMIT = 50;

// class/functions
class RaindropProcessor {
  // constructor
  constructor(private client: RaindropClient) {}

  // public methods
  async process(options: ProcessorOptions): Promise<void> {
    // ...
  }

  // private methods
  private async validate(data: unknown): Promise<void> {
    // ...
  }
}

// exports
export { RaindropProcessor };
export type { ProcessorOptions };

// Define custom error types
class ApiError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public originalError?: Error
  ) {
    super(message);
    this.name = "ApiError";
  }
}

// Use try-catch with proper typing
try {
  const result = await fetchRaindrops(token);
  return result;
} catch (error) {
  if (error instanceof ApiError) {
    // Handle API errors
    console.error(`API Error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof Error) {
    // Handle generic errors
    console.error(`Error: ${error.message}`);
  } else {
    // Handle unknown errors
    console.error("Unknown error occurred");
  }
  throw error;
}

// ✅ Good
function processRaindrops(
  raindrops: Raindrop[],
  options: ProcessOptions,
): Promise<ProcessResult> {
  return raindrops
    .filter((r) => shouldInclude(r, options))
    .map((r) => transformRaindrop(r))
    .reduce((acc, r) => merge(acc, r), {});
}

// ❌ Avoid
function processRaindrops(raindrops, options) {
  let result = {}
  for(let i=0; i<raindrops.length; i++){
    if(shouldInclude(raindrops[i],options)){
      result = merge(result, transformRaindrop(raindrops[i]))
    }
  }
  return result
}

// tests/unit/processors/raindropProcessor.test.ts

import { RaindropProcessor } from "../../../src/processors/raindropProcessor";
import { mockRaindropClient } from "../../mocks/raindropClient";

describe("RaindropProcessor", () => {
  let processor: RaindropProcessor;

  beforeEach(() => {
    processor = new RaindropProcessor(mockRaindropClient());
  });

  describe("processRaindrop", () => {
    it("should create a note with correct title", async () => {
      const raindrop = {
        id: 123,
        title: "Test Article",
        link: "https://example.com",
      };

      const result = await processor.processRaindrop(raindrop);

      expect(result.title).toBe("Test Article");
    });

    it("should throw error on invalid input", async () => {
      await expect(processor.processRaindrop(null)).rejects.toThrow();
    });
  });
});

// Use logger utility
import { logger } from "./utils/logger";

logger.info("Processing started", { itemCount: 10 });
logger.error("Failed to fetch", { error });
logger.debug("Details", { data });