/**
 * Calculates the total price including tax and discounts.
 *
 * @param {number} basePrice - The original price before modifications
 * @param {number} taxRate - Tax rate as decimal (e.g., 0.21 for 21%)
 * @param {number} [discount=0] - Optional discount as decimal
 * @returns {number} The final calculated price
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * // Calculate price with 21% tax and 10% discount
 * const total = calculateTotalPrice(100, 0.21, 0.10);
 * // Returns: 108.90
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error('Price and tax rate must be non-negative');
  }
  const discountedPrice = basePrice * (1 - discount);
  return discountedPrice * (1 + taxRate);
}

/**
 * User service for managing user operations.
 */
export class UserService {
  /**
   * Creates a new user in the system.
   *
   * @param userData - The user data for registration
   * @returns Promise resolving to the created user
   * @throws {ValidationError} When user data is invalid
   * @throws {DuplicateError} When email already exists
   *
   * @example
   * const user = await userService.createUser({
   *   email: 'user@example.com',
   *   name: 'John Doe'
   * });
   */
  async createUser(userData: CreateUserDTO): Promise<User> {
    // Implementation
  }

  /**
   * Retrieves a user by their unique identifier.
   *
   * @param id - The user's UUID
   * @returns The user if found, null otherwise
   */
  async getUserById(id: string): Promise<User | null> {
    // Implementation
  }
}

def process_transaction(
    amount: float,
    currency: str,
    metadata: dict | None = None
) -> TransactionResult:
    """Process a financial transaction with validation and logging.

    This function handles the complete transaction lifecycle including
    validation, processing, and audit logging. It supports multiple
    currencies and optional metadata attachment.

    Args:
        amount: The transaction amount in the specified currency.
            Must be positive and not exceed the daily limit.
        currency: ISO 4217 currency code (e.g., 'USD', 'EUR').
        metadata: Optional dictionary with additional transaction
            details. Keys 'reference' and 'notes' are recommended.

    Returns:
        TransactionResult containing:
            - transaction_id: Unique identifier for the transaction
            - status: 'completed', 'pending', or 'failed'
            - timestamp: UTC datetime of processing
            - fee: Applied transaction fee

    Raises:
        ValidationError: If amount is negative or exceeds limits.
        CurrencyNotSupportedError: If currency code is invalid.
        InsufficientFundsError: If account balance is too low.

    Example:
        >>> result = process_transaction(
        ...     amount=100.50,
        ...     currency='USD',
        ...     metadata={'reference': 'INV-001'}
        ... )
        >>> print(result.transaction_id)
        'txn_abc123xyz'

    Note:
        Transactions over $10,000 require additional verification
        and may be held for compliance review.
    """
    pass

def calculate_statistics(
    data: np.ndarray,
    weights: np.ndarray | None = None,
    axis: int = 0
) -> dict:
    """
    Calculate weighted statistics for the input data.

    Parameters
    ----------
    data : np.ndarray
        Input data array of shape (n_samples, n_features).
    weights : np.ndarray, optional
        Weight array of shape (n_samples,). If None, uniform
        weights are used.
    axis : int, default=0
        Axis along which to compute statistics.

    Returns
    -------
    dict
        Dictionary containing:
        - 'mean' : np.ndarray
            Weighted mean values.
        - 'std' : np.ndarray
            Weighted standard deviation.
        - 'median' : np.ndarray
            Weighted median values.

    Raises
    ------
    ValueError
        If data and weights have incompatible shapes.
    TypeError
        If data is not a numpy array.

    See Also
    --------
    numpy.average : Compute weighted average.
    scipy.stats.describe : Compute descriptive statistics.

    Examples
    --------
    >>> data = np.array([[1, 2], [3, 4], [5, 6]])
    >>> stats = calculate_statistics(data)
    >>> stats['mean']
    array([3., 4.])
    """
    pass

undefined

undefined

undefined

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member"
}

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member",
  "createdAt": "2024-01-15T10:30:00Z"
}

undefined

undefined

npm install project-name

import { Client } from 'project-name';

const client = new Client({ apiKey: 'your-key' });
const result = await client.doSomething();

undefined

undefined

undefined

// GOOD: Explain WHY, not WHAT
// Skip validation for internal requests to improve performance
// External requests are validated at the API gateway
if (request.isInternal) {
  return processDirectly(data);
}

// BAD: States the obvious
// Check if user is null
if (user === null) {
  return null;
}

// GOOD: Document complex logic
// Using binary search for O(log n) lookup in sorted array
// Linear search would be O(n) for 10k+ items
const index = binarySearch(sortedItems, targetId);

// GOOD: Explain business rules
// Orders over $1000 require manager approval per policy DOC-123
// This threshold was set by finance team in Q3 2023
if (order.total > 1000 && !order.hasManagerApproval) {
  throw new ApprovalRequiredError();
}

{
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs",
    "plugin": ["typedoc-plugin-markdown"],
    "readme": "README.md",
    "excludePrivate": true,
    "excludeInternal": true
  }
}

undefined

undefined