Fetch many entities

Fetch a paginated, filtered, and sorted list of entities

Overview

useFetchManyEntities returns a function that fetches a paginated list of entities with full filtering and sorting support. This is the low-level hook underlying EntityListProvider. For continuous-scroll or load-more list UIs, use useEntityList instead, which wraps this hook with built-in pagination state.

Usage Example

import { useFetchManyEntities } from "@sublay/react-js";
import { useEffect, useState } from "react";

function EntityFeed() {
  const fetchEntities = useFetchManyEntities();
  const [entities, setEntities] = useState([]);

  useEffect(() => {
    fetchEntities({
      page: 1,
      limit: 20,
      sortBy: "score",
      spaceId: "space_abc",
      include: ["user"],
    }).then((res) => setEntities(res.data));
  }, []);

  return (
    <ul>
      {entities.map((e) => (
        <li key={e.id}>{e.title}</li>
      ))}
    </ul>
  );
}

Parameters

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to server default.

sortBy · string

Field to sort by. Options: "createdAt", "top", "hot", "controversial", or "metadata.<property>" to sort by a metadata field.

sortByReaction · string

Sort by a specific reaction type count. Use with sortBy: "reaction".

sortDir · string

Sort direction: "asc" or "desc".

sortType · string

Sort algorithm type. Options: "auto", "numeric", "text", "boolean", "timestamp". Used when sorting by a metadata field.

timeFrame · string

Filter entities to a time window. Options: "day", "week", "month", "year".

sourceId · string

Filter to entities associated with a specific source ID.

spaceId · string

Filter to entities in a specific space.

userId · string

Filter to entities created by a specific user.

followedOnly · boolean

If true, return only entities from users the authenticated user follows.

keywordsFilters · object

Filter by keywords. See Entity List Filters for the full filter schema.

titleFilters · object

Filter by title content. See Entity List Filters.

contentFilters · object

Filter by body content. See Entity List Filters.

attachmentsFilters · object

Filter by attachments data. See Entity List Filters.

locationFilters · object

Filter by geographic proximity. See Entity List Filters.

metadataFilters · object

Filter by metadata fields. See Entity List Filters.

include · string | string[]

Populate related fields. Accepted values: "user", "space", "topComment", "saved", "files".

spaceReputationId · string

Resolves each row’s embedded author reputation into a spaceReputation number. Accepts a space <uuid>, "none" (project-general bucket), or "context" (server-derived per row from the request context). Empty string, "general", and null are rejected. See Reputation.

spaceReputationDescendants · boolean

When true, spaceReputation is the subtree sum (the space plus all its descendants). Only honored when spaceReputationId is an explicit <uuid>.

Returns

data · Entity[]

Array of entities for the current page. When spaceReputationId is set, each embedded author carries an added spaceReputation number. See Reputation.

pagination.page · number

Current page number.

pagination.pageSize · number

Number of results per page.

pagination.totalPages · number

Total number of pages matching the filters.

pagination.totalItems · number

Total count of entities matching the filters (across all pages).

pagination.hasMore · boolean

true if there are additional pages available.