Skip to main content

​
fetchEntities API Reference

The fetchEntities function is the primary method for loading and filtering entity lists. It accepts filters, configuration, and options to control how entities are fetched and displayed.

​
Syntax

entityList.fetchEntities(filters, config?, options?)

​
Parameters

​
Filters (Required)

User-controlled parameters that determine which entities to fetch: 
interface EntityListFilters {
  sortBy: EntityListSortByOptions; // Required
  timeFrame?: TimeFrame | null;
  userId?: string | null;
  followedOnly?: boolean;
  keywordsFilters?: KeywordsFilters | null;
  titleFilters?: TitleFilters | null;
  contentFilters?: ContentFilters | null;
  attachmentsFilters?: AttachmentsFilters | null;
  locationFilters?: LocationFilters | null;
  metadataFilters?: MetadataFilters | null;
}

​
sortBy (Required)

  • "hot" - Replyke’s hotness algorithm (default)
  • "new" - Newest first
  • "top" - Highest voted
  • "controversial" - Mixed voting scores

​
timeFrame (Optional)

  • "hour" - Last hour
  • "day" - Last 24 hours
  • "week" - Last 7 days
  • "month" - Last 30 days
  • "year" - Last 12 months
  • null - No time restriction (default)

​
Configuration (Optional)

System-level parameters that control fetch behavior: 
interface EntityListConfig {
  sourceId?: string | null;
  limit?: number;
}
  • sourceId: Logical separation of entities by context (default: null)
  • limit: Entities per page (default: 10)

​
Options (Optional)

Controls how the fetch operation behaves: 
interface EntityListFetchOptions {
  immediate?: boolean;
  clearImmediately?: boolean;
  resetUnspecified?: boolean;
}
  • immediate: Skip debouncing, execute immediately (default: false)
  • clearImmediately: Clear current entities before fetching (default: false)
  • resetUnspecified: Reset unspecified filters to defaults (default: false)

​
Examples

​
Basic Usage

// Minimal fetch
entityList.fetchEntities({ sortBy: "hot" });

// With configuration
entityList.fetchEntities(
  { sortBy: "new" },
  { sourceId: "blog-posts", limit: 20 }
);

​
Common Patterns

​
User Profile Feed

entityList.fetchEntities(
  { sortBy: "new", userId: "user123" },
  { limit: 15 },
  { resetUnspecified: true }
);

​
Search Results

entityList.fetchEntities(
  {
    sortBy: "new",
    titleFilters: { includes: [searchQuery] },
    timeFrame: "week"
  },
  { limit: 30 },
  { immediate: true, clearImmediately: true }
);

​
Trending Content

entityList.fetchEntities({
  sortBy: "hot",
  timeFrame: "day",
  followedOnly: false
});

​
Location-Based Feed

entityList.fetchEntities({
  sortBy: "new",
  locationFilters: {
    latitude: 40.7128,
    longitude: -74.0060,
    radius: 10
  }
});

​
Advanced Filtering

​
Multiple Content Filters

entityList.fetchEntities({
  sortBy: "hot",
  titleFilters: { includes: ["React", "Vue"] },
  contentFilters: { doesNotInclude: ["deprecated"] },
  keywordsFilters: {
    includes: ["javascript"],
    doesNotInclude: ["beginner"]
  },
  attachmentsFilters: { hasAttachments: true }
});

​
Metadata Filtering

entityList.fetchEntities({
  sortBy: "new",
  metadataFilters: {
    includes: { category: "tech", difficulty: "advanced" },
    exists: ["author", "publishDate"],
    doesNotInclude: { status: "draft" }
  }
});

​
Debouncing Behavior

By default, fetchEntities debounces rapid calls with an 800ms delay to prevent excessive API requests: 
// These calls will be debounced
entityList.fetchEntities({ sortBy: "hot", userId: "user1" });
entityList.fetchEntities({ sortBy: "hot", userId: "user2" }); // Only this will execute

// Bypass debouncing for immediate execution
entityList.fetchEntities(
  { sortBy: "hot", userId: "user3" },
  undefined,
  { immediate: true }
);

​
State Management

After calling fetchEntities, the entity list state updates automatically: 
// Before fetch
console.log(entityList.loading); // false
console.log(entityList.entities); // []

// Call fetch
entityList.fetchEntities({ sortBy: "hot" });

// During fetch
console.log(entityList.loading); // true

// After fetch completes
console.log(entityList.loading); // false
console.log(entityList.entities); // [entity1, entity2, ...]
console.log(entityList.hasMore); // true/false

​
Error Handling

The function handles errors internally and updates the entity list state: 
// Errors are logged and state is updated
// No need for try/catch in your component
entityList.fetchEntities({ sortBy: "hot" });

// Check for errors in your UI
if (!entityList.loading && entityList.entities.length === 0) {
  // Handle empty state (could be error or no results)
}

​
Performance Tips

  1. Use debouncing - Let the default 800ms debouncing handle rapid filter changes
  2. Specify immediate - Use immediate: true only when necessary (search, user actions)
  3. Clear wisely - Use clearImmediately: true for search results, avoid for filter updates
  4. Reasonable limits - Balance between UX and API costs with appropriate limit values
  5. Reset sparingly - Use resetUnspecified: true only when you want to clear all other filters
⌘I