Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

Odesli.js Examples

This directory contains comprehensive examples demonstrating how to use the Odesli.js library and its advanced features.

Examples Overview

Basic Usage (basic-usage.js)

Demonstrates fundamental usage patterns for both CommonJS and ESM:

  • Single URL fetching
  • Batch URL fetching with the unified API
  • Basic error handling
  • Country-specific requests
  • Platform detection utilities
node examples/basic-usage.js

Advanced Usage (advanced-usage.js)

Shows advanced features and configurations:

  • Custom client configuration with all options
  • Platform detection and ID extraction
  • Cache management and statistics
  • Unified fetch API for both single and batch operations
  • Error handling and recovery strategies
  • Performance optimization techniques
node examples/advanced-usage.js

Advanced Features (advanced-features-example.js)

Comprehensive demonstration of enterprise-grade features:

  • Rate limiting with all three strategies (token bucket, sliding window, leaky bucket)
  • Comprehensive metrics collection and analysis
  • Plugin system with hooks, middleware, and transformers
  • Error handling with plugins
  • Performance monitoring and optimization
node examples/advanced-features-example.js

Rate Limiter Strategies (rate-limiter-strategies.js)

Detailed comparison and usage of all rate limiting strategies:

  • Token Bucket: Burst handling with configurable capacity
  • Sliding Window: Precise timing with no overages
  • Leaky Bucket: Traffic smoothing with queue management
  • Performance comparisons and timing demonstrations
node examples/rate-limiter-strategies.js

User-Agent Example (user-agent-example.js)

Shows how to work with User-Agent headers and custom configurations:

  • Default User-Agent generation
  • Custom header overrides
  • Platform and version information
  • Browser-like User-Agent strings
node examples/user-agent-example.js

Import Examples

CommonJS (require)

// Main library
const Odesli = require('odesli.js');

// Extensions
const { RateLimiter } = require('odesli.js/rate-limiter');
const { MetricsCollector } = require('odesli.js/metrics');
const { PluginSystem } = require('odesli.js/plugin-system');

ESM (import)

// Main library
import Odesli from 'odesli.js';

// Extensions
import { RateLimiter } from 'odesli.js/rate-limiter';
import { MetricsCollector } from 'odesli.js/metrics';
import { PluginSystem } from 'odesli.js/plugin-system';

Key Features Demonstrated

Unified Fetch API

The fetch() method supports both single URLs and arrays of URLs with comprehensive options:

// Single fetch
const song = await odesli.fetch('https://open.spotify.com/track/123');

// Batch fetch
const songs = await odesli.fetch([
  'https://open.spotify.com/track/123',
  'https://open.spotify.com/track/456',
]);

// Batch fetch with advanced options
const songs = await odesli.fetch(urls, {
  country: 'GB',
  concurrency: 3,
  skipCache: true,
  timeout: 5000,
});

Rate Limiting

Built-in rate limiting with three strategies and auto-queue functionality:

const { RateLimiter } = require('odesli.js/rate-limiter');

// Sliding Window (recommended for API compliance)
const limiter = new RateLimiter({
  maxRequests: 8, // Stay under the 10/minute API limit
  windowMs: 60000, // 1 minute
  strategy: 'sliding-window',
});

// Auto-queue all requests
async function fetchWithRateLimit(url, index) {
  await limiter.waitForSlot();
  return await odesli.fetch(url);
}

// Submit all requests at once - they'll be processed automatically
const promises = urls.map((url, index) => fetchWithRateLimit(url, index));
const results = await Promise.all(promises);

Metrics Collection

Comprehensive metrics tracking with real-time analysis:

const { MetricsCollector } = require('odesli.js/metrics');

const metrics = new MetricsCollector({
  enabled: true,
  retentionMs: 24 * 60 * 60 * 1000, // 24 hours
  maxDataPoints: 10000,
});

// Record request with full context
metrics.recordRequest({
  url: 'https://api.song.link/v1-alpha.1/links',
  method: 'GET',
  startTime: Date.now(),
  endTime: Date.now() + 150,
  success: true,
  statusCode: 200,
  responseTime: 150,
  platform: 'spotify',
  country: 'US',
  cacheHit: false,
});

// Get comprehensive summary
const summary = metrics.getSummary();
console.log(
  'Success Rate:',
  (summary.rates.successRate * 100).toFixed(1) + '%'
);
console.log(
  'Cache Hit Rate:',
  (summary.rates.cacheHitRate * 100).toFixed(1) + '%'
);
console.log('Average Response Time:', summary.recent.avgResponseTime + 'ms');

Plugin System

Extensible functionality through hooks, middleware, and transformers:

const { PluginSystem } = require('odesli.js/plugin-system');

const plugins = new PluginSystem();

// Register a logging plugin
plugins.registerPlugin('logger', {
  hooks: {
    beforeRequest: context => {
      console.log(`🔍 Requesting: ${context.url}`);
    },
    afterRequest: context => {
      console.log(`✅ Completed: ${context.url} (${context.responseTime}ms)`);
    },
    onError: context => {
      console.log(`❌ Error: ${context.error.message}`);
    },
  },
});

// Register middleware for authentication
plugins.registerPlugin('auth', {
  middleware: async (context, next) => {
    context.headers = context.headers || {};
    context.headers['Authorization'] = 'Bearer your-api-key';
    return await next();
  },
});

// Execute hooks and middleware
await plugins.executeHook('beforeRequest', {
  url: 'https://api.song.link/test',
});

Error Handling

Robust error handling for both single and batch operations:

// Single request with error handling
try {
  const song = await odesli.fetch('https://open.spotify.com/track/123');
  console.log(`Success: ${song.title}`);
} catch (error) {
  console.error(`Error: ${error.message}`);
}

// Batch requests with graceful error handling
const results = await odesli.fetch(urls);
results.forEach((result, index) => {
  if (result.error) {
    console.log(`Song ${index + 1}: Error - ${result.error}`);
    console.log(`  Platform: ${result.platform}`);
    console.log(`  Status: ${result.statusCode}`);
    console.log(`  Suggestion: ${result.suggestion}`);
  } else {
    console.log(`Song ${index + 1}: ${result.title}`);
  }
});

Platform Detection and Utilities

Utility methods for working with URLs and platforms:

// Detect platform from URL
const platform = odesli.detectPlatform('https://open.spotify.com/track/123');
console.log('Platform:', platform); // 'spotify'

// Extract ID from URL
const id = odesli.extractId('https://open.spotify.com/track/123');
console.log('ID:', id); // '123'

// Get supported platforms
const platforms = odesli.getSupportedPlatforms();
console.log('Supported platforms:', platforms);

// Get country options for UI dropdowns
const countries = Odesli.getCountryOptions();
console.log('Available countries:', countries.length);

Advanced Features

Rate Limiting Strategies

  1. Token Bucket (Burst Handling):

    const limiter = new RateLimiter({
  maxRequests: 10,
  windowMs: 60000,
  strategy: 'token-bucket',
  burstCapacity: 15, // Allow bursts up to 15 requests
});

  2. Sliding Window (Precise Timing - Recommended):

    const limiter = new RateLimiter({
  maxRequests: 8,
  windowMs: 60000,
  strategy: 'sliding-window',
});

  3. Leaky Bucket (Traffic Smoothing):

    const limiter = new RateLimiter({
  maxRequests: 3,
  windowMs: 5000,
  strategy: 'leaky-bucket',
  queueSize: 10, // Limit queue to 10 pending requests
});

Metrics Analysis

  • Real-time counters: Total requests, success/failure rates, cache hits/misses
  • Performance metrics: Response times, throughput, requests per minute
  • Cache analytics: Hit rates, cache efficiency, cache size
  • Platform analysis: Usage by platform and country
  • Error tracking: Error patterns, frequency, and suggestions
  • Rate limit monitoring: Rate limit hits and average delays

Plugin System Features

  • Hooks: Execute code at specific points (beforeRequest, afterRequest, onError, onRateLimit, etc.)
  • Middleware: Process requests through a chain with context modification
  • Transformers: Modify response data for different formats
  • Built-in plugins: Logging, caching, analytics, response transformation
  • Priority system: Control execution order of hooks
  • Error isolation: Prevent plugin errors from breaking the system

Running Examples

Prerequisites

npm install

Basic Examples

# Basic usage
node examples/basic-usage.js

# Advanced usage
node examples/advanced-usage.js

# User agent examples
node examples/user-agent-example.js

Running Advanced Examples

# Comprehensive advanced features
node examples/advanced-features-example.js

# Rate limiter strategy comparison
node examples/rate-limiter-strategies.js

Environment Variables

Some examples use environment variables for API keys:

# Optional: Set API key for higher rate limits
export ODESLI_API_KEY=your-api-key-here

# Run examples with API key
node examples/advanced-features-example.js

Testing

Run the comprehensive test suite:

npm test
npm test -- --testNamePattern="Advanced Features"

Example Output

Rate Limiter Demo

🚀 Auto-Queue Rate Limiter Demo
📊 Limit: 2 requests per 3s
🔗 Submitting 3 requests...

⏳ Request 1: Waiting for slot...
✅ Request 1: Got slot, fetching...
🎵 Request 1: Bad and Boujee

⏳ Request 2: Waiting for slot...
✅ Request 2: Got slot, fetching...
🎵 Request 2: Rockstar

⏳ Request 3: Waiting for slot...
✅ Request 3: Got slot, fetching...
🎵 Request 3: Congratulations

🎉 All requests completed!
📊 Total songs fetched: 3

Metrics Summary

📊 Metrics Summary:
Counters: {
  totalRequests: 15,
  successfulRequests: 14,
  failedRequests: 1,
  cacheHits: 3,
  cacheMisses: 12,
  rateLimitHits: 2
}
Recent Activity: {
  requests: 15,
  errors: 1,
  avgResponseTime: '245ms',
  requestsPerMinute: 0.25
}
Rates: {
  successRate: '93.3%',
  cacheHitRate: '20.0%',
  errorRate: '6.7%'
}

Notes

  • Examples make actual API calls and may be subject to rate limiting without an API key
  • Rate limiting examples demonstrate how to handle API limits gracefully
  • All examples include comprehensive error handling
  • Examples are designed to be copy-paste ready for production use
  • Performance metrics are real and reflect actual API response times