Class RequestBuilder<TBuilder, TEntity>

Namespace

CivitaiSharp.Core.Request

Assembly

CivitaiSharp.Core.dll

Immutable base record for API request builders. Encapsulates common paging, sorting, and filter logic to support a consistent fluent API across all resource types. Instances are thread-safe and can be cached and reused; each fluent method returns a new builder instance with the updated state.

public abstract record RequestBuilder<TBuilder, TEntity> : IEquatable<RequestBuilder<TBuilder, TEntity>> where TBuilder : RequestBuilder<TBuilder, TEntity>

Type Parameters

TBuilder

The derived builder type (for fluent chaining).

TEntity

The entity type returned by requests.

Inheritance

object

RequestBuilder<TBuilder, TEntity>

Implements

IEquatable<RequestBuilder<TBuilder, TEntity>>

Derived

CreatorBuilder

ImageBuilder

ModelBuilder

TagBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

DefaultResultsLimit

Gets the default results limit when none is specified for this endpoint.

protected abstract int DefaultResultsLimit { get; }

Property Value

int

Endpoint

Gets the API endpoint path segment for this resource type (e.g., "models", "images").

protected abstract string Endpoint { get; }

Property Value

string

Filters

Gets the immutable dictionary of request filter parameters with typed values.

protected ImmutableDictionary<string, object?> Filters { get; }

Property Value

ImmutableDictionary<string, object>

MaxResultsLimit

Gets the maximum allowed value for results limit for this endpoint.

protected abstract int MaxResultsLimit { get; }

Property Value

int

MinResultsLimit

Gets the minimum allowed value for results limit for this endpoint.

protected abstract int MinResultsLimit { get; }

Property Value

int

ResultsLimit

Gets the number of results to return per page.

protected int? ResultsLimit { get; }

Property Value

int?

Sort

Gets the sort option value.

protected string? Sort { get; }

Property Value

string

SupportsSorting

Gets a value indicating whether this endpoint supports sorting. Override to return true in derived classes that support sorting.

protected virtual bool SupportsSorting { get; }

Property Value

bool

Methods

ExecuteAsync(int?, string?, CancellationToken)

Executes the request and returns paged results with pagination metadata.

public Task<Result<PagedResult<TEntity>>> ExecuteAsync(int? resultsLimit = null, string? cursor = null, CancellationToken cancellationToken = default)

Parameters

resultsLimit int?

Optional number of results per page. Must be between MinResultsLimit and MaxResultsLimit. Omit to use the API default.

cursor string

Optional cursor for cursor-based pagination.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<PagedResult<TEntity>>>

A task that represents the asynchronous operation. The result contains either the paged items or an error.

Exceptions

ArgumentOutOfRangeException

Thrown if resultsLimit is specified and is less than MinResultsLimit or greater than MaxResultsLimit.

FirstOrDefaultAsync(CancellationToken)

Executes the request and returns only the first result, or null if no results are found. This is a convenience method that internally limits the request to 1 result for efficiency.

public Task<Result<TEntity?>> FirstOrDefaultAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<TEntity>>

A task that represents the asynchronous operation. The result contains either:

• The first entity if results exist
• Null if no results match the query
• An error if the request failed

With(ImmutableDictionary<string, object?>, string?, int?)

Creates a new builder instance with the specified state changes. Derived classes must implement this to return the correct derived type.

protected abstract TBuilder With(ImmutableDictionary<string, object?> filters, string? sort, int? resultsLimit)

Parameters

filters ImmutableDictionary<string, object>

The new filters dictionary with typed values.

sort string

The new sort value.

resultsLimit int?

The new results limit.

Returns

TBuilder

A new builder instance with the updated state.

WithFilter(string, object?)

Adds or updates a filter parameter with a typed value. The value type is preserved (booleans stay bool, arrays stay arrays, etc.) for consistent query string formatting.

protected TBuilder WithFilter(string key, object? value)

Parameters

key string

The filter key.

value object

The filter value. Can be a primitive, enum, or array. Null values are ignored during query string building.

Returns

TBuilder

A new builder instance with the updated filter.

WithSort(string?)

Sets the sort option.

protected TBuilder WithSort(string? sort)

Parameters

sort string

The sort option value.

Returns

TBuilder

A new builder instance with the updated sort.