convex-cms 0.0.1

package/dist/client/queryBuilder.d.ts

@@ -0,0 +1,765 @@
+/**
+ * Fluent Query Builder for Content Entries
+ *
+ * Provides a chainable, type-safe interface for constructing complex
+ * content queries. Supports filtering, sorting, pagination, and search
+ * with TypeScript inference.
+ *
+ * @example
+ * ```typescript
+ * // Simple query with chaining
+ * const posts = await cms.contentEntries
+ *   .query()
+ *   .contentType("blog_post")
+ *   .status("published")
+ *   .limit(10)
+ *   .execute(ctx);
+ *
+ * // Complex query with field filters
+ * const featured = await cms.contentEntries
+ *   .query()
+ *   .contentType("blog_post")
+ *   .where("category", "eq", "technology")
+ *   .where("featured", "eq", true)
+ *   .whereIn("tags", ["javascript", "typescript"])
+ *   .orderBy("_creationTime", "desc")
+ *   .limit(5)
+ *   .execute(ctx);
+ *
+ * // Pagination with cursor
+ * const page1 = await cms.contentEntries
+ *   .query()
+ *   .contentType("blog_post")
+ *   .limit(20)
+ *   .execute(ctx);
+ *
+ * const page2 = await cms.contentEntries
+ *   .query()
+ *   .contentType("blog_post")
+ *   .limit(20)
+ *   .cursor(page1.continueCursor)
+ *   .execute(ctx);
+ * ```
+ */
+import type { ContentEntry, ContentStatus, FilterOperator, PaginationResult, ContentQueryOptions } from "./types.js";
+import type { ConvexContext, TypedComponentApi } from "./wrapper.js";
+/**
+ * Sort direction for query results.
+ */
+export type SortDirection = "asc" | "desc";
+/**
+ * Sortable fields for content entries.
+ * Currently supports creation time; can be extended for custom field sorting.
+ */
+export type SortableField = "_creationTime" | "_id" | string;
+/**
+ * Result from executing a query builder.
+ * Extends PaginationResult with convenience methods.
+ */
+export interface QueryBuilderResult<T> extends PaginationResult<T> {
+    /**
+     * Whether there are more results available.
+     * Alias for !isDone for convenience.
+     */
+    hasMore: boolean;
+}
+/**
+ * Fluent query builder for constructing content entry queries.
+ *
+ * Provides a chainable API for building complex queries with:
+ * - Content type filtering
+ * - Status filtering (single or multiple)
+ * - Field-level filters with various operators
+ * - Full-text search
+ * - Locale filtering
+ * - Cursor-based pagination
+ * - Sort direction
+ *
+ * All methods return `this` for chaining, except terminal methods
+ * (`execute()`, `first()`, `count()`) which execute the query.
+ *
+ * @example
+ * ```typescript
+ * // The query builder is obtained from contentEntries.query()
+ * const builder = cms.contentEntries.query();
+ *
+ * // Chain methods to build the query
+ * const result = await builder
+ *   .contentType("blog_post")
+ *   .status("published")
+ *   .where("author", "eq", "user_123")
+ *   .search("typescript")
+ *   .limit(10)
+ *   .execute(ctx);
+ * ```
+ */
+export declare class ContentQueryBuilder {
+    private state;
+    private readonly api;
+    constructor(api: TypedComponentApi);
+    /**
+     * Filter by content type name.
+     *
+     * @param name - The content type name (e.g., "blog_post")
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const posts = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .execute(ctx);
+     * ```
+     */
+    contentType(name: string): this;
+    /**
+     * Filter by content type ID.
+     *
+     * @param id - The content type ID
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const posts = await cms.contentEntries
+     *   .query()
+     *   .contentTypeById(typeId)
+     *   .execute(ctx);
+     * ```
+     */
+    contentTypeById(id: string): this;
+    /**
+     * Filter by a single status.
+     *
+     * @param status - The status to filter by
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const published = await cms.contentEntries
+     *   .query()
+     *   .status("published")
+     *   .execute(ctx);
+     * ```
+     */
+    status(status: ContentStatus): this;
+    /**
+     * Filter by multiple statuses (OR logic).
+     *
+     * Useful for admin views that need to show content in various states.
+     *
+     * @param statuses - Array of statuses to include
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Show all non-archived content in admin
+     * const editorial = await cms.contentEntries
+     *   .query()
+     *   .statusIn(["draft", "published", "scheduled"])
+     *   .execute(ctx);
+     * ```
+     */
+    statusIn(statuses: ContentStatus[]): this;
+    /**
+     * Shorthand for status("published").
+     *
+     * @returns this for chaining
+     */
+    published(): this;
+    /**
+     * Shorthand for status("draft").
+     *
+     * @returns this for chaining
+     */
+    drafts(): this;
+    /**
+     * Shorthand for status("archived").
+     *
+     * @returns this for chaining
+     */
+    archived(): this;
+    /**
+     * Shorthand for status("scheduled").
+     *
+     * @returns this for chaining
+     */
+    scheduled(): this;
+    /**
+     * Filter by locale.
+     *
+     * @param locale - The locale code (e.g., "en-US", "es-ES")
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const spanishPosts = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .locale("es-ES")
+     *   .execute(ctx);
+     * ```
+     */
+    locale(locale: string): this;
+    /**
+     * Include soft-deleted entries in results.
+     *
+     * By default, soft-deleted entries are excluded.
+     *
+     * @param include - Whether to include deleted entries (default: true)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Show all entries including deleted ones
+     * const all = await cms.contentEntries
+     *   .query()
+     *   .includeDeleted()
+     *   .execute(ctx);
+     *
+     * // Explicitly exclude deleted (same as default)
+     * const active = await cms.contentEntries
+     *   .query()
+     *   .includeDeleted(false)
+     *   .execute(ctx);
+     * ```
+     */
+    includeDeleted(include?: boolean): this;
+    /**
+     * Only return soft-deleted entries.
+     *
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const trash = await cms.contentEntries
+     *   .query()
+     *   .onlyDeleted()
+     *   .execute(ctx);
+     * ```
+     */
+    onlyDeleted(): this;
+    /**
+     * Search content using full-text search.
+     *
+     * Searches indexed fields in the content entry data.
+     * Requires the searchIndexing feature to be enabled.
+     *
+     * @param query - The search query string
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const results = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .search("typescript tutorial")
+     *   .execute(ctx);
+     * ```
+     */
+    search(query: string): this;
+    /**
+     * Add a field filter condition.
+     *
+     * Multiple filters are combined with AND logic.
+     *
+     * @param field - The field name in the content data
+     * @param operator - The comparison operator
+     * @param value - The value to compare against
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const techPosts = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .where("category", "eq", "technology")
+     *   .where("views", "gte", 100)
+     *   .execute(ctx);
+     * ```
+     */
+    where(field: string, operator: FilterOperator, value: unknown): this;
+    /**
+     * Filter where field equals value.
+     * Shorthand for where(field, "eq", value).
+     *
+     * @param field - The field name
+     * @param value - The value to match
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const featured = await cms.contentEntries
+     *   .query()
+     *   .whereEquals("featured", true)
+     *   .execute(ctx);
+     * ```
+     */
+    whereEquals(field: string, value: unknown): this;
+    /**
+     * Filter where field does not equal value.
+     * Shorthand for where(field, "ne", value).
+     *
+     * @param field - The field name
+     * @param value - The value to exclude
+     * @returns this for chaining
+     */
+    whereNotEquals(field: string, value: unknown): this;
+    /**
+     * Filter where field is greater than value.
+     * Shorthand for where(field, "gt", value).
+     *
+     * @param field - The field name
+     * @param value - The minimum value (exclusive)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const expensive = await cms.contentEntries
+     *   .query()
+     *   .contentType("product")
+     *   .whereGreaterThan("price", 100)
+     *   .execute(ctx);
+     * ```
+     */
+    whereGreaterThan(field: string, value: number | Date): this;
+    /**
+     * Filter where field is greater than or equal to value.
+     * Shorthand for where(field, "gte", value).
+     *
+     * @param field - The field name
+     * @param value - The minimum value (inclusive)
+     * @returns this for chaining
+     */
+    whereGreaterThanOrEquals(field: string, value: number | Date): this;
+    /**
+     * Filter where field is less than value.
+     * Shorthand for where(field, "lt", value).
+     *
+     * @param field - The field name
+     * @param value - The maximum value (exclusive)
+     * @returns this for chaining
+     */
+    whereLessThan(field: string, value: number | Date): this;
+    /**
+     * Filter where field is less than or equal to value.
+     * Shorthand for where(field, "lte", value).
+     *
+     * @param field - The field name
+     * @param value - The maximum value (inclusive)
+     * @returns this for chaining
+     */
+    whereLessThanOrEquals(field: string, value: number | Date): this;
+    /**
+     * Filter where field is in a range (inclusive).
+     *
+     * @param field - The field name
+     * @param min - The minimum value (inclusive)
+     * @param max - The maximum value (inclusive)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const midRange = await cms.contentEntries
+     *   .query()
+     *   .contentType("product")
+     *   .whereBetween("price", 50, 150)
+     *   .execute(ctx);
+     * ```
+     */
+    whereBetween(field: string, min: number | Date, max: number | Date): this;
+    /**
+     * Filter where field value is in an array of allowed values.
+     * Shorthand for where(field, "in", values).
+     *
+     * @param field - The field name
+     * @param values - Array of allowed values
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const categoryPosts = await cms.contentEntries
+     *   .query()
+     *   .whereIn("category", ["tech", "science", "design"])
+     *   .execute(ctx);
+     * ```
+     */
+    whereIn(field: string, values: unknown[]): this;
+    /**
+     * Filter where field value is NOT in an array of values.
+     * Shorthand for where(field, "notIn", values).
+     *
+     * @param field - The field name
+     * @param values - Array of excluded values
+     * @returns this for chaining
+     */
+    whereNotIn(field: string, values: unknown[]): this;
+    /**
+     * Filter where string field contains a substring.
+     * For array fields, checks if the array contains the value.
+     * Shorthand for where(field, "contains", value).
+     *
+     * @param field - The field name
+     * @param value - The substring or array value to find
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // String contains
+     * const results = await cms.contentEntries
+     *   .query()
+     *   .whereContains("title", "guide")
+     *   .execute(ctx);
+     *
+     * // Array contains
+     * const tagged = await cms.contentEntries
+     *   .query()
+     *   .whereContains("tags", "featured")
+     *   .execute(ctx);
+     * ```
+     */
+    whereContains(field: string, value: unknown): this;
+    /**
+     * Filter where string field starts with a prefix.
+     * Shorthand for where(field, "startsWith", prefix).
+     *
+     * @param field - The field name
+     * @param prefix - The prefix to match
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const year2026 = await cms.contentEntries
+     *   .query()
+     *   .whereStartsWith("slug", "2026-")
+     *   .execute(ctx);
+     * ```
+     */
+    whereStartsWith(field: string, prefix: string): this;
+    /**
+     * Filter where string field ends with a suffix.
+     * Shorthand for where(field, "endsWith", suffix).
+     *
+     * @param field - The field name
+     * @param suffix - The suffix to match
+     * @returns this for chaining
+     */
+    whereEndsWith(field: string, suffix: string): this;
+    /**
+     * Set the sort order for results.
+     *
+     * Supports sorting by:
+     * - System fields: "_creationTime", "_id", "firstPublishedAt", "lastPublishedAt", "scheduledPublishAt", "version"
+     * - Custom data fields: Use "data.fieldName" format (e.g., "data.price", "data.sortOrder")
+     *
+     * Results are sorted in descending order by default.
+     *
+     * @param field - The field to sort by (system field or "data.fieldName" for custom fields)
+     * @param direction - Sort direction ("asc" or "desc")
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Newest first (default)
+     * const newest = await cms.contentEntries
+     *   .query()
+     *   .orderBy("_creationTime", "desc")
+     *   .execute(ctx);
+     *
+     * // Oldest first
+     * const oldest = await cms.contentEntries
+     *   .query()
+     *   .orderBy("_creationTime", "asc")
+     *   .execute(ctx);
+     *
+     * // Sort by publish date
+     * const byPublishDate = await cms.contentEntries
+     *   .query()
+     *   .orderBy("firstPublishedAt", "desc")
+     *   .execute(ctx);
+     *
+     * // Sort by custom field (price, low to high)
+     * const byPrice = await cms.contentEntries
+     *   .query()
+     *   .contentType("product")
+     *   .orderBy("data.price", "asc")
+     *   .execute(ctx);
+     *
+     * // Sort by custom order field
+     * const byOrder = await cms.contentEntries
+     *   .query()
+     *   .contentType("menu_item")
+     *   .orderBy("data.sortOrder", "asc")
+     *   .execute(ctx);
+     * ```
+     */
+    orderBy(field: SortableField, direction?: SortDirection): this;
+    /**
+     * Sort by first publish date (newest published first).
+     * Useful for showing recently published content.
+     *
+     * @param direction - Sort direction ("asc" or "desc", default "desc")
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const recentlyPublished = await cms.contentEntries
+     *   .query()
+     *   .status("published")
+     *   .byPublishDate()
+     *   .execute(ctx);
+     * ```
+     */
+    byPublishDate(direction?: SortDirection): this;
+    /**
+     * Sort by last publish date (most recently updated first).
+     * Useful for showing recently updated content.
+     *
+     * @param direction - Sort direction ("asc" or "desc", default "desc")
+     * @returns this for chaining
+     */
+    byLastPublishDate(direction?: SortDirection): this;
+    /**
+     * Sort by a custom data field.
+     * Convenience method that automatically prefixes field name with "data.".
+     *
+     * @param fieldName - The field name in the content entry's data object
+     * @param direction - Sort direction ("asc" or "desc", default "desc")
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Sort by price (low to high)
+     * const cheapest = await cms.contentEntries
+     *   .query()
+     *   .contentType("product")
+     *   .orderByField("price", "asc")
+     *   .execute(ctx);
+     *
+     * // Sort by title alphabetically
+     * const alphabetical = await cms.contentEntries
+     *   .query()
+     *   .orderByField("title", "asc")
+     *   .execute(ctx);
+     * ```
+     */
+    orderByField(fieldName: string, direction?: SortDirection): this;
+    /**
+     * Sort by newest first (descending creation time).
+     * Shorthand for orderBy("_creationTime", "desc").
+     *
+     * @returns this for chaining
+     */
+    newestFirst(): this;
+    /**
+     * Sort by oldest first (ascending creation time).
+     * Shorthand for orderBy("_creationTime", "asc").
+     *
+     * @returns this for chaining
+     */
+    oldestFirst(): this;
+    /**
+     * Set the maximum number of results to return.
+     *
+     * @param count - Number of items per page (1-250)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const firstTen = await cms.contentEntries
+     *   .query()
+     *   .limit(10)
+     *   .execute(ctx);
+     * ```
+     */
+    limit(count: number): this;
+    /**
+     * Set the pagination cursor for fetching the next page.
+     *
+     * Use the `continueCursor` from the previous query result.
+     *
+     * @param cursor - The cursor from the previous page
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * const page1 = await cms.contentEntries
+     *   .query()
+     *   .limit(20)
+     *   .execute(ctx);
+     *
+     * if (!page1.isDone) {
+     *   const page2 = await cms.contentEntries
+     *     .query()
+     *     .limit(20)
+     *     .cursor(page1.continueCursor)
+     *     .execute(ctx);
+     * }
+     * ```
+     */
+    cursor(cursor: string | null | undefined): this;
+    /**
+     * Alias for cursor() for more natural chaining.
+     *
+     * @param cursor - The cursor from the previous page
+     * @returns this for chaining
+     */
+    after(cursor: string | null | undefined): this;
+    /**
+     * Build the query options object from the current state.
+     *
+     * This is primarily for internal use, but can be useful for debugging
+     * or when you need to pass options to the underlying API directly.
+     *
+     * @returns The compiled ContentQueryOptions
+     *
+     * @example
+     * ```typescript
+     * const options = cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .status("published")
+     *   .orderBy("data.price", "asc")
+     *   .toOptions();
+     *
+     * console.log(options);
+     * // {
+     * //   contentTypeName: "blog_post",
+     * //   status: "published",
+     * //   sortField: "data.price",
+     * //   sortDirection: "asc",
+     * //   fieldFilters: [],
+     * //   paginationOpts: { numItems: 50 }
+     * // }
+     * ```
+     */
+    toOptions(): ContentQueryOptions;
+    /**
+     * Execute the query and return paginated results.
+     *
+     * This is the primary terminal method that runs the built query.
+     *
+     * @param ctx - Convex query context
+     * @returns Promise resolving to paginated results
+     *
+     * @example
+     * ```typescript
+     * const result = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .status("published")
+     *   .limit(10)
+     *   .execute(ctx);
+     *
+     * console.log(result.page);        // Array of entries
+     * console.log(result.isDone);      // true if no more results
+     * console.log(result.continueCursor); // Cursor for next page
+     * console.log(result.hasMore);     // Convenience: !isDone
+     * ```
+     */
+    execute(ctx: ConvexContext): Promise<QueryBuilderResult<ContentEntry>>;
+    /**
+     * Execute the query and return only the first result.
+     *
+     * Convenience method that sets limit(1) and returns the first item or null.
+     *
+     * @param ctx - Convex query context
+     * @returns Promise resolving to the first entry or null
+     *
+     * @example
+     * ```typescript
+     * const latest = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .status("published")
+     *   .newestFirst()
+     *   .first(ctx);
+     *
+     * if (latest) {
+     *   console.log(latest.data.title);
+     * }
+     * ```
+     */
+    first(ctx: ConvexContext): Promise<ContentEntry | null>;
+    /**
+     * Execute the query and check if any results exist.
+     *
+     * Convenience method that sets limit(1) and returns boolean.
+     *
+     * @param ctx - Convex query context
+     * @returns Promise resolving to true if results exist
+     *
+     * @example
+     * ```typescript
+     * const hasPublished = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .status("published")
+     *   .exists(ctx);
+     *
+     * if (!hasPublished) {
+     *   console.log("No published posts yet");
+     * }
+     * ```
+     */
+    exists(ctx: ConvexContext): Promise<boolean>;
+    /**
+     * Execute the query and collect all results into a single array.
+     *
+     * WARNING: This fetches ALL matching results, potentially making
+     * multiple paginated requests. Use with caution on large datasets.
+     *
+     * @param ctx - Convex query context
+     * @param maxPages - Maximum number of pages to fetch (default: 10)
+     * @returns Promise resolving to array of all entries
+     *
+     * @example
+     * ```typescript
+     * // Get all published posts (use with caution!)
+     * const allPosts = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .status("published")
+     *   .all(ctx);
+     * ```
+     */
+    all(ctx: ConvexContext, maxPages?: number): Promise<ContentEntry[]>;
+    /**
+     * Create a copy of this query builder with the current state.
+     *
+     * Useful for creating variations of a base query.
+     *
+     * @returns A new QueryBuilder with the same state
+     *
+     * @example
+     * ```typescript
+     * const baseQuery = cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post");
+     *
+     * const published = await baseQuery.clone()
+     *   .status("published")
+     *   .execute(ctx);
+     *
+     * const drafts = await baseQuery.clone()
+     *   .status("draft")
+     *   .execute(ctx);
+     * ```
+     */
+    clone(): ContentQueryBuilder;
+    /**
+     * Reset the query builder to its initial state.
+     *
+     * @returns this for chaining
+     */
+    reset(): this;
+}
+/**
+ * Create a new content query builder.
+ *
+ * This is typically called internally by ContentEntriesApi.query().
+ *
+ * @param api - The typed component API
+ * @returns A new ContentQueryBuilder instance
+ */
+export declare function createQueryBuilder(api: TypedComponentApi): ContentQueryBuilder;
+//# sourceMappingURL=queryBuilder.d.ts.map